Data plane configuration

Learn how to dynamically update the NGINX Gateway Fabric global data plane configuration.

Overview

NGINX Gateway Fabric can dynamically update the global data plane configuration without restarting. The data plane configuration contains configuration for NGINX that is not available using the standard Gateway API resources. This includes options such as configuring an OpenTelemetry collector, disabling HTTP/2, changing the IP family, and setting the NGINX error log level.

It also contains options for updating the NGINX Deployment and Service config, either through native fields or patches.

The data plane configuration is stored in the NginxProxy custom resource, which is a namespace-scoped resource that can be attached to a GatewayClass or Gateway. When attached to a GatewayClass, the fields in the NginxProxy affect all Gateways that belong to the GatewayClass. When attached to a Gateway, the fields in the NginxProxy only affect the Gateway. If a GatewayClass and its Gateway both specify an NginxProxy, the GatewayClass NginxProxy provides defaults that can be overridden by the Gateway NginxProxy. See the Merging Semantics section for more detail.

For a full list of configuration options that can be set, see the NginxProxy spec in the API reference.

Merging Semantics

NginxProxy resources are merged when a GatewayClass and a Gateway reference different NginxProxy resources.

For fields that are bools, integers, and strings:

  • If a field on the Gateway’s NginxProxy is unspecified (nil), the Gateway inherits the value of the field in the GatewayClass’s NginxProxy.
  • If a field on the Gateway’s NginxProxy is specified, its value overrides the value of the field in the GatewayClass’s NginxProxy.

For array fields:

  • If the array on the Gateway’s NginxProxy is unspecified (nil), the Gateway inherits the entire array in the GatewayClass’s NginxProxy.
  • If the array on the Gateway’s NginxProxy is empty, it overrides the entire array in the GatewayClass’s NginxProxy, effectively unsetting the field.
  • If the array on the Gateway’s NginxProxy is specified and not empty, it overrides the entire array in the GatewayClass’s NginxProxy.

Merging Examples

This section contains examples of how NginxProxy resources are merged when they are attached to both a Gateway and its GatewayClass.

Disable HTTP/2 for a Gateway

A GatewayClass references the following NginxProxy which explicitly allows HTTP/2 traffic and sets the IPFamily to ipv4:

yaml
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: gateway-class-enable-http2
  namespace: default
spec:
  ipFamily: "ipv4"
  disableHTTP: false

To disable HTTP/2 traffic for a particular Gateway, reference the following NginxProxy in the Gateway’s spec:

yaml
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: gateway-disable-http
  namespace: default
spec:
  disableHTTP: true

These NginxProxy resources are merged and the following settings are applied to the Gateway:

yaml
ipFamily: "ipv4"
disableHTTP: true

Change Telemetry configuration for a Gateway

A GatewayClass references the following NginxProxy which configures telemetry:

yaml
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: gateway-class-telemetry
  namespace: default
spec:
  telemetry:
    exporter:
      endpoint: "my.telemetry.collector:9000"
      interval: "60s"
      batchSize: 20
    serviceName: "my-company"
    spanAttributes:
    - key: "company-key"
      value: "company-value"

To change the telemetry configuration for a particular Gateway, reference the following NginxProxy in the Gateway’s spec:

yaml
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: gateway-telemetry-service-name
  namespace: default
spec:
  telemetry:
    exporter:
      batchSize: 50
      batchCount: 5
    serviceName: "my-app"
    spanAttributes:
    - key: "app-key"
      value: "app-value"

These NginxProxy resources are merged and the following settings are applied to the Gateway:

yaml
  telemetry:
    exporter:
      endpoint: "my.telemetry.collector:9000"
      interval: "60s"
      batchSize: 50
      batchCount: 5
    serviceName: "my-app"
    spanAttributes:
    - key: "app-key"
      value: "app-value"

Disable Tracing for a Gateway

A GatewayClass references the following NginxProxy which configures telemetry:

yaml
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: gateway-class-telemetry
  namespace: default
spec:
  telemetry:
    exporter:
      endpoint: "my.telemetry.collector:9000"
      interval: "60s"
    serviceName: "my-company"

