Deploying the Kong Gateway Agent in Docker

Deploy the Kong Gateway Agent as a stand alone application in Docker by downloading the Kong Gateway agent image.

Before you begin

Make sure that you have completed the following prerequisites:

Started the Docker client.
Assigned any one of the following user roles in Kong Gateway:
- admin
- super-admin
Obtained Admin API key and license key for Kong Gateway Enterprise. For Kong Gateway OSS (Open Source), keys are not required.
In Kong Gateway, the OpenAPI specification can be synchronized with federated API management along with APIs. Make sure that the OpenAPI specification is hosted at a URL and configure the URL for the service by using the Kong Spec Expose plugin. For details, see Kong Spec Expose.
Configured a Prometheus server. For details, see Prometheus Server documentation.
Enabled Prometheus plugin in Kong Gateway to collect metrics. Configure a Prometheus server in the docker compose file alongside the Kong Gateway service. Make sure that the Kong Gateway service and the Prometheus server are connected to the same docker network so that Prometheus can scrape metrics from Kong Gateway.
Verified that both Kong Gateway and federated API management are up and running before establishing connectivity through the agent.

Download and load the Kong Gateway agent Docker image

Click Download resources.
Download docker image corresponding to the Kong Runtime Connector standalone container (amd64) or Kong Runtime Connector standalone container (arm64) component based on your system architecture.
Kong runtime connector docker image can be downloaded from Federated API Management version 12.1.1 and later. If you are using a version earlier than 12.1.1, contact the IBM Support team to obtain the docker image.
Extract the tar file and open the Kong-runtime-config.yaml file from api-control plane-runtime-connector/runtime-configurations directory.

Configure the following properties related to

Control Plane Details
Kong Admin API Connection
Prometheus Connection
Runtime Identification
Sync Configuration (in seconds)

in the quick-start section.

Important: Kong gateway can establish connectivity with federated API management by configuring only the properties listed in the quick -start section. The remaining properties in the YAML file have default values and do not need to be modified unless you have specific requirements. In addition to the properties described in the quick -start section, you can modify other configuration properties to customize the deployment. Before modifying any additional properties, ensure that you understand their purpose and impact.

The following table lets you specify the configurations required to connect Kong Gateway with federated API management:

Properties	Description
control-plane-url	Mandatory. The valid URL used to access federated API management.
control-plane-username	Mandatory. User name that is used to log in to federated API management.
control-plane-password	Mandatory. Password of the corresponding user name, which is used for logging into the federated API management through basic authentication.
control-plane-truststore-path	Optional. Location of the truststore file. If control-plane-tls-enabled is set to true, you must specify a value for this property.
control-plane-truststore-password	Optional. Password to access the truststore file. If control-plane-tls-enabled is set to true, you must specify a value for this property.
control-plane-truststore-type	Optional. Type of the truststore. If control-plane-tls-enabled is set to true, you must specify a value for this property.
control-plane-keystore-path	Optional. Location of the keystore file. If control-plane-tls-enabled is set to true, you must specify a value for this property.
control-plane-keystore-password	Optional. Password to access the keystore file. If control-plane-tls-enabled is set to true, you must specify a value for this property.
control-plane-keystore-type	Optional. Type of the keystore. If control-plane-tls-enabled is set to true, you must specify a value for this property.
control-plane-key-alias	Optional. Alias of key in the keystore. If control-plane-tls-enabled is set to true, you must specify a value for this property.
control-plane-key-password	Optional. Password of key in the keystore. If control-plane-tls-enabled is set to true, you must specify a value for this property.
kong-admin-url	Mandatory. Specify the valid URL from which the Kong Gateway's assets must be retrieved. Example: `http://kong:<port-number>`
kong-spec-url	Optional. Specify the Kong gateway proxy URL from which the Open API specification must be retrieved. `http://kong:<port-number>`
kong-admin-api-key	Mandatory. Specify the `admin_api_key`of Kong Gateway.
prometheus-url	Mandatory. Specify the valid URL from which the Kong Gateway's metrics must be retrieved. Example: `http://prometheus:<port-number>`
runtime-id	Mandatory. Unique runtime ID used to identify the runtime in federated API management.
runtime-name	Mandatory. The runtime name defines how you want to identify the runtime in federated API management. Name must not exceed 50 characters.
runtime-deployment-type	Mandatory. Defines the type of deployment such as on-premise.
runtime-region	Optional. The region name where the runtime is hosted. Example: EAST US. Region name must not exceed 50 characters.
runtime-description	Optional. The runtime description. Description must not exceed 300 characters.
sync-interval	Mandatory. The duration in seconds in which the Agent must synchronize the changes made to the assets from the Kong Gateway to federated API management. Min:60 seconds Max: 21600 seconds (6 hours) Default: 300 seconds If you do not specify a value for this property, the default value is considered.
heartbeat-interval	Mandatory. The duration in seconds in which the Agent must send the health check status to federated API management. Min:60 seconds Max: 21600 seconds (6 hours) Default: 300 seconds If you do not specify a value for this property, the default value is considered.
metrics-interval	Mandatory. The duration in seconds in which the Agent must retrieve the metrics from Kong Gateway and send metrics to federated API management. Min:15 seconds Max: 900 seconds (5 minutes) Default: 60 seconds If you do not specify a value for this property, the default value is considered.

Note: It is recommended to store the following properties as a secret,

control-plane-username
control-plane-password
kong-admin-api-key
control-plane-truststore-password
control-plane-keystore-password
control-plane-key-password

Before running the Kong Gateway agent, create a secret file for the properties in the following directory: api-controlplane-runtime-connector/docker/secrets.

Ensure that:

The file name exactly matches the secret property name, for example, kong-admin-api-key
The file does not include a file extension such as .txt
The file contains only the secret value without labels, quotes, or extra whitespace.

For example, echo "your-actual-access-key-id" > kong-admin-api-key.

If the secret is configured, you do not need to specify the key in the quick-start section leave it blank. The agent automatically retrieves the key from the secret file.

Load the Docker image from a tar file using the following command:
docker load -i <filename.tar>

Deploy the Kong Gateway agent Docker image

Extract the Docker image package and run the following commands:.
cd devops

cd docker-compose
Run the following command:
```
docker-compose up -d
```
The Kong Gateway agent application starts.
Verify whether Kong Gateway (runtime) is registered with the federated API management and if the APIs and metrics are published and synchronized with federated API management respectively.
1. Open the federated API management application.
2. On the Catalog page, click the Runtimes.
3. Check whether the runtime is registered with federated API management by verifying if the runtime-name (specified in the Kong-runtime-config.yaml file) is listed. If the runtime is listed, it indicates that the runtime is successfully registered with the federated API management.
4. Check whether the runtime's health status is sent to federated API management by verifying the status of that corresponding runtime in the Status column. The status appears green only if the runtime is up and the heartbeats (status) are received successfully by federated API management.
5. Check whether the APIs are published from the runtime to federated API management by selecting Details from Action menu of the corresponding runtime for which, you want to verify if its APIs are published to federated API management.
6. Click Relations tab.
  
  A list of all the APIs associated with the runtime appears. You can also view the runtimes and its associated APIs in the APIs tab of the Catalog page.
7. Check if the API metrics are synchronized from the runtime to federated API management by clicking the icon under the Action column corresponding to the runtime for which, you want to verify if the metrics are published to federated API management.
8. Click Insights tab.
  The Runtime-specific monitor page renders the metrics of that runtime pertaining to a specified time interval. It lists the metrics such as Transactions, Error rate, Availability, Response time, and so on. For details, see Monitoring performance of runtimes in federated API management.