Configuration

Customize your agentgateway proxy with .

About customizing your proxy

In upstream agentgateway, you can manage configuration via a YAML or JSON file. The configuration features of agentgateway are captured in the schema of the agentgateway codebase.

Unlike in the upstream agentgateway project, you do not configure these features in a raw configuration file in the agentgateway proxy. Instead, you configure them in a Kubernetes Gateway API-native way as explained in the guides throughout this doc set.

However, you still might want to pass in custom configuration to your agentgateway proxy. This can be useful in the following use cases:

Migrating from upstream to kgateway.
Using a feature that is not yet exposed via the Kubernetes Gateway or kgateway APIs.

You can choose between the following options to provide custom configuration to your agentgateway proxy.

Embed in CRD directly (recommended): You can add your custom configuration to the custom resource directly. This way, your configuration is validated when you apply the resource in your cluster. Keep in mind that not all upstream configuration options, such as binds, are currently supported in the resource. For supported options, see the API reference.
rawConfig: For configuration that cannot be embedded into the resource directly, or if you prefer to pass in raw upstream configuration, you can use the rawConfig option in the resource instead. Note that configuration is not automatically validated. If configuration is malformatted or includes unsupported fields, the agentgateway proxy does not start. You can run kubectl logs deploy/agentgateway-proxy -n agentgateway-system to view the logs of the proxy and find more information about why the configuration could not be applied.

Before you begin

Set up an agentgateway proxy.

Step 1: Create agentgateway configuration

Choose between the following options to provide your agentgateway configuration:

Embed in
rawConfig

Embed in

You can add your custom configuration to the custom resource directly. This way, your configuration is validated when you apply the resource in your cluster.

Create an resource with your custom configuration. The following example changes the logging format from text to json.

kubectl apply -f- <<EOF
apiVersion: 
kind: 
metadata:
  name: agentgateway-config
  namespace: 
spec:
  logging:
     format: json
EOF

Create a Gateway resource that sets up an agentgateway proxy that uses your .

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: agentgateway-config
  namespace: 
spec:
  gatewayClassName: 
  infrastructure:
    parametersRef:
      name: agentgateway-config
      group: 
      kind:        
  listeners:
    - name: http
      port: 3030
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: All
EOF

Check the pod logs to verify that the agentgateway logs are displayed in JSON format.

kubectl logs deployment/agentgateway-config -n

Example output:

{"level":"info","time":"2025-12-16T15:58:18.245219Z","scope":"agent_core::readiness","message":"Task 'agentgateway' complete (2.378042ms), still awaiting 1 tasks"}
{"level":"info","time":"2025-12-16T15:58:18.245221Z","scope":"agentgateway::management::hyper_helpers","message":"listener established","address":"127.0.0.1:15000","component":"admin"}
{"level":"info","time":"2025-12-16T15:58:18.245231Z","scope":"agentgateway::management::hyper_helpers","message":"listener established","address":"[::]:15020","component":"stats"}
{"level":"info","time":"2025-12-16T15:58:18.248025Z","scope":"agent_xds::client","message":"Stream established","xds":{"id":1}}
{"level":"info","time":"2025-12-16T15:58:18.248081Z","scope":"agent_xds::client","message":"received response","type_url":"type.googleapis.com/agentgateway.dev.workload.Address","size":44,"removes":0,"xds":{"id":1}}

`rawConfig`

Use the rawConfig option to pass in raw upstream configuration to your agentgateway proxy. Note that the configuration is not automatically validated. If configuration is malformatted or includes unsupported fields, the agentgateway proxy does not start. You can run kubectl logs deploy/agentgateway-proxy -n agentgateway-system to view the logs of the proxy and find more information about why the configuration could not be applied.

Create an resource with your custom configuration. The following example sets up a simple direct response listener on port 3000 that returns a 200 OK response with the body "hello!" for requests to the /direct path.

kubectl apply -f- <<EOF
apiVersion: 
kind: 
metadata:
  name: agentgateway-config
  namespace: 
spec:
  rawConfig:
    binds: 
    - port: 3000
      listeners: 
      - protocol: HTTP
        routes: 
        - name: direct-response
          matches: 
          - path: 
              pathPrefix: /direct
          policies: 
            directResponse:
              body: "hello!"
              status: 200
EOF

Create a Gateway resource that sets up an agentgateway proxy that uses your . Set the port to a dummy value like 3030 to avoid conflicts with the binds defined in your resource.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: agentgateway-config
  namespace: 
spec:
  gatewayClassName: 
  infrastructure:
    parametersRef:
      name: agentgateway-config
      group:   
      kind:        
  listeners:
    - name: http
      port: 3030
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: All
EOF

Check the pod logs to verify that agentgateway loaded the configuration from the ConfigMap, such as by searching for the port binding.
```
kubectl logs deployment/agentgateway-config -n  | grep 3000
```
Example output:
```
2025-10-28T13:47:01.116095Z	info	proxy::gateway	started bind	bind="bind/3000"
```
Send a test request.
- Cloud Provider LoadBalancer:
  1. Get the external address of the gateway proxy and save it in an environment variable.
  export INGRESS_GW_ADDRESS=$(kubectl get svc -n agentgateway-config -o=jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}") echo $INGRESS_GW_ADDRESS
  1. Send a request along the /direct path to the agentgateway proxy through port 3000.
    curl -i http://$INGRESS_GW_ADDRESS:3000/direct
- Port-forward for local testing
  1. Port-forward the agentgateway-config pod on port 3000.
    kubectl port-forward deployment/agentgateway-config -n 3000:3000
  2. Send a request to verify that you get back the expected response from your direct response configuration.
    curl -i localhost:3000/direct
Example output:
```
HTTP/1.1 200 OK
content-length: 6
date: Tue, 28 Oct 2025 14:13:48 GMT

hello!
```

Clean up

You can remove the resources that you created in this guide.

kubectl delete Gateway agentgateway-config -n 
kubectl delete  agentgateway-config -n

CEL-based RBAC Routes