To disable tracing for a particular Gateway, reference the following NginxProxy in the Gateway’s spec:

yaml
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: gateway-disable-tracing
  namespace: default
spec:
  telemetry:
    disabledFeatures:
    - DisableTracing

These NginxProxy resources are merged and the following settings are applied to the Gateway:

yaml
telemetry:
    exporter:
      endpoint: "my.telemetry.collector:9000"
      interval: "60s"
    serviceName: "my-app"
    disabledFeatures:
    - DisableTracing

Configuring the GatewayClass NginxProxy on install

By default, an NginxProxy resource is created in the same namespace where NGINX Gateway Fabric is installed, attached to the GatewayClass. You can set configuration options in the nginx Helm value section, and the resource will be created and attached using the set values. You can also manually create and attach specific NginxProxy resources to target different Gateways.

When installed using the Helm chart, the NginxProxy resource is named <RELEASE_NAME>-proxy-config and is created in the release Namespace.

For a full list of configuration options that can be set, see the NginxProxy spec in the API reference.

Some global configuration also requires an associated policy to fully enable a feature (such as tracing, for example).

Manually Creating NginxProxies

The following command creates a basic NginxProxy configuration in the default namespace that sets the IP family to ipv4 instead of the default value of dual:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
  namespace: default
spec:
  ipFamily: ipv4
EOF

For a full list of configuration options that can be set, see the NginxProxy spec in the API reference.

Attaching NginxProxy to Gateway

To attach the ngf-proxy-config NginxProxy to a Gateway:

kubectl edit gateway <GATEWAY_NAME>

Replace <GATEWAY_NAME> with the name of your Gateway.

This will open your default editor, allowing you to add the following to the spec:

yaml
infrastructure:
    parametersRef:
        group: gateway.nginx.org
        kind: NginxProxy
        name: ngf-proxy-config
The NginxProxy resource must reside in the same namespace as the Gateway it is attached to.

After updating, you can check the status of the Gateway to see if the configuration is valid:

kubectl describe gateway <GATEWAY_NAME>
text
...
Status:
  Conditions:
     ...
    Message:               parametersRef resource is resolved
    Observed Generation:   1
    Reason:                ResolvedRefs
    Status:                True
    Type:                  ResolvedRefs

If everything is valid, the ResolvedRefs condition should be True. Otherwise, you will see an InvalidParameters condition in the status.

Configure the data plane log level

You can use the NginxProxy resource to dynamically configure the log level.

The following command creates a basic NginxProxy configuration that sets the log level to warn instead of the default value of info:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  logging:
    errorLevel: warn
EOF

To view the full list of supported log levels, see the NginxProxy spec in the API reference.

For debug logging to work, NGINX needs to be built with --with-debug or "in debug mode". NGINX Gateway Fabric can easily be run with NGINX in debug mode upon startup through the addition of a few arguments. JSON error log format is not supported in debug mode.

Configure the data plane log format

NGINX records client requests immediately after each request is processed. You can use the NginxProxy resource to dynamically configure the access log format.

The following command creates a basic NginxProxy that defines a custom log format $remote_addr - [$time_local] "$request" $status $body_bytes_sent:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  logging:
    accessLog:
      format: $remote_addr - [$time_local] "$request" $status $body_bytes_sent
EOF

You can disable access logging entirely with the following configuration:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  logging:
    accessLog:
      disable: true
EOF

NGINX Gateway Fabric supports errorLog in JSON format for NGINX Plus users. When errorLogFormat is set to json and no custom access log format is defined, the access log also defaults to JSON format.

By default, NGINX Gateway Fabric writes access logs to /dev/stdout. To send them to a file or a syslog server instead, set destination under spec.logging.accessLog in the NginxProxy resource.

The following command creates an NginxProxy that writes access logs to a file, paired with a custom log format:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  logging:
    accessLog:
      format: $remote_addr - [$time_local] "$request" $status $body_bytes_sent
      destination:
        type: file
        file:
          path: /var/log/nginx/access.log
EOF

