# NGF Ref ## Overview NGINX Gateway API Reference

Packages:

gateway.nginx.org/v1alpha1

Package v1alpha1 contains API Schema definitions for the gateway.nginx.org API group.

Resource Types:

ClientSettingsPolicy

ClientSettingsPolicy is an Inherited Attached Policy. It provides a way to configure the behavior of the connection between the client and NGINX Gateway Fabric.

Field Description
apiVersion
string		 gateway.nginx.org/v1alpha1
kind
string 		ClientSettingsPolicy
metadata
Kubernetes meta/v1.ObjectMeta 		Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
ClientSettingsPolicySpec

Spec defines the desired state of the ClientSettingsPolicy.



body
ClientBody 		(Optional)

Body defines the client request body settings.
keepAlive
ClientKeepAlive 		(Optional)

KeepAlive defines the keep-alive settings.
targetRef
sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference

TargetRef identifies an API object to apply the policy to. Object must be in the same namespace as the policy. Support: Gateway, HTTPRoute, GRPCRoute.
status
sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus

Status defines the state of the ClientSettingsPolicy.

NginxGateway

NginxGateway represents the dynamic configuration for an NGINX Gateway Fabric control plane.

Field Description
apiVersion
string		 gateway.nginx.org/v1alpha1
kind
string 		NginxGateway
metadata
Kubernetes meta/v1.ObjectMeta 		Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
NginxGatewaySpec

NginxGatewaySpec defines the desired state of the NginxGateway.



logging
Logging 		(Optional)

Logging defines logging related settings for the control plane.
status
NginxGatewayStatus

NginxGatewayStatus defines the state of the NginxGateway.

ObservabilityPolicy

ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the GatewayClass parametersRef.

Field Description
apiVersion
string		 gateway.nginx.org/v1alpha1
kind
string 		ObservabilityPolicy
metadata
Kubernetes meta/v1.ObjectMeta 		Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
ObservabilityPolicySpec

Spec defines the desired state of the ObservabilityPolicy.



tracing
Tracing 		(Optional)

