Kong Gateway Enterprise [ARCHIVE]

2.4.x

Kong Konnect Platform
Kong Gateway
Deployment
Installation

PermalinkInstalling Kong Gateway (Enterprise) on Kubernetes

PermalinkIntroduction

Kong Gateway on Kubernetes supports all Enterprise plugins and features.

This installation topic walks you through a database-backed deployment on Kubernetes. For a basic DB-less deployment with the Kong Ingress Controller, see Installing Kong for Kubernetes Enterprise.

Note: See Kong for Kubernetes deployment options for a feature breakdown and comparison between DB-less and database-backed deployments.

Kong Gateway on Kubernetes

You can use kubectl or OpenShift oc to configure Kong Gateway on Kubernetes, then deploy it using Helm.

This software is governed by the Kong Software License Agreement.

PermalinkDeployment options

The following instructions assume that you are deploying Kong Gateway in classic embedded mode.

If you would like to run Kong Gateway in Hybrid mode, the instructions in this topic will walk you though setting up a Control Plane instance. Afterward, you will need to bring up additional gateway instances for the Data Planes, and perform further configuration steps. See Hybrid Mode setup documentation for details.

PermalinkPrerequisites

Before starting installation, be sure you have the following:

Kubernetes cluster with load balancer: Kong is compatible with all distributions of Kubernetes. You can use a Minikube, GKE, or OpenShift cluster.
kubectl or oc access: You should have kubectl or oc (if working with OpenShift) installed and configured to communicate to your Kubernetes cluster.
Helm installed.
Enterprise users only: You have received a license.json file from your sales representative.

PermalinkStep 1. Provision a namespace

To create the license secret, first provision the kong namespace:

      kubectl
    
      OpenShift oc
    
$ kubectl create namespace kong
$ oc new-project kong

PermalinkStep 2. Set up license secret

Free mode

Enterprise license

Create a dummy license file:

$ echo '{ }' > license

If you plan on using a license to unlock Enterprise features, see prerequisites for more information.

Save the license file temporarily to disk with filename license (no file extension).

Run the following command:

      kubectl
    
      OpenShift oc
    
$ kubectl create secret generic kong-enterprise-license -n kong --from-file=./license
$ oc create secret generic kong-enterprise-license -n kong --from-file=./license

Note:

There is no .json extension in the --from-file parameter.
-n kong specifies the namespace in which you are deploying Kong for Kubernetes Enterprise. If you are deploying in a different namespace, change this value.

PermalinkStep 3. Set up Helm

Add the Kong charts repository:

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

Update Helm:
```
 $ helm repo update
```

PermalinkStep 4. Seed the Super Admin password

(Optional) Create a password for the super admin:

      kubectl
    

      OpenShift oc
    
$ kubectl create secret generic kong-enterprise-superuser-password \
  -n kong \
  --from-literal=password=<your-password>
$ oc create secret generic kong-enterprise-superuser-password \
  -n kong \
  --from-literal=password=<your-password>

Important:Though not required, this is recommended if you want to use RBAC, as it cannot be done after initial setup.

PermalinkStep 5. Prepare the sessions plugin for Kong Manager and Dev Portal

In the following steps, replace <your-password> with a secure password.

kubectl

OpenShift oc

Create a sessions config file for Kong Manager:

 $ echo '{"cookie_name":"admin_session","cookie_samesite":"off","secret":"<your-password>","cookie_secure":false,"storage":"kong"}' > admin_gui_session_conf

(Optional, only with a license) Create a sessions config file for Kong Dev Portal:

This feature is only available with a Kong Konnect Enterprise subscription.

 $ echo '{"cookie_name":"portal_session","cookie_samesite":"off","secret":"<your-password>","cookie_secure":false,"storage":"kong"}' > portal_session_conf

Or, if you have different subdomains for the portal_api_url and portal_gui_host, set the cookie_domain and cookie_samesite properties as follows:

 $ echo '{"cookie_name":"portal_session","cookie_samesite":"off","cookie_domain":"<.your_subdomain.com>","secret":"<your-password>","cookie_secure":false,"storage":"kong"}' > portal_session_conf

Create the secret.

With Kong Manager only:

 $ kubectl create secret generic kong-session-config \
   -n kong \
   --from-file=admin_gui_session_conf

