Set up a Kong Gateway Runtime with Docker

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

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

Use the quick setup script, which generates a data plane container 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.

Quick setup

Prerequisites

The quick setup script requires Docker and a Unix shell
Platform-specific 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. If you can’t set up a WSL 2 backend, see the advanced instructions for a custom Docker setup instead.

Run the quick setup script

Open the Runtime Manager.
Select a runtime group.
Click + New Runtime Instance.
Click Copy Script.
Replace the placeholder for <your-password> with your own Konnect Cloud 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 Cloud account.
Click Done to go to the Runtime Instances overview, where you will see a new entry for your instance.

Advanced setup

Prerequisites

Tools and permissions:

All platforms: Docker installed
Linux: User added to the docker group
Windows and MacOS: Docker Desktop installed

Generate certificates

In Konnect, select Runtime Manager.
Select a runtime group.
Click New Runtime Instance.
Open the tab for either Linux or Kubernetes.

For an advanced Docker setup using custom configuration values, use either tab. Do not use the Quick Setup tab.
Click Generate Certificate.

Two new fields appear: a certificate and a private key. 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
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 the local filesystem of the runtime instance.

Note: The certificates generated by Konnect have a ten year expiration date by default. If you bring your own certificates, make sure to monitor the expiration date. To rotate certificates, see Renew Certificates.

Start Kong Gateway

Use the following docker run command sample as a guide to compile your actual values:

      Any Unix shell
    

      Windows PowerShell
    
$ docker run -d --name kong-dp \
  -e "KONG_ROLE=data_plane" \
  -e "KONG_DATABASE=off" \
  -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" \
  --mount type=bind,source="$(pwd)",target={PATH_TO_KEYS_AND_CERTS},readonly \
  -p 8000:8000 \
  kong/kong-gateway:2.8.0.0-alpine
docker run -d --name kong-dp `
  -e "KONG_ROLE=data_plane" `
  -e "KONG_DATABASE=off" `
  -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" `
  --mount type=bind,source="$(pwd)",target={PATH_TO_KEYS_AND_CERTS},readonly `
  -p 8000:8000 `
  kong/kong-gateway:2.8.0.0-alpine

Replace the values in KONG_CLUSTER_CERT and KONG_CLUSTER_CERT_KEY with the paths to your certificate and key files.
Check the Linux or Kubernetes tabs in the Konnect UI to find the values for KONG_CLUSTER_CONTROL_PLANE, KONG_CLUSTER_SERVER_NAME, KONG_CLUSTER_TELEMETRY_ENDPOINT, and KONG_CLUSTER_TELEMETRY_SERVER_NAME, then substitute them in the example below.

See Parameters for descriptions and the matching fields in Konnect.
-p 8000:8000 sets the proxy URL to http://localhost:8000. If you want 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
```
Run the docker run command with your substituted values.
In Konnect, click Done to go to the Runtime Instances overview, where you will see 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.