Step 8 – Create an API Gateway Docker image

To create an API Gateway Docker image, use the build_gw_image.py script. This script builds an API Gateway Docker image using the base image you created in Step 5 – Create base Docker image.

You must specify the following as options when using the build_gw_image.py script:

  • Domain certificate, private key, and password.
  • API Gateway license. Your license must also include any optional licensed features that you are using (for example, API Manager, FIPS mode).

This script also supports additional options when generating an API Gateway image. For example, you can:

  • Specify a group ID for the API Gateway group. All containers started from this image are part of this API Gateway group.
  • Build an image from existing API Gateway configuration by specifying an existing fed file (or existing pol and env files). If OAuth or API Manager are enabled in the fed, they are enabled the API Gateway Docker image.
  • Specify a merge directory to add to the API Gateway Docker image. This merge directory can include custom configuration, JAR files, and so on.
  • Enable FIPS mode for the API Gateway Docker image.

For the latest script usage and options, run the script with no options, or with the -h option. For example:

$ cd emt_containers-<version>
$ ./build_gw_image.py -h

The following examples show how you can use the script to build API Gateway Docker images:

Create an API Gateway image using defaults

The following example creates an API Gateway Docker image using default certificates and a default factory fed.

Usage guidelines

  • Do not use default options on production systems. The --default-cert option is provided only as a convenience for development environments.

Example command

$ cd emt_containers-<version>
$ ./build_gw_image.py 
--license=/tmp/api_gw_license_complete.lic 
--default-cert 
--factory-fed

This example creates an API Gateway Docker image named api-gateway-defaultgroup with a tag of latest. This image has the following characteristics:

  • Uses a default certificate and key (generated from running ./gen_domain_cert.py --default-cert)
  • Uses a default factory fed

Create an API Manager image using defaults

The following example creates an API Manager Docker image using default certificates and a default factory fed with samples.

Usage guidelines

  • Do not use default options on production systems. The --default-cert and --api-manager options are provided only as a convenience for development environments.
  • When using the --api-manager default option:
    • You must have an Apache Cassandra server running at the host name specified by ${environment.CASS_HOST}.
    • You must have a metrics database running at ${environment.METRICS_DB_URL}, with credentials of ${environment.METRICS_DB_USERNAME} and ${environment.METRICS_DB_PASS}.
    • You can log in to the API Manager web console using a default user name of apiadmin and the default password.
  • You must have a valid API Manager license file to create an API Manager image.
  • Use the --merge-dir option to specify the apigateway directory containing the JDBC driver JAR file for the metrics database in the ext/lib directory.
    • The merge directory must be called apigateway and must have the same directory structure as the apigateway directory of an API Gateway installation.
    • Copy the JAR file to a new directory /tmp/apigateway/ext/lib/ and specify /tmp/apigateway to the --merge-dir option.

Example command

$ cd emt_containers-<version>
$ ./build_gw_image.py 
--license=/tmp/api_gw_api_mgr.lic 
--merge-dir /tmp/apigateway
--default-cert --api-manager

This example creates an API Gateway Docker image named api-gateway-defaultgroup with a tag of latest. This image has the following characteristics:

  • Uses a default certificate and key (generated from running ./gen_domain_cert.py --default-cert)
  • Uses a default factory fed with samples and with API Manager configured
  • Uses a specified merge directory (containing the JDBC driver JAR file for the metrics database) that is merged into the API Gateway image

Create an API Gateway image using domain certificate

The following example creates an API Gateway Docker image using a specified domain certificate and a default factory fed.

Example command

$ cd emt_containers-<version>
$ ./build_gw_image.py 
--license=/tmp/api_gw_license_complete.lic 
--domain-cert=certs/mydomain/mydomain-cert.pem 
--domain-key=certs/mydomain/mydomain-key.pem 
--domain-key-pass-file=/tmp/pass.txt
--factory-fed
--parent-image=my-gw-base:1.0 --out-image=my-api-gateway:1.0

This example creates an API Gateway Docker image named my-api-gateway with a tag of 1.0. This image has the following characteristics:

  • Based on the my-gw-base:1.0 image
  • Uses a specified certificate and key
  • Uses a default factory fed

Create an API Gateway image using existing fed and customized configuration

The following example creates an API Gateway Docker image using an existing API Gateway deployment package (fed file) and customized configuration from an existing API Gateway installation.

Usage guidelines

  • Ensure that your fed contains the following:
    • API Gateway version 7.6.2 configuration.
    • You can upgrade existing projects (from version 7.5.1 or later) using projupgrade, see Upgrade an API Gateway project in the API Gateway DevOps Deployment Guide.
    • You can also upgrade existing fed files using Policy Studio or upgradeconfig, see the API Gateway Upgrade Guide.
    • Only IP addresses that are accessible at runtime. For example, the fed cannot contain IP addresses of container-based Admin Node Managers and API Gateways, as IP addresses are usually dynamically assigned in a Docker network.
  • Use the --merge-dir option to add additional files and folders to the apigateway directory inside the image.
    • The merge directory must be called apigateway and must have the same directory structure as the apigateway directory of an API Gateway installation.
    • For example, to add a custom envSettings.props file to your image, copy envSettings.props to a new directory /tmp/apigateway/conf/ and specify /tmp/apigateway to the --merge-dir option. The envSettings.props must contain only IP addresses and host names that are accessible at runtime. For example, it cannot contain IP addresses of container-based Admin Node Managers and API Gateways, as IP addresses are usually dynamically assigned in a Docker network.
    • For example, to add custom JAR files to your image, copy the JAR files to a new directory /tmp/apigateway/ext/lib/ and specify /tmp/apigateway to the --merge-dir option.

