API reference

Spec defines the desired state of the AuthenticationFilter.

Status defines the state of the AuthenticationFilter.

Spec defines the desired state of the ClientSettingsPolicy.

Status defines the state of the ClientSettingsPolicy.

NginxGatewaySpec defines the desired state of the NginxGateway.

NginxGatewayStatus defines the state of the NginxGateway.

Spec defines the desired state of the ProxySettingsPolicy.

Status defines the state of the ProxySettingsPolicy.

Spec defines the desired state of the RateLimitPolicy.

Status defines the state of the RateLimitPolicy.

Spec defines the desired state of the SnippetsFilter.

Status defines the state of the SnippetsFilter.

Spec defines the desired state of the SnippetsPolicy.

Status defines the current state of the SnippetsPolicy.

Spec defines the desired state of the UpstreamSettingsPolicy.

Status defines the state of the UpstreamSettingsPolicy.

Spec defines the desired state of the WAFPolicy.

Status defines the state of the WAFPolicy.

"Basic"

AuthTypeBasic is the HTTP Basic Authentication mechanism.

"JWT"

AuthTypeJWT is the JWT Authentication mechanism.

"OIDC"

AuthTypeOIDC is the OpenID Connect Authentication mechanism.

"Accepted"

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

"Invalid"

AuthenticationFilterConditionReasonInvalid is used with the Accepted condition type when the filter is invalid.

"Accepted"

AuthenticationFilterConditionTypeAccepted indicates that the AuthenticationFilter is accepted.

Possible reasons for this condition to be True: * Accepted

Possible reasons for this condition to be False: * Invalid.

Basic configures HTTP Basic Authentication.

OIDC configures OpenID Connect Authentication (NGINX Plus).

JWT configures JSON Web Token authentication (NGINX Plus).

Type selects the authentication mechanism.

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

SecretRef references a Secret containing credentials in the same namespace.

Realm used by NGINX auth_basic directive. https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html#auth_basic Also configures “realm=”” in WWW-Authenticate header in error page location.

SecretRef references a Kubernetes Secret in the same namespace as the WAFPolicy. The Secret may contain: - “username” and “password” fields for HTTP Basic Authentication - “token” field for Bearer Token Authentication (NIM) or APIToken Authentication (N1C)

Interval is the period between poll cycles. Defaults to 5m when polling is enabled but no interval is set.

Enabled activates periodic re-fetching of the bundle. When true, NGF fetches the bundle on each interval and deploys it only if its checksum differs from the last successfully fetched version.

ExpectedChecksum is the expected SHA256 checksum of the bundle. If set, the downloaded bundle must match this checksum or it will be rejected. For N1C sources, the checksum reported by the N1C API is verified automatically; set this field only if you want to enforce an additional, independently known value.

VerifyChecksum enables automatic checksum verification by fetching a companion checksum file at .sha256 and comparing it against the downloaded bundle. Only supported when the policy source type is HTTP (policySource.httpSource or logSource.url); setting this for NIM or N1C sources is rejected at admission. Note: for N1C sources, bundle integrity is always verified automatically using the checksum returned by the N1C compile API — this field is not needed. Mutually exclusive with expectedChecksum.

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

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 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 defines the keep-alive timeouts for clients.

MinTimeout defines the timeout for which the keep-alive client connection will not be closed on the server side for connection reuse or on graceful shutdown of worker processes. Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_min_timeout.

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 sets the timeout in the “Keep-Alive: timeout=time” response header field.

Body defines the client request body settings.

KeepAlive defines the keep-alive settings.

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

"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.

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 describe the status of the SnippetsFilter.

"log_all"

DefaultLogProfileAll logs all events.

"log_blocked"

DefaultLogProfileBlocked logs blocked events.

"log_default"

DefaultLogProfileDefault logs illegal events (equivalent to log_illegal).

"log_grpc_all"

DefaultLogProfileGRPCAll logs all gRPC events.

"log_grpc_blocked"

DefaultLogProfileGRPCBlocked logs blocked gRPC events.

"log_grpc_illegal"

