(Legacy) Set up a Kong Gateway Runtime on Kubernetes

This documentation is for the legacy Konnect environment at konnect.konghq.com. For the cloud.konghq.com environment, see the current Konnect documentation.

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.

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, select Runtime Manager.

2. Select a runtime group.

3. Click New Runtime Instance.

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

5. Click Generate Certificate.

   Two new fields appear: a certificate and a private 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:

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

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.

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 code block in the Step 2. Configuration Parameters section.

   

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

    image:
      repository: kong/kong-gateway
      tag: "2.7.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