Generate API Management Docker images

This topic describes how to generate and configure custom API Management Docker images using scripts. This approach is recommended in a production environment for high availability.

For details on how to download and run pre-built Docker images in a development or test environment, see Run pre-built API Management Docker images.

Set up your local environment

The following components are required on your system:

Docker

API Management supports the following:

  • Docker version 1.13.x
  • Docker Compose version 1.8.0.x

API Management

The following components are required:

  • API Gateway Linux installer available from Axway Support
  • API Gateway Docker scripts available as a separate zip file from Axway Support
  • API Gateway license file
Note   Docker images require an API Gateway license that is not restricted to a specific host name. For more details, contact your Axway account manager.

Specify an API Gateway license file

For details on how to specify a license file, see Step 1—Build your Docker images. You can also set the APIGW_LICENSE variable on the host machine that runs the Docker daemon. For example, this is useful when running a pre-built Docker image in a development environment. For details, see Run pre-built API Management Docker images.

The following command shows an example of setting this variable:

export APIGW_LICENSE="$(cat /path/to/license/my-apigateway-license.lic | gzip | base64)

Note   If the APIGW_LICENSE environment variable is set, and a license file named lic.lic already exists in the container, the environment variable overrides the license file at runtime. If a license file does not exist, a new lic.lic file is created and populated with the value of this variable (in compressed and base-64 decoded format).

If this variable is not set or invalid, and there is no license file in the container, the API Gateway fails to start up.

Python

Python version 2.7.x is required to create Docker data volumes. For more details, see Customize your API Management topology in Docker.

Minimum disk space and memory

The following are required for the 3-node sample architecture:

  • At least 100 GB of disk space
  • At least 16 GB of RAM
Tip   On Linux systems, the free -h command provides human-readable information about the amount of free and used memory in the system. You can also use other tools such as top and vm_stat to get this information. See also Troubleshooting.

Create your API Management Docker infrastructure

When you have set up your environment, the steps to create your API Management Docker infrastructure are as follows:

Create your API Managment Docker infrastructure

These steps are described in the following sections:

Step 1—Build your Docker images

Docker images are required to generate your API Management topology. To build your Docker images, perform the following steps:

  1. Unzip the file containing the Docker scripts available from Axway Support. For example:

APIGateway_7.5.3_SamplesPackageDocker_linux-x86-64_BN<n>

  1. In the directory in which you unzipped the scripts, use the build.py command to build your images:
./build.py --installer <API_GATEWAY_LINUX_INSTALL_FILE> --license <API_GATEWAY_LICENSE_FILE> --baseos <BASE_O/S> --sp <OPTIONAL_SERVICE_PACK_FILE> --clean

The parameters are described as follows:

Parameter

Description

--installer Specify the API Gateway Linux installer file. This parameter is required.
--license Specify the API Gateway license file. This parameter is required.
--baseos

Specify one of the following operating systems for the container base image:

  • centos: CentOS Linux 7
  • rhel: Red Hat Enterprise Linux 7

Defaults to centos.

--sp

Specify an optional API Gateway service pack file if needed.

--clean Removes the static images from the local Docker registry.

The following command shows an example with Red Hat Enterprise Linux 7 as the base image:

./build.py --installer ~/dependencies/APIGateway_7.5.3_Install_linux-x86-64_BNn.run --license lic.lic --baseos redhat --clean

This command builds the following images to the local Docker registry:

apigw_linux64_redhat
cassandra_redhat
gwredhat
registry.access.redhat.com/rhel7

Step 2—Generate your API Management topology

You can create different kinds of API Management topology images using the following command:

./compose.py --config <API_GATEWAY_JSON_TOPOLOGY_FILE>

For example:

./compose.py --config sample-compose-config/gwlatest-3nodeha-apimgr.json

Note   If the --baseos parameter was supplied to build.py, it must also be supplied to the compose.py script. For example:

./compose.py --config sample-compose-config/gwlatest-3nodeha-apimgr.json --baseos redhat

The following default JSON topology files are available in the sample-compose-config subdirectory:

JSON topology file Description
gwlatest-1node-apimgr.json Includes 1 API Manager, 1 Admin Node Manager, and 3 Cassandra nodes
gwlatest-2nodeha-apimgr.json Includes 2 API Manager, 1 Admin Node Manager, 1 Node Manager, and 3 Cassandra nodes
gwlatest-3nodeha-apimgr.json Includes 3 API Manager, 2 Admin Node Manager, 1 Node Manager, and 3 Cassandra nodes

For example, for the recommended three-node HA system, the following images are added to the local Docker registry:

gwlatest-3nodeha-apimgr_node3
gwlatest-3nodeha-apimgr_node2
gwlatest-3nodeha-apimgr_node1

The generated docker-compose.yml file is written to the compose-generated/servers directory.

For details on how to customize the docker-compose.yml file for the default 3-node system to suit your environment, see Customize your API Management topology in Docker.

Cassandra consistency levels

Tip   The consistency levels in the JSON topology file are set to QUORUM by default. However, for a development or test configuration running against one-node Cassandra only, the consistency level should be set to ONE (because QUORUM requires 3 nodes at least). For each node, the default settings in the topology file are as follows:

"readConsistencyLevel" : "QUORUM",
"writeConsistencyLevel" : "QUORUM",

Step 3—Run and test your API Management system

You can run and test your API Management topology images locally, or you can copy the images and docker-compose.yml to your Docker-compatible system.

Run docker-compose up to launch containers from the runtime images. For example:

docker-compose -f compose-generated/servers/gwlatest-3nodeha-apimgr/docker-compose.yml up -d
Tip   You can omit -d to view output on stdout instead.

You must wait for the services in containers to start. For example:

ps -ef | grep vshell
root 19048 18558 11 15:36 ? 00:00:18 Node Manager on node1 ( Node Manager Group) (7.5.3) (vshell)root 19081 18627 12 15:36 ? 00:00:19 Node Manager on node2 ( Node Manager Group) (7.5.2) (vshell)
root 19159 18558 23 15:37 ? 00:00:27 PortalInstance-1 (PortalGroup-1) (7.5.3) (vshell)
root 19193 18627 23 15:37 ? 00:00:27 PortalInstance-2 (PortalGroup-1) (7.5.3) (vshell)

Further information

For details on how to create Docker data volumes for persistence, see Customize your API Management topology in Docker.

Troubleshooting

If a container dies, this is most often due to insufficient memory being available. For details, see Minimum disk space and memory.

For example, you can run the following command on the host operating system to diagnose why a process died:

dmesg | grep -E -i -B100 'killed process'

Related Links