Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
|
search
Kong Gateway
3.1.x
github-edit-pageEdit this page
report-issueReport an issue
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

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

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

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:

  1. curl the example values.yaml file.

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

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

    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.

   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.

  1. Create the Kong namespace for Kong Gateway:

    kubectl create namespace kong

  2. 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_samesite":"off","cookie_secure":false}' \
    --from-literal=admin_gui_session_conf='{"storage":"kong","secret":"super_secret_salt_string","cookie_name":"admin_session","cookie_samesite":"off","cookie_secure":false}' \
    --from-literal=pg_host="enterprise-postgresql.kong.svc.cluster.local" \
    --from-literal=kong_admin_password=kong \
    --from-literal=password=kong

  3. Create a Kong Enterprise license secret:

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:

  1. Add the Jetstack Cert Manager Helm repository:

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

  2. Install Cert Manager:

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

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

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

  1. Add the Kong Helm repo:

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

  2. Install Kong:

    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:

    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:

    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:

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

  2. Install Kong:

    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:

    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:

    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:

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

  2. Install Kong:

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

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

    kubectl get po --namespace kong -w

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

  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:

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

Teardown

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

  1. Remove Kong

    helm uninstall --namespace kong quickstart

  2. Delete Kong secrets

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

  3. Remove Kong database PVC

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

  4. Remove Kong Helm chart repository

    helm repo remove kong

  5. Remove cert-manager

    helm uninstall --namespace cert-manager cert-manager

  6. Remove jetstack cert-manager Helm repository

    helm repo remove jetstack

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

  1. Remove Kong

    helm uninstall --namespace kong quickstart

  2. Delete Kong secrets

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

  3. Remove Kong database PVC

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

  4. Remove Kong Helm chart repository

    helm repo remove kong

  5. Remove cert-manager

    helm uninstall --namespace cert-manager cert-manager

  6. Remove jetstack cert-manager Helm repository

    helm repo remove jetstack

  7. Destroy the Kind cluster

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

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

  1. Remove Kong

    helm uninstall --namespace kong quickstart

  2. Delete Kong secrets

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

  3. Remove Kong database PVC

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

  4. Remove Kong Helm chart repository

    helm repo remove kong

  5. Remove cert-manager

    helm uninstall --namespace cert-manager cert-manager

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