From 08636f54cd7e22f2490a36161ef26cc7a785bd0e Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Thu, 20 Aug 2020 17:11:25 -0700 Subject: [PATCH 01/20] doc: add resource class concept doc --- docs/concepts/resource-classes.md | 120 ++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 docs/concepts/resource-classes.md diff --git a/docs/concepts/resource-classes.md b/docs/concepts/resource-classes.md new file mode 100644 index 0000000000..4c46476504 --- /dev/null +++ b/docs/concepts/resource-classes.md @@ -0,0 +1,120 @@ +# Kong Ingress Controller and resource class + + +## Table of Contents + +- [**Introduction**](#introduction) +- [**Configuring the controller class**](#configuring-the-controller-class) +- [**Kubernetes resource class**](#kubernetes-resource-class) +- [**When to use custom classes**](#when-to-use-custom-classes) +- [**Legacy behavior**](#legacy-behavior) + +## Introduction + +The Kong Ingress Controller uses resource classes to filter Kubernetes Ingress +objects and other resources before converting them into Kong configuration. +This allows it to coexist with other ingress controllers and/or other +deployments of the Kong Ingress Controller in the same cluster: a Kong Ingress +Controller will only process configuration marked for its use. + +## Configuring the controller class + +The `--ingress-class` flag (or `CONTROLLER_INGRESS_CLASS` environment variable) +specify the resource class expected by the Kong Ingress Controller. By default, +it expects the `kong` class. + +## Kubernetes resource class + +The Kong Ingress Controller translates a variety of Kubernetes resources into +Kong configuration. Broadly speaking, we can separate these resources into two +categories: + +- Resources that the controller translates directly into Kong configuration. +- Resources referenced by some other resource, where the other resource is + directly translated into Kong configuration. + +For example, an Ingress is translated directly into a Kong route, and a +KongConsumer is translated directly into a Kong consumer. A Secret containing +an authentication plugin credential is _not_ translated directly: it is only +translated into Kong configuration if a KongConsumer resource references it. + +Because they create Kong configuration indenpendent of any other resources, +directly-translated resources require a class, and their class must match the +class configured for the controller. Referenced resources do not require a +class, but must be referenced by a directly-translated resource matches the +controller. + +### Adding class information to resources + +Most resources use a [kubernetes.io/ingress-class annoration][class-annotation] +to indicate their class. There are several exceptions: + +- v1 Ingress resources have a dedicated `class` field. +- Knative Services [use the class specifed][knative-class] by the + `ingress.class` key of the Knative installation's `config-network` ConfigMap. + You can optionally [override this on a per-Service basis][knative-override] + by adding a `networking.knative.dev/ingress.class` annotation to the Service. + +### Allowing resources without a class + +Specifying a class is optional for some resources. Although specifying a class +is recommended, you can instruct the controller to process resources without a +class annotation using flags: + +- `--process-classless-ingress-v1beta1` instructs the controller to translate + v1beta1 Ingress resources with no class annotation. +- `--process-classless-kong-consumer` instructs the controller to translate + KongConsumer resources with no class annotation. + +These flags are primarily intended for compatibility with older configuration +(older versions of the Kong Ingress Controller had less strict class +requirements, and it was common to omit class annotations). If you are creating +new configuration and do not have older configuration without class +annotations, recommended best practice is to add class information to Ingress +and KongConsumer resources and not set the above flags. Doing so avoids +accidentally creating duplicate configuration in other ingress controller +instances. + +These flags do not _ignore_ `ingress.class` annotations: they allow resources +with no such annotation, but will not allow resource that have a non-matching +`ingress.class` annotation. + +## When to use custom classes + +Using the default `kong` class is fine for simpler deployments, where only one +Kong Ingress Controller instance is running in a cluster. Changing the class is +typical when: + +- You install multiple Kong environments in one cluster to handle different + types of ingress traffic, e.g. when using separate Kong instances to handle + traffic on internal and external load balancers, or deploying different types + of non-production environments in a single test cluster. +- You install multiple controller instances that create configuration in + different Kong workspaces (using the `--kong-workspace` flag). + +## Legacy behavior + +This overview covers behavior in Kong Ingress Controller version 0.10.0 onward. +Earlier versions had a special case for the default class and a bug affecting +custom classes: + +- When using the default `kong` class, the controller would always process + classless resources in addition to `kong`-class resources. When using a + non-default controller class, the controller would only process resources + with that class, not classless resources. Although this was by design, it was + a source of user confusion. +- When using a custom controller class, some resources that should not have + required a class (because they were referenced by other resources) + effectively did require a class: while these resources were loaded initially, + the controller would not track updates to them unless they had a class + annotation. + +In versions 0.10.0+ you must instruct the controller to load classless +resources, which is allowed (but not recommended) for either the default or +custom classess. Resources referenced by another resource are always loaded and +updated correctly regardless of which class you set on the controller; you do +not need to add class annotations to these resources when using a custom class. + +[class-annotation]: ../references/annotations.md#kubernetesioingressclass +[knative-class]: ../guides/using-kong-with-knative.md#ingress-class +[knative-override]: https://knative.tips/networking/ingress-override/ From 1edda65da307d004696ecaae3e4b40458295f978 Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Fri, 21 Aug 2020 11:04:52 -0700 Subject: [PATCH 02/20] doc: link class concept section --- docs/README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/README.md b/docs/README.md index 66c047bfd3..d09589c161 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,7 @@ - [Custom Resources](#custom-resources) - [Deployment methods](#deployment-methods) - [High-availability and scaling](#high-availability-and-scaling) + - [Resource classes](#resource-classes) - [Security](#security) - [Guides and Tutorials](#guides-and-tutorials) - [Configuration reference](#configuration-reference) @@ -48,6 +49,12 @@ and infrastructure. Please refer to [this document](concepts/ha-and-scaling.md) to understand failures scenarios, recovery methods, as well as scaling considerations. +### Resource classes + +[Resource classes](concepts/resource-classes.md) filter which resources the +controller loads. They ensure that Kong Ingress Controller instances do not +load configuration intended for other instances or other ingress controllers. + ### Security Please refer to [this document](concepts/security.md) to understand the From 2b6815a7a079a29a6801250208f6e8601576dece Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Fri, 21 Aug 2020 16:30:19 -0700 Subject: [PATCH 03/20] doc: add resource class examples --- docs/concepts/resource-classes.md | 61 +++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/concepts/resource-classes.md b/docs/concepts/resource-classes.md index 4c46476504..baac25ec10 100644 --- a/docs/concepts/resource-classes.md +++ b/docs/concepts/resource-classes.md @@ -8,6 +8,7 @@ - [**Kubernetes resource class**](#kubernetes-resource-class) - [**When to use custom classes**](#when-to-use-custom-classes) - [**Legacy behavior**](#legacy-behavior) +- [**Examples**](#examples) ## Introduction @@ -115,6 +116,66 @@ custom classess. Resources referenced by another resource are always loaded and updated correctly regardless of which class you set on the controller; you do not need to add class annotations to these resources when using a custom class. +## Examples + +Typical configurations will include a mix of resources that have class +information and resources that are referenced by them. For example, consider +the following configuration for authenticating a request, using a KongConsumer, +credential Secret, Ingress, and KongPlugin (a Service is implied, but not +shown): + +``` +kind: KongConsumer +metadata: + name: dyadya-styopa + annotations: + kubernetes.io/ingress.class: "kong" +username: styopa +credentials: +- styopa-key + +--- + +kind: Secret +apiVersion: v1 +stringData: + key: bylkogdatomoryakom + kongCredType: key-auth +metadata: + name: styopa-key + +--- + +kind: Ingress +apiVersion: extensions/v1beta1 +metadata: + name: ktonezhnaet + annotations: + kubernetes.io/ingress.class: "kong" + konghq.com/plugins: "key-auth-example" +spec: + rules: + - http: + paths: + - path: /vsemznakom + backend: + serviceName: httpbin + servicePort: 80 + +--- + +apiVersion: configuration.konghq.com/v1 +kind: KongPlugin +metadata: + name: key-auth-example +plugin: key-auth +``` + +The KongConsumer and Ingress resources both have class annotations, as they are +resources that the controller uses as a basis for building Kong configuration. +The Secret and KongPlugin _do not_ have class annotations, as they are +referenced by other resources that do. + [class-annotation]: ../references/annotations.md#kubernetesioingressclass [knative-class]: ../guides/using-kong-with-knative.md#ingress-class [knative-override]: https://knative.tips/networking/ingress-override/ From fa612408ca45f275319bc5fb4c3910148d44f35c Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 25 Aug 2020 12:33:17 -0700 Subject: [PATCH 04/20] doc: add class to example Ingress resources Add a "kubernetes.io/ingress.class: kong" annotation to all example Ingress resources. This aligns them with the 0.10 default behavior, which requires an ingress class (most previously had no class annotation). Examples should still be valid for versions <0.10, as those versions only allowed classless Ingresses when the controller was set to use the default "kong" class. --- docs/guides/cert-manager.md | 3 +++ docs/guides/configure-acl-plugin.md | 6 ++++++ docs/guides/configuring-fallback-service.md | 3 +++ docs/guides/configuring-health-checks.md | 1 + docs/guides/configuring-https-redirect.md | 1 + docs/guides/getting-started.md | 3 +++ docs/guides/prometheus-grafana.md | 1 + docs/guides/redis-rate-limiting.md | 1 + docs/guides/using-consumer-credential-resource.md | 2 ++ docs/guides/using-external-service.md | 1 + docs/guides/using-ingress-with-grpc.md | 2 ++ docs/guides/using-kongclusterplugin-resource.md | 3 +++ docs/guides/using-kongingress-resource.md | 2 ++ docs/guides/using-kongplugin-resource.md | 2 ++ docs/guides/using-mtls-auth-plugin.md | 1 + docs/guides/using-oidc-plugin.md | 2 ++ docs/guides/using-rewrites.md | 2 ++ docs/references/custom-resources.md | 1 + 18 files changed, 37 insertions(+) diff --git a/docs/guides/cert-manager.md b/docs/guides/cert-manager.md index 02f23b6c6d..f31e3116cc 100644 --- a/docs/guides/cert-manager.md +++ b/docs/guides/cert-manager.md @@ -124,6 +124,8 @@ apiVersion: extensions/v1beta1 kind: Ingress metadata: name: demo-yolo42-com + annotations: + kubernetes.io/ingress.class: kong spec: rules: - host: demo.yolo42.com @@ -190,6 +192,7 @@ metadata: annotations: kubernetes.io/tls-acme: "true" cert-manager.io/cluster-issuer: letsencrypt-prod + kubernetes.io/ingress.class: kong spec: tls: - secretName: demo-yolo42-com diff --git a/docs/guides/configure-acl-plugin.md b/docs/guides/configure-acl-plugin.md index 02209f66a4..d010fd7584 100644 --- a/docs/guides/configure-acl-plugin.md +++ b/docs/guides/configure-acl-plugin.md @@ -54,6 +54,7 @@ metadata: name: demo-get annotations: konghq.com/strip-path: "false" + kubernetes.io/ingress.class: kong spec: rules: - http: @@ -71,6 +72,7 @@ metadata: name: demo-post annotations: konghq.com/strip-path: "false" + kubernetes.io/ingress.class: kong spec: rules: - http: @@ -161,6 +163,7 @@ metadata: annotations: plugins.konghq.com: app-jwt konghq.com/strip-path: "false" + kubernetes.io/ingress.class: kong spec: rules: - http: @@ -179,6 +182,7 @@ metadata: annotations: plugins.konghq.com: app-jwt konghq.com/strip-path: "false" + kubernetes.io/ingress.class: kong spec: rules: - http: @@ -567,6 +571,7 @@ metadata: annotations: plugins.konghq.com: app-jwt,plain-user-acl konghq.com/strip-path: "false" + kubernetes.io/ingress.class: kong spec: rules: - http: @@ -585,6 +590,7 @@ metadata: annotations: plugins.konghq.com: app-jwt,admin-acl konghq.com/strip-path: "false" + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/configuring-fallback-service.md b/docs/guides/configuring-fallback-service.md index 81a04e4315..cfb25aae6d 100644 --- a/docs/guides/configuring-fallback-service.md +++ b/docs/guides/configuring-fallback-service.md @@ -56,6 +56,7 @@ metadata: name: demo annotations: konghq.com/strip-path: "true" + kubernetes.io/ingress.class: kong spec: rules: - http: @@ -104,6 +105,8 @@ apiVersion: extensions/v1beta1 kind: Ingress metadata: name: fallback + annotations: + kubernetes.io/ingress.class: kong spec: backend: serviceName: fallback-svc diff --git a/docs/guides/configuring-health-checks.md b/docs/guides/configuring-health-checks.md index 98ef3c676c..d85de3acbe 100644 --- a/docs/guides/configuring-health-checks.md +++ b/docs/guides/configuring-health-checks.md @@ -58,6 +58,7 @@ metadata: name: demo annotations: konghq.com/strip-path: "true" + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/configuring-https-redirect.md b/docs/guides/configuring-https-redirect.md index fdfd8797a6..848f485832 100644 --- a/docs/guides/configuring-https-redirect.md +++ b/docs/guides/configuring-https-redirect.md @@ -54,6 +54,7 @@ metadata: name: demo annotations: konghq.com/strip-path: "true" + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index da5faa49a5..bcaad76cff 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -53,6 +53,8 @@ apiVersion: extensions/v1beta1 kind: Ingress metadata: name: demo + annotations: + kubernetes.io/ingress.class: kong spec: rules: - http: @@ -122,6 +124,7 @@ metadata: name: demo-example-com annotations: konghq.com/plugins: request-id + kubernetes.io/ingress.class: kong spec: rules: - host: example.com diff --git a/docs/guides/prometheus-grafana.md b/docs/guides/prometheus-grafana.md index 89f580434e..846fcac769 100644 --- a/docs/guides/prometheus-grafana.md +++ b/docs/guides/prometheus-grafana.md @@ -201,6 +201,7 @@ metadata: name: sample-ingresses annotations: konghq.com/strip-path: "true" + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/redis-rate-limiting.md b/docs/guides/redis-rate-limiting.md index 16178a2f94..b25a2cd467 100644 --- a/docs/guides/redis-rate-limiting.md +++ b/docs/guides/redis-rate-limiting.md @@ -62,6 +62,7 @@ metadata: name: demo annotations: konghq.com/strip-path: "true" + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/using-consumer-credential-resource.md b/docs/guides/using-consumer-credential-resource.md index 1558657c2b..60c7151247 100644 --- a/docs/guides/using-consumer-credential-resource.md +++ b/docs/guides/using-consumer-credential-resource.md @@ -54,6 +54,7 @@ metadata: name: demo annotations: konghq.com/strip-path: "true" + kubernetes.io/ingress.class: kong spec: rules: - http: @@ -113,6 +114,7 @@ metadata: annotations: konghq.com/strip-path: "true" konghq.com/plugins: httpbin-auth + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/using-external-service.md b/docs/guides/using-external-service.md index de1c6092b2..c831cca5a0 100644 --- a/docs/guides/using-external-service.md +++ b/docs/guides/using-external-service.md @@ -59,6 +59,7 @@ metadata: name: proxy-from-k8s-to-httpbin annotations: konghq.com/strip-path: "true" + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/using-ingress-with-grpc.md b/docs/guides/using-ingress-with-grpc.md index 9b5a0f51b1..6dbb8e2065 100644 --- a/docs/guides/using-ingress-with-grpc.md +++ b/docs/guides/using-ingress-with-grpc.md @@ -50,6 +50,8 @@ $ echo "apiVersion: extensions/v1beta1 kind: Ingress metadata: name: demo + annotations: + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/using-kongclusterplugin-resource.md b/docs/guides/using-kongclusterplugin-resource.md index 3e695efa47..97fc4f1321 100644 --- a/docs/guides/using-kongclusterplugin-resource.md +++ b/docs/guides/using-kongclusterplugin-resource.md @@ -69,6 +69,7 @@ metadata: namespace: httpbin annotations: konghq.com/strip-path: "true" + kubernetes.io/ingress.class: kong spec: rules: - http: @@ -86,6 +87,8 @@ kind: Ingress metadata: name: echo-app namespace: echo + annotations: + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/using-kongingress-resource.md b/docs/guides/using-kongingress-resource.md index 133b32bb94..9550909286 100644 --- a/docs/guides/using-kongingress-resource.md +++ b/docs/guides/using-kongingress-resource.md @@ -53,6 +53,8 @@ apiVersion: extensions/v1beta1 kind: Ingress metadata: name: demo + annotations: + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/using-kongplugin-resource.md b/docs/guides/using-kongplugin-resource.md index a8cee9d506..91ecdc8ae7 100644 --- a/docs/guides/using-kongplugin-resource.md +++ b/docs/guides/using-kongplugin-resource.md @@ -64,6 +64,7 @@ metadata: name: demo annotations: konghq.com/strip-path: "true" + kubernetes.io/ingress.class: kong spec: rules: - http: @@ -130,6 +131,7 @@ metadata: name: demo-2 annotations: konghq.com/strip-path: "true" + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/using-mtls-auth-plugin.md b/docs/guides/using-mtls-auth-plugin.md index 608747db13..15282056fa 100644 --- a/docs/guides/using-mtls-auth-plugin.md +++ b/docs/guides/using-mtls-auth-plugin.md @@ -147,6 +147,7 @@ metadata: name: demo annotations: konghq.com/plugins: mtls-auth + kubernetes.io/ingress.class: kong spec: rules: - http: diff --git a/docs/guides/using-oidc-plugin.md b/docs/guides/using-oidc-plugin.md index 7eab05978b..24735dc31e 100644 --- a/docs/guides/using-oidc-plugin.md +++ b/docs/guides/using-oidc-plugin.md @@ -54,6 +54,8 @@ apiVersion: extensions/v1beta1 kind: Ingress metadata: name: demo + annotations: + kubernetes.io/ingress.class: kong spec: rules: - host: 192.0.2.8.xip.io diff --git a/docs/guides/using-rewrites.md b/docs/guides/using-rewrites.md index d192b96074..cce44092e6 100644 --- a/docs/guides/using-rewrites.md +++ b/docs/guides/using-rewrites.md @@ -84,6 +84,8 @@ kind: Ingress metadata: name: my-app namespace: echo + annotations: + kubernetes.io/ingress.class: kong spec: rules: - host: myapp.example.com diff --git a/docs/references/custom-resources.md b/docs/references/custom-resources.md index dfd0547ee0..97d4046ecb 100644 --- a/docs/references/custom-resources.md +++ b/docs/references/custom-resources.md @@ -119,6 +119,7 @@ metadata: name: demo-example-com annotations: plugins.konghq.com: request-id + kubernetes.io/ingress.class: kong spec: rules: - host: example.com From 1d983ce4dcbc505ee64f6e6a47b13393185e5bef Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 25 Aug 2020 12:42:05 -0700 Subject: [PATCH 05/20] doc: add class annotation to example KongConsumers Similar to 9897078 but for KongConsumer. Adds a "kubernetes.io/ingress.class: kong" annotation to KongConsumer resources in examples to conform to 0.10+ default behavior, which requires it. --- docs/deployment/admission-webhook.md | 4 ++++ docs/guides/configure-acl-plugin.md | 12 ++++++++++++ docs/guides/using-consumer-credential-resource.md | 4 ++++ docs/guides/using-kongplugin-resource.md | 1 + docs/references/custom-resources.md | 4 ++++ 5 files changed, 25 insertions(+) diff --git a/docs/deployment/admission-webhook.md b/docs/deployment/admission-webhook.md index 59bd22ea3d..e2c5573293 100644 --- a/docs/deployment/admission-webhook.md +++ b/docs/deployment/admission-webhook.md @@ -142,6 +142,8 @@ $ echo "apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: harry + annotations: + kubernetes.io/ingress.class: kong username: harry" | kubectl apply -f - kongconsumer.configuration.konghq.com/harry created ``` @@ -153,6 +155,8 @@ $ echo "apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: harry2 + annotations: + kubernetes.io/ingress.class: kong username: harry" | kubectl apply -f - Error from server: error when creating "STDIN": admission webhook "validations.kong.konghq.com" denied the request: consumer already exists ``` diff --git a/docs/guides/configure-acl-plugin.md b/docs/guides/configure-acl-plugin.md index d010fd7584..12be687b85 100644 --- a/docs/guides/configure-acl-plugin.md +++ b/docs/guides/configure-acl-plugin.md @@ -238,6 +238,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: admin + annotations: + kubernetes.io/ingress.class: kong username: admin " | kubectl apply -f - @@ -246,6 +248,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: plain-user + annotations: + kubernetes.io/ingress.class: kong username: plain-user " | kubectl apply -f - ``` @@ -303,6 +307,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: admin + annotations: + kubernetes.io/ingress.class: kong username: admin credentials: - app-admin-jwt @@ -313,6 +319,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: plain-user + annotations: + kubernetes.io/ingress.class: kong username: plain-user credentials: - app-user-jwt @@ -540,6 +548,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: admin + annotations: + kubernetes.io/ingress.class: kong username: admin credentials: - app-admin-jwt @@ -551,6 +561,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: plain-user + annotations: + kubernetes.io/ingress.class: kong username: plain-user credentials: - app-user-jwt diff --git a/docs/guides/using-consumer-credential-resource.md b/docs/guides/using-consumer-credential-resource.md index 60c7151247..fb540fdc08 100644 --- a/docs/guides/using-consumer-credential-resource.md +++ b/docs/guides/using-consumer-credential-resource.md @@ -154,6 +154,8 @@ $ echo "apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: harry + annotations: + kubernetes.io/ingress.class: kong username: harry" | kubectl apply -f - kongconsumer.configuration.konghq.com/harry created ``` @@ -187,6 +189,8 @@ $ echo "apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: harry + annotations: + kubernetes.io/ingress.class: kong username: harry credentials: - harry-apikey" | kubectl apply -f - diff --git a/docs/guides/using-kongplugin-resource.md b/docs/guides/using-kongplugin-resource.md index 91ecdc8ae7..c4cb9180e3 100644 --- a/docs/guides/using-kongplugin-resource.md +++ b/docs/guides/using-kongplugin-resource.md @@ -415,6 +415,7 @@ kind: KongConsumer metadata: name: harry annotations: + kubernetes.io/ingress.class: kong konghq.com/plugins: harry-rate-limit username: harry credentials: diff --git a/docs/references/custom-resources.md b/docs/references/custom-resources.md index 97d4046ecb..b72c213294 100644 --- a/docs/references/custom-resources.md +++ b/docs/references/custom-resources.md @@ -342,6 +342,8 @@ kind: KongConsumer metadata: name: namespace: + annotations: + kubernetes.io/ingress.class: kong username: custom_id: ``` @@ -353,6 +355,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongConsumer metadata: name: consumer-team-x + annotations: + kubernetes.io/ingress.class: kong username: team-X ``` From 9ef64aa470e2d3e7982a71e54439030c33bc44e3 Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 25 Aug 2020 12:48:12 -0700 Subject: [PATCH 06/20] doc: add ingress.class to TCPIngress examples --- docs/guides/using-tcpingress.md | 4 ++++ docs/references/custom-resources.md | 2 ++ 2 files changed, 6 insertions(+) diff --git a/docs/guides/using-tcpingress.md b/docs/guides/using-tcpingress.md index 56030cd867..284e4ff754 100644 --- a/docs/guides/using-tcpingress.md +++ b/docs/guides/using-tcpingress.md @@ -141,6 +141,8 @@ $ echo "apiVersion: configuration.konghq.com/v1beta1 kind: TCPIngress metadata: name: echo-plaintext + annotations: + kubernetes.io/ingress.class: kong spec: rules: - port: 9000 @@ -194,6 +196,8 @@ $ echo "apiVersion: configuration.konghq.com/v1beta1 kind: TCPIngress metadata: name: echo-tls + annotations: + kubernetes.io/ingress.class: kong spec: rules: - host: example.com diff --git a/docs/references/custom-resources.md b/docs/references/custom-resources.md index b72c213294..8a31332902 100644 --- a/docs/references/custom-resources.md +++ b/docs/references/custom-resources.md @@ -313,6 +313,8 @@ kind: TCPIngress metadata: name: namespace: + annotations: + kubernetes.io/ingress.class: kong spec: rules: - host: From e3daa368b210c0f5877f52baf6b6fd51057f3428 Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 25 Aug 2020 12:50:02 -0700 Subject: [PATCH 07/20] doc: add ingress.class to KongClusterPlugin examples --- docs/guides/prometheus-grafana.md | 2 ++ docs/guides/redis-rate-limiting.md | 4 ++++ docs/guides/using-kongclusterplugin-resource.md | 4 ++++ docs/guides/using-kongplugin-resource.md | 2 ++ docs/references/custom-resources.md | 2 ++ 5 files changed, 14 insertions(+) diff --git a/docs/guides/prometheus-grafana.md b/docs/guides/prometheus-grafana.md index 846fcac769..6227ea3e9d 100644 --- a/docs/guides/prometheus-grafana.md +++ b/docs/guides/prometheus-grafana.md @@ -116,6 +116,8 @@ $ echo 'apiVersion: configuration.konghq.com/v1 kind: KongClusterPlugin metadata: name: prometheus + annotations: + kubernetes.io/ingress.class: kong labels: global: "true" plugin: prometheus diff --git a/docs/guides/redis-rate-limiting.md b/docs/guides/redis-rate-limiting.md index b25a2cd467..385eb94c65 100644 --- a/docs/guides/redis-rate-limiting.md +++ b/docs/guides/redis-rate-limiting.md @@ -102,6 +102,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongClusterPlugin metadata: name: global-rate-limit + annotations: + kubernetes.io/ingress.class: kong labels: global: \"true\" config: @@ -187,6 +189,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongClusterPlugin metadata: name: global-rate-limit + annotations: + kubernetes.io/ingress.class: kong labels: global: \"true\" config: diff --git a/docs/guides/using-kongclusterplugin-resource.md b/docs/guides/using-kongclusterplugin-resource.md index 97fc4f1321..999a9418c2 100644 --- a/docs/guides/using-kongclusterplugin-resource.md +++ b/docs/guides/using-kongclusterplugin-resource.md @@ -148,6 +148,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongClusterPlugin metadata: name: add-response-header + annotations: + kubernetes.io/ingress.class: kong config: add: headers: @@ -230,6 +232,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongClusterPlugin metadata: name: add-response-header + annotations: + kubernetes.io/ingress.class: kong config: add: headers: diff --git a/docs/guides/using-kongplugin-resource.md b/docs/guides/using-kongplugin-resource.md index c4cb9180e3..7d82640d8c 100644 --- a/docs/guides/using-kongplugin-resource.md +++ b/docs/guides/using-kongplugin-resource.md @@ -338,6 +338,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongClusterPlugin metadata: name: global-rate-limit + annotations: + kubernetes.io/ingress.class: kong labels: global: \"true\" config: diff --git a/docs/references/custom-resources.md b/docs/references/custom-resources.md index 8a31332902..b4c16b6d21 100644 --- a/docs/references/custom-resources.md +++ b/docs/references/custom-resources.md @@ -183,6 +183,8 @@ apiVersion: configuration.konghq.com/v1 kind: KongClusterPlugin metadata: name: request-id + annotations: + kubernetes.io/ingress.class: kong labels: global: "true" # optional, if set, then the plugin will be executed # for every request that Kong proxies From e81e80a98073757227e7f07294fb5e08c86b7b7a Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 25 Aug 2020 12:51:35 -0700 Subject: [PATCH 08/20] doc: add ingress.class to CA certificate examples --- docs/guides/using-mtls-auth-plugin.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guides/using-mtls-auth-plugin.md b/docs/guides/using-mtls-auth-plugin.md index 15282056fa..dbbfd955d8 100644 --- a/docs/guides/using-mtls-auth-plugin.md +++ b/docs/guides/using-mtls-auth-plugin.md @@ -57,6 +57,8 @@ $ echo "apiVersion: v1 kind: Secret metadata: name: my-ca-cert + annotations: + kubernetes.io/ingress.class: kong labels: konghq.com/ca-cert: 'true' type: Opaque From bdc218f1342a2cfe4f330c393cc76e7d2f4c455c Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 25 Aug 2020 13:05:54 -0700 Subject: [PATCH 09/20] doc: use generic ingress class for some references Several examples in the custom resource reference use generic placeholder values for some fields. Align kubernetes.io/ingress.class example with this pattern for examples that use it. --- docs/references/custom-resources.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/references/custom-resources.md b/docs/references/custom-resources.md index b4c16b6d21..3c228bc44c 100644 --- a/docs/references/custom-resources.md +++ b/docs/references/custom-resources.md @@ -184,7 +184,7 @@ kind: KongClusterPlugin metadata: name: request-id annotations: - kubernetes.io/ingress.class: kong + kubernetes.io/ingress.class: labels: global: "true" # optional, if set, then the plugin will be executed # for every request that Kong proxies @@ -316,7 +316,7 @@ metadata: name: namespace: annotations: - kubernetes.io/ingress.class: kong + kubernetes.io/ingress.class: spec: rules: - host: @@ -347,7 +347,7 @@ metadata: name: namespace: annotations: - kubernetes.io/ingress.class: kong + kubernetes.io/ingress.class: username: custom_id: ``` From c9bdfc552c8755eef7e61152f7e782b080c3652e Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 25 Aug 2020 13:28:16 -0700 Subject: [PATCH 10/20] doc: call out required class annotations Indicate when the `kubernetes.io/ingress.class` annotation is required, and when that requirement can be disabled. Update mTLS instructions to use "must" for several requirements that previously said "should" although they were not actually optional. --- docs/concepts/custom-resources.md | 12 ++++++++ docs/guides/using-mtls-auth-plugin.md | 11 +++++--- docs/references/annotations.md | 40 +++++++++++++++++++++++---- 3 files changed, 54 insertions(+), 9 deletions(-) diff --git a/docs/concepts/custom-resources.md b/docs/concepts/custom-resources.md index 9af38039cb..f895cff107 100644 --- a/docs/concepts/custom-resources.md +++ b/docs/concepts/custom-resources.md @@ -73,6 +73,10 @@ The below diagram shows how the `KongPlugin` resource can be linked to an ## KongClusterPlugin +_This resource requires the `kubernetes.io/ingress.class` annotation. Its value +must match the value of the controller's `--ingress-class` argument, which is +"kong" by default._ + KongClusterPlugin resource is exactly same as KongPlugin, except that it is a Kubernetes cluster-level resources instead of being a namespaced resource. This can help when the configuration of the plugin needs to be centralized @@ -87,12 +91,20 @@ KongClusterPlugin with the same name. ## KongConsumer +_This resource requires the `kubernetes.io/ingress.class` annotation. Its value +must match the value of the controller's `--ingress-class` argument, which is +"kong" by default._ + This custom resource configures `Consumers` in Kong. Every `KongConsumer` resource in Kubernetes directly translates to a [Consumer][kong-consumer] object in Kong. ## TCPIngress +_This resource requires the `kubernetes.io/ingress.class` annotation. Its value +must match the value of the controller's `--ingress-class` argument, which is +"kong" by default._ + This Custom Resource is used for exposing non-HTTP and non-GRPC services running inside Kubernetes to the outside world via Kong. This proves to be useful when diff --git a/docs/guides/using-mtls-auth-plugin.md b/docs/guides/using-mtls-auth-plugin.md index dbbfd955d8..5b9867b906 100644 --- a/docs/guides/using-mtls-auth-plugin.md +++ b/docs/guides/using-mtls-auth-plugin.md @@ -42,11 +42,14 @@ This is expected as Kong does not yet know how to proxy the request. CA certificates in Kong are provisioned by create a `Secret` resource in Kubernetes. -The secret resource should have a few properties: -- It should have the `konghq.com/ca-cert: "true"` label. -- It should have a `cert` data property which contains a valid CA certificate +The secret resource must have a few properties: +- It must have the `konghq.com/ca-cert: "true"` label. +- It must have a `cert` data property which contains a valid CA certificate in PEM format. -- It should have an `id` data property which contains a random UUID. +- It must have an `id` data property which contains a random UUID. +- It must have a `kubernetes.io/ingress.class` annotation whose value matches + the value of the controller's `--ingress-class` argument. By default, that + value is "kong". Note that a self-signed CA certificate is being used for the purpose of this guide. You should use your own CA certificate that is backed by diff --git a/docs/references/annotations.md b/docs/references/annotations.md index b1d1f2f8fa..60ea9c441e 100644 --- a/docs/references/annotations.md +++ b/docs/references/annotations.md @@ -8,7 +8,7 @@ Following annotations are supported on Ingress resources: | Annotation name | Description | |-----------------|-------------| -| [`kubernetes.io/ingress.class`](#kubernetesioingressclass) | Restrict the Ingress rules that Kong should satisfy | +| REQUIRED [`kubernetes.io/ingress.class`](#kubernetesioingressclass) | Restrict the Ingress rules that Kong should satisfy | | [`konghq.com/plugins`](#konghqcomplugins) | Run plugins for specific Ingress. | | [`konghq.com/protocols`](#konghqcomprotocols) | Set protocols to handle for each Ingress resource. | | [`konghq.com/preserve-host`](#konghqcompreserve-host) | Pass the `host` header as is to the upstream service. | @@ -21,6 +21,16 @@ Following annotations are supported on Ingress resources: | DEPRECATED [`configuration.konghq.com`](#configurationkonghqcom) | Please use [`konghq.com/override`](#konghqcomoverride) | | DEPRECATED [`configuration.konghq.com/protocols`](#configurationkonghqcomprotocols) | Please use [`konghq.com/protocols`](#konghqcomprotocols) | +`kubernetes.io/ingress.class` is normally required, and its value should match +the value of the `--ingress-class` controller argument ("kong" by default). + +Passing `--process-classless-ingress-v1beta1=true` removes that requirement: +when enabled, the controller will process Ingresses with no +`kubernetes.io/ingress.class` annotation. Recommended best practice is to set +the annotation and leave this flag disabled; the flag is primarily intended for +older configurations, as controller versions prior to 0.10 processed classless +Ingress resources by default. + ## Service resource Following annotations are supported on Service resources: @@ -45,10 +55,20 @@ Following annotaitons are supported on KongConsumer resources: | Annotation name | Description | |-----------------|-------------| -| [`kubernetes.io/ingress.class`](#kubernetesioingressclass) | Restrict the KongConsumers that a controller should satisfy | +| REQUIRED [`kubernetes.io/ingress.class`](#kubernetesioingressclass) | Restrict the KongConsumers that a controller should satisfy | | [`konghq.com/plugins`](#konghqcomplugins) | Run plugins for a specific consumer | | DEPRECATED [`plugins.konghq.com`](#pluginskonghqcom) | Please use [`konghq.com/plugins`](#konghqcomplugins) | +`kubernetes.io/ingress.class` is normally required, and its value should match +the value of the `--ingress-class` controller argument ("kong" by default). + +Passing `process-classless-kong-consumer` removes that requirement: +when enabled, the controller will process KongConsumers with no +`kubernetes.io/ingress.class` annotation. Recommended best practice is to set +the annotation and leave this flag disabled; the flag is primarily intended for +older configurations, as controller versions prior to 0.10 processed classless +KongConsumer resources by default. + ## Annotations ### `kubernetes.io/ingress.class` @@ -90,9 +110,19 @@ metadata: will target Kong Ingress controller, forcing the GCE controller to ignore it. -> Deploying multiple ingress controller and not specifying the -annotation will cause both controllers fighting to satisfy the Ingress -and will lead to unknown behaviour. +Ingress, KongConsumer, TCPIngress, KongClusterPlugin, and Secret resources with +the `ca-cert` label _require_ this annotation by default. You can optionally +allow Ingress or KongConsumer resources with no class annotation (by setting +the `--process-classless-ingress-v1beta1` or +`--process-classless-kong-consumer` flags, respectively), though recommended +best practice is to leave these flags disabled: the flags are primarily +intended for compatibility with configuration created before this requirement +was introduced in controller 0.10. + +If you allow classless resources, you must take care when using multiple +controller instances in a single cluster: only one controller instance should +enable these flags to avoid different controller instances fighting over +classless resources, which will result in unexpected and unknown behavior. The ingress class used by Kong Ingress Controller to filter Ingress resources can be changed using the `CONTROLLER_INGRESS_CLASS` From 8a7abad8bd48e2f1e36fdadf29b92f7290931fa4 Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 25 Aug 2020 13:49:01 -0700 Subject: [PATCH 11/20] doc: use bulleted list for required class --- docs/references/annotations.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/references/annotations.md b/docs/references/annotations.md index 60ea9c441e..197bb101c0 100644 --- a/docs/references/annotations.md +++ b/docs/references/annotations.md @@ -110,10 +110,16 @@ metadata: will target Kong Ingress controller, forcing the GCE controller to ignore it. -Ingress, KongConsumer, TCPIngress, KongClusterPlugin, and Secret resources with -the `ca-cert` label _require_ this annotation by default. You can optionally -allow Ingress or KongConsumer resources with no class annotation (by setting -the `--process-classless-ingress-v1beta1` or +The following resources _require_ this annotation by default: + +- Ingress +- KongConsumer +- TCPIngress +- KongClusterPlugin +- Secret resources with the `ca-cert` label + +You can optionally allow Ingress or KongConsumer resources with no class +annotation (by setting the `--process-classless-ingress-v1beta1` or `--process-classless-kong-consumer` flags, respectively), though recommended best practice is to leave these flags disabled: the flags are primarily intended for compatibility with configuration created before this requirement From 07456c6814f9bfbd5f497c9987d2adf9469be0ae Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Fri, 28 Aug 2020 12:44:53 -0700 Subject: [PATCH 12/20] pr: apply review suggestions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Flendrich --- docs/concepts/custom-resources.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/concepts/custom-resources.md b/docs/concepts/custom-resources.md index f895cff107..dfeb8165e0 100644 --- a/docs/concepts/custom-resources.md +++ b/docs/concepts/custom-resources.md @@ -73,9 +73,7 @@ The below diagram shows how the `KongPlugin` resource can be linked to an ## KongClusterPlugin -_This resource requires the `kubernetes.io/ingress.class` annotation. Its value -must match the value of the controller's `--ingress-class` argument, which is -"kong" by default._ +_This resource requires the [`kubernetes.io/ingress.class` annotation](../README.md#resource-classes)._ KongClusterPlugin resource is exactly same as KongPlugin, except that it is a Kubernetes cluster-level resources instead of being a namespaced resource. From 86a71404f5bc5f171eb61e991dbc1b3df780b16e Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Fri, 28 Aug 2020 12:46:37 -0700 Subject: [PATCH 13/20] pr: apply review suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Flendrich --- docs/concepts/resource-classes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/resource-classes.md b/docs/concepts/resource-classes.md index baac25ec10..4eb0cd1c89 100644 --- a/docs/concepts/resource-classes.md +++ b/docs/concepts/resource-classes.md @@ -56,7 +56,7 @@ to indicate their class. There are several exceptions: You can optionally [override this on a per-Service basis][knative-override] by adding a `networking.knative.dev/ingress.class` annotation to the Service. -### Allowing resources without a class +### Enabling support for classless resources Specifying a class is optional for some resources. Although specifying a class is recommended, you can instruct the controller to process resources without a From 2c11361116ce3a703b631b51f0548d0154850701 Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Fri, 28 Aug 2020 15:26:14 -0700 Subject: [PATCH 14/20] pr: improve sentence style --- docs/concepts/custom-resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/custom-resources.md b/docs/concepts/custom-resources.md index dfeb8165e0..afa3ef4b4a 100644 --- a/docs/concepts/custom-resources.md +++ b/docs/concepts/custom-resources.md @@ -64,7 +64,7 @@ Once this resource is created, the resource needs to be associated with an `Ingress`, `Service`, or `KongConsumer` resource in Kubernetes. For more details, please read the reference documentation on `KongPlugin`. -The below diagram shows how the `KongPlugin` resource can be linked to an +The below diagram shows how you can link `KongPlugin` resource to an `Ingress`, `Service`, or `KongConsumer`: | | | From 2e2b56b44b7c1b04153201f3368034ca5a1bae9f Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Fri, 28 Aug 2020 16:03:15 -0700 Subject: [PATCH 15/20] pr: change resource class nomenclature --- docs/README.md | 4 +-- ...resource-classes.md => ingress-classes.md} | 26 +++++++++---------- 2 files changed, 15 insertions(+), 15 deletions(-) rename docs/concepts/{resource-classes.md => ingress-classes.md} (90%) diff --git a/docs/README.md b/docs/README.md index d09589c161..a1878c8807 100644 --- a/docs/README.md +++ b/docs/README.md @@ -49,9 +49,9 @@ and infrastructure. Please refer to [this document](concepts/ha-and-scaling.md) to understand failures scenarios, recovery methods, as well as scaling considerations. -### Resource classes +### Ingress classes -[Resource classes](concepts/resource-classes.md) filter which resources the +[Ingress classes](concepts/ingress-classes.md) filter which resources the controller loads. They ensure that Kong Ingress Controller instances do not load configuration intended for other instances or other ingress controllers. diff --git a/docs/concepts/resource-classes.md b/docs/concepts/ingress-classes.md similarity index 90% rename from docs/concepts/resource-classes.md rename to docs/concepts/ingress-classes.md index 4eb0cd1c89..1b8db3cedb 100644 --- a/docs/concepts/resource-classes.md +++ b/docs/concepts/ingress-classes.md @@ -1,30 +1,30 @@ -# Kong Ingress Controller and resource class +# Kong Ingress Controller and ingress class ## Table of Contents - [**Introduction**](#introduction) -- [**Configuring the controller class**](#configuring-the-controller-class) -- [**Kubernetes resource class**](#kubernetes-resource-class) -- [**When to use custom classes**](#when-to-use-custom-classes) +- [**Configuring the controller class**](#configuring-the-controller-ingress-class) +- [**Loading resources by class**](#loading-resouces-by-class) +- [**When to use a custom class**](#when-to-use-a-custom-class) - [**Legacy behavior**](#legacy-behavior) - [**Examples**](#examples) ## Introduction -The Kong Ingress Controller uses resource classes to filter Kubernetes Ingress +The Kong Ingress Controller uses ingress classes to filter Kubernetes Ingress objects and other resources before converting them into Kong configuration. This allows it to coexist with other ingress controllers and/or other deployments of the Kong Ingress Controller in the same cluster: a Kong Ingress Controller will only process configuration marked for its use. -## Configuring the controller class +## Configuring the controller ingress class The `--ingress-class` flag (or `CONTROLLER_INGRESS_CLASS` environment variable) -specify the resource class expected by the Kong Ingress Controller. By default, +specify the ingress class expected by the Kong Ingress Controller. By default, it expects the `kong` class. -## Kubernetes resource class +## Loading resources by class The Kong Ingress Controller translates a variety of Kubernetes resources into Kong configuration. Broadly speaking, we can separate these resources into two @@ -40,10 +40,10 @@ an authentication plugin credential is _not_ translated directly: it is only translated into Kong configuration if a KongConsumer resource references it. Because they create Kong configuration indenpendent of any other resources, -directly-translated resources require a class, and their class must match the -class configured for the controller. Referenced resources do not require a -class, but must be referenced by a directly-translated resource matches the -controller. +directly-translated resources require an ingress class, and their class must +match the class configured for the controller. Referenced resources do not +require a class, but must be referenced by a directly-translated resource +matches the controller. ### Adding class information to resources @@ -80,7 +80,7 @@ These flags do not _ignore_ `ingress.class` annotations: they allow resources with no such annotation, but will not allow resource that have a non-matching `ingress.class` annotation. -## When to use custom classes +## When to use a custom class Using the default `kong` class is fine for simpler deployments, where only one Kong Ingress Controller instance is running in a cluster. Changing the class is From 74fd96bc0a41f05a3e8c5cb38d038b4688281b41 Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 1 Sep 2020 15:38:15 -0700 Subject: [PATCH 16/20] pr: apply suggestions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Flendrich --- docs/concepts/ingress-classes.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/concepts/ingress-classes.md b/docs/concepts/ingress-classes.md index 1b8db3cedb..8c0a4aaea7 100644 --- a/docs/concepts/ingress-classes.md +++ b/docs/concepts/ingress-classes.md @@ -35,7 +35,7 @@ categories: directly translated into Kong configuration. For example, an Ingress is translated directly into a Kong route, and a -KongConsumer is translated directly into a Kong consumer. A Secret containing +KongConsumer is translated directly into a [Kong consumer](https://docs.konghq.com/latest/admin-api/#consumer-object). A Secret containing an authentication plugin credential is _not_ translated directly: it is only translated into Kong configuration if a KongConsumer resource references it. @@ -43,11 +43,11 @@ Because they create Kong configuration indenpendent of any other resources, directly-translated resources require an ingress class, and their class must match the class configured for the controller. Referenced resources do not require a class, but must be referenced by a directly-translated resource -matches the controller. +that matches the controller. ### Adding class information to resources -Most resources use a [kubernetes.io/ingress-class annoration][class-annotation] +Most resources use a [kubernetes.io/ingress-class annotation][class-annotation] to indicate their class. There are several exceptions: - v1 Ingress resources have a dedicated `class` field. @@ -68,7 +68,7 @@ class annotation using flags: KongConsumer resources with no class annotation. These flags are primarily intended for compatibility with older configuration -(older versions of the Kong Ingress Controller had less strict class +(Kong Ingress Controller before 0.10 had less strict class requirements, and it was common to omit class annotations). If you are creating new configuration and do not have older configuration without class annotations, recommended best practice is to add class information to Ingress @@ -112,7 +112,7 @@ custom classes: In versions 0.10.0+ you must instruct the controller to load classless resources, which is allowed (but not recommended) for either the default or -custom classess. Resources referenced by another resource are always loaded and +custom classes. Resources referenced by another resource are always loaded and updated correctly regardless of which class you set on the controller; you do not need to add class annotations to these resources when using a custom class. @@ -124,7 +124,7 @@ the following configuration for authenticating a request, using a KongConsumer, credential Secret, Ingress, and KongPlugin (a Service is implied, but not shown): -``` +```yaml kind: KongConsumer metadata: name: dyadya-styopa From cfd292b713326a99a6d1553f6fbca689a947f212 Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 1 Sep 2020 15:05:25 -0700 Subject: [PATCH 17/20] doc: clarify custom class cases --- docs/concepts/ingress-classes.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/concepts/ingress-classes.md b/docs/concepts/ingress-classes.md index 8c0a4aaea7..5b03acb012 100644 --- a/docs/concepts/ingress-classes.md +++ b/docs/concepts/ingress-classes.md @@ -86,12 +86,14 @@ Using the default `kong` class is fine for simpler deployments, where only one Kong Ingress Controller instance is running in a cluster. Changing the class is typical when: -- You install multiple Kong environments in one cluster to handle different - types of ingress traffic, e.g. when using separate Kong instances to handle - traffic on internal and external load balancers, or deploying different types - of non-production environments in a single test cluster. -- You install multiple controller instances that create configuration in - different Kong workspaces (using the `--kong-workspace` flag). +- You install multiple Kong environments in one Kubernetes cluster to handle + different types of ingress traffic, e.g. when using separate Kong instances + to handle traffic on internal and external load balancers, or deploying + different types of non-production environments in a single test cluster. +- You install multiple controller instances alongside a single Kong cluster to + separate configuration into different Kong workspaces (using the + `--kong-workspace` flag) or to restrict which Kubernetes namespaces any one + controller instance has access to. ## Legacy behavior From 8eb00b8368a3cc348054c783471fc9aeecf05ca9 Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 1 Sep 2020 17:37:55 -0700 Subject: [PATCH 18/20] pr: suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Flendrich --- docs/references/annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/annotations.md b/docs/references/annotations.md index 197bb101c0..74940d2d6b 100644 --- a/docs/references/annotations.md +++ b/docs/references/annotations.md @@ -24,7 +24,7 @@ Following annotations are supported on Ingress resources: `kubernetes.io/ingress.class` is normally required, and its value should match the value of the `--ingress-class` controller argument ("kong" by default). -Passing `--process-classless-ingress-v1beta1=true` removes that requirement: +Setting the `--process-classless-ingress-v1beta1` controller flag removes that requirement: when enabled, the controller will process Ingresses with no `kubernetes.io/ingress.class` annotation. Recommended best practice is to set the annotation and leave this flag disabled; the flag is primarily intended for From fd0f109e7ab89ea90534042be75ac816eb5e698d Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 1 Sep 2020 17:38:06 -0700 Subject: [PATCH 19/20] pr: suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Flendrich --- docs/references/annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/annotations.md b/docs/references/annotations.md index 74940d2d6b..505a16940a 100644 --- a/docs/references/annotations.md +++ b/docs/references/annotations.md @@ -27,7 +27,7 @@ the value of the `--ingress-class` controller argument ("kong" by default). Setting the `--process-classless-ingress-v1beta1` controller flag removes that requirement: when enabled, the controller will process Ingresses with no `kubernetes.io/ingress.class` annotation. Recommended best practice is to set -the annotation and leave this flag disabled; the flag is primarily intended for +the annotation and leave this flag disabled; the flag is intended for older configurations, as controller versions prior to 0.10 processed classless Ingress resources by default. From 206396916bc6d10d7ac7a8334d7ac96b28b4995e Mon Sep 17 00:00:00 2001 From: Travis Raines Date: Tue, 1 Sep 2020 17:38:26 -0700 Subject: [PATCH 20/20] pr: suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Flendrich --- docs/references/annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/annotations.md b/docs/references/annotations.md index 505a16940a..2a9ac8cd4e 100644 --- a/docs/references/annotations.md +++ b/docs/references/annotations.md @@ -62,7 +62,7 @@ Following annotaitons are supported on KongConsumer resources: `kubernetes.io/ingress.class` is normally required, and its value should match the value of the `--ingress-class` controller argument ("kong" by default). -Passing `process-classless-kong-consumer` removes that requirement: +Setting the `--process-classless-kong-consumer` controller flag removes that requirement: when enabled, the controller will process KongConsumers with no `kubernetes.io/ingress.class` annotation. Recommended best practice is to set the annotation and leave this flag disabled; the flag is primarily intended for