Tracing allows for enabling and configuring tracing.
targetRefs
[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference

TargetRefs identifies the API object(s) to apply the policy to. Objects must be in the same namespace as the policy. Support: HTTPRoute, GRPCRoute.
status
sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus

Status defines the state of the ObservabilityPolicy.

SnippetsFilter

SnippetsFilter is a filter that allows inserting NGINX configuration into the generated NGINX config for HTTPRoute and GRPCRoute resources.

Field Description
apiVersion
string		 gateway.nginx.org/v1alpha1
kind
string 		SnippetsFilter
metadata
Kubernetes meta/v1.ObjectMeta 		Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
SnippetsFilterSpec

Spec defines the desired state of the SnippetsFilter.



snippets
[]Snippet

Snippets is a list of NGINX configuration snippets. There can only be one snippet per context. Allowed contexts: main, http, http.server, http.server.location.
status
SnippetsFilterStatus

Status defines the state of the SnippetsFilter.

UpstreamSettingsPolicy

UpstreamSettingsPolicy is a Direct Attached Policy. It provides a way to configure the behavior of the connection between NGINX and the upstream applications.

Field Description
apiVersion
string		 gateway.nginx.org/v1alpha1
kind
string 		UpstreamSettingsPolicy
metadata
Kubernetes meta/v1.ObjectMeta 		Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
UpstreamSettingsPolicySpec

Spec defines the desired state of the UpstreamSettingsPolicy.



zoneSize
Size 		(Optional)

ZoneSize is the size of the shared memory zone used by the upstream. This memory zone is used to share the upstream configuration between nginx worker processes. The more servers that an upstream has, the larger memory zone is required. Default: OSS: 512k, Plus: 1m. Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone
keepAlive
UpstreamKeepAlive 		(Optional)

KeepAlive defines the keep-alive settings.
targetRefs
[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference

TargetRefs identifies API object(s) to apply the policy to. Objects must be in the same namespace as the policy. Support: Service

TargetRefs must be distinct. The name field must be unique for all targetRef entries in the UpstreamSettingsPolicy.
status
sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus

Status defines the state of the UpstreamSettingsPolicy.

ClientBody

(Appears on: ClientSettingsPolicySpec)

ClientBody contains the settings for the client request body.

Field Description
maxSize
Size 		(Optional)

MaxSize sets the maximum allowed size of the client request body. If the size in a request exceeds the configured value, the 413 (Request Entity Too Large) error is returned to the client. Setting size to 0 disables checking of client request body size. Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size.
timeout
Duration 		(Optional)

Timeout defines a timeout for reading client request body. The timeout is set only for a period between two successive read operations, not for the transmission of the whole request body. If a client does not transmit anything within this time, the request is terminated with the 408 (Request Time-out) error. Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_timeout.

ClientKeepAlive

(Appears on: ClientSettingsPolicySpec)

ClientKeepAlive defines the keep-alive settings for clients.

Field Description
requests
int32 		(Optional)

Requests sets the maximum number of requests that can be served through one keep-alive connection. After the maximum number of requests are made, the connection is closed. Closing connections periodically is necessary to free per-connection memory allocations. Therefore, using too high maximum number of requests is not recommended as it can lead to excessive memory usage. Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests.
time
Duration 		(Optional)

Time defines the maximum time during which requests can be processed through one keep-alive connection. After this time is reached, the connection is closed following the subsequent request processing. Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_time.
timeout
ClientKeepAliveTimeout 		(Optional)

Timeout defines the keep-alive timeouts for clients.

ClientKeepAliveTimeout

(Appears on: ClientKeepAlive)

ClientKeepAliveTimeout defines the timeouts related to keep-alive client connections. Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout.

Field Description
server
Duration 		(Optional)

Server sets the timeout during which a keep-alive client connection will stay open on the server side. Setting this value to 0 disables keep-alive client connections.
header
Duration 		(Optional)

Header sets the timeout in the “Keep-Alive: timeout=time” response header field.

ClientSettingsPolicySpec

(Appears on: ClientSettingsPolicy)

ClientSettingsPolicySpec defines the desired state of ClientSettingsPolicy.

Field Description
body
ClientBody 		(Optional)

Body defines the client request body settings.
keepAlive
ClientKeepAlive 		(Optional)

KeepAlive defines the keep-alive settings.
targetRef
sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference

TargetRef identifies an API object to apply the policy to. Object must be in the same namespace as the policy. Support: Gateway, HTTPRoute, GRPCRoute.

ControllerLogLevel (string alias)

(Appears on: Logging)

ControllerLogLevel type defines the logging level for the control plane.

Value Description

"debug"

ControllerLogLevelDebug is the debug level for control plane logging.

"error"

ControllerLogLevelError is the error level for control plane logging.

"info"

ControllerLogLevelInfo is the info level for control plane logging.

ControllerStatus

(Appears on: SnippetsFilterStatus)

Field Description
controllerName
sigs.k8s.io/gateway-api/apis/v1.GatewayController

ControllerName is a domain/path string that indicates the name of the controller that wrote this status. This corresponds with the controllerName field on GatewayClass.

Example: “example.net/gateway-controller”.

The format of this field is DOMAIN “/” PATH, where DOMAIN and PATH are valid Kubernetes names (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).

Controllers MUST populate this field when writing status. Controllers should ensure that entries to status populated with their ControllerName are cleaned up when they are no longer necessary.
conditions
[]Kubernetes meta/v1.Condition 		(Optional)

Conditions describe the status of the SnippetsFilter.

Duration (string alias)

(Appears on: ClientBody, ClientKeepAlive, ClientKeepAliveTimeout, UpstreamKeepAlive, TelemetryExporter)

Duration is a string value representing a duration in time. Duration can be specified in milliseconds (ms), seconds (s), minutes (m), hours (h). A value without a suffix is seconds. Examples: 120s, 50ms, 5m, 1h.

Logging

(Appears on: NginxGatewaySpec)

Logging defines logging related settings for the control plane.

Field Description
level
ControllerLogLevel 		(Optional)

Level defines the logging level.

NginxContext (string alias)

(Appears on: Snippet)

NginxContext represents the NGINX configuration context.

Value Description

"http"

NginxContextHTTP is the http context of the NGINX configuration. https://nginx.org/en/docs/http/ngx_http_core_module.html#http

"http.server"

NginxContextHTTPServer is the server context of the NGINX configuration. https://nginx.org/en/docs/http/ngx_http_core_module.html#server

"http.server.location"

NginxContextHTTPServerLocation is the location context of the NGINX configuration. https://nginx.org/en/docs/http/ngx_http_core_module.html#location

"main"

NginxContextMain is the main context of the NGINX configuration.

NginxGatewayConditionReason (string alias)

NginxGatewayConditionReason defines the set of reasons that explain why a particular NginxGateway condition type has been raised.

Value Description

"Invalid"

NginxGatewayReasonInvalid is a reason that is used with the “Valid” condition when the condition is False.

"Valid"

NginxGatewayReasonValid is a reason that is used with the “Valid” condition when the condition is True.

NginxGatewayConditionType (string alias)

NginxGatewayConditionType is a type of condition associated with an NginxGateway. This type should be used with the NginxGatewayStatus.Conditions field.

Value Description

"Valid"

NginxGatewayConditionValid is a condition that is true when the NginxGateway configuration is syntactically and semantically valid.

NginxGatewaySpec

(Appears on: NginxGateway)

NginxGatewaySpec defines the desired state of the NginxGateway.

Field Description
logging
Logging 		(Optional)

Logging defines logging related settings for the control plane.

NginxGatewayStatus

(Appears on: NginxGateway)

NginxGatewayStatus defines the state of the NginxGateway.

Field Description
conditions
[]Kubernetes meta/v1.Condition 		(Optional)

ObservabilityPolicySpec

(Appears on: ObservabilityPolicy)

ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.

Field Description
tracing
Tracing 		(Optional)

Tracing allows for enabling and configuring tracing.
targetRefs
[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference

TargetRefs identifies the API object(s) to apply the policy to. Objects must be in the same namespace as the policy. Support: HTTPRoute, GRPCRoute.

Size (string alias)

(Appears on: ClientBody, UpstreamSettingsPolicySpec)

Size is a string value representing a size. Size can be specified in bytes, kilobytes (k), megabytes (m), or gigabytes (g). Examples: 1024, 8k, 1m.

Snippet

(Appears on: SnippetsFilterSpec)

Snippet represents an NGINX configuration snippet.

Field Description
context
NginxContext

Context is the NGINX context to insert the snippet into.
value
string

Value is the NGINX configuration snippet.

SnippetsFilterConditionReason (string alias)

SnippetsFilterConditionReason is a reason for a SnippetsFilter condition type.

Value Description

"Accepted"

SnippetsFilterConditionReasonAccepted is used with the Accepted condition type when the condition is true.

"Invalid"

SnippetsFilterConditionReasonInvalid is used with the Accepted condition type when SnippetsFilter is invalid.

SnippetsFilterConditionType (string alias)

SnippetsFilterConditionType is a type of condition associated with SnippetsFilter.

Value Description

"Accepted"

SnippetsFilterConditionTypeAccepted indicates that the SnippetsFilter is accepted.

Possible reasons for this condition to be True:

  • Accepted

Possible reasons for this condition to be False:

  • Invalid.

SnippetsFilterSpec

(Appears on: SnippetsFilter)

SnippetsFilterSpec defines the desired state of the SnippetsFilter.

Field Description
snippets
[]Snippet

Snippets is a list of NGINX configuration snippets. There can only be one snippet per context. Allowed contexts: main, http, http.server, http.server.location.

SnippetsFilterStatus

(Appears on: SnippetsFilter)

SnippetsFilterStatus defines the state of SnippetsFilter.

Field Description
controllers
[]ControllerStatus

Controllers is a list of Gateway API controllers that processed the SnippetsFilter and the status of the SnippetsFilter with respect to each controller.

SpanAttribute

(Appears on: Tracing, Telemetry, Tracing)

SpanAttribute is a key value pair to be added to a tracing span.

Field Description
key
string

Key is the key for a span attribute. Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’
value
string

Value is the value for a span attribute. Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’

TraceContext (string alias)

(Appears on: Tracing)

TraceContext specifies how to propagate traceparent/tracestate headers.

Value Description

"extract"

TraceContextExtract uses an existing trace context from the request, so that the identifiers of a trace and the parent span are inherited from the incoming request.

"ignore"

TraceContextIgnore skips context headers processing.

"inject"

TraceContextInject adds a new context to the request, overwriting existing headers, if any.

"propagate"

TraceContextPropagate updates the existing context (combines extract and inject).

TraceStrategy (string alias)

(Appears on: Tracing)

TraceStrategy defines the tracing strategy.

Value Description

"parent"

TraceStrategyParent enables tracing and only records spans if the parent span was sampled.

"ratio"

TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate.

Tracing

(Appears on: ObservabilityPolicySpec)

Tracing allows for enabling and configuring OpenTelemetry tracing.

Field Description
strategy
TraceStrategy

Strategy defines if tracing is ratio-based or parent-based.
ratio
int32 		(Optional)

Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100. By default, 100% of http requests are traced. Not applicable for parent-based tracing. If ratio is set to 0, tracing is disabled.
context
TraceContext 		(Optional)

Context specifies how to propagate traceparent/tracestate headers. Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context
spanName
string 		(Optional)

SpanName defines the name of the Otel span. By default is the name of the location for a request. If specified, applies to all locations that are created for a route. Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’ Examples of invalid names: some-$value, quoted-“value”-name, unescaped
spanAttributes
[]SpanAttribute 		(Optional)

SpanAttributes are custom key/value attributes that are added to each span.

UpstreamKeepAlive

(Appears on: UpstreamSettingsPolicySpec)

UpstreamKeepAlive defines the keep-alive settings for upstreams.

Field Description
connections
int32 		(Optional)

Connections sets the maximum number of idle keep-alive connections to upstream servers that are preserved in the cache of each nginx worker process. When this number is exceeded, the least recently used connections are closed. Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive
requests
int32 		(Optional)

Requests sets the maximum number of requests that can be served through one keep-alive connection. After the maximum number of requests are made, the connection is closed. Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests
time
Duration 		(Optional)

Time defines the maximum time during which requests can be processed through one keep-alive connection. After this time is reached, the connection is closed following the subsequent request processing. Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_time
timeout
Duration 		(Optional)

Timeout defines the keep-alive timeout for upstreams. Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout

UpstreamSettingsPolicySpec

(Appears on: UpstreamSettingsPolicy)

UpstreamSettingsPolicySpec defines the desired state of the UpstreamSettingsPolicy.

Field Description
zoneSize
Size 		(Optional)

ZoneSize is the size of the shared memory zone used by the upstream. This memory zone is used to share the upstream configuration between nginx worker processes. The more servers that an upstream has, the larger memory zone is required. Default: OSS: 512k, Plus: 1m. Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone
keepAlive
UpstreamKeepAlive 		(Optional)

KeepAlive defines the keep-alive settings.
targetRefs
[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference

TargetRefs identifies API object(s) to apply the policy to. Objects must be in the same namespace as the policy. Support: Service

TargetRefs must be distinct. The name field must be unique for all targetRef entries in the UpstreamSettingsPolicy.

gateway.nginx.org/v1alpha2

Package v1alpha2 contains API Schema definitions for the gateway.nginx.org API group.

Resource Types:

NginxProxy

NginxProxy is a configuration object that can be referenced from a GatewayClass parametersRef or a Gateway infrastructure.parametersRef. It provides a way to configure data plane settings. If referenced from a GatewayClass, the settings apply to all Gateways attached to the GatewayClass. If referenced from a Gateway, the settings apply to that Gateway alone. If both a Gateway and its GatewayClass reference an NginxProxy, the settings are merged. Settings specified on the Gateway NginxProxy override those set on the GatewayClass NginxProxy.

Field Description
apiVersion
string		 gateway.nginx.org/v1alpha2
kind
string 		NginxProxy
metadata
Kubernetes meta/v1.ObjectMeta 		Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
NginxProxySpec

Spec defines the desired state of the NginxProxy.



ipFamily
IPFamilyType 		(Optional)

IPFamily specifies the IP family to be used by the NGINX. Default is “dual”, meaning the server will use both IPv4 and IPv6.
telemetry
Telemetry 		(Optional)

Telemetry specifies the OpenTelemetry configuration.
metrics
Metrics 		(Optional)

Metrics defines the configuration for Prometheus scraping metrics. Changing this value results in a re-roll of the NGINX deployment.
rewriteClientIP
RewriteClientIP 		(Optional)

RewriteClientIP defines configuration for rewriting the client IP to the original client’s IP.
logging
NginxLogging 		(Optional)

Logging defines logging related settings for NGINX.
nginxPlus
NginxPlus 		(Optional)

NginxPlus specifies NGINX Plus additional settings.
disableHTTP2
bool 		(Optional)

DisableHTTP2 defines if http2 should be disabled for all servers. If not specified, or set to false, http2 will be enabled for all servers.
disableSNIHostValidation
bool 		(Optional)

DisableSNIHostValidation disables the validation that ensures the SNI hostname matches the Host header in HTTPS requests. When disabled, HTTPS connections can be reused for requests to different hostnames covered by the same certificate. This resolves HTTP/2 connection coalescing issues with wildcard certificates but introduces security risks as described in Gateway API GEP-3567. If not specified, defaults to false (validation enabled).
kubernetes
KubernetesSpec 		(Optional)

Kubernetes contains the configuration for the NGINX Deployment and Service Kubernetes objects.
workerConnections
int32 		(Optional)

WorkerConnections specifies the maximum number of simultaneous connections that can be opened by a worker process. Default is 1024.

ObservabilityPolicy

ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the GatewayClass parametersRef.

Field Description
apiVersion
string		 gateway.nginx.org/v1alpha2
kind
string 		ObservabilityPolicy
metadata
Kubernetes meta/v1.ObjectMeta 		Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
ObservabilityPolicySpec

Spec defines the desired state of the ObservabilityPolicy.



tracing
Tracing 		(Optional)

Tracing allows for enabling and configuring tracing.
targetRefs
[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference

TargetRefs identifies the API object(s) to apply the policy to. Objects must be in the same namespace as the policy. Support: HTTPRoute, GRPCRoute.

TargetRefs must be distinct. This means that the multi-part key defined by kind and name must be unique across all targetRef entries in the ObservabilityPolicy.
status
sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus

Status defines the state of the ObservabilityPolicy.

AgentLogLevel (string alias)

(Appears on: NginxLogging)

AgentLevel defines the log level of the NGINX agent process.

Value Description

"debug"

AgentLogLevelDebug is the debug level NGINX agent logs.

"error"

AgentLogLevelError is the error level NGINX agent logs.

"fatal"

AgentLogLevelFatal is the fatal level NGINX agent logs.

"info"

AgentLogLevelInfo is the info level NGINX agent logs.

"panic"

AgentLogLevelPanic is the panic level NGINX agent logs.

AutoscalingSpec

(Appears on: DeploymentSpec)

AutoscalingSpec is the configuration for the Horizontal Pod Autoscaling.

Field Description
behavior
Kubernetes autoscaling/v2.HorizontalPodAutoscalerBehavior 		(Optional)

Behavior configures the scaling behavior of the target in both Up and Down directions (scaleUp and scaleDown fields respectively). If not set, the default HPAScalingRules for scale up and scale down are used.
targetCPUUtilizationPercentage
int32 		(Optional)

Target cpu utilization percentage of HPA.
targetMemoryUtilizationPercentage
int32 		(Optional)

Target memory utilization percentage of HPA.
minReplicas
int32 		(Optional)

Minimum number of replicas.
metrics
[]Kubernetes autoscaling/v2.MetricSpec 		(Optional)

Metrics configures additional metrics options.
maxReplicas
int32

Maximum number of replicas.
enable
bool

Enable or disable Horizontal Pod Autoscaler.

ContainerSpec

(Appears on: DaemonSetSpec, DeploymentSpec)

ContainerSpec defines container fields for the NGINX container.

Field Description
debug
bool 		(Optional)

Debug enables debugging for NGINX by using the nginx-debug binary.
image
Image 		(Optional)

Image is the NGINX image to use.
resources
Kubernetes core/v1.ResourceRequirements 		(Optional)

Resources describes the compute resource requirements.
lifecycle
Kubernetes core/v1.Lifecycle 		(Optional)

Lifecycle describes actions that the management system should take in response to container lifecycle events. For the PostStart and PreStop lifecycle handlers, management of the container blocks until the action is complete, unless the container process fails, in which case the handler is aborted.
readinessProbe
ReadinessProbeSpec 		(Optional)

ReadinessProbe defines the readiness probe for the NGINX container.
hostPorts
[]HostPort 		(Optional)

HostPorts are the list of ports to expose on the host.
volumeMounts
[]Kubernetes core/v1.VolumeMount 		(Optional)

VolumeMounts describe the mounting of Volumes within a container.

DaemonSetSpec

(Appears on: KubernetesSpec)

DaemonSet is the configuration for the NGINX DaemonSet.

Field Description
container
ContainerSpec 		(Optional)

Container defines container fields for the NGINX container.
pod
PodSpec 		(Optional)

Pod defines Pod-specific fields.
patches
[]Patch 		(Optional)

Patches are custom patches to apply to the NGINX DaemonSet.

DeploymentSpec

(Appears on: KubernetesSpec)

Deployment is the configuration for the NGINX Deployment.

Field Description
replicas
int32 		(Optional)

Number of desired Pods.
autoscaling
AutoscalingSpec 		(Optional)

Autoscaling defines the configuration for Horizontal Pod Autoscaling.
pod
PodSpec 		(Optional)

Pod defines Pod-specific fields.
container
ContainerSpec 		(Optional)

Container defines container fields for the NGINX container.
patches
[]Patch 		(Optional)

Patches are custom patches to apply to the NGINX Deployment.

DisableTelemetryFeature (string alias)

(Appears on: Telemetry)

DisableTelemetryFeature is a telemetry feature that can be disabled.

Value Description

"DisableTracing"

DisableTracing disables the OpenTelemetry tracing feature.

ExternalTrafficPolicy (string alias)

(Appears on: ServiceSpec)

ExternalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, ExternalIPs, and LoadBalancer IPs. Ignored for ClusterIP services.

Value Description

"Cluster"

ExternalTrafficPolicyCluster routes traffic to all endpoints.

"Local"

ExternalTrafficPolicyLocal preserves the source IP of the traffic by routing only to endpoints on the same node as the traffic was received on (dropping the traffic if there are no local endpoints).

HostPort

(Appears on: ContainerSpec)

HostPort exposes an nginx container port on the host.

Field Description
port
int32

Port to expose on the host.
containerPort
int32

ContainerPort is the port on the nginx container to map to the HostPort.

IPFamilyType (string alias)

(Appears on: NginxProxySpec)

IPFamilyType specifies the IP family to be used by NGINX.

Value Description

"dual"

Dual specifies that NGINX will use both IPv4 and IPv6.

"ipv4"

IPv4 specifies that NGINX will use only IPv4.

"ipv6"

IPv6 specifies that NGINX will use only IPv6.

Image

(Appears on: ContainerSpec)

Image is the NGINX image to use.

Field Description
repository
string 		(Optional)

Repository is the image path. Default is ghcr.io/nginx/nginx-gateway-fabric/nginx.
tag
string 		(Optional)

Tag is the image tag to use. Default matches the tag of the control plane.
pullPolicy
PullPolicy 		(Optional)

PullPolicy describes a policy for if/when to pull a container image.

KubernetesSpec

(Appears on: NginxProxySpec)

KubernetesSpec contains the configuration for the NGINX Deployment and Service Kubernetes objects.

Field Description
deployment
DeploymentSpec 		(Optional)

Deployment is the configuration for the NGINX Deployment. This is the default deployment option.
daemonSet
DaemonSetSpec 		(Optional)

DaemonSet is the configuration for the NGINX DaemonSet.
service
ServiceSpec 		(Optional)

Service is the configuration for the NGINX Service.

Metrics

(Appears on: NginxProxySpec)

Metrics defines the configuration for Prometheus scraping metrics.

Field Description
port
int32 		(Optional)

Port where the Prometheus metrics are exposed.
disable
bool 		(Optional)

Disable serving Prometheus metrics on the listen port.

NginxErrorLogLevel (string alias)

(Appears on: NginxLogging)

NginxErrorLogLevel type defines the log level of error logs for NGINX.

Value Description

"alert"

NginxLogLevelAlert is the alert level for NGINX error logs.

"crit"

NginxLogLevelCrit is the crit level for NGINX error logs.

"debug"

NginxLogLevelDebug is the debug level for NGINX error logs.

"emerg"

NginxLogLevelEmerg is the emerg level for NGINX error logs.

"error"

NginxLogLevelError is the error level for NGINX error logs.

"info"

NginxLogLevelInfo is the info level for NGINX error logs.

"notice"

NginxLogLevelNotice is the notice level for NGINX error logs.

"warn"

NginxLogLevelWarn is the warn level for NGINX error logs.

NginxLogging

(Appears on: NginxProxySpec)

NginxLogging defines logging related settings for NGINX.

Field Description
errorLevel
NginxErrorLogLevel 		(Optional)

ErrorLevel defines the error log level. Possible log levels listed in order of increasing severity are debug, info, notice, warn, error, crit, alert, and emerg. Setting a certain log level will cause all messages of the specified and more severe log levels to be logged. For example, the log level ‘error’ will cause error, crit, alert, and emerg messages to be logged. https://nginx.org/en/docs/ngx_core_module.html#error_log
agentLevel
AgentLogLevel 		(Optional)

AgentLevel defines the log level of the NGINX agent process. Changing this value results in a re-roll of the NGINX deployment.

NginxPlus

(Appears on: NginxProxySpec)

NginxPlus specifies NGINX Plus additional settings. These will only be applied if NGINX Plus is being used.

Field Description
allowedAddresses
[]NginxPlusAllowAddress 		(Optional)

AllowedAddresses specifies IPAddresses or CIDR blocks to the allow list for accessing the NGINX Plus API.

NginxPlusAllowAddress

(Appears on: NginxPlus)

NginxPlusAllowAddress specifies the address type and value for an NginxPlus allow address.

Field Description
type
NginxPlusAllowAddressType

Type specifies the type of address.
value
string

Value specifies the address value.

NginxPlusAllowAddressType (string alias)

(Appears on: NginxPlusAllowAddress)

NginxPlusAllowAddressType specifies the type of address.

Value Description

"CIDR"

NginxPlusAllowCIDRAddressType specifies that the address is a CIDR block.

"IPAddress"

NginxPlusAllowIPAddressType specifies that the address is an IP address.

NginxProxySpec

(Appears on: NginxProxy)

NginxProxySpec defines the desired state of the NginxProxy.

Field Description
ipFamily
IPFamilyType 		(Optional)

IPFamily specifies the IP family to be used by the NGINX. Default is “dual”, meaning the server will use both IPv4 and IPv6.
telemetry
Telemetry 		(Optional)

Telemetry specifies the OpenTelemetry configuration.
metrics
Metrics 		(Optional)

Metrics defines the configuration for Prometheus scraping metrics. Changing this value results in a re-roll of the NGINX deployment.
rewriteClientIP
RewriteClientIP 		(Optional)

RewriteClientIP defines configuration for rewriting the client IP to the original client’s IP.
logging
NginxLogging 		(Optional)

Logging defines logging related settings for NGINX.
nginxPlus
NginxPlus 		(Optional)

NginxPlus specifies NGINX Plus additional settings.
disableHTTP2
bool 		(Optional)

DisableHTTP2 defines if http2 should be disabled for all servers. If not specified, or set to false, http2 will be enabled for all servers.
disableSNIHostValidation
bool 		(Optional)

DisableSNIHostValidation disables the validation that ensures the SNI hostname matches the Host header in HTTPS requests. When disabled, HTTPS connections can be reused for requests to different hostnames covered by the same certificate. This resolves HTTP/2 connection coalescing issues with wildcard certificates but introduces security risks as described in Gateway API GEP-3567. If not specified, defaults to false (validation enabled).
kubernetes
KubernetesSpec 		(Optional)

Kubernetes contains the configuration for the NGINX Deployment and Service Kubernetes objects.
workerConnections
int32 		(Optional)

WorkerConnections specifies the maximum number of simultaneous connections that can be opened by a worker process. Default is 1024.

NodePort

(Appears on: ServiceSpec)

NodePort creates a port on each node on which the NGINX data plane service is exposed. The NodePort MUST map to a Gateway listener port, otherwise it will be ignored. If not specified, Kubernetes allocates a NodePort automatically if required. The default NodePort range enforced by Kubernetes is 30000-32767.

Field Description
port
int32

Port is the NodePort to expose.
listenerPort
int32

ListenerPort is the Gateway listener port that this NodePort maps to.

ObservabilityPolicySpec

(Appears on: ObservabilityPolicy)

ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.

Field Description
tracing
Tracing 		(Optional)

Tracing allows for enabling and configuring tracing.
targetRefs
[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference

TargetRefs identifies the API object(s) to apply the policy to. Objects must be in the same namespace as the policy. Support: HTTPRoute, GRPCRoute.

TargetRefs must be distinct. This means that the multi-part key defined by kind and name must be unique across all targetRef entries in the ObservabilityPolicy.

Patch

(Appears on: DaemonSetSpec, DeploymentSpec, ServiceSpec)

Patch defines a patch to apply to a Kubernetes object.

Field Description
type
PatchType 		(Optional)

Type is the type of patch. Defaults to StrategicMerge.
value
k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1.JSON 		(Optional)

Value is the patch data as raw JSON. For StrategicMerge and Merge patches, this should be a JSON object. For JSONPatch patches, this should be a JSON array of patch operations.

PatchType (string alias)

(Appears on: Patch)

PatchType specifies the type of patch.

Value Description

"JSONPatch"

PatchTypeJSONPatch uses JSON patch (RFC 6902).

"Merge"

PatchTypeMerge uses merge patch (RFC 7386).

"StrategicMerge"

PatchTypeStrategicMerge uses strategic merge patch.

PodSpec

(Appears on: DaemonSetSpec, DeploymentSpec)

PodSpec defines Pod-specific fields.

Field Description
terminationGracePeriodSeconds
int64 		(Optional)

TerminationGracePeriodSeconds is the optional duration in seconds the pod needs to terminate gracefully. Value must be non-negative integer. The value zero indicates stop immediately via the kill signal (no opportunity to shut down). If this value is nil, the default grace period will be used instead. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. Defaults to 30 seconds.
affinity
Kubernetes core/v1.Affinity 		(Optional)

Affinity is the pod’s scheduling constraints.
nodeSelector
map[string]string 		(Optional)

NodeSelector is a selector which must be true for the pod to fit on a node. Selector which must match a node’s labels for the pod to be scheduled on that node.
tolerations
[]Kubernetes core/v1.Toleration 		(Optional)

Tolerations allow the scheduler to schedule Pods with matching taints.
volumes
[]Kubernetes core/v1.Volume 		(Optional)

Volumes represents named volumes in a pod that may be accessed by any container in the pod.
topologySpreadConstraints
[]Kubernetes core/v1.TopologySpreadConstraint 		(Optional)

TopologySpreadConstraints describes how a group of Pods ought to spread across topology domains. Scheduler will schedule Pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed.

PullPolicy (string alias)

(Appears on: Image)

PullPolicy describes a policy for if/when to pull a container image.

Value Description

"Always"

PullAlways means that kubelet always attempts to pull the latest image. Container will fail if the pull fails.

"IfNotPresent"

PullIfNotPresent means that kubelet pulls if the image isn’t present on disk. Container will fail if the image isn’t present and the pull fails.

"Never"

PullNever means that kubelet never pulls an image, but only uses a local image. Container will fail if the image isn’t present.

ReadinessProbeSpec

(Appears on: ContainerSpec)

ReadinessProbeSpec defines the configuration for the NGINX readiness probe.

Field Description
port
int32 		(Optional)

Port is the port on which the readiness endpoint is exposed. If not specified, the default port is 8081.
initialDelaySeconds
int32 		(Optional)

InitialDelaySeconds is the number of seconds after the container has started before the readiness probe is initiated. If not specified, the default is 3 seconds.

RewriteClientIP

(Appears on: NginxProxySpec)

RewriteClientIP specifies the configuration for rewriting the client’s IP address.

Field Description
mode
RewriteClientIPModeType 		(Optional)

Mode defines how NGINX will rewrite the client’s IP address. There are two possible modes: - ProxyProtocol: NGINX will rewrite the client’s IP using the PROXY protocol header. - XForwardedFor: NGINX will rewrite the client’s IP using the X-Forwarded-For header. Sets NGINX directive real_ip_header: https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header
setIPRecursively
bool 		(Optional)

SetIPRecursively configures whether recursive search is used when selecting the client’s address from the X-Forwarded-For header. It is used in conjunction with TrustedAddresses. If enabled, NGINX will recurse on the values in X-Forwarded-Header from the end of array to start of array and select the first untrusted IP. For example, if X-Forwarded-For is [11.11.11.11, 22.22.22.22, 55.55.55.1], and TrustedAddresses is set to 55.55.55.1⁄32, NGINX will rewrite the client IP to 22.22.22.22. If disabled, NGINX will select the IP at the end of the array. In the previous example, 55.55.55.1 would be selected. Sets NGINX directive real_ip_recursive: https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive
trustedAddresses
[]RewriteClientIPAddress 		(Optional)

TrustedAddresses specifies the addresses that are trusted to send correct client IP information. If a request comes from a trusted address, NGINX will rewrite the client IP information, and forward it to the backend in the X-Forwarded-For* and X-Real-IP headers. If the request does not come from a trusted address, NGINX will not rewrite the client IP information. To trust all addresses (not recommended for production), set to 0.0.0.0/0. If no addresses are provided, NGINX will not rewrite the client IP information. Sets NGINX directive set_real_ip_from: https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from This field is required if mode is set.

RewriteClientIPAddress

(Appears on: RewriteClientIP)

RewriteClientIPAddress specifies the address type and value for a RewriteClientIP address.

Field Description
type
RewriteClientIPAddressType

Type specifies the type of address.
value
string

Value specifies the address value.

RewriteClientIPAddressType (string alias)

(Appears on: RewriteClientIPAddress)

RewriteClientIPAddressType specifies the type of address.

Value Description

"CIDR"

RewriteClientIPCIDRAddressType specifies that the address is a CIDR block.

"Hostname"

RewriteClientIPHostnameAddressType specifies that the address is a Hostname.

"IPAddress"

RewriteClientIPIPAddressType specifies that the address is an IP address.

RewriteClientIPModeType (string alias)

(Appears on: RewriteClientIP)

RewriteClientIPModeType defines how NGINX Gateway Fabric will determine the client’s original IP address.

Value Description

"ProxyProtocol"

RewriteClientIPModeProxyProtocol configures NGINX to accept PROXY protocol and set the client’s IP address to the IP address in the PROXY protocol header. Sets the proxy_protocol parameter on the listen directive of all servers and sets real_ip_header to proxy_protocol: https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header.

"XForwardedFor"

RewriteClientIPModeXForwardedFor configures NGINX to set the client’s IP address to the IP address in the X-Forwarded-For HTTP header. https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header.

ServiceSpec

(Appears on: KubernetesSpec)

ServiceSpec is the configuration for the NGINX Service.

Field Description
type
ServiceType 		(Optional)

ServiceType describes ingress method for the Service.
externalTrafficPolicy
ExternalTrafficPolicy 		(Optional)

ExternalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, ExternalIPs, and LoadBalancer IPs.
loadBalancerIP
string 		(Optional)

LoadBalancerIP is a static IP address for the load balancer. Requires service type to be LoadBalancer.
loadBalancerClass
string 		(Optional)

LoadBalancerClass is the class of the load balancer implementation this Service belongs to. Requires service type to be LoadBalancer.
loadBalancerSourceRanges
[]string 		(Optional)

LoadBalancerSourceRanges are the IP ranges (CIDR) that are allowed to access the load balancer. Requires service type to be LoadBalancer.
nodePorts
[]NodePort 		(Optional)

NodePorts are the list of NodePorts to expose on the NGINX data plane service. Each NodePort MUST map to a Gateway listener port, otherwise it will be ignored. The default NodePort range enforced by Kubernetes is 30000-32767.
patches
[]Patch 		(Optional)

Patches are custom patches to apply to the NGINX Service.

ServiceType (string alias)

(Appears on: ServiceSpec)

ServiceType describes ingress method for the Service.

Value Description

"ClusterIP"

ServiceTypeClusterIP means a Service will only be accessible inside the cluster, via the cluster IP.

"LoadBalancer"

ServiceTypeLoadBalancer means a Service will be exposed via an external load balancer (if the cloud provider supports it), in addition to ‘NodePort’ type.

"NodePort"

ServiceTypeNodePort means a Service will be exposed on one port of every node, in addition to ‘ClusterIP’ type.

Telemetry

(Appears on: NginxProxySpec)

Telemetry specifies the OpenTelemetry configuration.

Field Description
disabledFeatures
[]DisableTelemetryFeature 		(Optional)

DisabledFeatures specifies OpenTelemetry features to be disabled.
exporter
TelemetryExporter 		(Optional)

Exporter specifies OpenTelemetry export parameters.
serviceName
string 		(Optional)

ServiceName is the “service.name” attribute of the OpenTelemetry resource. Default is ‘ngf::’. If a value is provided by the user, then the default becomes a prefix to that value.
spanAttributes
[]SpanAttribute 		(Optional)

SpanAttributes are custom key/value attributes that are added to each span.

TelemetryExporter

(Appears on: Telemetry)

TelemetryExporter specifies OpenTelemetry export parameters.

Field Description
interval
Duration 		(Optional)

Interval is the maximum interval between two exports. Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_exporter
batchSize
int32 		(Optional)

BatchSize is the maximum number of spans to be sent in one batch per worker. Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_exporter
batchCount
int32 		(Optional)

BatchCount is the number of pending batches per worker, spans exceeding the limit are dropped. Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_exporter
endpoint
string 		(Optional)

Endpoint is the address of OTLP/gRPC endpoint that will accept telemetry data. Format: alphanumeric hostname with optional http scheme and optional port.

TraceContext (string alias)

(Appears on: Tracing)

TraceContext specifies how to propagate traceparent/tracestate headers.

Value Description

"extract"

TraceContextExtract uses an existing trace context from the request, so that the identifiers of a trace and the parent span are inherited from the incoming request.

"ignore"

TraceContextIgnore skips context headers processing.

"inject"

TraceContextInject adds a new context to the request, overwriting existing headers, if any.

"propagate"

TraceContextPropagate updates the existing context (combines extract and inject).

TraceStrategy (string alias)

(Appears on: Tracing)

TraceStrategy defines the tracing strategy.

Value Description

"parent"

TraceStrategyParent enables tracing and only records spans if the parent span was sampled.

"ratio"

TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate.

Tracing

(Appears on: ObservabilityPolicySpec)

Tracing allows for enabling and configuring OpenTelemetry tracing.

Field Description
strategy
TraceStrategy

Strategy defines if tracing is ratio-based or parent-based.
ratio
int32 		(Optional)

Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100. By default, 100% of http requests are traced. Not applicable for parent-based tracing. If ratio is set to 0, tracing is disabled.
context
TraceContext 		(Optional)

Context specifies how to propagate traceparent/tracestate headers. Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context
spanName
string 		(Optional)

SpanName defines the name of the Otel span. By default is the name of the location for a request. If specified, applies to all locations that are created for a route. Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’ Examples of invalid names: some-$value, quoted-“value”-name, unescaped
spanAttributes
[]SpanAttribute 		(Optional)

SpanAttributes are custom key/value attributes that are added to each span.

Generated with gen-crd-api-reference-docs