Managing Deployment Zones

Manage deployment zones on the platform, including adding, viewing, modifying, and deleting deployment zones.

API Platform Version: 8.2 and later

Table of Contents

  1. What is a deployment zone?
  2. Who can manage deployment zones on the API Platform?
  3. How do I manage deployment zones on the API Platform?
  4. How do I add a deployment zone?
  5. How do I configure hostname settings for a deployment zone?
  6. How do I manage environment/implementation associations for a deployment zone?
  7. How do I make changes to a deployment zone?
  8. How do I delete a deployment zone?
  9. How do I set up a deployment zone to support HTTPS?

What is a deployment zone?

If an API is hosted on the platform and is using the platform as a proxy, the API owner can specify one or more deployment zones, such as a geographical area or a specific data center, that an API implementation will be proxied in.

The Business Admin configures the deployment zones, which are then available for selection by the API Admin. Deployment zones are defined separately for each tenant.

A deployment zone can include one or more containers in a cluster. Multiple deployment zones could be at the same location, or could be in different data centers.

Any container or container cluster that can host APIs for the platform instance can be defined as a deployment zone. If deployment zones are not configured, any valid container or container cluster is identified as a possible deployment zone and is therefore available to someone adding an API on the platform.

For example, there could be Network Director clusters in different data centers, and APIs could be hosted in each of the deployment zones.

The deployment zone definition includes information about the geographical location. In the API portal user interface, deployment zones are displayed in a map view.

Deployment zones are also useful for DNS redirection. Although the host address is set up, the deployment zone can include a DNS redirection. This allows you to choose not to expose the actual hostname. For example, Network Director might be on one specific hostname, but it might be determined that it's better not to expose that hostname to customers, but rather to specify a DNS redirection for each deployment zone.

Configuring deployment zones allows you to:

  • Limit the containers or container clusters that are available for platform APIs, so that the APIs can only use those that you specify are available. When you define deployment zones, only those that are defined are valid choices when adding an API to the platform. You might have other containers or container clusters that you don't want to use for platform APIs. Defining deployment zones protects those from use by platform APIs.
  • Limit a specific container or container cluster for use only as a Sandbox endpoint or only as a live endpoint. When you define deployment zones, you can specify Environment/Implementation associations that it's valid for. For example, you might have one deployment zone designated for live API traffic, and another designated for all other types of traffic, such as sandbox and testing. This allows you to ensure that production servers are not impacted by testing activity.
  • Define a virtual host. A Network Director HTTP or HTTPS listener only has one hostname, but you could configure deployment zones to show a different hostname, a virtual hostname. This is useful in scenarios where the API needs to be published with a specific hostname, independently of where it is deployed.

Note: It's best to maintain one-to-one mapping of deployment zone to API Gateways.

Back to top

Who can manage deployment zones on the API Platform?

Business Admins at the root level can manage deployment zones for the API platform.

Deployment zones cannot be configured at the Organization level.

Back to top

How do I manage deployment zones on the API Platform?

A Business Admin can complete the following tasks relating to deployment zones, in the developer portal user interface.

The Deployment Zones List page (Administration > Deployment Zones) displays a summary view of all deployment zones currently configured on the platform. From this page you can:

Back to top

How do I add a deployment zone?

The Business Admin can add a deployment zone in the developer portal user interface.

When you create a deployment zone, it automatically becomes available for all valid environments and implementations. However, you can modify these associations manually, to control which deployment zones are used for what traffic, as explained in What is a deployment zone? above.

To manage associations, see How do I manage environment/implementation associations for a deployment zone? below.

Note: It's best to maintain one-to-one mapping of deployment zone to API Gateways.

To add a deployment zone:
  1. Log in to the developer portal as the Business Admin.
  2. Go to Administration > Deployment Zones.
  3. On the right, click Add.
  4. In the Add Deployment Zone page, add information about the deployment zone:
    • Name and Description
    • API Gateway field: From the drop-down list, choose the Network Director container name/container key that's applicable for the deployment zone. API implementations associated with this deployment zone will be deployed to this container.
      Note: API Gateways are added by the Policy Manager Administrator. If there are no API Gateways, or you don't see what you want on the list—for example, you need an HTTPS option and there isn't one—check with the Administrator.
    • Allow APIs to specify vanity URLs (CNAMEs): If this option is enabled, you can choose to allow APIs to specify their own vanity hostnames (which must be valid registered domain names).
    • Hostname Generation: Choose a hostname generation method, out of the available options. If you choose Override API Gateway Hostname, specify a valid hostname. For more information, see How do I configure hostname settings for a deployment zone? below.
  5. Click Save.

Note: If you choose an API Gateway that's already referenced by an existing deployment zone, you'll see a warning message on save. It's best to maintain a one-to-one correlation.

Back to top

How do I configure hostname settings for a deployment zone?

