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
  • Prerequisites
  • Set up Helm
  • Generate certificates
  • Configure the runtime
    • Configure secrets
    • Write and apply configuration
    • Troubleshooting
  • Access services using the proxy
Konnect Cloud
  • Kong Konnect Platform
  • Konnect Cloud
  • Runtime manager

Set up a Kong Gateway Runtime on Kubernetes

Set up a Kubernetes 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.

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

Prerequisites

  • You have Runtime Admin or Organization Admin permissions in Konnect Cloud.
  • Kubernetes cluster with load balancer: Konnect is compatible with all distributions of Kubernetes. You can use a Minikube, GKE, or OpenShift TLS.
  • kubectl or oc access: You have kubectl or oc (if working with OpenShift) installed and configured to communicate to your Kubernetes TLS.
  • Helm 3 is installed.

Set up Helm

On your runtime’s system, create a namespace and pull down the kong Helm repo.

  1. Create a namespace:
     $ kubectl create namespace kong
    
  2. Add the Kong charts repository:
     $ helm repo add kong https://charts.konghq.com
    
  3. Update Helm:
     $ helm repo update
    

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.

Configure the runtime

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

Configure secrets

Store the certificates and key you generated through the Runtime Manager in Kubernetes secrets.

  1. Create a tls secret using the tls.cert and tls.key files you saved earlier:

     $ kubectl create secret tls kong-cluster-cert -n kong \
       --cert=/{PATH_TO_FILE}/tls.crt \
       --key=/{PATH_TO_FILE}/tls.key
    
  2. Create a generic secret for the ca.crt file:

     $ kubectl create secret generic kong-cluster-ca -n kong \
       --from-file=ca.crt=/{PATH_TO_FILE}/ca.crt
    

Write and apply configuration

  1. Create a values.yaml file.

  2. Return to Konnect and copy the codeblock in the Step 2. Configuration Parameters section.

    Konnect Runtime Parameters

  3. Paste the codeblock into your values.yaml file. It should look something like this:

     image:
       repository: kong/kong-gateway
       tag: "2.8.0.0-alpine"
    
     secretVolumes:
     - kong-cluster-cert
     - kong-cluster-ca
    
     admin:
       enabled: false
    
     env:
       role: data_plane
       database: "off"
       vitals_ttl_days: 732
       cluster_mtls: pki
       cluster_control_plane: {EXAMPLE.CP.KONNECT.FOO}:443
       cluster_server_name: {KONG-CPOUTLET-EXAMPLE.SERVICE}
       cluster_telemetry_endpoint: {EXAMPLE.TP.KONNECT.FOO}:443
       cluster_telemetry_server_name: {KONG-TELEMETRY-EXAMPLE.SERVICE}
       cluster_ca_cert: /etc/secrets/kong-cluster-ca/ca.crt
       cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
       cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
    
     ingressController:
       enabled: false
       installCRDs: false
    
  4. Replace any placeholder values in the env section of the values.yaml with your specific values from Konnect.

    If your cluster cert locations differ from the paths in the template, update the values in cluster_cert, cluster_cert_key, and cluster_ca_cert with references to the secrets you created earlier.

    See Parameters for descriptions and matching values in Konnect.

  5. Apply the values.yaml:

     $ helm install my-kong kong/kong -n kong \
       --values ./values.yaml
    
  6. 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.

Troubleshooting

If you configured everything above but don’t see your runtime in the Runtime Manager, check the logs from your deployment:

$ kubectl logs deployment/my-kong-kong -n kong

If you find any errors and need to update values.yaml, make your changes, save the file, then reapply the configuration by running the Helm upgrade command:

$ helm upgrade my-kong kong/kong -n kong \
    --values ./values.yaml

Access services using the proxy

To proxy traffic through this runtime, you’ll need its external IP address, a port, and a route.

  1. To find the address and port, run:

     $ kubectl get service my-kong-kong-proxy -n kong
    
  2. In the output, the IP in the EXTERNAL_IP column is the access point for your Konnect services:

     NAME         TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                      AGE
     kong-proxy   LoadBalancer   10.63.254.78   35.233.198.16   80:32697/TCP,443:32365/TCP   22h
    
  3. With the external IP and one of the available ports (80 or 443), and assuming that you have configured a service with a route, you can now access your service at {EXTERNAL_IP}:{PORT}/{ROUTE}.

    For example, using the values above and a sample route, you now have the following:

    • IP: 35.233.198.16
    • Port: 80
    • Route: /mock

    Putting them together, the end result looks like this: 35.233.198.16:80/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