The following command creates an NginxProxy that sends access logs to a syslog server, paired with a custom log format. Give the server as a host:port value:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  logging:
    accessLog:
      format: $remote_addr - [$time_local] "$request" $status $body_bytes_sent
      destination:
        type: syslog
        syslog:
          server: syslog-svc.default.svc.cluster.local:514
EOF
A destination takes effect only when an access log format is also defined. Set accessLog.format to a custom format, or set errorLogFormat to json to use the built-in JSON format.

For a full list of configuration options that can be set, see the NginxProxy spec in the API reference.

Run NGINX Gateway Fabric with NGINX in debug mode

To run NGINX Gateway Fabric with NGINX in debug mode, during installation, follow these additional steps:

  • Helm: Set nginx.debug to true.
  • Manifests: Set spec.kubernetes.deployment.container.debug field in the NginxProxy resource to true.

To change NGINX mode after deploying NGINX Gateway Fabric, use the NginxProxy spec.kubernetes.deployment.container.debug field.

The following command creates a basic NginxProxy configuration that sets both the NGINX mode and log level to debug.

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  logging:
    errorLevel: debug
  kubernetes:
    deployment:
      container:
        debug: true
EOF
When modifying any deployment field in the NginxProxy resource, any corresponding NGINX instances will be restarted.

Configure PROXY protocol and RewriteClientIP settings

When a request is passed through multiple proxies or load balancers, the client IP is set to the IP address of the server that last handled the request. To preserve the original client IP address, you can configure RewriteClientIP settings in the NginxProxy resource. RewriteClientIP has the fields: mode, trustedAddresses and setIPRecursively.

Mode determines how the original client IP is passed through multiple proxies and the way the load balancer is set to receive it. It can have two values:

  1. ProxyProtocol is a protocol that carries connection information from the source requesting the connection to the destination for which the connection was requested.
  2. XForwardedFor is a multi-value HTTP header that is used by proxies to append IP addresses of the hosts that passed the request.

The choice of mode depends on how the load balancer fronting NGINX Gateway Fabric receives information.

TrustedAddresses are used to specify the IP addresses of the trusted proxies that pass the request. These can be in the form of CIDRs, IPs, or hostnames. For example, if a load balancer is forwarding the request to NGINX Gateway Fabric, the IP address of the load balancer should be specified in the trustedAddresses list to inform NGINX that the forwarded request is from a known source.

SetIPRecursively is a boolean field used to enable recursive search when selecting the client’s address from a multi-value header. It is applicable in cases where we have a multi-value header containing client IPs to select from, that is, when using XForwardedFor mode.

The following command creates an NginxProxy resource with RewriteClientIP settings that set the mode to ProxyProtocol and sets a CIDR in the list of trusted addresses to find the original client IP address.

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  rewriteClientIP:
    mode: ProxyProtocol
    trustedAddresses:
    - type: CIDR
      value: "76.89.90.11/24"
EOF
RewriteClientIP settings apply only to TLS Terminate listeners, not to TLS Passthrough listeners. A Passthrough listener uses the ssl_preread and pass directives to forward encrypted traffic, and does not add a PROXY protocol header. A proxy_protocol directive on a Passthrough listener would cause broken header errors. For more information, see TLS routing with TLSRoute.
When sending curl requests to a server expecting proxy information, use the flag --haproxy-protocol to avoid broken header errors.

Route upstream traffic to the Service ClusterIP

By default, NGINX Gateway Fabric resolves each backend Service to its individual Pod IPs and uses those as the upstream servers. This means that every time the backend Pods change (for example, during a scale up, scale down, or rollout), NGINX must reload to pick up the new set of endpoints.

Setting useClusterIP to true in the NginxProxy resource configures NGINX to route to the Service’s ClusterIP and port instead of the individual Pod IPs. The upstream then contains a single server (the Service VIP), and NGINX no longer needs to reload when the backend Pods churn. This is also useful for service mesh compatibility and for controllers or operators that require traffic to traverse the Service VIP.

You can set useClusterIP globally for all Services through the NginxProxy resource, as shown below, or for a specific Service through the useClusterIP field of an UpstreamSettingsPolicy. When both are configured for the same Service, the UpstreamSettingsPolicy value takes precedence.

