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.

Before you begin

Set up an agentgateway proxy.

Step 1: Create agentgateway configuration

Use a ConfigMap to pass upstream configuration settings directly to the agentgateway proxy.

Create a ConfigMap with your agentgateway configuration. This configuration defines the binds, listeners, routes, backends, and policies that you want agentgateway to use. The key must be named config.yaml. 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: v1
kind: ConfigMap
metadata:
  name: agentgateway-config
  namespace: 
data:
  config.yaml: |-
    binds:
    - port: 3000
      listeners:
      - protocol: HTTP
        routes:
        - name: direct-response
          matches:
          - path:
              pathPrefix: /direct
          policies:
            directResponse:
              body: "hello!"
              status: 200    
EOF

Create a resource that refers to your ConfigMap.

kubectl apply -f- <<EOF
apiVersion: 
kind: 
metadata:
  name: agentgateway-config
  namespace: 
spec:
  kube:
    agentgateway:
      enabled: true
      customConfigMapName: agentgateway-config
EOF

Create a Gateway resource for your agentgateway proxy that uses the resource. Set the port to a dummy value like 3030 to avoid conflicts with the binds defined in 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: gateway.kgateway.dev 
      kind:        
  listeners:
    - name: http
      port: 3030
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: All
EOF

Step 2: Verify the configuration

Describe the agentgateway pod. Verify that the pod is Running and that the Mounts section mounts the /config from the ConfigMap.
```
kubectl describe pod -l app.kubernetes.io/name=agentgateway-config -n 
```
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
  2. Send a request along the /direct path to the agentgateway proxy. Use port 3000 as defined in your ConfigMap.
    curl -i http://$INGRESS_GW_ADDRESS:3000/direct
- Port-forward for local testing
  1. Port-forward the agentgateway-config pod on port 3000 as defined in your ConfigMap.
    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  kubectl delete ConfigMap agentgateway-config -n

CEL-based RBAC Routes