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 Kong Konnect 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:
- MacOS: Docker Desktop
-
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 Create runtime instance.
-
Choose the tile for your platform: MacOS, Windows, or Linux (Docker).
-
Click Generate script, then click Copy to copy it to your clipboard.
-
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 Kong Konnect account.
-
Click Done to go to the Runtime Instances overview, where you will see a new entry for your instance.
Custom setup
Prerequisites
Tools and permissions:
- All platforms: Docker and a Unix shell
-
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 Create Runtime Instance.
-
Click the tile for either Linux or Kubernetes.
For an advanced Docker setup using custom configuration values, use either tile. Don’t use the MacOS, Windows, or Linux (Docker) tiles.
-
Click Generate certificate.
Two new fields appear: a cluster certificate and a certificate 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:
- Cluster certificate:
tls.crt
- Certificate 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.
- Cluster certificate:
-
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:
-
Replace the values in
KONG_CLUSTER_CERT_STRING
andKONG_CLUSTER_CERT_KEY_STRING
with the path to your certificate and key files. -
Check the Linux or Kubernetes tiles in the Konnect UI to find the values for
KONG_CLUSTER_CONTROL_PLANE
,KONG_CLUSTER_SERVER_NAME
,KONG_CLUSTER_TELEMETRY_ENDPOINT
, andKONG_CLUSTER_TELEMETRY_SERVER_NAME
, then substitute them in the command sample.See Parameters for descriptions and the matching fields in Konnect.
-
-p 8000:8000
sets the proxy URL tohttp://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
.