Customize the gateway

Customize your agentgateway proxy with the AgentgatewayParameters resource.

Before you begin

Set up an agentgateway proxy.

Customize the gateway

Choose between the following options to customize your agentgateway proxy:

• Built-in customization
• Overlays
• rawConfig

Built-in customization

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

1. Create an AgentgatewayParameters resource with your custom configuration. The following example changes the logging format from text to json. For other examples, see Built-in customization.

   kubectl apply --server-side -f- <<'EOF'
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayParameters
   metadata:
     name: agentgateway-config
     namespace: agentgateway-system
   spec:
     logging:
        format: json
   EOF

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

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

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

   kubectl logs deployment/agentgateway-config -n agentgateway-system

   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}}

Overlays

You can define Kubernetes overlays in the AgentgatewayParameters resource to override default settings for the deployment, service, and service account that are created for an agentgateway proxy.

1. Create an AgentgatewayParameters resource with your custom configuration. The following example changes the default replica count from 1 to 3. For other examples, see Overlays.

   kubectl apply --server-side -f- <<'EOF'
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayParameters
   metadata:
     name: agentgateway-config
     namespace: agentgateway-system
   spec:
     deployment:
       spec:
         replicas: 3
   EOF

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

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

3. Check the number of agentgateway pods that are created. Verify that you see 3 replicas.

   kubectl get pods -n agentgateway-system

   Example output:

   NAME                                   READY   STATUS    RESTARTS       AGE
   agentgateway-config-54975d9598-qrh8v   1/1     Running   0              7s
   agentgateway-config-54975d9598-tb6qx   1/1     Running   0              7s
   agentgateway-config-54975d9598-w4cx2   1/1     Running   0              7s

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.

1. Create an AgentgatewayParameters 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 --server-side -f- <<'EOF'
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayParameters
   metadata:
     name: agentgateway-config
     namespace: agentgateway-system
   spec:
     rawConfig:
       binds: 
       - port: 3000
         listeners: 
         - protocol: HTTP
           routes: 
           - name: direct-response
             matches: 
             - path: 
                 pathPrefix: /direct
             policies: 
               directResponse:
                 body: "hello!"
                 status: 200
   EOF

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

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

3. 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-system 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 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 agentgateway-system 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!

Cleanup

kubectl delete Gateway agentgateway-config -n agentgateway-system
kubectl delete AgentgatewayParameters agentgateway-config -n agentgateway-system

Next

Explore other common agentgateway proxy configurations that you can apply in your environment.