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

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

Secrets

Kong Gateway Enterprise License

First, create the kong namespace:

  1. kubectl create namespace kong

Next, create a Kong Gateway Enterprise license secret:

Kong Gateway Enterprise Free Mode

Kong Gateway Enterprise Licensed Mode

  1. kubectl create secret generic kong-enterprise-license --from-literal=license="'{}'" -n kong

Ensure you are in the directory that contains a license.json file before running this command.

  1. kubectl create secret generic kong-enterprise-license --from-file=license=license.json -n kong

Clustering Certificates

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

  1. Generate a TLS certificate using OpenSSL.

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

  2. Create a Kubernetes secret containing the certificate.

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

  1. Create a values-cp.yaml file.

    Kong Gateway

    Kong Gateway (OSS)

    1. # Do not use Kong Ingress Controller
    2. ingressController:
    3.   enabled: false
    5. image:
    6.   repository: kong/kong-gateway
    7.   tag: "3.7.1.2"
    9. # Mount the secret created earlier
    10. secretVolumes:
    11.   - kong-cluster-cert
    13. env:
    14.   # This is a control_plane node
    15.   role: control_plane
    16.   # These certificates are used for control plane / data plane communication
    17.   cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
    18.   cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
    20.   # Database
    21.   # CHANGE THESE VALUES
    22.   database: postgres
    23.   pg_database: kong
    24.   pg_user: kong
    25.   pg_password: demo123
    26.   pg_host: kong-cp-postgresql.kong.svc.cluster.local
    27.   pg_ssl: "on"
    29.   # Kong Manager password
    30.   password: kong_admin_password
    32. # Enterprise functionality
    33. enterprise:
    34.   enabled: true
    35.   license_secret: kong-enterprise-license
    37. # The control plane serves the Admin API
    38. admin:
    39.   enabled: true
    40.   http:
    41.     enabled: true
    43. # Clustering endpoints are required in hybrid mode
    44. cluster:
    45.   enabled: true
    46.   tls:
    47.     enabled: true
    49. clustertelemetry:
    50.   enabled: true
    51.   tls:
    52.     enabled: true
    54. # Optional features
    55. manager:
    56.   enabled: false
    58. # These roles will be served by different Helm releases
    59. proxy:
    60.   enabled: false
    1. # Do not use Kong Ingress Controller
    2. ingressController:
    3.   enabled: false
    5. image:
    6.   repository: kong
    7.   tag: "3.7.1"
    9. # Mount the secret created earlier
    10. secretVolumes:
    11.   - kong-cluster-cert
    13. env:
    14.   # This is a control_plane node
    15.   role: control_plane
    16.   # These certificates are used for control plane / data plane communication
    17.   cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
    18.   cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
    20.   # Database
    21.   # CHANGE THESE VALUES
    22.   database: postgres
    23.   pg_database: kong
    24.   pg_user: kong
    25.   pg_password: demo123
    26.   pg_host: kong-cp-postgresql.kong.svc.cluster.local
    27.   pg_ssl: "on"
    29.   # Kong Manager password
    30.   password: kong_admin_password
    32. # Enterprise functionality
    33. enterprise:
    34.   enabled: false
    35.   license_secret: kong-enterprise-license
    37. # The control plane serves the Admin API
    38. admin:
    39.   enabled: true
    40.   http:
    41.     enabled: true
    43. # Clustering endpoints are required in hybrid mode
    44. cluster:
    45.   enabled: true
    46.   tls:
    47.     enabled: true
    49. clustertelemetry:
    50.   enabled: true
    51.   tls:
    52.     enabled: true
    54. # Optional features
    55. manager:
    56.   enabled: false
    58. # These roles will be served by different Helm releases
    59. proxy:
    60.   enabled: false

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

    1.  # This is for testing purposes only
    2.  # DO NOT DO THIS IN PRODUCTION
    3.  # Your cluster needs a way to create PersistentVolumeClaims
    4.  # if this option is enabled
    5.  postgresql:
    6.    enabled: true
    7.    auth:
    8.      password: demo123

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

  4. Set your Kong Manager super admin password in values-cp.yaml.

    • env.password: The Kong Manager super admin password

  5. Run helm install to create the release.

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

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

    1.  NAME                                 READY   STATUS
    2.  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.

  1. Create a values-dp.yaml file.

    Kong Gateway

    Kong Gateway (OSS)

    1. # Do not use Kong Ingress Controller
    2. ingressController:
    3.   enabled: false
    5. image:
    6.   repository: kong/kong-gateway
    7.   tag: "3.7.1.2"
    9. # Mount the secret created earlier
    10. secretVolumes:
    11.   - kong-cluster-cert
    13. env:
    14.   # data_plane nodes do not have a database
    15.   role: data_plane
    16.   database: "off"
    18.   # Tell the data plane how to connect to the control plane
    19.   cluster_control_plane: kong-cp-kong-cluster.kong.svc.cluster.local:8005
    20.   cluster_telemetry_endpoint: kong-cp-kong-clustertelemetry.kong.svc.cluster.local:8006
    22.   # Configure control plane / data plane authentication
    23.   lua_ssl_trusted_certificate: /etc/secrets/kong-cluster-cert/tls.crt
    24.   cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
    25.   cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
    27. # Enterprise functionality
    28. enterprise:
    29.   enabled: true
    30.   license_secret: kong-enterprise-license
    32. # The data plane handles proxy traffic only
    33. proxy:
    34.   enabled: true
    36. # These roles are served by the kong-cp deployment
    37. admin:
    38.   enabled: false
    40. manager:
    41.   enabled: false
    1. # Do not use Kong Ingress Controller
    2. ingressController:
    3.   enabled: false
    5. image:
    6.   repository: kong
    7.   tag: "3.7.1"
    9. # Mount the secret created earlier
    10. secretVolumes:
    11.   - kong-cluster-cert
    13. env:
    14.   # data_plane nodes do not have a database
    15.   role: data_plane
    16.   database: "off"
    18.   # Tell the data plane how to connect to the control plane
    19.   cluster_control_plane: kong-cp-kong-cluster.kong.svc.cluster.local:8005
    20.   cluster_telemetry_endpoint: kong-cp-kong-clustertelemetry.kong.svc.cluster.local:8006
    22.   # Configure control plane / data plane authentication
    23.   lua_ssl_trusted_certificate: /etc/secrets/kong-cluster-cert/tls.crt
    24.   cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
    25.   cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
    27. # Enterprise functionality
    28. enterprise:
    29.   enabled: false
    30.   license_secret: kong-enterprise-license
    32. # The data plane handles proxy traffic only
    33. proxy:
    34.   enabled: true
    36. # These roles are served by the kong-cp deployment
    37. admin:
    38.   enabled: false
    40. manager:
    41.   enabled: false

  2. Run helm install to create the release.

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

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

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

Testing

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

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

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

  2. Make a HTTP request to your $PROXY_IP. This will return a HTTP 404 served by Kong Gateway

    1.  curl $PROXY_IP/mock/anything

  3. In another terminal, run kubectl port-forward to set up port forwarding and access the admin API.

    1.  kubectl port-forward -n kong service/kong-cp-kong-admin 8001

  4. Create a mock service and route

    1.  curl localhost:8001/services -d name=mock  -d url="http://httpbin.org"
    2.  curl localhost:8001/services/mock/routes -d "paths=/mock"

  5. Make a HTTP request to your $PROXY_IP again. This time Kong Gateway will route the request to httpbin.

    1.  curl $PROXY_IP/mock/anything

Previous Overview

Next Configure the Admin API