You are browsing documentation for an outdated version. See the latest documentation here.

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:

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

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.

  1. bash -c "cat <<EOF > /tmp/kind-config.yaml && kind create cluster --config /tmp/kind-config.yaml
  2. apiVersion: kind.x-k8s.io/v1alpha4
  3. kind: Cluster
  4. name: kong
  5. networking:
  6.   apiServerAddress: "0.0.0.0"
  7.   apiServerPort: 16443
  8. nodes:
  9.   - role: control-plane
  10.     extraPortMappings:
  11.     - listenAddress: "0.0.0.0"
  12.       protocol: TCP
  13.       hostPort: 80
  14.       containerPort: 80
  15.     - listenAddress: "0.0.0.0"
  16.       protocol: TCP
  17.       hostPort: 443
  18.       containerPort: 443
  19. EOF"

Set your kubeconfig context and verify with the following commands.

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

Configure Kubectl

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

  1. kubectl cluster-info

Prepare the Helm chart

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

  1. curl the example values.yaml file.

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

  2. Replace example.com with your preferred domain name and export as a variable.

    1. export BASE_DOMAIN="example.com"

  3. Find & replace the 127-0-0-1.nip.io base domain in the values file with your preferred domain name.

MacOS

Linux

  1.    sed -i '' "s/127-0-0-1\.nip\.io/$BASE_DOMAIN/g" ~/quickstart.yaml
  1.    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.

  1. Create the Kong namespace for Kong Gateway:

    1. kubectl create namespace kong

  2. Create Kong config and credential variables:

    1. kubectl create secret generic kong-config-secret -n kong \
    2.     --from-literal=portal_session_conf='{"storage":"kong","secret":"super_secret_salt_string","cookie_name":"portal_session","cookie_samesite":"off","cookie_secure":false}' \
    3.     --from-literal=admin_gui_session_conf='{"storage":"kong","secret":"super_secret_salt_string","cookie_name":"admin_session","cookie_samesite":"off","cookie_secure":false}' \
    4.     --from-literal=pg_host="enterprise-postgresql.kong.svc.cluster.local" \
    5.     --from-literal=kong_admin_password=kong \
    6.     --from-literal=password=kong

  3. Create a Kong Enterprise license secret:

Kong Enterprise Free Mode

Kong Enterprise Licensed Mode

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

  1. 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:

  1. Add the Jetstack Cert Manager Helm repository:

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

  2. Install Cert Manager:

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

  3. Create a SelfSigned certificate issuer:

    1. bash -c "cat <<EOF | kubectl apply -n kong -f -
    2. apiVersion: cert-manager.io/v1
    3. kind: Issuer
    4. metadata:
    5.   name: quickstart-kong-selfsigned-issuer-root
    6. spec:
    7.   selfSigned: {}
    8. ---
    9. apiVersion: cert-manager.io/v1
    10. kind: Certificate
    11. metadata:
    12.   name: quickstart-kong-selfsigned-issuer-ca
    13. spec:
    14.   commonName: quickstart-kong-selfsigned-issuer-ca
    15.   duration: 2160h0m0s
    16.   isCA: true
    17.   issuerRef:
    18.     group: cert-manager.io
    19.     kind: Issuer
    20.     name: quickstart-kong-selfsigned-issuer-root
    21.   privateKey:
    22.     algorithm: ECDSA
    23.     size: 256
    24.   renewBefore: 360h0m0s
    25.   secretName: quickstart-kong-selfsigned-issuer-ca
    26. ---
    27. apiVersion: cert-manager.io/v1
    28. kind: Issuer
    29. metadata:
    30.   name: quickstart-kong-selfsigned-issuer
    31. spec:
    32.   ca:
    33.     secretName: quickstart-kong-selfsigned-issuer-ca
    34. 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:

  1. Add the Kong Helm repo:

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

  2. Install Kong:

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

  3. Wait for all pods to be in the Running and Completed states:

    1. kubectl get po --namespace kong -w

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

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

  5. 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:

  1. Add the Kong Helm repo:

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

  2. Install Kong:

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

  3. Wait for all pods to be in the Running and Completed states:

    1. kubectl get po --namespace kong -w

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

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

  5. 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:

  1. Add the Kong Helm repo:

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

  2. Install Kong:

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

  3. Wait for all pods to be in the Running and Completed states:

    1. kubectl get po --namespace kong -w

  4. Once all pods are running, find the cloud load balancer of your Kong Gateway data plane:

    1. kubectl get svc --namespace kong quickstart-kong-proxy -w

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

  6. Open Kong Manager with the kong subdomain on your domain. For example: https://kong.example.com, or open it with the following command:

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

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

  1. curl --silent --insecure -X GET https://kong.127-0-0-1.nip.io/api -H 'kong-admin-token:kong'
  1. 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:

  1. Remove Kong

    1. helm uninstall --namespace kong quickstart

  2. Delete Kong secrets

    1. kubectl delete secrets -nkong kong-enterprise-license
    2. kubectl delete secrets -nkong kong-config-secret

  3. Remove Kong database PVC

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

  4. Remove Kong Helm chart repository

    1. helm repo remove kong

  5. Remove cert-manager

    1. helm uninstall --namespace cert-manager cert-manager

  6. Remove jetstack cert-manager Helm repository

    1. helm repo remove jetstack

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

  1. Remove Kong

    1. helm uninstall --namespace kong quickstart

  2. Delete Kong secrets

    1. kubectl delete secrets -nkong kong-enterprise-license
    2. kubectl delete secrets -nkong kong-config-secret

  3. Remove Kong database PVC

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

  4. Remove Kong Helm chart repository

    1. helm repo remove kong

  5. Remove cert-manager

    1. helm uninstall --namespace cert-manager cert-manager

  6. Remove jetstack cert-manager Helm repository

    1. helm repo remove jetstack

  7. Destroy the Kind cluster

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

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

  1. Remove Kong

    1. helm uninstall --namespace kong quickstart

  2. Delete Kong secrets

    1. kubectl delete secrets -nkong kong-enterprise-license
    2. kubectl delete secrets -nkong kong-config-secret

  3. Remove Kong database PVC

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

  4. Remove Kong Helm chart repository

    1. helm repo remove kong

  5. Remove cert-manager

    1. helm uninstall --namespace cert-manager cert-manager

  6. Remove jetstack cert-manager Helm Repository

    1. helm repo remove jetstack

Next Steps

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