For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

CEL-based RBAC

Use CEL expressions to enforce role-based access control on AI resource requests.

Use Common Expression Language (CEL) expressions to secure access to AI resources and to regular HTTP traffic.

About CEL-based RBAC

Agentgateway proxies use CEL expressions to match requests or responses on specific parameters, such as a request header or source address. If the request matches the condition, it is allowed. Requests that do not match any of the conditions are denied.

The policy matches on request attributes rather than on the destination, so the same pattern works for any backend. The following sections show it twice: first for an LLM provider, and then for regular HTTP traffic to the httpbin sample app.

For an overview of supported CEL expressions, see the CEL reference.

Before you begin

1. Follow the Get started guide to install agentgateway.

2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

3. Get the external address of the gateway and save it in an environment variable.

   Cloud Provider LoadBalancerPort-forward for local testing

   Tip

   Kind cluster? Kind does not support LoadBalancer services by default. To use this option with a Kind cluster, install and run cloud-provider-kind.

   export INGRESS_GW_ADDRESS=$(kubectl get svc -n agentgateway-system agentgateway-proxy -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
   echo $INGRESS_GW_ADDRESS  

   kubectl port-forward deployment/agentgateway-proxy -n agentgateway-system 8080:80

Set up access to Gemini

Configure access to an LLM provider such as Gemini. You can use any other LLM provider, an MCP server, or an agent to try out CEL-based RBAC.

1. Save your Gemini API key as an environment variable. To retrieve your API key, log in to the Google AI Studio and select API Keys.

   export GOOGLE_KEY=<your-api-key>

2. Create a secret to authenticate to Google.

   kubectl apply -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: google-secret
     namespace: agentgateway-system
   type: Opaque
   stringData:
     Authorization: $GOOGLE_KEY
   EOF

3. Create an AgentgatewayBackend resource to configure an LLM provider that references the AI API key secret.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayBackend
   metadata:
     name: google
     namespace: agentgateway-system
   spec:
     ai:
       provider:
         gemini:
           model: gemini-2.5-flash-lite
     policies:
       auth:
         secretRef:
           name: google-secret
   EOF

   Review the following table to understand this configuration. For more information, see the API reference.

   Setting	Description
   ai.provider.gemini	Define the Gemini provider.
   gemini.model	The model to use to generate responses. In this example, you use the gemini-2.5-flash-lite model. For more models, see the Google AI docs.
   policies.auth	The authentication token to use to authenticate to the LLM provider. The example refers to the secret that you created in the previous step.

4. Create an HTTPRoute resource that routes incoming traffic to the AgentgatewayBackend. The following example sets up a route. Note that agentgateway automatically rewrites the endpoint to the appropriate chat completion endpoint of the LLM provider for you, based on the LLM provider that you set up in the AgentgatewayBackend resource.

   Gemini defaultOpenAI-compatible v1/chat/completionsCustom route

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: google
     namespace: agentgateway-system
   spec:
     parentRefs:
       - name: agentgateway-proxy
         namespace: agentgateway-system
     rules:
     - backendRefs:
       - name: google
         namespace: agentgateway-system
         group: agentgateway.dev
         kind: AgentgatewayBackend
   EOF

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: google
     namespace: agentgateway-system
   spec:
     parentRefs:
       - name: agentgateway-proxy
         namespace: agentgateway-system
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /v1/chat/completions
       backendRefs:
       - name: google
         namespace: agentgateway-system
         group: agentgateway.dev
         kind: AgentgatewayBackend
   EOF

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: google
     namespace: agentgateway-system
   spec:
     parentRefs:
       - name: agentgateway-proxy
         namespace: agentgateway-system
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /gemini
       backendRefs:
       - name: google
         namespace: agentgateway-system
         group: agentgateway.dev
         kind: AgentgatewayBackend
   EOF

5. Send a request to the LLM provider API along the route that you previously created. Verify that the request succeeds and that you get back a response from the API.

   Gemini defaultOpenAI-compatible v1/chat/completionsCustom route

   Cloud Provider LoadBalancer:

   curl "$INGRESS_GW_ADDRESS/v1beta/openai/chat/completions" -H content-type:application/json  -d '{
     "model": "",
     "messages": [
      {"role": "user", "content": "Explain how AI works in simple terms."}
    ]
   }' | jq

   Localhost:

   curl "localhost:8080/v1beta/openai/chat/completions" -H content-type:application/json  -d '{
     "model": "",
     "messages": [
      {"role": "user", "content": "Explain how AI works in simple terms."}
    ]
   }' | jq

   Cloud Provider LoadBalancer:

   curl "$INGRESS_GW_ADDRESS/v1/chat/completions" -H content-type:application/json  -d '{
     "model": "",
     "messages": [
      {"role": "user", "content": "Explain how AI works in simple terms."}
    ]
   }' | jq

   Localhost:

   curl "localhost:8080/v1/chat/completions" -H content-type:application/json  -d '{
     "model": "",
     "messages": [
      {"role": "user", "content": "Explain how AI works in simple terms."}
    ]
   }' | jq

   Cloud Provider LoadBalancer:

   curl "$INGRESS_GW_ADDRESS/gemini" -H content-type:application/json  -d '{
     "model": "",
     "messages": [
      {"role": "user", "content": "Explain how AI works in simple terms."}
    ]
   }' | jq

   Localhost:

   curl "localhost:8080/gemini" -H content-type:application/json  -d '{
     "model": "",
     "messages": [
      {"role": "user", "content": "Explain how AI works in simple terms."}
    ]
   }' | jq

   Example output:

   {"id":"aGLEaMjbLp6p_uMPopeAoAc",
   "choices":
     [{"index":0,"message":{
         "content":"Imagine teaching a dog a trick.  You show it what to do, reward it when it's right, and correct it when it's wrong.  Eventually, the dog learns.\n\nAI is similar.  We \"teach\" computers by showing them lots of examples.  For example, to recognize cats in pictures, we show it thousands of pictures of cats, labeling each one \"cat.\"  The AI learns patterns in these pictures – things like pointy ears, whiskers, and furry bodies – and eventually, it can identify a cat in a new picture it's never seen before.\n\nThis learning process uses math and algorithms (like a secret code of instructions) to find patterns and make predictions.  Some AI is more like a dog learning tricks (learning from examples), and some is more like following a very detailed recipe (following pre-programmed rules).\n\nSo, in short: AI is about teaching computers to learn from data and make decisions or predictions, just like we teach dogs tricks.\n",
         "role":"assistant"
         },
      "finish_reason":"stop"
      }],
    "created":1757700714,
    "model":"gemini-1.5-flash-latest",
    "object":"chat.completion",
    "usage":{
        "prompt_tokens":8,
        "completion_tokens":205,
        "total_tokens":213
        }
   }

