kgo: kongpluginbinding guide

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

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 }}",

app/_includes/md/kgo/konnect-entities-prerequisites.md

@@ -2,7 +2,7 @@
 <details class="custom" markdown="1">
 <summary>
 <blockquote class="note">
-  <p style="cursor: pointer">Before you create any Konnect entity, make sure you've <u>installed {{site.kgo_product_name}} and created a valid KonnectAPIAuthConfiguration {% if include.with-control-plane %} and `KonnectGatewayControlPlane`{% endif %}</u> in your cluster.</p>
+  <p style="cursor: pointer">Before you create any Konnect entity, make sure you've <u>installed {{site.kgo_product_name}} and created a valid KonnectAPIAuthConfiguration {% if include.with-control-plane %} and KonnectGatewayControlPlane{% endif %}</u> in your cluster.</p>
 </blockquote>
 </summary>
 

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.

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.

app/_src/gateway-operator/guides/konnect-plugin-binding.md → 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
@@ -34,7 +40,6 @@ spec:
 Then, create a `KongPlugin`:
 
 ```bash
-# Create a KongPlugin
 echo '
 kind: KongPlugin
 apiVersion: configuration.konghq.com/v1
@@ -75,15 +80,18 @@ spec:
 
 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
 
-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 }}.
+{:.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 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
-```
+```

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

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' %}