When you're setting up a deployment zone, the configuration settings available to you are determined by the settings in the underlying API Gateway that you select.

In terms of hostname configuration, the possible scenarios are:

  • Overriding the default API Gateway hostname with a specific vanity hostname might be:
    • Allowed (optional)
    • Not allowed
    • Required
  • Adding a random prefix, to either the API Gateway hostname or a vanity hostname, might be:
    • Allowed (optional)
    • Not allowed
    • Required

In terms of configuration of a deployment zone in the developer portal, the possible options are listed below. These options might or might not be available depending on the underlying API Gateway settings.

Note: The underlying API Gateway settings always take precedence over the Deployment Zone settings. If the underlying API Gateway settings change after you've set up the deployment zone, you'll be prompted to confirm new choices the next time you edit the deployment zone.

Deployment zone hostname settings and their explanations are shown in the table below.

This setting... Means...
Allow APIs to specify vanity URLs (CNAMEs) If you choose this option, API Admins will have the option to specify a vanity URL for an API implementation (API > Implementation > Deployments Edit > Provide Vanity Hostname).
Hostname Generation:
Use API Gateway Hostname
If you choose this option, the API hostname will be the same as the hostname of the API Gateway container; for example, apigl.com.
Hostname Generation:
Override API Gateway Hostname

If you choose to override the API Gateway hostname, you must specify your own hostname; for example, api.mycompany.com.

In this scenario, all APIs in the business will have the same hostname. The API Admin must make sure that the DNS system is configured to resolve this hostname to the hostname for the API implementation.

Append random prefix to hostname To guarantee uniqueness in the environment, the platform can append a randomly-generated prefix to the hostname. For example, if the hostname is example.com, the generated API hostname will be something like api15633.example.com. Once the random prefix is assigned to the specific API, the API Admin must configure the DNS system for the API so that it resolves the hostname to the hostname for the API implementation.

Back to top

How do I manage environment/implementation associations for a deployment zone?

When you create a deployment zone, by default it becomes available for any environments and implementations on the platform. However, you can manage these associations to specify which type of environment and which type of implementation the deployment zone is valid for.

By specifying the environment/implementation associations, you can limit a specific container or container cluster for use only in Sandbox implementations or only in Live implementations. This gives you flexibility in managing the traffic for your business.

To manage environment/implementation associations for a deployment zone:
  1. Log in to the developer portal as the Business Admin.
  2. Go to Administration > Deployment Zones.
  3. Click the link for the deployment zone you want to manage.
  4. In the Environment/Implementation Associations section, click Edit.
  5. On the Environment/Implementation Associations page, all current associations are displayed. You can:
    • Add an association: choose an environment and implementation and click Finish.
    • Edit an association: find the association on the list and click the Edit icon. Modify as needed and then click Finish.
    • Delete an association: find the association on the list and click the Delete icon.
    • Delete all associations: click Clear All. At the confirmation message, click OK.
  6. When done, click Finish to save changes and exit.

Back to top

How do I make changes to a deployment zone?

You can modify a deployment zone, if needed, at any point. If you make changes to an existing deployment zone, make sure you're not impacting current APIs that are using the deployment zone.

Note: The underlying API Gateway hostname settings, as explained in How do I configure hostname settings for a deployment zone? above, always take precedence over the Deployment Zone settings. If the underlying API Gateway settings change after you've set up the deployment zone, you'll be prompted to confirm new choices the next time you edit the deployment zone. If you need assistance, contact the Administrator for the underlying infrastructure.

To edit a deployment zone:
  1. Log in to the developer portal as the Business Admin.
  2. Go to Administration > Deployment Zones.
  3. Click the link for the deployment zone you want to edit.
  4. In the top section, click Edit to modify basic values associated with the implementation. See To add a deployment zone. For information about hostname generation for the deployment zone, see How do I configure hostname settings for a deployment zone?
  5. In the bottom section, click Edit to manage environment/implementation associations. See To manage environment/implementation associations for a deployment zone.
  6. When done, click Finish to save changes.

Back to top

How do I delete a deployment zone?

Note: If you delete a deployment zone, make sure you're not impacting current APIs that are using the deployment zone.

To delete a deployment zone:
  1. Log in to the developer portal as the Business Admin.
  2. Go to Administration > Deployment Zones.
  3. Click the link for the deployment zone you want to delete.
  4. Click Delete.
  5. At the confirmation message, click OK. The deployment zone is deleted.

Back to top

How do I set up a deployment zone to support HTTPS?

When you add a deployment zone in the developer portal, you specify the Network Director container name/container key that's applicable for the deployment zone, in the API Gateway field. Within the developer portal, you can only select from available options. If there are no HTTPS deployment zones available, you'll need to ask the Policy Manager Administrator to set that up for you.

If the deployment zone doesn't support HTTPS, the API Admin won't be able to specify HTTPS for the API implementation protocol, and will not be able to use SNI.

Back to top