helm/infrastructure/subcharts/kong/README.md

   1 ## Kong
   2
   3 [Kong](https://KongHQ.com/) is an open-source API Gateway and Microservices
   4 Management Layer, delivering high performance and reliability.
   5
   6 ## TL;DR;
   7
   8 ```bash
   9 $ helm install stable/kong
  10 ```
  11
  12 ## Introduction
  13
  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.
  16
  17 ## Prerequisites
  18
  19 - Kubernetes 1.8+ with Beta APIs enabled.
  20 - PV provisioner support in the underlying infrastructure if persistence
  21   is needed for Kong datastore.
  22
  23 ## Installing the Chart
  24
  25 To install the chart with the release name `my-release`:
  26
  27 ```bash
  28 $ helm install --name my-release stable/kong
  29 ```
  30
  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.
  37
  38 Reading through [the full list of Enterprise considerations](#kong-enterprise-specific-parameters)
  39 is recommended.
  40
  41 > **Tip**: List all releases using `helm list`
  42
  43 ## Uninstalling the Chart
  44
  45 To uninstall/delete the `my-release` deployment:
  46
  47 ```bash
  48 $ helm delete my-release
  49 ```
  50
  51 The command removes all the Kubernetes components associated with the
  52 chart and deletes the release.
  53
  54 ## Configuration
  55
  56 ### General Configuration Parameters
  57
  58 The following table lists the configurable parameters of the Kong chart
  59 and their default values.
  60
  61 | Parameter                          | Description                                                                           | Default             |
  62 | ---------------------------------- | ------------------------------------------------------------------------------------- | ------------------- |
  63 | image.repository                   | Kong image                                                                            | `kong`              |
  64 | image.tag                          | Kong image version                                                                    | `1.3`               |
  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 | updateStrategy                     | update strategy for deployment                                                        | `{}`                |
 102 | env                                | Additional [Kong configurations](https://getkong.org/docs/latest/configuration/)      |                     |
 103 | runMigrations                      | Run Kong migrations job                                                               | `true`              |
 104 | readinessProbe                     | Kong readiness probe                                                                  |                     |
 105 | livenessProbe                      | Kong liveness probe                                                                   |                     |
 106 | affinity                           | Node/pod affinities                                                                   |                     |
 107 | nodeSelector                       | Node labels for pod assignment                                                        | `{}`                |
 108 | podAnnotations                     | Annotations to add to each pod                                                        | `{}`                |
 109 | resources                          | Pod resource requests & limits                                                        | `{}`                |
 110 | tolerations                        | List of node taints to tolerate                                                       | `[]`                |
 111 | podDisruptionBudget.enabled        | Enable PodDisruptionBudget for Kong                                                   | `false`             |
 112 | podDisruptionBudget.maxUnavailable | Represents the minimum number of Pods that can be unavailable (integer or percentage) | `50%`               |
 113 | podDisruptionBudget.minAvailable   | Represents the number of Pods that must be available (integer or percentage)          |                     |
 114 | serviceMonitor.enabled             | Create ServiceMonitor for Prometheus Operator                                         | false               |
 115 | serviceMonitor.interval            | Scrapping interval                                                                    | 10s                 |
 116 | serviceMonitor.namespace           | Where to create ServiceMonitor                                                        |                     |
 117
 118 ### Admin/Proxy listener override
 119
 120 If you specify `env.admin_listen` or `env.proxy_listen`, this chart will use
 121 the value provided by you as opposed to constructing a listen variable
 122 from fields like `proxy.http.containerPort` and `proxy.http.enabled`. This allows
 123 you to be more prescriptive when defining listen directives.
 124
 125 **Note:** Overriding `env.proxy_listen` and `env.admin_listen` will potentially cause
 126 `admin.containerPort`, `proxy.http.containerPort` and `proxy.tls.containerPort` to become out of sync,
 127 and therefore must be updated accordingly.
 128
 129 I.E. updatating to `env.proxy_listen: 0.0.0.0:4444, 0.0.0.0:4443 ssl` will need
 130 `proxy.http.containerPort: 4444` and `proxy.tls.containerPort: 4443` to be set in order
 131 for the service definition to work properly.
 132
 133 ### Kong-specific parameters
 134
 135 Kong has a choice of either Postgres or Cassandra as a backend datatstore.
 136 This chart allows you to choose either of them with the `env.database`
 137 parameter.  Postgres is chosen by default.
 138
 139 Additionally, this chart allows you to use your own database or spin up a new
 140 instance by using the `postgres.enabled` or `cassandra.enabled` parameters.
 141 Enabling both will create both databases in your cluster, but only one
 142 will be used by Kong based on the `env.database` parameter.
 143 Postgres is enabled by default.
 144
 145 | Parameter                     | Description                                                             | Default               |
 146 | ------------------------------| ------------------------------------------------------------------------| ----------------------|
 147 | cassandra.enabled             | Spin up a new cassandra cluster for Kong                                | `false`               |
 148 | postgresql.enabled            | Spin up a new postgres instance for Kong                                | `true`                |
 149 | waitImage.repository          | Image used to wait for database to become ready                         | `busybox`             |
 150 | waitImage.tag                 | Tag for image used to wait for database to become ready                 | `latest`              |
 151 | env.database                  | Choose either `postgres`, `cassandra` or `"off"` (for dbless mode)      | `postgres`            |
 152 | env.pg_user                   | Postgres username                                                       | `kong`                |
 153 | env.pg_database               | Postgres database name                                                  | `kong`                |
 154 | env.pg_password               | Postgres database password (required if you are using your own database)| `kong`                |
 155 | env.pg_host                   | Postgres database host (required if you are using your own database)    | ``                    |
 156 | env.pg_port                   | Postgres database port                                                  | `5432`                |
 157 | env.cassandra_contact_points  | Cassandra contact points (required if you are using your own database)  | ``                    |
 158 | env.cassandra_port            | Cassandra query port                                                    | `9042`                |
 159 | env.cassandra_keyspace        | Cassandra keyspace                                                      | `kong`                |
 160 | env.cassandra_repl_factor     | Replication factor for the Kong keyspace                                | `2`                   |
 161 | dblessConfig.configMap        | Name of an existing ConfigMap containing the `kong.yml` file. This must have the key `kong.yml`.| `` |
 162 | dblessConfig.config           | Yaml configuration file for the dbless (declarative) configuration of Kong | see in `values.yaml`    |
 163
 164 All `kong.env` parameters can also accept a mapping instead of a value to ensure the parameters can be set through configmaps and secrets.
 165
 166 An example :
 167
 168 ```yaml
 169 kong:
 170   env:
 171      pg_user: kong
 172      pg_password:
 173        valueFrom:
 174          secretKeyRef:
 175             key: kong
 176             name: postgres
 177 ```
 178
 179
 180 For complete list of Kong configurations please check https://getkong.org/docs/latest/configuration/.
 181
 182 Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example,
 183
 184 ```console
 185 $ helm install stable/kong --name my-release \
 186   --set=image.tag=1.3,env.database=cassandra,cassandra.enabled=true
 187 ```
 188
 189 Alternatively, a YAML file that specifies the values for the above parameters
 190 can be provided while installing the chart. For example,
 191
 192 ```console
 193 $ helm install stable/kong --name my-release -f values.yaml
 194 ```
 195
 196 > **Tip**: You can use the default [values.yaml](values.yaml)
 197
 198 ### Kong Enterprise-specific parameters
 199
 200 Kong Enterprise requires some additional configuration not needed when using
 201 Kong OSS. Some of the more important configuration is grouped in sections
 202 under the `.enterprise` key in values.yaml, though most enterprise-specific
 203 configuration can be placed under the `.env` key.
 204
 205 To use Kong Enterprise, change your image to a Kong Enterprise image and set
 206 `.enterprise.enabled: true` in values.yaml to render Enterprise sections of the
 207 templates. Review the sections below for other settings you should consider
 208 configuring before installing the chart.
 209
 210 #### Service location hints
 211
 212 Kong Enterprise add two GUIs, Kong Manager and the Kong Developer Portal, that
 213 must know where other Kong services (namely the admin and files APIs) can be
 214 accessed in order to function properly. Kong's default behavior for attempting
 215 to locate these absent configuration is unlikely to work in common Kubernetes
 216 environments. Because of this, you should set each of `admin_gui_url`,
 217 `admin_api_uri`, `proxy_url`, `portal_api_url`, `portal_gui_host`, and
 218 `portal_gui_protocol` under the `.env` key in values.yaml to locations where
 219 each of their respective services can be accessed to ensure that Kong services
 220 can locate one another and properly set CORS headers. See the [Property Reference documentation](https://docs.konghq.com/enterprise/0.35-x/property-reference/)
 221 for more details on these settings.
 222
 223 #### License
 224
 225 All Kong Enterprise deployments require a license. If you do not have a copy
 226 of yours, please contact Kong Support. Once you have it, you will need to
 227 store it in a Secret. Save your secret in a file named `license` (no extension)
 228 and then create and inspect your secret:
 229
 230 ```
 231 $ kubectl create secret generic kong-enterprise-license --from-file=./license
 232 $ kubectl get secret kong-enterprise-license -o yaml
 233 apiVersion: v1
 234 data:
 235   license: eyJsaWNlbnNlIjp7InNpZ25hdHVyZSI6IkhFWSBJIFNFRSBZT1UgUEVFS0lORyBJTlNJREUgTVkgQkFTRTY0IEVYQU1QTEUiLCJwYXlsb2FkIjp7ImN1c3RvbWVyIjoiV0VMTCBUT08gQkFEIiwibGljZW5zZV9jcmVhdGlvbl9kYXRlIjoiMjAxOC0wNi0wNSIsInByb2R1Y3Rfc3Vic2NyaXB0aW9uIjoiVEhFUkVTIE5PVEhJTkcgSEVSRSIsImFkbWluX3NlYXRzIjoiNSIsInN1cHBvcnRfcGxhbiI6IkZha2UiLCJsaWNlbnNlX2V4cGlyYXRpb25fZGF0ZSI6IjIwMjAtMjAtMjAiLCJsaWNlbnNlX2tleSI6IlRTT0kgWkhJViJ9LCJ2ZXJzaW9uIjoxfX0K
 236 kind: Secret
 237 metadata:
 238   creationTimestamp: "2019-05-17T21:45:16Z"
 239   name: kong-enterprise-license
 240   namespace: default
 241   resourceVersion: "48695485"
 242   selfLink: /api/v1/namespaces/default/secrets/kong-enterprise-license
 243   uid: 0f2e8903-78ed-11e9-b1a6-42010a8a02ec
 244 type: Opaque
 245 ```
 246 Set the secret name in values.yaml, in the `.enterprise.license_secret` key.
 247
 248 #### RBAC
 249
 250 Note that you can create a default RBAC superuser when initially setting up an
 251 environment, by setting the `KONG_PASSWORD` environment variable on the initial
 252 migration Job's Pod. This will create a `kong_admin` admin whose token and
 253 basic-auth password match the value of `KONG_PASSWORD`
 254
 255 Using RBAC within Kubernetes environments requires providing Kubernetes an RBAC
 256 user for its readiness and liveness checks. We recommend creating a user that
 257 has permission to read `/status` and nothing else. For example, with RBAC still
 258 disabled:
 259
 260 ```
 261 $ curl -sX POST http://admin.kong.example/rbac/users --data name=statuschecker --data user_token=REPLACE_WITH_SOME_TOKEN
 262 {"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}
 263
 264 $ curl -sX POST http://admin.kong.example/rbac/roles --data name=read-status
 265 {"comment":null,"created_at":1558131353,"id":"e32507a5-e636-40b2-88c0-090042db7d79","name":"read-status","is_default":false}
 266
 267 $ curl -sX POST http://admin.kong.example/rbac/roles/read-status/endpoints --data endpoint="/status" --data actions=read
 268 {"endpoint":"\/status","created_at":1558131423,"workspace":"default","actions":["read"],"negative":false,"role":{"id":"e32507a5-e636-40b2-88c0-090042db7d79"}}
 269
 270 $ curl -sX POST http://admin.kong.example/rbac/users/statuschecker/roles --data roles=read-status
 271 {"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}}
 272 ```
 273 Probes will then need to include that user's token, e.g. for the readinessProbe:
 274
 275 ```
 276 readinessProbe:
 277   httpGet:
 278     path: "/status"
 279     port: admin
 280     scheme: HTTP
 281     httpHeaders:
 282       - name: Kong-Admin-Token
 283         value: REPLACE_WITH_SOME_TOKEN
 284     ...
 285 ```
 286
 287 Note that RBAC is **NOT** currently enabled on the admin API container for the
 288 controller Pod when the ingress controller is enabled. This admin API container
 289 is not exposed outside the Pod, so only the controller can interact with it. We
 290 intend to add RBAC to this container in the future after updating the controller
 291 to add support for storing its RBAC token in a Secret, as currently it would
 292 need to be stored in plaintext. RBAC is still enforced on the admin API of the
 293 main deployment when using the ingress controller, as that admin API *is*
 294 accessible outside the Pod.
 295
 296 #### Sessions
 297
 298 Login sessions for Kong Manager and the Developer Portal make use of [the Kong
 299 Sessions plugin](https://docs.konghq.com/enterprise/0.35-x/kong-manager/authentication/sessions/).
 300 Their configuration must be stored in Secrets, as it contains an HMAC key.
 301 If using either RBAC or the Portal, create a Secret with `admin_gui_session_conf`
 302 and `portal_session_conf` keys.
 303
 304 ```
 305 $ cat admin_gui_session_conf
 306 {"cookie_name":"admin_session","cookie_samesite":"off","secret":"admin-secret-CHANGEME","cookie_secure":true,"storage":"kong"}
 307 $ cat portal_session_conf
 308 {"cookie_name":"portal_session","cookie_samesite":"off","secret":"portal-secret-CHANGEME","cookie_secure":true,"storage":"kong"}
 309 $ kubectl create secret generic kong-session-config --from-file=admin_gui_session_conf --from-file=portal_session_conf
 310 secret/kong-session-config created
 311 ```
 312 The exact plugin settings may vary in your environment. The `secret` should
 313 always be changed for both configurations.
 314
 315 After creating your secret, set its name in values.yaml, in the
 316 `.enterprise.rbac.session_conf_secret` and
 317 `.enterprise.rbac.session_conf_secret` keys.
 318
 319 #### Email/SMTP
 320
 321 Email is used to send invitations for [Kong Admins](https://docs.konghq.com/enterprise/enterprise/0.35-x/kong-manager/networking/email/)
 322 and [Developers](https://docs.konghq.com/enterprise/enterprise/0.35-x/developer-portal/configuration/smtp/).
 323
 324 Email invitations rely on setting a number of SMTP settings at once. For
 325 convenience, these are grouped under the `.enterprise.smtp` key in values.yaml.
 326 Setting `.enterprise.smtp.disabled: true` will set `KONG_SMTP_MOCK=on` and
 327 allow Admin/Developer invites to proceed without sending email. Note, however,
 328 that these have limited functionality without sending email.
 329
 330 If your SMTP server requires authentication, you should the `username` and
 331 `smtp_password_secret` keys under `.enterprise.smtp.auth`.
 332 `smtp_password_secret` must be a Secret containing an `smtp_password` key whose
 333 value is your SMTP password.
 334
 335 ### DB-less Configuration
 336
 337
 338 When deploying Kong in DB-less mode (`env.database: "off"`) and without the Ingress
 339 Controller (`ingressController.enabled: false`), Kong needs a config to run. In
 340 this case, configuration can be provided using an exsiting ConfigMap
 341 (`dblessConfig.configMap`) or pushed directly into the values file under
 342 `dblessConfig.config`. See the example configuration in the default values.yaml
 343 for more details.
 344
 345 ### Kong Ingress Controller
 346
 347 Kong Ingress Controller's primary purpose is to satisfy Ingress resources
 348 created in your Kubernetes cluster.
 349 It uses CRDs for more fine grained control over routing and
 350 for Kong specific configuration.
 351 To deploy the ingress controller together with
 352 kong run the following command:
 353
 354 ```bash
 355 # without a database
 356 helm install stable/kong --set ingressController.enabled=true \
 357   --set postgresql.enabled=false --set env.database=off
 358 # with a database
 359 helm install stable/kong --set ingressController.enabled=true
 360 ```
 361
 362 If you like to use a static IP:
 363
 364 ```shell
 365 helm install stable/kong --set ingressController.enabled=true --set proxy.loadBalancerIP=[Your IP goes there] --set proxy.type=LoadBalancer --name kong --namespace kong
 366 ```
 367
 368 **Note**: Kong Ingress controller doesn't support custom SSL certificates
 369 on Admin port. We will be removing this limitation in the future.
 370
 371 Kong ingress controller relies on several Custom Resource Definition objects to
 372 declare the the Kong configurations and synchronize the configuration with the
 373 Kong admin API. Each of this new objects  declared in Kubernetes have a
 374 one-to-one relation with a Kong resource.
 375 The custom resources are:
 376
 377 - KongConsumer
 378 - KongCredential
 379 - KongPlugin
 380 - KongIngress
 381
 382 You can can learn about kong ingress custom resource definitions [here](https://github.com/Kong/kubernetes-ingress-controller/blob/master/docs/custom-resources.md).
 383
 384
 385 | Parameter                          | Description                                                                           | Default                                                                      |
 386 | ---------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
 387 | enabled                            | Deploy the ingress controller, rbac and crd                                           | false                                                                        |
 388 | replicaCount                       | Number of desired ingress controllers                                                 | 1                                                                            |
 389 | image.repository                   | Docker image with the ingress controller                                              | kong-docker-kubernetes-ingress-controller.bintray.io/kong-ingress-controller |
 390 | image.tag                          | Version of the ingress controller                                                     | 0.2.0                                                                        |
 391 | readinessProbe                     | Kong ingress controllers readiness probe                                              |                                                                              |
 392 | livenessProbe                      | Kong ingress controllers liveness probe                                               |                                                                              |
 393 | ingressClass                       | The ingress-class value for controller                                                | nginx                                                                        |
 394 | podDisruptionBudget.enabled        | Enable PodDisruptionBudget for ingress controller                                     | `false`                                                                      |
 395 | podDisruptionBudget.maxUnavailable | Represents the minimum number of Pods that can be unavailable (integer or percentage) | `50%`                                                                        |
 396 | podDisruptionBudget.minAvailable   | Represents the number of Pods that must be available (integer or percentage)          |                                                                              |
 397