API Key Authentication

Convert an NGINX API key check to a kgateway TrafficPolicy with native apiKeyAuth.

In open-source NGINX, API key validation is often implemented using a configuration-snippet that checks for a specific header. kgateway provides a more robust, native apiKeyAuth mechanism in its TrafficPolicy.

Before: Ingress with API Key Check

This is a common way to enforce API keys in NGINX Ingress:

cat <<'EOF' > api-key-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-key-demo
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      if ($http_x_api_key = "") {
        return 401;
      }
spec:
  ingressClassName: nginx
  rules:
  - host: api.example.com
    http:
      paths:
      - backend:
          service:
            name: httpbin
            port:
              number: 8000
        path: /
        pathType: Prefix
EOF

Convert

ingress2gateway print --providers=ingress-nginx --emitter=kgateway \
  --input-file api-key-ingress.yaml > api-key-kgateway.yaml

After: TrafficPolicy with API Key Auth

The configuration-snippet is raw NGINX configuration, so ingress2gateway passes it through without translating it. You author the apiKeyAuth policy by hand: instead of a raw if-statement, you define the source (for example, a header name) and a secret that holds the valid keys.

apiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata:
  name: api-key-policy
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: api-key-demo-api-example-com
  apiKeyAuth:
    keySources:
    - header: X-API-Key
    secretRef:
      name: valid-api-keys

Each entry in the secret represents a valid client/key pair:

apiVersion: v1
kind: Secret
metadata:
  name: valid-api-keys
stringData:
  client-a: "key-12345"
  client-b: "key-67890"

Apply and verify

kubectl apply -f api-key-kgateway.yaml
kubectl get trafficpolicies

JWT Authentication OIDC Authentication

Was this page helpful?