Set up RBAC permissions for an LLM route

1. Create an AgentgatewayPolicy with your CEL rules. The following example allows requests with the x-llm: gemini header.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayPolicy
   metadata:
     name: rbac-policy
     namespace: agentgateway-system
   spec:
     targetRefs:
       - group: gateway.networking.k8s.io
         kind: HTTPRoute
         name: google
     traffic:
       authorization:
         action: Allow
         policy:
           matchExpressions:
             - "request.headers['x-llm'] == 'gemini'"
   EOF

2. Send a request to the LLM provider API without the x-llm header. Verify that the request is denied with a 403 HTTP response code.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -vik "$INGRESS_GW_ADDRESS:80/gemini" -H content-type:application/json -d '{
     "model": "",
     "messages": [
      {"role": "user", "content": "Explain how AI works in simple terms."}
    ]
   }'

   curl -vik "localhost:8080/gemini" -H content-type:application/json -d '{
     "model": "",
     "messages": [
      {"role": "user", "content": "Explain how AI works in simple terms."}
    ]
   }'

   Example output:

   * upload completely sent off: 109 bytes
   < HTTP/1.1 403 Forbidden
   < content-type: text/plain
   < content-length: 20
   
   authorization failed
   

3. Send another request to the LLM provider. This time, you include the x-llm header. Verify that the request succeeds with a 200 HTTP response code.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -vik "$INGRESS_GW_ADDRESS:80/gemini" \
     -H "content-type: application/json" \
     -H "x-llm: gemini" -d '{
     "model": "",
     "messages": [
      {"role": "user", "content": "Explain how AI works in simple terms."}
    ]
   }'

   curl -vik "localhost:8080/gemini" \
     -H "content-type: application/json" \
     -H "x-llm: gemini" -d '{
     "model": "",
     "messages": [
      {"role": "user", "content": "Explain how AI works in simple terms."}
    ]
   }'

Set up RBAC permissions for an HTTP route

The same policy pattern restricts access to regular HTTP traffic, such as the httpbin sample app.

1. Create an AgentgatewayPolicy with your CEL rules. The following example allows requests that include the x-team: engineering header, and denies every other request to the httpbin route.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayPolicy
   metadata:
     name: rbac-policy-httpbin
     namespace: httpbin
   spec:
     targetRefs:
       - group: gateway.networking.k8s.io
         kind: HTTPRoute
         name: httpbin
     traffic:
       authorization:
         action: Allow
         policy:
           matchExpressions:
             - "request.headers['x-team'] == 'engineering'"
   EOF

   Note

   This example matches a header that the client sets, which demonstrates the mechanism but does not verify who sent the request. To make an authorization decision based on a verified identity, match on a JWT claim instead.

2. Send a request to the httpbin app without the x-team header. Verify that the request is denied with a 403 HTTP response code.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -i "$INGRESS_GW_ADDRESS:80/headers" -H "host: www.example.com"

   curl -i localhost:8080/headers -H "host: www.example.com"

   Example output:

   HTTP/1.1 403 Forbidden
   content-type: text/plain
   content-length: 20
   
   authorization failed
   

3. Send another request to the httpbin app. This time, include the x-team: engineering header. Verify that the request succeeds with a 200 HTTP response code.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -i "$INGRESS_GW_ADDRESS:80/headers" -H "host: www.example.com" -H "x-team: engineering"

   curl -i localhost:8080/headers -H "host: www.example.com" -H "x-team: engineering"

   Example output:

   HTTP/1.1 200 OK
   

Cleanup

kubectl delete AgentgatewayPolicy rbac-policy -n agentgateway-system
kubectl delete AgentgatewayPolicy rbac-policy-httpbin -n httpbin
kubectl delete httproute google -n agentgateway-system
kubectl delete AgentgatewayBackend google -n agentgateway-system
kubectl delete secret google-secret -n agentgateway-system