Kong Gateway Enterprise [ARCHIVE]

2.1.x

Kong Konnect Platform
Kong Gateway
Deployment
Installation

PermalinkInstalling Kong Enterprise on Kubernetes

PermalinkIntroduction

Kong Enterprise on Kubernetes supports all Kong 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 Enterprise on Kubernetes

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

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 Kong 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.
You have signed up for a paid Enterprise subscription and received a license.json file from Kong.

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 Kong Enterprise license

Running Kong Enterprise on Kubernetes requires a valid license. See prerequisites for more information.

Save the license file temporarily to disk with filename license (no file extension) and execute the following:

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

kubectl

OpenShift oc

(Optional) Create a password for the super admin:

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

(Optional) Create a password for the super admin:

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

Create a sessions config file for Kong Dev Portal:

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

 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

Create a sessions config file for Kong Dev Portal:

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

 $ 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 Enterprise values.yaml file. For example, this values file enables most Kong Enterprise features.

Minimally, for setting up Kong Enterprise 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.1.4.6-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 Enterprise parameters for more details.

PermalinkStep 7. Deploy Kong Enterprise on Kubernetes

The steps in this section show you how to install Kong Enterprise 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 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.

Important: If you have already installed the CRDs, run the command above with the following flag: --set ingressController.installCRDs=false.
Check pod status:
```
 $ kubectl get pods -n kong
```
After migrations are complete and the my-kong-kong-<ID> pod is running, continue to the next section.

Run:

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

This may take some time.

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 -n kong my-kong-kong-admin --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}'

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.