Customization options

In the standalone agentgateway deployment, 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 standalone agentgateway deployment, you do not configure these features in a raw configuration file when running agentgateway on Kubernetes. Instead, you configure them in a Kubernetes Gateway API-native way by using an AgentgatewayParameters resource.

The following options can be used to provide custom agentgateway proxy configuration in the AgentgatewayParameters resource.

Built-in config options (recommended)
Overlays (strategic merge patch)
Raw upstream config

To see a setup example for each option, see Customize the gateway. For common customization examples, see Example configs.

Built-in customization (recommended)

The AgentgatewayParameters resource comes with built-in customization options that you can use to change certain aspects of your agentgateway proxy, such as the image that you use, logging configuration, resource limits and requests, or environment variables. These built-in config options are automatically validated when you create the agentgateway proxy from your AgentgatewayParameters resource.

Review the built-in configurations that are provided via the AgentgatewayParameters resource.

Built-in customization	Description
`env`	Add custom environment variables to your agentgateway proxy deployment. To remove a default environment variable, set its value to `null`.
`image`	Provide a custom image for the agentgateway proxy. This setting is useful if you deploy your proxy in an airgapped environment.
`logging`	Change the log level and format of the agentgateway proxy logs.
`resources`	Set resource limits and requests. For more information, see the Kubernetes documentation.

ℹ️

Because the built-in customization options are provided by the agentgateway API, they are considered stable and do not change between upgrades. Use the built-in customization options where possible. To change configuration that is not exposed via the built-in options, use overlays instead, or add raw upstream agentgateway configuration to your proxies.

To find common configuration examples, Example configs.

Overlays

For advanced customization of the Kubernetes resources that the agentgateway control plane generates, such as Deployments, Services, and ServiceAccounts, you can configure overlays in the AgentgatewayParameters resource. Overlays use Kubernetes strategic merge patch (SMP) semantics to modify the generated resources after they are rendered. For additional examples, see the kubectl patch documentation.

Review the following table for the resource types that you can overlay in the AgentgatewayParameters spec.

Field	Resource Type	Description
`deployment`	Deployment	The agentgateway proxy deployment. Common use casese include adding image pull secrets to pull images from private registries, removing default security contexts, configuring node selectors, affinities, and tolerations, adding custom labels and annotations, or mounting custom ConfigMaps or Secrets as volumes.
`service`	Service	The service that exposes the agentgateway proxy. A common use case is configuring cloud provider-specific service annotations.
`serviceAccount`	ServiceAccount	The service account for the proxy pods
`horizontalPodAutoscaler`	HorizontalPodAutoscaler (HPA)	Unlike Deployment, Service, and ServiceAccount, HPA are created only when an overlay is specified.
`podDisruptionBudget`	PodDisruptionBudget (PBD)	Unlike Deployment, Service, and ServiceAccount, PDBs are created only when an overlay is specified.

How overlays work

Overlays are applied after the agentgateway control plane renders the base Kubernetes resources. The control plane runs through the following steps:

The control plane reads built-in customization options from the AgentgatewayParameters resource, such as image, logging, and resources.
The control plane generates the base resources for the agentgateway proxy, including the Deployment, Service, and ServiceAccount.
The control plane applies any overlays that you specified in the AgentgatewayParameters resource.
The control plane creates or updates the resources in the cluster.

Unlike the built-in customization options, overlays are not validated by the agentgateway control plane when you create the Gateway. Instead, the resulting resources, such as the Deployment is validated by Kubernetes when the Deployment is created or updated.

Keep in mind that the overlay API is not stable and might change between Kubernetes versions, which can lead to breaking changes or unexpected behaviors. Make sure to test your overlay configurations thoroughly after each upgrade and use these configurations only if the customization cannot be achieved with the built-in option.

Remove or replace config

You can use overlays to also remove configuration from your resources, such as the pod security context when working in OpenShift environments. To remove configuration, the strategic merge patch allows the following methods:

Set field value to null

Set a field to a null value. This option is best for removing scalar values and simple objects.

The following example snippet sets the securityContext field in the container template to null. Note that you must use the kubectl apply --server-side command to apply the change and set the field to null. If you do not use the --server-side option, the null value is silently dropped when you apply the AgentgatewayParameters resource.


spec:
  deployment:
    spec:
      template:
        spec:
          containers:
            - name: agentgateway
              # Removes the securityContext entirely
              securityContext: null

Remove an entire field

To remove an entire field, use the $patch: delete method instead.

The following example snippets removes the securityContext field from the deployment template.


spec:
  deployment:
    spec:
      template:
        spec:
          # Removes the pod-level securityContext
          securityContext:
            $patch: delete

To replace a list, $patch: delete must be added as a separate list item as shown in the following snippet:


spec:
  deployment:
    spec:
      template:
        spec:
          volumes:
            - $patch: replace
            - name: custom-config
              configMap:
                name: my-custom-config

Raw config

For configuration that is not exposed via the AgentgatewayParameters’s built-in or overlay configuration options, or if you prefer to pass in raw upstream configuration, such as to migrate more easily from the agentgateway standalone binary to agentgateway on Kubernetes, you can use the rawConfig option in the AgentgatewayParameters resource.

To find the raw configuration that you want to apply, review Configuration in the standalone agentgateway binary docs.

Note that raw 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.

For a setup example, see Customize the gateway.

Configuration priority and precedence

You can attach an AgentgatewayParameters resource to either a GatewayClass that is shared by all Gateways that use that class, or to an individual Gateway. When the resource is applied to both, they are processed in the following order:

Built-in configuration in the GatewayClass is applied first - This includes settings, such as image, logging, resources, and env.
Built-in configuration in the Gateway overrides GatewayClass settings - If conflicting built-in configuration is specified on the Gateway, the GatewayClass configuration is overridden.
Overlay configuration in GatewayClass - After all built-in configuration is processed, overlay configuration that is defined on the GatewayClass is applied and might modify the rendered resources.
Overlay configuration in Gateway overrides GatewayClass settings - If conflicting overlay configuration is specified on the Gateway, the configuration in the GatewayClass is overridden by using strategic merge patch semantics. Consider the following examples:
- For scalar values, such as replicas, the Gateway configuration takes precedence.
- For maps, such as labels, the label keys are merged. If both the Gateway and GatewayClass specify the same label key, the label key on the Gateway takes precedence.

Example:

Consider the following GatewayClass configuration:


spec:
  deployment:
    spec:
      replicas: 3
      template:
        spec:
          containers:
            - name: agentgateway
              resources:
                limits:
                  memory: 512Mi

Consider the following Gateway configuration:


spec:
  deployment:
    spec:
      replicas: 5
      template:
        spec:
          containers:
            - name: agentgateway
              resources:
                limits:
                  cpu: 500m

The resulting configuration merges both configurations as follows:

replicas: 5 - Gateway configuration takes precedence
memory: 512Mi - GatewayClass setting is preserved
cpu: 500m - Gateway setting is added

Customize the gateway