Kong Gateway

3.3.x (latest)

Install with Kong Gateway using Helm

This guide will show you how to install Kong Gateway on Kubernetes with Helm. Two options are provided for deploying a local development environment using Docker Desktop Kubernetes and Kind Kubernetes. You can also follow this guide using an existing cloud hosted Kubernetes cluster.

Docker Desktop Kubernetes

Kind Kubernetes

Kubernetes in the Cloud

Docker Desktop

Docker Desktop Kubernetes is a tool for running a local Kubernetes cluster using Docker. These instructions will guide you through deploying Kong Gateway to a local Docker Desktop Kubernetes cluster.

Dependencies

Kong Admin API & Kong Manager services will be published to localhost at the domain name kong.127-0-0-1.nip.io. The nip.io service is used to automatically resolve this domain to the localhost address.

Configure Kubectl

Set your kubeconfig context and verify with the following command:

kubectl config use-context docker-desktop && kubectl cluster-info

Kind Kubernetes

Kind or “Kubernetes-in-Docker”, is a tool for running local Kubernetes clusters in Docker containers. These instructions will guide you through deploying Kong Gateway to a local Kind Kubernetes cluster.

Dependencies

Helm 3
kubectl v1.19 or later
KinD

Kong Admin API & Kong Manager services will be published to localhost at the domain name kong.127-0-0-1.nip.io. The nip.io service is used to automatically resolve this domain to the localhost address.

Create Kubernetes Cluster

A Kind config file is required to build a local cluster listening locally on ports 80 and 443. Starting from the bash command, and ending with the EOF" line, highlight and copy this text block, then paste it into your terminal.

bash -c "cat <<EOF > /tmp/kind-config.yaml && kind create cluster --config /tmp/kind-config.yaml
apiVersion: kind.x-k8s.io/v1alpha4
kind: Cluster
name: kong
networking:
  apiServerAddress: "0.0.0.0"
  apiServerPort: 16443
nodes:
  - role: control-plane
    extraPortMappings:
    - listenAddress: "0.0.0.0"
      protocol: TCP
      hostPort: 80
      containerPort: 80
    - listenAddress: "0.0.0.0"
      protocol: TCP
      hostPort: 443
      containerPort: 443
EOF"

Set your kubeconfig context and verify with the following commands.

kubectl config use-context kind-kong && kubectl cluster-info

Kubernetes in the cloud

These instructions will guide you through deploying Kong Gateway to a cloud hosted Kubernetes cluster you have already built. Please ensure your local system and your Kubernetes cluster meet the dependency criteria listed below before continuing.

Please note that it is recommended to first try the Docker Desktop or Kind Kubernetes local deploys before proceeding to build on a cloud hosted kubernetes cluster.

Dependencies

Helm 3
kubectl v1.19 or later
Domain Name
DNS configured with your DNS Provider
Public Cloud hosted Kubernetes cluster
Cloud load balancer support

Configure Kubectl

Verify your kubeconfig context is set correctly with the following command.

kubectl cluster-info

Prepare the Helm chart

To inject your custom domain name into the Helm values file configure the Kong Gateway deployment with:

curl the example values.yaml file.

curl -o ~/quickstart.yaml -L https://bit.ly/KongGatewayHelmValuesAIO

Replace example.com with your preferred domain name and export as a variable.
```
export BASE_DOMAIN="example.com"
```
Find & replace the 127-0-0-1.nip.io base domain in the values file with your preferred domain name.

MacOS

Linux

   sed -i '' "s/127-0-0-1\.nip\.io/$BASE_DOMAIN/g" ~/quickstart.yaml

   sed -i "s/127-0-0-1\.nip\.io/$BASE_DOMAIN/g" ~/quickstart.yaml

Create Kong Gateway secrets

Configuring Kong Gateway requires a namespace and configuration secrets. The secrets contain Kong’s enterprise license, admin password, session configurations, and PostgreSQL connection details.

Create the Kong namespace for Kong Gateway:
```
kubectl create namespace kong
```

Create Kong config and credential variables:

