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

Install Kong Gateway

This guide explains how to deploy Kong Gateway on Kubernetes without using Kong Konnect or Kong Ingress Controller.

Kong Konnect is recommended for new installations to reduce deployment complexity.
Let Kong run the control plane and database for you. With Kong Konnect, you only need to run the data planes. Get started in under 5 minutes.

These instructions configure Kong Gateway to use separate control plane and data plane deployments. This is the recommended production installation method.

Prerequisites

Helm 3
kubectl v1.19 or later
A running PostgreSQL database

Helm Setup

Kong provides a Helm chart for deploying Kong Gateway. Add the charts.konghq.com repository and run helm repo update to ensure that you have the latest version of the chart.

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

Secrets

Kong Gateway Enterprise License

First, create the kong namespace:

kubectl create namespace kong

Next, 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

Clustering Certificates

Kong Gateway uses mTLS to secure the control plane/data plane communication when running in hybrid mode.

Generate a TLS certificate using OpenSSL.

 openssl req -new -x509 -nodes -newkey ec:<(openssl ecparam -name secp384r1) -keyout ./tls.key -out ./tls.crt -days 1095 -subj "/CN=kong_clustering"

Create a Kubernetes secret containing the certificate.

 kubectl create secret tls kong-cluster-cert --cert=./tls.crt --key=./tls.key -n kong

Installation

Control Plane

The control plane contains all Kong Gateway configurations. The configuration is stored in a PostgreSQL database.

Create a values-cp.yaml file.

      Kong Gateway
    

      Kong Gateway (OSS)
    
# Do not use Kong Ingress Controller
ingressController:
  enabled: false
   
image:
  repository: kong/kong-gateway
  tag: "3.6.1.8"
   
# Mount the secret created earlier
secretVolumes:
  - kong-cluster-cert
   
env:
  # This is a control_plane node
  role: control_plane
  # These certificates are used for control plane / data plane communication
  cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
  cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
   
  # Database
  # CHANGE THESE VALUES
  database: postgres
  pg_database: kong
  pg_user: kong
  pg_password: demo123
  pg_host: kong-cp-postgresql.kong.svc.cluster.local
  pg_ssl: "on"
   
  # Kong Manager password
  password: kong_admin_password
   
# Enterprise functionality
enterprise:
  enabled: true
  license_secret: kong-enterprise-license
   
# The control plane serves the Admin API
admin:
  enabled: true
  http:
    enabled: true
   
# Clustering endpoints are required in hybrid mode
cluster:
  enabled: true
  tls:
    enabled: true
   
clustertelemetry:
  enabled: true
  tls:
    enabled: true
   
# Optional features
manager:
  enabled: false
   
# These roles will be served by different Helm releases
proxy:
  enabled: false
# Do not use Kong Ingress Controller
ingressController:
  enabled: false
   
image:
  repository: kong
  tag: "3.6.1"
   
# Mount the secret created earlier
secretVolumes:
  - kong-cluster-cert
   
env:
  # This is a control_plane node
  role: control_plane
  # These certificates are used for control plane / data plane communication
  cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
  cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
   
  # Database
  # CHANGE THESE VALUES
  database: postgres
  pg_database: kong
  pg_user: kong
  pg_password: demo123
  pg_host: kong-cp-postgresql.kong.svc.cluster.local
  pg_ssl: "on"
   
  # Kong Manager password
  password: kong_admin_password
   
# Enterprise functionality
enterprise:
  enabled: false
  license_secret: kong-enterprise-license
   
# The control plane serves the Admin API
admin:
  enabled: true
  http:
    enabled: true
   
# Clustering endpoints are required in hybrid mode
cluster:
  enabled: true
  tls:
    enabled: true
   
clustertelemetry:
  enabled: true
  tls:
    enabled: true
   
# Optional features
manager:
  enabled: false
   
# These roles will be served by different Helm releases
proxy:
  enabled: false

(Optional) If you want to deploy a Postgres database within the cluster for testing purposes, add the following to the bottom of values-cp.yaml.

 # This is for testing purposes only
 # DO NOT DO THIS IN PRODUCTION
 # Your cluster needs a way to create PersistentVolumeClaims
 # if this option is enabled
 postgresql:
   enabled: true
   auth:
     password: demo123

