Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

KGO: add guide for kongpluginbinding #8049

Merged
merged 5 commits into from
Oct 31, 2024
Merged

KGO: add guide for kongpluginbinding #8049

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
230922b
add guide for kongpluginbinding
randmonkey Oct 14, 2024
9d41632
add docs for entities combination
randmonkey Oct 14, 2024
e345348
Apply suggestions from code review
pmalek Oct 31, 2024
68d933d
Apply suggestions from code review
pmalek Oct 31, 2024
9384c6e
Update app/_src/gateway-operator/guides/konnect-plugin-binding.md
pmalek Oct 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
300 changes: 300 additions & 0 deletions app/_src/gateway-operator/guides/konnect-plugin-binding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,300 @@
---
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.

### Introduction of `KongPluginBinding` CRD

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.

### 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
metadata:
namespace: default
name: service-example
spec:
host: example.com
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: cp
' | kubectl apply -f -
```

Then, create a `KongPlugin`:

```bash
# Create a KongPlugin
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 -
```

And you can create a `KongPluginBinding` to bind them together.

```bash
echo '
kind: KongPluginBinding
apiVersion: configuration.konghq.com/v1alpha1
metadata:
namespace: default
name: binding-service-example-rate-limiting
spec:
pluginRef:
kind: KongPlugin
name: rate-limiting-minute-10
targets:
serviceRef:
group: configuration.konghq.com
kind: KongService
name: service-example
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: cp
' | kubectl apply -f -
```

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

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 }}.
pmalek marked this conversation as resolved.
Show resolved Hide resolved

In the example above, you can create a `KongPlugin` and a `KongService` like this:

```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-example
annotations:
konghq.com/plugins: rate-limiting-minute-10
spec:
host: example.com
controlPlaneRef:
type: konnectNamespacedRef
konnectNamespacedRef:
name: cp
' | 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:

```
kubectl get kongpluginbinding
NAME PLUGIN-KIND PLUGIN-NAME PROGRAMMED
rate-limiting-minute-10-a0z1x KongPlugin rate-limiting-minute-10 True
```

#### Attaching plugins to multiple entities

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 '
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
```
Loading