From 6c13ad5dee42992e945e6ca2775af33445712bef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patryk=20Ma=C5=82ek?= Date: Thu, 31 Oct 2024 15:52:59 +0100 Subject: [PATCH] kgo: kongpluginbinding guide --- app/_data/docs_nav_kgo_1.4.x.yml | 2 + app/_includes/md/kgo/check-condition.md | 2 +- .../md/kgo/konnect-entities-prerequisites.md | 2 +- .../guides/konnect-entities/dpcertificate.md | 1 - .../guides/konnect-entities/key-and-keyset.md | 18 +---- .../konnect-plugin-binding.md | 78 +++++++++++++------ .../konnect-entities/upstream-and-target.md | 2 +- .../guides/konnect-entities/vault.md | 19 +---- 8 files changed, 60 insertions(+), 64 deletions(-) rename app/_src/gateway-operator/guides/{ => konnect-entities}/konnect-plugin-binding.md (68%) diff --git a/app/_data/docs_nav_kgo_1.4.x.yml b/app/_data/docs_nav_kgo_1.4.x.yml index 73977593301..802b0df8a7a 100644 --- a/app/_data/docs_nav_kgo_1.4.x.yml +++ b/app/_data/docs_nav_kgo_1.4.x.yml @@ -129,6 +129,8 @@ items: url: /guides/konnect-entities/dpcertificate/ - text: Tagging and Labeling url: /guides/konnect-entities/tagging-and-labeling/ + - text: Managing Plugin Bindings by CRD + url: /guides/konnect-entities/konnect-plugin-binding/ - text: FAQ url: /guides/konnect-entities/faq/ - title: Reference diff --git a/app/_includes/md/kgo/check-condition.md b/app/_includes/md/kgo/check-condition.md index db54ba64a2e..79c57917326 100644 --- a/app/_includes/md/kgo/check-condition.md +++ b/app/_includes/md/kgo/check-condition.md @@ -14,7 +14,7 @@ kubectl get {{ kind | downcase }} {{ name }} -o=jsonpath='{.status.conditions[?( The output should look similar to this: -```console +```json { "observedGeneration": {{ generation }}, "reason": "{{ reason }}", diff --git a/app/_includes/md/kgo/konnect-entities-prerequisites.md b/app/_includes/md/kgo/konnect-entities-prerequisites.md index bf839a06cac..a6436153ab2 100644 --- a/app/_includes/md/kgo/konnect-entities-prerequisites.md +++ b/app/_includes/md/kgo/konnect-entities-prerequisites.md @@ -2,7 +2,7 @@
-

Before you create any Konnect entity, make sure you've installed {{site.kgo_product_name}} and created a valid KonnectAPIAuthConfiguration {% if include.with-control-plane %} and `KonnectGatewayControlPlane`{% endif %} in your cluster.

+

