Zones and gateways

6 minute readReferenceScalability

The CloudBees CD/RO server is a member of the default zone, created during CloudBees CD/RO installation. To ensure that the CloudBees CD/RO server can reach remote zones, you must establish a gateway or a gateway chain to reach each one either directly or indirectly. Also, to preserve this reachability, do not rename the default zone.

All gateway agents that meet these criteria must be updated to CloudBees CD/RO v10.2+:

  • Your enterprise implements a multi-zone environment.

  • Agent versions are a combination of pre-v10.2 and v10.2+.

  • The access route to a v10.2+ agent is configured through a pre-v10.2 gateway agent.

Gateway objects

To communicate with a resource, workspace, or artifact repository server in another zone, a gateway must be created. A gateway object contains two resource (or "agent") machines. For example, GatewayResource1 and GatewayResource2, each configured to communicate with the other. One gateway resource resides in the source zone and the other in the target zone. A gateway is bidirectional and informs the CloudBees CD/RO server that each gateway machine is configured to communicate with its other gateway machine in another zone.

There can be only one gateway that directly connects any two zones.

If your company requires the added security of a firewall between zones, gateway agents can be configured to communicate with or through the firewall. Gateway agents can be trusted or untrusted, meaning that they simply use HTTPS.

  • A firewall between zones: A gateway resource can be configured to communicate with an intermediary firewall in its path as a proxy to communicate with its peer on the other side of the gateway.

    If the actual gateway agents are behind a load balancer, do not register resources for them in CloudBees CD/RO. The actual gateway agents should be pinged by CloudBees CD/RO only via the load balancer.
  • Each gateway records the host/port combination each gateway agent/resource must use to communication with its peer on the other side of the gateway.

  • Multiple gateways can be defined for a zone if required. For example, you may have multiple resources in zoneA that need to communicate with each other, but some of those resources also need to communicate with zoneB, while others need to communicate with zoneC only. In this scenario, zoneA would require two gateways—one to zoneB and one to zoneC.

  • One resource can participate in multiple gateways. For example, assume we have 3 zones, zone1, zone2, and zone3, each created to contain agent/resource machines for a different, specific purpose (for example, production or testing), but we want to share or pass data from a resource in zone1 to another resource in zone2 or zone3. We need two gateways:

    • Gateway1 connects ResourceA in zone1 to ResourceC in zone3

    • Gateway2 connects ResourceA in zone1 to ResourceB in zone2

    With this gateway-resource configuration, ResourceA can communicate directly with zone2 or zone3.

For gateway agents v10.1 and higher, you must configure the CloudBees CD/RO server IP address.

  1. Navigate to Administration  Server settings.

  2. Select the System Settings from the left-hand menu.

  3. Scroll to the Server IP address entry and add the fully qualified domain name of your CloudBees CD/RO server’s load balancer.

    This setting controls how agents contact the CloudBees CD/RO server when they send results from job steps and similar prompts.

Viewing the gateway object list

To view all gateways currently defined in CloudBees CD/RO, navigate to Administration  Gateways. To performs tasks such as details, edit, delete, properties, access control, and so on, select the Action icon for the entry.

A gateway inherits privileges from the ZonesAndGateways ACL. Refer to Access control for more information.

Creating a gateway

To create a new gateway:

  1. Select Add gateway, and enter the following information:

    Field Name Description / Action

    Details tab

    Name

    Name of your choice for this gateway. The name must be unique among other gateway names.

    Description

    (Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

    • For example, the following HTML:

      <p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">\https://www.google.com</a>. </span> </p>

      renders as follows:

      <i>Note</i>: For more information about the <b>abc</b> object, see \https://www.google.com.

    Enabled

    Check box the gateway.

    Configuration tab

    Resource 1

    Name of your choice for the first of two required gateway resources. Do not include spaces in a resource name. For actual gateway agents that are behind a load balancer, specify the resource for the inbound or outbound load balancer (not the actual agent).

    Host 1

    Agent host name where Resource 1 resides. This external host name is used by Resource 2 to communicate with Resource 1. Specify only the host name or IP address of Resource 1. To use the host name from Resource 1’s definition, leave this field blank.

    Port 1

    Port number used by Resource 1. The default is the port number used by the resource.

    Resource 2

    Name of your choice for the second of two required gateway resources. Do not include spaces in a resource name. For actual gateway agents that are behind a load balancer, specify the resource for the inbound or outbound load balancer (not the actual agent).

    Host 2

    Agent host name where Resource 2 resides. This external host name is used by Resource 1 to communicate with Resource 2. Specify only the host name or IP address of Resource 2. To use the host name from Resource 2’s definition, leave this field blank.

    Port 2

    Port number used by Resource 2. The default is the port number used by the resource.

  2. Select OK to view your new gateway displayed in the list.

Editing a gateway

To edit a gateway:

  1. Locate the desired gateway and select its name. The Edit Gateway dialog displays, populated with previously supplied information to define the gateway.

  2. You can change any existing specifications or add new information.

  3. Select OK to save your changes.

Zone management

A zone is a way to partition a collection of agents to secure them from use by other groups. For example, you might choose to create a developer’s zone, a production zone, and a test zone—agents in one zone cannot directly communicate with agents in another zone.

  • A default zone is created during the CloudBees CD/RO installation. The server implicitly belongs to the default zone, which means all agents in this zone can communicate with the server directly without the use of a gateway.

  • Each zone can have one or more gateway agents, which you define. Gateway agents are used for communication from one zone to another zone. For more information, refer to Gateway objects.

  • Every agent, and all resources defined on that agent, can belong to one zone only.

  • Within a zone, agents can be either trusted or untrusted.

    • Trusted:The CloudBees CD/RO server verifies the agent’s identity using SSL certificate verification.

    • Untrusted: The CloudBees CD/RO server does not verify agent identity. Potentially, an untrusted agent is a security risk.

Viewing the zone object list

To view all zones currently defined in CloudBees CD/RO, navigate to Administration  Zones. To perform tasks such as view details, edit, delete, view properties, access control, and so on, select the Actions icon for the desired zone object.

A zone inherits privileges from the ZonesAndGateways ACL. Refer to Access control for more information.

Resource and Resource Pool inherit their privileges from Resources privileges. To create a resource, you must have Modify privileges on Resources, and you must have Modify privileges on the zone.

In addition, to move a resource from one zone to another, you must have Modify privileges on both the zones and the resource that you want to move.

Creating a new zone

To create a new zone:

  1. Select Add zone and enter the following information:

    Field Name Description

    Name

    Enter a name of your choice for this zone. The name must be unique among other zone names.

    Description

    (Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

    • For example, the following HTML:

      <p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">\https://www.google.com</a>. </span> </p>

      renders as follows:

      <i>Note</i>: For more information about the <b>abc</b> object, see \https://www.google.com.
  2. Select OK to view your new zone displayed in the table.

  3. To add resources to this zone, select Resources from the action menu for the zone object.

Editing a zone

Once you have created a new zone, you can later change any existing specifications or add new information.

To edit a zone:

  1. Locate the desired zone and select its name. The Edit Gateway dialog displays, populated with previously supplied information to define the gateway.

  2. You can change any existing specifications or add new information.

  3. Select OK to save your changes.