diff --git a/content/ngf/get-started.md b/content/ngf/get-started.md index e8cb75fdb..d54afedb2 100644 --- a/content/ngf/get-started.md +++ b/content/ngf/get-started.md @@ -36,14 +36,14 @@ Create the file _cluster-config.yaml_ with the following contents, noting the hi apiVersion: kind.x-k8s.io/v1alpha4 kind: Cluster nodes: -- role: control-plane - extraPortMappings: - - containerPort: 31437 - hostPort: 8080 - protocol: TCP - - containerPort: 31438 - hostPort: 8443 - protocol: TCP + - role: control-plane + extraPortMappings: + - containerPort: 31437 + hostPort: 8080 + protocol: TCP + - containerPort: 31438 + hostPort: 8443 + protocol: TCP ``` {{< warning >}} @@ -73,7 +73,7 @@ Thanks for using kind! 😊 ``` {{< note >}} -If you have cloned [the NGINX Gateway Fabric repository](https://github.com/nginx/nginx-gateway-fabric/tree/main), you can also create a kind cluster from the root folder with the following *make* command: +If you have cloned [the NGINX Gateway Fabric repository](https://github.com/nginx/nginx-gateway-fabric/tree/main), you can also create a kind cluster from the root folder with the following _make_ command: ```shell make create-kind-cluster @@ -90,7 +90,7 @@ make create-kind-cluster Use `kubectl` to add the API resources for NGINX Gateway Fabric with the following command: ```shell -kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.5.1" | kubectl apply -f - +kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.1" | kubectl apply -f - ``` ```text @@ -105,7 +105,7 @@ customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking To use experimental features, you'll need to install the API resources from the experimental channel instead. ```shell -kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.5.1" | kubectl apply -f - +kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.1" | kubectl apply -f - ``` {{< /note >}} @@ -121,7 +121,7 @@ helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namesp ``` ```text -Pulled: ghcr.io/nginx/charts/nginx-gateway-fabric:1.5.1 +Pulled: ghcr.io/nginx/charts/nginx-gateway-fabric:1.6.1 Digest: sha256:9bbd1a2fcbfd5407ad6be39f796f582e6263512f1f3a8969b427d39063cc6fee NAME: ngf LAST DEPLOYED: Mon Oct 21 14:45:14 2024 @@ -159,23 +159,23 @@ metadata: labels: app.kubernetes.io/name: nginx-gateway-fabric app.kubernetes.io/instance: ngf - app.kubernetes.io/version: "1.5.1" + app.kubernetes.io/version: "1.6.1" spec: type: NodePort selector: app.kubernetes.io/name: nginx-gateway-fabric app.kubernetes.io/instance: ngf ports: - - name: http - port: 80 - protocol: TCP - targetPort: 80 - nodePort: 31437 - - name: https - port: 443 - protocol: TCP - targetPort: 443 - nodePort: 31438 + - name: http + port: 80 + protocol: TCP + targetPort: 80 + nodePort: 31437 + - name: https + port: 443 + protocol: TCP + targetPort: 443 + nodePort: 31438 ``` Apply it using `kubectl`: diff --git a/content/ngf/how-to/monitoring/prometheus.md b/content/ngf/how-to/monitoring/prometheus.md index cc4424dd2..c50d8a8d8 100644 --- a/content/ngf/how-to/monitoring/prometheus.md +++ b/content/ngf/how-to/monitoring/prometheus.md @@ -83,7 +83,7 @@ NGINX Gateway Fabric provides a variety of metrics for monitoring and analyzing ### NGINX/NGINX Plus metrics -NGINX metrics cover specific NGINX operations such as the total number of accepted client connections. For a complete list of available NGINX/NGINX Plus metrics, refer to the [NGINX Prometheus Exporter developer docs](https://github.com/nginxinc/nginx-prometheus-exporter#exported-metrics). +NGINX metrics cover specific NGINX operations such as the total number of accepted client connections. For a complete list of available NGINX/NGINX Plus metrics, refer to the [NGINX Prometheus Exporter developer docs](https://github.com/nginx/nginx-prometheus-exporter#exported-metrics). These metrics use the `nginx_gateway_fabric` namespace and include the `class` label, indicating the NGINX Gateway class. For example, `nginx_gateway_fabric_connections_accepted{class="nginx"}`. @@ -119,13 +119,13 @@ You can configure monitoring metrics for NGINX Gateway Fabric using Helm or Mani ### Using Helm -If you're setting up NGINX Gateway Fabric with Helm, you can adjust the `metrics.*` parameters to fit your needs. For detailed options and instructions, see the [Helm README](https://github.com/nginx/nginx-gateway-fabric/blob/v1.5.1/charts/nginx-gateway-fabric/README.md). +If you're setting up NGINX Gateway Fabric with Helm, you can adjust the `metrics.*` parameters to fit your needs. For detailed options and instructions, see the [Helm README](https://github.com/nginx/nginx-gateway-fabric/blob/v1.6.1/charts/nginx-gateway-fabric/README.md). --- ### Using Kubernetes manifests -For setups using Kubernetes manifests, change the metrics configuration by editing the NGINX Gateway Fabric manifest that you want to deploy. You can find some examples in the [deploy](https://github.com/nginx/nginx-gateway-fabric/tree/v1.5.1/deploy) directory. +For setups using Kubernetes manifests, change the metrics configuration by editing the NGINX Gateway Fabric manifest that you want to deploy. You can find some examples in the [deploy](https://github.com/nginx/nginx-gateway-fabric/tree/v1.6.1/deploy) directory. --- @@ -136,18 +136,18 @@ If you need to disable metrics: 1. Set the `-metrics-disable` [command-line argument]({{< ref "/ngf/reference/cli-help.md">}}) to `true` in the NGINX Gateway Fabric Pod's configuration. Remove any other `-metrics-*` arguments. 2. In the Pod template for NGINX Gateway Fabric, delete the metrics port entry from the container ports list: - ```yaml - - name: metrics - containerPort: 9113 - ``` + ```yaml + - name: metrics + containerPort: 9113 + ``` 3. Also, remove the following annotations from the NGINX Gateway Fabric Pod template: - ```yaml - annotations: - prometheus.io/scrape: "true" - prometheus.io/port: "9113" - ``` + ```yaml + annotations: + prometheus.io/scrape: "true" + prometheus.io/port: "9113" + ``` #### Changing the default port @@ -156,19 +156,19 @@ To change the default port for metrics: 1. Update the `-metrics-port` [command-line argument]({{< ref "/ngf/reference/cli-help.md">}}) in the NGINX Gateway Fabric Pod's configuration to your chosen port number. 2. In the Pod template, change the metrics port entry to reflect the new port: - ```yaml - - name: metrics - containerPort: - ``` + ```yaml + - name: metrics + containerPort: + ``` 3. Modify the `prometheus.io/port` annotation in the Pod template to match the new port: - ```yaml - annotations: - <...> - prometheus.io/port: "" - <...> - ``` + ```yaml + annotations: + <...> + prometheus.io/port: "" + <...> + ``` --- @@ -180,9 +180,9 @@ For enhanced security with HTTPS: 2. Add an HTTPS scheme annotation to the Pod template: - ```yaml - annotations: - <...> - prometheus.io/scheme: "https" - <...> - ``` + ```yaml + annotations: + <...> + prometheus.io/scheme: "https" + <...> + ``` diff --git a/content/ngf/how-to/monitoring/tracing.md b/content/ngf/how-to/monitoring/tracing.md index 8f42df39d..ed7635670 100644 --- a/content/ngf/how-to/monitoring/tracing.md +++ b/content/ngf/how-to/monitoring/tracing.md @@ -15,7 +15,7 @@ This guide explains how to enable tracing on HTTPRoutes in NGINX Gateway Fabric NGINX Gateway Fabric supports tracing using [OpenTelemetry](https://opentelemetry.io/). -The official [NGINX OpenTelemetry Module](https://github.com/nginxinc/nginx-otel) instruments the NGINX data plane to export traces to a configured collector. Tracing data can be used with an OpenTelemetry Protocol (OTLP) exporter, such as the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector). +The official [NGINX OpenTelemetry Module](https://github.com/nginxinc/nginx-otel) instruments the NGINX data plane to export traces to a configured collector. Tracing data can be used with an OpenTelemetry Protocol (OTLP) exporter, such as the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector). This collector can then export data to one or more upstream collectors like [Jaeger](https://www.jaegertracing.io/), [DataDog](https://docs.datadoghq.com/tracing/), and many others. This is called the [Agent model](https://opentelemetry.io/docs/collector/deployment/agent/). @@ -104,7 +104,7 @@ The span attribute will be added to all tracing spans. To install: ```shell -helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway -f values.yaml +helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway -f values.yaml ``` You should see the following configuration: @@ -123,8 +123,8 @@ spec: exporter: endpoint: otel-collector.tracing.svc:4317 spanAttributes: - - key: cluster-attribute-key - value: cluster-attribute-value + - key: cluster-attribute-key + value: cluster-attribute-value ``` ```shell @@ -144,24 +144,24 @@ spec: name: ngf-proxy-config status: conditions: - - lastTransitionTime: "2024-05-22T15:18:35Z" - message: GatewayClass is accepted - observedGeneration: 1 - reason: Accepted - status: "True" - type: Accepted - - lastTransitionTime: "2024-05-22T15:18:35Z" - message: Gateway API CRD versions are supported - observedGeneration: 1 - reason: SupportedVersion - status: "True" - type: SupportedVersion - - lastTransitionTime: "2024-05-22T15:18:35Z" - message: parametersRef resource is resolved - observedGeneration: 1 - reason: ResolvedRefs - status: "True" - type: ResolvedRefs + - lastTransitionTime: "2024-05-22T15:18:35Z" + message: GatewayClass is accepted + observedGeneration: 1 + reason: Accepted + status: "True" + type: Accepted + - lastTransitionTime: "2024-05-22T15:18:35Z" + message: Gateway API CRD versions are supported + observedGeneration: 1 + reason: SupportedVersion + status: "True" + type: SupportedVersion + - lastTransitionTime: "2024-05-22T15:18:35Z" + message: parametersRef resource is resolved + observedGeneration: 1 + reason: ResolvedRefs + status: "True" + type: ResolvedRefs ``` If you already have NGINX Gateway Fabric installed, then you can create the `NginxProxy` resource and link it to the GatewayClass `parametersRef`: @@ -172,10 +172,10 @@ kubectl edit gatewayclasses.gateway.networking.k8s.io nginx Save the public IP address and port of NGINX Gateway Fabric into shell variables: - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` +```text +GW_IP=XXX.YYY.ZZZ.III +GW_PORT= +``` You can now create the application, route, and tracing policy. @@ -283,7 +283,7 @@ To enable tracing for the coffee HTTPRoute, create the following policy: ```yaml kubectl apply -f - <}}) NGINX Gateway Fabric. - Save the public IP address and port of NGINX Gateway Fabric into shell variables: - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_PORT= + ``` {{< note >}} In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. {{< /note >}} @@ -45,7 +44,7 @@ The goal is to create a set of rules that will result in client requests being s Begin by deploying the `coffee-v1` and `coffee-v2` applications: ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/advanced-routing/coffee.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/advanced-routing/coffee.yaml ``` --- @@ -117,7 +116,7 @@ This HTTPRoute has a few important properties: - The `parentRefs` references the gateway resource that we created, and specifically defines the `http` listener to attach to, via the `sectionName` field. - `cafe.example.com` is the hostname that is matched for all requests to the backends defined in this HTTPRoute. - The first rule defines that all requests with the path prefix `/coffee` and no other matching conditions are sent to the `coffee-v1` Service. -- The second rule defines two matching conditions. If *either* of these conditions match, requests are forwarded to the `coffee-v2` Service: +- The second rule defines two matching conditions. If _either_ of these conditions match, requests are forwarded to the `coffee-v2` Service: - Request with the path prefix `/coffee` and header `version=v2` - Request with the path prefix `/coffee` and the query parameter `TEST=v2` @@ -173,7 +172,7 @@ Let's deploy a different set of applications now called `tea` and `tea-post`. Th ### Deploy the Tea applications ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/advanced-routing/tea.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/advanced-routing/tea.yaml ``` --- diff --git a/content/ngf/how-to/traffic-management/client-settings.md b/content/ngf/how-to/traffic-management/client-settings.md index 8f694505d..615bca682 100644 --- a/content/ngf/how-to/traffic-management/client-settings.md +++ b/content/ngf/how-to/traffic-management/client-settings.md @@ -17,11 +17,11 @@ The `ClientSettingsPolicy` API allows Cluster Operators and Application Develope The settings in `ClientSettingsPolicy` correspond to the following NGINX directives: -- [`client_max_body_size`]() -- [`client_body_timeout`]() -- [`keepalive_requests`]() -- [`keepalive_time`]() -- [`keepalive_timeout`]() +- [`client_max_body_size`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) +- [`client_body_timeout`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_timeout) +- [`keepalive_requests`](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests) +- [`keepalive_time`](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_time) +- [`keepalive_timeout`](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout) `ClientSettingsPolicy` is an [Inherited PolicyAttachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) that can be applied to a Gateway, HTTPRoute, or GRPCRoute in the same namespace as the `ClientSettingsPolicy`. @@ -41,7 +41,7 @@ For all the possible configuration options for `ClientSettingsPolicy`, see the [ - [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. - Save the public IP address and port of NGINX Gateway Fabric into shell variables: - ```text + ```text GW_IP=XXX.YYY.ZZZ.III GW_PORT= ``` @@ -51,20 +51,20 @@ For all the possible configuration options for `ClientSettingsPolicy`, see the [ - Create the coffee and tea example applications: ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/examples/client-settings-policy/app.yaml + kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/client-settings-policy/app.yaml ``` - Create a Gateway: ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/examples/client-settings-policy/gateway.yaml - ``` + kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/client-settings-policy/gateway.yaml + ``` - Create HTTPRoutes for the coffee and tea applications: ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/examples/client-settings-policy/httproutes.yaml - ``` + kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/client-settings-policy/httproutes.yaml + ``` - Test the configuration: @@ -87,7 +87,7 @@ For all the possible configuration options for `ClientSettingsPolicy`, see the [ ```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea - ``` + ``` This request should receive a response from the tea Pod: diff --git a/content/ngf/how-to/traffic-management/request-response-headers.md b/content/ngf/how-to/traffic-management/request-response-headers.md index d884b4049..e6e9ad209 100644 --- a/content/ngf/how-to/traffic-management/request-response-headers.md +++ b/content/ngf/how-to/traffic-management/request-response-headers.md @@ -22,10 +22,10 @@ This guide describes how to configure the headers application to modify the head - [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. - Save the public IP address and port of NGINX Gateway Fabric into shell variables: - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_PORT= + ``` {{< note >}} In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for .{{< /note >}} @@ -67,7 +67,7 @@ This examples demonstrates how to configure traffic routing for a simple echo se Begin by deploying the example application `headers`. It is a simple application that returns the request headers which will be modified later. ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/http-request-header-filter/headers.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/http-request-header-filter/headers.yaml ``` This will create the headers Service and a Deployment with one Pod. Run the following command to verify the resources were created: @@ -132,9 +132,9 @@ This HTTPRoute has a few important properties: - The `match` rule defines that all requests with the path prefix `/headers` are sent to the `headers` Service. - It has a `RequestHeaderModifier` filter defined for the path prefix `/headers`. This filter: - 1. Sets the value for header `My-Overwrite-Header` to `this-is-the-only-value`. - 1. Appends the value `compress` to the `Accept-Encoding` header and `this-is-an-appended-value` to the `My-Cool-header`. - 1. Removes `User-Agent` header. + 1. Sets the value for header `My-Overwrite-Header` to `this-is-the-only-value`. + 1. Appends the value `compress` to the `Accept-Encoding` header and `this-is-an-appended-value` to the `My-Cool-header`. + 1. Removes `User-Agent` header. --- @@ -179,7 +179,7 @@ kubectl delete httproutes.gateway.networking.k8s.io headers ``` ```shell -kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/http-request-header-filter/headers.yaml +kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/http-request-header-filter/headers.yaml ``` --- @@ -195,7 +195,7 @@ Begin by configuring an application with custom headers and a simple HTTPRoute. Begin by deploying the example application `headers`. It is a simple application that adds response headers that will be modified later. ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/http-response-header-filter/headers.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/http-response-header-filter/headers.yaml ``` This will create the headers Service and a Deployment with one Pod. Run the following command to verify the resources were created: @@ -352,7 +352,7 @@ X-Header-Set: overwritten-value ok ``` -In the output above you can notice the modified response headers as the `X-Header-Unmodified` remains unchanged as we did not include it in the filter and `X-Header-Remove` header is absent. The header `X-Header-Add` gets appended with the new value and `X-Header-Set` gets overwritten to `overwritten-value` as defined in the *HttpRoute*. +In the output above you can notice the modified response headers as the `X-Header-Unmodified` remains unchanged as we did not include it in the filter and `X-Header-Remove` header is absent. The header `X-Header-Add` gets appended with the new value and `X-Header-Set` gets overwritten to `overwritten-value` as defined in the _HttpRoute_. --- diff --git a/content/ngf/how-to/traffic-management/snippets.md b/content/ngf/how-to/traffic-management/snippets.md index fe7821d21..bf995b7c6 100644 --- a/content/ngf/how-to/traffic-management/snippets.md +++ b/content/ngf/how-to/traffic-management/snippets.md @@ -59,13 +59,14 @@ We have outlined a few best practices to keep in mind when using `SnippetsFilter ## Setup - To enable Snippets, [install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric with these modifications: + - Using Helm: set the `nginxGateway.snippetsFilters.enable=true` Helm value. - Using Kubernetes manifests: set the `--snippets-filters` flag in the nginx-gateway container argument, add `snippetsfilters` to the RBAC rules with verbs `list` and `watch`, and add `snippetsfilters/status` to the RBAC rules with verb `update`. See this [example manifest](https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/main/deploy/snippets-filters/deploy.yaml) for clarification. - Save the public IP address and port of NGINX Gateway Fabric into shell variables: - ```text + ```text GW_IP= GW_PORT= ``` @@ -75,20 +76,20 @@ We have outlined a few best practices to keep in mind when using `SnippetsFilter - Create the coffee and tea example applications: ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/examples/snippets-filter/app.yaml + kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/snippets-filter/app.yaml ``` - Create a Gateway: ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/examples/snippets-filter/gateway.yaml - ``` + kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/snippets-filter/gateway.yaml + ``` - Create HTTPRoutes for the coffee and tea applications: ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/examples/snippets-filter/httproutes.yaml - ``` + kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/examples/snippets-filter/httproutes.yaml + ``` - Test the configuration: @@ -111,7 +112,7 @@ We have outlined a few best practices to keep in mind when using `SnippetsFilter ```shell curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea - ``` + ``` This request should receive a response from the tea Pod: diff --git a/content/ngf/how-to/traffic-management/upstream-settings.md b/content/ngf/how-to/traffic-management/upstream-settings.md new file mode 100644 index 000000000..08c815cc0 --- /dev/null +++ b/content/ngf/how-to/traffic-management/upstream-settings.md @@ -0,0 +1,397 @@ +--- +title: "Upstream Settings Policy API" +weight: 900 +toc: true +type: how-to +product: NGF +docs: "DOCS-000" +--- + +Learn how to use the `UpstreamSettingsPolicy` API. + +## Overview + +The `UpstreamSettingsPolicy` API allows Application Developers to configure the behavior of a connection between NGINX and the upstream applications. + +The settings in `UpstreamSettingsPolicy` correspond to the following NGINX directives: + +- [`zone`]() +- [`keepalive`]() +- [`keepalive_requests`]() +- [`keepalive_time`]() +- [`keepalive_timeout`]() + +`UpstreamSettingsPolicy` is a [Direct Policy Attachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) that can be applied to one or more services in the same namespace as the policy. +`UpstreamSettingsPolicies` can only be applied to HTTP or gRPC services, in other words, services that are referenced by an HTTPRoute or GRPCRoute. + +See the [custom policies]({{< relref "/ngf/overview/custom-policies.md" >}}) document for more information on policies. + +This guide will show you how to use the `UpstreamSettingsPolicy` API to configure the upstream zone size and keepalives for your applications. + +For all the possible configuration options for `UpstreamSettingsPolicy`, see the [API reference]({{< relref "/ngf/reference/api.md" >}}). + +--- + +## Before you begin + +- [Install]({{< relref "/ngf/installation/" >}}) NGINX Gateway Fabric. +- Save the public IP address and port of NGINX Gateway Fabric into shell variables: + + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_PORT= + ``` + +- Lookup the name of the NGINX Gateway Fabric pod and save into shell variable: + + ```text + NGF_POD_NAME= + ``` + + {{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} + +--- + +## Setup + +Create the `coffee` and `tea` example applications: + +```yaml +kubectl apply -f - < 80/TCP 23h +service/tea ClusterIP 10.244.0.15 80/TCP 23h + +NAME READY STATUS RESTARTS AGE +pod/coffee-676c9f8944-n9g6n 1/1 Running 0 23h +pod/tea-6fbfdcb95d-cf84d 1/1 Running 0 23h +``` + +Create a Gateway: + +```yaml +kubectl apply -f - < +``` + +Next, verify that the policy has been applied to the `coffee` and `tea` upstreams by inspecting the NGINX configuration: + +```shell +kubectl exec -it -n nginx-gateway $NGF_POD_NAME -c nginx -- nginx -T +``` + +You should see the `zone` directive in the `coffee` and `tea` upstreams both specify the size `1m`: + +```text +upstream default_coffee_80 { + random two least_conn; + zone default_coffee_80 1m; + + server 10.244.0.14:8080; +} + +upstream default_tea_80 { + random two least_conn; + zone default_tea_80 1m; + + server 10.244.0.15:8080; +} +``` + +## Enable keepalive connections + +To enable keepalive connections for the `coffee` service, create the following `UpstreamSettingsPolicy`: + +```yaml +kubectl apply -f - < +``` + +Next, verify that the policy has been applied to the `coffee` upstreams, by inspecting the NGINX configuration: + +```shell +kubectl exec -it -n nginx-gateway $NGF_POD_NAME -c nginx -- nginx -T +``` + +You should see that the `coffee` upstream has the `keepalive` directive set to 32: + +```text +upstream default_coffee_80 { + random two least_conn; + zone default_coffee_80 1m; + + server 10.244.0.14:8080; + keepalive 32; +} +``` + +Notice, that the `tea` upstream does not contain the `keepalive` directive, since the `upstream-keepalives` policy does not target the `tea` service: + +```text +upstream default_tea_80 { + random two least_conn; + zone default_tea_80 1m; + + server 10.244.0.15:8080; +} +``` + +--- + +## Further reading + +- [Custom policies]({{< relref "/ngf/overview/custom-policies.md" >}}): learn about how NGINX Gateway Fabric custom policies work. +- [API reference]({{< relref "/ngf/reference/api.md" >}}): all configuration fields for the `UpstreamSettingsPolicy` API. diff --git a/content/ngf/how-to/upgrade-apps-without-downtime.md b/content/ngf/how-to/upgrade-apps-without-downtime.md index 3ec8a38a1..e959a0f82 100644 --- a/content/ngf/how-to/upgrade-apps-without-downtime.md +++ b/content/ngf/how-to/upgrade-apps-without-downtime.md @@ -58,15 +58,15 @@ For example, an application can be exposed using a routing rule like below: ```yaml - matches: - - path: - type: PathPrefix - value: / + - path: + type: PathPrefix + value: / backendRefs: - - name: my-app - port: 80 + - name: my-app + port: 80 ``` -{{< note >}} See the [Cafe example](https://github.com/nginx/nginx-gateway-fabric/tree/v1.5.1/examples/cafe-example) for a basic example. {{< /note >}} +{{< note >}} See the [Cafe example](https://github.com/nginx/nginx-gateway-fabric/tree/v1.6.1/examples/cafe-example) for a basic example. {{< /note >}} The upgrade methods in the next sections cover: @@ -107,16 +107,16 @@ A more flexible and precise way to implement canary releases is to configure a t ```yaml - matches: - - path: - type: PathPrefix - value: / + - path: + type: PathPrefix + value: / backendRefs: - - name: my-app-old - port: 80 - weight: 95 - - name: my-app-new - port: 80 - weight: 5 + - name: my-app-old + port: 80 + weight: 95 + - name: my-app-new + port: 80 + weight: 5 ``` {{< note >}} Every request coming from the same client won't necessarily be sent to the same backend. NGINX will independently split each request among the backend references. {{< /note >}} @@ -125,16 +125,16 @@ By updating the rule you can further increase the share of traffic the new versi ```yaml - matches: - - path: - type: PathPrefix - value: / + - path: + type: PathPrefix + value: / backendRefs: - - name: my-app-old - port: 80 - weight: 0 - - name: my-app-new - port: 80 - weight: 1 + - name: my-app-old + port: 80 + weight: 0 + - name: my-app-new + port: 80 + weight: 1 ``` -See the [Traffic splitting example](https://github.com/nginx/nginx-gateway-fabric/tree/v1.5.1/examples/traffic-splitting) from our repository. +See the [Traffic splitting example](https://github.com/nginx/nginx-gateway-fabric/tree/v1.6.1/examples/traffic-splitting) from our repository. diff --git a/content/ngf/installation/building-the-images.md b/content/ngf/installation/building-the-images.md index 5acd5e8b1..3975aec8c 100644 --- a/content/ngf/installation/building-the-images.md +++ b/content/ngf/installation/building-the-images.md @@ -32,22 +32,23 @@ If building the NGINX Plus image, you will also need a valid NGINX Plus license 1. Clone the repo and change into the `nginx-gateway-fabric` directory: ```shell - git clone https://github.com/nginx/nginx-gateway-fabric.git --branch v1.5.1 + git clone https://github.com/nginx/nginx-gateway-fabric.git --branch v1.6.1 cd nginx-gateway-fabric ``` 1. Build the images: + - To build both the NGINX Gateway Fabric and NGINX images: - ```makefile - make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-images - ``` + ```makefile + make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-images + ``` - To build both the NGINX Gateway Fabric and NGINX Plus images: - ```makefile - make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-images-with-plus - ``` + ```makefile + make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-images-with-plus + ``` - To build just the NGINX Gateway Fabric image: @@ -68,20 +69,20 @@ If building the NGINX Plus image, you will also need a valid NGINX Plus license ``` Set the `PREFIX` variable to the name of the registry you'd like to push the image to. By default, the images will be - named `nginx-gateway-fabric:1.5.1` and `nginx-gateway-fabric/nginx:1.5.1` or `nginx-gateway-fabric/nginx-plus:1.5.1`. + named `nginx-gateway-fabric:1.6.1` and `nginx-gateway-fabric/nginx:1.6.1` or `nginx-gateway-fabric/nginx-plus:1.6.1`. 1. Push the images to your container registry: ```shell - docker push myregistry.example.com/nginx-gateway-fabric:1.5.1 - docker push myregistry.example.com/nginx-gateway-fabric/nginx:1.5.1 + docker push myregistry.example.com/nginx-gateway-fabric:1.6.1 + docker push myregistry.example.com/nginx-gateway-fabric/nginx:1.6.1 ``` or ```shell - docker push myregistry.example.com/nginx-gateway-fabric:1.5.1 - docker push myregistry.example.com/nginx-gateway-fabric/nginx-plus:1.5.1 + docker push myregistry.example.com/nginx-gateway-fabric:1.6.1 + docker push myregistry.example.com/nginx-gateway-fabric/nginx-plus:1.6.1 ``` Make sure to substitute `myregistry.example.com/nginx-gateway-fabric` with your registry. diff --git a/content/ngf/installation/installing-ngf/helm.md b/content/ngf/installation/installing-ngf/helm.md index 9fc0edc2b..3d15c0869 100644 --- a/content/ngf/installation/installing-ngf/helm.md +++ b/content/ngf/installation/installing-ngf/helm.md @@ -24,6 +24,7 @@ To complete this guide, you'll need to install: - [Helm 3.0 or later](https://helm.sh/docs/intro/install/), for deploying and managing applications on Kubernetes. {{< important >}} If you’d like to use NGINX Plus, some additional setup is also required: {{}} +
NGINX Plus JWT setup @@ -129,13 +130,13 @@ helm install ngf . --set nginx.image.repository=private-registry.nginx.com/nginx {{}} - `ngf` is the name of the release, and can be changed to any name you want. This name is added as a prefix to the Deployment name. +`ngf` is the name of the release, and can be changed to any name you want. This name is added as a prefix to the Deployment name. - To wait for the Deployment to be ready, you can either add the `--wait` flag to the `helm install` command, or run the following after installing: +To wait for the Deployment to be ready, you can either add the `--wait` flag to the `helm install` command, or run the following after installing: - ```shell - kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available - ``` +```shell +kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available +``` --- @@ -174,7 +175,7 @@ helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namesp #### Examples -You can find several examples of configuration options of the `values.yaml` file in the [helm examples](https://github.com/nginx/nginx-gateway-fabric/tree/v1.5.1/examples/helm) directory. +You can find several examples of configuration options of the `values.yaml` file in the [helm examples](https://github.com/nginx/nginx-gateway-fabric/tree/v1.6.1/examples/helm) directory. --- @@ -201,13 +202,13 @@ To upgrade your Gateway API resources, take the following steps: - To upgrade the Gateway API resources, run: ```shell - kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.5.1" | kubectl apply -f - + kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.1" | kubectl apply -f - ``` or, if you installed the from the experimental channel: ```shell - kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.5.1" | kubectl apply -f - + kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.1" | kubectl apply -f - ``` --- @@ -223,7 +224,7 @@ To upgrade the CRDs, take the following steps: 2. Upgrade the CRDs: ```shell - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/crds.yaml + kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/crds.yaml ``` {{}}Ignore the following warning, as it is expected.{{}} @@ -354,16 +355,15 @@ Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your K ```shell kubectl delete ns nginx-gateway - kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/crds.yaml + kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/crds.yaml ``` 3. **Remove the Gateway API resources:** - {{< include "/ngf/installation/uninstall-gateway-api-resources.md" >}} - --- ## Additional configuration -For a full list of the Helm Chart configuration parameters, read [the NGINX Gateway Fabric Helm Chart](https://github.com/nginx/nginx-gateway-fabric/blob/v1.5.1/charts/nginx-gateway-fabric/README.md#configuration). +For a full list of the Helm Chart configuration parameters, read [the NGINX Gateway Fabric Helm Chart](https://github.com/nginx/nginx-gateway-fabric/blob/v1.6.1/charts/nginx-gateway-fabric/README.md#configuration). diff --git a/content/ngf/installation/installing-ngf/manifests.md b/content/ngf/installation/installing-ngf/manifests.md index 6bb844ac0..9726af98c 100644 --- a/content/ngf/installation/installing-ngf/manifests.md +++ b/content/ngf/installation/installing-ngf/manifests.md @@ -23,6 +23,7 @@ To complete this guide, you'll need to install: - [kubectl](https://kubernetes.io/docs/tasks/tools/), a command-line interface for managing Kubernetes clusters. {{< important >}} If you’d like to use NGINX Plus, some additional setup is also required: {{}} +
NGINX Plus JWT setup @@ -63,7 +64,7 @@ Deploying NGINX Gateway Fabric with Kubernetes manifests takes only a few steps. #### Stable release ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/crds.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/crds.yaml ``` #### Edge version @@ -85,7 +86,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/ma Deploys NGINX Gateway Fabric with NGINX OSS. ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/default/deploy.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/default/deploy.yaml ``` {{% /tab %}} @@ -95,7 +96,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1 Deploys NGINX Gateway Fabric with NGINX OSS and an AWS Network Load Balancer service. ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/aws-nlb/deploy.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/aws-nlb/deploy.yaml ``` {{% /tab %}} @@ -105,7 +106,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1 Deploys NGINX Gateway Fabric with NGINX OSS and `nodeSelector` to deploy on Linux nodes. ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/azure/deploy.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/azure/deploy.yaml ``` {{% /tab %}} @@ -117,7 +118,7 @@ NGINX Plus Docker registry, and the `imagePullSecretName` is the name of the Sec The NGINX Plus JWT Secret used to run NGINX Plus is also specified in a volume mount and the `--usage-report-secret` parameter. These Secrets are created as part of the [Before you begin](#before-you-begin) section. ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/nginx-plus/deploy.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/nginx-plus/deploy.yaml ``` {{% /tab %}} @@ -127,7 +128,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1 Deploys NGINX Gateway Fabric with NGINX OSS and experimental features. ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/experimental/deploy.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/experimental/deploy.yaml ``` {{< note >}} Requires the Gateway APIs installed from the experimental channel. {{< /note >}} @@ -141,7 +142,7 @@ NGINX Plus Docker registry, and the `imagePullSecretName` is the name of the Sec The NGINX Plus JWT Secret used to run NGINX Plus is also specified in a volume mount and the `--usage-report-secret` parameter. These Secrets are created as part of the [Before you begin](#before-you-begin) section. ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/nginx-plus-experimental/deploy.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/nginx-plus-experimental/deploy.yaml ``` {{< note >}} Requires the Gateway APIs installed from the experimental channel. {{< /note >}} @@ -153,7 +154,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1 Deploys NGINX Gateway Fabric with NGINX OSS using a Service type of `NodePort`. ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/nodeport/deploy.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/nodeport/deploy.yaml ``` {{% /tab %}} @@ -163,7 +164,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1 Deploys NGINX Gateway Fabric with NGINX OSS on OpenShift. ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/openshift/deploy.yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/openshift/deploy.yaml ``` {{% /tab %}} @@ -211,13 +212,13 @@ To upgrade NGINX Gateway Fabric and get the latest features and improvements, ta - To upgrade the Gateway API resources, run: ```shell - kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.5.1" | kubectl apply -f - + kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.1" | kubectl apply -f - ``` or, if you installed the from the experimental channel: ```shell - kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.5.1" | kubectl apply -f - + kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.1" | kubectl apply -f - ``` 1. **Upgrade NGINX Gateway Fabric CRDs:** @@ -225,7 +226,7 @@ To upgrade NGINX Gateway Fabric and get the latest features and improvements, ta - To upgrade the Custom Resource Definitions (CRDs), run: ```shell - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/crds.yaml + kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/crds.yaml ``` 1. **Upgrade NGINX Gateway Fabric deployment:** @@ -300,7 +301,7 @@ Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your K ``` ```shell - kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.5.1/deploy/crds.yaml + kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/crds.yaml ``` 1. **Remove the Gateway API resources:** diff --git a/content/ngf/installation/nginx-plus-jwt.md b/content/ngf/installation/nginx-plus-jwt.md index bebfea9ea..6f456cb00 100644 --- a/content/ngf/installation/nginx-plus-jwt.md +++ b/content/ngf/installation/nginx-plus-jwt.md @@ -159,10 +159,10 @@ You also need to define the proper volume mount to mount the Secrets to the ngin - name: nginx-plus-usage-certs projected: sources: - - secret: - name: nim-ca - - secret: - name: nim-client + - secret: + name: nim-ca + - secret: + name: nim-client ``` and the following volume mounts to the `nginx` container: @@ -250,7 +250,7 @@ Replace the contents of `` with the contents of the JWT token itself. You can then pull the image: ```shell -docker pull private-registry.nginx.com/nginx-gateway-fabric/nginx-plus:1.5.1 +docker pull private-registry.nginx.com/nginx-gateway-fabric/nginx-plus:1.6.1 ``` Once you have successfully pulled the image, you can tag it as needed, then push it to a different container registry. diff --git a/content/ngf/overview/gateway-architecture.md b/content/ngf/overview/gateway-architecture.md index 9c6810e08..8cb041f4e 100644 --- a/content/ngf/overview/gateway-architecture.md +++ b/content/ngf/overview/gateway-architecture.md @@ -24,7 +24,7 @@ NGINX Gateway Fabric is an open source project that provides an implementation o For a list of supported Gateway API resources and features, see the [Gateway API Compatibility]({{< ref "/ngf/overview/gateway-api-compatibility.md" >}}) documentation. -We have more information regarding our [design principles](https://github.com/nginx/nginx-gateway-fabric/blob/v1.5.1/docs/developer/design-principles.md) in the project's GitHub repository. +We have more information regarding our [design principles](https://github.com/nginx/nginx-gateway-fabric/blob/v1.6.1/docs/developer/design-principles.md) in the project's GitHub repository. --- @@ -79,7 +79,7 @@ The following list describes the connections, preceeded by their types in parent 1. (HTTPS) - Read: _NGF_ reads the _Kubernetes API_ to get the latest versions of the resources in the cluster. - - Write: _NGF_ writes to the _Kubernetes API_ to update the handled resources' statuses and emit events. If there's more than one replica of _NGF_ and [leader election](https://github.com/nginx/nginx-gateway-fabric/tree/v1.5.1/charts/nginx-gateway-fabric#configuration) is enabled, only the _NGF_ pod that is leading will write statuses to the _Kubernetes API_. + - Write: _NGF_ writes to the _Kubernetes API_ to update the handled resources' statuses and emit events. If there's more than one replica of _NGF_ and [leader election](https://github.com/nginx/nginx-gateway-fabric/tree/v1.6.1/charts/nginx-gateway-fabric#configuration) is enabled, only the _NGF_ pod that is leading will write statuses to the _Kubernetes API_. 1. (HTTP, HTTPS) _Prometheus_ fetches the `controller-runtime` and NGINX metrics via an HTTP endpoint that _NGF_ exposes (`:9113/metrics` by default). Prometheus is **not** required by NGINX Gateway Fabric, and its endpoint can be turned off. 1. (File I/O) - Write: _NGF_ generates NGINX _configuration_ based on the cluster resources and writes them as `.conf` files to the mounted `nginx-conf` volume, located at `/etc/nginx/conf.d`. It also writes _TLS certificates_ and _keys_ from [TLS secrets](https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets) referenced in the accepted Gateway resource to the `nginx-secrets` volume at the path `/etc/nginx/secrets`. @@ -89,11 +89,11 @@ The following list describes the connections, preceeded by their types in parent 1. (Signal) To reload NGINX, _NGF_ sends the [reload signal](https://nginx.org/en/docs/control.html) to the **NGINX master**. 1. (File I/O) - Write: The _NGINX master_ writes its PID to the `nginx.pid` file stored in the `nginx-run` volume. - - Read: The _NGINX master_ reads _configuration files_ and the _TLS cert and keys_ referenced in the configuration when it starts or during a reload. These files, certificates, and keys are stored in the `nginx-conf` and `nginx-secrets` volumes that are mounted to both the `nginx-gateway` and `nginx` containers. + - Read: The _NGINX master_ reads _configuration files_ and the _TLS cert and keys_ referenced in the configuration when it starts or during a reload. These files, certificates, and keys are stored in the `nginx-conf` and `nginx-secrets` volumes that are mounted to both the `nginx-gateway` and `nginx` containers. 1. (File I/O) - Write: The _NGINX master_ writes to the auxiliary Unix sockets folder, which is located in the `/var/run/nginx` directory. - - Read: The _NGINX master_ reads the `nginx.conf` file from the `/etc/nginx` directory. This [file](https://github.com/nginx/nginx-gateway-fabric/blob/v1.5.1/internal/mode/static/nginx/conf/nginx.conf) contains the global and http configuration settings for NGINX. In addition, _NGINX master_ reads the NJS modules referenced in the configuration when it starts or during a reload. NJS modules are stored in the `/usr/lib/nginx/modules` directory. + - Read: The _NGINX master_ reads the `nginx.conf` file from the `/etc/nginx` directory. This [file](https://github.com/nginx/nginx-gateway-fabric/blob/v1.6.1/internal/mode/static/nginx/conf/nginx.conf) contains the global and http configuration settings for NGINX. In addition, _NGINX master_ reads the NJS modules referenced in the configuration when it starts or during a reload. NJS modules are stored in the `/usr/lib/nginx/modules` directory. 1. (File I/O) The _NGINX master_ sends logs to its _stdout_ and _stderr_, which are collected by the container runtime. 1. (File I/O) An _NGINX worker_ writes logs to its _stdout_ and _stderr_, which are collected by the container runtime. 1. (Signal) The _NGINX master_ controls the [lifecycle of _NGINX workers_](https://nginx.org/en/docs/control.html#reconfiguration) it creates workers with the new configuration and shutdowns workers with the old configuration. diff --git a/content/ngf/overview/nginx-plus.md b/content/ngf/overview/nginx-plus.md index 81565da74..ae4de3643 100644 --- a/content/ngf/overview/nginx-plus.md +++ b/content/ngf/overview/nginx-plus.md @@ -10,7 +10,7 @@ NGINX Gateway Fabric can use NGINX Open Source or NGINX Plus as its data plane. ## Benefits of NGINX Plus -- **Robust metrics**: A plethora of [additional Prometheus metrics](https://github.com/nginxinc/nginx-prometheus-exporter#metrics-for-nginx-plus) are available. +- **Robust metrics**: A plethora of [additional Prometheus metrics](https://github.com/nginx/nginx-prometheus-exporter#metrics-for-nginx-plus) are available. - **Live activity monitoring**: The [NGINX Plus dashboard]({{< ref "/ngf/how-to/monitoring/dashboard.md" >}}) shows real-time metrics and information about your server infrastructure. - **Dynamic upstream configuration**: NGINX Plus can dynamically reconfigure upstream servers when applications in Kubernetes scale up and down, preventing the need for an NGINX reload. - **Support**: With an NGINX Plus license, you can take advantage of full [support](https://my.f5.com/manage/s/article/K000140156/) from NGINX, Inc. diff --git a/content/ngf/reference/api.md b/content/ngf/reference/api.md index 74ea08d3c..77eafa4ac 100644 --- a/content/ngf/reference/api.md +++ b/content/ngf/reference/api.md @@ -10,6 +10,9 @@ NGINX Gateway API Reference
  • gateway.nginx.org/v1alpha1
    • +
  • +gateway.nginx.org/v1alpha2 +

    • gateway.nginx.org/v1alpha1

    @@ -683,6 +686,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.

    @@ -1825,7 +1829,8 @@ and the status of the SnippetsFilter with respect to each controller.

    (Appears on: Telemetry, -Tracing) +Tracing, +Tracing)

    SpanAttribute is a key value pair to be added to a tracing span.

    @@ -2290,6 +2295,326 @@ 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.

    + + + + +
    +

    gateway.nginx.org/v1alpha2

    +

    +

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

    +

    +Resource Types: + +

    ObservabilityPolicy +¶ +

    +

    +

    ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for +the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the +GatewayClass parametersRef.

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +apiVersion
    +string    		 + +gateway.nginx.org/v1alpha2 + +
    +kind
    +string +    		ObservabilityPolicy
    +metadata
    + + +Kubernetes meta/v1.ObjectMeta + + +    		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
    +spec
    + + +ObservabilityPolicySpec + + +    		 +

    Spec defines the desired state of the ObservabilityPolicy.

    +
    +
    + + + + + + + + + +
    +tracing
    + + +Tracing + + +    		 +(Optional) +

    Tracing allows for enabling and configuring tracing.

    +
    +targetRefs
    + + +[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference + + +    		 +

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

    +

    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.

    +
    +
    +status
    + + +sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus + + +    		 +

    Status defines the state of the ObservabilityPolicy.

    +
    +

    ObservabilityPolicySpec +¶ +

    +

    +(Appears on: +ObservabilityPolicy) +

    +

    +

    ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.

    +

    + + + + + + + + + + + + + + + + + +
    FieldDescription
    +tracing
    + + +Tracing + + +    		 +(Optional) +

    Tracing allows for enabling and configuring tracing.

    +
    +targetRefs
    + + +[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference + + +    		 +

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

    +

    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.

    +
    +

    TraceContext +(string alias)

    ¶ +

    +

    +(Appears on: +Tracing) +

    +

    +

    TraceContext specifies how to propagate traceparent/tracestate headers.

    +

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

    "extract"

    TraceContextExtract uses an existing trace context from the request, so that the identifiers +of a trace and the parent span are inherited from the incoming request.

    +

    "ignore"

    TraceContextIgnore skips context headers processing.

    +

    "inject"

    TraceContextInject adds a new context to the request, overwriting existing headers, if any.

    +

    "propagate"

    TraceContextPropagate updates the existing context (combines extract and inject).

    +
    +

    TraceStrategy +(string alias)

    ¶ +

    +

    +(Appears on: +Tracing) +

    +

    +

    TraceStrategy defines the tracing strategy.

    +

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

    "parent"

    TraceStrategyParent enables tracing and only records spans if the parent span was sampled.

    +

    "ratio"

    TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate.

    +
    +

    Tracing +¶ +

    +

    +(Appears on: +ObservabilityPolicySpec) +

    +

    +

    Tracing allows for enabling and configuring OpenTelemetry tracing.

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +strategy
    + + +TraceStrategy + + +    		 +

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

    +
    +ratio
    + +int32 + +    		 +(Optional) +

    Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100. +By default, 100% of http requests are traced. Not applicable for parent-based tracing. +If ratio is set to 0, tracing is disabled.

    +
    +context
    + + +TraceContext + + +    		 +(Optional) +

    Context specifies how to propagate traceparent/tracestate headers. +Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context

    +
    +spanName
    + +string + +    		 +(Optional) +

    SpanName defines the name of the Otel span. By default is the name of the location for a request. +If specified, applies to all locations that are created for a route. +Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’ +Examples of invalid names: some-$value, quoted-“value”-name, unescaped

    +
    +spanAttributes
    + + +[]SpanAttribute + + +    		 +(Optional) +

    SpanAttributes are custom key/value attributes that are added to each span.