Home / Kong Operator / Konnect
Edit
Report

Reference Secrets across multiple namespaces with Kong Operator

Uses: Kong Operator
Deployment Platform
Related Documentation
Operator Documentation
Related Resources
Reference Konnect authentication across multiple namespaces
Minimum Version
Kong Operator - 2.1
TL;DR

Use a ReferenceGrant for Gateway API resources or a KongReferenceGrant for Kong-specific resources in the same namespace as the Secret to authorize references from the source namespace.

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 -

By default, Kong Operator restricts references to resources within the same namespace for security. To enable cross-namespace references, you must use one of the following resources in the target namespace:

  • ReferenceGrant: A standard Kubernetes Gateway API resource used for authorizing references from Gateway API resources to other resources.
  • KongReferenceGrant: A Kong-specific resource used for authorizing references from Kong resources to other resources.

This example demonstrates using both ReferenceGrant and KongReferenceGrant to allow a Gateway in the kong namespace to reference a TLS Secret in the secret-ns namespace.

Create a certificate

Run the following command to create a self-signed certificate:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=example.localdomain.dev"

Create a Secret

Run the following command to create a secret-ns namespace and a Secret resource containing the TLS certificate and key in that namespace:

echo "
apiVersion: v1
kind: Namespace
metadata:
  name: secret-ns
---
apiVersion: v1
kind: Secret
metadata:
  name: example-tls-secret
  namespace: secret-ns
  labels:
    konghq.com/secret: 'true'
type: kubernetes.io/tls
data:
  tls.crt: "$(cat tls.crt | base64 | tr -d '\n')"
  tls.key: "$(cat tls.key | base64 | tr -d '\n')"" | kubectl apply -f -

Create a ReferenceGrant and a KongReferenceGrant

Create the following resources:

  • A ReferenceGrant to allow standard Gateway API resources in other namespaces to access the Secret. In this example, we’ll grant access to Gateway resources in the kong namespace.
  • A KongReferenceGrant to allow Kong-specific resources in other namespaces to access the Secret. In this example, we’ll grant access to KongCertificate resources in the kong namespace.
echo '
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-gateway-to-secret
  namespace: secret-ns
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: Gateway
      namespace: kong
  to:
    - group: ""
      kind: Secret
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongReferenceGrant
metadata:
  name: allow-kong-to-secret
  namespace: secret-ns
spec:
  from:
    - group: configuration.konghq.com
      kind: KongCertificate
      namespace: kong
  to:
    - group: core
      kind: Secret' | kubectl apply -f -

Configure the Gateway

Create the following resources:

  • A kong namespace.
  • A GatewayConfiguration and a GatewayClass to configure your gateway with the latest Kong Gateway version and Kong Operator as the controller.
  • A Gateway that references the Secret in the secret-ns namespace.

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

echo '
apiVersion: v1
kind: Namespace
metadata:
  name: kong
---
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-gateway
  namespace: kong
spec:
  gatewayClassName: gateway-class
  listeners:
    - name: https
      port: 443
      protocol: HTTPS
      hostname: example.localdomain.dev
      tls:
        mode: Terminate
        certificateRefs:
          - group: ""
            kind: Secret
            name: example-tls-secret
            namespace: secret-ns' | kubectl apply -f -
echo '
apiVersion: v1
kind: Namespace
metadata:
  name: kong
---
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-gateway
  namespace: kong
spec:
  gatewayClassName: gateway-class
  listeners:
    - name: https
      port: 443
      protocol: HTTPS
      hostname: example.localdomain.dev
      tls:
        mode: Terminate
        certificateRefs:
          - group: ""
            kind: Secret
            name: example-tls-secret
            namespace: secret-ns' | kubectl apply -f -

Create a Service and a Route

  1. Run the following command to create a sample echo Service:

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

  2. Deploy a sample HTTPRoute to verify that TLS termination is working:

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

Validate

  1. Wait for the Gateway to be programmed:

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

  2. Get the Gateway’s external IP:

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

  3. Test the connection:

    curl -ivk --resolve example.localdomain.dev:443:$PROXY_IP https://example.localdomain.dev/echo

    You should get TLS handshake and a 200 response.

Cleanup

Delete the resources created in this guide

Delete the Gateway, the resources it serves, and the Secret it references, along with the grants that allow the reference:

kubectl delete -n kong --ignore-not-found \
  httproute/echo-route \
  service/echo \
  gateway/kong-gateway \
  gatewayconfiguration/gateway-configuration
kubectl delete --ignore-not-found gatewayclass/gateway-class
kubectl delete -n secret-ns --ignore-not-found \
  kongreferencegrant/allow-kong-to-secret \
  referencegrant/allow-gateway-to-secret \
  secret/example-tls-secret
kubectl delete namespace --ignore-not-found kong secret-ns
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