Configure a plugin for a specific HTTPRoute

Uses: Kong Operator

Deployment Platform

konnect

on-prem

Prerequisites

Kong Konnect

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
Set the personal access token as an environment variable:
```
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
```
Copied!

Kong Operator running

Add the Kong Helm charts:

helm repo add kong https://charts.konghq.com
helm repo update

Copied!

Install Kong Operator using Helm:
```
helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
  --set image.tag=2.1.0 \
  --set env.ENABLE_CONTROLLER_KONNECT=true
```
Copied!
```
helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
  --set image.tag=2.1.0
```
Copied!
If you want cert-manager to issue and rotate the admission and conversion webhook certificates, install cert-manager to your cluster and enable cert-manager integration by passing the following argument while installing, in the next step:
```
--set global.webhooks.options.certManager.enabled=true
```
Copied!
If you do not enable this, the chart will generate and inject self-signed certificates automatically. We recommend enabling cert-manager to manage the lifecycle of these certificates.

Kong Operator needs a certificate authority to sign the certificate for mTLS communication between the control plane and the data plane. This is handled automatically by the Helm chart. If you need to provide a custom CA certificate, refer to the certificateAuthority section in the values.yaml of the Helm chart to learn how to create and reference your own CA certificate.

This tutorial doesn’t require a license, but you can add one using KongLicense. This assumes that your license is available in ./license.json.

echo "
apiVersion: configuration.konghq.com/v1alpha1
kind: KongLicense
metadata:
 name: kong-license
rawLicenseString: '$(cat ./license.json)'
" | kubectl apply -f -

Copied!

Kong Operator running

Add the Kong Helm charts:

helm repo add kong https://charts.konghq.com
helm repo update

Copied!

Install Kong Operator using Helm:
```
helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
  --set image.tag=2.1.0 \
  --set env.ENABLE_CONTROLLER_KONNECT=true
```
Copied!
```
helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
  --set image.tag=2.1.0
```
Copied!
If you want cert-manager to issue and rotate the admission and conversion webhook certificates, install cert-manager to your cluster and enable cert-manager integration by passing the following argument while installing, in the next step:
```
--set global.webhooks.options.certManager.enabled=true
```
Copied!
If you do not enable this, the chart will generate and inject self-signed certificates automatically. We recommend enabling cert-manager to manage the lifecycle of these certificates.

Kong Operator needs a certificate authority to sign the certificate for mTLS communication between the control plane and the data plane. This is handled automatically by the Helm chart. If you need to provide a custom CA certificate, refer to the certificateAuthority section in the values.yaml of the Helm chart to learn how to create and reference your own CA certificate.

This tutorial doesn’t require a license, but you can add one using KongLicense. This assumes that your license is available in ./license.json.

echo "
apiVersion: configuration.konghq.com/v1alpha1
kind: KongLicense
metadata:
 name: kong-license
rawLicenseString: '$(cat ./license.json)'
" | kubectl apply -f -

Copied!

Create a KonnectAPIAuthConfiguration resource

kubectl create namespace kong --dry-run=client -o yaml | kubectl apply -f -
echo '
kind: KonnectAPIAuthConfiguration
apiVersion: konnect.konghq.com/v1alpha1
metadata:
  name: konnect-api-auth
  namespace: kong
spec:
  type: token
  token: "'$KONNECT_TOKEN'"
  serverURL: us.api.konghq.com
' | kubectl apply -f -

Copied!

Create a KonnectGatewayControlPlane resource

echo '
kind: KonnectGatewayControlPlane
apiVersion: konnect.konghq.com/v1alpha2
metadata:
  name: gateway-control-plane
  namespace: kong
spec:
  createControlPlaneRequest:
    name: gateway-control-plane
  konnect:
    authRef:
      name: konnect-api-auth
' | kubectl apply -f -

Copied!

Create Gateway resources

Create the kong namespace:

kubectl create namespace kong

Copied!

Create the GatewayConfiguration, GatewayClass, and Gateway resources with basic configuration:

