3 [Kong](https://KongHQ.com/) is an open-source API Gateway and Microservices
4 Management Layer, delivering high performance and reliability.
9 $ helm install stable/kong
14 This chart bootstraps all the components needed to run Kong on a [Kubernetes](http://kubernetes.io)
15 cluster using the [Helm](https://helm.sh) package manager.
19 - Kubernetes 1.8+ with Beta APIs enabled.
20 - PV provisioner support in the underlying infrastructure if persistence
21 is needed for Kong datastore.
23 ## Installing the Chart
25 To install the chart with the release name `my-release`:
28 $ helm install --name my-release stable/kong
31 If using Kong Enterprise, several additional steps are necessary before
32 installing the chart. At minimum, you must:
33 * Create a [license secret](#license).
34 * Set `enterprise.enabled: true` in values.yaml.
35 * Update values.yaml to use a Kong Enterprise image. If needed, follow the
36 instructions in values.yaml to add a registry pull secret.
38 Reading through [the full list of Enterprise considerations](#kong-enterprise-specific-parameters)
41 > **Tip**: List all releases using `helm list`
43 ## Uninstalling the Chart
45 To uninstall/delete the `my-release` deployment:
48 $ helm delete my-release
51 The command removes all the Kubernetes components associated with the
52 chart and deletes the release.
56 ### General Configuration Parameters
58 The following table lists the configurable parameters of the Kong chart
59 and their default values.
61 | Parameter | Description | Default |
62 | ------------------------------ | -------------------------------------------------------------------------------- | ------------------- |
63 | image.repository | Kong image | `kong` |
64 | image.tag | Kong image version | `1.2` |
65 | image.pullPolicy | Image pull policy | `IfNotPresent` |
66 | image.pullSecrets | Image pull secrets | `null` |
67 | replicaCount | Kong instance count | `1` |
68 | admin.useTLS | Secure Admin traffic | `true` |
69 | admin.servicePort | TCP port on which the Kong admin service is exposed | `8444` |
70 | admin.containerPort | TCP port on which Kong app listens for admin traffic | `8444` |
71 | admin.nodePort | Node port when service type is `NodePort` | |
72 | admin.hostPort | Host port to use for admin traffic | |
73 | admin.type | k8s service type, Options: NodePort, ClusterIP, LoadBalancer | `NodePort` |
74 | admin.loadBalancerIP | Will reuse an existing ingress static IP for the admin service | `null` |
75 | admin.loadBalancerSourceRanges | Limit admin access to CIDRs if set and service type is `LoadBalancer` | `[]` |
76 | admin.ingress.enabled | Enable ingress resource creation (works with proxy.type=ClusterIP) | `false` |
77 | admin.ingress.tls | Name of secret resource, containing TLS secret | |
78 | admin.ingress.hosts | List of ingress hosts. | `[]` |
79 | admin.ingress.path | Ingress path. | `/` |
80 | admin.ingress.annotations | Ingress annotations. See documentation for your ingress controller for details | `{}` |
81 | proxy.http.enabled | Enables http on the proxy | true |
82 | proxy.http.servicePort | Service port to use for http | 80 |
83 | proxy.http.containerPort | Container port to use for http | 8000 |
84 | proxy.http.nodePort | Node port to use for http | 32080 |
85 | proxy.http.hostPort | Host port to use for http | |
86 | proxy.tls.enabled | Enables TLS on the proxy | true |
87 | proxy.tls.containerPort | Container port to use for TLS | 8443 |
88 | proxy.tls.servicePort | Service port to use for TLS | 8443 |
89 | proxy.tls.nodePort | Node port to use for TLS | 32443 |
90 | proxy.tls.hostPort | Host port to use for TLS | |
91 | proxy.type | k8s service type. Options: NodePort, ClusterIP, LoadBalancer | `NodePort` |
92 | proxy.loadBalancerSourceRanges | Limit proxy access to CIDRs if set and service type is `LoadBalancer` | `[]` |
93 | proxy.loadBalancerIP | To reuse an existing ingress static IP for the admin service | |
94 | proxy.externalIPs | IPs for which nodes in the cluster will also accept traffic for the proxy | `[]` |
95 | proxy.externalTrafficPolicy | k8s service's externalTrafficPolicy. Options: Cluster, Local | |
96 | proxy.ingress.enabled | Enable ingress resource creation (works with proxy.type=ClusterIP) | `false` |
97 | proxy.ingress.tls | Name of secret resource, containing TLS secret | |
98 | proxy.ingress.hosts | List of ingress hosts. | `[]` |
99 | proxy.ingress.path | Ingress path. | `/` |
100 | proxy.ingress.annotations | Ingress annotations. See documentation for your ingress controller for details | `{}` |
101 | env | Additional [Kong configurations](https://getkong.org/docs/latest/configuration/) | |
102 | runMigrations | Run Kong migrations job | `true` |
103 | readinessProbe | Kong readiness probe | |
104 | livenessProbe | Kong liveness probe | |
105 | affinity | Node/pod affinities | |
106 | nodeSelector | Node labels for pod assignment | `{}` |
107 | podAnnotations | Annotations to add to each pod | `{}` |
108 | resources | Pod resource requests & limits | `{}` |
109 | tolerations | List of node taints to tolerate | `[]` |
111 ### Admin/Proxy listener override
113 If you specify `env.admin_listen` or `env.proxy_listen`, this chart will use
114 the value provided by you as opposed to constructing a listen variable
115 from fields like `proxy.http.containerPort` and `proxy.http.enabled`. This allows
116 you to be more prescriptive when defining listen directives.
118 **Note:** Overriding `env.proxy_listen` and `env.admin_listen` will potentially cause
119 `admin.containerPort`, `proxy.http.containerPort` and `proxy.tls.containerPort` to become out of sync,
120 and therefore must be updated accordingly.
122 I.E. updatating to `env.proxy_listen: 0.0.0.0:4444, 0.0.0.0:4443 ssl` will need
123 `proxy.http.containerPort: 4444` and `proxy.tls.containerPort: 4443` to be set in order
124 for the service definition to work properly.
126 ### Kong-specific parameters
128 Kong has a choice of either Postgres or Cassandra as a backend datatstore.
129 This chart allows you to choose either of them with the `env.database`
130 parameter. Postgres is chosen by default.
132 Additionally, this chart allows you to use your own database or spin up a new
133 instance by using the `postgres.enabled` or `cassandra.enabled` parameters.
134 Enabling both will create both databases in your cluster, but only one
135 will be used by Kong based on the `env.database` parameter.
136 Postgres is enabled by default.
138 | Parameter | Description | Default |
139 | ------------------------------ | -------------------------------------------------------------------- | ------------------- |
140 | cassandra.enabled | Spin up a new cassandra cluster for Kong | `false` |
141 | postgresql.enabled | Spin up a new postgres instance for Kong | `true` |
142 | waitImage.repository | Image used to wait for database to become ready | `busybox` |
143 | waitImage.tag | Tag for image used to wait for database to become ready | `latest` |
144 | env.database | Choose either `postgres` or `cassandra` | `postgres` |
145 | env.pg_user | Postgres username | `kong` |
146 | env.pg_database | Postgres database name | `kong` |
147 | env.pg_password | Postgres database password (required if you are using your own database)| `kong` |
148 | env.pg_host | Postgres database host (required if you are using your own database) | `` |
149 | env.pg_port | Postgres database port | `5432` |
150 | env.cassandra_contact_points | Cassandra contact points (required if you are using your own database) | `` |
151 | env.cassandra_port | Cassandra query port | `9042` |
152 | env.cassandra_keyspace | Cassandra keyspace | `kong` |
153 | env.cassandra_repl_factor | Replication factor for the Kong keyspace | `2` |
156 All `kong.env` parameters can also accept a mapping instead of a value to ensure the parameters can be set through configmaps and secrets.
172 For complete list of Kong configurations please check https://getkong.org/docs/latest/configuration/.
174 Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example,
177 $ helm install stable/kong --name my-release \
178 --set=image.tag=1.2,env.database=cassandra,cassandra.enabled=true
181 Alternatively, a YAML file that specifies the values for the above parameters
182 can be provided while installing the chart. For example,
185 $ helm install stable/kong --name my-release -f values.yaml
188 > **Tip**: You can use the default [values.yaml](values.yaml)
190 ### Kong Enterprise-specific parameters
192 Kong Enterprise requires some additional configuration not needed when using
193 Kong OSS. Some of the more important configuration is grouped in sections
194 under the `.enterprise` key in values.yaml, though most enterprise-specific
195 configuration can be placed under the `.env` key.
197 To use Kong Enterprise, change your image to a Kong Enterprise image and set
198 `.enterprise.enabled: true` in values.yaml to render Enterprise sections of the
199 templates. Review the sections below for other settings you should consider
200 configuring before installing the chart.
202 #### Service location hints
204 Kong Enterprise add two GUIs, Kong Manager and the Kong Developer Portal, that
205 must know where other Kong services (namely the admin and files APIs) can be
206 accessed in order to function properly. Kong's default behavior for attempting
207 to locate these absent configuration is unlikely to work in common Kubernetes
208 environments. Because of this, you should set each of `admin_gui_url`,
209 `admin_api_uri`, `proxy_url`, `portal_api_url`, `portal_gui_host`, and
210 `portal_gui_protocol` under the `.env` key in values.yaml to locations where
211 each of their respective services can be accessed to ensure that Kong services
212 can locate one another and properly set CORS headers. See the [Property Reference documentation](https://docs.konghq.com/enterprise/0.35-x/property-reference/)
213 for more details on these settings.
217 All Kong Enterprise deployments require a license. If you do not have a copy
218 of yours, please contact Kong Support. Once you have it, you will need to
219 store it in a Secret. Save your secret in a file named `license` (no extension)
220 and then create and inspect your secret:
223 $ kubectl create secret generic kong-enterprise-license --from-file=./license
224 $ kubectl get secret kong-enterprise-license -o yaml
227 license: eyJsaWNlbnNlIjp7InNpZ25hdHVyZSI6IkhFWSBJIFNFRSBZT1UgUEVFS0lORyBJTlNJREUgTVkgQkFTRTY0IEVYQU1QTEUiLCJwYXlsb2FkIjp7ImN1c3RvbWVyIjoiV0VMTCBUT08gQkFEIiwibGljZW5zZV9jcmVhdGlvbl9kYXRlIjoiMjAxOC0wNi0wNSIsInByb2R1Y3Rfc3Vic2NyaXB0aW9uIjoiVEhFUkVTIE5PVEhJTkcgSEVSRSIsImFkbWluX3NlYXRzIjoiNSIsInN1cHBvcnRfcGxhbiI6IkZha2UiLCJsaWNlbnNlX2V4cGlyYXRpb25fZGF0ZSI6IjIwMjAtMjAtMjAiLCJsaWNlbnNlX2tleSI6IlRTT0kgWkhJViJ9LCJ2ZXJzaW9uIjoxfX0K
230 creationTimestamp: "2019-05-17T21:45:16Z"
231 name: kong-enterprise-license
233 resourceVersion: "48695485"
234 selfLink: /api/v1/namespaces/default/secrets/kong-enterprise-license
235 uid: 0f2e8903-78ed-11e9-b1a6-42010a8a02ec
238 Set the secret name in values.yaml, in the `.enterprise.license_secret` key.
242 Note that you can create a default RBAC superuser when initially setting up an
243 environment, by setting the `KONG_PASSWORD` environment variable on the initial
244 migration Job's Pod. This will create a `kong_admin` admin whose token and
245 basic-auth password match the value of `KONG_PASSWORD`
247 Using RBAC within Kubernetes environments requires providing Kubernetes an RBAC
248 user for its readiness and liveness checks. We recommend creating a user that
249 has permission to read `/status` and nothing else. For example, with RBAC still
253 $ curl -sX POST http://admin.kong.example/rbac/users --data name=statuschecker --data user_token=REPLACE_WITH_SOME_TOKEN
254 {"user_token_ident":"45239","user_token":"$2b$09$cL.xbvRQCzE35A0osl8VTej7u0BgJOIgpTVjxpwZ1U8.jNdMwyQRW","id":"fe8824dc-09a7-4b68-b5e6-541e4b9b4ced","name":"statuschecker","enabled":true,"comment":null,"created_at":1558131229}
256 $ curl -sX POST http://admin.kong.example/rbac/roles --data name=read-status
257 {"comment":null,"created_at":1558131353,"id":"e32507a5-e636-40b2-88c0-090042db7d79","name":"read-status","is_default":false}
259 $ curl -sX POST http://admin.kong.example/rbac/roles/read-status/endpoints --data endpoint="/status" --data actions=read
260 {"endpoint":"\/status","created_at":1558131423,"workspace":"default","actions":["read"],"negative":false,"role":{"id":"e32507a5-e636-40b2-88c0-090042db7d79"}}
262 $ curl -sX POST http://admin.kong.example/rbac/users/statuschecker/roles --data roles=read-status
263 {"roles":[{"created_at":1558131353,"id":"e32507a5-e636-40b2-88c0-090042db7d79","name":"read-status"}],"user":{"user_token_ident":"45239","user_token":"$2b$09$cL.xbvRQCzE35A0osl8VTej7u0BgJOIgpTVjxpwZ1U8.jNdMwyQRW","id":"fe8824dc-09a7-4b68-b5e6-541e4b9b4ced","name":"statuschecker","comment":null,"enabled":true,"created_at":1558131229}}
265 Probes will then need to include that user's token, e.g. for the readinessProbe:
274 - name: Kong-Admin-Token
275 value: REPLACE_WITH_SOME_TOKEN
279 Note that RBAC is **NOT** currently enabled on the admin API container for the
280 controller Pod when the ingress controller is enabled. This admin API container
281 is not exposed outside the Pod, so only the controller can interact with it. We
282 intend to add RBAC to this container in the future after updating the controller
283 to add support for storing its RBAC token in a Secret, as currently it would
284 need to be stored in plaintext. RBAC is still enforced on the admin API of the
285 main deployment when using the ingress controller, as that admin API *is*
286 accessible outside the Pod.
290 Login sessions for Kong Manager and the Developer Portal make use of [the Kong
291 Sessions plugin](https://docs.konghq.com/enterprise/0.35-x/kong-manager/authentication/sessions/).
292 Their configuration must be stored in Secrets, as it contains an HMAC key.
293 If using either RBAC or the Portal, create a Secret with `admin_gui_session_conf`
294 and `portal_session_conf` keys.
297 $ cat admin_gui_session_conf
298 {"cookie_name":"admin_session","cookie_samesite":"off","secret":"admin-secret-CHANGEME","cookie_secure":true,"storage":"kong"}
299 $ cat portal_session_conf
300 {"cookie_name":"portal_session","cookie_samesite":"off","secret":"portal-secret-CHANGEME","cookie_secure":true,"storage":"kong"}
301 $ kubectl create secret generic kong-session-config --from-file=admin_gui_session_conf --from-file=portal_session_conf
302 secret/kong-session-config created
304 The exact plugin settings may vary in your environment. The `secret` should
305 always be changed for both configurations.
307 After creating your secret, set its name in values.yaml, in the
308 `.enterprise.rbac.session_conf_secret` and
309 `.enterprise.rbac.session_conf_secret` keys.
313 Email is used to send invitations for [Kong Admins](https://docs.konghq.com/enterprise/enterprise/0.35-x/kong-manager/networking/email/)
314 and [Developers](https://docs.konghq.com/enterprise/enterprise/0.35-x/developer-portal/configuration/smtp/).
316 Email invitations rely on setting a number of SMTP settings at once. For
317 convenience, these are grouped under the `.enterprise.smtp` key in values.yaml.
318 Setting `.enterprise.smtp.disabled: true` will set `KONG_SMTP_MOCK=on` and
319 allow Admin/Developer invites to proceed without sending email. Note, however,
320 that these have limited functionality without sending email.
322 If your SMTP server requires authentication, you should the `username` and
323 `smtp_password_secret` keys under `.enterprise.smtp.auth`.
324 `smtp_password_secret` must be a Secret containing an `smtp_password` key whose
325 value is your SMTP password.
327 ### Kong Ingress Controller
329 Kong Ingress Controller's primary purpose is to satisfy Ingress resources
330 created in your Kubernetes cluster.
331 It uses CRDs for more fine grained control over routing and
332 for Kong specific configuration.
333 To deploy the ingress controller together with
334 kong run the following command:
338 helm install stable/kong --set ingressController.enabled=true \
339 --set postgresql.enabled=false --set env.database=off
341 helm install stable/kong --set ingressController.enabled=true
344 If you like to use a static IP:
347 helm install stable/kong --set ingressController.enabled=true --set proxy.loadBalancerIP=[Your IP goes there] --set proxy.type=LoadBalancer --name kong --namespace kong
350 **Note**: Kong Ingress controller doesn't support custom SSL certificates
351 on Admin port. We will be removing this limitation in the future.
353 Kong ingress controller relies on several Custom Resource Definition objects to
354 declare the the Kong configurations and synchronize the configuration with the
355 Kong admin API. Each of this new objects declared in Kubernetes have a
356 one-to-one relation with a Kong resource.
357 The custom resources are:
364 You can can learn about kong ingress custom resource definitions [here](https://github.com/Kong/kubernetes-ingress-controller/blob/master/docs/custom-resources.md).
366 | Parameter | Description | Default |
367 | --------------- | ----------------------------------------- | ---------------------------------------------------------------------------- |
368 | enabled | Deploy the ingress controller, rbac and crd | false |
369 | replicaCount | Number of desired ingress controllers | 1 |
370 | image.repository | Docker image with the ingress controller | kong-docker-kubernetes-ingress-controller.bintray.io/kong-ingress-controller |
371 | image.tag | Version of the ingress controller | 0.2.0 |
372 | readinessProbe | Kong ingress controllers readiness probe | |
373 | livenessProbe | Kong ingress controllers liveness probe | |
374 | ingressClass | The ingress-class value for controller | nginx