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.
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.
- Create a namespace:
$ kubectl create namespace kong
- Add the Kong charts repository:
$ helm repo add kong https://charts.konghq.com
- Update Helm:
$ helm repo update
Generate certificates
-
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.
-
(Optional) If this is not the first runtime configuration, click Configure New Runtime.
-
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.
-
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.
-
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.
- Certificate:
-
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.
-
Create a
tls
secret using thetls.cert
andtls.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
-
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
-
Create a
values.yaml
file. -
Return to Konnect and copy the codeblock in the Step 2. Configuration Parameters section.
-
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
-
Replace any placeholder values in the
env
section of thevalues.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
, andcluster_ca_cert
with references to the secrets you created earlier.See Parameters for descriptions and matching values in Konnect.
-
Apply the
values.yaml
:$ helm install my-kong kong/kong -n kong \ --values ./values.yaml
-
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.
-
To find the address and port, run:
$ kubectl get service my-kong-kong-proxy -n kong
-
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
-
With the external IP and one of the available ports (
80
or443
), 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
- IP: