KBEC-00254 - CloudBees CD (CloudBees Flow) Gateways and Zones

Article ID:360032828972
2 minute readKnowledge base


CloudBees CD (CloudBees Flow) provides the capability of establishing security zones for agents and repository servers.

What is a zone?

A zone consists of a collection of resources that can directly communicate with each other. Within a large corporation, a zone may encapsulate a physical site, and communication between the two sites occurs through firewalls.

Cross-zone communication

The following figure shows an example gateway and zone configuration with two zones and three machines.

*"Commander Server" at this diagram means Flow service daemon.

Cross-zone communication is managed by proxying requests through specially marked resources called gateway resources. In the previous example, if the CloudBees CD (CloudBees Flow) server wants to run a command block process step on an agent in Zone B, it issues its request through GatewayAgent1. The request includes extra metadata that instructs GatewayAgent1 to forward the request to the target agent. The firewall is configured to allow connections from GatewayAgent1 to GatewayAgent2. It is also configured to allow connections from GatewayAgent2 to GatewayAgent1. This is necessary because API communication (CLI commands as well as the step completion message) is sent from GatewayAgent2 on its own outbound connection to the server (through GatewayAgent1).

Because the firewall separates two private networks, there’s no guarantee that IP address ranges in one network do not overlap with those of the other. When either gateway agent wants to connect to the other, the gateway agent uses an IP address to the firewall that is valid for its side of the firewall.

What is a gateway?

The details of this connection information are recorded in a gateway object in CloudBees CD (CloudBees Flow). Using the previous example as a reference, a gateway object consists of the following information:

  • Name of a gateway resource in one zone (GatewayAgent1)

  • Name of a gateway resource in another zone (GatewayAgent2)

  • Host/port GatewayAgent2 uses to communicate with GatewayAgent1 (e.g. the firewall IP address in ZoneB)

  • Host/port GatewayAgent1 uses to communicate with GatewayAgent2 (e.g. the firewall IP address in ZoneA)

Support for gateways

The previous example shows two zones for simplicity, but CloudBees CD (CloudBees Flow) supports an unlimited number of zones, including chained zones. For example, if a third zone called Zone C is only accessible from Zone B via GatewayAgent3 (in Zone B) and GatewayAgent4 (in Zone C), the server could issue a request to GatewayAgent1, which forwards the request to GatewayAgent2, which forwards it to GatewayAgent3, which forwards it to GatewayAgent4.

Also, for resiliency, CloudBees CD (CloudBees Flow) supports having multiple gateway agents between two zones. If one gateway agent goes down, the system will detect the failure and route all requests through the other gateway agent.


  • Agents need not be trusted when using a gateway, but is recommended

  • Local agent on the server also needs to trusted when using trusted gateway agents to resolve log file requests.

How to see if the communication really runs through the gateway.

  • net state --o 1  monitor.txt will show you which agent port 7800 is used. (Port number can be changed by different configuration.)


An example going over the process of setting up a basic environment with two zones and a gateway can be found in this KB article.

Applies to

  • Product versions: 4.2

  • OS versions: All