echo '
apiVersion: gateway-operator.konghq.com/v2beta1
kind: GatewayConfiguration
metadata:
  name: gateway-configuration
  namespace: kong
spec:
  dataPlaneOptions:
    deployment:
      podTemplateSpec:
        spec:
          containers:
            - image: kong/kong-gateway:3.13
              name: proxy
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: gateway-class
spec:
  controllerName: konghq.com/gateway-operator
  parametersRef:
    group: gateway-operator.konghq.com
    kind: GatewayConfiguration
    name: gateway-configuration
    namespace: kong
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kong
  namespace: kong
spec:
  gatewayClassName: gateway-class
  listeners:
    - name: http
      port: 80
      protocol: HTTP' | kubectl apply -f -

Copied!

Create a Service and a Route

Run the following command to create a sample echo Service:

kubectl apply -f https://developer.konghq.com/manifests/kic/echo-service.yaml -n kong

Copied!

Create an HTTPRoute resource:

echo '
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo-route
  namespace: kong
spec:
  parentRefs:
    - name: kong
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /echo
      backendRefs:
        - name: echo
          kind: Service
          port: 1027' | kubectl apply -f -

Copied!

Create a KongPlugin

Regardless of the attachment method, you first need to define the plugin configuration using the KongPlugin CRD.

echo '
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: rate-limit-example
  namespace: kong
plugin: rate-limiting
config:
  minute: 5
  policy: local
' | kubectl apply -f -

Copied!

Apply the plugin to the HTTPRoute

The KongPluginBinding resource can be used when managing entities in Konnect or when using the Hybrid mode. It allows you to bind a plugin to one or more entities without modifying those entities.

For more details about the KongPluginBinding resources, see Understanding KongPluginBinding.

Use this method if you need to reuse the same plugin configuration across multiple Routes without editing each Route resource, or if you do not have permission to modify the Route.

echo '
apiVersion: configuration.konghq.com/v1alpha1
kind: KongPluginBinding
metadata:
  name: bind-rate-limit-to-route
  namespace: kong
spec:
  controlPlaneRef:
    type: konnectNamespacedRef
    konnectNamespacedRef:
      name: gateway-control-plane
  pluginRef:
    name: rate-limit-example
  targets:
    routeRef:
      group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: echo-route
' | kubectl apply -f -

Copied!

The Gateway API supports extending Route rules using filters. Kong Operator supports the ExtensionRef filter type to attach plugins directly to the HTTPRoute specification. This is the preferred method for standard Gateway API deployments.

echo '
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo-route
  namespace: kong
spec:
  parentRefs:
    - name: kong
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /echo
      filters:
        - type: ExtensionRef
          extensionRef:
            group: configuration.konghq.com
            kind: KongPlugin
            name: rate-limit-example
      backendRefs:
        - name: echo
          port: 1027' | kubectl apply -f -

Copied!

You can use the konghq.com/plugins annotation on the HTTPRoute resource:

echo '
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo-route
  namespace: kong
  annotations:
    konghq.com/plugins: rate-limit-example
spec:
  parentRefs:
    - name: kong
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /echo
      backendRefs:
        - name: echo
          port: 1027' | kubectl apply -f -

Copied!

This method is consistent with the Kong Ingress Controller behavior.

Validate

Get the proxy IP address:

export PROXY_IP=$(kubectl get gateway kong -n kong -o jsonpath='{.status.addresses[0].value}')

Copied!

Send multiple requests to the /echo endpoint:

for i in {1..6}; do curl -s http://$PROXY_IP/echo; done

Copied!

You should receive a 429 Too Many Requests status code with the last request.

Configure a plugin for a specific HTTPRoute

Prerequisites

Kong Konnect

Kong Operator running

Kong Operator running

Create a KonnectAPIAuthConfiguration resource

Create a KonnectGatewayControlPlane resource

Create Gateway resources

Create a Service and a Route

Create a KongPlugin

Apply the plugin to the HTTPRoute

Validate

Help us make these docs great!

Still need help