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:
  • NginxGateway
  • +NginxProxy +
  • ObservabilityPolicy
  • SnippetsFilter @@ -243,6 +245,154 @@ NginxGatewayStatus +

    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.

    +

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

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

    +
    +

    ObservabilityPolicy

    @@ -549,6 +699,7 @@ UpstreamKeepAlive

    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.

    @@ -895,8 +1046,8 @@ longer necessary.

    ClientBody, ClientKeepAlive, ClientKeepAliveTimeout, -UpstreamKeepAlive, -TelemetryExporter) +TelemetryExporter, +UpstreamKeepAlive)

    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.

    +

    IPFamilyType +(string alias)

    +

    +

    +(Appears on: +NginxProxySpec) +

    +

    +

    IPFamilyType specifies the IP family to be used by NGINX.

    +

    + + + + + + + + + + + + + + +
    ValueDescription

    "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

    @@ -972,6 +1151,49 @@ ControllerLogLevel +

    NginxErrorLogLevel +(string alias)

    +

    +

    +(Appears on: +NginxLogging) +

    +

    +

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

    +

    + + + + + + + + + + + + + + + + + + + + + + + + +
    ValueDescription

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

    +

    NginxGatewayConditionReason (string alias)

    @@ -1081,15 +1303,15 @@ Logging -

    ObservabilityPolicySpec - +

    NginxLogging +

    (Appears on: -ObservabilityPolicy) +NginxProxySpec)

    -

    ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.

    +

    NginxLogging defines logging related settings for NGINX.

    @@ -1101,57 +1323,66 @@ Logging + +
    -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

    +

    NginxPlus + +

    +

    +(Appears on: +NginxProxySpec) +

    +

    +

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

    +

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

    -

    Size -(string alias)

    +

    NginxPlusAllowAddress +

    (Appears on: -ClientBody, -UpstreamSettingsPolicySpec) -

    -

    -

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

    -

    -

    Snippet - -

    -

    -(Appears on: -SnippetsFilterSpec) +NginxPlus)

    -

    Snippet represents an NGINX configuration snippet.

    +

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

    @@ -1163,15 +1394,15 @@ Examples: 1024, 8k, 1m.

    @@ -1182,16 +1413,20 @@ string
    -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.

    -

    SnippetsFilterConditionReason -(string alias)

    +

    NginxPlusAllowAddressType +(string alias)

    -

    SnippetsFilterConditionReason is a reason for a SnippetsFilter condition type.

    +(Appears on: +NginxPlusAllowAddress) +

    +

    +

    NginxPlusAllowAddressType specifies the type of address.

    @@ -1200,51 +1435,126 @@ string - - + - - +
    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.

    -

    SnippetsFilterConditionType -(string alias)

    +

    NginxProxySpec +

    -

    SnippetsFilterConditionType is a type of condition associated with SnippetsFilter.

    +(Appears on: +NginxProxy) +

    +

    +

    NginxProxySpec defines the desired state of the NginxProxy.

    - + - - + + - + + + + + + + + + + + + + + + + + + + + + + +
    ValueField Description

    "Accepted"

    SnippetsFilterConditionTypeAccepted indicates that the SnippetsFilter is accepted.

    -

    Possible reasons for this condition to be True:

    -
      -
    • Accepted
    • -
    -

    Possible reasons for this condition to be False:

    -
      -
    • Invalid.
    • -
    +
    +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.

    +
    -

    SnippetsFilterSpec - +

    ObservabilityPolicySpec +

    (Appears on: -SnippetsFilter) +ObservabilityPolicy)

    -

    SnippetsFilterSpec defines the desired state of the SnippetsFilter.

    +

    ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.

    @@ -1256,30 +1566,44 @@ SnippetsFilter is invalid.

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

    -

    SnippetsFilterStatus - +

    RewriteClientIP +

    (Appears on: -SnippetsFilter) +NginxProxySpec)

    -

    SnippetsFilterStatus defines the state of SnippetsFilter.

    +

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

    @@ -1291,30 +1615,75 @@ Allowed contexts: main, http, http.server, http.server.location.

    + + + + + + + +
    -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.132, 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.124, fe80::164. +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.

    -

    SpanAttribute - +

    RewriteClientIPAddress +

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

    @@ -1326,14 +1695,15 @@ and the status of the SnippetsFilter with respect to each controller.

    @@ -1344,21 +1714,20 @@ string
    -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.

    -

    TraceContext -(string alias)

    +

    RewriteClientIPAddressType +(string alias)

    (Appears on: -Tracing) +RewriteClientIPAddress)

    -

    TraceContext specifies how to propagate traceparent/tracestate headers.

    +

    RewriteClientIPAddressType specifies the type of address.

    @@ -1367,30 +1736,26 @@ Format: must have all ‘“’ escaped and must not contain any &ls - - - - + - - + - - +
    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.

    -

    TraceStrategy -(string alias)

    +

    RewriteClientIPModeType +(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.

    @@ -1399,23 +1764,41 @@ of a trace and the parent span are inherited from the incoming request.

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

    -

    Tracing - +

    Size +(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.

    +

    +

    Snippet + +

    +

    +(Appears on: +SnippetsFilterSpec) +

    +

    +

    Snippet represents an NGINX configuration snippet.

    @@ -1427,86 +1810,123 @@ of a trace and the parent span are inherited from the incoming request.

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

    +

    SnippetsFilterConditionReason +(string alias)

    +

    +

    +

    SnippetsFilterConditionReason is a reason for a SnippetsFilter condition type.

    +

    + + - + + + + + - + - + +
    -context
    - - -TraceContext - - +
    ValueDescription

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

    +

    SnippetsFilterConditionType +(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

    +
    ValueDescription

    "Accepted"

    SnippetsFilterConditionTypeAccepted indicates that the SnippetsFilter is accepted.

    +

    Possible reasons for this condition to be True:

    +
      +
    • Accepted
    • +
    +

    Possible reasons for this condition to be False:

    +
      +
    • Invalid.
    • +
    +

    SnippetsFilterSpec + +

    +

    +(Appears on: +SnippetsFilter) +

    +

    +

    SnippetsFilterSpec defines the desired state of the SnippetsFilter.

    +

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

    -

    UpstreamKeepAlive - +

    SnippetsFilterStatus +

    (Appears on: -UpstreamSettingsPolicySpec) +SnippetsFilter)

    -

    UpstreamKeepAlive defines the keep-alive settings for upstreams.

    +

    SnippetsFilterStatus defines the state of SnippetsFilter.

    @@ -1518,75 +1938,75 @@ Examples of invalid names: some-$value, quoted-“value”-name, unescap + +
    -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.

    +

    SpanAttribute + +

    +

    +(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

    -
    FieldDescription
    -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 ‘\’

    -

    UpstreamSettingsPolicySpec - +

    Telemetry +

    (Appears on: -UpstreamSettingsPolicy) +NginxProxySpec)

    -

    UpstreamSettingsPolicySpec defines the desired state of the UpstreamSettingsPolicy.

    +

    Telemetry specifies the OpenTelemetry configuration.

    @@ -1598,73 +2018,57 @@ Directive: -Size + +TelemetryExporter
    (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::’. If a value is provided by the user, +then the default becomes a prefix to that value.

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

    -
    -

    gateway.nginx.org/v1alpha2

    -

    -

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

    -

    -Resource Types: - -

    NginxProxy - +

    TelemetryExporter +

    -

    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.

    @@ -1676,177 +2080,100 @@ set on the GatewayClass NginxProxy.

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

    Spec defines the desired state of the NginxProxy.

    -
    -
    - - - - - - - - -
    -ipFamily
    - - -IPFamilyType - - -
    -(Optional) -

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

    -
    -telemetry
    +interval
    - -Telemetry + +Duration
    (Optional) -

    Telemetry specifies the OpenTelemetry configuration.

    +

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

    -rewriteClientIP
    +batchSize
    - -RewriteClientIP - +int32
    (Optional) -

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

    +

    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

    -logging
    +batchCount
    - -NginxLogging - +int32
    (Optional) -

    Logging defines logging related settings for NGINX.

    +

    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

    -disableHTTP2
    +endpoint
    -bool +string
    -(Optional) -

    DisableHTTP2 defines if http2 should be disabled for all servers. -If not specified, or set to false, http2 will be enabled for all servers.

    -
    +

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

    -

    Address - +

    TraceContext +(string alias)

    (Appears on: -RewriteClientIP) +Tracing)

    -

    Address is a struct that specifies address type and value.

    +

    TraceContext specifies how to propagate traceparent/tracestate headers.

    - + - - - + - + - - - + - + - - +
    FieldValue 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).

    -

    AddressType -(string alias)

    +

    TraceStrategy +(string alias)

    (Appears on: -Address) +Tracing)

    -

    AddressType specifies the type of address.

    +

    TraceStrategy defines the tracing strategy.

    @@ -1855,119 +2182,194 @@ string - - - - + - - +
    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.

    -

    DisableTelemetryFeature -(string alias)

    +

    Tracing +

    (Appears on: -Telemetry) +ObservabilityPolicySpec)

    -

    DisableTelemetryFeature is a telemetry feature that can be disabled.

    +

    Tracing allows for enabling and configuring OpenTelemetry tracing.

    - + - - + + - -
    ValueField Description

    "DisableTracing"

    DisableTracing disables the OpenTelemetry tracing feature.

    +
    +strategy
    + + +TraceStrategy + +
    -

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

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

    +
    -

    NginxErrorLogLevel -(string alias)

    +

    UpstreamKeepAlive +

    (Appears on: -NginxLogging) +UpstreamSettingsPolicySpec)

    -

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

    +

    UpstreamKeepAlive defines the keep-alive settings for upstreams.

    - + - - + + - - - - + + - - - - + + - - - - + + - - - + +
    ValueField 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

    -

    NginxLogging - +

    UpstreamSettingsPolicySpec +

    (Appears on: -NginxProxySpec) +UpstreamSettingsPolicy)

    -

    NginxLogging defines logging related settings for NGINX.

    +

    UpstreamSettingsPolicySpec defines the desired state of the UpstreamSettingsPolicy.

    @@ -1979,32 +2381,71 @@ string + + + + + + + +
    -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 name field must be unique for all targetRef entries in the UpstreamSettingsPolicy.

    -

    NginxProxySpec - -

    +
    +

    gateway.nginx.org/v1alpha2

    -(Appears on: -NginxProxy) +

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

    +Resource Types: + +

    ObservabilityPolicy + +

    -

    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.

    @@ -2016,85 +2457,107 @@ crit, alert, and emerg messages to be logged. -IPFamilyType + +Kubernetes meta/v1.ObjectMeta - +

    Spec defines the desired state of the ObservabilityPolicy.

    +
    +
    +
    -(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 kind and name must +be unique across all targetRef entries in the ObservabilityPolicy.

    +
    -disableHTTP2
    +status
    -bool + +sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus + -(Optional) -

    DisableHTTP2 defines if http2 should be disabled for all servers. -If not specified, or set to false, http2 will be enabled for all servers.

    +

    Status defines the state of the ObservabilityPolicy.

    -

    RewriteClientIP - +

    ObservabilityPolicySpec +

    (Appears on: -NginxProxySpec) +ObservabilityPolicy)

    -

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

    +

    ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.

    @@ -2106,74 +2569,46 @@ If not specified, or set to false, http2 will be enabled for all servers.

    - - - -
    -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.132, 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 kind and name must +be unique across all targetRef entries in the ObservabilityPolicy.

    -

    RewriteClientIPModeType -(string alias)

    +

    TraceContext +(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.

    @@ -2182,104 +2617,55 @@ This field is required if mode is set.

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

    -

    Telemetry - +

    TraceStrategy +(string alias)

    (Appears on: -NginxProxySpec) +Tracing)

    -

    Telemetry specifies the OpenTelemetry configuration.

    +

    TraceStrategy defines the tracing strategy.

    - + - - - - - - - - - - - - - - - + - + - - +
    FieldValue Description
    -disabledFeatures
    - - -[]DisableTelemetryFeature - - -
    -(Optional) -

    DisabledFeatures specifies OpenTelemetry features to be disabled.

    -
    -exporter
    - - -TelemetryExporter - - -
    -(Optional) -

    Exporter specifies OpenTelemetry export parameters.

    -
    -serviceName
    - -string - -
    -(Optional) -

    ServiceName is the “service.name” attribute of the OpenTelemetry resource. -Default is ‘ngf::’. If a value is provided by the user, -then the default becomes a prefix to that value.

    -
    -spanAttributes
    - - -[]SpanAttribute - - +

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

    -

    TelemetryExporter - +

    Tracing +

    (Appears on: -Telemetry) +ObservabilityPolicySpec)

    -

    TelemetryExporter specifies OpenTelemetry export parameters.

    +

    Tracing allows for enabling and configuring OpenTelemetry tracing.

    @@ -2291,56 +2677,73 @@ then the default becomes a prefix to that value.

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