DefaultLogProfileGRPCIllegal logs illegal gRPC events.

"log_illegal"

DefaultLogProfileIllegal logs illegal events.

URL is the full URL of the compiled policy bundle (.tgz), e.g. “https://storage.example.com/bundles/policy.tgz”.

File specifies local JWKS configuration. Required when Source == File.

KeyCache is the cache duration for keys. Configures auth_jwt_key_cache directive. https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_cache Example: “auth_jwt_key_cache 10m;”.

Remote specifies remote JWKS configuration. Required when Source == Remote.

Realm used by NGINX auth_jwt directive https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt Configures “realm=”” in WWW-Authenticate header in error page location.

Source selects how JWT keys are provided: local file or remote JWKS.

SecretRef references a Secret containing the JWKS.

"File"

JWTKeySourceFile configures JWT to fetch JWKS from a local secret.

"Remote"

JWTKeySourceRemote configures JWT to fetch JWKS from a remote source.

URI is the JWKS endpoint.

CACertificateRefs references a list of secrets containing trusted CA certificates in PEM format used to verify the server certificate of the JWKS endpoint. The referenced secrets must contain an entry with the key “ca.crt”. Only one secret can be referenced currently. If not specified, the system CA bundle is used.

Directive: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_trusted_certificate

"hash"

LoadBalancingTypeHash enables generic hash-based load balancing, routing requests to upstream servers based on a hash of a specified key HashMethodKey field must be set when this method is selected. Example configuration: hash $binary_remote_addr;.

"hash consistent"

LoadBalancingTypeHashConsistent enables consistent hash-based load balancing, which minimizes the number of keys remapped when a server is added or removed. HashMethodKey field must be set when this method is selected. Example configuration: hash $binary_remote_addr consistent;.

"ip_hash"

LoadBalancingTypeIPHash enables IP hash-based load balancing, ensuring requests from the same client IP are routed to the same upstream server.

"least_conn"

LoadBalancingTypeLeastConnection enables least-connections load balancing, routing requests to the upstream server with the fewest active connections.

"least_time header"

LoadBalancingTypeLeastTimeHeader enables least-time load balancing, routing requests to the upstream server with the least time to receive the response header.

"least_time header inflight"

LoadBalancingTypeLeastTimeHeaderInflight enables least-time load balancing, routing requests to the upstream server with the least time to receive the response header, considering the incomplete requests.

"least_time last_byte"

LoadBalancingTypeLeastTimeLastByte enables least-time load balancing, routing requests to the upstream server with the least time to receive the full response.

"least_time last_byte inflight"

LoadBalancingTypeLeastTimeLastByteInflight enables least-time load balancing, routing requests to the upstream server with the least time to receive the full response, considering the incomplete requests.

"random"

LoadBalancingTypeRandom enables random load balancing, routing requests to upstream servers in a random manner.

"random two"

LoadBalancingTypeRandomTwo enables a variation of random load balancing that randomly selects two servers and forwards traffic to one of them. The default method is least_conn which passes a request to a server with the least number of active connections.

"random two least_conn"

LoadBalancingTypeRandomTwoLeastConnection enables a variation of least-connections balancing that randomly selects two servers and forwards traffic to the one with fewer active connections.

"random two least_time=header"

LoadBalancingTypeRandomTwoLeastTimeHeader enables a variation of least-time load balancing that randomly selects two servers and forwards traffic to the one with the least time to receive the response header.

"random two least_time=last_byte"

LoadBalancingTypeRandomTwoLeastTimeLastByte enables a variation of least-time load balancing that randomly selects two servers and forwards traffic to the one with the least time to receive the full response.

"round_robin"

LoadBalancingTypeRoundRobin enables round-robin load balancing, distributing requests evenly across all upstream servers.

Name is the name of the referenced object.

Rules contains the list of rate limit rules.

DefaultProfile selects one of the built-in WAF log profile bundles shipped with the WAF engine. Mutually exclusive with HTTPSource, NIMSource, and N1CSource.

HTTPSource configures direct bundle fetching from an HTTP/HTTPS URL. Mutually exclusive with DefaultProfile, NIMSource and N1CSource.

