Skip to content
Kong Gateway 2.8 Increases Security and Simplifies API Management.  —Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Konnect Cloud
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Kong Konnect Platform

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Request Demo
  • Kong Gateway
  • Konnect Cloud
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Kong Konnect Platform

  • Docs contribution guidelines
    • Using the Konnect Docs
    • Key Concepts and Terms
    • Access a Konnect Account
      • Manage a Konnect Account or Plan
      • Change to a Different Plan
      • Manage Payment Methods and Invoices
      • Manage Users and Roles
      • Set up SSO with Okta
    • Account and Org Deactivation
    • License Management
    • Port and Network Requirements
    • Network Resiliency and Availability
    • Migrate from Kong Gateway to Konnect Cloud
      • Set up a Runtime
      • Configure a Service
      • Implement and Test the Service
    • Manage Konnect Cloud with decK
    • Manage Services
      • Manage Service Documentation
      • Publish a Service to Dev Portal
      • Docker
      • Kubernetes
      • Linux
      • Runtime Parameter Reference
    • Upgrade a Runtime to a New Version
    • Renew Certificates
      • Developer Registration
      • Manage Developer Access
      • Auto Approve Dev and App Registrations
      • Application Overview
      • Create, Edit, and Delete an Application
      • Enable App Registration
      • Disable App Registration
      • Manage Application Registration Requests
      • Manage Application Connections
      • Register an Application with a Service
      • Generate Credentials for an Application
      • Appearance
      • Public Portal
      • Add a Custom Domain
    • Generating Vitals Reports
    • Configure a Plugin on a Service
    • Configure a Plugin on a Route
    • Configure Global or Consumer Plugins
    • Proxy Traffic
      • Konnect API Reference

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Quick setup
    • Prerequisites
    • Run the quick setup script
  • Advanced setup
    • Prerequisites
    • Generate certificates
    • Start Kong Gateway
  • Access services using the proxy URL
Konnect Cloud
  • Kong Konnect Platform
  • Konnect Cloud
  • Runtime manager

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 Cloud 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.

Quick setup

Prerequisites

  • You have Runtime Admin or Organization Admin permissions in Konnect Cloud.
  • The quick setup script requires Docker and a Unix shell (for example, bash or zshell). 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

  1. 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 Cloud account.

  2. (Optional) If this is not the first runtime configuration, click Configure New Runtime.

  3. Click Copy Script.

    You can expand the codeblock by clicking Show to see the entire script.

  4. Replace the placeholder for <your-password> with your own Konnect Cloud password.

  5. 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.

  6. 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

Prerequisites

  • You have Runtime Admin or Organization Admin permissions in Konnect Cloud.
  • Tools and permissions:
    • All platforms: Docker installed
    • Linux: User added to the docker group
    • Windows and MacOS: Docker Desktop installed

Generate certificates

  1. 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 Cloud account.

  2. (Optional) If this is not the first runtime configuration, click Configure New Runtime.

  3. Open the tab that suits your environment: Linux or Kubernetes.

    For an advanced Docker setup, use either tab. Do not use the Quick Setup tab.

  4. 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.

  5. 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.

  6. Store the files on your runtime’s local filesystem.

Important: Certificates expire every six (6) 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.

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_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_CA_CERT=/{PATH_TO_FILE}/ca.crt" \
  -e "KONG_CLUSTER_CERT_KEY=/{PATH_TO_FILE}/tls.key" \
  --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_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_CA_CERT=/{PATH_TO_FILE}/ca.crt" `
  -e "KONG_CLUSTER_CERT_KEY=/{PATH_TO_FILE}/tls.key" `
  --mount type=bind,source="$(pwd)",target={PATH_TO_KEYS_AND_CERTS},readonly `
  -p 8000:8000 `
  kong/kong-gateway:2.8.0.0-alpine
  1. Replace the values in KONG_CLUSTER_CERT, KONG_CLUSTER_CA_CERT, and KONG_CLUSTER_CERT_KEY with the paths to your certificate and key files.

  2. 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.

    Konnect Runtime Parameters

    See Parameters for descriptions and the matching fields in Konnect.

  3. -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
    
  4. Run the docker run command with your substituted values.

  5. 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.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2022