Because the upstream contains only the Service VIP as a single server, you lose NGINX’s load balancing across the backend Pods. Traffic is instead load balanced by the Kubernetes Service (kube-proxy), so NGINX load balancing settings such as those in an UpstreamSettingsPolicy no longer apply to that Service.

The following command creates an NginxProxy resource that enables useClusterIP:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  useClusterIP: true
EOF

useClusterIP applies only when the target Service has a ClusterIP. The following cases fall back to the default Pod IP resolution:

  • Headless Services (ClusterIP: None).
  • ExternalName Services.

Layer 4 (TCPRoute/UDPRoute) stream upstreams are unaffected by this setting, since it does not apply to L4 traffic.

If not specified, useClusterIP defaults to false. As with other NginxProxy fields, it can be set on the GatewayClass to apply globally, or on a Gateway to override the GatewayClass value. See the Merging Semantics section for details, and the NginxProxy spec in the API reference for the full list of options.

Configure the global upstream zone size

NGINX keeps the configuration and runtime state of each upstream in a shared memory zone. The more servers (backend Pods) an upstream has, the larger the zone it needs. By default, NGINX Gateway Fabric gives each upstream a fixed default zone size. To change that size for all HTTP and gRPC upstreams, set the zoneSize field of the NginxProxy resource.

The following command creates an NginxProxy resource that sets zoneSize to 1m:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  zoneSize: 1m
EOF

Enter the size as a number of up to four digits followed by k, m, or g. For example, 512k, 1m, or 2m.

To set a different size for one Service, use the zoneSize field of an UpstreamSettingsPolicy. For the steps, see Configure upstream zone size. When both are set for the same Service, the UpstreamSettingsPolicy value takes precedence. For example, give a Service with many more backend Pods than the others a larger zone.

To confirm the new size, inspect the running NGINX configuration:

kubectl exec -it deployments/gateway-nginx -- nginx -T

The zone directive of each HTTP upstream shows 1m, unless an UpstreamSettingsPolicy sets another size for that Service.

Layer 4 stream upstreams for TLSRoute, TCPRoute, and UDPRoute don’t use this setting. They keep their default zone size.

You can set zoneSize on the GatewayClass to apply it to all Gateways. To override that value for one Gateway, set it on the Gateway. See the Merging Semantics section for details. The NginxProxy spec in the API reference lists the default zone sizes and the full list of options.

You can configure deployment and service settings for all data plane instances by editing the NginxProxy resource at the Gateway or GatewayClass level. These settings can also be specified under the nginx section in the Helm values file. You can edit things such as replicas, pod scheduling options, container resource limits, extra volume mounts, service types, load balancer settings, and PodDisruptionBudgets.

The following command creates an NginxProxy resource with 2 replicas, sets container.resources.requests to 100m CPU and 128Mi memory, configures a 90 second pod.terminationGracePeriodSeconds, and sets the service type to LoadBalancer with IP 192.87.9.1 and AWS NLB annotation.

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config-test
spec:
  kubernetes:
    deployment:
      container:
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
      pod:
        terminationGracePeriodSeconds: 90
      replicas: 2
    service:
      type: LoadBalancer
      loadBalancerIP: "192.87.9.1"
EOF

To view the full list of configuration options, see the NginxProxy spec in the API reference.

Configure the load balancer class

When the Service type is LoadBalancer, the loadBalancerClass field selects which controller manages the Service.

By default, NGINX Gateway Fabric leaves this field unset. Your cloud provider or an external controller, such as an AWS Load Balancer or MetalLB, then manages the Service.

To let NGINX Gateway Fabric manage the load balancer, set loadBalancerClass to the controller name. The controller name comes from the --gateway-ctlr-name flag or the nginxGateway.gatewayControllerName Helm value. The default is gateway.nginx.org/nginx-gateway-controller. If you changed the controller name, use your value in the following example:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config-test
spec:
  kubernetes:
    service:
      type: LoadBalancer
      loadBalancerClass: gateway.nginx.org/nginx-gateway-controller
EOF

