Skip to content
Kong Logo | Kong Docs Logo
search
  • Docs
    • Explore the API Specs
      View all API Specs View all API Specs View all API Specs arrow image
    • Documentation
      API Specs
      Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Gateway
3.3.x
  • Home icon
  • Kong Gateway
  • Install
  • Kubernetes
  • Install with Kong Gateway using Helm
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.5.x (latest)
  • 3.4.x
  • 3.3.x
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Archive (pre-2.6)
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Docker Desktop
  • Dependencies
  • Configure Kubectl
  • Kind Kubernetes
  • Dependencies
  • Create Kubernetes Cluster
  • Kubernetes in the cloud
  • Dependencies
  • Configure Kubectl
  • Prepare the Helm chart
  • Create Kong Gateway secrets
  • Install Cert Manager
  • Deploy Kong Gateway
  • Use Kong Gateway
  • Teardown
  • Next Steps
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

  • Helm 3
  • kubectl v1.19 or later
  • Docker Desktop Kubernetes

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:

  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.

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.

  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_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
    
  3. Create a Kong Gateway Enterprise license secret:

Kong Gateway Enterprise Free Mode
Kong Gateway 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:

  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

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:

    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

Docker Desktop Kubernetes
Kind Kubernetes
Kubernetes in the Cloud

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.

Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    Powering the API world

    Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller.

    • Products
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • Product Updates
      • Get Started
    • Documentation
      • Kong Konnect Docs
      • Kong Gateway Docs
      • Kong Gateway Enterprise Docs
      • Kong Mesh Docs
      • Kong Insomnia Docs
      • Kong Konnect Plugin Hub
    • Open Source
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kong Community
    • Company
      • About Kong
      • Customers
      • Careers
      • Press
      • Events
      • Contact
  • Terms• Privacy• Trust and Compliance
© Kong Inc. 2023