For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
AgentgatewayParameters
Use AgentgatewayParameters to configure the agentgateway data plane.
Explore the configuration reference by clicking on a property name or expanding the property types. Use the in-field search bar to search for a property. The reference is also available as a table.agentgateway.dev/v1alpha1
AgentgatewayParameters are configuration that is used to dynamically
provision the agentgateway data plane. Labels and annotations that apply to
all resources may be specified at a higher level; see
https://gateway-api.sigs.k8s.io/reference/spec/#gatewayinfrastructure
provision the agentgateway data plane. Labels and annotations that apply to
all resources may be specified at a higher level; see
https://gateway-api.sigs.k8s.io/reference/spec/#gatewayinfrastructure
- apiVersionstring
- kindstring
- metadataobject
- *spec
- deployment
- metadata
- annotationsobject
- labelsobject
- specobject
- env
- *namestring
- valuestring
- valueFrom
- configMapKeyRef
- *keystring
- namestring
- optionalboolean
- fieldRef
- apiVersionstring
- *fieldPathstring
- fileKeyRef
- *keystring
- optionalboolean
- *pathstring
- *volumeNamestring
- resourceFieldRef
- containerNamestring
- divisor
- *resourcestring
- secretKeyRef
- *keystring
- namestring
- optionalboolean
- horizontalPodAutoscaler
- metadata
- annotationsobject
- labelsobject
- specobject
- image
- digeststring
- pullPolicystring
- registrystring
- repositorystring
- tagstring
- istio
- additionalTrustDomainsstring[]
- caAddressstring
- trustDomainstring
- logging
- formatstring
- levelstring
- podDisruptionBudget
- metadata
- annotationsobject
- labelsobject
- specobject
- rawConfigobject
- resources
- claims
- *namestring
- requeststring
- limitsobject
- requestsobject
- service
- metadata
- annotationsobject
- labelsobject
- specobject
- serviceAccount
- metadata
- annotationsobject
- labelsobject
- specobject
- shutdown
- *maxinteger
- *mininteger
- statusobject
apiVersion
APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
kind
Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
metadata
No description for this field.
spec
spec defines the desired state of AgentgatewayParameters.
spec.deployment
deployment allows specifying overrides for the generatedDeployment resource.Documentation References (2)
spec.deployment.metadata
metadata defines a subset of object metadata to be customized.labels and annotations are merged with existing values. If bothGatewayClass and Gateway parameters define the same label orannotation key, the
Gateway value takes precedence (applied second).Documentation References (1)
spec.deployment.metadata.annotations
Annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
Documentation References (1)
spec.deployment.metadata.labels
Map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
Documentation References (1)
spec.deployment.spec
spec provides an opaque mechanism to configure the resource spec.This field accepts a complete or partial Kubernetes resource spec, such
as
PodSpec or ServiceSpec, and will be merged with the generatedconfiguration using Strategic Merge Patch semantics.
Application Order
Overlays are applied after all typed configuration fields from both levels.
The full merge order is:
The full merge order is:
1.
2.
3.
4.
GatewayClass typed configuration fields2.
Gateway typed configuration fields3.
GatewayClass overlays4.
Gateway overlays (can override all previous values)Strategic Merge Patch & Deletion Guide
This merge strategy allows you to override individual fields, merge lists, or delete items
without needing to provide the entire resource definition.
without needing to provide the entire resource definition.
1. Replacing Values (Scalars):
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
2. Merging Lists (Append/Merge):
Lists with "merge keys", like
will append your items to the generated list, or update existing items if keys match.
Lists with "merge keys", like
containers which merges on name, ortolerations which merges on key,will append your items to the generated list, or update existing items if keys match.
3. Deleting Fields or List Items ($patch: delete):
To remove a field or list item from the generated resource, use the
and is the recommended approach because it works with both client-side
and server-side apply.
To remove a field or list item from the generated resource, use the
$patch: delete directive. This works for both map fields and list items,and is the recommended approach because it works with both client-side
and server-side apply.
spec:
template:
spec:
# Delete pod-level securityContext
securityContext:
$patch: delete
# Delete nodeSelector
nodeSelector:
$patch: delete
containers:
# Be sure to use the correct proxy name here or you will add a
# container instead of modifying a container.
- name: proxy-name
# Delete container-level securityContext
securityContext:
$patch: delete4. Null Values (server-side apply only):
Setting a field to
the API server, so the deletion won't occur. Prefer
for consistent behavior across both apply modes.
Setting a field to
null can also remove it, but this ONLY works withkubectl apply --server-side or equivalent. With regular client-sidekubectl apply, null values are stripped by kubectl before reachingthe API server, so the deletion won't occur. Prefer
$patch: deletefor consistent behavior across both apply modes.
spec:
template:
spec:
nodeSelector: null # Removes nodeSelector (server-side apply only!)5. Replacing Maps Entirely ($patch: replace):
To replace an entire map with your values (instead of merging), use
This removes all existing keys and replaces them with only your specified keys.
To replace an entire map with your values (instead of merging), use
$patch: replace.This removes all existing keys and replaces them with only your specified keys.
spec:
template:
spec:
nodeSelector:
$patch: replace
custom-key: custom-value6. Replacing Lists Entirely ($patch: replace):
If you want to strictly define a list and ignore all generated defaults, use
If you want to strictly define a list and ignore all generated defaults, use
$patch: replace.service:
spec:
ports:
- $patch: replace
- name: http
port: 80
targetPort: 8080
protocol: TCP
- name: https
port: 443
targetPort: 8443
protocol: TCPValidation
Preserve unknown fieldstrue
Documentation References (2)
spec.env
The container environment variables. These override any existing
values. If you want to delete an environment variable entirely, use
[variable
expansion](https://kubernetes.io/docs/tasks/inject-data-application/define-interdependent-environment-variables/)
does apply, but is highly discouraged -- to set dependent environment
variables, you can use
values. If you want to delete an environment variable entirely, use
$patch: delete with AgentgatewayParametersOverlays instead. Note that[variable
expansion](https://kubernetes.io/docs/tasks/inject-data-application/define-interdependent-environment-variables/)
does apply, but is highly discouraged -- to set dependent environment
variables, you can use
$(VAR_NAME), but it's highly discouraged.$$(VAR_NAME) avoids expansion and results in a literal$(VAR_NAME).If
controller-managed per-
SESSION_KEY is specified, it takes precedence over thecontroller-managed per-
Gateway session key Secret.Documentation References (3)
spec.env.name
Name of the environment variable.
May consist of any printable ASCII characters except '='.
May consist of any printable ASCII characters except '='.
Documentation References (3)
spec.env.value
Variable references $(VAR_NAME) are expanded
using the previously defined environment variables in the container and
any service environment variables. If a variable cannot be resolved,
the reference in the input string will be unchanged. Double $$ are reduced
to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e.
"$$(VAR_NAME)" will produce the string literal "$(VAR_NAME)".
Escaped references will never be expanded, regardless of whether the variable
exists or not.
Defaults to "".
using the previously defined environment variables in the container and
any service environment variables. If a variable cannot be resolved,
the reference in the input string will be unchanged. Double $$ are reduced
to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e.
"$$(VAR_NAME)" will produce the string literal "$(VAR_NAME)".
Escaped references will never be expanded, regardless of whether the variable
exists or not.
Defaults to "".
Documentation References (3)
spec.env.valueFrom
Source for the environment variable's value. Cannot be used if value is not empty.
spec.env.valueFrom.configMapKeyRef
Selects a key of a ConfigMap.
Validation
Map typeatomic
spec.env.valueFrom.configMapKeyRef.key
The key to select.
spec.env.valueFrom.configMapKeyRef.name
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
spec.env.valueFrom.configMapKeyRef.optional
Specify whether the ConfigMap or its key must be defined
spec.env.valueFrom.fieldRef
Selects a field of the pod: supports metadata.name, metadata.namespace,
spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.
metadata.labels['<KEY>'], metadata.annotations['<KEY>'],spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.
Validation
Map typeatomic
spec.env.valueFrom.fieldRef.apiVersion
Version of the schema the FieldPath is written in terms of, defaults to "v1".
spec.env.valueFrom.fieldRef.fieldPath
Path of the field to select in the specified API version.
spec.env.valueFrom.fileKeyRef
FileKeyRef selects a key of the env file.
Requires the EnvFiles feature gate to be enabled.
Requires the EnvFiles feature gate to be enabled.
Validation
Map typeatomic
spec.env.valueFrom.fileKeyRef.key
The key within the env file. An invalid key will prevent the pod from starting.
The keys defined within a source may consist of any printable ASCII characters except '='.
During Alpha stage of the EnvFiles feature gate, the key size is limited to 128 characters.
The keys defined within a source may consist of any printable ASCII characters except '='.
During Alpha stage of the EnvFiles feature gate, the key size is limited to 128 characters.
spec.env.valueFrom.fileKeyRef.optional
Specify whether the file or its key must be defined. If the file or key
does not exist, then the env var is not published.
If optional is set to true and the specified key does not exist,
the environment variable will not be set in the Pod's containers.
does not exist, then the env var is not published.
If optional is set to true and the specified key does not exist,
the environment variable will not be set in the Pod's containers.
If optional is set to false and the specified key does not exist,
an error will be returned during Pod creation.
an error will be returned during Pod creation.
Validation
Defaultfalse
spec.env.valueFrom.fileKeyRef.path
The path within the volume from which to select the file.
Must be relative and may not contain the '..' path or start with '..'.
Must be relative and may not contain the '..' path or start with '..'.
spec.env.valueFrom.fileKeyRef.volumeName
The name of the volume mount containing the env file.
spec.env.valueFrom.resourceFieldRef
Selects a resource of the container: only resources limits and requests
(limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.
(limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.
Validation
Map typeatomic
spec.env.valueFrom.resourceFieldRef.containerName
Container name: required for volumes, optional for env vars
spec.env.valueFrom.resourceFieldRef.divisor
Specifies the output format of the exposed resources, defaults to "1"
Validation
Pattern^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
Int or stringtrue
spec.env.valueFrom.resourceFieldRef.resource
Required: resource to select
spec.env.valueFrom.secretKeyRef
Selects a key of a secret in the pod's namespace
Validation
Map typeatomic
spec.env.valueFrom.secretKeyRef.key
The key of the secret to select from. Must be a valid secret key.
spec.env.valueFrom.secretKeyRef.name
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
spec.env.valueFrom.secretKeyRef.optional
Specify whether the Secret or its key must be defined
spec.horizontalPodAutoscaler
horizontalPodAutoscaler allows creating a HorizontalPodAutoscalerfor the agentgateway proxy. If absent, no HPA is created. If present, an
HPA is created with its
scaleTargetRef automatically configured totarget the agentgateway proxy
Deployment. The metadata and specfields from this overlay are applied to the generated HPA.
Documentation References (1)
spec.horizontalPodAutoscaler.metadata
metadata defines a subset of object metadata to be customized.labels and annotations are merged with existing values. If bothGatewayClass and Gateway parameters define the same label orannotation key, the
Gateway value takes precedence (applied second).Documentation References (1)
spec.horizontalPodAutoscaler.metadata.annotations
Annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
spec.horizontalPodAutoscaler.metadata.labels
Map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
Documentation References (1)
spec.horizontalPodAutoscaler.spec
spec provides an opaque mechanism to configure the resource spec.This field accepts a complete or partial Kubernetes resource spec, such
as
PodSpec or ServiceSpec, and will be merged with the generatedconfiguration using Strategic Merge Patch semantics.
Application Order
Overlays are applied after all typed configuration fields from both levels.
The full merge order is:
The full merge order is:
1.
2.
3.
4.
GatewayClass typed configuration fields2.
Gateway typed configuration fields3.
GatewayClass overlays4.
Gateway overlays (can override all previous values)Strategic Merge Patch & Deletion Guide
This merge strategy allows you to override individual fields, merge lists, or delete items
without needing to provide the entire resource definition.
without needing to provide the entire resource definition.
1. Replacing Values (Scalars):
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
2. Merging Lists (Append/Merge):
Lists with "merge keys", like
will append your items to the generated list, or update existing items if keys match.
Lists with "merge keys", like
containers which merges on name, ortolerations which merges on key,will append your items to the generated list, or update existing items if keys match.
3. Deleting Fields or List Items ($patch: delete):
To remove a field or list item from the generated resource, use the
and is the recommended approach because it works with both client-side
and server-side apply.
To remove a field or list item from the generated resource, use the
$patch: delete directive. This works for both map fields and list items,and is the recommended approach because it works with both client-side
and server-side apply.
spec:
template:
spec:
# Delete pod-level securityContext
securityContext:
$patch: delete
# Delete nodeSelector
nodeSelector:
$patch: delete
containers:
# Be sure to use the correct proxy name here or you will add a
# container instead of modifying a container.
- name: proxy-name
# Delete container-level securityContext
securityContext:
$patch: delete4. Null Values (server-side apply only):
Setting a field to
the API server, so the deletion won't occur. Prefer
for consistent behavior across both apply modes.
Setting a field to
null can also remove it, but this ONLY works withkubectl apply --server-side or equivalent. With regular client-sidekubectl apply, null values are stripped by kubectl before reachingthe API server, so the deletion won't occur. Prefer
$patch: deletefor consistent behavior across both apply modes.
spec:
template:
spec:
nodeSelector: null # Removes nodeSelector (server-side apply only!)5. Replacing Maps Entirely ($patch: replace):
To replace an entire map with your values (instead of merging), use
This removes all existing keys and replaces them with only your specified keys.
To replace an entire map with your values (instead of merging), use
$patch: replace.This removes all existing keys and replaces them with only your specified keys.
spec:
template:
spec:
nodeSelector:
$patch: replace
custom-key: custom-value6. Replacing Lists Entirely ($patch: replace):
If you want to strictly define a list and ignore all generated defaults, use
If you want to strictly define a list and ignore all generated defaults, use
$patch: replace.service:
spec:
ports:
- $patch: replace
- name: http
port: 80
targetPort: 8080
protocol: TCP
- name: https
port: 443
targetPort: 8443
protocol: TCPValidation
Preserve unknown fieldstrue
Documentation References (1)
spec.image
The agentgateway container image. See
https://kubernetes.io/docs/concepts/containers/images
for details.
https://kubernetes.io/docs/concepts/containers/images
for details.
Default values, which may be overridden individually:
registry: cr.agentgateway.dev
repository: agentgateway
tag: <agentgateway version>
pullPolicy: <omitted, relying on Kubernetes defaults which depend on the tag>Documentation References (1)
spec.image.digest
The hash digest of the image, e.g.
sha256:12345...spec.image.pullPolicy
The image pull policy for the container. See
https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy
for details.
https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy
for details.
Documentation References (1)
spec.image.repository
The image repository (name).
Documentation References (1)
spec.istio
Configure Istio integration. If enabled, Agentgateway can natively connect to Istio enabled pods with mTLS.
spec.istio.additionalTrustDomains
Additional SPIFFE trust domains accepted on inbound HBONE connections.
The local trust domain is always implicitly included.
The local trust domain is always implicitly included.
spec.istio.caAddress
The address of the Istio CA. If unset, defaults to
https://istiod.istio-system.svc:15012.spec.istio.trustDomain
The Istio trust domain. If not set, defaults to
cluster.local.spec.logging
logging configuration for Agentgateway. By default, all logs are set toinfo level.Documentation References (2)
spec.logging.format
The default logging format is text.
Validation
Enumjson, text
Documentation References (2)
spec.logging.level
Logging level in standard
default), or a comma-separated per-module setting such as
RUST_LOG syntax, for example info (thedefault), or a comma-separated per-module setting such as
rmcp=warn,hickory_server::server::server_future=off,typespec_client_core::http::policies::logging=warn.spec.podDisruptionBudget
podDisruptionBudget allows creating a PodDisruptionBudget for theagentgateway proxy. If absent, no PDB is created. If present, a PDB is
created with its selector automatically configured to target the
agentgateway proxy
Deployment. The metadata and spec fields fromthis overlay are applied to the generated PDB.
Documentation References (1)
spec.podDisruptionBudget.metadata
metadata defines a subset of object metadata to be customized.labels and annotations are merged with existing values. If bothGatewayClass and Gateway parameters define the same label orannotation key, the
Gateway value takes precedence (applied second).Documentation References (1)
spec.podDisruptionBudget.metadata.annotations
Annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
spec.podDisruptionBudget.metadata.labels
Map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
Documentation References (1)
spec.podDisruptionBudget.spec
spec provides an opaque mechanism to configure the resource spec.This field accepts a complete or partial Kubernetes resource spec, such
as
PodSpec or ServiceSpec, and will be merged with the generatedconfiguration using Strategic Merge Patch semantics.
Application Order
Overlays are applied after all typed configuration fields from both levels.
The full merge order is:
The full merge order is:
1.
2.
3.
4.
GatewayClass typed configuration fields2.
Gateway typed configuration fields3.
GatewayClass overlays4.
Gateway overlays (can override all previous values)Strategic Merge Patch & Deletion Guide
This merge strategy allows you to override individual fields, merge lists, or delete items
without needing to provide the entire resource definition.
without needing to provide the entire resource definition.
1. Replacing Values (Scalars):
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
2. Merging Lists (Append/Merge):
Lists with "merge keys", like
will append your items to the generated list, or update existing items if keys match.
Lists with "merge keys", like
containers which merges on name, ortolerations which merges on key,will append your items to the generated list, or update existing items if keys match.
3. Deleting Fields or List Items ($patch: delete):
To remove a field or list item from the generated resource, use the
and is the recommended approach because it works with both client-side
and server-side apply.
To remove a field or list item from the generated resource, use the
$patch: delete directive. This works for both map fields and list items,and is the recommended approach because it works with both client-side
and server-side apply.
spec:
template:
spec:
# Delete pod-level securityContext
securityContext:
$patch: delete
# Delete nodeSelector
nodeSelector:
$patch: delete
containers:
# Be sure to use the correct proxy name here or you will add a
# container instead of modifying a container.
- name: proxy-name
# Delete container-level securityContext
securityContext:
$patch: delete4. Null Values (server-side apply only):
Setting a field to
the API server, so the deletion won't occur. Prefer
for consistent behavior across both apply modes.
Setting a field to
null can also remove it, but this ONLY works withkubectl apply --server-side or equivalent. With regular client-sidekubectl apply, null values are stripped by kubectl before reachingthe API server, so the deletion won't occur. Prefer
$patch: deletefor consistent behavior across both apply modes.
spec:
template:
spec:
nodeSelector: null # Removes nodeSelector (server-side apply only!)5. Replacing Maps Entirely ($patch: replace):
To replace an entire map with your values (instead of merging), use
This removes all existing keys and replaces them with only your specified keys.
To replace an entire map with your values (instead of merging), use
$patch: replace.This removes all existing keys and replaces them with only your specified keys.
spec:
template:
spec:
nodeSelector:
$patch: replace
custom-key: custom-value6. Replacing Lists Entirely ($patch: replace):
If you want to strictly define a list and ignore all generated defaults, use
If you want to strictly define a list and ignore all generated defaults, use
$patch: replace.service:
spec:
ports:
- $patch: replace
- name: http
port: 80
targetPort: 8080
protocol: TCP
- name: https
port: 443
targetPort: 8443
protocol: TCPValidation
Preserve unknown fieldstrue
Documentation References (1)
spec.rawConfig
rawConfig provides an opaque mechanism to configure the agentgatewayconfig file. The
agentgateway binary has a -f option to specify aconfig file, and this field supplies that file. This will be merged with
configuration derived from typed fields like
logging.format, and thosetyped fields will take precedence.
Example:
rawConfig:
binds:
- port: 3000
listeners:
- routes:
- policies:
cors:
allowOrigins:
- "*"
allowHeaders:
- mcp-protocol-version
- content-type
- cache-control
backends:
- mcp:
targets:
- name: everything
stdio:
cmd: npx
args: ["@modelcontextprotocol/server-everything"]Validation
Preserve unknown fieldstrue
Documentation References (1)
spec.resources
The compute resources required by this container. See
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
for details.
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
for details.
Documentation References (1)
spec.resources.claims
Claims lists the names of resources, defined in spec.resourceClaims,
that are used by this container.
that are used by this container.
This field depends on the
DynamicResourceAllocation feature gate.
DynamicResourceAllocation feature gate.
This field is immutable. It can only be set for containers.
Validation
List typemap
List map keysname
spec.resources.claims.name
Name must match the name of one entry in pod.spec.resourceClaims of
the Pod where this field is used. It makes that resource available
inside a container.
the Pod where this field is used. It makes that resource available
inside a container.
spec.resources.claims.request
Request is the name chosen for a request in the referenced claim.
If empty, everything from the claim is made available, otherwise
only the result of this request.
If empty, everything from the claim is made available, otherwise
only the result of this request.
spec.resources.limits
Limits describes the maximum amount of compute resources allowed.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
Documentation References (1)
spec.resources.requests
Requests describes the minimum amount of compute resources required.
If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
otherwise to an implementation-defined value. Requests cannot exceed Limits.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
otherwise to an implementation-defined value. Requests cannot exceed Limits.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
Documentation References (1)
spec.service
service allows specifying overrides for the generated Serviceresource.
Documentation References (1)
spec.service.metadata
metadata defines a subset of object metadata to be customized.labels and annotations are merged with existing values. If bothGatewayClass and Gateway parameters define the same label orannotation key, the
Gateway value takes precedence (applied second).Documentation References (1)
spec.service.metadata.annotations
Annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
Documentation References (1)
spec.service.metadata.labels
Map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
spec.service.spec
spec provides an opaque mechanism to configure the resource spec.This field accepts a complete or partial Kubernetes resource spec, such
as
PodSpec or ServiceSpec, and will be merged with the generatedconfiguration using Strategic Merge Patch semantics.
Application Order
Overlays are applied after all typed configuration fields from both levels.
The full merge order is:
The full merge order is:
1.
2.
3.
4.
GatewayClass typed configuration fields2.
Gateway typed configuration fields3.
GatewayClass overlays4.
Gateway overlays (can override all previous values)Strategic Merge Patch & Deletion Guide
This merge strategy allows you to override individual fields, merge lists, or delete items
without needing to provide the entire resource definition.
without needing to provide the entire resource definition.
1. Replacing Values (Scalars):
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
2. Merging Lists (Append/Merge):
Lists with "merge keys", like
will append your items to the generated list, or update existing items if keys match.
Lists with "merge keys", like
containers which merges on name, ortolerations which merges on key,will append your items to the generated list, or update existing items if keys match.
3. Deleting Fields or List Items ($patch: delete):
To remove a field or list item from the generated resource, use the
and is the recommended approach because it works with both client-side
and server-side apply.
To remove a field or list item from the generated resource, use the
$patch: delete directive. This works for both map fields and list items,and is the recommended approach because it works with both client-side
and server-side apply.
spec:
template:
spec:
# Delete pod-level securityContext
securityContext:
$patch: delete
# Delete nodeSelector
nodeSelector:
$patch: delete
containers:
# Be sure to use the correct proxy name here or you will add a
# container instead of modifying a container.
- name: proxy-name
# Delete container-level securityContext
securityContext:
$patch: delete4. Null Values (server-side apply only):
Setting a field to
the API server, so the deletion won't occur. Prefer
for consistent behavior across both apply modes.
Setting a field to
null can also remove it, but this ONLY works withkubectl apply --server-side or equivalent. With regular client-sidekubectl apply, null values are stripped by kubectl before reachingthe API server, so the deletion won't occur. Prefer
$patch: deletefor consistent behavior across both apply modes.
spec:
template:
spec:
nodeSelector: null # Removes nodeSelector (server-side apply only!)5. Replacing Maps Entirely ($patch: replace):
To replace an entire map with your values (instead of merging), use
This removes all existing keys and replaces them with only your specified keys.
To replace an entire map with your values (instead of merging), use
$patch: replace.This removes all existing keys and replaces them with only your specified keys.
spec:
template:
spec:
nodeSelector:
$patch: replace
custom-key: custom-value6. Replacing Lists Entirely ($patch: replace):
If you want to strictly define a list and ignore all generated defaults, use
If you want to strictly define a list and ignore all generated defaults, use
$patch: replace.service:
spec:
ports:
- $patch: replace
- name: http
port: 80
targetPort: 8080
protocol: TCP
- name: https
port: 443
targetPort: 8443
protocol: TCPValidation
Preserve unknown fieldstrue
Documentation References (1)
spec.serviceAccount
serviceAccount allows specifying overrides for the generatedServiceAccount resource.Documentation References (1)
spec.serviceAccount.metadata
metadata defines a subset of object metadata to be customized.labels and annotations are merged with existing values. If bothGatewayClass and Gateway parameters define the same label orannotation key, the
Gateway value takes precedence (applied second).Documentation References (1)
spec.serviceAccount.metadata.annotations
Annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
Documentation References (1)
spec.serviceAccount.metadata.labels
Map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
spec.serviceAccount.spec
spec provides an opaque mechanism to configure the resource spec.This field accepts a complete or partial Kubernetes resource spec, such
as
PodSpec or ServiceSpec, and will be merged with the generatedconfiguration using Strategic Merge Patch semantics.
Application Order
Overlays are applied after all typed configuration fields from both levels.
The full merge order is:
The full merge order is:
1.
2.
3.
4.
GatewayClass typed configuration fields2.
Gateway typed configuration fields3.
GatewayClass overlays4.
Gateway overlays (can override all previous values)Strategic Merge Patch & Deletion Guide
This merge strategy allows you to override individual fields, merge lists, or delete items
without needing to provide the entire resource definition.
without needing to provide the entire resource definition.
1. Replacing Values (Scalars):
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
Simple fields (strings, integers, booleans) in your config will overwrite the generated defaults.
2. Merging Lists (Append/Merge):
Lists with "merge keys", like
will append your items to the generated list, or update existing items if keys match.
Lists with "merge keys", like
containers which merges on name, ortolerations which merges on key,will append your items to the generated list, or update existing items if keys match.
3. Deleting Fields or List Items ($patch: delete):
To remove a field or list item from the generated resource, use the
and is the recommended approach because it works with both client-side
and server-side apply.
To remove a field or list item from the generated resource, use the
$patch: delete directive. This works for both map fields and list items,and is the recommended approach because it works with both client-side
and server-side apply.
spec:
template:
spec:
# Delete pod-level securityContext
securityContext:
$patch: delete
# Delete nodeSelector
nodeSelector:
$patch: delete
containers:
# Be sure to use the correct proxy name here or you will add a
# container instead of modifying a container.
- name: proxy-name
# Delete container-level securityContext
securityContext:
$patch: delete4. Null Values (server-side apply only):
Setting a field to
the API server, so the deletion won't occur. Prefer
for consistent behavior across both apply modes.
Setting a field to
null can also remove it, but this ONLY works withkubectl apply --server-side or equivalent. With regular client-sidekubectl apply, null values are stripped by kubectl before reachingthe API server, so the deletion won't occur. Prefer
$patch: deletefor consistent behavior across both apply modes.
spec:
template:
spec:
nodeSelector: null # Removes nodeSelector (server-side apply only!)5. Replacing Maps Entirely ($patch: replace):
To replace an entire map with your values (instead of merging), use
This removes all existing keys and replaces them with only your specified keys.
To replace an entire map with your values (instead of merging), use
$patch: replace.This removes all existing keys and replaces them with only your specified keys.
spec:
template:
spec:
nodeSelector:
$patch: replace
custom-key: custom-value6. Replacing Lists Entirely ($patch: replace):
If you want to strictly define a list and ignore all generated defaults, use
If you want to strictly define a list and ignore all generated defaults, use
$patch: replace.service:
spec:
ports:
- $patch: replace
- name: http
port: 80
targetPort: 8080
protocol: TCP
- name: https
port: 443
targetPort: 8443
protocol: TCPValidation
Preserve unknown fieldstrue
spec.shutdown
Shutdown delay configuration. How graceful planned or unplanned data
plane changes happen is in tension with how quickly rollouts of the data
plane complete. How long a data plane pod must wait for shutdown to be
perfectly graceful depends on how you have configured your
resources.
plane changes happen is in tension with how quickly rollouts of the data
plane complete. How long a data plane pod must wait for shutdown to be
perfectly graceful depends on how you have configured your
Gatewayresources.
Validation
Rule
The 'min' value must be less than or equal to the 'max' value.
Documentation References (1)
spec.shutdown.max
Maximum time (in seconds) to wait before allowing Agentgateway to
terminate. Refer to the
environment variable for details.
terminate. Refer to the
TERMINATION_GRACE_PERIOD_SECONDSenvironment variable for details.
Validation
Formatint64
Minimum0
Maximum31536000
Documentation References (1)
spec.shutdown.min
Minimum time (in seconds) to wait before allowing Agentgateway to
terminate. Refer to the
environment variable for details.
terminate. Refer to the
CONNECTION_MIN_TERMINATION_DEADLINEenvironment variable for details.
Validation
Formatint64
Minimum0
Maximum31536000
Documentation References (1)
status
status defines the current state of AgentgatewayParameters.
Was this page helpful?
