Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
    • Overview of Konnect
    • Architecture
    • Network Resiliency and Availability
    • Port and Network Requirements
    • Compatibility
    • Stages of Software Availability
    • Release Notes
      • Control Plane Upgrades FAQ
      • Supported Installation Options
    • Overview
    • Access a Konnect Account
    • Set up a Runtime
    • Configure a Service
    • Implement and Test the Service
      • Publish and Consume Services
      • Register Applications
    • Import Kong Gateway Entities into Konnect
    • Overview
      • Overview
      • Dashboard
      • Manage Runtime Groups with UI
      • Manage Runtime Groups with decK
      • Installation Options
      • Install with Docker
      • Install on Kubernetes
      • Install on Linux
      • Install on AWS
      • Install on Azure
      • Upgrade a Runtime Instance to a New Version
      • Renew Certificates
      • Runtime Parameter Reference
    • Create Consumer Groups
      • Overview
      • Set Up and Use a Vault in Konnect
    • Kong Gateway Configuration in Konnect
    • Plugin Ordering Reference
    • Troubleshoot
    • Overview
    • Manage Service Documentation
      • Overview
      • Configure a Plugin on a Service
      • Configure a Plugin on a Route
    • Overview
    • Access the Dev Portal
    • Sign Up for a Dev Portal Account
      • Manage Developer Access
      • Manage Application Registration Requests
      • Manage Application Connections
      • Auto Approve Dev and App Registrations
      • Azure OIDC
      • Application Overview
      • Enable and Disable App Registration
        • Overview
        • Okta
        • Curity
        • Auth0
      • Create, Edit, and Delete an Application
      • Register an Application with a Service
      • Generate Credentials for an Application
    • Customize Dev Portal
    • Troubleshoot
    • Introduction to Analytics
    • Analyze Services and Routes
    • Reports Use Cases
    • Reports Reference
    • Troubleshoot
      • Manage a Konnect Account or Plan
      • Change to a Different Plan
      • Manage Payment Methods and Invoices
      • Overview
        • Overview
        • Manage Teams
        • Teams Reference
        • Roles Reference
      • Manage Users
      • Manage System Accounts
      • Set up SSO with OIDC
      • Set up SSO with Okta
      • Login Sessions Reference
    • Account and Org Deactivation
    • Troubleshoot
    • Overview
      • API Documentation
      • Identity Integration Guide
      • API Documentation
      • API Documentation
      • Portal RBAC Guide
      • Overview
      • Nodes
      • Data Plane Certificiates
        • Services
        • Routes
        • Consumers
        • Plugins
        • Upstreams
        • Certificates
        • CA Certificates
        • SNIs
        • Targets
        • Vaults
      • API Spec
      • Filtering
    • Labels

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
  • Custom setup
    • Prerequisites
    • Generate certificates
    • Start Kong Gateway
  • Access services using the proxy URL
Kong Konnect
  • Home
  • Kong Konnect
  • Runtime Manager
  • Runtime Instances
  • Set up a Kong Gateway Runtime with Docker

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

  1. Open the runtimes icon Runtime Manager.

  2. Select a runtime group.

  3. Click Create runtime instance.

  4. Choose the tile for your platform: MacOS, Windows, or Linux (Docker).

  5. Click Generate script, then click Copy to copy it to your clipboard.

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

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

  1. In Konnect, select runtimes icon Runtime Manager.

  2. Select a runtime group.

  3. Click Create Runtime Instance.

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

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

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

  7. 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 \
        -e "KONG_ROLE=data_plane" \
        -e "KONG_DATABASE=off" \
        -e "KONG_ANONYMOUS_REPORTS=off" \
        -e "KONG_VITALS_TTL_DAYS=723" \
        -e "KONG_CLUSTER_MTLS=pki" \
        -e "KONG_CLUSTER_CONTROL_PLANE=91288f8ed2.us.cp0.konghq.com:443" \
        -e "KONG_CLUSTER_SERVER_NAME=91288f8ed2.us.cp0.konghq.com" \
        -e "KONG_CLUSTER_TELEMETRY_ENDPOINT=91288f8ed2.us.tp0.konghq.com:443" \
        -e "KONG_CLUSTER_TELEMETRY_SERVER_NAME=91288f8ed2.us.tp0.konghq.com" \
        -e "KONG_CLUSTER_CERT_STRING='-----BEGIN PRIVATE KEY-----\-----END PRIVATE KEY-----\r\n'" \
        -e "KONG_CLUSTER_CERT_KEY_STRING='-----BEGIN CERTIFICATE-----\-----END CERTIFICATE-----\r\n'" \
        -e "KONG_LUA_SSL_TRUSTED_CERTIFICATE=system,/config/cluster.crt" \
        -p "$KONNECT_RUNTIME_PORT":8000 \
        -p "$KONNECT_RUNTIME_PORT_SECURE":8443 \
        kong/kong-gateway:3.2.1.0

docker run -d \
        -e "KONG_ROLE=data_plane" `
        -e "KONG_DATABASE=off" `
        -e "KONG_ANONYMOUS_REPORTS=off" `
        -e "KONG_VITALS_TTL_DAYS=723" `
        -e "KONG_CLUSTER_MTLS=pki" `
        -e "KONG_CLUSTER_CONTROL_PLANE=91288f8ed2.us.cp0.konghq.com:443" `
        -e "KONG_CLUSTER_SERVER_NAME=91288f8ed2.us.cp0.konghq.com" `
        -e "KONG_CLUSTER_TELEMETRY_ENDPOINT=91288f8ed2.us.tp0.konghq.com:443" `
        -e "KONG_CLUSTER_TELEMETRY_SERVER_NAME=91288f8ed2.us.tp0.konghq.com" `
        -e "KONG_CLUSTER_CERT_STRING='-----BEGIN PRIVATE KEY-----\-----END PRIVATE KEY-----\r\n'" `
        -e "KONG_CLUSTER_CERT_KEY_STRING='-----BEGIN CERTIFICATE-----\-----END CERTIFICATE-----\r\n'" `
        -e "KONG_LUA_SSL_TRUSTED_CERTIFICATE=system,/config/cluster.crt" `
        -p "$KONNECT_RUNTIME_PORT":8000 `
        -p "$KONNECT_RUNTIME_PORT_SECURE":8443 `
        kong/kong-gateway:3.2.1.0

  1. Replace the values in KONG_CLUSTER_CERT_STRING and KONG_CLUSTER_CERT_KEY_STRING with the path to your certificate and key files.

  2. 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, and KONG_CLUSTER_TELEMETRY_SERVER_NAME, then substitute them in the command sample.

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

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