NIMSource configures bundle fetching from NGINX Instance Manager. Mutually exclusive with DefaultProfile, HTTPSource and N1CSource.

N1CSource configures bundle fetching from F5 NGINX One Console. Mutually exclusive with DefaultProfile, HTTPSource, and NIMSource.

Auth configures authentication credentials for fetching the log bundle. Only applicable when url is set.

TLSSecretRef references a Secret containing a custom CA certificate (key: “ca.crt”). Only applicable when url is set.

Validation configures integrity verification for the downloaded log bundle. Only applicable when url is set.

Polling configures automatic periodic re-fetching of the log bundle. Only applicable when url is set.

Timeout is the maximum duration for a single log bundle fetch attempt. Defaults to 30s when not set. Only applicable when url is set.

RetryAttempts is the maximum number of additional fetch attempts on transient failures (network errors, HTTP 5xx). Set to 0 to disable retries. Defaults to 3. Non-transient errors (HTTP 4xx, checksum mismatch) are never retried. Only applicable when url is set.

InsecureSkipVerify disables TLS certificate verification when fetching the bundle. Not recommended for production use.

Level defines the logging level.

PolicyName is the name of the security policy in N1C. Mutually exclusive with policyObjectID.

PolicyObjectID is the unique object identifier of the security policy in N1C (e.g. “pol_-IUuEUN7ST63oRC7AlQPLw”). Mutually exclusive with policyName.

PolicyVersionID pins a specific version of the policy bundle using its opaque version ID (e.g. “pv_UJ2gL5fOQ3Gnb3OVuVo1XA”). When omitted, the latest available version is used.

URL is the base URL of the F5 NGINX One Console instance, e.g. “https://.volterra.us”.

Namespace is the NGINX One Console namespace that owns the security policy.

ProfileName is the name of the log profile in N1C that corresponds to the log profile bundle.

ProfileObjectID is the unique object identifier of the log profile in N1C (e.g. “lp_8s8uZxLpThWwEGF7LTn_rA”) that corresponds to the log profile bundle.

URL is the base URL of the F5 NGINX One Console instance, e.g. “https://.volterra.us”.

Namespace is the NGINX One Console namespace that owns the log profile.

PolicyName is the name of the compiled policy bundle in NIM. Mutually exclusive with policyUID.

PolicyUID is the unique identifier of the compiled policy bundle in NIM. Mutually exclusive with policyName. Must be a valid UUID (e.g. “2bc1e3ac-7990-4ca4-910a-8634c444c804”).

URL is the base URL of the NGINX Instance Manager instance, e.g. “https://nim.example.com”.

ProfileName is the name of the compiled log profile bundle in NIM.

URL is the base URL of the NGINX Instance Manager instance, e.g. “https://nim.example.com”.

"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.

"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.

"Valid"

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

Logging defines logging related settings for the control plane.

CRLSecretRef references a Secret containing a certificate revocation list in PEM format. The referenced Secret must contain an entry with the key “ca.crl”. This is used to verify that certificates presented by the OpenID Provider endpoints have not been revoked.

ConfigURL sets a custom URL to retrieve the OpenID Provider metadata. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#config_url NGINX Default: /.well-known/openid-configuration

PKCE enables Proof Key for Code Exchange (PKCE) for the authentication flow. If nil, NGINX automatically enables PKCE when the OpenID Provider requires it. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#pkce

ExtraAuthArgs sets additional query arguments for the authentication request URL. Arguments are appended with “&”. For example: “prompt=consent&audience=api”. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#extra_auth_args

Session configures session management for OIDC authentication.

Logout defines the logout behavior for OIDC authentication.

RedirectURI sets a custom redirect URI for the OIDC callback. If a path-only URI is specified, a callback location block is created to handle the redirect from the OIDC provider. If a full URI is specified, it points to an external callback handler; no location block is created. If not specified, defaults to /oidccallback_. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#redirect_uri NGINX Default: /oidc_callback Example: /oidc_callback, https://cafe.example.com:8442/oidc_callback