You can set loadBalancerClass only when the Service type is LoadBalancer. NGINX Gateway Fabric rejects the field on any other Service type.

When loadBalancerClass is the controller name, NGINX Gateway Fabric writes the IP addresses from the Gateway spec.addresses field to the Service status.

The Gateway status reports the IP addresses from the Gateway spec.addresses field together with the IP addresses and hostnames that the load balancer assigns. NGINX Gateway Fabric removes duplicates and reports at most 16 addresses, the limit that the Gateway API sets. When it has more, it keeps IP addresses ahead of hostnames.

Configure a PodDisruptionBudget for the data plane

When you set the podDisruptionBudget field on the NginxProxy resource, the control plane creates a Kubernetes PodDisruptionBudget (PDB) for the data plane. A PodDisruptionBudget caps how many pods in the NGINX data plane can be voluntarily evicted at once. This keeps a minimum number of pods serving traffic during node drains, upgrades, and autoscaler evictions. Without a PodDisruptionBudget, a node drain or autoscaler action can evict every data plane replica at once and interrupt traffic.

The control plane creates one PodDisruptionBudget for each NGINX Deployment it provisions, which is one per Gateway that uses this NginxProxy.

A data plane PodDisruptionBudget applies only when the data plane runs as a Deployment (nginx.kind: deployment). It has no effect on a DaemonSet data plane.

Set the PodDisruptionBudget through the spec.kubernetes.deployment.podDisruptionBudget field in the NginxProxy resource. Note: There is no enable field for this setting in the NginxProxy resource: the control plane creates the PodDisruptionBudget when the field is present. The field takes these settings:

  • minAvailable: the minimum number of pods that must stay available after an eviction. Use an absolute number such as 1, or a percentage such as 50%.
  • maxUnavailable: the maximum number of pods that can be unavailable after an eviction. Use an absolute number or a percentage.
  • unhealthyPodEvictionPolicy: optional. IfHealthyBudget blocks eviction of unhealthy pods when that eviction would break the budget. AlwaysAllow always permits eviction of unhealthy pods. When unset, Kubernetes applies IfHealthyBudget.
Warning
Set exactly one of minAvailable or maxUnavailable. If you set both or neither, the API server rejects the NginxProxy and creates no PodDisruptionBudget.
Caution
Setting minAvailable to an absolute number equal to or greater than the replica count blocks every voluntary eviction. Set it below the replica count. To set the replica count, see Scaling the control plane and data plane.

The following command creates an NginxProxy that keeps at least one data plane pod available during voluntary disruptions:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  kubernetes:
    deployment:
      podDisruptionBudget:
        minAvailable: 1
EOF

To limit how many pods can be unavailable instead, set maxUnavailable and omit minAvailable:

yaml
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-config
spec:
  kubernetes:
    deployment:
      podDisruptionBudget:
        maxUnavailable: 50%
EOF

You can also set the PodDisruptionBudget at install or upgrade time under the nginx.podDisruptionBudget section in the Helm values. This section exposes four keys: enable, minAvailable, maxUnavailable, and unhealthyPodEvictionPolicy. Set nginx.podDisruptionBudget.enable to true to turn it on. Through Helm, minAvailable defaults to 1, so enable: true on its own produces a valid PodDisruptionBudget. unhealthyPodEvictionPolicy defaults to an empty string, so Helm omits the field and Kubernetes applies IfHealthyBudget.

The following partial values fragment, set in a values file or with --set, turns on the data plane PodDisruptionBudget with a minAvailable of 1:

yaml
nginx:
  kind: deployment
  podDisruptionBudget:
    enable: true
    minAvailable: 1

To use maxUnavailable through Helm, set minAvailable to an empty string and set maxUnavailable. The empty minAvailable is dropped, so only maxUnavailable renders:

yaml
nginx:
  kind: deployment
  podDisruptionBudget:
    enable: true
    minAvailable: ""
    maxUnavailable: 1

After you apply either configuration, list the PodDisruptionBudgets in the namespace of the Gateway that uses this NginxProxy:

kubectl get poddisruptionbudgets -n <namespace>

