stable/kong/README.md
This chart has been deprecated in favor of Kong's official chart repository.
All users are advised to immediately migrate over to the new repository.
Kong for Kubernetes is an open-source Ingress Controller for Kubernetes that offers API management capabilities with a plugin architecture.
This chart bootstraps all the components needed to run Kong on a Kubernetes cluster using the Helm package manager.
$ helm repo update
$ helm install stable/kong
To install the chart with the release name my-release:
$ helm repo update
$ helm install --name my-release stable/kong
To uninstall/delete the my-release deployment:
$ helm delete my-release
The command removes all the Kubernetes components associated with the chart and deletes the release.
Tip: List all releases using
helm list
Please read the FAQs document.
If using Kong Enterprise, several additional steps are necessary before installing the chart:
enterprise.enabled to true in values.yaml fileOnce you have these set, it is possible to install Kong Enterprise
Please read through Kong Enterprise considerations to understand all settings that are enterprise specific.
Kong is a highly configurable piece of software that can be deployed in a number of different ways, depending on your use-case.
All combinations of various runtimes, databases and configuration methods are supported by this Helm chart. The recommended approach is to use the Ingress Controller based configuration along-with DB-less mode.
Following sections detail on various high-level architecture options available:
Kong can run with or without a database (DB-less). By default, this chart installs Kong without a database.
Although Kong can run with Postgres and Cassandra, the recommended database, if you would like to use one, is Postgres for Kubernetes installations. If your use-case warrants Cassandra, you should run the Cassandra cluster outside of Kubernetes.
The database to use for Kong can be controlled via the env.database parameter.
For more details, please read the env section.
Furthermore, this chart allows you to bring your own database that you manage
or spin up a new Postgres instance using the postgres.enabled parameter.
Cassandra deployment via a sub-chart was previously supported but the support has now been dropped due to stability issues. You can still deploy Cassandra on your own and configure Kong to use that via the
env.databaseparameter.
When deploying Kong in DB-less mode(env.database: "off")
and without the Ingress Controller(ingressController.enabled: false),
you have to provide a declarative configuration for Kong to run.
The configuration can be provided using an existing ConfigMap
(dblessConfig.configMap) or or the whole configuration can be put into the
values.yaml file for deployment itself, under the dblessConfig.config
parameter. See the example configuration in the default values.yaml
for more details.
There are three different packages of Kong that are available:
The package to run can be changed via image.repository and image.tag
parameters. If you would like to run the Enterprise package, please read
the Kong Enterprise Parameters section.
Kong can be configured via two methods:
kubectl and Kubernetes-native APIs.
This is also known as Kong Ingress Controller or Kong for Kubernetes and is
the default deployment pattern for this Helm Chart. The configuration
for Kong is managed via Ingress and a few
Custom Resources.
For more details, please read the
documentation
on Kong Ingress Controller.
To configure and fine-tune the controller, please read the
Ingress Controller Parameters section.admin.enabled and env.admin_listen parameters.| Parameter | Description | Default |
|---|---|---|
| image.repository | Kong image | kong |
| image.tag | Kong image version | 1.3 |
| image.pullPolicy | Image pull policy | IfNotPresent |
| image.pullSecrets | Image pull secrets | null |
| replicaCount | Kong instance count | 1 |
| admin.enabled | Create Admin Service | false |
| admin.useTLS | Secure Admin traffic | true |
| admin.servicePort | TCP port on which the Kong admin service is exposed | 8444 |
| admin.containerPort | TCP port on which Kong app listens for admin traffic | 8444 |
| admin.nodePort | Node port when service type is NodePort | |
| admin.hostPort | Host port to use for admin traffic | |
| admin.type | k8s service type, Options: NodePort, ClusterIP, LoadBalancer | NodePort |
| admin.loadBalancerIP | Will reuse an existing ingress static IP for the admin service | null |
| admin.loadBalancerSourceRanges | Limit admin access to CIDRs if set and service type is LoadBalancer | [] |
| admin.ingress.enabled | Enable ingress resource creation (works with proxy.type=ClusterIP) | false |
| admin.ingress.tls | Name of secret resource, containing TLS secret | |
| admin.ingress.hosts | List of ingress hosts. | [] |
| admin.ingress.path | Ingress path. | / |
| admin.ingress.annotations | Ingress annotations. See documentation for your ingress controller for details | {} |
| proxy.http.enabled | Enables http on the proxy | true |
| proxy.http.servicePort | Service port to use for http | 80 |
| proxy.http.containerPort | Container port to use for http | 8000 |
| proxy.http.nodePort | Node port to use for http | 32080 |
| proxy.http.hostPort | Host port to use for http | |
| proxy.tls.enabled | Enables TLS on the proxy | true |
| proxy.tls.containerPort | Container port to use for TLS | 8443 |
| proxy.tls.servicePort | Service port to use for TLS | 8443 |
| proxy.tls.nodePort | Node port to use for TLS | 32443 |
| proxy.tls.hostPort | Host port to use for TLS | |
| proxy.tls.overrideServiceTargetPort | Override service port to use for TLS without touching Kong containerPort | |
| proxy.type | k8s service type. Options: NodePort, ClusterIP, LoadBalancer | LoadBalancer |
| proxy.clusterIP | k8s service clusterIP | |
| proxy.loadBalancerSourceRanges | Limit proxy access to CIDRs if set and service type is LoadBalancer | [] |
| proxy.loadBalancerIP | To reuse an existing ingress static IP for the admin service | |
| proxy.externalIPs | IPs for which nodes in the cluster will also accept traffic for the proxy | [] |
| proxy.externalTrafficPolicy | k8s service's externalTrafficPolicy. Options: Cluster, Local | |
| proxy.ingress.enabled | Enable ingress resource creation (works with proxy.type=ClusterIP) | false |
| proxy.ingress.tls | Name of secret resource, containing TLS secret | |
| proxy.ingress.hosts | List of ingress hosts. | [] |
| proxy.ingress.path | Ingress path. | / |
| proxy.ingress.annotations | Ingress annotations. See documentation for your ingress controller for details | {} |
| plugins | Install custom plugins into Kong via ConfigMaps or Secrets | {} |
| env | Additional Kong configurations | |
| runMigrations | Run Kong migrations job | true |
| waitImage.repository | Image used to wait for database to become ready | busybox |
| waitImage.tag | Tag for image used to wait for database to become ready | latest |
| waitImage.pullPolicy | Wait image pull policy | IfNotPresent |
| postgresql.enabled | Spin up a new postgres instance for Kong | false |
| dblessConfig.configMap | Name of an existing ConfigMap containing the kong.yml file. This must have the key kong.yml. | `` |
| dblessConfig.config | Yaml configuration file for the dbless (declarative) configuration of Kong | see in values.yaml |
All of the following properties are nested under the ingressController
section of values.yaml file:
| Parameter | Description | Default |
|---|---|---|
| enabled | Deploy the ingress controller, rbac and crd | true |
| replicaCount | Number of desired ingress controllers | 1 |
| image.repository | Docker image with the ingress controller | kong-docker-kubernetes-ingress-controller.bintray.io/kong-ingress-controller |
| image.tag | Version of the ingress controller | 0.7.0 |
| readinessProbe | Kong ingress controllers readiness probe | |
| livenessProbe | Kong ingress controllers liveness probe | |
| env | Specify Kong Ingress Controller configuration via environment variables | |
| ingressClass | The ingress-class value for controller | kong |
| admissionWebhook.enabled | Whether to enable the validating admission webhook | false |
| admissionWebhook.failurePolicy | How unrecognized errors from the admission endpoint are handled (Ignore or Fail) | Fail |
| admissionWebhook.port | The port the ingress controller will listen on for admission webhooks | 8080 |
For a complete list of all configuration values you can set in the
env section, please read the Kong Ingress Controller's
configuration document.
| Parameter | Description | Default |
|---|---|---|
| updateStrategy | update strategy for deployment | {} |
| readinessProbe | Kong readiness probe | |
| livenessProbe | Kong liveness probe | |
| affinity | Node/pod affinities | |
| nodeSelector | Node labels for pod assignment | {} |
| podAnnotations | Annotations to add to each pod | {} |
| resources | Pod resource requests & limits | {} |
| tolerations | List of node taints to tolerate | [] |
| podDisruptionBudget.enabled | Enable PodDisruptionBudget for Kong | false |
| podDisruptionBudget.maxUnavailable | Represents the minimum number of Pods that can be unavailable (integer or percentage) | 50% |
| podDisruptionBudget.minAvailable | Represents the number of Pods that must be available (integer or percentage) | |
| podSecurityPolicy.enabled | Enable podSecurityPolicy for Kong | false |
| serviceMonitor.enabled | Create ServiceMonitor for Prometheus Operator | false |
| serviceMonitor.interval | Scrapping interval | 10s |
| serviceMonitor.namespace | Where to create ServiceMonitor | |
| secretVolumes | Mount given secrets as a volume in Kong container to override default certs and keys. | [] |
| serviceMonitor.labels | ServiceMonito Labels | {} |
env sectionThe env section can be used to configured all properties of Kong.
Any key value put under this section translates to environment variables
used to control Kong's configuration. Every key is prefixed with KONG_
and upper-cased before setting the environment variable.
Furthermore, all kong.env parameters can also accept a mapping instead of a
value to ensure the parameters can be set through configmaps and secrets.
An example :
kong:
env: # load PG password from a secret dynamically
pg_user: kong
pg_password:
valueFrom:
secretKeyRef:
key: kong
name: postgres
nginx_worker_processes: "2"
For complete list of Kong configurations please check the Kong configuration docs.
Tip: You can use the default values.yaml
If you specify env.admin_listen or env.proxy_listen, this chart will use
the value provided by you as opposed to constructing a listen variable
from fields like proxy.http.containerPort and proxy.http.enabled.
This allows you to be more prescriptive when defining listen directives.
Note: Overriding env.proxy_listen and env.admin_listen will
potentially cause admin.containerPort, proxy.http.containerPort and
proxy.tls.containerPort to become out of sync,
and therefore must be updated accordingly.
For example, updating to env.proxy_listen: 0.0.0.0:4444, 0.0.0.0:4443 ssl
will need proxy.http.containerPort: 4444 and proxy.tls.containerPort: 4443
to be set in order for the service definition to work properly.
Kong Enterprise requires some additional configuration not needed when using Kong Open-Source. To use Kong Enterprise, at the minimum, you need to do the following:
enterprise.enabled to true in values.yaml fileOnce you have these set, it is possible to install Kong Enterprise, but please make sure to review the below sections for other settings that you should consider configuring before installing Kong.
Some of the more important configuration is grouped in sections
under the .enterprise key in values.yaml, though most enterprise-specific
configuration can be placed under the .env key.
All Kong Enterprise deployments require a license. If you do not have a copy
of yours, please contact Kong Support. Once you have it, you will need to
store it in a Secret. Save your secret in a file named license (no extension)
and then create and inspect your secret:
$ kubectl create secret generic kong-enterprise-license --from-file=./license
Set the secret name in values.yaml, in the .enterprise.license_secret key.
Please ensure the above secret is created in the same namespace in which
Kong is going to be deployed.
Next, we need to setup Docker credentials in order to allow Kubernetes nodes to pull down Kong Enterprise Docker image, which is hosted as a private repository.
As part of your sign up for Kong Enterprise, you should have received credentials for these as well.
$ kubectl create secret docker-registry kong-enterprise-docker \
--docker-server=kong-docker-kong-enterprise-k8s.bintray.io \
--docker-username=<your-username> \
--docker-password=<your-password>
secret/kong-enterprise-docker created
Set the secret name in values.yaml in the image.pullSecrets section.
Again, Please ensure the above secret is created in the same namespace in which
Kong is going to be deployed.
Kong Enterprise add two GUIs, Kong Manager and the Kong Developer Portal, that
must know where other Kong services (namely the admin and files APIs) can be
accessed in order to function properly. Kong's default behavior for attempting
to locate these absent configuration is unlikely to work in common Kubernetes
environments. Because of this, you should set each of admin_gui_url,
admin_api_uri, proxy_url, portal_api_url, portal_gui_host, and
portal_gui_protocol under the .env key in values.yaml to locations where
each of their respective services can be accessed to ensure that Kong services
can locate one another and properly set CORS headers. See the
Property Reference documentation
for more details on these settings.
You can create a default RBAC superuser when initially setting up an
environment, by setting the KONG_PASSWORD environment variable on the initial
migration Job's Pod. This will create a kong_admin admin whose token and
basic-auth password match the value of KONG_PASSWORD.
You can create a secret holding the initial password value and then
mount the secret as an environment variable using the env section.
Note that RBAC is NOT currently enabled on the admin API container for the controller Pod when the ingress controller is enabled. This admin API container is not exposed outside the Pod, so only the controller can interact with it. We intend to add RBAC to this container in the future after updating the controller to add support for storing its RBAC token in a Secret, as currently it would need to be stored in plaintext. RBAC is still enforced on the admin API of the main deployment when using the ingress controller, as that admin API is accessible outside the Pod.
Login sessions for Kong Manager and the Developer Portal make use of
the Kong Sessions plugin.
Their configuration must be stored in Secrets, as it contains an HMAC key.
If using either RBAC or the Portal, create a Secret with admin_gui_session_conf
and portal_session_conf keys.
$ cat admin_gui_session_conf
{"cookie_name":"admin_session","cookie_samesite":"off","secret":"admin-secret-CHANGEME","cookie_secure":true,"storage":"kong"}
$ cat portal_session_conf
{"cookie_name":"portal_session","cookie_samesite":"off","secret":"portal-secret-CHANGEME","cookie_secure":true,"storage":"kong"}
$ kubectl create secret generic kong-session-config --from-file=admin_gui_session_conf --from-file=portal_session_conf
secret/kong-session-config created
The exact plugin settings may vary in your environment. The secret should
always be changed for both configurations.
After creating your secret, set its name in values.yaml, in the
.enterprise.rbac.session_conf_secret and
.enterprise.portal.session_conf_secret keys.
Email is used to send invitations for Kong Admins and Developers.
Email invitations rely on setting a number of SMTP settings at once. For
convenience, these are grouped under the .enterprise.smtp key in values.yaml.
Setting .enterprise.smtp.disabled: true will set KONG_SMTP_MOCK=on and
allow Admin/Developer invites to proceed without sending email. Note, however,
that these have limited functionality without sending email.
If your SMTP server requires authentication, you should the username and
smtp_password_secret keys under .enterprise.smtp.auth.
smtp_password_secret must be a Secret containing an smtp_password key whose
value is your SMTP password.
This version has no code changes and Kong's chart is now deprecated in this repository. Please use Kong's official chart repository.
grpc protocol for KongPluginssideEffects and admissionReviewVersions for Admission Webhook1s to 5shelm del --purge $RELEASE and redeploy from scratch.
Note that this will cause downtime for the kong proxy.PR #19856
PR #19854
This release contains no user-visible changes
PR #19887
PR #19885
PR #19852
final_env helper.PR #19840
proxy. Previously this
was auto-generated by Helm. This deterministic naming allows for simpler
scripts and documentation.Following changes have no end user visible effects:
wait-for-postgres container has been refactored and de-duplicated/tmp and /kong_prefix to allow
for read-only root filesystem securityContexts and PodSecurityPolicys./usr/local/kong prefix to the mounted emptyDir
at /kong_prefix in .Values.env..Values.enterprise.enabled == true. Inverted template to create
it (and set it to "off") if that setting is instead disabled.admin.enabled)proxy.type has been changed to LoadBalanceradmin.enabled flag.migrations-pre-upgrade.yamladmin_gui_auth_conf_secret is now required for Kong Manager
authentication methods other than basic-auth.
Users defining values for admin_gui_auth_conf should migrate them to
an externally-defined secret with a key of admin_gui_auth_conf and
reference the secret name in admin_gui_auth_conf_secret.admin_api_uri and similar settings. Configuration for
the proxy ingress is unchanged, but its documentation now accurately reflects
the TLS configuration needed.If you run into an issue, bug or have a question, please reach out to the Kong community via Kong Nation. Please do not open issues in this repository as the maintainers will not be notified and won't respond.