Issuer is the URL of the OpenID Provider. Must exactly match the “issuer” value from the provider’s .well-known/openid-configuration endpoint. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#issuer Examples: - Keycloak: “https://keycloak.example.com/realms/my-realm” - Okta: “https://dev-123456.okta.com/oauth2/default” - Auth0: “https://my-tenant.auth0.com/”

ClientID is the client identifier registered with the OpenID Provider. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_id

ClientSecretRef references a Kubernetes secret which contains the OIDC client secret to be used in the Authentication Request: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest. The referenced Secret must contain an entry with the key “client-secret”. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret

CACertificateRefs references a list of secrets containing trusted CA certificates in PEM format used to verify the certificates of the OpenID Provider endpoints. The referenced secrets must contain an entry with the key “ca.crt”. Only one secret can be referenced currently. If not specified, the system CA bundle is used.

Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate NGINX Default: system CA bundle

URI defines the path for initiating session logout. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#logout_uri Example: /logout

PostLogoutURI defines the URI to redirect to after logout. Must match the configuration on the provider’s side. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#post_logout_uri Example: /after_logout, https://example.com/after_logout

FrontChannelLogoutURI defines the path for front-channel logout. The OpenID Provider should be configured to set “iss” and “sid” arguments. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#frontchannel_logout_uri Example: /frontchannel_logout

TokenHint adds the id_token_hint argument to the provider’s Logout Endpoint. Some OpenID Providers require this. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#logout_token_hint NGINX Default: false

CookieName sets the name of the session cookie. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#cookie_name NGINX Default: NGX_OIDC_SESSION

Timeout sets the session timeout duration. Directive: https://nginx.org/en/docs/http/ngx_http_oidc_module.html#session_timeout NGINX Default: 8h

HTTPSource configures direct bundle fetching from an HTTP/HTTPS URL. Required when type is HTTP; must not be set for other types.

NIMSource configures bundle fetching from NGINX Instance Manager. Required when type is NIM; must not be set for other types.

N1CSource configures bundle fetching from F5 NGINX One Console. Required when type is N1C; must not be set for other types.

Auth configures authentication credentials for fetching the bundle.

TLSSecretRef references a Secret containing a custom CA certificate (key: “ca.crt”) for verifying the bundle server’s TLS certificate.

Validation configures integrity verification for the downloaded bundle.

Polling configures automatic periodic re-fetching of the bundle.

Timeout is the maximum duration for a single bundle fetch attempt. Defaults to 30s when not set.

RetryAttempts is the maximum number of additional fetch attempts on transient failures (network errors, HTTP 5xx). Set to 0 to disable retries. Defaults to 3. Non-transient errors (HTTP 4xx, checksum mismatch) are never retried.

InsecureSkipVerify disables TLS certificate verification when fetching the bundle. Not recommended for production use.

"HTTP"

PolicySourceTypeHTTP fetches a compiled .tgz bundle directly from an HTTP/HTTPS URL.

"N1C"

PolicySourceTypeN1C fetches a compiled bundle from the F5 NGINX One Console security policies API. Requires managedSource.n1cNamespace in addition to managedSource.policyName. Authentication uses the APIToken scheme: the “token” key from the referenced Secret is sent as “Authorization: APIToken ”.

"NIM"

PolicySourceTypeNIM fetches a compiled bundle from the NGINX Instance Manager security policies API.

Disable enables or disables buffering of responses from the proxied server. If Disable is true, buffering is disabled. If Disable is false, or if Disable is not set, buffering is enabled. Directive: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering

BufferSize sets the size of the buffer used for reading the first part of the response received from the proxied server. This part usually contains a small response header. Directive: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size

Buffers sets the number and size of buffers used for reading a response from the proxied server, for a single connection. Directive: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers

BusyBuffersSize sets the total size of buffers that can be busy sending a response to the client, while the response is not yet fully read. Directive: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size

Size sets the size of each buffer.

Number sets the number of buffers.

Buffering configures the buffering of responses from the proxied server.

Timeout configures timeouts for the connection to the proxied server.

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

