Deploying the API Gateway in Multiple Environments


You can specify configuration values in the API Gateway on a per-environment basis using environment variables in the envSettings.props file. For example, you can specify the port on which the API Gateway listens for HTTP traffic with different values depending on the environment in which the API Gateway is deployed.

The environment variable settings in the envSettings.props file are external to the API Gateway core configuration. The API Gateway runtime settings are determined by a combination of external environment variable settings and core configuration polices. This mechanism provides a simple and powerful approach for configuring the API Gateway to work across multiple environments.

The envSettings.props file is located in the conf directory of your API Gateway installation, and is read each time the API Gateway starts up. Environment variable values specified in the envSettings.props file are displayed as environment variable selectors in the Policy Studio (for example, ${env.PORT.TRAFFIC}) For more details on selectors, see Selecting Configuration Values at Runtime.

Configuring Environment Variables

The envSettings.props file enables you to externalize configuration values and set them on a per-environment basis. This section shows the configuration syntax used, and shows some example values in this file.

Environment Variable Syntax

If the API Gateway configuration contains a selector with a format of ${env.X}, where X is any string (for example, MyCustomSetting), the envSettings.props file must contain an equivalent name-value pair with the following format:


When the API Gateway starts up, every occurrence of the ${env.MyCustomSetting} selector is expanded to the value of MyCustomValue. For example, by default, the HTTP port in the server configuration is set to ${env.PORT.TRAFFIC}. Specifying a name-value pair of env.PORT.TRAFFIC=8080 in the envSettings.props file results in the server opening up port 8080 at start up.

Example Settings

The following simple example shows some environment variables set in the envSettings.props file:

# default port the API Gateway listens on for HTTP traffic

# default port the API Gateway listens on for management/configuration HTTP traffic

The following example screenshot shows the corresponding ${env.PORT.TRAFFIC} selector displayed in the Configure HTTP Interface dialog. At runtime, this is expanded to the value of the env.PORT.TRAFFIC environment variable specified in the envSettings.props file:

Environment Variable in Policy Studio

[Important] Important

All entries in the envSettings.props file use the env. prefix, and the corresponding selectors specified in the Policy Studio use the ${env.*) syntax. If you update the envSettings.props file, you must restart or deploy the API Gateway for updates to be applied to the currently running API Gateway configuration.

Configuring Certificates as Environment Variables

You can also use the envSettings.props file to bind a reference to a server host-specific SSL certificate to a specific deployment.

Example Syntax:

The following entry shows an example of the environment variable syntax used to specify a server host-specific certificate:


Alternatively, the following entry shows the syntax when the alias is the same as the Distinguished Name:


Example Settings

When the env.serverCertificate variable is specified in the envSettings.props file, the X.509 Certificate field in the Configure HTTPS Interface dialog can then reference its value using the ${env.serverCertificate} selector. The following example screenshot shows the corresponding ${env.serverCertificate} selector specified at the bottom of the Select Certificate dialog, which is displayed by pressing the X.509 Certificate button:

Referencing a Certificate Environment Variable in Policy Studio

The following example screenshot then shows the ${env.serverCertificate} selector referenced in X.509 Certificate field:

Certificate Environment Variable in Policy Studio

[Important] Important

In the envSettings.props file, you must specify commas using \\ escape characters. For example:

linux-test-desktop\\,OU=QA\\,O=Saturn Inc.\\,L=Dublin\\,ST=Dublin\\,C=IE