diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index 7270947e7..fbd75d681 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -361,7 +361,7 @@ spec: mode: ProxyProtocol trustedAddresses: - type: CIDR - value "76.89.90.11/24" + value: "76.89.90.11/24" EOF ``` diff --git a/content/ngf/how-to/monitoring/dashboard.md b/content/ngf/how-to/monitoring/dashboard.md index 94e411879..fd16d9911 100644 --- a/content/ngf/how-to/monitoring/dashboard.md +++ b/content/ngf/how-to/monitoring/dashboard.md @@ -30,3 +30,30 @@ The dashboard will look like this: {{< img src="/ngf/img/nginx-plus-dashboard.png" alt="">}} {{< note >}} The [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) used by the dashboard for metrics is also accessible using the `/api` path. {{< /note >}} + +### Configure dashboard access through NginxProxy + +To allow access to the NGINX Plus dashboard from different sources than the default `127.0.0.1`, we can use the NginxProxy resource +to allow access to other IP Addresses or CIDR blocks. + +The following NginxProxy configuration allows access to the NGINX Plus dashboard from the IP Addresses `192.0.2.8` and +`192.0.2.0` and the CIDR block `198.51.100.0/24`: + +```yaml +apiVersion: gateway.nginx.org/v1alpha1 +kind: NginxProxy +metadata: + name: ngf-proxy-config +spec: + nginxPlus: + allowedAddresses: + - type: IPAddress + value: 192.0.2.8 + - type: IPAddress + value: 192.0.2.0 + - type: CIDR + value: 198.51.100.0/24 +``` + +For more information on configuring the NginxProxy resource, visit our [data plane configuration]({{< ref "data-plane-configuration.md" >}}) document +which explains how to either configure an NginxProxy resource on installation, manually create an NginxProxy resource, or edit an existing NginxProxy resource. \ No newline at end of file diff --git a/content/ngf/reference/api.md b/content/ngf/reference/api.md index 11647ab7b..0f829e7ac 100644 --- a/content/ngf/reference/api.md +++ b/content/ngf/reference/api.md @@ -25,6 +25,8 @@ Resource Types:
+
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. ++ +
|
+
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.
Duration is a string value representing a duration in time. @@ -904,6 +1055,34 @@ Duration can be specified in milliseconds (ms), seconds (s), minutes (m), hours A value without a suffix is seconds. Examples: 120s, 50ms, 5m, 1h.
+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. + |
+
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. + |
+
string
alias)¶
(Appears on: -ObservabilityPolicy) +NginxProxySpec)
-
ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.
+NginxLogging defines logging related settings for NGINX.
-tracing + errorLevel - -Tracing + +NginxErrorLogLevel |
(Optional)
- Tracing allows for enabling and configuring tracing. +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 |
+(Appears on: +NginxProxySpec) +
++
NginxPlus specifies NGINX Plus additional settings. These will only be applied if NGINX Plus is being used.
+ +Field | +Description | +
---|---|
-targetRefs + allowedAddresses - -[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference + +[]NginxPlusAllowAddress |
- TargetRefs identifies the API object(s) to apply the policy to. -Objects must be in the same namespace as the policy. -Support: HTTPRoute, GRPCRoute. +(Optional) +AllowedAddresses specifies IPAddresses or CIDR blocks to the allow list for accessing the NGINX Plus API. |
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.
- --(Appears on: -SnippetsFilterSpec) +NginxPlus)
-
Snippet represents an NGINX configuration snippet.
+NginxPlusAllowAddress specifies the address type and value for an NginxPlus allow address.
-context + type - -NginxContext + +NginxPlusAllowAddressType |
- Context is the NGINX context to insert the snippet into. +Type specifies the type of address. |
- Value is the NGINX configuration snippet. +Value specifies the address value. |
string
alias)¶
+string
alias)¶
-
SnippetsFilterConditionReason is a reason for a SnippetsFilter condition type.
+(Appears on: +NginxPlusAllowAddress) + ++
NginxPlusAllowAddressType specifies the type of address.
Description | -|
---|---|
"Accepted" |
-SnippetsFilterConditionReasonAccepted is used with the Accepted condition type when -the condition is true. + |
"CIDR" |
+NginxPlusAllowCIDRAddressType specifies that the address is a CIDR block. |
-
"Invalid" |
-SnippetsFilterConditionReasonInvalid is used with the Accepted condition type when -SnippetsFilter is invalid. + |
"IPAddress" |
+NginxPlusAllowIPAddressType specifies that the address is an IP address. |
string
alias)¶
+-
SnippetsFilterConditionType is a type of condition associated with SnippetsFilter.
+(Appears on: +NginxProxy) + ++
NginxProxySpec defines the desired state of the NginxProxy.
Value | +Field | Description |
---|---|---|
"Accepted" |
-SnippetsFilterConditionTypeAccepted indicates that the SnippetsFilter is accepted. -Possible reasons for this condition to be True: -
Possible reasons for this condition to be False: -
| |
+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. + |
+|
+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 + + |
+
+ DisableHTTP2 defines if http2 should be disabled for all servers. +Default is false, meaning http2 will be enabled for all servers. + |
+
(Appears on: -SnippetsFilter) +ObservabilityPolicy)
-
SnippetsFilterSpec defines the desired state of the SnippetsFilter.
+ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.
-snippets + tracing - -[]Snippet + +Tracing |
- 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. +(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. |
(Appears on: -SnippetsFilter) +NginxProxySpec)
-
SnippetsFilterStatus defines the state of SnippetsFilter.
+RewriteClientIP specifies the configuration for rewriting the client’s IP address.
-controllers + mode - -[]ControllerStatus + +RewriteClientIPModeType |
- Controllers is a list of Gateway API controllers that processed the SnippetsFilter -and the status of the SnippetsFilter with respect to each controller. +(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. +TrustedAddresses only supports CIDR blocks: 192.33.21.1⁄24, fe80::1⁄64. +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. |
(Appears on: -Tracing, -Telemetry) +RewriteClientIP)
-
SpanAttribute is a key value pair to be added to a tracing span.
+RewriteClientIPAddress specifies the address type and value for a RewriteClientIP address.
-key + type -string + +RewriteClientIPAddressType + |
- Key is the key for a span attribute. -Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’ +Type specifies the type of address. |
- Value is the value for a span attribute. -Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’ +Value specifies the address value. |
string
alias)¶
+string
alias)¶
(Appears on: -Tracing) +RewriteClientIPAddress)
-
TraceContext specifies how to propagate traceparent/tracestate headers.
+RewriteClientIPAddressType specifies the type of address.
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. + |
"CIDR" |
+RewriteClientIPCIDRAddressType specifies that the address is a CIDR block. |
-
"inject" |
-TraceContextInject adds a new context to the request, overwriting existing headers, if any. + |
"Hostname" |
+RewriteClientIPHostnameAddressType specifies that the address is a Hostname. |
-
"propagate" |
-TraceContextPropagate updates the existing context (combines extract and inject). + |
"IPAddress" |
+RewriteClientIPIPAddressType specifies that the address is an IP address. |
string
alias)¶
+string
alias)¶
(Appears on: -Tracing) +RewriteClientIP)
-
TraceStrategy defines the tracing strategy.
+RewriteClientIPModeType defines how NGINX Gateway Fabric will determine the client’s original IP address.
Description | -|
---|---|
"parent" |
-TraceStrategyParent enables tracing and only records spans if the parent span was sampled. + |
"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. |
-
"ratio" |
-TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate. + |
"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. |
string
alias)¶
(Appears on: -ObservabilityPolicySpec) +ClientBody, +UpstreamSettingsPolicySpec)
-
Tracing allows for enabling and configuring OpenTelemetry tracing.
+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.
+ ++(Appears on: +SnippetsFilterSpec) +
++
Snippet represents an NGINX configuration snippet.
-strategy + context - -TraceStrategy + +NginxContext |
- Strategy defines if tracing is ratio-based or parent-based. +Context is the NGINX context to insert the snippet into. |
-ratio + value -int32 +string |
-(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. +Value is the NGINX configuration snippet. |
string
alias)¶
++
SnippetsFilterConditionReason is a reason for a SnippetsFilter condition type.
+ +
-context - - -TraceContext - - + | Value | +Description | +
---|---|---|
"Accepted" |
+SnippetsFilterConditionReasonAccepted is used with the Accepted condition type when +the condition is true. |
-
-(Optional)
- Context specifies how to propagate traceparent/tracestate headers. -Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context + |
"Invalid" |
+SnippetsFilterConditionReasonInvalid is used with the Accepted condition type when +SnippetsFilter is invalid. |
-
string
alias)¶
++
SnippetsFilterConditionType is a type of condition associated with SnippetsFilter.
+ +
-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 + | Value | +Description | +
---|---|---|---|
"Accepted" |
+SnippetsFilterConditionTypeAccepted indicates that the SnippetsFilter is accepted. +Possible reasons for this condition to be True: +
Possible reasons for this condition to be False: +
|
+
+(Appears on: +SnippetsFilter) +
++
SnippetsFilterSpec defines the desired state of the SnippetsFilter.
+ +Field | +Description |
---|---|
-spanAttributes + snippets - -[]SpanAttribute + +[]Snippet |
-(Optional)
- SpanAttributes are custom key/value attributes that are added to each span. +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. |
(Appears on: -UpstreamSettingsPolicySpec) +SnippetsFilter)
-
UpstreamKeepAlive defines the keep-alive settings for upstreams.
+SnippetsFilterStatus defines the state of SnippetsFilter.
-connections + controllers -int32 + +[]ControllerStatus + |
-(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 +Controllers is a list of Gateway API controllers that processed the SnippetsFilter +and the status of the SnippetsFilter with respect to each controller. |
+(Appears on: +Telemetry, +Tracing, +Tracing) +
++
SpanAttribute is a key value pair to be added to a tracing span.
+ +
-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 - |
+Field | +Description |
---|---|---|---|
-time + key - -Duration - +string |
-(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 +Key is the key for a span attribute. +Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’ |
||
-timeout + value - -Duration - +string |
-(Optional)
- Timeout defines the keep-alive timeout for upstreams. -Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout +Value is the value for a span attribute. +Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’ |
(Appears on: -UpstreamSettingsPolicy) +NginxProxySpec)
-
UpstreamSettingsPolicySpec defines the desired state of the UpstreamSettingsPolicy.
+Telemetry specifies the OpenTelemetry configuration.
(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 +Exporter specifies OpenTelemetry export parameters. |
|
-keepAlive + serviceName - -UpstreamKeepAlive - +string |
(Optional)
- KeepAlive defines the keep-alive settings. +ServiceName is the “service.name” attribute of the OpenTelemetry resource.
+Default is ‘ngf: |
-targetRefs + spanAttributes - -[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference + +[]SpanAttribute |
- TargetRefs identifies API object(s) to apply the policy to. -Objects must be in the same namespace as the policy. -Support: Service +(Optional) +SpanAttributes are custom key/value attributes that are added to each span. |
-
Package v1alpha2 contains API Schema definitions for the -gateway.nginx.org API group.
- -Resource Types: --
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.
+(Appears on: +Telemetry) + ++
TelemetryExporter specifies OpenTelemetry export parameters.
-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. -- -
Endpoint is the address of OTLP/gRPC endpoint that will accept telemetry data. +Format: alphanumeric hostname with optional http scheme and optional port. |
string
alias)¶
(Appears on: -RewriteClientIP) +Tracing)
-
Address is a struct that specifies address type and value.
+TraceContext specifies how to propagate traceparent/tracestate headers.
Field | +Value | Description |
---|---|---|
-type - - -AddressType - - + | ||
"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. |
-
- Type specifies the type of address. + |
"ignore" |
+TraceContextIgnore skips context headers processing. |
-|
-value - -string - + | ||
"inject" |
+TraceContextInject adds a new context to the request, overwriting existing headers, if any. |
-
- Value specifies the address value. + |
"propagate" |
+TraceContextPropagate updates the existing context (combines extract and inject). |
-
string
alias)¶
+string
alias)¶
(Appears on: -Address) +Tracing)
-
AddressType specifies the type of address.
+TraceStrategy defines the tracing strategy.
Description | -|
---|---|
"CIDR" |
-CIDRAddressType specifies that the address is a CIDR block. - |
-
"Hostname" |
-HostnameAddressType specifies that the address is a Hostname. + |
"parent" |
+TraceStrategyParent enables tracing and only records spans if the parent span was sampled. |
-
"IPAddress" |
-IPAddressType specifies that the address is an IP address. + |
"ratio" |
+TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate. |
string
alias)¶
+(Appears on: -Telemetry) +ObservabilityPolicySpec)
-
DisableTelemetryFeature is a telemetry feature that can be disabled.
+Tracing allows for enabling and configuring OpenTelemetry tracing.
Value | +Field | Description |
---|---|---|
"DisableTracing" |
-DisableTracing disables the OpenTelemetry tracing feature. + | |
+strategy + + +TraceStrategy + + |
-
string
alias)¶
--(Appears on: -NginxProxySpec) -
--
IPFamilyType specifies the IP family to be used by NGINX.
- -
+ Strategy defines if tracing is ratio-based or parent-based. + |
+
|||
Value | -Description | +
+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. + |
---|---|---|---|
"dual" |
-Dual specifies that NGINX will use both IPv4 and IPv6. + | ||
+context + + +TraceContext + + |
-|||
"ipv4" |
-IPv4 specifies that NGINX will use only IPv4. + |
+(Optional)
+ Context specifies how to propagate traceparent/tracestate headers. +Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context |
-|
"ipv6" |
-IPv6 specifies that NGINX will use only IPv6. + | ||
+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. + |
+
string
alias)¶
+(Appears on: -NginxLogging) +UpstreamSettingsPolicySpec)
-
NginxErrorLogLevel type defines the log level of error logs for NGINX.
+UpstreamKeepAlive defines the keep-alive settings for upstreams.
Value | +Field | Description |
---|---|---|
"alert" |
-NginxLogLevelAlert is the alert level for NGINX error logs. + | |
+connections + +int32 + |
-||
"crit" |
-NginxLogLevelCrit is the crit level for NGINX error logs. + |
+(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 |
-
"debug" |
-NginxLogLevelDebug is the debug level for NGINX error logs. + | |
+requests + +int32 + |
-||
"emerg" |
-NginxLogLevelEmerg is the emerg level for NGINX error logs. + |
+(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 |
-
"error" |
-NginxLogLevelError is the error level for NGINX error logs. + | |
+time + + +Duration + + |
-||
"info" |
-NginxLogLevelInfo is the info level for NGINX error logs. + |
+(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 |
-
"notice" |
-NginxLogLevelNotice is the notice level for NGINX error logs. + | |
+timeout + + +Duration + + |
-||
"warn" |
-NginxLogLevelWarn is the warn level for NGINX error logs. + |
+(Optional)
+ Timeout defines the keep-alive timeout for upstreams. +Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout |
-
(Appears on: -NginxProxySpec) +UpstreamSettingsPolicy)
-
NginxLogging defines logging related settings for NGINX.
+UpstreamSettingsPolicySpec defines the desired state of the UpstreamSettingsPolicy.
-errorLevel + zoneSize - -NginxErrorLogLevel + +Size |
(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 +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 |
-(Appears on: -NginxProxy) +
Package v1alpha2 contains API Schema definitions for the +gateway.nginx.org API group.
+Resource Types: + +-
NginxProxySpec defines the desired state of the NginxProxy.
+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.
-(Optional)
- IPFamily specifies the IP family to be used by the NGINX. -Default is “dual”, meaning the server will use both IPv4 and IPv6. +Refer to the Kubernetes API documentation for the fields of the +metadata field.
|
|
-telemetry + spec - -Telemetry + +ObservabilityPolicySpec |
-(Optional)
- Telemetry specifies the OpenTelemetry configuration. - |
-
-rewriteClientIP + tracing - -RewriteClientIP + +Tracing |
(Optional)
- RewriteClientIP defines configuration for rewriting the client IP to the original client’s IP. +Tracing allows for enabling and configuring tracing. |
-logging + targetRefs - -NginxLogging + +[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference |
-(Optional)
- Logging defines logging related settings for NGINX. +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 |
+
disableHTTP2
status
DisableHTTP2 defines if http2 should be disabled for all servers. -If not specified, or set to false, http2 will be enabled for all servers.
+Status defines the state of the ObservabilityPolicy.
(Appears on: -NginxProxySpec) +ObservabilityPolicy)
-
RewriteClientIP specifies the configuration for rewriting the client’s IP address.
+ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.
-mode + tracing - -RewriteClientIPModeType + +Tracing |
(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 +Tracing allows for enabling and configuring tracing. |
-trustedAddresses + targetRefs - -[]Address + +[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference |
-(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. +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 |
string
alias)¶
+string
alias)¶
(Appears on: -RewriteClientIP) +Tracing)
-
RewriteClientIPModeType defines how NGINX Gateway Fabric will determine the client’s original IP address.
+TraceContext specifies how to propagate traceparent/tracestate headers.
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. + |
"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. |
-
"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. + |
"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). |
string
alias)¶
(Appears on: -NginxProxySpec) +Tracing)
-
Telemetry specifies the OpenTelemetry configuration.
+TraceStrategy defines the tracing strategy.
Field | +Value | 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: |
-|
-spanAttributes - - -[]SpanAttribute - - + | ||
"parent" |
+TraceStrategyParent enables tracing and only records spans if the parent span was sampled. |
-
-(Optional)
- SpanAttributes are custom key/value attributes that are added to each span. + |
"ratio" |
+TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate. |
-
(Appears on: -Telemetry) +ObservabilityPolicySpec)
-
TelemetryExporter specifies OpenTelemetry export parameters.
+Tracing allows for enabling and configuring OpenTelemetry tracing.
-interval + strategy - -Duration + +TraceStrategy |
-(Optional)
- Interval is the maximum interval between two exports. -Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_exporter +Strategy defines if tracing is ratio-based or parent-based. |
-batchSize + ratio 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 +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. |
-batchCount + context -int32 + +TraceContext + |
(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 +Context specifies how to propagate traceparent/tracestate headers. +Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context |
-endpoint + spanName 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. +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. |