Connect sets the timeout for establishing a connection with the proxied server. Directive: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout

Read sets the timeout for reading a response from the proxied server. Directive: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout

Send sets the timeout for transmitting a request to the proxied server. Directive: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout

Local defines the local rate limit rules for this policy.

DryRun enables the dry run mode. In this mode, the rate limit is not actually applied, but the number of excessive requests is accounted as usual in the shared memory zone.

Directive: https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run

LogLevel sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Allowed values are info, notice, warn or error.

Directive: https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_log_level

RejectCode sets the status code to return in response to rejected requests. Must fall into the range 400-599.

Directive: https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_status

"error"

RateLimitLogLevelError is the error level rate limit logs.

"info"

RateLimitLogLevelInfo is the info level rate limit logs.

"notice"

RateLimitLogLevelNotice is the notice level rate limit logs.

"warn"

RateLimitLogLevelWarn is the warn level rate limit logs.

RateLimit defines the Rate Limit settings.

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

Support: Gateway, HTTPRoute, GRPCRoute

ZoneSize is the size of the shared memory zone.

Directive: https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone

Delay specifies a limit at which excessive requests become delayed. Default value is zero, which means all excessive requests are delayed.

Directive: https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req

NoDelay disables the delaying of excessive requests while requests are being limited. NoDelay cannot be true when Delay is also set.

Directive: https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req

Burst sets the maximum burst size of requests. If the requests rate exceeds the rate configured for a zone, their processing is delayed such that requests are processed at a defined rate. Excessive requests are delayed until their number exceeds the maximum burst size in which case the request is terminated with an error.

Directive: https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req

Rate represents the rate of requests permitted. The rate is specified in requests per second (r/s) or requests per minute (r/m).

Directive: https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone

Key represents the key to which the rate limit is applied. The key can contain text, variables, and their combination.

Directive: https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone

File defines the file destination configuration. Only valid when type is “file”.

Syslog defines the syslog destination configuration. Only valid when type is “syslog”.

Type identifies the type of security log destination.

"file"

SecurityLogDestinationTypeFile writes logs to a specified file path.

"stderr"

SecurityLogDestinationTypeStderr outputs logs to container stderr.

"syslog"

SecurityLogDestinationTypeSyslog sends logs to a syslog server via TCP.

Path is the file path where security logs will be written. Must be accessible to the waf-enforcer container.

Server is the syslog server address in the format “host:port”.

Context is the NGINX context to insert the snippet into.

Value is the NGINX configuration snippet.

"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.

"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.

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.

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

TargetRefs identifies API object(s) to apply the policy to.

Snippets is a list of snippets to be injected into the NGINX configuration.

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

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

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. The keepAlive directive for upstreams defaults to 16. To override this value, set the connections field. To disable the keepAlive directive, set connections to 0. Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive

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 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 defines the keep-alive timeout for upstreams. Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout

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 defines the keep-alive settings.

LoadBalancingMethod specifies the load balancing algorithm to be used for the upstream. If not specified, NGINX Gateway Fabric defaults to random two least_conn, which differs from the standard NGINX default round-robin.

HashMethodKey defines the key used for hash-based load balancing methods. This field is required when LoadBalancingMethod is set to hash or hash consistent.

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.

TargetRefs identifies API object(s) to apply the policy to. Objects must be in the same namespace as the policy. All targets must be of the same Kind (all Gateways OR all HTTPRoutes OR all GRPCRoutes). Support: Gateway, HTTPRoute, GRPCRoute.

Type identifies the source type for the policy bundle. HTTP fetches directly from a URL; NIM uses the NGINX Instance Manager bundles API; N1C uses the F5 NGINX One Console security policies API.

PolicySource holds all policy bundle fetch configuration.

SecurityLogs defines security logging configurations.

LogSource configures the log profile bundle source for this log entry. Exactly one of url or defaultProfile must be set.

Destination defines where security logs are sent.

Spec defines the desired state of the NginxProxy.

Spec defines the desired state of the ObservabilityPolicy.

Status defines the state of the ObservabilityPolicy.

