API reference
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.
|
||||||
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.
|
||
status NginxGatewayStatus |
NginxGatewayStatus defines the state of the NginxGateway. |
NginxProxy ¶
NginxProxy is a configuration object that is attached to a GatewayClass parametersRef. It provides a way to configure global settings for all Gateways defined from the GatewayClass.
Field | Description | ||||||
---|---|---|---|---|---|---|---|
apiVersion string |
gateway.nginx.org/v1alpha1
|
||||||
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.
|
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.
|
||||
status sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus |
Status defines the state of the ObservabilityPolicy. |
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. |
Duration
(string
alias)¶
(Appears on: ClientBody, ClientKeepAlive, ClientKeepAliveTimeout, TelemetryExporter)
Duration is a string value representing a duration in time. Duration can be specified in milliseconds (ms) or seconds (s) A value without a suffix is seconds. Examples: 120s, 50ms.
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. |
Logging ¶
(Appears on: NginxGatewaySpec)
Logging defines logging related settings for the control plane.
Field | Description |
---|---|
level ControllerLogLevel |
(Optional)
Level defines the logging level. |
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) |
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. |
disableHTTP2 bool |
(Optional)
DisableHTTP2 defines if http2 should be disabled for all servers. Default is false, meaning http2 will be enabled for all servers. |
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)
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.
SpanAttribute ¶
(Appears on: 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 ‘\’ |
Telemetry ¶
(Appears on: NginxProxySpec)
Telemetry specifies the OpenTelemetry configuration.
Field | Description |
---|---|
exporter TelemetryExporter |
(Optional)
Exporter specifies OpenTelemetry export parameters. |
serviceName string |
(Optional)
ServiceName is the “service.name” attribute of the OpenTelemetry resource.
Default is ‘ngf: |
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 |
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