Before you create any Konnect entity, make sure you've installed {{site.kgo_product_name}} and created a valid KonnectAPIAuthConfiguration {% if include.with-control-plane %} and KonnectGatewayControlPlane{% endif %} in your cluster.

 diff --git a/app/_src/gateway-operator/guides/konnect-entities/dpcertificate.md b/app/_src/gateway-operator/guides/konnect-entities/dpcertificate.md index 5a9c6f94352..3fedfb39438 100644 --- a/app/_src/gateway-operator/guides/konnect-entities/dpcertificate.md +++ b/app/_src/gateway-operator/guides/konnect-entities/dpcertificate.md @@ -48,7 +48,6 @@ spec: ' | kubectl apply -f - ``` - {% include md/kgo/check-condition.md name='dp-cert' kind='KongDataPlaneClientCertificate' %} At this point, you should see the Data Plane Client Certificate in the Gateway Manager UI. diff --git a/app/_src/gateway-operator/guides/konnect-entities/key-and-keyset.md b/app/_src/gateway-operator/guides/konnect-entities/key-and-keyset.md index e0f28aa5d55..d87acf623fd 100644 --- a/app/_src/gateway-operator/guides/konnect-entities/key-and-keyset.md +++ b/app/_src/gateway-operator/guides/konnect-entities/key-and-keyset.md @@ -137,22 +137,6 @@ spec: ' | kubectl apply -f - ``` -You can verify the `KongKey` was successfully associated with the `KongKeySet` by checking its `KeySetRefValid` -condition. - -```shell -kubectl get kongkey key -o=jsonpath='{.status.conditions}' | jq '.[] | select(.type == "KeySetRefValid")' -``` - -The output should look similar to this: - -```console -{ - "observedGeneration": 2, - "reason": "Valid", - "status": "True", - "type": "KeySetRefValid" -} -``` +{% include md/kgo/check-condition.md name='key' kind='KongKey' conditionType='KeySetRefValid' reason='Valid' %} At this point, you should see the key associated with the key set in the Gateway Manager UI. diff --git a/app/_src/gateway-operator/guides/konnect-plugin-binding.md b/app/_src/gateway-operator/guides/konnect-entities/konnect-plugin-binding.md similarity index 68% rename from app/_src/gateway-operator/guides/konnect-plugin-binding.md rename to app/_src/gateway-operator/guides/konnect-entities/konnect-plugin-binding.md index 07e7ba0b686..166b0ff052a 100644 --- a/app/_src/gateway-operator/guides/konnect-plugin-binding.md +++ b/app/_src/gateway-operator/guides/konnect-entities/konnect-plugin-binding.md @@ -2,20 +2,26 @@ title: Managing Plugin Bindings by CRD --- -The `KongPluginBinding` is the CRD used to manage the binding relationship between plugins and attached Konnect entities, including services, routes, consumers, and consumer groups, or a supported combination of these entities. +In this guide you'll learn how to use the `KongPluginBinding` to bind plugins to {{site.konnect_short_name }} entities +from within your Kubernetes cluster. -### Introduction of `KongPluginBinding` CRD +{% include md/kgo/konnect-entities-prerequisites.md disable_accordian=false version=page.version release=page.release +with-control-plane=true %} -A `KongPluginBinding` resource describes a binding relationship between a plugin and an attached entity or a combination of possible entities. It has two parts for the binding description in its specification: `spec.pluginRef` to refer to a `KongPlugin` resource which contains the plugin name and configuration of the plugin, and `spec.targets` to refer to the entity or combination of entities that the plugin attached to. The `spec.controlPlaneRef` refers to the {{site.konnect_product_name}} control plane this `KongPluginBinding` is associated with. +## Introduction of `KongPluginBinding` CRD -### Using an Unmanaged `KongPluginBinding` +The `KongPluginBinding` is the CRD used to manage the binding relationship between plugins and attached {{site.konnect_short_name}} entities, including services, routes, consumers, and consumer groups, or a supported combination of these entities. + +It has two parts for the binding description in its specification: `spec.pluginRef` to refer to a `KongPlugin` resource which contains the plugin name and configuration of the plugin, and `spec.targets` to refer to the entity or combination of entities that the plugin attached to. +The `spec.controlPlaneRef` refers to the {{site.konnect_product_name}} control plane this `KongPluginBinding` is associated with. + +## Using an unmanaged `KongPluginBinding` You can directly create a `KongPluginBinding` to bind your plugin to a Konnect entity. Assume that you have an existing and programmed `KonnectGatewayControlPlane` with the name `cp` in the `default` namespace. First, create a service and a plugin by `KongService` and `KongPlugin` CRD: ```bash -# Create a KongService for a service in Konnect echo ' kind: KongService apiVersion: configuration.konghq.com/v1alpha1 @@ -28,13 +34,12 @@ spec: type: konnectNamespacedRef konnectNamespacedRef: name: cp -' | kubectl apply -f - +' | kubectl apply -f - ``` Then, create a `KongPlugin`: ```bash -# Create a KongPlugin echo ' kind: KongPlugin apiVersion: configuration.konghq.com/v1 @@ -45,7 +50,7 @@ plugin: rate-limiting config: policy: local minute: 10 -' | kubectl apply -f - +' | kubectl apply -f - ``` And you can create a `KongPluginBinding` to bind them together. @@ -70,20 +75,23 @@ spec: type: konnectNamespacedRef konnectNamespacedRef: name: cp -' | kubectl apply -f - +' | kubectl apply -f - ``` Then the plugin will be successfully attached to the service in {{ site.konnect_short_name }}. -#### Attaching plugins to multiple entities +### Attaching plugins to multiple entities + +{{ site.kgo_product_name }} also supports to attach plugins to combination of multiple entities by `KongPluginBinding`. +Supported combinations includes: -{{ site.kgo_product_name }} also supports to attach plugins to combination of multiple entities by `KongPluginBinding`. Supported combinations includes: -* `Service` and `Route`; +* `Service` and `Route` * `Service` and `Consumer` * `Service` and `ConsumerGroup` * `Service`, `Route` and `Consumer` -* `Service`, `Route` and `ConsumerGroup` -* `Consumer` and `ConsumerGroup`. +* `Service`, `Route` and `ConsumerGroup` +* `Consumer` and `ConsumerGroup` + For example, we can configure a `rate-limiting` plugin to a service and a consumer like this: Create a service: @@ -101,7 +109,7 @@ spec: type: konnectNamespacedRef konnectNamespacedRef: name: cp -' | kubectl apply -f - +' | kubectl apply -f - ``` Create a consumer: @@ -135,7 +143,7 @@ plugin: rate-limiting config: policy: local minute: 10 -' | kubectl apply -f - +' | kubectl apply -f - ``` Then, you can create a `KongPluginBinding` including both references to the `KongService` and the `KongCosumer` to attach the plugin to the service and the consumer: @@ -162,12 +170,17 @@ spec: type: konnectNamespacedRef konnectNamespacedRef: name: cp -' | kubectl apply -f - +' | kubectl apply -f - ``` -### Using annotations to bind plugins to other entities +## Using annotations to bind plugins to other entities + +{:.note} +> **NOTE:** This approach is considered legacy and using `KongPluginBinding` CRD is recommended instead. +> Users can expect that `konghq.com/plugins` annotation support will be removed at some point in the future. -You can also use the `konghq.com/plugins` annotation to attach plugins to other entities like what we used in {{ site.kic_product_name }}. The {{ site.kgo_product_name }} will create `KongPluginBinding` resources for the annotations and configure them in {{ site.konnect_short_name }}. +You can also use the `konghq.com/plugins` annotation to attach plugins to other entities like it's done in {{ site.kic_product_name }}. +The {{ site.kgo_product_name }} will create `KongPluginBinding` resources for the annotations and configure them in {{ site.konnect_short_name }}. In the example above, you can create a `KongPlugin` and a `KongService` like this: @@ -203,17 +216,32 @@ spec: ' | kubectl apply -f - ``` -Then you can also see the plugin is attached to the service in {{ site.konnect_short_name }}. You can also check the `KongPluginBinding` resource by `kubectl get kongpluginbindings`. You can see the created `KongPluginBinding` like: +At this point you can see the plugin is attached to the service in {{ site.konnect_short_name }}. -``` +You can also check the `KongPluginBinding` resource by running. + +```terminal kubectl get kongpluginbinding +``` + +You can see the created `KongPluginBinding` like this: + +```terminal NAME PLUGIN-KIND PLUGIN-NAME PROGRAMMED rate-limiting-minute-10-a0z1x KongPlugin rate-limiting-minute-10 True ``` -#### Attaching plugins to multiple entities +### Attaching plugins to multiple entities + +{:.note} +> **NOTE:** Binding plugins with this approach has limited observability and can yield unexpected results +> when multiple different resources are attached to the same plugin +> (e.g. a service already has a plugin attached to it and we're annotating consumer with the same plugin). +> Users are advised to use `KongPluginBinding` CRD instead for better control and auditability. -Similar to those introduced above, you can also attach a plugin to multiple entities by configuring annotations of attached entities. If a plugin appears in the `konghq.com/plugins` annotation of multiple entities, a `KongPluginBinding` will be created for the binding relationship between the plugin and the combination of these entities. Taking the example above where a plugin is attached to a service and a consumer: +Similar to those introduced above, you can also attach a plugin to multiple entities by configuring annotations of attached entities. +If a plugin appears in the `konghq.com/plugins` annotation of multiple entities, a `KongPluginBinding` will be created for the binding relationship between the plugin and the combination of these entities. +Taking the example above where a plugin is attached to a service and a consumer: ```bash echo ' @@ -226,7 +254,7 @@ plugin: rate-limiting config: policy: local minute: 10 -' | kubectl apply -f - +' | kubectl apply -f - ``` ```bash @@ -297,4 +325,4 @@ spec: group: configuration.konghq.com kind: KongService name: service-plugin-binding-combination -``` \ No newline at end of file +``` diff --git a/app/_src/gateway-operator/guides/konnect-entities/upstream-and-target.md b/app/_src/gateway-operator/guides/konnect-entities/upstream-and-target.md index b1cb3a9ba37..764e5aa1b24 100644 --- a/app/_src/gateway-operator/guides/konnect-entities/upstream-and-target.md +++ b/app/_src/gateway-operator/guides/konnect-entities/upstream-and-target.md @@ -1,5 +1,5 @@ --- -title: Upstream and Target +title: Upstream and Target --- In this guide you'll learn how to use the `KongUpstream` and `KongTarget` custom resources to diff --git a/app/_src/gateway-operator/guides/konnect-entities/vault.md b/app/_src/gateway-operator/guides/konnect-entities/vault.md index 95702cb1e72..ad6cfb1f757 100644 --- a/app/_src/gateway-operator/guides/konnect-entities/vault.md +++ b/app/_src/gateway-operator/guides/konnect-entities/vault.md @@ -38,21 +38,4 @@ spec: ' | kubectl apply -f - ``` -You can verify the `KongVault` was reconciled successfully by checking its `Programmed` condition. - -```shell -kubectl get kongvault env-vault -o=jsonpath='{.status.conditions}' | jq '.[] | select(.type == "Programmed")' -``` - -The output should look similar to this: - -```console -{ - "observedGeneration": 1, - "reason": "Programmed", - "status": "True", - "type": "Programmed" -} -``` - -At this point, you should see the Vault in the Gateway Manager UI. +{% include md/kgo/check-condition.md name='env-vault' kind='KongVault' %}