Home / Kong Operator / Gateway Deployment / How-To
Edit
Report

Manage Consumers and credentials with Kong Operator

Uses: Kong Operator
Deployment Platform
Related Documentation
Operator Documentation
Related Resources
Consumer entity
Key Authentication plugin
TL;DR

Create a KongConsumer resource and link it to a Kubernetes Secret containing the credentials.

Prerequisites

Kong Konnect

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

  1. 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.

  2. Set the personal access token as an environment variable:

    export KONNECT_TOKEN='YOUR KONNECT TOKEN'

Kong Operator running

  1. Add the Kong Helm charts:

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

  2. Install Kong Operator using Helm:

    helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
  --set image.tag=2.3 \
  --set env.ENABLE_CONTROLLER_KONNECT=true
  kubectl -n kong-system wait --for=condition=Available=true --timeout=300s deployment/kong-operator-kong-operator-controller-manager
    helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
   --set image.tag=2.3
  kubectl -n kong-system wait --for=condition=Available=true --timeout=300s deployment/kong-operator-kong-operator-controller-manager

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

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.

Apply a 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 -

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 -

Create Gateway resources

Create the kong namespace:

kubectl create namespace kong

Create the kong namespace:

kubectl create namespace kong --dry-run=client -o yaml | kubectl apply -f -

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

Setting spec.konnect.authRef attaches the data plane to Konnect, which manages its configuration:

echo '
apiVersion: gateway-operator.konghq.com/v2beta1
kind: GatewayConfiguration
metadata:
  name: gateway-configuration
  namespace: kong
spec:
  konnect:
    authRef:
      name: konnect-api-auth
      namespace: kong
  dataPlaneOptions:
    deployment:
      podTemplateSpec:
        spec:
          containers:
            - image: kong/kong-gateway:3.16
              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
  annotations:
    gateway-operator.konghq.com/static-naming: "true"
spec:
  gatewayClassName: gateway-class
  listeners:
    - name: http
      port: 80
      protocol: HTTP' | kubectl apply -f -

The gateway-operator.konghq.com/static-naming: "true" annotation gives the resources Kong Operator generates for the Gateway static, predictable names: the KonnectGatewayControlPlane it creates for the Gateway is named after the Gateway, in this case kong. You can reference that control plane from other resources before it exists, and its name in Konnect is derived from the Gateway name.

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.16
              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 -

Create the echo Service

Run the following command to create a sample echo Service:

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

Configure the Key Authentication plugin

First, create a KongPlugin resource to enable key authentication:

echo '
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: key-auth
  namespace: kong
plugin: key-auth
config:
  key_names:
  - apikey
' | kubectl apply -f -

Create the HTTPRoute

Create an HTTPRoute resource and add the plugin using an ExtensionRef filter:

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

Create a Secret

Create a Kubernetes Secret to store the API key and label the secret with konghq.com/credential: key-auth:

echo '
apiVersion: v1
kind: Secret
metadata:
  name: test-user-apikey
  namespace: kong
  labels:
    konghq.com/credential: key-auth
    konghq.com/secret: "true"
stringData:
  key: secret-api-key
' | kubectl apply -f -

For more information on how Kong Operator handles Secrets, please refer to the Secrets reference

Create a Consumer

Create a KongConsumer resource to represent the user, and reference the test-user-apikey Secret we created:

echo '
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: test-user
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
username: test-user
credentials:
- test-user-apikey
' | kubectl apply -f -
echo '
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: test-user
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
username: test-user
spec:
  controlPlaneRef:
    type: konnectNamespacedRef
    konnectNamespacedRef:
      name: kong
credentials:
- test-user-apikey
' | kubectl apply -f -

The Gateway you created in the prerequisites uses the gateway-operator.konghq.com/static-naming annotation, so the KonnectGatewayControlPlane Kong Operator creates for it is named after the Gateway, kong. See static naming.

Validate

  1. Wait for the Gateway to be programmed:

    kubectl wait --for=condition=Programmed gateway/kong -n kong --timeout=5m

  2. Get the Gateway’s external IP:

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

  3. Try to access the Route without a key:

    curl -i "http://$PROXY_IP/echo" \
     --no-progress-meter --fail-with-body 
    curl -i "http://$PROXY_IP/echo" \
     --no-progress-meter --fail-with-body

    You should receive a 401 Unauthorized response.

  4. Access the route with the API key in the apikey header:

    curl -i "http://$PROXY_IP/echo" \
     --no-progress-meter --fail-with-body  \
     -H "apikey: secret-api-key"
    curl -i "http://$PROXY_IP/echo" \
     --no-progress-meter --fail-with-body  \
     -H "apikey: secret-api-key"

    You should receive a 200 OK response from the echo service.

Cleanup

Delete the resources created in this guide

Deleting the Gateway also deletes the control plane and data plane resources Kong Operator created for it. Deleting the kong-system namespace removes the operator:

kubectl delete -n kong --ignore-not-found \
  kongconsumer/test-user \
  secret/test-user-apikey \
  kongplugin/key-auth \
  httproute/echo-route \
  service/echo \
  gateway/kong \
  gatewayconfiguration/gateway-configuration
kubectl delete --ignore-not-found gatewayclass/gateway-class
kubectl delete --ignore-not-found namespace kong
helm uninstall kong-operator -n kong-system
kubectl delete --ignore-not-found namespace kong-system
Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help?

Ask in our Slack Community
Contact Support