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
    4. image:
    5. repository: kong/kong-gateway
    6. tag: "3.8.0.0"
    7. # Mount the secret created earlier
    8. secretVolumes:
    9. - kong-cluster-cert
    10. env:
    11. # This is a control_plane node
    12. role: control_plane
    13. # These certificates are used for control plane / data plane communication
    14. cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
    15. cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
    16. # Database
    17. # CHANGE THESE VALUES
    18. database: postgres
    19. pg_database: kong
    20. pg_user: kong
    21. pg_password: demo123
    22. pg_host: kong-cp-postgresql.kong.svc.cluster.local
    23. pg_ssl: "on"
    24. # Kong Manager password
    25. password: kong_admin_password
    26. # Enterprise functionality
    27. enterprise:
    28. enabled: true
    29. license_secret: kong-enterprise-license
    30. # The control plane serves the Admin API
    31. admin:
    32. enabled: true
    33. http:
    34. enabled: true
    35. # Clustering endpoints are required in hybrid mode
    36. cluster:
    37. enabled: true
    38. tls:
    39. enabled: true
    40. clustertelemetry:
    41. enabled: true
    42. tls:
    43. enabled: true
    44. # Optional features
    45. manager:
    46. enabled: false
    47. # These roles will be served by different Helm releases
    48. proxy:
    49. enabled: false
    1. # Do not use Kong Ingress Controller
    2. ingressController:
    3. enabled: false
    4. image:
    5. repository: kong
    6. tag: "3.8.0"
    7. # Mount the secret created earlier
    8. secretVolumes:
    9. - kong-cluster-cert
    10. env:
    11. # This is a control_plane node
    12. role: control_plane
    13. # These certificates are used for control plane / data plane communication
    14. cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
    15. cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
    16. # Database
    17. # CHANGE THESE VALUES
    18. database: postgres
    19. pg_database: kong
    20. pg_user: kong
    21. pg_password: demo123
    22. pg_host: kong-cp-postgresql.kong.svc.cluster.local
    23. pg_ssl: "on"
    24. # Kong Manager password
    25. password: kong_admin_password
    26. # Enterprise functionality
    27. enterprise:
    28. enabled: false
    29. license_secret: kong-enterprise-license
    30. # The control plane serves the Admin API
    31. admin:
    32. enabled: true
    33. http:
    34. enabled: true
    35. # Clustering endpoints are required in hybrid mode
    36. cluster:
    37. enabled: true
    38. tls:
    39. enabled: true
    40. clustertelemetry:
    41. enabled: true
    42. tls:
    43. enabled: true
    44. # Optional features
    45. manager:
    46. enabled: false
    47. # These roles will be served by different Helm releases
    48. proxy:
    49. 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
    4. image:
    5. repository: kong/kong-gateway
    6. tag: "3.8.0.0"
    7. # Mount the secret created earlier
    8. secretVolumes:
    9. - kong-cluster-cert
    10. env:
    11. # data_plane nodes do not have a database
    12. role: data_plane
    13. database: "off"
    14. # Tell the data plane how to connect to the control plane
    15. cluster_control_plane: kong-cp-kong-cluster.kong.svc.cluster.local:8005
    16. cluster_telemetry_endpoint: kong-cp-kong-clustertelemetry.kong.svc.cluster.local:8006
    17. # Configure control plane / data plane authentication
    18. lua_ssl_trusted_certificate: /etc/secrets/kong-cluster-cert/tls.crt
    19. cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
    20. cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
    21. # Enterprise functionality
    22. enterprise:
    23. enabled: true
    24. license_secret: kong-enterprise-license
    25. # The data plane handles proxy traffic only
    26. proxy:
    27. enabled: true
    28. # These roles are served by the kong-cp deployment
    29. admin:
    30. enabled: false
    31. manager:
    32. enabled: false
    1. # Do not use Kong Ingress Controller
    2. ingressController:
    3. enabled: false
    4. image:
    5. repository: kong
    6. tag: "3.8.0"
    7. # Mount the secret created earlier
    8. secretVolumes:
    9. - kong-cluster-cert
    10. env:
    11. # data_plane nodes do not have a database
    12. role: data_plane
    13. database: "off"
    14. # Tell the data plane how to connect to the control plane
    15. cluster_control_plane: kong-cp-kong-cluster.kong.svc.cluster.local:8005
    16. cluster_telemetry_endpoint: kong-cp-kong-clustertelemetry.kong.svc.cluster.local:8006
    17. # Configure control plane / data plane authentication
    18. lua_ssl_trusted_certificate: /etc/secrets/kong-cluster-cert/tls.crt
    19. cluster_cert: /etc/secrets/kong-cluster-cert/tls.crt
    20. cluster_cert_key: /etc/secrets/kong-cluster-cert/tls.key
    21. # Enterprise functionality
    22. enterprise:
    23. enabled: false
    24. license_secret: kong-enterprise-license
    25. # The data plane handles proxy traffic only
    26. proxy:
    27. enabled: true
    28. # These roles are served by the kong-cp deployment
    29. admin:
    30. enabled: false
    31. manager:
    32. 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