kubectl create secret generic kong-config-secret -n kong \
    --from-literal=portal_session_conf='{"storage":"kong","secret":"super_secret_salt_string","cookie_name":"portal_session","cookie_same_site":"Lax","cookie_secure":false}' \
    --from-literal=admin_gui_session_conf='{"storage":"kong","secret":"super_secret_salt_string","cookie_name":"admin_session","cookie_same_site":"Lax","cookie_secure":false}' \
    --from-literal=pg_host="enterprise-postgresql.kong.svc.cluster.local" \
    --from-literal=kong_admin_password=kong \
    --from-literal=password=kong

Create a Kong Enterprise license secret:

Kong Enterprise Free Mode

Kong Enterprise Licensed Mode

kubectl create secret generic kong-enterprise-license --from-literal=license="'{}'" -n kong --dry-run=client -o yaml | kubectl apply -f -

This command must be run in the directory that contains your license.json file.

kubectl create secret generic kong-enterprise-license --from-file=license=license.json -n kong --dry-run=client -o yaml | kubectl apply -f -

Kong can run in two license modes, Enterprise Licensed, or Enterprise Free. If you would like to run all enterprise features, please contact your account manager to request a license.json file.

Install Cert Manager

Cert Manager provides automation for generating SSL certificates. Kong Gateway uses Cert Manager to provide the required certificates.

Install Cert Manager and create a basic SelfSigned certificate issuer:

Add the Jetstack Cert Manager Helm repository:

helm repo add jetstack https://charts.jetstack.io ; helm repo update

Install Cert Manager:

helm upgrade --install cert-manager jetstack/cert-manager \
    --set installCRDs=true --namespace cert-manager --create-namespace

Create a SelfSigned certificate issuer:

bash -c "cat <<EOF | kubectl apply -n kong -f -
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: quickstart-kong-selfsigned-issuer-root
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: quickstart-kong-selfsigned-issuer-ca
spec:
  commonName: quickstart-kong-selfsigned-issuer-ca
  duration: 2160h0m0s
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: Issuer
    name: quickstart-kong-selfsigned-issuer-root
  privateKey:
    algorithm: ECDSA
    size: 256
  renewBefore: 360h0m0s
  secretName: quickstart-kong-selfsigned-issuer-ca
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: quickstart-kong-selfsigned-issuer
spec:
  ca:
    secretName: quickstart-kong-selfsigned-issuer-ca
EOF"

You can replace this self signed issuer with your own CA issuer, ACME LetsEncrypt issuer, or other external issuers to get valid certificates for Kong Gateway.

Deploy Kong Gateway

Docker Desktop Kubernetes

Kind Kubernetes

Kubernetes in the Cloud

Once all dependencies are installed and ready, deploy Kong Gateway to your cluster:

Add the Kong Helm repo:

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

Install Kong:

helm install quickstart kong/kong --namespace kong --values https://bit.ly/KongGatewayHelmValuesAIO

Wait for all pods to be in the Running and Completed states:
```
kubectl get po --namespace kong -w
```
Once all the pods are running, open Kong Manager in your browser at its ingress host domain, for example: https://kong.127-0-0-1.nip.io. Or open it with the following command:
```
open "https://$(kubectl get ingress --namespace kong quickstart-kong-manager -o jsonpath='{.spec.tls[0].hosts[0]}')"
```
You will receive a “Your Connection is not Private” warning message due to using selfsigned certs. If you are using Chrome there may not be an “Accept risk and continue” option, to continue type thisisunsafe while the tab is in focus to continue.
If running Kong Gateway in Licensed Mode, use the Super Admin username with the password set in the secret kong-config-secret created earlier: kong_admin:kong

Once all dependencies are installed and ready, deploy Kong Gateway to your cluster:

Add the Kong Helm repo:

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

Install Kong:

helm install quickstart kong/kong --namespace kong --values https://bit.ly/KongGatewayHelmValuesAIO

Wait for all pods to be in the Running and Completed states:
```
kubectl get po --namespace kong -w
```
Once all the pods are running, open Kong Manager in your browser at its ingress host domain, for example: https://kong.127-0-0-1.nip.io. Or open it with the following command:
```
open "https://$(kubectl get ingress --namespace kong quickstart-kong-manager -o jsonpath='{.spec.tls[0].hosts[0]}')"
```
You will receive a “Your Connection is not Private” warning message due to using selfsigned certs. If you are using Chrome there may not be an “Accept risk and continue” option, to continue type thisisunsafe while the tab is in focus to continue.
If running Kong Gateway in Licensed Mode, use the Super Admin username with the password set in the secret kong-config-secret created earlier: kong_admin:kong