"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.

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.

Target cpu utilization percentage of HPA.

Target memory utilization percentage of HPA.

Minimum number of replicas.

Metrics configures additional metrics options.

Maximum number of replicas.

Enable or disable Horizontal Pod Autoscaler.

Debug enables debugging for NGINX by using the nginx-debug binary.

Image is the NGINX image to use.

Resources describes the compute resource requirements.

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 defines the readiness probe for the NGINX container.

HostPorts are the list of ports to expose on the host.

VolumeMounts describe the mounting of Volumes within a container.

Timeout specifies the timeout for name resolution.

CacheTTL specifies how long to cache DNS responses.

DisableIPv6 disables IPv6 lookups. If not specified, or set to false, IPv6 lookups will be enabled.

Addresses specifies the list of DNS server addresses. Each address can be an IP address or hostname. Example: [{“type”: “IPAddress”, “value”: “8.8.8.8”}, {“type”: “Hostname”, “value”: “dns.google”}]

Type specifies the type of address.

Value specifies the address value. When Type is “IPAddress”, this must be a valid IPv4 or IPv6 address. When Type is “Hostname”, this must be a valid hostname.

"Hostname"

DNSResolverHostnameType specifies that the address is a hostname.

"IPAddress"

DNSResolverIPAddressType specifies that the address is an IP address.

Container defines container fields for the NGINX container.

WAFContainers defines container specifications for NGINX App Protect WAF v5 containers. These containers are only deployed when WAF is enabled in the NginxProxy spec.

Pod defines Pod-specific fields.

Patches are custom patches to apply to the NGINX DaemonSet.

Number of desired Pods.

Autoscaling defines the configuration for Horizontal Pod Autoscaling.

WAFContainers defines container specifications for NGINX App Protect WAF v5 containers. These containers are only deployed when WAF is enabled in the NginxProxy spec.

Pod defines Pod-specific fields.

Container defines container fields for the NGINX container.

Patches are custom patches to apply to the NGINX Deployment.

"DisableTracing"

DisableTracing disables the OpenTelemetry tracing feature.

"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).

Port to expose on the host.

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

"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.

Repository is the image path. Default is ghcr.io/nginx/nginx-gateway-fabric/nginx.

Tag is the image tag to use. Default matches the tag of the control plane.

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

Deployment is the configuration for the NGINX Deployment. This is the default deployment option.

DaemonSet is the configuration for the NGINX DaemonSet.

Service is the configuration for the NGINX Service.

Port where the Prometheus metrics are exposed.

Disable serving Prometheus metrics on the listen port.

Disable turns off access logging when set to true.

Format specifies the custom log format string. If not specified, NGINX default ‘combined’ format is used. For now only path /dev/stdout can be used. See https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format

Escape specifies how to escape characters in variables for access log. Possible values are: default, json, none. If not specified, ‘default’ escaping is used. See https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format

"default"

NginxAccessLogEscapeDefault specifies that characters ‘\“’, ‘\’, and other characters with values less than 32 or above 126 are escaped as ‘\xXX’.

"json"

NginxAccessLogEscapeJSON specifies that all characters not allowed in JSON strings are escaped. Characters ‘\“’ and ‘\’ are escaped as ‘\”’ and ‘\’, characters with values less than 32 are escaped as ‘\n’, ‘\r’, ‘\t’, ‘\b’, ‘\f’, or ‘\u00XX’.

"none"

NginxAccessLogEscapeNone disables escaping of characters.

"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.

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 defines the log level of the NGINX agent process. Changing this value results in a re-roll of the NGINX deployment.

AccessLog defines the access log settings, including format itself and disabling option. For now only path /dev/stdout can be used.

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

Type specifies the type of address.

Value specifies the address value.

"CIDR"

NginxPlusAllowCIDRAddressType specifies that the address is a CIDR block.

"IPAddress"

NginxPlusAllowIPAddressType specifies that the address is an IP address.

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

Telemetry specifies the OpenTelemetry configuration.

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

RewriteClientIP defines configuration for rewriting the client IP to the original client’s IP.

