Set up a Kong Gateway Runtime with Docker

Set up a Docker runtime through the Konnect Runtime Manager and configure your Kong Gateway instance to accept configuration from Konnect. The Runtime Manager keeps track of all runtimes associated with the Konnect SaaS account.

You have the following options when configuring a new runtime with Docker:

Use the quick setup script, which generates a data plane running on localhost.
Use the advanced setup to customize your installation.

Note: Kong does not host runtimes. You must install and host your own runtime instances.

Prerequisites

You have a Kong Konnect account. Contact your sales representative for access.
(Quick Setup only) Tools and permissions:
- All platforms: Docker and jq installed
- Linux: User added to the docker group
- Windows: Docker Desktop installed and integrated with a WSL 2 backend

Quick setup

From the left navigation menu, open Runtimes.

For the first runtime, the page opens to a Configure New Runtime form.

Once configured, this page lists all runtimes associated with the Konnect SaaS account.
(Optional) If this is not the first runtime configuration, click Configure New Runtime.
Click Copy Script.

You can expand the codeblock by clicking Show to see the entire script.
Replace the placeholder for <your-password> with your own Konnect SaaS password.
Run the script on any host you choose.

This script creates a Docker container running a simple Kong Gateway instance and connects it to your Konnect SaaS account.
Click Done to go to the Runtime Manager overview.

Once the script has finished running, the Runtimes Manager will include a new entry for your instance.

Advanced setup

Generate certificates

In Konnect, from the left navigation menu, select Runtimes.

For the first runtime, the page opens to a Configure New Runtime form.

Once configured, this page lists all runtimes associated with the Konnect SaaS account.
(Optional) If this is not the first runtime configuration, click Configure New Runtime.
Open the tab that suits your environment: Quick Setup - Docker, Linux, or Kubernetes.
Click Generate Certificate.

Three new fields appear: a certificate, a private key, and a root CA certificate. The contents of these fields are unique to each runtime configuration.
Save the contents of each field into a separate file in a safe location:
- Certificate: tls.crt
- Private key: tls.key
- Root CA Certificate: ca.crt
If you navigate away from this page before saving all of the certificate and key files, you will need to regenerate them.
Store the files on your runtime’s local filesystem.

Important: Certificates expire after six months and must be renewed. See Renew Certificates.

Keep the configuration page open for the next section, as you’ll need to refer back to it for the configuration parameters.

Configure the runtime

Next, pull the Kong Gateway Docker image, and configure a Kong Gateway runtime using the certificate, the private key, and the remaining configuration details on the Configure Runtime page.

Using Docker, pull the following image:

 $ docker pull kong/kong-gateway:2.3.2.0-alpine

You should now have your Kong Gateway image locally.

Verify that it worked, and find the image ID matching your repository:
```
1
 $ docker images
```

Tag the image ID for easier use, replacing <IMAGE_ID> with the one matching your repository:

 $ docker tag <IMAGE_ID> kong-ee

Return to Konnect and copy the codeblock in the Step 2. Configuration Parameters section.
Replace the values in KONG_CLUSTER_CERT, KONG_CLUSTER_CERT_KEY, and KONG_LUA_SSL_TRUSTED_CERTIFICATE with the paths to your certificate files.

Using the provided values, bring up a new container.

See Parameters for descriptions and the matching fields in Konnect.

 $ docker run -d --name kong-gateway-dp1 \
   -e "KONG_ROLE=data_plane" \
   -e "KONG_DATABASE=off" \
   -e "KONG_ANONYMOUS_REPORTS=off" \
   -e "KONG_VITALS_TTL_DAYS=732" \
   -e "KONG_CLUSTER_MTLS=pki" \
   -e "KONG_CLUSTER_CONTROL_PLANE=<example.cp.konnect.foo>:443" \
   -e "KONG_CLUSTER_SERVER_NAME=<kong-cpoutlet-example.service>" \
   -e "KONG_CLUSTER_TELEMETRY_ENDPOINT=<example.tp.konnect.foo>:443" \
   -e "KONG_CLUSTER_TELEMETRY_SERVER_NAME=<kong-telemetry-example.service>" \
   -e "KONG_CLUSTER_CERT=/<path-to-file>/tls.crt" \
   -e "KONG_CLUSTER_CERT_KEY=/<path-to-file>/tls.key" \
   -e "KONG_LUA_SSL_TRUSTED_CERTIFICATE=system,/<path-to-file>/ca.crt" \
   --mount type=bind,source="$(pwd)",target=<path-to-keys-and-certs>,readonly \
   -p 8000:8000 \
   kong-ee

-p 8000:8000 sets the proxy URL to http://localhost:8000. To change this, bind the port to a different host. For example, you can explicitly set an IP:

 -p 127.0.0.1:8000:8000

On the Configure New Runtime page, click Done to go to the Runtime Manager overview.

The Runtime Manager will include a new entry for your instance.

Access services using the proxy URL

Kong Gateway uses port 8000 for the proxy, taking incoming traffic from consumers, and forwarding it to upstream services.

The default proxy URL is http://localhost:8000. If you configured a different host above, replace localhost with your hostname. Use this URL, along with any routes you set, to access your services.

For example, to access a service with the route /mock, use http://localhost:8000/mock, or http://example-host:8000/mock.