With Kong Manager and Dev Portal:

 $ kubectl create secret generic kong-session-config \
   -n kong \
   --from-file=admin_gui_session_conf \
   --from-file=portal_session_conf

Create a sessions config file for Kong Manager:

 $ echo '{"cookie_name":"admin_session","cookie_samesite":"off","secret":"<your-password>","cookie_secure":false,"storage":"kong"}' > admin_gui_session_conf

(Optional, only with a license) Create a sessions config file for Kong Dev Portal:

This feature is only available with a Kong Konnect Enterprise subscription.

 $ echo '{"cookie_name":"portal_session","cookie_samesite":"off","secret":"<your-password>","cookie_secure":false,"storage":"kong"}' > portal_session_conf

Or, if you have different subdomains for the portal_api_url and portal_gui_host, set the cookie_domain and cookie_samesite properties as follows:

 $ echo '{"cookie_name":"portal_session","cookie_samesite":"off","cookie_domain":"<.your_subdomain.com>","secret":"<your-password>","cookie_secure":false,"storage":"kong"}' > portal_session_conf

Create the secret.

With Kong Manager only:

 $ oc create secret generic kong-session-config \
   -n kong \
   --from-file=admin_gui_session_conf

With Kong Manager and Dev Portal:

 $ oc create secret generic kong-session-config \
   -n kong \
   --from-file=admin_gui_session_conf \
   --from-file=portal_session_conf

PermalinkStep 6. Prepare Kong’s configuration file

Create a values.yaml file for Helm based on the template in the Kong charts repository. This file contains all the possible parameters for your Kong deployment.

You can also base your configuration on a sample Kong Gateway values.yaml file. For example, this values file enables most Enterprise features.

Minimally, for setting up Kong Gateway on Kubernetes, you will need to set the following parameters:

Parameter	Value
`enterprise.enabled`	`true`
`enterprise.portal.enabled`	(Optional) Set to `true` to enable the Kong Developer Portal.
`enterprise.rbac.enabled`	(Optional) Set to `true` to enable RBAC. Requires seeding the super admin password; see above.
`env.database`	`"postgres"` or `"cassandra"`
`env.pg_host`	(If using Postgres) Set to host of the Postgres server (only if `postgresql.enabled` is `false`).
`env.pg_port`	(If using Postgres) Set to port of the Postgres server (only if `postgresql.enabled` is `false`).
`env.pg_user`	(If using Postgres) Set to the Postgres user (default `kong`). When `postgresql.enabled` is `true`, this has to match `postgresql.postgresqlUsername`.
`env.pg_password`	(If using Postgres) Set to the Postgres user’s password. When `postgresql.enabled` is `true`, this has to match `postgresql.postgresqlPassword`.
`env.pg_database`	(If using Postgres) Set to the Postgres database name (default `kong`). When `postgresql.enabled` is `true`, this has to match `postgresql.postgresqlDatabase`.
`env.password.valueFrom.secretKeyRef.name`	Name of secret that holds the super admin password. In the example above, this is set to `kong-enterprise-superuser-password`.
`env.password.valueFrom.secretKeyRef.key`	The type of secret key used for authentication. If you followed the default settings in the example above, this is `password`.
`image.repository`	The Docker repository. In this case, `kong/kong-gateway`.
`image.tag`	The Docker image tag you want to pull down, e.g. `"2.4.1.0-alpine"`.
`admin.enabled`	Set to `true` to enable the Admin API, which is required for the Kong Manager.
`ingressController.enabled`	Set to `true` if you want to use the Kong Ingress Controller, or `false` if you don’t want to install it.
`postgresql.enabled`	Set to `true` to deploy a Postgres database along with Kong.
`postgresql.postgresqlUsername`	Set Postgres user (e.g. `kong`).
`postgresql.postgresqlPassword`	Set Postgres user’s password.
`postgresql.postgresqlDatabase`	Set Postgres database name (e.g. `kong`).

In the Kong Enterprise section, enable Kong Manager (manager) and Kong Dev Portal (portal).

For example:

 manager:
   enabled: true
   type: LoadBalancer
   http:
     enabled: true
     servicePort: 8002
   tls:
     enabled: true
     servicePort: 8445

 portal:
   enabled: true
   type: LoadBalancer
   http:
     enabled: true
     servicePort: 8003
   tls:
     enabled: true
     servicePort: 8446

