add docs for entities combination

Kong · Oct 29, 2024 · 2c33a63 · 2c33a63
1 parent b376ec0
commit 2c33a63
Showing 1 changed file with 178 additions and 7 deletions.
diff --git a/app/_src/gateway-operator/guides/konnect-plugin-binding.md b/app/_src/gateway-operator/guides/konnect-plugin-binding.md
@@ -2,15 +2,15 @@
 title: Managing Plugin Bindings by CRD
 ---
 
-The `KongPluginBinding` is the CRD used to manage binding relationship between plugins and attached Konnect entities, including services, routes, consumers and consumer groups, or supported comblination of these entities.
+The `KongPluginBinding` is the CRD used to manage binding relationship between plugins and attached Konnect entities, including services, routes, consumers and consumer groups, or supported combination of these entities.
 
 ### Introduction of `KongPluginBinding` CRD
 
 A `KongPluginBinding` resource describes a binding relationship of a plugin and an attached entity or a combination of possible entities. It has two parts for describing the binding 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 Konnect ControlPlane this KongPluginBinding is associated with.
 
-### Using an Unmannaged `KongPluginBinding`
+### 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 name `cp` in `default` namespace.
+You can directly create a `KongPluginBinding` to bind your plugin to a Konnect entity. Assume that you have an existing and programmed `KonnectGatewayControlPlane` with name `cp` in the `default` namespace.
 
 First, Create a service and a plugin by `KongService` and `KongPlugin` CRD:
 
@@ -48,7 +48,7 @@ config:
 ' | kubectl apply -f - 
 ```
 
-And we can create a `KongPluginBinding` to bind them together.
+And you can create a `KongPluginBinding` to bind them together.
 
 ```bash
 echo '
@@ -75,11 +75,94 @@ spec:
 
 Then the plugin will be successfully attached to the service in {{ site.konnect_short_name }}.
 
+#### Attaching Plugins to Multiple Entities
+
+{{ site.kgo_product_name }} also supports to attach plugins to combination of multiple entities by `KongPluginBinding`. Supported combinations includes: `Service` and `Route`; `Service` and `Consumer`; `Service` and `ConsumerGroup`; `Service`, `Route` and `Consumer`; `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:
+
+```bash
+echo '
+kind: KongService
+apiVersion: configuration.konghq.com/v1alpha1
+metadata:
+  namespace: default
+  name: service-plugin-binding-combination
+spec:
+  host: example.com
+  controlPlaneRef:
+    type: konnectNamespacedRef
+    konnectNamespacedRef:
+      name: cp
+' | kubectl apply -f - 
+```
+
+Create a consumer:
+
+```bash
+echo '
+kind: KongConsumer
+apiVersion: configuration.konghq.com/v1
+metadata:
+  namespace: default
+  name: consumer-plugin-binding-combination
+username: consumer-test
+spec:
+  controlPlaneRef:
+    type: konnectNamespacedRef
+    konnectNamespacedRef:
+      name: cp
+' | kubectl apply -f -
+```
+
+Create a plugin:
+
+```bash
+echo '
+kind: KongPlugin
+apiVersion: configuration.konghq.com/v1
+metadata:
+  namespace: default
+  name: rate-limiting-minute-10
+plugin: rate-limiting
+config:
+  policy: local
+  minute: 10
+' | 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:
+
+```bash
+echo '
+kind: KongPluginBinding
+apiVersion: configuration.konghq.com/v1alpha1
+metadata:
+  namespace: default
+  name: binding-combination-service-consumer
+spec:
+  pluginRef:
+    kind: KongPlugin
+    name: rate-limiting-minute-10
+  targets:
+    serviceRef:
+      group: configuration.konghq.com
+      kind: KongService
+      name: service-plugin-binding-combination
+    consumerRef:
+      name: consumer-plugin-binding-combination
+  controlPlaneRef:
+    type: konnectNamespacedRef
+    konnectNamespacedRef:
+      name: cp
+' | kubectl apply -f - 
+```
+
 ### Using Annotations to Bind Plugins to Other Entities
 
-We 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 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 }}.
 
-For the example above, we can create a `KongPlugin` and a `KongService` like this:
+For the example above, you can create a `KongPlugin` and a `KongService` like this:
 
 ```bash
 echo '
@@ -118,5 +201,93 @@ Then you can also see the plugin is attached to the service in {{ site.konnect_s
 ```
 kubectl get kongpluginbinding
 NAME                            PLUGIN-KIND   PLUGIN-NAME                  PROGRAMMED
-rate-limiting-minute-10-r4xvt   KongPlugin    rate-limiting-minute-10      True
+rate-limiting-minute-10-a0z1x   KongPlugin    rate-limiting-minute-10      True
+```
+
+#### Attaching Plugins to Multiple Entities
+
+Similar to introduced above, you can also attach a plugin to multiple entities by configuring annotations of attached entities. If a plugin appeared 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 '
+kind: KongPlugin
+apiVersion: configuration.konghq.com/v1
+metadata:
+  namespace: default
+  name: rate-limiting-minute-10
+plugin: rate-limiting
+config:
+  policy: local
+  minute: 10
+' | kubectl apply -f - 
+```
+
+```bash
+echo '
+kind: KongService
+apiVersion: configuration.konghq.com/v1alpha1
+metadata:
+  namespace: default
+  name: service-plugin-binding-combination
+  annotations:
+    konghq.com/plugins: rate-limiting-minute-10
+spec:
+  host: example.com
+  controlPlaneRef:
+    type: konnectNamespacedRef
+    konnectNamespacedRef:
+      name: cp
+' | kubectl apply -f -
 ```
+
+```bash
+echo '
+kind: KongConsumer
+apiVersion: configuration.konghq.com/v1
+metadata:
+  namespace: default
+  name: consumer-plugin-binding-combination
+  annotations:
+    konghq.com/plugins: rate-limiting-minute-10
+username: consumer-test
+spec:
+  controlPlaneRef:
+    type: konnectNamespacedRef
+    konnectNamespacedRef:
+      name: cp
+' | kubectl apply -f -
+```
+
+A `KongPluginBinding` with both `serviceRef` and `consumerRef` in its `spec.targets` will be created like:
+
+```yaml
+apiVersion: configuration.konghq.com/v1alpha1
+kind: KongPluginBinding
+metadata:
+  creationTimestamp: "2024-10-14T07:14:05Z"
+  generateName: rate-limiting-minute-10-
+  name: rate-limiting-minute-10-xyz98
+  namespace: default
+  ownerReferences:
+  - apiVersion: configuration.konghq.com/v1
+    blockOwnerDeletion: true
+    kind: KongPlugin
+    name: rate-limiting-minute-10
+    uid: 01234567-89ab-cdef-fdec-ba9876543210
+spec:
+  controlPlaneRef:
+    konnectNamespacedRef:
+      name: test1
+      namespace: default
+    type: konnectNamespacedRef
+  pluginRef:
+    kind: KongPlugin
+    name: rate-limiting-minute-10
+  targets:
+    consumerRef:
+      name: consumer-plugin-binding-combination
+    serviceRef:
+      group: configuration.konghq.com
+      kind: KongService
+      name: service-plugin-binding-combination
+```