Configuration

Docs

Documentation

Agentgateway

Configuration

Configure agentgateway with GatewayParameters.

GatewayParameters provide a way for you to pass configuration for special use cases, such as passing in raw upstream configuration from a YAML file.

Before you begin

Install kgateway and enable the agentgateway integration.

Verify that the agentgateway integration is enabled.

helm get values kgateway -n kgateway-system -o yaml

Example output:

agentgateway:
  enabled: true

Upstream configuration

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 kgateway. 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 your upstream configuration file in kgateway. 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.

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: kgateway-system
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 GatewayParameters resource that refers to your ConfigMap.

kubectl apply -f- <<EOF
apiVersion: gateway.kgateway.dev/v1alpha1
kind: GatewayParameters
metadata:
  name: agentgateway-config
  namespace: kgateway-system
spec:
  kube:
    agentgateway:
      enabled: true
      customConfigMapName: agentgateway-config
EOF

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

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: agentgateway-config
  namespace: kgateway-system
spec:
  gatewayClassName: agentgateway
  infrastructure:
    parametersRef:
      name: agentgateway-config
      group: gloo.solo.io
      kind: GatewayParameters       
  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 kgateway-system
```

Check the pod logs to verify that agentgateway loaded the configuration from the ConfigMap, such as by searching for the port binding.

kubectl logs -l app.kubernetes.io/name=agentgateway-config -n kgateway-system | grep 3000

Example output:

2025-10-28T13:47:01.116095Z	info	proxy::gateway	started bind	bind="bind/3000"

Send a test request.
1. Get the external address of the gateway proxy and save it in an environment variable.
  export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-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. Use port 3000 as defined in your ConfigMap.
  curl -i http://$INGRESS_GW_ADDRESS:3000/direct
1. Port-forward the agentgateway-config pod on port 3000 as defined in your ConfigMap.
  kubectl port-forward deployment/agentgateway-config -n kgateway-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!
```

Clean up

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

kubectl delete Gateway agentgateway-config -n kgateway-system
kubectl delete GatewayParameters agentgateway-config -n kgateway-system
kubectl delete ConfigMap agentgateway-config -n kgateway-system

CEL-based RBAC Routes