Fill in the rest of the parameters as appropriate for your implementation. Use the comments in the sample file to guide you, and see the documentation on Kong Gateway parameters for more details.

PermalinkStep 7. Deploy Kong Gateway on Kubernetes

The steps in this section show you how to install Kong Gateway on Kubernetes using Helm.

Note: The following instructions assume that you're running Helm 3.

kubectl

OpenShift oc

Run:
```
 $ helm install my-kong kong/kong -n kong --values ./values.yaml
```
This may take some time.
Important:
- If you have already installed the CRDs, run the command above with the following flag: --set ingressController.installCRDs=false.
- If you are running Postgres as a sub-chart and having problems with connecting to the database, delete Postgres' persistent volumes in your Kubernetes cluster, then retry the Helm install.
Check pod status:
```
 $ kubectl get pods -n kong
```

Run:
```
 $ helm install my-kong kong/kong -n kong --values ./values.yaml
```
This may take some time.
Important:
- If you have already installed the CRDs, run the command above with the following flag: --set ingressController.installCRDs=false.
- If you are running Postgres as a sub-chart and having problems with connecting to the database, delete Postgres' persistent volumes in your Kubernetes cluster, then retry the Helm install.
Check pod status:
```
 $ oc get pods -n kong
```

After migrations are complete and the my-kong-kong-<ID> pod is running, continue to the next section.

PermalinkStep 8. Finalize configuration and verify installation

kubectl

OpenShift oc

Run:
```
 $ kubectl get svc my-kong-kong-admin \
   -n kong \
   --output=jsonpath='{.status.loadBalancer.ingress[0].ip}'
```
Important: The command above requires the Kong Admin API. If you have not set admin.enabled to true in your values.yaml, then this command will not work.
Copy the IP address from the output, then edit the values.yaml file to add the following line under env section:

Note: Do not use IPs with RBAC. If you want to use RBAC, you need to set up a DNS hostname first, instead of directly specifying an IP.
```
 admin_api_uri: <your-DNSorIP>
```
Clean up:
```
 $ kubectl delete jobs -n kong --all
```

Update Kong to use the changed values.yaml:

 $ helm upgrade my-kong kong/kong -n kong --values ./values.yaml

After the upgrade is complete, run:

 $ kubectl get svc -n kong

In the output, the IP in the EXTERNAL_IP column is your access point for Kong features, including Kong Manager and Kong Dev Portal:

 NAME                          TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)                            AGE
 my-kong-kong-manager          LoadBalancer   10.96.61.116     10.96.61.116    8002:31308/TCP,8445:32420/TCP      24m
 my-kong-kong-portal           LoadBalancer   10.101.251.123   10.101.251.123  8003:31609/TCP,8446:32002/TCP      24m

Run:
```
 $ oc get svc my-kong-kong-admin \
   -n kong \
   --output=jsonpath='{.status.loadBalancer.ingress[0].ip}'
```
Important: The command above requires the Kong Admin API. If you have not set admin.enabled to true in your values.yaml, then this command will not work.
Copy the IP address from the output, then edit the values.yaml file to add the following line under env section:

Note: Do not use IPs with RBAC. If you want to use RBAC, you need to set up a DNS hostname first, instead of directly specifying an IP.
```
 admin_api_uri: <your-DNSorIP>
```
Clean up:
```
 $ oc delete jobs -n kong --all
```

Update Kong to use the changed values.yaml:

 $ helm upgrade my-kong kong/kong -n kong --values ./values.yaml

After the upgrade is complete, run:

 $ oc get svc -n kong

In the output, the IP in the EXTERNAL_IP column is your access point for Kong features, including Kong Manager and Kong Dev Portal:

 NAME                          TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)                            AGE
 my-kong-kong-manager          LoadBalancer   10.96.61.116     10.96.61.116    8002:31308/TCP,8445:32420/TCP      24m
 my-kong-kong-portal           LoadBalancer   10.101.251.123   10.101.251.123  8003:31609/TCP,8446:32002/TCP      24m

PermalinkNext steps

See Using Kong for Kubernetes Enterprise for information about concepts, how-to guides, reference guides, and using plugins.