Logging defines logging related settings for NGINX.

NginxPlus specifies NGINX Plus additional settings.

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 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 contains the configuration for the NGINX Deployment and Service Kubernetes objects.

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

DNSResolver specifies the DNS resolver configuration for external name resolution. This enables support for routing to ExternalName Services.

ServerTokens configures whether NGINX emits its version in the “Server” response header and on error pages.

OSS NGINX accepts: - “on”: Shows nginx and version (e.g. “nginx/1.25.0”) - “off”: Shows nginx only (e.g. “nginx”) - “build”: Shows version and build name (e.g. “nginx/1.25.0 (build-name)”)

NGINX Plus additionally accepts: - “”: Suppress the “Server” response header entirely - : Set a custom header value and supports variables

See: https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens NGINX directive: https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens Default is “off”.

WAF configures NGINX App Protect WAF functionality.

Port is the NodePort to expose.

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

Tracing allows for enabling and configuring tracing.

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.

Type is the type of patch. Defaults to StrategicMerge.

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.

"JSONPatch"

PatchTypeJSONPatch uses JSON patch (RFC 6902).

"Merge"

PatchTypeMerge uses merge patch (RFC 7386).

"StrategicMerge"

PatchTypeStrategicMerge uses strategic merge patch.

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 is the pod’s scheduling constraints.

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 allow the scheduler to schedule Pods with matching taints.

Volumes represents named volumes in a pod that may be accessed by any container in the pod.

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.

"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.

Port is the port on which the readiness endpoint is exposed. If not specified, the default port is 8081.

Path is the path on which the readiness endpoint is exposed. If not specified, the default path is /readyz. Must start with a forward slash and contain only valid URL path characters.

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.

Expose toggles whether the endpoint should be exposed through the Gateway Service object. This allows an external LoadBalancer to perform healthchecks. Default is false.

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 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.¹⁄₃₂, 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 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.

Type specifies the type of address.

Value specifies the address value.

"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.

"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.

ServiceType describes ingress method for the Service.

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

LoadBalancerIP is a static IP address for the load balancer. Requires service type to be LoadBalancer.

LoadBalancerClass is the class of the load balancer implementation this Service belongs to. Requires service type to be LoadBalancer.

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

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 are custom patches to apply to the NGINX Service.

"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.

DisabledFeatures specifies OpenTelemetry features to be disabled.

Exporter specifies OpenTelemetry export parameters.

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 are custom key/value attributes that are added to each span.

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

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 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 is the address of OTLP/gRPC endpoint that will accept telemetry data. Format: alphanumeric hostname with optional http scheme and optional port.

"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).

"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.

Strategy defines if tracing is ratio-based or parent-based.

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 specifies how to propagate traceparent/tracestate headers. Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context

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 are custom key/value attributes that are added to each span.

Image is the container image to use for this WAF container.

Resources describes the compute resource requirements for this WAF container.

VolumeMounts describe the mounting of Volumes within the WAF container.

Enforcer defines the configuration for the WAF enforcer container. This container performs the actual WAF enforcement and policy application.

ConfigManager defines the configuration for the WAF configuration manager container. This container manages policy configuration and communication with the enforcer.

Enable enables NGINX App Protect WAF functionality. When enabled, NGINX Gateway Fabric will deploy additional WAF containers (waf-enforcer and waf-config-mgr) alongside the main NGINX container. Default is false.

DisableCookieSeed disables the app_protect_cookie_seed directive. By default, NGF sets this directive to a stable value derived from the Gateway UID, ensuring WAF session cookies are consistent across multiple NGINX replicas. Set this to true if you have pre-compiled the cookie seed into your WAF policy bundles via the compiler global settings, to avoid conflicting with the compiled-in value. Default is false.

BundleFailOpen controls the behavior when a WAF policy bundle (policy or log profile) has not yet been successfully fetched. When set to true, NGINX configuration is pushed and traffic is served without WAF protection until the bundle becomes available. When false (the default), the configuration push is withheld until the bundle is fetched, maintaining a fail-closed posture.