Once all dependencies are installed and ready, deploy Kong Gateway to your cluster:

Add the Kong Helm repo:

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

Install Kong:

helm install quickstart kong/kong --namespace kong --values ~/quickstart.yaml

Wait for all pods to be in the Running and Completed states:
```
kubectl get po --namespace kong -w
```
Once all pods are running, find the cloud load balancer of your Kong Gateway data plane:
```
kubectl get svc --namespace kong quickstart-kong-proxy -w
```
Using your DNS Provider, configure a DNS entry to point to the load balancer shown by the last step. A wildcard DNS record is recommended for development environments.
Open Kong Manager with the kong subdomain on your domain. For example: https://kong.example.com, or open it with the following command:
```
open "https://$(kubectl get ingress --namespace kong quickstart-kong-manager -o jsonpath='{.spec.tls[0].hosts[0]}')"
```
You will receive a “Your Connection is not Private” warning message due to using selfsigned certs. If you are using Chrome there may not be an “Accept risk and continue” option, to continue type thisisunsafe while the tab is in focus to continue.
If running Kong Gateway in Licensed Mode, use the Super Admin username with the password set in the secret kong-config-secret created earlier: kong_admin:kong

Use Kong Gateway

Kong Gateway is now serving the Kong Manager Web UI and the Kong Admin API.

For local deployments, Kong Manager is locally accessible at https://kong.127-0-0-1.nip.io. The nip.io service resolves this domain to localhost also known as 127.0.0.1.

You can configure Kong via the Admin API with decK, Insomnia, HTTPie, or cURL, at https://kong.127-0-0-1.nip.io/api:

      cURL
    
      HTTPie
    
curl --silent --insecure -X GET https://kong.127-0-0-1.nip.io/api -H 'kong-admin-token:kong'
http --verify=no get https://kong.127-0-0-1.nip.io/api kong-admin-token:kong

Teardown

Docker Desktop Kubernetes

Kind Kubernetes

Kubernetes in the Cloud

To remove Kong Gateway from your system, follow these instructions:

Remove Kong

helm uninstall --namespace kong quickstart

Delete Kong secrets

kubectl delete secrets -nkong kong-enterprise-license
kubectl delete secrets -nkong kong-config-secret

Remove Kong database PVC

kubectl delete pvc -n kong data-quickstart-postgresql-0

Remove Kong Helm chart repository
```
helm repo remove kong
```

Remove cert-manager

helm uninstall --namespace cert-manager cert-manager

Remove jetstack cert-manager Helm repository
```
helm repo remove jetstack
```

To remove Kong Gateway from your system, follow these instructions:

Remove Kong

helm uninstall --namespace kong quickstart

Delete Kong secrets

kubectl delete secrets -nkong kong-enterprise-license
kubectl delete secrets -nkong kong-config-secret

Remove Kong database PVC

kubectl delete pvc -n kong data-quickstart-postgresql-0

Remove Kong Helm chart repository
```
helm repo remove kong
```

Remove cert-manager

helm uninstall --namespace cert-manager cert-manager

Remove jetstack cert-manager Helm repository
```
helm repo remove jetstack
```

Destroy the Kind cluster

kind delete cluster --name=kong
rm /tmp/kind-config.yaml 

To remove Kong Gateway from your system, follow these instructions:

Remove Kong

helm uninstall --namespace kong quickstart

Delete Kong secrets

kubectl delete secrets -nkong kong-enterprise-license
kubectl delete secrets -nkong kong-config-secret

Remove Kong database PVC

kubectl delete pvc -n kong data-quickstart-postgresql-0

Remove Kong Helm chart repository
```
helm repo remove kong
```

Remove cert-manager

helm uninstall --namespace cert-manager cert-manager

Remove jetstack cert-manager Helm Repository
```
helm repo remove jetstack
```

Next Steps

See the Kong Ingress Controller docs for how-to guides, reference guides, and more.