Update the database connection values in values-cp.yaml.
- env.pg_database: The database name to use
- env.pg_user: Your database username
- env.pg_password: Your database password
- env.pg_host: The hostname of your Postgres database
- env.pg_ssl: Use SSL to connect to the database
Set your Kong Manager super admin password in values-cp.yaml.
- env.password: The Kong Manager super admin password

Run helm install to create the release.

 helm install kong-cp kong/kong -n kong --values ./values-cp.yaml

Run kubectl get pods -n kong. Ensure that the control plane is running as expected.

 NAME                                 READY   STATUS
 kong-cp-kong-7bb77dfdf9-x28xf        1/1     Running

Data Plane

The Kong Gateway data plane is responsible for processing incoming traffic. It receives the routing configuration from the control plane using the clustering endpoint.

Create a values-dp.yaml file.

      Kong Gateway
    

      Kong Gateway (OSS)
    
# Do not use Kong Ingress Controller
ingressController:
  enabled: false
   
image:
  repository: kong/kong-gateway
  tag: "3.6.1.8"
   
# Mount the secret created earlier
secretVolumes:
  - kong-cluster-cert
   
env:
  # data_plane nodes do not have a database
  role: data_plane
  database: "off"
   
  # Tell the data plane how to connect to the control plane
  cluster_control_plane: kong-cp-kong-cluster.kong.svc.cluster.local:8005
  cluster_telemetry_endpoint: kong-cp-kong-clustertelemetry.kong.svc.cluster.local:8006
   
  # Configure control plane / data plane authentication
  lua_ssl_trusted_certificate: /etc/secrets/kong-cluster-cert/tls.crt
  cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
  cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
   
# Enterprise functionality
enterprise:
  enabled: true
  license_secret: kong-enterprise-license
   
# The data plane handles proxy traffic only
proxy:
  enabled: true
   
# These roles are served by the kong-cp deployment
admin:
  enabled: false
   
manager:
  enabled: false
# Do not use Kong Ingress Controller
ingressController:
  enabled: false
   
image:
  repository: kong
  tag: "3.6.1"
   
# Mount the secret created earlier
secretVolumes:
  - kong-cluster-cert
   
env:
  # data_plane nodes do not have a database
  role: data_plane
  database: "off"
   
  # Tell the data plane how to connect to the control plane
  cluster_control_plane: kong-cp-kong-cluster.kong.svc.cluster.local:8005
  cluster_telemetry_endpoint: kong-cp-kong-clustertelemetry.kong.svc.cluster.local:8006
   
  # Configure control plane / data plane authentication
  lua_ssl_trusted_certificate: /etc/secrets/kong-cluster-cert/tls.crt
  cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
  cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
   
# Enterprise functionality
enterprise:
  enabled: false
  license_secret: kong-enterprise-license
   
# The data plane handles proxy traffic only
proxy:
  enabled: true
   
# These roles are served by the kong-cp deployment
admin:
  enabled: false
   
manager:
  enabled: false

Run helm install to create the release.

helm install kong-dp kong/kong -n kong --values ./values-dp.yaml

Run kubectl get pods -n kong. Ensure that the data plane is running as expected.

 NAME                                 READY   STATUS
 kong-dp-kong-5dbcd9f6b9-f2w49        1/1     Running

Testing

Kong Gateway is now running. To send some test traffic, try the following:

Fetch the LoadBalancer address for the kong-dp service and store it in the PROXY_IP environment variable

 PROXY_IP=$(kubectl get service --namespace kong kong-dp-kong-proxy -o jsonpath='{range .status.loadBalancer.ingress[0]}{@.ip}{@.hostname}{end}')

Make a HTTP request to your $PROXY_IP. This will return a HTTP 404 served by Kong Gateway
```
 curl $PROXY_IP/mock/anything
```
In another terminal, run kubectl port-forward to set up port forwarding and access the admin API.
```
 kubectl port-forward -n kong service/kong-cp-kong-admin 8001
```

Create a mock service and route

 curl localhost:8001/services -d name=mock  -d url="https://httpbin.konghq.com"
 curl localhost:8001/services/mock/routes -d "paths=/mock"

Make a HTTP request to your $PROXY_IP again. This time Kong Gateway will route the request to httpbin.
```
 curl $PROXY_IP/mock/anything
```

Previous Overview

Next Configure the Admin API