Rotate TLS certificates without restarting Kong Gateway

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

1. The following Konnect items are required to complete this tutorial:
   • Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

2. Set the personal access token as an environment variable:

   export KONNECT_TOKEN='YOUR KONNECT TOKEN'

   Copied!

1. Install the Gateway API CRDs before installing Kong Ingress Controller.

   kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml

   Copied!

2. Create a Gateway and GatewayClass instance to use.

   echo "
   apiVersion: v1
   kind: Namespace
   metadata:
     name: kong
   ---
   apiVersion: gateway.networking.k8s.io/v1
   kind: GatewayClass
   metadata:
     name: kong
     annotations:
       konghq.com/gatewayclass-unmanaged: 'true'
   spec:
     controllerName: konghq.com/kic-gateway-controller
   ---
   apiVersion: gateway.networking.k8s.io/v1
   kind: Gateway
   metadata:
     name: kong
   spec:
     gatewayClassName: kong
     listeners:
     - name: proxy
       port: 80
       protocol: HTTP
       allowedRoutes:
         namespaces:
           from: All
   " | kubectl apply -n kong -f -

   Copied!

Use the Konnect API to create a new CLUSTER_TYPE_K8S_INGRESS_CONTROLLER Control Plane:

CONTROL_PLANE_DETAILS=$(curl -X POST "https://us.api.konghq.com/v2/control-planes" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "My KIC CP",
       "cluster_type": "CLUSTER_TYPE_K8S_INGRESS_CONTROLLER"
     }'
)

We’ll need the id and telemetry_endpoint for the values.yaml file later. Save them as environment variables:

CONTROL_PLANE_ID=$(echo $CONTROL_PLANE_DETAILS | jq -r .id)
CONTROL_PLANE_TELEMETRY=$(echo $CONTROL_PLANE_DETAILS | jq -r '.config.telemetry_endpoint | sub("https://";"")')

Create mTLS certificates

Kong Ingress Controller talks to Konnect over a connected secured with TLS certificates.

Generate a new certificate using openssl:

openssl req -new -x509 -nodes -newkey rsa:2048 -subj "/CN=kongdp/C=US" -keyout ./tls.key -out ./tls.crt

The certificate needs to be a single line string to send it to the Konnect API with curl. Use awk to format the certificate:

export CERT=$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' tls.crt);

Next, upload the certificate to Konnect:

curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/dp-client-certificates" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "cert": "'$CERT'"
     }'

Finally, store the certificate in a Kubernetes secret so that Kong Ingress Controller can read it:

kubectl create namespace kong -o yaml --dry-run=client | kubectl apply -f -
kubectl create secret tls konnect-client-tls -n kong --cert=./tls.crt --key=./tls.key

1. Add the Kong Helm charts:

   helm repo add kong https://charts.konghq.com
   helm repo update

   Copied!

2. Create a values.yaml file:

   cat <<EOF > values.yaml
   controller:
     ingressController:
       image:
         tag: "3.5"
       env:
         feature_gates: "FillIDs=true"
       konnect:
         license:
           enabled: true
         enabled: true
         controlPlaneID: "$CONTROL_PLANE_ID"
         tlsClientCertSecretName: konnect-client-tls
         apiHostname: "us.kic.api.konghq.com"
   gateway:
     image:
       repository: kong
       tag: "3.9.3"
     env:
       konnect_mode: 'on'
       vitals: "off"
       cluster_mtls: pki
       cluster_telemetry_endpoint: "$CONTROL_PLANE_TELEMETRY:443"
       cluster_telemetry_server_name: "$CONTROL_PLANE_TELEMETRY"
       cluster_cert: /etc/secrets/konnect-client-tls/tls.crt
       cluster_cert_key: /etc/secrets/konnect-client-tls/tls.key
       lua_ssl_trusted_certificate: system
       proxy_access_log: "off"
       dns_stale_ttl: "3600"
     secretVolumes:
        - konnect-client-tls
   EOF

   Copied!

3. Install Kong Ingress Controller using Helm:

   helm install kong kong/ingress -n kong --create-namespace --values ./values.yaml --wait 

   Copied!

4. Set $PROXY_IP as an environment variable for future commands:

   export PROXY_IP=$(kubectl get svc --namespace kong kong-gateway-proxy -o jsonpath='{range .status.loadBalancer.ingress[0]}{@.ip}{@.hostname}{end}')
   echo $PROXY_IP

   Copied!

1. Add the Kong Helm charts:

   helm repo add kong https://charts.konghq.com
   helm repo update

   Copied!

2. Install Kong Ingress Controller using Helm:

   helm install kong kong/ingress -n kong --create-namespace --wait 

   Copied!

3. Set $PROXY_IP as an environment variable for future commands:

   export PROXY_IP=$(kubectl get svc --namespace kong kong-gateway-proxy -o jsonpath='{range .status.loadBalancer.ingress[0]}{@.ip}{@.hostname}{end}')
   echo $PROXY_IP

   Copied!

This how-to requires some Kubernetes services to be available in your cluster. These services will be used by the resources created in this how-to.

kubectl apply -f https://developer.konghq.com/manifests/kic/echo-service.yaml -n kong

Wait until the pods for the services are ready:

kubectl wait --for=condition=Ready pod --all -n kong --timeout=300s

Install cert-manager in your cluster to issue and rotate certificates automatically:

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm upgrade --install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true
kubectl wait -n cert-manager --for=condition=ready pod --all --timeout=90s