Contents
This topic describes the tasks, tools, and architecture used in API Gateway deployment and promotion. It explains the breakdown of tasks performed by a policy developer in a development environment, and the tasks performed by an API Gateway administrator in an upstream environment (for example, testing or production).
In a development environment, the policy developer works in a continuous cycle of iterative development, deployment, and testing. In this environment, it makes sense to keep all API Gateway configuration in a single package. This enables the policy developer to deploy the API Gateway configuration directly from Policy Studio in a single deployment package. The following diagram shows an example environment topology:
The deployment package contains the entire API Gateway configuration, and is implemented as a
.fed file.
When development is complete, the policy developer must prepare the configuration for promotion to upstream environments. This involves environmentalizing the configuration that will require environment-specific settings in upstream environments. The policy developer performs the following tasks in Policy Studio:
-
Selects the policy, listener, and external connection configuration settings that are environment specific.
-
Enters values for these environment-specific settings to ensure that the configuration remains deployable in the Development environment. These environment-specific settings are contained in the environment settings in the deployment package. If you have already entered values for these settings, these are used so you do not have to manually re-enter them.
-
Exports a policy package (
.polfile) on disk for promotion. For example, this enables you to FTP the file to the upstream environments, or to load the file into a CM repository.
The following diagram shows an example environment topology:
The policy package that is exported for promotion is implemented as a .pol file. This
file should remain unchanged when it is promoted to upstream environments.
A first cycle promotion refers to promoting to an upstream environment in which
no previous promotions have been performed. This means that the upstream environment is still running
the default factory configuration that is installed with the API Gateway. In this case, there is no
existing upstream environment package (.env) to load into the
Configuration Studio at promotion time.
Creating an Environment Package
In an upstream environment (for example, Testing), the API Gateway administrator uses the Configuration Studio
to create an environment package that is specific to their environment. Because this is the first
promotion cycle, the administrator opens the policy package (.pol) received from the
Development environment, and performs the following tasks:
-
Specifies values for the environment-specific settings selected in the Development environment (for example, policy, listener, and external connections).
-
Imports or creates certificates and keys.
-
Defines users and user groups.
-
Exports the environment package to a file on disk. The environment package is implemented as an
.envfile. For version history and rollback, you could also load the file into a CM repository.
Deploying the Policy and Environment Packages
When the environment package has been created, the administrator can use the API Gateway Manager web console
or scripts to deploy both the policy package from the Development environment and the newly created
environment package. Each environment will have its own version of the .env file containing
environment-specific settings, certificates, users, and so on. This constitutes a full deployable
configuration when combined with the unmodified .pol file from the Development environment.
![[Note]](../common_oracle/images/admon/note.png) |
Note |
|---|---|
|
Alternatively, the administrator can save a deployment package ( |
The following diagram shows an example environment topology:
|
Note |
|---|---|
|
The environment settings in the environment package ( |
A subsequent cycle promotion refers to promoting to an upstream environment that
has already had configuration promoted to it (any number of times). In this case, there is an existing
version of the upstream environment package (.env) to load into the Configuration Studio at
promotion time.
Creating the Environment Package
In the upstream environment, the API Gateway administrator uses the Configuration Studio to create an environment package specific to their environment that contains all the environment-specific settings, certificates, and so on. This is required for the new policy package received from the Development environment. Because this is not the first promotion cycle, there is already an environment package deployed in this environment. The administrator must merge this with the new policy package from the Development environment, which enables reuse of environment-specific settings already entered.
The administrator opens the new policy package from the Development environment, and the environment
package currently deployed in their environment. Opening these .pol and .env
files displays a merged view of the environment settings. The administrator then performs the following
tasks:
-
Specifies values for new environment-specific settings required by the new policy package from the Development environment.
-
Updates values for environment-specific settings that previously existed (if necessary).
-
Adds or removes certificates and keys.
-
Adds or removes users and user groups.
-
Exports the environment package to a file on disk. Alternatively, for version history and rollback, you could load the file into a CM repository.
Deploying the Policy and Environment Packages
When the environment package has been created, the API Gateway administrator can then deploy both the policy package received from the Development environment, and the new environment package using the API Gateway Manager web console, or using scripts.
The following diagram shows an example environment topology:
You must ensure to maintain a copy of previous configuration versions (policy and environment packages) in case you need to roll back and deploy an earlier configuration version. For example, you could use a Configuration Management (CM) repository to manage and roll back configuration package versions.
Some environments may require different environment values for connections, certificates, and so on (for example, a remote High Availability (HA) site for a production environment in an active/passive configuration). In this scenario, the primary site is active processing requests. The remote site is the backup passive configuration, deployed but not processing requests, and only becomes active if the primary site goes down. The same API Gateway configuration is deployed in both sites. Each site could be a separate domain, or one domain with different groups for each site. But specific environment values could be different for each site. For example, the remote site may connect to a different backup authentication server.
When the administrator receives the policy package (.pol) from the downstream environment,
they can use Configuration Studio to create separate environment packages (.env) for the primary
site and the remote site. The only difference between both environment packages is in the environment
values required. In the primary site, the administrator deploys the policy package and the primary site
environment package. In the remote HA site, the administrator deploys the same policy archive and the
remote site environment package.
When promoting encryption passphrase-protected configuration between environments (for example, from
testing to production), the passphrase for the target configuration (production) must be the same as
the passphrase in the source configuration (testing). If you are using a different passphrase in each
environment, before the deployment takes place, you must make a copy of the configuration (for example,
.fed file), and set it with the passphrase of the target configuration.
For details on setting encryption passphrases, see the API Gateway Administrator Guide.
