Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.2.x (latest)
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Older Enterprise versions (2.1-2.5)
  • Older OSS versions (2.1-2.5)
  • Archive (pre-2.1)
    • Overview of Kong Gateway
      • Version Support Policy
      • Supported Installation Options
      • Supported Linux Distributions
    • Stability
    • Release Notes
      • Services
        • Overview
        • Configure Routes with Expressions
      • Upstreams
      • Plugins
      • Routing Traffic
      • Load Balancing
      • Health Checks and Circuit Breakers
      • Kong Performance Testing
    • Glossary
    • Get Kong
    • Services and Routes
    • Rate Limiting
    • Proxy Caching
    • Key Authentication
    • Load-Balancing
      • Overview
        • Overview
        • Deploy Kong Gateway in Hybrid mode
      • DB-less Deployment
      • Traditional
      • Overview
        • Helm
        • OpenShift with Helm
        • kubectl apply
        • Kubernetes Deployment Options
        • Using docker run
        • Build your own Docker images
        • Amazon Linux
        • Debian
        • Red Hat
        • Ubuntu
      • Running Kong as a non-root user
      • Securing the Admin API
      • Using systemd
      • Start Kong Gateway Securely
      • Programatically Creating Admins
      • Enabling RBAC
      • Overview
      • Download your License
      • Deploy Enterprise License
      • Using the License API
      • Monitor Licenses Usage
      • Default Ports
      • DNS Considerations
      • Network and Firewall
      • CP/DP Communication through a Forward Proxy
    • Kong Configuration File
    • Environment Variables
    • Serving a Website and APIs from Kong
      • Overview
      • Prometheus
      • StatsD
      • Datadog
      • Overview
      • Writing a Custom Trace Exporter
      • Tracing API Reference
    • Resource Sizing Guidelines
    • Security Update Process
    • Blue-Green Deployments
    • Canary Deployments
    • Clustering Reference
      • Log Reference
      • Dynamic log level updates
      • Customize Gateway Logs
      • Upgrade Kong Gateway 3.1.x
      • Migrate from OSS to Enterprise
    • Overview
      • Overview
      • Metrics
      • Analytics with InfluxDB
      • Analytics with Prometheus
      • Estimate Analytics Storage in PostgreSQL
      • Overview
      • Getting Started
      • Advanced Usage
        • Overview
        • Environment Variables
        • AWS Secrets Manager
        • Google Secrets Manager
        • Hashicorp Vault
        • Securing the Database with AWS Secrets Manager
      • Reference Format
      • Overview
      • Get Started with Dynamic Plugin Ordering
      • Overview
      • Enable the Dev Portal
      • Publish an OpenAPI Spec
      • Structure and File Types
      • Themes Files
      • Working with Templates
      • Using the Editor
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
        • Manage Developers
        • Developer Roles and Content Permissions
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
          • External OAuth2 Support
          • Set up Okta and Kong for External Oauth
          • Set up Azure AD and Kong for External Authentication
        • Manage Applications
        • Theme Editing
        • Migrating Templates Between Workspaces
        • Markdown Rendering Module
        • Customizing Portal Emails
        • Adding and Using JavaScript Assets
        • Single Page App in Dev Portal
        • Alternate OpenAPI Renderer
      • SMTP
      • Workspaces
      • Helpers CLI
      • Portal API Documentation
    • Audit Logging
    • Keyring and Data Encryption
    • Workspaces
    • Consumer Groups
    • Event Hooks
    • FIPS 140-2
    • Overview
    • Enable Kong Manager
      • Services and Routes
      • Rate Limiting
      • Proxy Caching
      • Authentication with Consumers
      • Load Balancing
      • Overview
      • Create a Super Admin
      • Workspaces and Teams
      • Reset Passwords and RBAC Tokens
      • Basic Auth
        • Configure LDAP
        • LDAP Service Directory Mapping
        • Configure OIDC
        • OIDC Authenticated Group Mapping
      • Sessions
        • Overview
        • Enable RBAC
        • Add a Role and Permissions
        • Create a User
        • Create an Admin
    • Networking Configuration
    • Workspaces
    • Create Consumer Groups
    • Sending Email
    • Overview
    • File Structure
    • Implementing Custom Logic
    • Plugin Configuration
    • Accessing the Data Store
    • Storing Custom Entities
    • Caching Custom Entities
    • Extending the Admin API
    • Writing Tests
    • (un)Installing your Plugin
      • Overview
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.jwe
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.tracing
      • kong.vault
      • kong.websocket.client
      • kong.websocket.upstream
      • Go
      • Javascript
      • Python
      • Running Plugins in Containers
      • External Plugin Performance
    • Overview
        • Overview
        • OpenID Connect with Curity
        • OpenID Connect with Azure AD
        • OpenID Connect with Google
        • OpenID Connect with Okta
        • OpenID Connect with Auth0
        • OpenID Connect with Cognito
      • Authentication Reference
      • Allow Multiple Authentication Plugins
    • Rate Limiting Plugin
      • Add a Body Value
    • GraphQL
      • gRPC Plugins
      • Configure a gRPC service
    • Overview
    • Information Routes
    • Health Routes
    • Tags
    • Debug Routes
    • Services
    • Routes
    • Consumers
    • Plugins
    • Certificates
    • CA Certificates
    • SNIs
    • Upstreams
    • Targets
    • Vaults
    • Keys
    • Licenses
    • Workspaces
    • RBAC
    • Admins
    • Developers
    • Consumer Groups
    • Event Hooks
    • Keyring and Data Encryption
    • Audit Logs
    • kong.conf
    • Injecting Nginx Directives
    • CLI
    • File Permissions Reference
    • Key Management
    • Performance Testing Framework
    • Router Expressions Language
    • FAQ

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On 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
Kong Gateway
3.1.x
  • Home
  • Kong Gateway
  • Install
  • Kubernetes
  • Install with Kong Gateway using Helm
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_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:

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:

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

  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?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023