Confirm a PodDisruptionBudget exists for each NGINX Deployment. Each one reports its configured minAvailable or maxUnavailable and the number of voluntary disruptions it currently allows.

This check matters most for a DaemonSet data plane. Setting the field on a DaemonSet produces no PodDisruptionBudget, and the control plane reports no error. The list is how you confirm one was created. The exactly-one-of mistake fails differently, and it is not silent. If you set both or neither of minAvailable and maxUnavailable, the API server rejects the NginxProxy. The kubectl apply or kubectl edit command then fails at apply time.

To view the full list of configuration options, see the NginxProxy spec in the API reference.

Patch data plane Service, Deployment, and DaemonSet

NGINX Gateway Fabric supports advanced customization of the data plane Service, Deployment, and DaemonSet objects using patches in the NginxProxy resource. This allows you to apply Kubernetes-style patches to these resources, enabling custom labels, annotations, or other modifications that are not directly exposed via the NginxProxy spec.

Supported Patch Types

You can specify one or more patches for each of the following resources:

  • spec.kubernetes.service.patches
  • spec.kubernetes.deployment.patches
  • spec.kubernetes.daemonSet.patches

Each patch has two fields:

  • type: The patch type. Supported values are:
    • StrategicMerge (default): Strategic merge patch (Kubernetes default for most resources)
    • Merge: JSON merge patch (RFC 7386)
    • JSONPatch: JSON patch (RFC 6902)
  • value: The patch data. For StrategicMerge and Merge, this should be a JSON object. For JSONPatch, this should be a JSON array of patch operations.

Patches are applied in the order they appear in the array. Later patches can override fields set by earlier patches.

Which patch type should I use?

  • StrategicMerge is the default and most user-friendly for Kubernetes-native resources like Deployments and Services. It understands lists and merges fields intelligently (for example, merging containers by name). Use this for most use cases.
  • Merge (JSON Merge Patch) is simpler and works well for basic object merges, but does not handle lists or complex merging. Use this if you want to replace entire fields or for non-Kubernetes-native resources.
  • JSONPatch is the most powerful and flexible, allowing you to add, remove, or replace specific fields using RFC 6902 operations. Use this for advanced or fine-grained changes, but it is more verbose and error-prone.

If unsure, start with StrategicMerge. Use JSONPatch only if you need to surgically modify fields that cannot be addressed by the other patch types.

Patches are applied after all other NginxProxy configuration is rendered. Invalid patches will result in a validation error and will not be applied.

Example: Configure Service with session affinity

yaml
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-patch-service
spec:
  kubernetes:
    service:
      patches:
        - type: StrategicMerge
          value:
            spec:
              sessionAffinity: ClientIP
              sessionAffinityConfig:
                clientIP:
                  timeoutSeconds: 300

Example: Configure Deployment with custom strategy

yaml
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-patch-deployment
spec:
  kubernetes:
    deployment:
      patches:
        - type: Merge
          value:
            spec:
              strategy:
                type: RollingUpdate
                rollingUpdate:
                  maxUnavailable: 0
                  maxSurge: 2

Example: Use JSONPatch to configure DaemonSet host networking and priority

yaml
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-patch-daemonset
spec:
  kubernetes:
    daemonSet:
      patches:
        - type: JSONPatch
          value:
            - op: add
              path: /spec/template/spec/hostNetwork
              value: true
            - op: add
              path: /spec/template/spec/dnsPolicy
              value: "ClusterFirstWithHostNet"
            - op: add
              path: /spec/template/spec/priorityClassName
              value: "system-node-critical"

Example: Multiple patches, later patch overrides earlier

yaml
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
  name: ngf-proxy-multi-patch
spec:
  kubernetes:
    service:
      patches:
        - type: StrategicMerge
          value:
            spec:
              sessionAffinity: ClientIP
              publishNotReadyAddresses: false
        - type: StrategicMerge
          value:
            spec:
              sessionAffinity: None
              publishNotReadyAddresses: true

In this example, the final Service will have sessionAffinity: None and publishNotReadyAddresses: true because the second patch overrides the values from the first patch.

View source
View as Markdown
Edit this page
Create a new issue