Example command

$ cd emt_containers-<version>
$ ./build_gw_image.py 
--license=/tmp/api_gw.lic 
--domain-cert=certs/mydomain/mydomain-cert.pem 
--domain-key=certs/mydomain/mydomain-key.pem 
--domain-key-pass-file=/tmp/pass.txt
--parent-image=my-gw-base:1.0
--fed=my-group-fed.fed --fed-pass-file=/tmp/my-group-fedpass.txt
--group-id=my-group
--merge-dir=/tmp/apigateway

This example creates an API Gateway Docker image named api-gateway-my-group with a tag of latest. This image has the following characteristics:

  • Based on the my-gw-base:1.0 image.
  • Uses a specified certificate and key.
  • Uses a specified fed that contains API Gateway 7.6.2 configuration.
  • Belongs to the API Gateway group my-group. All containers started from this image belong to this group.
  • Uses a specified merge directory that is merged into the API Gateway image.

Create a FIPS-enabled API Gateway image

The following example creates an API Gateway Docker image that runs in FIPS-compliant mode.

Usage guidelines

  • You must have a valid FIPS-compliant mode API Gateway license file to create an image that can run in FIPS-compliant mode.

Example command

$ cd emt_containers-<version>
$ ./build_gw_image.py 
--license=/tmp/api_gw_fips.lic
--domain-cert=certs/mydomain/mydomain-cert.pem 
--domain-key=certs/mydomain/mydomain-key.pem 
--domain-key-pass-file=/tmp/pass.txt
--parent-image=my-gw-base:1.0 --out-image=my-fips-api-gateway:1.0
--fips

This example creates an API Gateway Docker image named my-fips-api-gateway with a tag of 1.0. This image has the following characteristics:

  • Based on the my-gw-base:1.0 image.
  • Uses a specified certificate and key.
  • Runs in FIPS-compliant mode.

Create an API Manager or OAuth enabled API Gateway image

The following example creates an API Manager enabled API Gateway Docker image using a deployment package exported from Policy Studio that has API Manager configured.

You can create an OAuth-enabled API Gateway Docker image in the same way (using a deployment package exported from Policy Studio that has OAuth configured).

Usage guidelines

To create an API Manager enabled image:

  • You must have a valid API Manager license file to create an API Manager image.
  • Use the --merge-dir option to specify the apigateway directory containing the JDBC driver JAR file for the metrics database in the ext/lib directory.
    • The merge directory must be called apigateway and must have the same directory structure as the apigateway directory of an API Gateway installation.
    • Copy the JAR file to a new directory /tmp/apigateway/ext/lib/ and specify /tmp/apigateway to the --merge-dir option.
  • Before running the build_gw_image.py script you must first create a project in Policy Studio, configure API Manager in that project, and export the configuration from Policy Studio as a fed file (or pol and env files). For more information, see Step 1 – Configure API Manager in Policy Studio.
  • You must specify the configuration exported from Policy Studio to the build_gw_image.py script when building the API Gateway Docker image.

To create an OAuth-enabled image:

  • Before running the build_gw_image.py script you must first create a project in Policy Studio, configure OAuth in that project, and export the configuration from Policy Studio as a fed file (or pol and env files). For more information, see Step 1 – Configure OAuth in Policy Studio.
  • You must specify the configuration exported from Policy Studio to the build_gw_image.py script when building the API Gateway Docker image.

Example command

$ cd emt_containers-<version>
$ ./build_gw_image.py 
--license=/tmp/api_gw_api_mgr.lic
--domain-cert=certs/mydomain/mydomain-cert.pem 
--domain-key=certs/mydomain/mydomain-key.pem 
--domain-key-pass-file=/tmp/pass.txt
--parent-image=my-gw-base:1.0
--fed=api-mgr-group-fed.fed --fed-pass-file=/tmp/api-mgr-group-fedpass.txt
--group-id=api-mgr-group
--merge-dir=/tmp/apigateway

This example creates an API Gateway Docker image named api-gateway-api-mgr-group with a tag of latest. This image has the following characteristics:

  • Based on the my-gw-base:1.0 image.
  • Uses a specified certificate and key.
  • Uses a specified fed that contains API Manager configuration that was exported from Policy Studio.
  • Belongs to the API Gateway group api-mgr-group. All containers started from this image belong to this group.
  • Uses a specified merge directory (containing the JDBC driver JAR file for the metrics database) that is merged into the API Gateway image

Related Links