diff --git a/.github/labeler.yml b/.github/labeler.yml index 569c08be8..2e8d1f8d7 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -67,7 +67,7 @@ product/nginx-one: - 'content/nginx-one/**' - 'content/includes/nginx-one/**' -product/nginxaas: +product/nginxaas-azure: - changed-files: - any-glob-to-any-file: - 'content/nginxaas-azure/**' diff --git a/.github/workflows/build-push.yml b/.github/workflows/build-push.yml index 18ffb3452..01273f449 100644 --- a/.github/workflows/build-push.yml +++ b/.github/workflows/build-push.yml @@ -80,7 +80,7 @@ jobs: permissions: read-all steps: - name: Send notification - uses: 8398a7/action-slack@1750b5085f3ec60384090fb7c52965ef822e869e # v3.18.0 + uses: 8398a7/action-slack@77eaa4f1c608a7d68b38af4e3f739dcd8cba273e # v3.19.0 with: status: custom custom_payload: | @@ -126,7 +126,7 @@ jobs: - uses: actions/checkout@v5 with: ref: ${{ github.event.workflow_run.head_branch }} - - uses: actions/setup-node@v4 + - uses: actions/setup-node@v5 with: node-version: 18 - name: Installing packages diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml index 975aad2c4..9f984f1b2 100644 --- a/.github/workflows/labeler.yml +++ b/.github/workflows/labeler.yml @@ -12,6 +12,6 @@ jobs: runs-on: ubuntu-latest steps: - name: Apply labels based on file paths - uses: actions/labeler@v5 + uses: actions/labeler@v6 with: repo-token: "${{ secrets.GITHUB_TOKEN }}" diff --git a/.github/workflows/linkchecker.yml b/.github/workflows/linkchecker.yml index 9d6709d9f..4114412f7 100644 --- a/.github/workflows/linkchecker.yml +++ b/.github/workflows/linkchecker.yml @@ -33,6 +33,11 @@ env: --ignore-url ^https://go.googlesource.com/ --ignore-url ^https://go.googlesource.com/sync --ignore-url ^https://linkerd.io/2.13/ --ignore-url ^http://www.redirectpage.com/ --ignore-url ^https://www.gnu.org/ --ignore-url ^https://insert_your_tenant_name.console.ves.volterra.io --ignore-url ^https://pkgs.nginx.com + --ignore-url ^http://backend1.example.com --ignore-url ^http://example.com --ignore-url ^https://my-nginx.example.com + --ignore-url ^https://www.nginxroute53.com --ignore-url ^http://cafe --ignore-url ^http://192.168.1.23 --ignore-url ^https://company.com + --ignore-url ^https://my-nginx-plus.example.com --ignore-url ^https://cognito-idp --ignore-url ^https:///www.okta.com + --ignore-url ^http://www.maxmind.com --ignore-url ^https://www.maxmind.com --ignore-url ^https://www.opswat.com + --ignore-url ^https://support.pingidentity.com --ignore-url ^https://docs.pingidentity.com --ignore-url ^https://demo.example.com --ignore-url ^https://\([a-zA-Z0-9-]+\).nginx.com/nginx-ingress-controller/css --ignore-url ^https://\([a-zA-Z0-9-]+\).nginx.com/nginxaas/azure/css --ignore-url ^https://\([a-zA-Z0-9-]+\).nginx.com/nginx-gateway-fabric/css @@ -56,6 +61,8 @@ jobs: - nginx-waf - nginx-management-suite - nginx-gateway-fabric + - nginx-agent + - nginx steps: # Determine and set basepath for schedule or workflow_dispatch - name: Set Basepath diff --git a/.github/workflows/notification.yml b/.github/workflows/notification.yml index fb39b1140..233e435d3 100644 --- a/.github/workflows/notification.yml +++ b/.github/workflows/notification.yml @@ -20,7 +20,7 @@ jobs: checks: read steps: - name: Retrieve Job Data - uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 continue-on-error: true id: data with: @@ -41,7 +41,7 @@ jobs: } - name: Send notification - uses: 8398a7/action-slack@1750b5085f3ec60384090fb7c52965ef822e869e # v3.18.0 + uses: 8398a7/action-slack@77eaa4f1c608a7d68b38af4e3f739dcd8cba273e # v3.19.0 with: status: custom custom_payload: | diff --git a/.github/workflows/ossf_scorecard.yml b/.github/workflows/ossf_scorecard.yml index c15bc2ab7..f01d4a00c 100644 --- a/.github/workflows/ossf_scorecard.yml +++ b/.github/workflows/ossf_scorecard.yml @@ -56,6 +56,6 @@ jobs: # Upload the results to GitHub's code scanning dashboard. - name: Upload SARIF results to code scanning - uses: github/codeql-action/upload-sarif@3c3833e0f8c1c83d449a7478aa59c036a9165498 # v3.29.5 + uses: github/codeql-action/upload-sarif@192325c86100d080feab897ff886c34abd4c83a3 # v3.29.5 with: sarif_file: results.sarif diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index a16041dc5..f10888ec3 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -18,7 +18,7 @@ jobs: pull-requests: write # for actions/stale to close stale PRs runs-on: ubuntu-latest steps: - - uses: actions/stale@v9.1.0 + - uses: actions/stale@v10.0.0 with: repo-token: ${{ secrets.GITHUB_TOKEN }} stale-issue-message: 'This issue is stale because it has been open for 90 days with no activity. Remove the stale label or add a comment to keep it open. If you do not take action, this will be closed in 10 days.' diff --git a/content/_index.md b/content/_index.md index 58cc801c2..77eb60731 100644 --- a/content/_index.md +++ b/content/_index.md @@ -1,49 +1,49 @@ --- -title: NGINX Product Documentation +title: F5 NGINX Product Documentation description: Learn how to deliver, manage, and protect your applications using F5 NGINX products. --- -## NGINX Product Documentation +# F5 NGINX Product Documentation Learn how to deliver, manage, and protect your applications using F5 NGINX products. -{{}} - {{}} +{{}} + {{}} Monitor your infrastructure, address security vulnerabilities, and assess the health of your NGINX fleet, all from a single console. {{}} - {{}} + {{}} The all-in-one load balancer, reverse proxy, web server, content cache, and API gateway. {{}} - {{}} + {{}} Track and control NGINX Open Source and NGINX Plus instances. {{}} - {{}} + {{}} Kubernetes traffic management with API gateway, identity, and observability features. {{}} - {{}} - Next generation Kubernetes connectivity using the Gateway API. + {{}} + Next-generation Kubernetes connectivity using the Gateway API. {{}} {{}} - The open source all-in-one load balancer, content cache, and web server + The open source all-in-one load balancer, content cache, and web server. {{}} {{}} - A daemon providing observability data and remote configuration for NGINX Open Source and NGINX Plus instances + A daemon providing observability data and remote configuration for NGINX Open Source and NGINX Plus instances. {{}} - {{}} + {{}} Stay compliant with your NGINX subscription licenses and see how you can use NGINX One to build secure, scalable, and high-performing applications and APIs. {{}} {{}} -{{}} - {{}} - Lightweight, high-performance, advanced protection against Layer 7 attacks on your apps and APIs +{{}} + {{}} + Lightweight, high-performance, advanced protection against Layer 7 attacks on your apps and APIs. {{}} - {{}} - Defend, adapt, and mitigate against Layer 7 denial-of-service attacks on your apps and APIs + {{}} + Defend, adapt, and mitigate against Layer 7 denial-of-service attacks on your apps and APIs. {{}} {{}} -{{}} - {{}} - Infrastructure-as-a-Service (IaaS) version of NGINX Plus for your Microsoft Azure application stack +{{}} + {{}} + Infrastructure-as-a-Service (IaaS) version of NGINX Plus for your Microsoft Azure application stack. {{}} {{}} diff --git a/content/agent/installation-upgrade/container-environments/docker-support.md b/content/agent/installation-upgrade/container-environments/docker-support.md index 1a57cafab..41b7d8773 100644 --- a/content/agent/installation-upgrade/container-environments/docker-support.md +++ b/content/agent/installation-upgrade/container-environments/docker-support.md @@ -10,7 +10,7 @@ nd-content-type: ## Overview -The NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/main/scripts/docker) that can be used to [build custom container images]({{< ref "/agent/installation-upgrade/container-environments/docker-images.md" >}}). Images are created with an NGINX Open Source or NGINX Plus instance and are available for various operating systems. +The NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/dev-v2/test/docker) that can be used to [build custom container images]({{< ref "/agent/installation-upgrade/container-environments/docker-images.md" >}}). Images are created with an NGINX Open Source or NGINX Plus instance and are available for various operating systems. See the [Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}) for a list of supported operationg systems. diff --git a/content/agent/installation-upgrade/getting-started.md b/content/agent/installation-upgrade/getting-started.md index e415d9161..4ee1483a4 100644 --- a/content/agent/installation-upgrade/getting-started.md +++ b/content/agent/installation-upgrade/getting-started.md @@ -71,7 +71,7 @@ tls: skip_verify: true ``` -For more information, see [Agent Protocol Definitions and Documentation](https://github.com/nginx/agent/tree/main/docs/proto/README.md). +For more information, see [Agent Protocol Definitions and Documentation](https://github.com/nginx/agent/blob/dev-v2/docs/proto/README.md). ### Enable the REST interface @@ -152,7 +152,7 @@ Open a web browser to view the mock control plane at [http://localhost:54790](ht - **configs/raw** - shows the actual configuration as it would live on the data plane - **metrics** - shows a buffer of metrics sent to the management plane (similar to what will be sent back in the REST API) -For more NGINX Agent use cases, refer to the [NGINX Agent SDK examples](https://github.com/nginx/agent/tree/main/sdk/examples). +For more NGINX Agent use cases, refer to the [NGINX Agent SDK examples](https://github.com/nginx/agent/tree/dev-v2/sdk/examples). ## Start and Enable Start on Boot diff --git a/content/includes/nginx-plus/oss-plus-comparison.md b/content/includes/nginx-plus/oss-plus-comparison.md new file mode 100644 index 000000000..f976335ba --- /dev/null +++ b/content/includes/nginx-plus/oss-plus-comparison.md @@ -0,0 +1,5 @@ +--- +docs: +--- + +{{< call-out "note" >}}For a detailed comparison between NGINX Plus and NGINX Open Source, refer to [Differences between NGINX Open Source and NGINX Plus](https://www.f5.com/products/get-f5/nginx-open-source-vs-nginx-one-differences-in-features) on the F5 website.{{}} \ No newline at end of file diff --git a/content/includes/nic/compatibility-tables/nic-nap.md b/content/includes/nic/compatibility-tables/nic-nap.md index 68f6b37bc..7baba8777 100644 --- a/content/includes/nic/compatibility-tables/nic-nap.md +++ b/content/includes/nic/compatibility-tables/nic-nap.md @@ -4,6 +4,7 @@ The following table shows compatibility between NGINX Ingress Controller (NIC) a | NIC Version | NAP-WAF Version | Config Manager | Enforcer | | ------------------- | --------------- | -------------- | -------- | | {{< nic-version >}} | 35+5.498 | 5.8.0 | 5.8.0 | +| 5.1.1 | 35+5.498 | 5.8.0 | 5.8.0 | | 5.0.0 | 34+5.342 | 5.6.0 | 5.6.0 | | 4.0.1 | 33+5.264 | 5.5.0 | 5.5.0 | | 3.7.2 | 32+5.1 | 5.3.0 | 5.3.0 | diff --git a/content/includes/nic/configuration/global-configuration/configmap-resource.md b/content/includes/nic/configuration/global-configuration/configmap-resource.md index ab77c60c9..b4c8ad7e3 100644 --- a/content/includes/nic/configuration/global-configuration/configmap-resource.md +++ b/content/includes/nic/configuration/global-configuration/configmap-resource.md @@ -80,6 +80,7 @@ For more information, view the [VirtualServer and VirtualServerRoute resources]( |*proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | |*proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | |*proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +|*proxy-busy-buffers-size* | Sets the value of the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. | Depends on the platform. | | |*proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | |*set-real-ip-from* | Sets the value of the [set_real_ip_from](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A | | |*real-ip-header* | Sets the value of the [real_ip_header](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | *X-Real-IP* | | @@ -198,7 +199,7 @@ If you encounter the error `error [emerg] 13#13: "zone_sync" directive is duplic {{}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|*zone-sync* | Enables zone synchronization between NGINX Ingress Controller Pods. This autogenerates a [zone_sync_server](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_server) and a headless service using the `ReplicaSet` or `DaemonSet` name. Please note that this headless service will be automatically cleaned up when uninstalling via Helm or by removing the value from the ConfigMap. The headless service will need to be manually removed if the `controller.customConfigMap` value is set via Helm or the deployment is uninstalled via Manifests. Each Ingress Controller manages its own headless service. NGINX Plus Required. | *False* | | +|*zone-sync* | Enables zone synchronization between NGINX Ingress Controller Pods. This autogenerates a [zone_sync_server](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_server) and a headless service using the `ReplicaSet`, `DaemonSet` or `StatefulSet` name. Please note that this headless service will be automatically cleaned up when uninstalling via Helm or by removing the value from the ConfigMap. The headless service will need to be manually removed if the `controller.customConfigMap` value is set via Helm or the deployment is uninstalled via Manifests. Each Ingress Controller manages its own headless service. NGINX Plus Required. | *False* | | |*zone-sync-port* | Specifies the optional port on which NGINX Ingress Controller listens for zone sync traffic. NGINX Plus & `zone-sync` Required. | *12345* | | |*zone-sync-resolver-addresses* | Configures optional addresses used in the [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync. This field takes a comma separated list of addresses. NGINX Plus & `zone-sync` Required | `kube-dns.kube-system.svc.cluster.local` | | |*zone-sync-resolver-ipv6* | Configures whether the optional [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync will look up IPv6 addresses. NGINX Plus & `zone-sync` Required | `true` | | diff --git a/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md b/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md index 1690f3a0b..11ccf7099 100644 --- a/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -108,6 +108,7 @@ The table below summarizes the available annotations. | *nginx.org/proxy-buffering* | *proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | | *nginx.org/proxy-buffers* | *proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | | *nginx.org/proxy-buffer-size* | *proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +| *nginx.org/proxy-busy-buffers-size* | *proxy-busy-buffers-size* | Sets the value of the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. | Depends on the platform. | | | *nginx.org/proxy-max-temp-file-size* | *proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | | *nginx.org/server-tokens* | *server-tokens* | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the “Server” field. | *True* | | | *nginx.org/path-regex* | N/A | Enables regular expression modifiers for Ingress path parameter. This translates to the NGINX [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive. You can specify one of these values: "case_sensitive", "case_insensitive", or "exact". The annotation is applied to the entire Ingress resource and its paths. While using Master and Minion Ingresses i.e. Mergeable Ingresses, this annotation can be specified on Minion types. The `path-regex` annotation specified on Master is ignored, and has no effect on paths defined on Minions. | N/A | [path-regex](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/path-regex) | diff --git a/content/includes/nic/configuration/security.md b/content/includes/nic/configuration/security.md index 4ade6e0cf..3d73fbf0d 100644 --- a/content/includes/nic/configuration/security.md +++ b/content/includes/nic/configuration/security.md @@ -53,10 +53,12 @@ The block below shows the code you will look for: # volumes: # - name: nginx-etc # emptyDir: {} -# - name: nginx-cache -# emptyDir: {} +# - name: nginx-cache # do not set this value in statefulset if volumeclaimtemplate is set +# emptyDir: {} # do not set this value in statefulset if volumeclaimtemplate is set # - name: nginx-lib # emptyDir: {} +# - name: nginx-lib-state +# emptyDir: {} # - name: nginx-log # emptyDir: {} . @@ -73,6 +75,8 @@ The block below shows the code you will look for: # name: nginx-cache # - mountPath: /var/lib/nginx # name: nginx-lib +# - mountPath: /var/lib/nginx/state +# name: nginx-lib-state # - mountPath: /var/log/nginx # name: nginx-log ``` diff --git a/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md b/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md index 3f447ed18..2807c0440 100644 --- a/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md @@ -371,6 +371,7 @@ tls: |``buffering`` | Enables buffering of responses from the upstream server. See the [proxy_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) directive. The default is set in the ``proxy-buffering`` ConfigMap key. | ``boolean`` | No | |``buffers`` | Configures the buffers used for reading a response from the upstream server for a single connection. | [buffers](#upstreambuffers) | No | |``buffer-size`` | Sets the size of the buffer used for reading the first part of a response received from the upstream server. See the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) directive. The default is set in the ``proxy-buffer-size`` ConfigMap key. | ``string`` | No | +|``busy-buffer-size`` | Sets the size of the buffer used for reading a response from the upstream server when the response is larger than the ``buffer-size``. See the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. The default is set in the ``proxy-busy-buffers-size`` ConfigMap key. | ``string`` | No | |``ntlm`` | Allows proxying requests with NTLM Authentication. See the [ntlm](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#ntlm) directive. In order for NTLM authentication to work, it is necessary to enable keepalive connections to upstream servers using the ``keepalive`` field. Note: this feature is supported only in NGINX Plus.| ``boolean`` | No | |``type`` |The type of the upstream. Supported values are ``http`` and ``grpc``. The default is ``http``. For gRPC, it is necessary to enable HTTP/2 in the [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#listeners) and configure TLS termination in the VirtualServer. | ``string`` | No | |``backup`` | The name of the backup service of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname). This will be used when the primary servers are unavailable. Note: The parameter cannot be used along with the ``random`` , ``hash`` or ``ip_hash`` load balancing methods. | ``string`` | No | diff --git a/content/includes/nic/installation/deploy-controller.md b/content/includes/nic/installation/deploy-controller.md index 7dcec97bd..489d80b7b 100644 --- a/content/includes/nic/installation/deploy-controller.md +++ b/content/includes/nic/installation/deploy-controller.md @@ -6,5 +6,6 @@ You have two options for deploying NGINX Ingress Controller: - **Deployment**. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller replicas. - **DaemonSet**. Choose this method if you want NGINX Ingress Controller to run on all nodes or a subset of nodes. +- **StatefulSet**. Choose this method when you need stable, persistent storage and ordered deployment/scaling for your NGINX Ingress Controller pods. Before you start, update the [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}) for the NGINX Ingress Controller container in the relevant manifest file to meet your specific requirements. diff --git a/content/includes/nic/installation/manifests/statefulset.md b/content/includes/nic/installation/manifests/statefulset.md new file mode 100644 index 000000000..9c7cac0ae --- /dev/null +++ b/content/includes/nic/installation/manifests/statefulset.md @@ -0,0 +1,25 @@ +--- +nd-docs: DOCS-000 +--- + +For additional context on managing containers using Kubernetes StatefulSets, refer to the official Kubernetes [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) documentation. + +When you deploy NGINX Ingress Controller as a StatefulSet, Kubernetes creates pods with stable network identities and persistent storage. + +- For NGINX, run: + + ```shell + kubectl apply -f deployments/stateful-set/nginx-ingress.yaml + ``` + +- For NGINX Plus, run: + + ```shell + kubectl apply -f deployments/stateful-set/nginx-plus-ingress.yaml + ``` + + Update the `nginx-plus-ingress.yaml` file to include your chosen image from the F5 Container registry or your custom container image. + +{{< call-out "note" >}} +StatefulSets include persistent volume claims for nginx cache storage via `volumeClaimTemplates`. You may need to configure a StorageClass in your cluster or modify the volumeClaimTemplates section in the manifest to match your storage requirements. Other volumes (like those needed for App Protect modules) are configured in the regular `volumes` section, not in volumeClaimTemplates. +{{< /call-out >}} diff --git a/content/ngf/_index.md b/content/ngf/_index.md index 5f7b85fde..6ea82a7c2 100644 --- a/content/ngf/_index.md +++ b/content/ngf/_index.md @@ -1,6 +1,6 @@ --- # The title is the product name -title: NGINX Gateway Fabric +title: F5 NGINX Gateway Fabric # The URL is the base of the deployed path, becoming "docs.nginx.com//" url: /nginx-gateway-fabric/ # The cascade directive applies its nested parameters down the page tree until overwritten diff --git a/content/ngf/get-started.md b/content/ngf/get-started.md index 48310cd99..4c8fd8d36 100644 --- a/content/ngf/get-started.md +++ b/content/ngf/get-started.md @@ -558,4 +558,4 @@ Request ID: 1b5c8f3a4532ea7d7510cf14ffeb27af - [Install NGINX Gateway Fabric]({{< ref "/ngf/install/" >}}), for additional ways to install NGINX Gateway Fabric - [Traffic management]({{< ref "/ngf/traffic-management/" >}}), for more in-depth traffic management configuration -- [How-to guides]({{< ref "/ngf/how-to/" >}}), for configuring your cluster \ No newline at end of file +- [How-to guides]({{< ref "/ngf/how-to/" >}}), for configuring your cluster diff --git a/content/ngf/install/ingress-to-gateway.md b/content/ngf/install/ingress-to-gateway.md new file mode 100644 index 000000000..782331973 --- /dev/null +++ b/content/ngf/install/ingress-to-gateway.md @@ -0,0 +1,51 @@ +--- +title: Migrate from NGINX Ingress Controller to NGINX Gateway Fabric +weight: 800 +toc: true +nd-content-type: how-to +nd-product: NGF +nd-docs: +--- + +This document describes how to migrate from F5 NGINX Ingress Controller to NGINX Gateway Fabric. + +If you're already using NGINX Ingress Controller and want to migrate to NGINX Gateway Fabric, you can use the [ingress2gateway](https://github.com/kubernetes-sigs/ingress2gateway) tool to automatically convert your existing Ingress resources to Gateway API resources. + +## Why migrate? + +The [Gateway API](https://gateway-api.sigs.k8s.io/) is the next-generation Kubernetes networking API that builds on the limitations of Ingress. Compared to Ingress, Gateway API provides: + +- **Role-oriented resources**: Distinct resources for infrastructure providers, cluster operators, and application developers, enabling [separation of concerns](https://gateway-api.sigs.k8s.io/concepts/security-model/#role-oriented-resources). +- **More expressive routing**: Support for [advanced traffic management](https://gateway-api.sigs.k8s.io/concepts/api-overview/#routes) such as path-based and header-based routing, traffic splitting, and TLS configuration. +- **Standardization and portability**: A Kubernetes [community standard](https://gateway-api.sigs.k8s.io/) supported by multiple vendors, ensuring consistent behavior across implementations. +- **Extensibility**: Built on Kubernetes [CRD extensibility](https://gateway-api.sigs.k8s.io/guides/migrating-from-ingress/?h=extensibility#approach-to-extensibility) to support new capabilities without breaking the core API. + +Migrating to Gateway API with NGINX Gateway Fabric helps future-proof your Kubernetes networking stack, provide a standardized API across implementations, and unlock advanced traffic management features. + +## About the ingress2gateway tool + +The ingress2gateway tool is a [Kubernetes SIG project](https://github.com/kubernetes-sigs) for converting Ingress resources to Gateway API resources. It supports multiple Ingress providers, including NGINX Ingress Controller. + +{{< call-out "important" >}} +The ingress2gateway tool is a conversion utility that translates Ingress resources to Gateway API equivalents. It is not a complete end-to-end migration solution. + +You will need to manually review the converted resources, test functionality, and make additional configuration changes as needed for your specific environment. +{{< /call-out >}} + +To convert your existing NGINX Ingress resources to Gateway API resources, first [install the ingress2gateway tool](https://github.com/kubernetes-sigs/ingress2gateway?tab=readme-ov-file#installation). + +Then run the conversion command for the NGINX provider: + +```shell +ingress2gateway print --providers=nginx --input-file= > gateway-api-resources.yaml +``` + +This tool will analyze your Ingress resources from the input file and output the equivalent Gateway API resources to a file named `gateway-api-resources.yaml`. + +Review the generated Gateway API resources in the output file and apply them to your cluster: + +```shell +kubectl apply -f gateway-api-resources.yaml +``` + +For detailed information about NGINX-specific features and conversion options, see the [NGINX provider documentation](https://github.com/kubernetes-sigs/ingress2gateway/blob/main/pkg/i2gw/providers/nginx/README.md). diff --git a/content/ngf/install/upgrade-version.md b/content/ngf/install/upgrade-version.md index b586bec06..4b2c7656c 100644 --- a/content/ngf/install/upgrade-version.md +++ b/content/ngf/install/upgrade-version.md @@ -2,8 +2,8 @@ title: Upgrade NGINX Gateway Fabric weight: 700 toc: true -type: how-to -product: NGF +nd-content-type: how-to +nd-product: NGF nd-docs: DOCS-1852 --- diff --git a/content/ngf/reference/cli-help.md b/content/ngf/reference/cli-help.md index a25a2faff..17115bfa9 100644 --- a/content/ngf/reference/cli-help.md +++ b/content/ngf/reference/cli-help.md @@ -50,6 +50,7 @@ This command runs the NGINX Gateway Fabric control plane. | _usage-report-skip-verify_ | _bool_ | Disable client verification of the NGINX Plus usage reporting server certificate. | | _usage-report-ca-secret_ | _string_ | The name of the Secret containing the NGINX Instance Manager CA certificate. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway) | | _usage-report-client-ssl-secret_ | _string_ | The name of the Secret containing the client certificate and key for authenticating with NGINX Instance Manager. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway) | +| _usage-report-enforce-initial-report_ | _bool_ | Enables or disables the 180-day grace period for sending the initial usage report.certificate. | | _snippets-filters_ | _bool_ | Enable SnippetsFilters feature. SnippetsFilters allow inserting NGINX configuration into the generated NGINX config for HTTPRoute and GRPCRoute resources. | | _nginx-scc_ | _string_ | The name of the SecurityContextConstraints to be used with the NGINX data plane Pods. Only applicable in OpenShift. | | _nginx-one-dataplane-key-secret_ | _string_ | The name of the secret which holds the dataplane key that is required to authenticate with the NGINX One Console. Secret must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway). | diff --git a/content/nginx-one/api/nginx_configuration.md b/content/nginx-one/api/nginx_configuration.md new file mode 100644 index 000000000..166210be3 --- /dev/null +++ b/content/nginx-one/api/nginx_configuration.md @@ -0,0 +1,161 @@ +--- +description: '' +nd-docs: DOCS-000 +title: Manage NGINX configurations with API requests +toc: true +weight: 100 +type: +- how-to +--- + +In this guide, we'll show you how to use API requests to update NGINX Configurations for Instances, Config Sync Groups, or Staged Configs in the F5 NGINX One Console. + +## Before you begin + +Before you begin, make sure you can properly authenticate your API requests with either an API Token or API Certificate, following the instructions in the [Authentication]({{}}) guide. To ensure you have registered or created your NGINX Instance, Config Sync Group, or Staged Config in the F5 NGINX One Console, follow the instructions in the [Manage your NGINX instances]({{}}) guide. + +{{< call-out "note" >}} +The workflows for managing NGINX Configs for Instances, Config Sync Groups, and Staged Configs in the F5 NGINX One Console are quite similar. This guide focuses on the steps for updating NGINX Configs for Instances. If you're working with Config Sync Groups, you'll follow a similar process but will need to update the API endpoints appropriately. +{{< /call-out>}} + +## Get the current NGINX configuration + +You can retrieve the current NGINX configuration for an Instance, Config Sync Group, or Staged Config using a `GET` request. This is useful for making updates based on the existing configuration. + +Use the following `curl` command to retrieve the current NGINX configuration for a specific Instance. Replace ``, ``, ``, and `` with your actual values. + + ```shell + curl -X GET "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ + -H "Authorization: APIToken " -o current_config.json + ``` + + - ``: Your tenant name for organization plans. + - ``: The namespace your Instance belongs to. + - ``: The object_id of the NGINX Instance you want to retrieve the NGINX configuration for. + - ``: Your API Token. + +{{< call-out "note" >}} +To update the NGINX configuration for a Config Sync Group or Staged Config, replace `instances` with `config-sync-groups` or `staged-configs` and use the object_id of the Config Sync Group or Staged Config in the URL. +{{< /call-out>}} + + The response will include the current NGINX configuration in JSON format. This response is saved to a file (with a name like `current_config.json`) for editing. + +You can modify the NGINX configuration using either `PUT` or `PATCH` requests. The `PUT` method replaces the entire NGINX configuration, while the `PATCH` method allows you to update specific fields without affecting the rest of the configuration. + +## How to base64 encode a file for JSON request + +When updating the NGINX Config, file `contents` must be base64 encoded. You can use the following command to base64 encode a file: + +```shell +base64 -w 0 -i +``` + +This command reads the file at `` and outputs its base64 encoded content in a single line (due to the `-w 0` option). You can then copy this encoded string and include it in your JSON request body. On some systems the `-w` option may not be available, in which case you can use: + +```shell +base64 -i | tr -d '\n' +``` + +## Update the NGINX configuration for an Instance using `PUT` + +When using the `PUT` method, ensure that your request body includes all necessary contents, as it will overwrite the existing configuration. +The following example demonstrates how to update the NGINX configuration for a specific Instance using `PUT`. Replace ``, ``, ``, and `` with your actual values. The request body should contain the complete NGINX configuration in JSON format. + + ```shell + curl -X PUT "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ + -H "Authorization : APIToken " \ + -H "Content-Type: application/json" \ + -d @updated_config.json + ``` + + - ``: Your tenant name for organization plans. + - ``: The namespace your Instance belongs to. + - ``: The object_id of the NGINX Instance you want to update the NGINX configuration for. + - ``: Your API Token. + +## Update the NGINX configuration for an Instance using `PATCH` + +When using the `PATCH` method, you only need to include the files you want to update in your request body. +The following example demonstrates how to update the NGINX configuration for a specific Instance using `PATCH`. Replace ``, ``, ``, and `` with your actual values. The request body should contain only the fields you want to update in JSON format. + ```shell + curl -X PATCH "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ + -H "Authorization : APIToken " \ + -H "Content-Type: application/json" \ + -d @partial_update_config.json + ``` + + - ``: Your tenant name for organization plans. + - ``: The namespace your Instance belongs to. + - ``: The object_id of the NGINX Instance you want to update the NGINX configuration for. + - ``: Your API Token. + +With `PATCH`, you can update specific parts of the NGINX Instance configuration without needing to resend the entire configuration. The following file `contents` disposition is observed: + - Leave out file `contents` to remove the file from the NGINX Config. + - Include file `contents` to add or update the file in the NGINX Config. File `contents` must be base64 encoded. File `contents` can be an empty string to create an empty file. + - `config_version` should be included to ensure you're updating the correct version of the configuration. You can get the current `config_version` from the response of the `GET` request. + +For example, to update only the `/etc/nginx/nginx.conf` file in the NGINX Config, your `partial_update_config.json` might look like this: + ```json + { + "conf_path": "/etc/nginx/nginx.conf", + "config_version": "", + "configs": [ + { + "name": "/etc/nginx", + "files": [ + { + "name": "nginx.conf", + "contents": "" + } + ] + } + ] + } + ``` + +To remove a file, omit the `contents` field for that file in your `PATCH` request body, your `partial_update_config.json` might look like this to remove `/etc/nginx/conf.d/default.conf` from the NGINX Instance configuration: + ```json + { + "conf_path": "/etc/nginx/nginx.conf", + "config_version": "", + "configs": [ + { + "name": "/etc/nginx/conf.d", + "files": [ + { + "name": "default.conf" + } + ] + } + ] + } + ``` + +## Set up multiple updates with `PATCH` + +You can make multiple updates can be made in a single `PATCH` request. For example, to update `/etc/nginx/nginx.conf` and remove `/etc/nginx/conf.d/default.conf`, your `partial_update_config.json` might look like this: + ```json + { + "conf_path": "/etc/nginx/nginx.conf", + "config_version": "", + "configs": [ + { + "name": "/etc/nginx/conf.d", + "files": [ + { + "name": "default.conf" + } + ] + }, + { + "name": "/etc/nginx", + "files": [ + { + "name": "nginx.conf", + "contents": "" + } + ] + } + ] + } + ``` \ No newline at end of file diff --git a/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md index f40929adb..920294db3 100644 --- a/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md @@ -333,3 +333,4 @@ Monitor the **Config Sync Status** column. It can help you ensure that your conf - [Create and manage data plane keys]({{< ref "/nginx-one/connect-instances/create-manage-data-plane-keys.md" >}}) - [Add an NGINX instance]({{< ref "/nginx-one/connect-instances/add-instance.md" >}}) +- [Updating the NGINX configuration with an NGINX One Console Config Sync Group push fails (My F5 Knowledge article)](https://my.f5.com/manage/s/article/K000154659) diff --git a/content/nginx-one/rbac/roles.md b/content/nginx-one/rbac/roles.md index 521bd70c5..d2ccefc2f 100644 --- a/content/nginx-one/rbac/roles.md +++ b/content/nginx-one/rbac/roles.md @@ -13,7 +13,7 @@ We provide three default **[roles](https://docs.cloud.f5.com/docs-v2/administrat ### Admin -The Admin role, identified as `f5xc-nginx-one-standard-admin`, provides full read and write access to all endpoints and features within the NGINX One Console. +The Admin role, identified as `f5xc-nginx-one-admin`, provides full read and write access to all endpoints and features within the NGINX One Console. It also supports Role-based access control for related XC services. ### User diff --git a/content/nginx/_index.md b/content/nginx/_index.md index ef928d074..9d8ddb58f 100644 --- a/content/nginx/_index.md +++ b/content/nginx/_index.md @@ -12,6 +12,8 @@ nd-product: NGINX Plus --- Request your [free 30‑day trial](https://www.nginx.com/free-trial-request) today. +{{< include "/nginx-plus/oss-plus-comparison.md" >}} + ## About [//]: # "These are Markdown comments to guide you through document structure. Remove them as you go, as well as any unnecessary sections." [//]: # "Use underscores for _italics_, and double asterisks for **bold**." diff --git a/content/nginx/admin-guide/basic-functionality/managing-configuration-files.md b/content/nginx/admin-guide/basic-functionality/managing-configuration-files.md index 4b41b5b71..1032e68d1 100644 --- a/content/nginx/admin-guide/basic-functionality/managing-configuration-files.md +++ b/content/nginx/admin-guide/basic-functionality/managing-configuration-files.md @@ -9,9 +9,9 @@ type: - how-to --- -NGINX and NGINX Plus are similar to other services in using a text‑based configuration file with a precise format. By default the file is named **nginx.conf** and for NGINX Plus is placed in the `**/etc/nginx**` directory. +Similar to other services, NGINX and NGINX Plus use a text‑based configuration file with a precise format. By default the file is named **nginx.conf** and for NGINX Plus is placed in the `/etc/nginx` directory. -For NGINX Open Source, the location depends on the package system used to install NGINX and the operating system. It is typically one of `**/usr/local/nginx/conf**`, `**/etc/nginx**`, or `**/usr/local/etc/nginx**`. +For NGINX Open Source, the location depends on the package system used to install NGINX and the operating system. It is typically one of `/usr/local/nginx/conf`, `/etc/nginx`, or `/usr/local/etc/nginx`. ## Directives The configuration file consists of _directives_ and their parameters. Simple (single‑line) directives end with a semicolon ( `;` ). Other directives act as “containers” which group together related directives. Containers are enclosed in curly braces ( `{}` ) and are often referred to as _blocks_. Here are some examples of simple directives. diff --git a/content/nginx/fips-compliance-nginx-plus.md b/content/nginx/fips-compliance-nginx-plus.md index eb11c2b91..d61966731 100644 --- a/content/nginx/fips-compliance-nginx-plus.md +++ b/content/nginx/fips-compliance-nginx-plus.md @@ -8,100 +8,249 @@ type: - concept --- -When used with a FIPS 140-2 validated build of OpenSSL operating in FIPS mode, NGINX Plus is compliant with the requirements of FIPS 140-2 (Level 1) with respect to the decryption and encryption of SSL/TLS‑encrypted network traffic. +## What is FIPS -## Introduction +The Federal Information Processing Standard (FIPS), issued by the [U.S. National Institute of Standards and Technology](https://www.nist.gov/) (NIST), defines mandatory security requirements for cryptographic modules used in federal IT systems. [FIPS 140-2](https://csrc.nist.gov/pubs/fips/140-2/upd2/final), and its successor [FIPS 140-3](https://csrc.nist.gov/pubs/fips/140-3/final), establish strict standards to protect sensitive information, including government communications and citizen data. -[FIPS 140-2](https://csrc.nist.gov/publications/detail/fips/140/2/final) is a United States Federal Standard that relates to the integrity and security of cryptographic modules. FIPS 140-2 Level 1 relates specifically to software cryptographic modules and makes stipulations about the cryptographic algorithms that may be used and the self‑tests that must be conducted to verify their integrity. +## Why FIPS-140 matters -Several operating system vendors have obtained FIPS 140-2 Level 1 validation for the OpenSSL Cryptographic Module shipped with their respective operating systems: +FIPS 140 is a mandatory cryptographic standard in the United States and Canada for federal agencies, their contractors, and many regulated industries. -- [Canonical Ltd.: Ubuntu 18.04 OpenSSL Cryptographic Module](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4540) -- [Oracle Corporation: Oracle OpenSSL FIPS Provider](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4506) -- [Red Hat, Inc.: Red Hat Enterprise Linux 7 NSS Cryptographic Module](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4498) -- [SUSE, LLC: SUSE Linux Enterprise Server Kernel Crypto API Cryptographic Module](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4508) +Non-compliance can result to contract loss, restricted project access, fines, or, in severe cases, data breaches compromising personal information or national security. -NGINX Plus uses the OpenSSL cryptographic module exclusively for all operations relating to the decryption and encryption of SSL/TLS and HTTP/2 traffic. +Some industries such as finance, healthcare, energy, also adopt FIPS to enhance data protection and operational security. -When NGINX Plus is executed on an operating system where a FIPS‑validated OpenSSL cryptographic module is present and FIPS mode is enabled, NGINX Plus is compliant with FIPS 140-2 with respect to the decryption and encryption of SSL/TLS and HTTP/2 traffic. +### FIPS compliance in U.S. -## Definition of Terms +Currently, both FIPS 140-2 and FIPS 140-3 certifications are accepted. However, FIPS 140-2 is being phased out as part of the [FIPS 140-3 transition plan](https://csrc.nist.gov/projects/fips-140-3-transition-effort). After September 22, 2026, only FIPS 140-3 certifications will be recognized. Organizations are encouraged to migrate to FIPS 140-3 to meet updated cryptographic security requirements. -This statement uses the following terms: +{{}} +| **Program/Regulation/Industry** | **FIPS 140-2/140-3 Requirement** | **Current Status** | +|---------------------------------|----------------------------------|---------------------------------------------------------------------| +| CJIS | 140-2 or 140-3 | FIPS required for systems protecting criminal justice data. | +| CMMC | 140-2 or 140-3 | FIPS required for Levels 2 and 3 compliance. | +| Common Criteria | 140-2 or 140-3 | Evaluations reference both FIPS versions for cryptographic security. | +| Critical Infrastructure | 140-2 or 140-3 | Utilities and systems accept both versions depending on deployments. | +| Department of Veterans Affairs| 140-2 or 140-3 | Both versions used for securing sensitive health and personal data. | +| DFARS | 140-2 or 140-3 | Cryptographic modules for CUI must be FIPS compliant. | +| DoDIN APL | 140-2 or 140-3 | Approved IT products must include FIPS validation. | +| FAA | 140-2 transitioning to 140-3 | 140-2 modules common in existing systems; new systems use 140-3. | +| FERPA | 140-2 or 140-3 | Federal-funded educational systems align with 140-2 or 140-3. | +| FedRAMP | 140-2 or 140-3 | FIPS required for encryption; both versions accepted. | +| FISMA | 140-2 or 140-3 | Both versions accepted; agencies adopt existing 140-2 modules. | +| HIPAA | 140-2 or 140-3 | FIPS ensures encryption for ePHI; both versions are valid. | +| HITECH | 140-2 or 140-3 | FIPS use aligns with encryption best practices for ePHI. | +| Intelligence Community | 140-2 transitioning to 140-3 | Current systems mostly use 140-2; newer systems adopt 140-3. | +| Military & Tactical Systems | 140-2 transitioning to 140-3 | 140-2 used widely; transitioning to 140-3 certifications for future tools.| +| NSA CSfC | 140-2 transitioning to 140-3 | NSA accepts 140-2 but prefers newer certifications under 140-3. | +| Nuclear Regulatory Commission | 140-2 or 140-3 | Cryptography for nuclear systems relies on both versions. | +| PCI DSS | 140-2 or 140-3 | Both versions recommended but not mandatory. | +| State and Local Gov Programs | 140-2 or 140-3 | FIPS required for federal grant-funded security systems. | +| TSA | 140-2 or 140-3 | Best practice for cryptographic protection; both versions accepted. | +{{< /bootstrap-table >}} -- **Cryptographic module**: The OpenSSL software, comprised of libraries of FIPS‑validated algorithms that can be used by other applications. +### FIPS compliance in other countries -- **Cryptographic boundary**: The operational functions that use FIPS‑validated algorithms. For NGINX Plus, the cryptographic boundary includes all functionality that is implemented by the [http_ssl](http://nginx.org/en/docs/http/ngx_http_ssl_module.html), [http_v2](http://nginx.org/en/docs/http/ngx_http_v2_module.html), [stream_ssl](http://nginx.org/en/docs/stream/ngx_stream_ssl_module.html), [mail_ssl](http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html), and [http_auth_jwt](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html) modules. These modules implement SSL and TLS operations for inbound and outbound connections which use HTTP, HTTP/2, TCP, and mail protocols. +Although FIPS 140 is primarily a North American government cryptographic standard, it is widely recognized as a global benchmark for cryptographic security. Numerous countries outside North America align their cryptographic requirements with FIPS, especially in regulated sectors such as finance, defense, healthcare, and critical infrastructure. -- **NGINX Plus**: The NGINX Plus software application developed by NGINX, Inc. and delivered in binary format from NGINX servers. +{{}} +| Country/Region | FIPS Use | +|----------------|-----------------------------------------------------------------------------| +| Australia | Referenced for government, defense, and cryptography systems. | +| Canada | Mandatory for federal and sensitive systems. | +| Denmark | Referenced in finance, healthcare, and NATO communications. | +| Estonia | Adopted for e-governance and critical systems. | +| Finland | Relied on for defense and NATO communications. | +| France | Relied on for defense and secure systems. | +| Germany | Relied on for defense, critical infrastructure, and NATO communications. | +| Israel | Trusted in defense, government, and financial systems. | +| Italy | Relied on for defense and financial cryptography. | +| Japan | Referenced in government and financial cryptographic practices. | +| Netherlands | Referenced in finance, healthcare, and NATO communications. | +| New Zealand | Referenced for government and national cryptography. | +| Poland | Relied on for secure government and NATO communications. | +| Spain | Referenced in NATO communications and critical systems. | +| Sweden | Relied on for defense and secure NATO communications. | +| UAE | Trusted in finance, energy, and interoperability with the U.S. cryptography.| +| United Kingdom | Referenced for defense, health, and procurement standards. | +| United States | Mandatory for federal government systems and contractors. | +{{< /bootstrap-table >}} -- **FIPS mode**: When the operating system is configured to run in FIPS mode, the OpenSSL cryptographic module operates in a mode that has been validated to be in compliance with FIPS 140-2 Level 2. Most operating systems do not run in FIPS mode by default, so explicit configuration is necessary to enable FIPS mode. +## FIPS compliant vs FIPS validated -- **FIPS validated**: A component of the OpenSSL cryptographic module (the OpenSSL FIPS Object Module) is formally validated by an authorized certification laboratory. The validation holds if the module is built from source with no modifications to the source or build process. The implementation of FIPS mode that is present in operating system vendors’ distributions of OpenSSL contains this validated module. +FIPS validation is a formal multistep process that certifies cryptographic modules through testing under the [Cryptographic Module Validation Program](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/cmvp-flow) (CMVP). The process is managed by the [NIST](https://csrc.nist.gov/) and requires accredited third-party laboratories to evaluate the cryptographic module. Once a module passes validation, it is officially recognized as FIPS-validated (FIPS-certified). + +FIPS compliance indicates that a system or a module claims to meet the FIPS requirements, however, it has not been officially tested or certified under the CMVP program. + +## FIPS compliance with NGINX Plus + +NGINX Plus is **FIPS 140-2 Level 1** and **FIPS 140-3 Level 1 compliant**, provided that the operating system and the OpenSSL library are operating in FIPS mode. + +NGINX Plus relies exclusively on the operating system’s FIPS-validated OpenSSL library for all SSL/TLS, HTTP/2, and HTTP/3 encryption and decryption operations. + +## FIPS compliance with NGINX Open Source + +While NGINX Plus is tested to work on FIPS-enabled operating systems in FIPS mode, NGINX Open Source is not verified for such environments, especially when third-party builds or modules implementing custom cryptographic functions are used. + +Compiling NGINX Open Source for FIPS mode may also require additional OS-level dependencies beyond its core requirements, potentially introducing unintended risks. Organizations should consult their security and compliance teams to ensure their configurations meet FIPS requirements. + +## FIPS validation of operating systems + +Several operating system vendors have obtained FIPS 140-2 Level 1 and 140-3 Level 1 validation for the OpenSSL Cryptographic Module included with their respective operating systems: + +- RedHat: [RedHat FIPS Certifications](https://access.redhat.com/compliance/fips) +- Ubuntu: [Overview of FIPS-certified modules](https://documentation.ubuntu.com/security/docs/compliance/fips/fips-overview/) +- Oracle: [Oracle FIPS Certifications](https://www.oracle.com/corporate/security-practices/assurance/development/external-security-evaluations/fips/certifications/) +- SUSE: [SUSE FIPS 140-3 cryptographic certificates](https://www.suse.com/c/suse-has-received-first-fips-140-3-cryptographic-certificates/) +- AWS: [FIPS 140-3 Compliance](https://aws.amazon.com/compliance/fips/) +- Amazon Linux: [Achieving FIPS 140-3 validation](https://aws.amazon.com/blogs/compute/amazon-linux-2023-achieves-fips-140-3-validation/) + +You also can verify whether your operating system or cryptographic module is FIPS-validated using the [NIST database search tool](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/validated-modules/search). + +## Verification of correct operation of NGINX Plus -- **FIPS compliant**: NGINX Plus is compliant with FIPS 140-2 Level 1 within the cryptographic boundary when used with a FIPS‑validated OpenSSL cryptographic module on an operating system running in FIPS mode. +The following process describes how to deploy NGINX Plus in a FIPS‑compliant environment and verify that the FIPS operations are functioning correctly. It involves three basic steps: -## Verification of Correct Operation of NGINX Plus +- [Verify](#os-fips-check) if the operating system is running in FIPS mode. If not, [configure](#os-fips-setup) it to enable FIPS mode. -The following process describes how to deploy NGINX Plus in a FIPS‑compliant fashion and then verify that the FIPS operations are correctly performed. +- [Verify](#openssl-fips-check) that the OpenSSL library is operating in FIPS mode. -The process uses Red Hat Enterprise Linux (RHEL) version 7.4 as an example, and can be adapted for other Linux operating systems that can be configured in FIPS mode. +- Run basic checks for [OpenSSL](#openssl-fips-check) and [NGINX Plus](#nginx-plus-fips-check) to confirm deployment in FIPS mode. -### Step 1: Configure the Operating System to Use FIPS Mode +The process uses Red Hat Enterprise Linux (RHEL) release 9.6 as an example and can be adapted for other Linux operating systems that can be configured in FIPS mode. -For the purposes of the following demonstration, we installed and configured a RHEL 7.4 server. The [Red Hat FIPS documentation](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/chap-federal_standards_and_regulations#sec-Enabling-FIPS-Mode) explains how to switch the operating system between FIPS mode and non‑FIPS mode by editing the boot options and restarting the system. +### Step 1: Configure the operating system to use FIPS mode {#os-fips-setup} -For instructions for enabling FIPS mode on other FIPS‑compliant Linux operating systems, see the operating system documentation (for example, [Oracle Linux](https://docs.oracle.com/cd/E52668_01/E54670/html/ol7-fips-enable.html), [Ubuntu](https://ubuntu.com/security/certifications/docs/fips-faq)). +For the purposes of the following demonstration, we installed and configured a RHEL 9.6 server. The [Red Hat FIPS documentation](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/chap-federal_standards_and_regulations#sec-Enabling-FIPS-Mode) explains how to switch the operating system between FIPS mode and non‑FIPS mode by editing the boot options and restarting the system. -### Step 2: Verify the Operating System and OpenSSL Are in FIPS Mode +For instructions for enabling FIPS mode on other FIPS‑compliant Linux operating systems, see the operating system documentation, for example: + +- RHEL 9: [Switching to FIPS mode](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/security_hardening/switching-rhel-to-fips-mode_security-hardening) + +- Ubuntu: [Switching to FIPS mode](https://documentation.ubuntu.com/security/docs/compliance/fips/how-to-install-ubuntu-with-fips/) + +- SLES: [How to enable FIPS](https://www.suse.com/support/kb/doc/?id=000019432) + +- Oracle Linux 9: [Configuring FIPS mode](https://docs.oracle.com/en/operating-systems/oracle-linux/9/security/configuring_fips_mode.html#configuring-fips-mode) + +- Amazon Linux 2023: [Enabling FIPS mode](https://docs.aws.amazon.com/linux/al2023/ug/fips-mode.html) + +- Amazon Linux 2: [Enabling FIPS mode](https://docs.aws.amazon.com/linux/al2/ug/fips-mode.html) + +- AlmaLinux: [FIPS Validation for AlmaLinux](https://almalinux.org/blog/2023-09-19-fips-validation-for-almalinux/) + +### Step 2: Verify the operating system is in FIPS mode {#os-fips-check} You can verify that the operating system is in FIPS mode and that the version of OpenSSL provided by the operating system vendor is FIPS‑compliant by using the following tests. -**Check operating system flags**: When the operating system is in FIPS mode, ```crypto.fips_enabled``` is ```1```; otherwise, it is ```0```: +**Check operating system flags**: When the operating system is in FIPS mode, `crypto.fips_enabled` kernlel flag is `1`; otherwise, it is `0`: ```shell -sudo sysctl –a | grep fips +sudo sysctl -a | grep fips +``` + +The output of the command shows that FIPS is enabled at the kernel level: +```none crypto.fips_enabled = 1 +crypto.fips_name = Red Hat Enterprise Linux 9 - Kernel Cryptographic API +crypto.fips_version = 5.14.0-570.39.1.el9_6.aarch64 +``` + +Check kernel logs for FIPS algorithm registration: +```shell +journalctl -k -o cat -g alg: ``` -**Determine whether OpenSSL can perform SHA1 hashes**: This test verifies the correct operation of OpenSSL. The SHA1 hash algorithm is permitted in all modes, so failure of this command indicates that the OpenSSL implementation does not work properly: +The output of the command verifies the status of algorithm self-tests and whether certain algorithms are registered, passed FIPS self-tests, or are disabled due to FIPS mode being active: + +```none +alg: self-tests for pkcs1pad(rsa-generic,sha512) (pkcs1pad(rsa,sha512)) passed +alg: self-tests for pkcs1pad(rsa-generic,sha256) (pkcs1pad(rsa,sha256)) passed +alg: self-tests for cbc-aes-ce (cbc(aes)) passed +alg: self-tests for jitterentropy_rng (jitterentropy_rng) passed +alg: poly1305 (poly1305-neon) is disabled due to FIPS +alg: xchacha12 (xchacha12-neon) is disabled due to FIPS +alg: xchacha20 (xchacha20-neon) is disabled due to FIPS +``` + +Beyond kernel-level verification, you can ensure that the whole operating system environment is configured for FIPS compliance: +```shell +sudo fips-mode-setup --check +``` +The output of the command shows that FIPS is running: +```none +FIPS mode is enabled. +``` + +### Step 3: Verify the OpenSSL is in FIPS mode {#openssl-fips-check} + +**Determine the OpenSSL FIPS Provider is active**: This test verifies the correct version of OpenSSL and that the OpenSSL FIPS Provider is active: + +```shell +openssl list -providers | grep -A3 fips +``` +The output of the command shows the FIPS provider status: +```none + fips + name: Red Hat Enterprise Linux 9 - OpenSSL FIPS Provider + version: 3.0.7-395c1a240fbfffd8 + status: active +``` + +**Determine whether OpenSSL can perform SHA1 hashes**: This test verifies the correct operation of OpenSSL. The SHA-1 hash algorithm, while considered weak, is still permitted in FIPS mode as it is included in FIPS-approved standards for certain legacy use cases. Failure of this command indicates that the OpenSSL implementation is not working properly: ```shell openssl sha1 /dev/null +``` +The result of the command, showing the SHA1 checksum of `/dev/null`: + +```none SHA1(/dev/null)= da39a3ee5e6b4b0d3255bfef95601890afd80709 ``` -**Determine whether OpenSSL can perform MD5 hashes**: This test verifies that OpenSSL is running in FIPS mode. MD5 is not a permitted hash algorithm in FIPS mode, so an attempt to use it fails: +**Determine whether OpenSSL allows MD5 hashes**: This test verifies that OpenSSL is running in FIPS mode. MD5 is not a permitted hash algorithm in FIPS mode, so an attempt to use it fails: ```shell openssl md5 /dev/null -Error setting digest md5 -140647163811744:error:060800A3:digital envelope routines:EVP_DigestInit _ex:disabled for fips:digest.c:251: +``` +The result of the command: + +```none +Error setting digest +200458BAFFFF0000:error:0308010C:digital envelope routines:inner_evp_generic_fetch:unsupported:crypto/evp/evp_fetch.c:355:Global default library context, Algorithm (MD5 : 95), Properties () +200458BAFFFF0000:error:03000086:digital envelope routines:evp_md_init_internal:initialization error:crypto/evp/digest.c:272: ``` If OpenSSL is not running in FIPS mode, the MD5 hash functions normally: ```shell openssl md5 /dev/null +``` +The result of the command, showing the MD5 checksum of `/dev/null`: + +```none MD5(/dev/null)= d41d8cd98f00b204e9800998ecf8427e ``` -### Step 3: Install NGINX Plus on the Operating System +### Step 4: Install NGINX Plus on the operating system {#nginx-plus-instll} -Follow the [F5 NGINX documentation](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) to install NGINX Plus on the host operating system, either directly from the [NGINX Plus repository](https://account.f5.com/myf5), or by downloading the **nginx-plus** package (**rpm** or **deb** package) onto another system and manually installing it on the host operating system. +Follow the [F5 NGINX Plus Installation guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) to install NGINX Plus on the host operating system, either directly from the [NGINX Plus repository](https://account.f5.com/myf5), or by downloading the **nginx-plus** package (**rpm** or **deb** package) onto another system and manually installing it on the host operating system. -**Verify that NGINX Plus is correctly installed**: Run the following command to confirm that NGINX Plus is installed and is using the expected OpenSSL cryptographic module: +**Verify that NGINX Plus is correctly installed**: Run the following command to confirm that NGINX Plus is installed and is using the expected OpenSSL cryptographic module: ```shell nginx -V -nginx version: nginx/1.15.2 (nginx-plus-r16) -built by gcc 4.8.5 20150623 (Red Hat 4.8.5-16) (GCC) -built with OpenSSL 1.0.2k-fips 26 Jan 2017 ``` +Sample output from the command: -Observe that the version number of the OpenSSL library includes the `–fips` suffix. This indicates that the library is FIPS‑validated, but does not confirm that it is running in FIPS mode. +```shell +nginx version: nginx/1.29.0 (nginx-plus-r35) +built by gcc 11.5.0 20240719 (Red Hat 11.5.0-5) (GCC) +built with OpenSSL 3.2.2 4 Jun 2024 +``` +Note that OpenSSL 1.0.x might include the `–fips` suffix to indicate that the library was linked with a FIPS-validated module, but it did not confirm that the library was operating in FIPS mode. Starting with OpenSSL 3.0, the concept of Providers was introduced, allowing explicit verification of FIPS validation by listing providers with the `openssl list -providers | grep fips` command. -**Configure NGINX Plus to serve a simple SSL/TLS‑protected website**: Add the following simple configuration to NGINX Plus: +**Configure NGINX Plus to serve a simple SSL/TLS‑protected website**: Add the following simple configuration to NGINX Plus: ```nginx server { @@ -110,8 +259,6 @@ server { ssl_certificate /etc/nginx/ssl/test.crt; ssl_certificate_key /etc/nginx/ssl/test.key; - ssl_protocols TLSv1.2 TLSv1.3; - location / { root /usr/share/nginx/html; index index.html index.htm; @@ -122,7 +269,7 @@ server { If necessary, you can generate a self‑signed certificate for test purposes: ```shell -mkdir -p /etc/nginx/ssl +mkdir -p /etc/nginx/ssl && \ openssl req -newkey rsa:2048 -nodes -keyout /etc/nginx/ssl/test.key -x509 -days 365 -out /etc/nginx/ssl/test.crt ``` @@ -134,17 +281,26 @@ Verify that you can access the website using HTTPS from a remote host. Connect t Use `openssl s_client` for this test because it unambiguously confirms which SSL/TLS cipher was negotiated in the connection. After some debugging information (including the cipher selected), the body of the default “Welcome to nginx!” greeting page is displayed. -### Step 4: Verify Compliance with FIPS 140-2 +### Step 5: Verify compliance with FIPS {#nginx-plus-fips-check} + +FIPS 140-2 and 140-3 disallows the use of some cryptographic algorithms, including the Camellia block cipher. In addition to FIPS 140-2, FIPS 140-3 disallows the use of several ciphers and algorithms that were once allowed or still allowed under FIPS 140-2. -FIPS 140-2 disallows the use of some cryptographic algorithms, including the Camellia block cipher. We can test compliance with FIPS 140-2 by issuing SSL/TLS requests with known ciphers on another (non-FIPS-mode) server: +You can test compliance with FIPS 140-2 / 140-3 by issuing SSL/TLS requests with known ciphers on another (non-FIPS-mode) server: #### RC4-MD5 +`RC4-MD5` is considered insecure and deprecated across all modern cryptographic standards. It is disallowed and disabled by default in FIPS-compliant OpenSSL, and TLS 1.2 and 1.3. The SSL handshake always fails. + ```shell (echo "GET /" ; sleep 1) | openssl s_client -connect :443 -cipher RC4-MD5 ``` -This cipher is insecure and is disabled by NGINX Plus by default. The SSL handshake always fails. +For FIPS compliance, alternative cipher suites can be used such as: + +- `TLS_RSA_WITH_AES_128_GCM_SHA256` +- `TLS_RSA_WITH_AES_256_GCM_SHA384` +- `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` +- `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` #### CAMELLIA-SHA @@ -152,45 +308,220 @@ This cipher is insecure and is disabled by NGINX Plus by default. The SSL hands (echo "GET /" ; sleep 1) | openssl s_client -connect :443 -cipher CAMELLIA256-SHA ``` -This cipher is considered secure but is not permitted by the FIPS standard. The SSL handshake fails if the target system is compliant with FIPS 140-2, and succeeds otherwise. - -Note that if you attempt to issue the client request on a host running in FIPS mode, it fails because the OpenSSL client cannot use this cipher. +This cipher is considered secure but is not permitted by the FIPS standard. The SSL handshake fails if the target system is compliant with FIPS 140-2 /140-3, and succeeds otherwise. #### AES256-SHA +The cipher is permitted under FIPS 140-2 as it combines AES encryption with SHA-1. However, under FIPS 140-3, SHA-1 is explicitly disallowed due to its vulnerabilities, such as susceptibility to collision attacks. As a result, the SSL handshake fails under FIPS 140-3 and succeeds under FIPS 140-2: + ```shell (echo "GET /" ; sleep 1) | openssl s_client -connect :443 -cipher AES256-SHA ``` -This cipher is considered secure by NGINX Plus and is permitted by FIPS 140-2. The SSL handshake succeeds. +For FIPS 140-3 compliance, alternative cipher suites that leverage SHA-2 or SHA-3 for hashing can be used: -## Which Ciphers Are Disabled in FIPS Mode? +- AES-GCM-Based Cipher Suites (TLS 1.2): + - `TLS_RSA_WITH_AES_256_GCM_SHA384` + - `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` -The FIPS 140-2 standard only permits a [subset of the typical SSL and TLS ciphers](https://csrc.nist.gov/csrc/media/publications/fips/140/2/final/documents/fips1402annexa.pdf). +- ChaCha20-Based Cipher Suites (TLS 1.2 or 1.3): + - `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256` -In the following test, the ciphers presented by NGINX Plus are surveyed using the [Qualys SSL server test](https://www.ssllabs.com/ssltest). In its default configuration, with the `ssl_ciphers HIGH:!aNULL:!MD5` directive, NGINX Plus presents the following ciphers to SSL/TLS clients: +- TLS 1.3 Cipher Suites: + - `TLS_AES_256_GCM_SHA384` + - `TLS_AES_128_GCM_SHA256` + - `TLS_CHACHA20_POLY1305_SHA256` -Ciphers presented by NGINX Plus to clients when in non-FIPS mode +#### 3DES -When FIPS mode is enabled on the host operating system, the two ciphers that use the Camellia block cipher (`TLS_RSA_WITH_CAMELLIA_128_CBC_SHA` and `TLS_RSA_WITH_CAMELLIA_256_CBC_SHA`) are removed: +The `3DES` (Triple DES) cipher is allowed under FIPS 140-2, but disallowed under FIPS 140-3. NIST deprecated its use [starting January 1, 2024](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar2.pdf) due to its reduced security strength (112 bits) and vulnerability to brute-force attacks. -Ciphers presented by NGINX Plus to clients when in FIPS mode +As a result, the SSL handshake always fails in FIPS-3 compliant environment: -When you configure NGINX Plus with the `ssl_ciphers ALL` directive, NGINX Plus presents all the relevant ciphers available in the OpenSSL cryptographic module to the client. FIPS mode disables the following ciphers: +```shell +(echo "GET /" ; sleep 1) | openssl s_client -connect :443 -cipher DES-CBC3 +``` +For FIPS 140-3 compliance, AES-Based or ChaCha20-Based cipher suites can be used: + +- `TLS_RSA_WITH_AES_128_GCM_SHA256` +- `TLS_RSA_WITH_AES_256_GCM_SHA384` +- `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` +- `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` +- `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256` + +#### DH and DSA + +Under FIPS 140-2, Diffie-Hellman (DH) and Digital Signature Algorithm (DSA) were permitted with a minimum key size of 1024 bits. However, under FIPS 140-3, the minimum key size for both DH and DSA has been increased to 2048 bits. + +For example, the `TLS_DH_RSA_WITH_AES_128_CBC_SHA` algorithm is FIPS 140-2 compliant, but not FIPS 140-3 compliant due to its use of DH with a key size of less than 2048 bits, CBC mode encryption, and SHA-1 hashing: + +```shell +(echo "GET /" ; sleep 1) | openssl s_client -connect :443 -cipher TLS_DH_RSA_WITH_AES_128_CBC_SHA +``` + +The `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` algorithm is FIPS 140-3 compliant as it uses Elliptic Curve Diffie-Hellman Ephemeral (ECDHE), AES-GCM for encryption, and SHA-256 for hashing: + +```shell +(echo "GET /" ; sleep 1) | openssl s_client -connect :443 -cipher TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 +``` + +## Ciphers disabled in FIPS Mode + +The FIPS 140-2 standard only permits a [subset of the typical SSL and TLS ciphers](https://csrc.nist.gov/csrc/media/publications/fips/140/2/final/documents/fips1402annexa.pdf), while FIPS 140-3 [extends this requirements](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.140-3.pdf) to enforce stricter cryptographic algorithms. + +In the following test, the ciphers presented by NGINX Plus are surveyed using the `nmap` utility (installed separately). In its default configuration, with the [`ssl_ciphers HIGH:!aNULL:!MD5`](nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers) directive, NGINX Plus presents the following ciphers to SSL/TLS clients: + +```shell +nmap --script ssl-enum-ciphers -p 443 +``` + +The output of the command for NGINX Plus running on Red Hat Enterprise Linux 9 without FIPS enabled: + +```shell +PORT STATE SERVICE +443/tcp open https +| ssl-enum-ciphers: +| TLSv1.2: +| ciphers: +| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (secp256r1) - A +| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (secp256r1) - A +| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (secp256r1) - A +| TLS_RSA_WITH_AES_128_CBC_SHA (rsa 2048) - A +| TLS_RSA_WITH_AES_128_CBC_SHA256 (rsa 2048) - A +| TLS_RSA_WITH_AES_128_CCM (rsa 2048) - A +| TLS_RSA_WITH_AES_128_GCM_SHA256 (rsa 2048) - A +| TLS_RSA_WITH_AES_256_CBC_SHA (rsa 2048) - A +| TLS_RSA_WITH_AES_256_CBC_SHA256 (rsa 2048) - A +| TLS_RSA_WITH_AES_256_CCM (rsa 2048) - A +| TLS_RSA_WITH_AES_256_GCM_SHA384 (rsa 2048) - A +| TLS_RSA_WITH_ARIA_128_GCM_SHA256 (rsa 2048) - A +| TLS_RSA_WITH_ARIA_256_GCM_SHA384 (rsa 2048) - A +| TLS_RSA_WITH_CAMELLIA_128_CBC_SHA (rsa 2048) - A +| TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 (rsa 2048) - A +| TLS_RSA_WITH_CAMELLIA_256_CBC_SHA (rsa 2048) - A +| TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 (rsa 2048) - A +| compressors: +| NULL +| cipher preference: client +| TLSv1.3: +| ciphers: +| TLS_AKE_WITH_AES_128_CCM_SHA256 (ecdh_x25519) - A +| TLS_AKE_WITH_AES_128_GCM_SHA256 (ecdh_x25519) - A +| TLS_AKE_WITH_AES_256_GCM_SHA384 (ecdh_x25519) - A +| TLS_AKE_WITH_CHACHA20_POLY1305_SHA256 (ecdh_x25519) - A +| cipher preference: client +|_ least strength: A +``` + +When FIPS 140-3 mode is enabled, NGINX Plus presents the following ciphers to SSL/TLS clients: + +```shell +PORT STATE SERVICE +443/tcp open https +| ssl-enum-ciphers: +| TLSv1.2: +| ciphers: +| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (secp256r1) - A +| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (secp256r1) - A +| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (secp256r1) - A +| TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (secp256r1) - A +| compressors: +| NULL +| cipher preference: client +| TLSv1.3: +| ciphers: +| TLS_AKE_WITH_AES_128_CCM_SHA256 (secp256r1) - A +| TLS_AKE_WITH_AES_128_GCM_SHA256 (secp256r1) - A +| TLS_AKE_WITH_AES_256_GCM_SHA384 (secp256r1) - A +| cipher preference: client +|_ least strength: A +``` -- `TLS_ECDH_anon_WITH_RC4_128_SHA` -- `TLS_ECDHE_RSA_WITH_RC4_128_SHA` -- `TLS_RSA_WITH_CAMELLIA_128_CBC_SHA` -- `TLS_RSA_WITH_CAMELLIA_256_CBC_SHA` -- `TLS_RSA_WITH_IDEA_CBC_SHA` -- `TLS_RSA_WITH_RC4_128_MD5` -- `TLS_RSA_WITH_RC4_128_SHA` -- `TLS_RSA_WITH_SEED_CBC_SHA` +Based on the results above, the following ciphers are disallowed under FIPS 140-3 compliance: + +- Camellia-Based Ciphers: FIPS compliance requires cryptographic algorithms to be validated by NIST, and Camellia is not NIST-approved despite being recognized by ISO/IEC standards. + + - `TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256` + - `TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384` + - `TLS_RSA_WITH_CAMELLIA_128_CBC_SHA` + - `TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256` + - `TLS_RSA_WITH_CAMELLIA_256_CBC_SHA` + - `TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256` + +- ARIA-Based Ciphers: similar to Camellia, ARIA is not a NIST-approved algorithm and is therefore excluded from FIPS compliance. + + - `TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256` + - `TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384` + - `TLS_RSA_WITH_ARIA_128_GCM_SHA256` + - `TLS_RSA_WITH_ARIA_256_GCM_SHA384` + +- RSA Key Exchange Ciphers: static RSA key exchange lacks Forward Secrecy, allowing decryption of past traffic if the private key is compromised, thus disallowed in FIPS mode. + + - `TLS_RSA_WITH_AES_128_CBC_SHA` + - `TLS_RSA_WITH_AES_128_CBC_SHA256` + - `TLS_RSA_WITH_AES_128_GCM_SHA256` + - `TLS_RSA_WITH_AES_256_CBC_SHA` + - `TLS_RSA_WITH_AES_256_CBC_SHA256` + - `TLS_RSA_WITH_AES_256_GCM_SHA384` + +- CBC Mode Ciphers (Non-AEAD: CBC is vulnerable to padding oracle attacks (e.g., POODLE, Lucky13), making it insecure. FIPS 140-3 prioritizes AEAD modes like AES-GCM and AES-CCM. + + - `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA` + - `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` + - `TLS_RSA_WITH_AES_128_CBC_SHA` + - `TLS_RSA_WITH_AES_128_CBC_SHA256` + - `TLS_RSA_WITH_AES_256_CBC_SHA` + - `TLS_RSA_WITH_AES_256_CBC_SHA256` + +- ChaCha20-Poly1305: it is not a NIST-approved algorithm and is excluded from FIPS compliance. FIPS exclusively permits algorithms such as `AES-GCM` and `AES-CCM`. + + - `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256` + +- AES-CCM Variants: + + - `TLS_RSA_WITH_AES_128_CCM` + - `TLS_RSA_WITH_AES_256_CCM` + + +You can also use the [Qualys SSL server test](https://www.ssllabs.com/ssltest) to verify the ciphers presented by NGINX Plus to SSL/TLS clients. ## Conclusion -NGINX Plus can be used to decrypt and encrypt SSL/TLS‑encrypted network traffic in deployments that require FIPS 140-2 Level 1 compliance. +NGINX Plus can be used to decrypt and encrypt SSL/TLS‑encrypted network traffic in deployments that require FIPS 140-2 Level 1 or FIPS 140-3 Level 1 compliance. + +The process described above may be used to verify that NGINX Plus is operating in conformance with the FIPS 140-2 Level 1 and FIPS 140-3 Level 1 standards. + +## Definition of terms + +- **Cryptographic module**: The OpenSSL software, comprised of libraries of FIPS‑validated algorithms that can be used by other applications. + +- **Cryptographic boundary**: The operational functions that use FIPS‑validated algorithms. For NGINX Plus, the cryptographic boundary includes all functionality that is implemented by the [`http_auth_jwt`](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html), [`http_ssl`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html), [`http_v2`](https://nginx.org/en/docs/http/ngx_http_v2_module.html), [`http_v3`](https://nginx.org/en/docs/http/ngx_http_v3_module.html), [`mail_ssl`](https://nginx.org/en/docs/mail/ngx_mail_ssl_module.html), and [`stream_ssl`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html) modules. These modules implement SSL and TLS operations for inbound and outbound connections which use HTTP, HTTP/2, HTTP/3, TCP, and mail protocols. + +- **NGINX Plus**: The NGINX Plus software application developed by F5, Inc. and delivered in binary format from F5 servers. + +- **FIPS mode**: When the operating system is configured to run in FIPS mode, the OpenSSL cryptographic module operates in a mode that has been validated to be in compliance with FIPS 140-2 Level 1 or FIPS 140-3 Level 1. Most operating systems do not run in FIPS mode by default, so explicit configuration is necessary to enable FIPS mode. + +- **FIPS validated**: A component of the OpenSSL cryptographic module (the OpenSSL FIPS Object Module) is formally validated by an authorized certification laboratory. The validation holds if the module is built from source with no modifications to the source or build process. The implementation of FIPS mode that is present in operating system vendors’ distributions of OpenSSL contains this validated module. + +- **FIPS compliant**: NGINX Plus is compliant with FIPS 140-2 Level 1 and FIPS 140-3 Level 1 within the cryptographic boundary when used with a FIPS‑validated OpenSSL cryptographic module on an operating system running in FIPS mode. + +## See also: + +[FIPS 140-3 Standard in the PDF format](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.140-3.pdf) + +[FIPS compliance with NGINX Plus and Red Hat Enterprise Linux](https://www.f5.com/pdf/technology-alliances/fips-compliance-made-simple-with-f5-and-red-hat-one-pager.pdf) + +[F5 NGINX Plus running on Red Hat Enterprise Linux is now FIPS 140-3 compliant](https://www.redhat.com/en/blog/f5-nginx-plus-running-red-hat-enterprise-linux-now-fips-140-3-compliant) -The process described above may be used to verify that NGINX Plus is operating in conformance with the FIPS 140-2 Level 1 standard. diff --git a/content/nginxaas-azure/_index.md b/content/nginxaas-azure/_index.md index 7d786a0ea..56a138de0 100644 --- a/content/nginxaas-azure/_index.md +++ b/content/nginxaas-azure/_index.md @@ -1,5 +1,5 @@ --- -title: NGINXaaS for Azure +title: F5 NGINXaaS for Azure nd-subtitle: Infrastructure-as-a-Service (IaaS) version of NGINX Plus for your Microsoft Azure application stack url: /nginxaas/azure/ nd-landing-page: true @@ -12,7 +12,7 @@ nd-product: N4Azure ## About -NGINX as a Service for Azure is an IaaS offering that is tightly integrated +F5 NGINXaaS for Azure is an IaaS offering that is tightly integrated into Microsoft Azure public cloud and its ecosystem, making applications fast, efficient, and reliable with full lifecycle management of advanced NGINX traffic services. @@ -20,7 +20,7 @@ and reliable with full lifecycle management of advanced NGINX traffic services. {{}} {{}} - Deploy NGINX as a Service for Azure using the Azure portal, Azure CLI, or Terraform + Deploy NGINXaaS for Azure using the Azure portal, Azure CLI, or Terraform {{}} {{}} Step-by-step guides for several common use cases, including scaling guidance, security controls, and more @@ -50,7 +50,7 @@ and reliable with full lifecycle management of advanced NGINX traffic services. {{}} {{}} - Learn about the differences between NGINX as a Service for Azure and NGINX Plus + Learn about the differences between NGINXaaS for Azure and NGINX Plus {{}} {{}} See the latest updates: New features, improvements, and bug fixes diff --git a/content/nginxaas-azure/app-protect/configure-waf.md b/content/nginxaas-azure/app-protect/configure-waf.md index 3a436654f..ba924183e 100644 --- a/content/nginxaas-azure/app-protect/configure-waf.md +++ b/content/nginxaas-azure/app-protect/configure-waf.md @@ -90,14 +90,14 @@ For more information on these policies refer the NGINX App Protect [configuratio The following table shows the path to the precompiled policy file that needs to be used with the `app_protect_policy_file` directive: -{{}} +{{< table >}} | Policy | Enforcement Mode | Path | |---------------------------- | ---------------------------- | -------------------------------------------- | | Default | Strict | /etc/app_protect/conf/NginxDefaultPolicy.json | | Default | Transparent | /etc/app_protect/conf/NginxDefaultPolicy_transparent.json | | Strict | Strict | /etc/app_protect/conf/NginxStrictPolicy.json | | Strict | Transparent | /etc/app_protect/conf/NginxStrictPolicy_transparent.json | -{{}} +{{< /table >}} To view the contents of the available security policies, navigate to the azure portal and select the **Security Policies** tab in the App Protect section. @@ -116,10 +116,10 @@ To create a custom security policy in the Azure Portal: In the policy editor: -- Enter the **Name** (as a filename), **File path**, your policy content, and then select **Save**. +- Enter the policy **Name**, **File path**, your policy content, and then select **Save**. - - Be sure to append the filename with ".json". - - The **File path** is automatically generated with "/etc/app_protect/conf/" as the default policies folder. + - The **File path** must start with the prefix "/etc/app_protect/conf/". + - The **File path** extension must be ".json". After your policy has been saved, you can then reference it in your NGINX configuration. For more information on policy configuration and syntax, refer to the NGINX App Protect [configuration guide](https://docs.nginx.com/nginx-app-protect-waf/v5/configuration-guide/configuration/). diff --git a/content/nginxaas-azure/app-protect/disable-waf.md b/content/nginxaas-azure/app-protect/disable-waf.md index 3efc32e04..a9cc3ba83 100644 --- a/content/nginxaas-azure/app-protect/disable-waf.md +++ b/content/nginxaas-azure/app-protect/disable-waf.md @@ -8,7 +8,7 @@ type: --- ## Overview -This guide explains how to disable F5 NGINX App Protect WAF on an NGINX as a Service for Azure (NGINXaaS) deployment. +This guide explains how to disable F5 NGINX App Protect WAF on an NGINXaaS for Azure (NGINXaaS) deployment. ## Before you start You must remove the WAF directives from your NGINX config file before attempting to disable WAF. diff --git a/content/nginxaas-azure/app-protect/enable-logging.md b/content/nginxaas-azure/app-protect/enable-logging.md index 04b171b85..3adf7cfe4 100644 --- a/content/nginxaas-azure/app-protect/enable-logging.md +++ b/content/nginxaas-azure/app-protect/enable-logging.md @@ -9,7 +9,7 @@ type: ## Overview -F5 NGINX as a Service for Azure (NGINXaaS) supports exporting NGINX App Protect logs to an Azure Storage account or to a Log Analytics workspace. +F5 NGINXaaS for Azure (NGINXaaS) supports exporting NGINX App Protect logs to an Azure Storage account or to a Log Analytics workspace. ## Setting up operational logs @@ -81,7 +81,7 @@ NGINXaaS for Azure ships with several pre-compiled log configuration bundles. Mo The following table shows the path to the log configuration file that needs to be used with the app_protect_security_log directive: - {{}} + {{< table >}} | Profile | Path | |---------------------------- | -------------------------------------------- | | log_default | /etc/app_protect/conf/log_default.json | @@ -91,7 +91,7 @@ The following table shows the path to the log configuration file that needs to b | log_grpc_all | /etc/app_protect/conf/log_grpc_all.json | | log_grpc_illegal | /etc/app_protect/conf/log_grpc_illegal.json | | log_grpc_blocked | /etc/app_protect/conf/log_grpc_blocked.json | - {{}} + {{< /table >}} To view the contents of the available log configuration, navigate to the azure portal and select the Log Configurations tab in the App Protect section. @@ -124,7 +124,7 @@ app_protect_security_log "/etc/app_protect/conf/log_all.json" /var/log/app_prote If the diagnostic setting destination details included a Logs Analytics workspace, logs appear in the "NGXSecurityLogs" table with the following columns: -{{}} +{{< table >}} | **Attribute** | **Description** | |-----------------------------|-----------------| | **Location** | The location of the NGINXaaS resource.| @@ -133,7 +133,7 @@ If the diagnostic setting destination details included a Logs Analytics workspac | **Tag** | The tag with which NGINX security logs are generated if syslog-based log configuration is used. | | **Facility** | The syslog facility that generates the NGINX security logs if syslog-based log configuration is being used. | | **Severity** | The syslog severity with which NGINX security logs were generated if syslog-based log configuration is used. | -{{}} +{{< /table >}} To view the raw data in the NGINX security log, run the following KQL query: ``` diff --git a/content/nginxaas-azure/app-protect/enable-waf.md b/content/nginxaas-azure/app-protect/enable-waf.md index 9335f2a36..6396dd850 100644 --- a/content/nginxaas-azure/app-protect/enable-waf.md +++ b/content/nginxaas-azure/app-protect/enable-waf.md @@ -9,7 +9,7 @@ type: ## Overview -This guide explains how to enable F5 NGINX App Protect WAF on a F5 NGINX as a Service for Azure (NGINXaaS) deployment. [F5 NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect-waf/v5) provides web application firewall (WAF) security protection for your web applications, including OWASP Top 10; response inspection; Meta characters check; HTTP protocol compliance; evasion techniques; disallowed file types; JSON & XML well-formedness; sensitive parameters & Data Guard. +This guide explains how to enable F5 NGINX App Protect WAF on a F5 NGINXaaS for Azure (NGINXaaS) deployment. [F5 NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect-waf/v5) provides web application firewall (WAF) security protection for your web applications, including OWASP Top 10; response inspection; Meta characters check; HTTP protocol compliance; evasion techniques; disallowed file types; JSON & XML well-formedness; sensitive parameters & Data Guard. ## Before you start - NGINX App Protect WAF can only be enabled on NGINXaaS for Azure deployments with the **Standard v2** [plan]({{< ref "/nginxaas-azure/billing/overview.md" >}}) diff --git a/content/nginxaas-azure/billing/overview.md b/content/nginxaas-azure/billing/overview.md index 42c426eae..0301452fb 100644 --- a/content/nginxaas-azure/billing/overview.md +++ b/content/nginxaas-azure/billing/overview.md @@ -14,7 +14,7 @@ NGINXaaS for Azure is deployed into your Azure subscription. Your NGINXaaS deplo NGINXaaS for Azure is billed monthly based on hourly consumption. -F5 NGINX as a Service for Azure (NGINXaaS) provides two pricing plans. +F5 NGINXaaS for Azure (NGINXaaS) provides two pricing plans. ### Standard V2 plan diff --git a/content/nginxaas-azure/changelog-archive/changelog-2022.md b/content/nginxaas-azure/changelog-archive/changelog-2022.md index a0e8d10fa..9f94ac27e 100644 --- a/content/nginxaas-azure/changelog-archive/changelog-2022.md +++ b/content/nginxaas-azure/changelog-archive/changelog-2022.md @@ -5,7 +5,7 @@ toc: true url: /nginxaas/azure/changelog-archive/changelog-2022/ --- -Learn about the updates, new features, and resolved bugs in F5 NGINX as a Service for Azure during the year 2022. +Learn about the updates, new features, and resolved bugs in F5 NGINXaaS for Azure during the year 2022. To see the latest changes, visit the [Changelog]({{< ref "/nginxaas-azure/changelog" >}}) page. diff --git a/content/nginxaas-azure/changelog-archive/changelog-2023.md b/content/nginxaas-azure/changelog-archive/changelog-2023.md index 6f3eddf78..840a77bd5 100644 --- a/content/nginxaas-azure/changelog-archive/changelog-2023.md +++ b/content/nginxaas-azure/changelog-archive/changelog-2023.md @@ -5,7 +5,7 @@ toc: true url: /nginxaas/azure/changelog-archive/changelog-2023/ --- -Learn about the updates, new features, and resolved bugs in F5 NGINX as a Service for Azure during the year 2023. +Learn about the updates, new features, and resolved bugs in F5 NGINXaaS for Azure during the year 2023. To see the latest changes, visit the [Changelog]({{< ref "/nginxaas-azure/changelog" >}}) page. @@ -294,7 +294,7 @@ To see a list of currently active issues, visit the [Known issues]({{< ref "/ngi - {{% icon-feature %}} **NGINXaaS is generally available** - We are pleased to announce the general availability of NGINX as a Service (NGINXaaS), a first-party-like experience as a service co-developed by Microsoft and NGINX and tightly integrated into the [Azure](https://azure.microsoft.com/) ecosystem. + We are pleased to announce the general availability of NGINXaaS for Azure, a first-party-like experience as a service co-developed by Microsoft and NGINX and tightly integrated into the [Azure](https://azure.microsoft.com/) ecosystem. NGINXaaS, powered by [NGINX Plus](https://www.nginx.com/products/nginx/), is a fully managed service that removes the burden of deploying your own NGINX Plus cluster, installing libraries, upgrading, and managing it. diff --git a/content/nginxaas-azure/changelog-archive/changelog-2024.md b/content/nginxaas-azure/changelog-archive/changelog-2024.md index 2894053f8..eaf886bed 100644 --- a/content/nginxaas-azure/changelog-archive/changelog-2024.md +++ b/content/nginxaas-azure/changelog-archive/changelog-2024.md @@ -5,7 +5,7 @@ toc: true url: /nginxaas/azure/changelog-archive/changelog-2024/ --- -Learn about the updates, new features, and resolved bugs in F5 NGINX as a Service for Azure during the year 2024. +Learn about the updates, new features, and resolved bugs in F5 NGINXaaS for Azure during the year 2024. To see the latest changes, visit the [Changelog]({{< ref "/nginxaas-azure/changelog" >}}) page. diff --git a/content/nginxaas-azure/changelog.md b/content/nginxaas-azure/changelog.md index e9470ef8e..0d3ee4efe 100644 --- a/content/nginxaas-azure/changelog.md +++ b/content/nginxaas-azure/changelog.md @@ -7,7 +7,7 @@ url: /nginxaas/azure/changelog/ --- -Learn about the latest updates, new features, and resolved bugs in F5 NGINX as a Service for Azure. +Learn about the latest updates, new features, and resolved bugs in F5 NGINXaaS for Azure. To see a list of currently active issues, visit the [Known issues]({{< ref "/nginxaas-azure/known-issues.md" >}}) page. diff --git a/content/nginxaas-azure/client-tools/cli.md b/content/nginxaas-azure/client-tools/cli.md index 1731e17ec..d82e51705 100644 --- a/content/nginxaas-azure/client-tools/cli.md +++ b/content/nginxaas-azure/client-tools/cli.md @@ -9,7 +9,7 @@ type: - task --- -F5 NGINX as a Service for Azure (NGINXaaS) deployments can be managed using the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/). This document outlines how to install the CLI tool including the NGINX extension. +F5 NGINXaaS for Azure (NGINXaaS) deployments can be managed using the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/). This document outlines how to install the CLI tool including the NGINX extension. ## Prerequisites @@ -20,7 +20,7 @@ F5 NGINX as a Service for Azure (NGINXaaS) deployments can be managed using the In order to install and manage your NGINXaaaS deployments using the Azure CLI, you will need to install the `nginx` extension: -```bash +```shell az extension add --name nginx --allow-preview true ``` @@ -28,6 +28,6 @@ az extension add --name nginx --allow-preview true Ensure you are running the latest version of the `nginx` CLI extension to take advantage of the latest capabilities available on your NGINXaaS deployments: -```bash +```shell az extension update --name nginx --allow-preview true ``` diff --git a/content/nginxaas-azure/client-tools/sdk.md b/content/nginxaas-azure/client-tools/sdk.md index 55e41e647..6c8d65428 100644 --- a/content/nginxaas-azure/client-tools/sdk.md +++ b/content/nginxaas-azure/client-tools/sdk.md @@ -10,7 +10,7 @@ type: - task --- -F5 NGINX as a Service for Azure (NGINXaaS) deployments can be managed using the multi-language SDK. This document outlines common workflows using the Python SDK. You can find example code to manage NGINXaaS deployments and related objects in the NGINXaaS GitHub repository, [NGINXaaS Snippets](https://github.com/nginxinc/nginxaas-for-azure-snippets/tree/main/sdk/python/). +F5 NGINXaaS for Azure (NGINXaaS) deployments can be managed using the multi-language SDK. This document outlines common workflows using the Python SDK. You can find example code to manage NGINXaaS deployments and related objects in the NGINXaaS GitHub repository, [NGINXaaS Snippets](https://github.com/nginxinc/nginxaas-for-azure-snippets/tree/main/sdk/python/). ## Prerequisites diff --git a/content/nginxaas-azure/client-tools/templates.md b/content/nginxaas-azure/client-tools/templates.md index aae949498..f4f0a1623 100644 --- a/content/nginxaas-azure/client-tools/templates.md +++ b/content/nginxaas-azure/client-tools/templates.md @@ -10,7 +10,7 @@ type: - task --- -F5 NGINX as a Service for Azure (NGINXaaS) deployments can be managed using the ARM API or the Azure CLI with ARM template deployments using JSON or Bicep formats. These deployments can be made locally or in a continuous integration pipeline. This document outlines common workflows using the ARM API. You can find example code to manage NGINXaaS deployments and related objects in the NGINXaaS GitHub repository, [NGINXaaS Snippets](https://github.com/nginxinc/nginxaas-for-azure-snippets). +F5 NGINXaaS for Azure (NGINXaaS) deployments can be managed using the ARM API or the Azure CLI with ARM template deployments using JSON or Bicep formats. These deployments can be made locally or in a continuous integration pipeline. This document outlines common workflows using the ARM API. You can find example code to manage NGINXaaS deployments and related objects in the NGINXaaS GitHub repository, [NGINXaaS Snippets](https://github.com/nginxinc/nginxaas-for-azure-snippets). ## Prerequisites diff --git a/content/nginxaas-azure/client-tools/terraform.md b/content/nginxaas-azure/client-tools/terraform.md index e9baec4f1..08631dfa8 100644 --- a/content/nginxaas-azure/client-tools/terraform.md +++ b/content/nginxaas-azure/client-tools/terraform.md @@ -10,7 +10,7 @@ type: - task --- -F5 NGINX as a Service for Azure (NGINXaaS) deployments can be managed using Terraform. This document outlines common Terraform workflows for NGINXaaS. +F5 NGINXaaS for Azure (NGINXaaS) deployments can be managed using Terraform. This document outlines common Terraform workflows for NGINXaaS. ## Prerequisites diff --git a/content/nginxaas-azure/disaster-recovery.md b/content/nginxaas-azure/disaster-recovery.md index 0d0a150ae..eb378a3b2 100644 --- a/content/nginxaas-azure/disaster-recovery.md +++ b/content/nginxaas-azure/disaster-recovery.md @@ -8,7 +8,7 @@ type: --- -This guide describes how to configure disaster recovery (DR) for F5 NGINX as a Service for Azure deployments in separate (ideally [paired](https://learn.microsoft.com/en-us/azure/reliability/regions-paired)) Azure regions, ensuring upstream access remains available even if the primary NGINXaaS deployment in a region fails. The deployment architecture ensures users can access backend application servers (upstreams) continuously from an alternative region if the primary NGINXaaS deployment becomes unavailable. The solution leverages Terraform, Azure Traffic Manager, Azure Virtual Network (VNet) peering, and unique subnets to support failover. +This guide describes how to configure disaster recovery (DR) for F5 NGINXaaS for Azure deployments in separate (ideally [paired](https://learn.microsoft.com/en-us/azure/reliability/regions-paired)) Azure regions, ensuring upstream access remains available even if the primary NGINXaaS deployment in a region fails. The deployment architecture ensures users can access backend application servers (upstreams) continuously from an alternative region if the primary NGINXaaS deployment becomes unavailable. The solution leverages Terraform, Azure Traffic Manager, Azure Virtual Network (VNet) peering, and unique subnets to support failover. --- @@ -42,10 +42,10 @@ This guide describes how to configure disaster recovery (DR) for F5 NGINX as a S ### Step 1: Terrraform setup -To get started, please review the [Terraform prerequisites]({{< ref "/nginxaas-azure/getting-started/create-deployment/deploy-terraform.md#prerequisites" >}}) for NGINX as a Service for Azure. +To get started, please review the [Terraform prerequisites]({{< ref "/nginxaas-azure/getting-started/create-deployment/deploy-terraform.md#prerequisites" >}}) for NGINXaaS for Azure. The following steps outline Terraform resources required to set up the disaster recovery topology; these resources can be placed in a `main.tf` file, variables used by these resources can go into `variables.tf`, and outputs you need to collect can be defined in `outputs.tf`. The directory structure looks as follows: -```bash +```shell $ tree . |-- main.tf @@ -55,7 +55,7 @@ $ tree To execute the Terraform code, `cd` into the directory with these files and run: -```bash +```shell terraform init terraform plan terraform apply --auto-approve diff --git a/content/nginxaas-azure/get-help.md b/content/nginxaas-azure/get-help.md index bd8e22aa1..63e29842a 100644 --- a/content/nginxaas-azure/get-help.md +++ b/content/nginxaas-azure/get-help.md @@ -10,7 +10,7 @@ type: ## Contact NGINX support -To contact support about F5 NGINX as a Service for Azure (NGINXaaS): +To contact support about F5 NGINXaaS for Azure (NGINXaaS): 1. Go to your NGINXaaS deployment. @@ -51,7 +51,7 @@ If your deployment is configured to use NGINX App Protect WAF, please collect th To provide or update the preferred support contact email: -1. Go to your NGINX as a Service (NGINXaaS) for Azure deployment. +1. Go to your NGINXaaS for Azure deployment. 2. Select **New Support request** in the left menu. diff --git a/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-cli.md b/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-cli.md index 3182aec32..2952ba883 100644 --- a/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-cli.md +++ b/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-cli.md @@ -9,7 +9,7 @@ type: ## Overview -The Azure CLI has an extension to be used for management of F5 NGINX as a Service for Azure (NGINXaaS) deployments whether that be locally or in continuous integration pipelines. This document links you to information around basic NGINXaaS extension usage. +The Azure CLI has an extension to be used for management of F5 NGINXaaS for Azure (NGINXaaS) deployments whether that be locally or in continuous integration pipelines. This document links you to information around basic NGINXaaS extension usage. ## Prerequisites @@ -19,7 +19,7 @@ The Azure CLI has an extension to be used for management of F5 NGINX as a Servic To create an NGINXaaS for Azure resource use the `az nginx deployment create` command: -```bash +```shell az nginx deployment create --deployment-name --resource-group [--auto-upgrade-profile] @@ -39,7 +39,7 @@ az nginx deployment create --deployment-name - Create a deployment with public IP: - ```bash + ```shell az nginx deployment create --name myDeployment --resource-group \ myResourceGroup --location eastus2 --sku name="standardv2_Monthly" \ --network-profile front-end-ip-configuration="{public-ip-addresses:[{id:/subscriptions/mySubscriptionID/resourceGroups/myResourceGroup/providers/Microsoft.Network/publicIPAddresses/myPublicIP}]}" \ @@ -48,7 +48,7 @@ az nginx deployment create --deployment-name - Create a deployment with private IP: - ```bash + ```shell az nginx deployment create --name myDeployment --resource-group \ myResourceGroup --location eastus2 --sku \ name="standardv2_Monthly" --network-profile \ @@ -56,7 +56,7 @@ az nginx deployment create --deployment-name network-interface-configuration="{subnet-id:/subscriptions/mySubscriptionID/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVNet/subnets/mySubnet}" ``` - ```bash + ```shell az nginx deployment create --name myDeployment --resource-group \ myResourceGroup --location eastus2 --sku \ name="standardv2_Monthly" --network-profile \ @@ -66,7 +66,7 @@ az nginx deployment create --deployment-name - Create a dual-stack (IPv4 + IPv6) NGINXaaS deployment with public IPs: - ```bash + ```shell az nginx deployment create --name myDeployment --resource-group \ myResourceGroup --location eastus2 --sku name="standardv2_Monthly" \ --network-profile front-end-ip-configuration="{public-ip-addresses:[{id:/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/publicIPAddresses/pubIPv4},{id:/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/publicIPAddresses/pubIPv6}]}" \ @@ -75,7 +75,7 @@ az nginx deployment create --deployment-name - Create a dual-stack (IPv4 + IPv6) NGINXaaS deployment with private IPs: - ```bash + ```shell az nginx deployment create --name myDeployment --resource-group \ myResourceGroup --location eastus2 --sku \ name="standardv2_Monthly" --network-profile \ @@ -85,7 +85,7 @@ az nginx deployment create --deployment-name - Create a deployment with managed identity, storage account and scaling: - ```bash + ```shell az nginx deployment create --deployment-name myDeployment --resource-group \ myResourceGroup --location eastus2 --sku name=standardv2_Monthly \ --network-profile \ @@ -102,7 +102,7 @@ See the [Azure CLI Deployment Create Documentation](https://learn.microsoft.com/ To update an NGINXaaS for Azure resource use the `az nginx deployment update` command: -```bash +```shell az nginx deployment update [--add] [--auto-upgrade-profile] [--deployment-name] @@ -128,7 +128,7 @@ az nginx deployment update [--add] - Update tags and enable diagnostics support for a deployment: - ```bash + ```shell az nginx deployment update --name myDeployment --resource-group \ myResourceGroup --location eastus2 --tags tag1="value1" \ tag2="value2" --enable-diagnostics @@ -136,7 +136,7 @@ az nginx deployment update [--add] Update an NGINXaaS deployment to a dual-stack (IPv4 + IPv6) network configuration with public IPs: - ```bash + ```shell az nginx deployment update --name myDeployment --resource-group myResourceGroup \ --network-profile front-end-ip-configuration="{public-ip-addresses:[{id:/subscriptions/mySubscriptionID/resourceGroups/myResourceGroup/providers/Microsoft.Network/publicIPAddresses/pubIPv4},{id:/subscriptions/mySubscriptionID/resourceGroups/myResourceGroup/providers/Microsoft.Network/publicIPAddresses/pubIPv6}]}" \ network-interface-configuration="{subnet-id:/subscriptions/mySubscriptionID/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVNet/subnets/mySubnet}" @@ -149,7 +149,7 @@ See the [Azure CLI Deployment Update Documentation](https://learn.microsoft.com/ Use the `az nginx deployment delete` command to delete an NGINXaaS for Azure resource: -```bash +```shell az nginx deployment delete [--name] [--ids] [--no-wait {0, 1, f, false, n, no, t, true, y, yes}] @@ -162,7 +162,7 @@ az nginx deployment delete [--name] - Delete a deployment: - ```bash + ```shell az nginx deployment delete --name myDeployment \ --resource-group myResourceGroup ``` diff --git a/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-portal.md b/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-portal.md index 8a146eaa8..6593413c0 100644 --- a/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-portal.md +++ b/content/nginxaas-azure/getting-started/create-deployment/deploy-azure-portal.md @@ -10,9 +10,9 @@ type: ## Overview -This guide explains how to deploy F5 NGINX as a Service for Azure (NGINXaaS) using [Microsoft Azure portal](https://azure.microsoft.com/en-us/get-started/azure-portal). The deployment process involves creating a new deployment, configuring the deployment, and testing the deployment. +This guide explains how to deploy F5 NGINXaaS for Azure (NGINXaaS) using [Microsoft Azure portal](https://azure.microsoft.com/en-us/get-started/azure-portal). The deployment process involves creating a new deployment, configuring the deployment, and testing the deployment. -## Find the NGINX as a Service for Azure offer in the Azure portal +## Find the NGINXaaS for Azure offer in the Azure portal You can start the NGINXaaS deployment process by visiting the [Create NGINXaaS](https://portal.azure.com/#create/f5-networks.f5-nginx-for-azure) page or finding the NGINXaaS service in the Azure portal: @@ -27,7 +27,7 @@ You can start the NGINXaaS deployment process by visiting the [Create NGINXaaS]( 1. On the Create NGINXaaS Deployment **Basics** page, provide the following information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | | Subscription | Select the appropriate Azure subscription that you have access to.| @@ -39,7 +39,7 @@ You can start the NGINXaaS deployment process by visiting the [Create NGINXaaS]( | Email | Provide an email address that can be notified about service alerts, maintenance data and activity reports. | | Upgrade Channel | Select the desired upgrade channel for your deployment. For more information, see [Upgrade Channels]({{< ref "/nginxaas-azure/quickstart/upgrade-channels.md" >}}). | - {{}} + {{< /table >}} 1. Next, select **Networking**. @@ -47,7 +47,7 @@ You can start the NGINXaaS deployment process by visiting the [Create NGINXaaS]( 1. On the Create NGINXaaS Deployment **Networking** page, provide the following information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | | Virtual Network | A virtual network is required for communication between the resources you create.
You can create a new virtual network or use an existing one (for an existing one see note below).
Additionally, you can peer a new virtual network with existing ones (in any region) to create network access from NGINXaaS for Azure to your upstream servers. To peer the virtual network with another see [Create, change, or delete a virtual network peering](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-network-manage-peering).| @@ -56,7 +56,7 @@ You can start the NGINXaaS deployment process by visiting the [Create NGINXaaS]( | IP address | Set the IP address (public or private) that the service listens to for requests:

If you select a public IP address:
- Create a new public IP or use an existing one (for an existing one see the note below).
- Set the resource name for your public IP address.
Newly created public IPs are [zone-redundant in supported regions](https://learn.microsoft.com/en-us/azure/virtual-network/ip-services/public-ip-addresses#availability-zone).

If you select a private IP address:
- Provide a static IP address from the same subnet range set previously. | | Inbound port rules | Select `None` to disallow inbound access on any port, or choose to allow traffic from one of these common http(s) ports.

**Note:** This option is only available when specifying a new virtual network as part of the create workflow. If you select an existing virtual network which is associated with a subnet and Network Security Group (NSG), you will need to edit the Inbound security rules to add access for the specific ports you want to allow (for example, ports 80 and 443).| | Apply default NGINX configuration | Confirm that you want your NGINXaaS deployment to be bootstrapped with a default NGINX configuration and a browsable splash page. | - {{}} + {{< /table >}} #### Notes on subnets: diff --git a/content/nginxaas-azure/getting-started/create-deployment/deploy-terraform.md b/content/nginxaas-azure/getting-started/create-deployment/deploy-terraform.md index e4c175a4d..10dda467c 100644 --- a/content/nginxaas-azure/getting-started/create-deployment/deploy-terraform.md +++ b/content/nginxaas-azure/getting-started/create-deployment/deploy-terraform.md @@ -9,7 +9,7 @@ type: ## Overview -F5 NGINX as a Service for Azure (NGINXaaS) deployments can be managed using Terraform. This document outlines common Terraform workflows for NGINXaaS. +F5 NGINXaaS for Azure (NGINXaaS) deployments can be managed using Terraform. This document outlines common Terraform workflows for NGINXaaS. ## Prerequisites @@ -21,7 +21,7 @@ You can find examples of Terraform configurations in the [NGINXaaS for Azure Sni To create a deployment, use the following Terraform commands: - ```bash + ```shell terraform init terraform plan terraform apply --auto-approve @@ -31,7 +31,7 @@ To create a deployment, use the following Terraform commands: Once the deployment is no longer needed, run the following to clean up the deployment and related resources: - ```bash + ```shell terraform destroy --auto-approve ``` diff --git a/content/nginxaas-azure/getting-started/managed-identity-portal.md b/content/nginxaas-azure/getting-started/managed-identity-portal.md index 2d91fd063..297d79ed2 100644 --- a/content/nginxaas-azure/getting-started/managed-identity-portal.md +++ b/content/nginxaas-azure/getting-started/managed-identity-portal.md @@ -10,7 +10,7 @@ type: ## Overview -F5 NGINX as a Service for Azure (NGINXaaS) leverages a user assigned and a system assigned managed identity for some of its integrations with Azure, such as: +F5 NGINXaaS for Azure (NGINXaaS) leverages a user assigned and a system assigned managed identity for some of its integrations with Azure, such as: - Azure Key Vault (AKV): fetch SSL/TLS certificates from AKV to your NGINXaaS deployment, so that they can be referenced by your NGINX configuration. diff --git a/content/nginxaas-azure/getting-started/migrate-from-standard.md b/content/nginxaas-azure/getting-started/migrate-from-standard.md index f0922ddd3..bbdcf449e 100644 --- a/content/nginxaas-azure/getting-started/migrate-from-standard.md +++ b/content/nginxaas-azure/getting-started/migrate-from-standard.md @@ -9,7 +9,7 @@ type: ## Overview -F5 NGINX as a Service for Azure (NGINXaaS) now supports in-place migration from Standard plan to the Standard V2 plan, we encourage you to upgrade your deployment to the Standard V2 plan as soon as possible. **The Standard plan is scheduled for retirement on May 1, 2025**. If you fail to migrate by May 1, 2025, your NGINXaaS deployment will stop receiving automatic updates that address critical security issues. +F5 NGINXaaS for Azure (NGINXaaS) now supports in-place migration from Standard plan to the Standard V2 plan, we encourage you to upgrade your deployment to the Standard V2 plan as soon as possible. **The Standard plan is scheduled for retirement on May 1, 2025**. If you fail to migrate by May 1, 2025, your NGINXaaS deployment will stop receiving automatic updates that address critical security issues. The Standard V2 plan maintains the same price as the Standard plan for existing capabilities. Enabling new capabilities such as NGINX App Protect WAF or additional listen ports that were added as part of Standard V2 will incur additional charges. @@ -47,7 +47,7 @@ terraform { Run the below command to update your NGINXaaS deployment. -```bash +```shell az nginx deployment update --name myDeployment --resource-group \ myResourceGroup --sku name="standardv2_Monthly_gmz7xq9ge3py" ``` diff --git a/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configuration-azure-cli.md b/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configuration-azure-cli.md index 1c5015b2e..a3123b953 100644 --- a/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configuration-azure-cli.md +++ b/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configuration-azure-cli.md @@ -9,7 +9,7 @@ type: ## Overview -F5 NGINX as a Service for Azure (NGINXaaS) configurations can be managed using the Azure CLI. This document outlines common Azure CLI workflows to validate, create, and update NGINX configurations. +F5 NGINXaaS for Azure (NGINXaaS) configurations can be managed using the Azure CLI. This document outlines common Azure CLI workflows to validate, create, and update NGINX configurations. ## Prerequisites @@ -23,7 +23,7 @@ F5 NGINX as a Service for Azure (NGINXaaS) configurations can be managed using t To create a new NGINX configuration, use the `az nginx deployment configuration create` command: -```bash +```shell az nginx deployment configuration create --configuration-name --deployment-name --resource-group @@ -39,7 +39,7 @@ az nginx deployment configuration create --configuration-name You can use the `analyze` command to validate your configuration before submitting it to the deployment: -```bash +```shell az nginx deployment configuration analyze --deployment-name $DEPLOYMENT_NAME \ --resource-group $RESOURCE_GROUP --root-file /etc/nginx/nginx.conf \ --name default --files "$FILES_CONTENT" @@ -49,7 +49,7 @@ az nginx deployment configuration analyze --deployment-name $DEPLOYMENT_NAME \ - Create a single file configuration: - ```bash + ```shell az nginx deployment configuration create --name default \ --deployment-name myDeployment --resource-group myResourceGroup \ --root-file /etc/nginx/nginx.conf \ @@ -70,7 +70,7 @@ az nginx deployment configuration analyze --deployment-name $DEPLOYMENT_NAME \ - Create a multiple file configuration: - ```bash + ```shell az nginx deployment configuration create --name default \ --deployment-name myDeployment --resource-group myResourceGroup \ --root-file /etc/nginx/nginx.conf \ @@ -92,7 +92,7 @@ az nginx deployment configuration analyze --deployment-name $DEPLOYMENT_NAME \ - Upload package with config files: - ```bash + ```shell $ tar -czf nginx.tar.gz nginx $ tar -tzf nginx.tar.gz nginx/ @@ -106,7 +106,7 @@ az nginx deployment configuration analyze --deployment-name $DEPLOYMENT_NAME \ Where `nginx` is a directory with the following structure: - ```bash + ```shell $ tree nginx nginx ├── nginx.conf @@ -120,7 +120,7 @@ az nginx deployment configuration analyze --deployment-name $DEPLOYMENT_NAME \ Encode your tar.gz file and create your NGINXaaS configuration - ```bash + ```shell TAR_DATA=$(base64 -i nginx.tar.gz) az nginx deployment configuration create --deployment-name myDeployment \ --resource-group myResourceGroup --root-file nginx.conf --name default \ @@ -129,7 +129,7 @@ az nginx deployment configuration analyze --deployment-name $DEPLOYMENT_NAME \ - Multiple file configuration with protected files: - ```bash + ```shell az nginx deployment configuration create --name default \ --deployment-name 0102242023test --resource-group azclitest-geo \ --root-file /etc/nginx/nginx.conf \ @@ -173,7 +173,7 @@ Update a configuration for a deployment using a gzipped archive. Use the `az nginx deployment configuration update` command to update an existing NGINX configuration: -```bash +```shell az nginx deployment configuration update [--add] [--configuration-name] [--deployment-name] @@ -193,7 +193,7 @@ az nginx deployment configuration update [--add] - Update content of the first file in a configuration: - ```bash + ```shell az nginx deployment configuration update --name default \ --deployment-name myDeployment --resource-group myResourceGroup \ --files [0].content="aHR0cCB7CiAgICB1cHN0cmVhbSBhcHAgewogICAgICAgIHpvbmUg \ diff --git a/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configuration-portal.md b/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configuration-portal.md index c3d4b769b..cafaa5383 100644 --- a/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configuration-portal.md +++ b/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configuration-portal.md @@ -13,7 +13,7 @@ An NGINX configuration can be applied to the deployment using the Azure portal i - Create a new NGINX configuration from scratch or by pasting it in the Azure portal editor. - Upload a gzip compressed tar archive containing your NGINX configuration. -As part of applying your NGINX configuration, the service validates the configuration for syntax and compatibility with F5 NGINX as a Service for Azure (NGINXaaS). The use of certain directives and parameters is not allowed to ensure the NGINX configuration’s compatibility with IaaS deployment model in Azure. Validation errors are reported in the editor for you to correct. For more information, check the [NGINX Configuration Validation]({{< ref "nginx-configuration.md#nginx-configuration-validation" >}}) section. +As part of applying your NGINX configuration, the service validates the configuration for syntax and compatibility with F5 NGINXaaS for Azure (NGINXaaS). The use of certain directives and parameters is not allowed to ensure the NGINX configuration’s compatibility with IaaS deployment model in Azure. Validation errors are reported in the editor for you to correct. For more information, check the [NGINX Configuration Validation]({{< ref "/nginxaas-azure/getting-started/nginx-configuration.md#nginx-configuration-validation" >}}) section. {{< call-out "note" >}} NGINXaaS supports Layer 7 HTTP loadbalancing. To configure .com and .net servers, refer to the server name in the server block within the HTTP context. To learn more, and see examples, follow the instructions in the [NGINX configuration validtion]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/nginx-configuration-portal.md#nginx-configuration-validation" >}}) section.{{< /call-out >}} @@ -34,13 +34,13 @@ NGINXaaS supports Layer 7 HTTP loadbalancing. To configure .com and .net servers 1. Select {{< icon "fa fa-plus">}}**New File** to add a file path, then **Confirm**. - {{}} + {{< table >}} | Property | Description | | -------- | ----------- | | File path | Each NGINX configuration file can be uniquely identified by a file path (for example, nginx.conf or /etc/nginx/nginx.conf) to align with the intended NGINX configuration file structure. | | Root file | The root file is the main NGINX configuration file.
  • The first file created will be the root file by default. You can designate a different root file if you have more than a single configuration file in your deployment.
  • The root file is designated with a {{< golden-star >}} icon on the portal.
| | Protected File | Indicates that the file may contain sensitive data such as passwords or represent an ssl/tls certificate.
  • To protect a file, enable the **Protected** {{}} toggle button.
  • You cannot access the file contents of a protected file saved to the NGINX configuration, but you can view its metadata, such as the SHA-256 hash of the file contents.
  • You can provide new contents for an existing protected file using the **Overwrite** link or resubmit it without having to provide the file contents again.
  • To modify the file path of a protected file or convert it to a regular file, delete the original file and create a new one.
  • A protected file is designated with a {{}} icon on the portal.
| - {{}} + {{< /table >}} {{< call-out "note" >}}If specifying an absolute file path, see the [NGINX Filesystem Restrictions table]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/overview/#nginx-filesystem-restrictions" >}}) for the allowed directories the file can be written to.{{< /call-out >}} @@ -69,7 +69,7 @@ The editing experience consists of a single view for both editing and validation Given the example gzipped archive, -```bash +```shell $ tar -czf nginx.tar.gz nginx $ tar -tzf nginx.tar.gz nginx/ @@ -83,7 +83,7 @@ nginx/servers/server2.conf where `nginx` is a directory with the following structure, -```bash +```shell $ tree nginx nginx ├── nginx.conf diff --git a/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configurations-terraform.md b/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configurations-terraform.md index 03789d9d3..421f7dfce 100644 --- a/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configurations-terraform.md +++ b/content/nginxaas-azure/getting-started/nginx-configuration/nginx-configurations-terraform.md @@ -9,7 +9,7 @@ type: ## Overview -F5 NGINX as a Service for Azure (NGINXaaS) configurations can be managed using Terraform. This document outlines common Terraform workflows for NGINXaaS. +F5 NGINXaaS for Azure (NGINXaaS) configurations can be managed using Terraform. This document outlines common Terraform workflows for NGINXaaS. ## Prerequisites @@ -21,7 +21,7 @@ You can find examples of Terraform configurations in the [NGINXaaS for Azure Sni To create a deployment and add a configuration, run the following commands: - ```bash + ```shell terraform init terraform plan terraform apply --auto-approve @@ -31,7 +31,7 @@ To create a deployment and add a configuration, run the following commands: NGINX configuration files are uploaded and returned as base64 encoded data. We recommend using git or other version control systems to view human-readable differences between configuration files during `terraform plan`. Alternatively, you can decode the file contents to view the whole file. For example, -```bash +```shell $ terraform plan ... - config_file { @@ -60,7 +60,7 @@ http { Once the deployment is no longer needed, run the following to clean up the deployment and related resources: - ```bash + ```shell terraform destroy --auto-approve ``` diff --git a/content/nginxaas-azure/getting-started/nginx-configuration/overview.md b/content/nginxaas-azure/getting-started/nginx-configuration/overview.md index 6d3f4910a..39684935c 100644 --- a/content/nginxaas-azure/getting-started/nginx-configuration/overview.md +++ b/content/nginxaas-azure/getting-started/nginx-configuration/overview.md @@ -8,7 +8,7 @@ type: --- This document provides details about using NGINX configuration files with your -F5 NGINX as a Service for Azure deployment, restrictions, and available directives. +F5 NGINXaaS for Azure deployment, restrictions, and available directives. ## NGINX configuration common user workflows @@ -27,7 +27,7 @@ NGINX configurations stored in GitHub can be applied to existing NGINXaaS for Az ## NGINX filesystem restrictions NGINXaaS for Azure places restrictions on the instance's filesystem; only a specific set of directories are allowed to be read from and written to. Below is a table describing what directories the NGINX worker process can read and write to and what directories files can be written to. These files include certificate files and any files uploaded to the deployment, excluding NGINX configuration files. - {{}} + {{< table >}} | Allowed Directory | NGINX worker process can read/write to | Files can be written to | |------------------ | ----------------- | ----------------- | | /etc/nginx | | ✓ | @@ -36,14 +36,14 @@ NGINXaaS for Azure places restrictions on the instance's filesystem; only a spec | /tmp | ✓ | | | /var/cache/nginx | ✓ | | | /var/www | ✓ | ✓ | -{{}} +{{< /table >}} Attempts to access other directories will be denied and result in a `5xx` error. ## Disallowed configuration directives Some directives are not supported because of specific limitations. If you include one of these directives in your NGINX configuration, you'll get an error. - {{}} + {{< table >}} | Disallowed Directive | Reason | |------------------ | ----------------- | | ssl_engine | No hardware SSL accelerator is available. | @@ -51,14 +51,14 @@ Some directives are not supported because of specific limitations. If you includ | fastcgi_bind
grpc_bind
memcached_bind
proxy_bind
scgi_bind
uwsgi_bind | Source IP specification for active-active deployments is not allowed. | | quic_bpf | QUIC connection migration is not currently supported for active-active deployments. | -{{}} +{{< /table >}} You may find that a few directives are not listed here as either allowed or disallowed. Our team is working on getting these directives supported soon. ## Directives that cannot be overridden Some directives cannot be overridden by the user provided configuration. - {{}} + {{< table >}} | Persistent Directive | Value | Reason | |------------------ | ----------------------- | -----------------| | `user` | `nginx` | The `nginx` user has the correct permissions for accessing certificates, policy files and other auxfiles. | @@ -69,7 +69,7 @@ Some directives cannot be overridden by the user provided configuration. | `master_process` | `on` | This directive is intended for NGINX developers. | | `worker_cpu_affinity` | `auto` | The value `auto` allows binding worker processes automatically to available CPUs based on the current capacity of the deployment. | -{{}} +{{< /table >}} ## NGINX listen port restrictions diff --git a/content/nginxaas-azure/getting-started/ssl-tls-certificates/overview.md b/content/nginxaas-azure/getting-started/ssl-tls-certificates/overview.md index 580baf1b4..4e1d1800a 100644 --- a/content/nginxaas-azure/getting-started/ssl-tls-certificates/overview.md +++ b/content/nginxaas-azure/getting-started/ssl-tls-certificates/overview.md @@ -7,9 +7,9 @@ type: - how-to --- -F5 NGINX as a Service for Azure (NGINXaaS) enables customers to secure traffic by adding SSL/TLS certificates to a deployment. NGINXaaS can fetch certificates directly from Azure Key Vault, rotate certificates, and provide observability on the status of your certificates. +F5 NGINXaaS for Azure (NGINXaaS) enables customers to secure traffic by adding SSL/TLS certificates to a deployment. NGINXaaS can fetch certificates directly from Azure Key Vault, rotate certificates, and provide observability on the status of your certificates. -This document provides details about using SSL/TLS certificates with your F5 NGINX as a Service for Azure deployment. +This document provides details about using SSL/TLS certificates with your F5 NGINXaaS for Azure deployment. ## Supported certificate types and formats @@ -62,7 +62,7 @@ For Azure client tools, such as the Azure CLI or Azure Resource Manager, the cer To view the status of your SSL/TLS certificates, [enable monitoring]({{< ref "/nginxaas-azure/monitoring/enable-monitoring.md" >}}) for your NGINXaaS deployment and navigate to the **Metrics** tab in the Azure portal. View the `nginxaas.certificates` metric under the `nginxaas statistics` metric namespace. The `nginxaas.certificates` metric allows you to filter by certificate name and the status of the certificate. The status dimension reports the health of your certificates through the following values: - {{}} + {{< table >}} | Status | Description | | ------------- | ------------- | @@ -71,7 +71,7 @@ To view the status of your SSL/TLS certificates, [enable monitoring]({{< ref "/n | `not found` | Azure returned a 404 error when fetching the certificate from AKV. | | `incompatible`| An error occurred while fetching or processing the certificate from AKV.

The possible reasons include:

  • Error while downloading certificate and key
  • Missing content type in certificate
  • Missing content in certificate
  • Unrecognized content type, certificate not in PEM or PKCS12 format
| - {{}} + {{< /table >}} {{< img src="nginxaas-azure/azure-metrics-nginxaas.certificates.png" alt="Interface screenshot showing the Azure metric nginxaas.certificates" >}} @@ -98,7 +98,7 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `MI_NAME`: the name of the managed identity - `MI_RESOURCE_GROUP`: the name of the resource group the managed identity is in - ```bash + ```shell mi_principal_id=$(az identity show --name $MI_NAME \ --resource-group $MI_RESOURCE_GROUP \ --query principalId --output tsv) @@ -109,7 +109,7 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `DEP_NAME`: the name of the NGINXaaS deployment - `DEP_RESOURCE_GROUP`: the name of the resource group the NGINXaaS deployment is in - ```bash + ```shell mi_principal_id=$(az nginx deployment show --name $DEP_NAME \ --resource-group $DEP_RESOURCE_GROUP \ --query identity.principalId --output tsv) @@ -119,13 +119,13 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `KV_NAME`: the name of the key vault - `KV_RESOURCE_GROUP`: the name of the resource group the key vault is in - ```bash + ```shell key_vault_id=$(az keyvault show --name $KV_NAME \ --resource-group $KV_RESOURCE_GROUP \ --query id --output tsv) ``` 1. Create the role assignment. - ```bash + ```shell az role assignment create --assignee $mi_principal_id \ --role "Key Vault Secrets User" \ --scope $key_vault_id @@ -148,7 +148,7 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `MI_NAME`: the name of the managed identity - `MI_RESOURCE_GROUP`: the name of the resource group the managed identity is in - ```bash + ```shell mi_principal_id=$(az identity show --name $MI_NAME \ --resource-group $MI_RESOURCE_GROUP \ --query principalId --output tsv) @@ -159,7 +159,7 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `DEP_NAME`: the name of the NGINXaaS deployment - `DEP_RESOURCE_GROUP`: the name of the resource group the NGINXaaS deployment is in - ```bash + ```shell mi_principal_id=$(az nginx deployment show --name $DEP_NAME \ --resource-group $DEP_RESOURCE_GROUP \ --query identity.principalId --output tsv) @@ -170,7 +170,7 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `KV_NAME`: the name of the key vault - `KV_RESOURCE_GROUP`: the name of the resource group the key vault is in - ```bash + ```shell az keyvault set-policy --name $KV_NAME \ --resource-group $KV_RESOURCE_GROUP \ --object-id $mi_principal_id \ @@ -192,14 +192,14 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `NSP_NAME`: the name of the network security perimeter - `NSP_RESOURCE_GROUP`: the name of the resource group the network security perimeter will be in - ```bash + ```shell az network perimeter create --name $NSP_NAME --resource-group $NSP_RESOURCE_GROUP ``` 1. Create a profile for the network security perimeter. Please ensure the following environment variable is set before copying the below Azure CLI command. - `PROFILE_NAME`: the name of the network security perimeter profile - ```bash + ```shell az network perimeter profile create --name $PROFILE_NAME \ --resource-group $NSP_RESOURCE_GROUP \ --perimeter-name $NSP_NAME @@ -209,19 +209,19 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `KV_NAME`: the name of the key vault - `KV_RESOURCE_GROUP`: the name of the resource group the key vault is in - ```bash + ```shell key_vault_id=$(az keyvault show --name $KV_NAME \ --resource-group $KV_RESOURCE_GROUP \ --query id --output tsv) ``` 1. Get the resource ID of the network security profile. - ```bash + ```shell nsp_profile_id=$(az network perimeter profile show --name $PROFILE_NAME \ --resource-group $NSP_RESOURCE_GROUP \ --perimeter-name $NSP_NAME --query id --output tsv) ``` 1. Associate the key vault with the network security perimeter - ```bash + ```shell az network perimeter association create --name key-vault-association \ --perimeter-name $NSP_NAME \ --resource-group $NSP_RESOURCE_GROUP \ @@ -233,7 +233,7 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `RULE_NAME`: the name of the access rule - `DEP_SUBSCRIPTION_ID`: the subscription ID of the NGINXaaS deployment - ```bash + ```shell az network perimeter profile access-rule create --name $RULE_NAME \ --profile-name $PROFILE_NAME \ --perimeter-name $NSP_NAME \ @@ -276,7 +276,7 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `MI_NAME`: the name of the managed identity - `MI_RESOURCE_GROUP`: the name of the resource group the managed identity is in - ```bash + ```shell mi_principal_id=$(az identity show --name $MI_NAME \ --resource-group $MI_RESOURCE_GROUP \ --query principalId --output tsv) @@ -287,7 +287,7 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `DEP_NAME`: the name of the NGINXaaS deployment - `DEP_RESOURCE_GROUP`: the name of the resource group the NGINXaaS deployment is in - ```bash + ```shell mi_principal_id=$(az nginx deployment show --name $DEP_NAME \ --resource-group $DEP_RESOURCE_GROUP \ --query identity.principalId --output tsv) @@ -298,7 +298,7 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `KV_NAME`: the name of the key vault - `KV_RESOURCE_GROUP`: the name of the resource group the key vault is in - ```bash + ```shell az keyvault set-policy --name $KV_NAME \ --resource-group $KV_RESOURCE_GROUP \ --object-id $mi_principal_id \ @@ -326,14 +326,14 @@ The following section describes common errors you might encounter while adding S Please ensure the following environment variables are set before copying the below Azure CLI command. - `CERT_NAME`: the name of the certificate - `KV_NAME`: the name of the key vault - ```bash + ```shell certificate_id=$(az keyvault certificate show --name $CERT_NAME \ --vault-name $KV_NAME \ --query id --output tsv) ``` 1. Enable the certificate. - ```bash + ```shell az keyvault certificate set-attributes --enabled true --id $certificate_id ``` diff --git a/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-azure-cli.md b/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-azure-cli.md index 1c8f189c7..39f228451 100644 --- a/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-azure-cli.md +++ b/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-azure-cli.md @@ -7,7 +7,7 @@ type: - how-to --- -You can use Azure Key Vault (AKV) to store SSL/TLS certificates and keys to use in your F5 NGINX as a Service for Azure (NGINXaaS) configuration. +You can use Azure Key Vault (AKV) to store SSL/TLS certificates and keys to use in your F5 NGINXaaS for Azure (NGINXaaS) configuration. ### Prerequisites @@ -21,7 +21,7 @@ Create a certificate under a deployment. This references an existing certificate To create a certificate, use the `az nginx deployment certificate create` command: -```bash +```shell az nginx deployment certificate create --certificate-name --deployment-name --resource-group @@ -36,7 +36,7 @@ az nginx deployment certificate create --certificate-name - Create a certificate with a certificate path, key path, and key vault secret ID: - ```bash + ```shell az nginx deployment certificate create --certificate-name myCertificate \ --deployment-name myDeployment --resource-group myResourceGroup \ --certificate-path /etc/nginx/test.cert --key-path /etc/nginx/test.key \ @@ -49,7 +49,7 @@ See [Azure CLI Certificate Create Documentation](https://learn.microsoft.com/en- To update a certificate, use the `az nginx deployment certificate update` command: -```bash +```shell az nginx deployment certificate update [--add] [--certificate-name] [--certificate-path] @@ -70,7 +70,7 @@ az nginx deployment certificate update [--add] - Update the certificate virtual path, key virtual path and certificate: - ```bash + ```shell az nginx deployment certificate update --certificate-name myCertificate \ --deployment-name myDeployment --resource-group myResourceGroup \ --certificate-path /etc/nginx/testupdated.cert \ @@ -84,7 +84,7 @@ See [Azure CLI Certificate Create Documentation](https://learn.microsoft.com/en- To delete a certificate, use the `az nginx deployment certificate delete` command: -```bash +```shell az nginx deployment certificate delete [--certificate-name] [--deployment-name] [--ids] @@ -98,7 +98,7 @@ az nginx deployment certificate delete [--certificate-name] - Delete a certificate: - ```bash + ```shell az nginx deployment certificate delete --certificate-name myCertificate \ --deployment-name myDeployment --resource-group myResourceGroup ``` diff --git a/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-portal.md b/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-portal.md index bb6c0fc65..c2d9e9106 100644 --- a/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-portal.md +++ b/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-portal.md @@ -10,7 +10,7 @@ type: ## Overview -You can manage SSL/TSL certificates for F5 NGINX as a Service for Azure (NGINXaaS) using the Azure portal. +You can manage SSL/TSL certificates for F5 NGINXaaS for Azure (NGINXaaS) using the Azure portal. ## Prerequisites @@ -28,22 +28,22 @@ Before you begin, refer Azure documentation to [Import a certificate to your Key 1. Provide the required information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | | Name | A unique name for the certificate. | | Certificate path | This path can match one or more `ssl_certificate` directive file arguments in your NGINX configuration.
The certificate path must be unique within the same deployment. | | Key path | This path can match one or more `ssl_certificate_key` directive file arguments in your NGINX configuration.
The key path must be unique within the same deployment.
The key path and certificate path can be the same within the certificate. | - {{}} + {{< /table >}} - The **Select certificate** button will take you to a new screen where you will need to provide the following information: - {{}} + {{< table >}} | Field | Description | |----------------------- | ---------------------------- | | Key vault | Select from the available key vaults. | | Certificate | Select the certificate you want to add from the previously selected key vault. | - {{}} + {{< /table >}} If you need to create a new key vault or certificate, you can do so by selecting **Create new key vault** or **Create new** under the **Key Vault** and **Certificate** fields, respectively. diff --git a/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-terraform.md b/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-terraform.md index a904e7a5d..f0a3d8751 100644 --- a/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-terraform.md +++ b/content/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-terraform.md @@ -9,7 +9,7 @@ type: ## Overview -You can manage SSL/TSL certificates for F5 NGINX as a Service for Azure (NGINXaaS) using Terraform. +You can manage SSL/TSL certificates for F5 NGINXaaS for Azure (NGINXaaS) using Terraform. ## Prerequisites @@ -21,7 +21,7 @@ You can find examples of Terraform configurations in the [NGINXaaS for Azure Sni To create a deployment, add a certificate, and use it in a configuration, run the following commands: - ```bash + ```shell terraform init terraform plan terraform apply --auto-approve @@ -31,7 +31,7 @@ To create a deployment, add a certificate, and use it in a configuration, run th Once the deployment is no longer needed, run the following to clean up the deployment and related resources: - ```bash + ```shell terraform destroy --auto-approve ``` diff --git a/content/nginxaas-azure/known-issues.md b/content/nginxaas-azure/known-issues.md index 29cd3214f..e307fbdf5 100644 --- a/content/nginxaas-azure/known-issues.md +++ b/content/nginxaas-azure/known-issues.md @@ -7,7 +7,7 @@ url: /nginxaas/azure/known-issues/ --- -List of known issues in the latest release of F5 NGINX as a Service for Azure (NGINXaaS). +List of known issues in the latest release of F5 NGINXaaS for Azure (NGINXaaS). ### {{% icon-bug %}} Custom and precompiled security policies cannot both be referenced in an NGINX configuration diff --git a/content/nginxaas-azure/loadbalancer-kubernetes.md b/content/nginxaas-azure/loadbalancer-kubernetes.md index 9ea1a46d4..a76032ef9 100644 --- a/content/nginxaas-azure/loadbalancer-kubernetes.md +++ b/content/nginxaas-azure/loadbalancer-kubernetes.md @@ -103,7 +103,7 @@ Make sure to write down the key value in a safe location after creation, as you Set shell variables about the name of the NGINXaaS you've already created: -```bash +```shell ## Customize this to provide the details about my already created NGINXaaS deployment nginxName=myNginx nginxGroup=myNginxGroup @@ -111,7 +111,7 @@ nginxGroup=myNginxGroup Generate a new random data plane API key: -```bash +```shell # Generate a new random key or specify a value for it. keyName=myKey keyValue=$(uuidgen --random) @@ -119,7 +119,7 @@ keyValue=$(uuidgen --random) Create the key for your NGINXaaS deployment: -```bash +```shell az nginx deployment api-key create --name $keyName --secret-text $keyValue --deployment-name $nginxName --resource-group $nginxGroup ``` @@ -135,7 +135,7 @@ The data plane API endpoint can be retrieved using the Azure CLI or portal. ##### View NGINXaaS data plane API endpoint using the Azure CLI -```bash +```shell dataplaneAPIEndpoint=$(az nginx deployment show -g "$nginxGroup" -n "$nginxName" --query properties.dataplaneApiEndpoint -o tsv) ``` @@ -147,7 +147,7 @@ The NLK controller can be installed in your Kubernetes cluster using either Helm Install the NLK controller using `helm install`. Be sure your kubectl context is pointed at the desired cluster. -```bash +```shell helm install nlk oci://registry-1.docker.io/nginxcharts/nginxaas-loadbalancer-kubernetes --version 1.1.1 \ --set "nlk.dataplaneApiKey=${keyValue}" \ --set "nlk.config.nginxHosts=${dataplaneAPIEndpoint}nplus" \ @@ -158,7 +158,7 @@ helm install nlk oci://registry-1.docker.io/nginxcharts/nginxaas-loadbalancer-ku Install the NLK controller using `az k8s-extension`. -```bash +```shell ## Customize this to provide the details about my already created AKS cluster aksName=myCluster aksGroup=myClusterGroup @@ -186,18 +186,18 @@ You can also install the NLK controller AKS extension by navigating to [F5 NGINX - Select **Continue** to proceed with the installation. - On the **Basics** tab, provide the following information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | | Subscription | Select the appropriate Azure subscription. | | Resource group | Select the AKS cluster's resource group. | - {{}} + {{< /table >}} - Select **Cluster Details**, and provide the AKS cluster name. You can select an existing AKS cluster or create a new one. - Select **Application Details**, and provide the following information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | @@ -206,7 +206,7 @@ You can also install the NLK controller AKS extension by navigating to [F5 NGINX | Allow minor version upgrades of extension | Select whether to allow the extension to be upgraded automatically to the latest minor version. | | NGINXaaS Dataplane API Key | Provide the previously generated data plane API key value: `{keyValue}` | | NGINXaaS Dataplane API Endpoint | Provide the previously retrieved data plane API endpoint value: `{dataplaneAPIEndpoint}nplus` | - {{}} + {{< /table >}} - Select **Review + Create** to continue. - Azure will validate the extension settings. This page will provide a summary of the provided information. Select **Create**. diff --git a/content/nginxaas-azure/module-changelog.md b/content/nginxaas-azure/module-changelog.md index efc14c51c..9f4c39a64 100644 --- a/content/nginxaas-azure/module-changelog.md +++ b/content/nginxaas-azure/module-changelog.md @@ -5,14 +5,51 @@ toc: true url: /nginxaas/azure/module-changelog/ --- -Learn about the modules supported by the latest versions of F5 NGINX as a Service for Azure. +Learn about the modules supported by the latest versions of F5 NGINXaaS for Azure. + + +## Access module versions using data plane API: + +To access available module versions from the data plane API, follow these steps: +- View Your API Endpoints and Create an API Key + - Follow the [NGINXaaS data plane API endpoint]({{< ref "/nginxaas-azure/loadbalancer-kubernetes.md#nginxaas-data-plane-api-endpoint" >}}) and [Create an NGINXaaS data plane API key]({{< ref "/nginxaas-azure/loadbalancer-kubernetes.md#create-an-nginxaas-data-plane-api-key" >}}) to locate your dataplane API endpoint and create an API key. + +- Construct the Request URL + - Add `/packages` to your data plane API endpoint, for example `https:///packages`. + +- Authenticate API requests + - Encode your API key to Base64 and add the prefix `ApiKey` to the encoded string. + - Set the `Authorization` HTTP header to: + `ApiKey ` + + +```shell + curl -H "Authorization: ApiKey " https:///packages +``` + +Response Example: +```json +{ + "packages": [ + { + "name": "nginx-plus-module-headers-more", + "version":"35+0.37-1~jammy" + }, + { + "name": "nginx-plus-module-otel", + "version": "35+0.1.2-1~jammy" + }, + ... + ] +} +``` ## July 03, 2025 ### Stable - {{}} + {{< table >}} | Name | Version | Description | |------------------------------------------|--------------------------|------------------------------------------------------------------------| @@ -30,13 +67,13 @@ Learn about the modules supported by the latest versions of F5 NGINX as a Servic | nginx-plus-module-appprotect | 33+5.264.0-1 | NGINX Plus app protect dynamic module version 5.264.0 | | app-protect-module-plus | 33+5.264.0-1 | App-Protect package for Nginx Plus, includes all of the default files and examples. NGINX App Protect provides web application firewall (WAF) security protection for your web applications, including OWASP Top 10 attacks. | | app-protect-plugin | 6.9.0-1 | NGINX App Protect plugin | -{{}} +{{< /table >}} ### Preview - {{}} + {{< table >}} | Name | Version | Description | |------------------------------------------|--------------------------|------------------------------------------------------------------------| @@ -54,4 +91,4 @@ Learn about the modules supported by the latest versions of F5 NGINX as a Servic | nginx-plus-module-appprotect | 33+5.264.0-1 | NGINX Plus app protect dynamic module version 5.264.0 | | app-protect-module-plus | 33+5.264.0-1 | App-Protect package for Nginx Plus, includes all of the default files and examples. NGINX App Protect provides web application firewall (WAF) security protection for your web applications, including OWASP Top 10 attacks. | | app-protect-plugin | 6.9.0-1 | NGINX App Protect plugin | -{{}} +{{< /table >}} diff --git a/content/nginxaas-azure/monitoring/configure-alerts.md b/content/nginxaas-azure/monitoring/configure-alerts.md index 85543bd35..7ad4027a4 100644 --- a/content/nginxaas-azure/monitoring/configure-alerts.md +++ b/content/nginxaas-azure/monitoring/configure-alerts.md @@ -11,7 +11,7 @@ type: ## Overview -{{< call-out "note" >}}F5 NGINX as a Service for Azure (NGINXaaS) publishes platform metrics to Azure Monitor. To learn more about how to create and manage metrics-based alert rules, refer to the [Alerts section in Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-create-new-alert-rule?tabs=metric) documentation from Microsoft. {{< /call-out >}} +{{< call-out "note" >}}F5 NGINXaaS for Azure (NGINXaaS) publishes platform metrics to Azure Monitor. To learn more about how to create and manage metrics-based alert rules, refer to the [Alerts section in Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-create-new-alert-rule?tabs=metric) documentation from Microsoft. {{< /call-out >}} This guide explains how to create and configure metrics-based alerts for your NGINXaaS for Azure deployment using Azure Monitor. diff --git a/content/nginxaas-azure/monitoring/enable-logging/logging-using-cli.md b/content/nginxaas-azure/monitoring/enable-logging/logging-using-cli.md index 08b1362c4..83f272526 100644 --- a/content/nginxaas-azure/monitoring/enable-logging/logging-using-cli.md +++ b/content/nginxaas-azure/monitoring/enable-logging/logging-using-cli.md @@ -10,7 +10,7 @@ type: ## Overview -F5 NGINX as a Service for Azure (NGINXaaS) supports integrating Azure Diagnostic Settings to collect NGINX error and access logs. +F5 NGINXaaS for Azure (NGINXaaS) supports integrating Azure Diagnostic Settings to collect NGINX error and access logs. {{< call-out "caution" >}} Enabling logs using the **NGINX Logs** blade on your NGINXaaS deployment is now deprecated. This feature will be removed in an upcoming update. If you have issues accessing your NGINX logs using the deprecated method, please follow the steps in this guide to access your NGINX logs. diff --git a/content/nginxaas-azure/monitoring/enable-logging/logging-using-portal.md b/content/nginxaas-azure/monitoring/enable-logging/logging-using-portal.md index 0f206a5b0..2ba868281 100644 --- a/content/nginxaas-azure/monitoring/enable-logging/logging-using-portal.md +++ b/content/nginxaas-azure/monitoring/enable-logging/logging-using-portal.md @@ -10,7 +10,7 @@ type: ## Overview -F5 NGINX as a Service for Azure (NGINXaaS) supports integrating Azure Diagnostic Settings to collect NGINX error and access logs. +F5 NGINXaaS for Azure (NGINXaaS) supports integrating Azure Diagnostic Settings to collect NGINX error and access logs. {{< call-out "caution" >}} Enabling logs using the **NGINX Logs** blade on your NGINXaaS deployment is now deprecated. This feature will be removed in an upcoming update. If you have issues accessing your NGINX logs using the deprecated method, please follow the steps in this guide to access your NGINX logs. diff --git a/content/nginxaas-azure/monitoring/enable-logging/logging-using-terraform.md b/content/nginxaas-azure/monitoring/enable-logging/logging-using-terraform.md index 8e544f5a2..e39f66416 100644 --- a/content/nginxaas-azure/monitoring/enable-logging/logging-using-terraform.md +++ b/content/nginxaas-azure/monitoring/enable-logging/logging-using-terraform.md @@ -10,7 +10,7 @@ type: ## Overview -F5 NGINX as a Service for Azure (NGINXaaS) supports integrating Azure Diagnostic Settings to collect NGINX error and access logs. +F5 NGINXaaS for Azure (NGINXaaS) supports integrating Azure Diagnostic Settings to collect NGINX error and access logs. {{< call-out "caution" >}} Enabling logs using the **NGINX Logs** blade on your NGINXaaS deployment is now deprecated. This feature will be removed in an upcoming update. If you have issues accessing your NGINX logs using the deprecated method, please follow the steps in this guide to access your NGINX logs. diff --git a/content/nginxaas-azure/monitoring/enable-monitoring.md b/content/nginxaas-azure/monitoring/enable-monitoring.md index f37b706f7..8b81680f3 100644 --- a/content/nginxaas-azure/monitoring/enable-monitoring.md +++ b/content/nginxaas-azure/monitoring/enable-monitoring.md @@ -8,7 +8,7 @@ type: - how-to --- -Monitoring your application's performance is crucial for maintaining its reliability and efficiency. F5 NGINX as a Service for Azure (NGINXaaS) seamlessly integrates with Azure Monitor, allowing you to collect, correlate, and analyze metrics for a thorough understanding of your application's health and behavior. +Monitoring your application's performance is crucial for maintaining its reliability and efficiency. F5 NGINXaaS for Azure (NGINXaaS) seamlessly integrates with Azure Monitor, allowing you to collect, correlate, and analyze metrics for a thorough understanding of your application's health and behavior. Refer to the [Azure monitor overview](https://docs.microsoft.com/en-us/azure/azure-monitor/overview) documentation from Microsoft to learn more about Azure Monitor. @@ -66,7 +66,7 @@ This section shows you how to effectively discover, gather and analyze NGINXaaS 1. **Retrieve metric definitions:** Metrics definitions give you insights into the various metrics available for NGINXaaS within a namespace and what they represent. The following `curl` example shows how to retrieve all metrics definitions within the `nginx connections statistics` namespace for your NGINXaaS deployment: - ```bash + ```shell curl --request GET --header "Authorization: Bearer $TOKEN" "https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-dep/providers/microsoft.insights/metricDefinitions?api-version=2024-02-01" ``` @@ -94,7 +94,7 @@ This section shows you how to effectively discover, gather and analyze NGINXaaS 2. **Metric values:** You can obtain the actual metric values which represent real-time or historical data points that tell you how your NGINXaaS is performing. The following `curl` example shows how to retrieve the value of metric `nginx.conn.current` over a 10-minute time window averaged over 5 minute intervals: - ```bash + ```shell curl --request GET --header "Authorization: Bearer $TOKEN" "https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/my-nginx-rg/providers/NGINX.NGINXPLUS/nginxDeployments/my-nginx-dep/providers/microsoft.insights/metrics?metricnames=nginx.conn.current×pan=2025-03-27T20:00:00Z/2025-03-27T20:10:00Z&aggregation=Average&interval=PT5M&api-version=2024-02-01" ``` diff --git a/content/nginxaas-azure/monitoring/metrics-catalog.md b/content/nginxaas-azure/monitoring/metrics-catalog.md index 0a6b06e0e..16ae9e82e 100644 --- a/content/nginxaas-azure/monitoring/metrics-catalog.md +++ b/content/nginxaas-azure/monitoring/metrics-catalog.md @@ -8,7 +8,7 @@ type: - concept --- -F5 NGINX as a Service for Azure (NGINXaaS) provides a rich set of metrics that you can use to monitor the health and performance of your NGINXaaS deployment. This document provides a catalog of the metrics that are available for monitoring NGINXaaS for Azure in Azure Monitor. +F5 NGINXaaS for Azure (NGINXaaS) provides a rich set of metrics that you can use to monitor the health and performance of your NGINXaaS deployment. This document provides a catalog of the metrics that are available for monitoring NGINXaaS for Azure in Azure Monitor. ## Available metrics @@ -32,7 +32,7 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio ### NGINXaaS statistics -{{}} +{{< table >}} | **Metric** | **Display Name** | **Dimensions** | **Type** | **Description** | **Roll-up per** | | --------------------- | --------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | @@ -48,13 +48,13 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio | system.listener_backlog.queue_limit | Listener backlog queue limit | listen_address, file_desc | count | The capacity of a specific backlog queue, labelled by listen address. | deployment | | system.listener_backlog.length | Listener backlog length | listen_address, file_desc | count | The number of items in a specific backlog queue, labelled by listen address. | deployment | -{{}} +{{< /table >}} {{< call-out "warning" >}}The `ncu.consumed` metric is now deprecated and is on the path to retirement. Please change any alerting on this metric to use the new Capacity Percentage metric.{{< /call-out >}} ### NGINX connections statistics -{{}} +{{< table >}} | **Metric** | **Display Name** | **Dimensions** | **Type** | **Description** | **Roll-up per** | |------------------------------|------------------|----------------|----------|---------------------------------------------------------------------------------------------------------------|-----------------| @@ -64,11 +64,11 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio | nginx.conn.idle | Idle connections | build version | count | Idle Connections The average number of idle client connections during the aggregation interval. | deployment | | nginx.conn.current | Current connections | build version | count | Current Connections The average number of active and idle client connections during the aggregation interval. | deployment | -{{}} +{{< /table >}} ### NGINX requests and response statistics -{{}} +{{< table >}} | **Metric** | **Display Name** | **Dimensions** | **Type** | **Description** | **Roll-up per** | |----------------------------------------|------------------|-----------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------|---------------| @@ -102,11 +102,11 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio | plus.http.request.location_zone.bytes_rcvd | Location zone HTTP bytes received | build version location_zone | count | Location Zone Bytes Received The total number of bytes received from clients during the aggregation interval. | location zone | | plus.http.request.location_zone.bytes_sent | Location zone HTTP bytes sent | build version location_zone | count | Location Zone Bytes Sent The total number of bytes sent to clients during the aggregation interval. | location zone | -{{}} +{{< /table >}} ### NGINX SSL statistics -{{}} +{{< table >}} | **Metric** | **Display Name** | **Dimensions** | **Type** | **Description** | **Roll-up per** | |----------------------------------------|------------------|-----------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------|---------------| @@ -134,11 +134,11 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio | plus.http.ssl.verify_failures.revoked_cert | Verify failures - revoked cert | build version server_zone | count | SSL certificate verification errors - a revoked certificate was presented by a client during the aggregation interval. | server zone | | plus.http.ssl.verify_failures.other | Verify failures - other | build version server_zone | count | SSL certificate verification errors - other SSL certificate verification errors during the aggregation interval. | server zone | -{{}} +{{< /table >}} ### NGINX cache statistics -{{}} +{{< table >}} | **Metric** | **Display Name** | **Dimensions** | **Type** | **Description** | **Roll-up per** | |----------------------------------------|------------------|-----------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------|---------------| @@ -164,11 +164,11 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio | plus.cache.bypass.responses_written | Cache bypass responses written | build version cache_zone | count | The total number of responses that bypassed the cache and were written back to the cache during the aggregation interval. | cache zone | | plus.cache.bypass.bytes_written | Cache bypass bytes written | build version cache_zone | count | The total number of bytes that bypassed the cache and were written back to the cache during the aggregation interval. | cache zone | -{{}} +{{< /table >}} ### NGINX worker statistics -{{}} +{{< table >}} | **Metric** | **Display Name** | **Dimensions** | **Type** | **Description** | **Roll-up per** | |----------------------------------------|-------------------------------|-----------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------|---------------| @@ -179,11 +179,11 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio | plus.worker.http.request.total | Total worker HTTP requests | build version worker_id | count | The total number of client requests received by the worker process during the aggregation interval. | worker | | plus.worker.http.request.current | Current worker HTTP requests | build version worker_id | count | The current number of client requests that are currently being processed by the worker process during the aggregation interval. | worker | -{{}} +{{< /table >}} ### NGINX upstream statistics -{{}} +{{< table >}} | **Metric** | **Display Name** | **Dimensions** | **Type** | **Description** | **Roll-up per** | |-----------------------------------|-------------------------------|-----------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------|---------------| @@ -238,11 +238,11 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio | plus.stream.upstream.peers.ssl.verify_failures.hostname_mismatch | Stream verify failure - hostname mismatch | build version upstream peer.address peer.name | count | SSL certificate verification errors - server's certificate doesn't match the hostname during the aggregation interval. | upstream peer | | plus.stream.upstream.peers.ssl.verify_failures.other | Stream SSL verify failure - other | build version upstream peer.address peer.name | count | SSL certificate verification errors - other SSL certificate verification errors during the aggregation interval. | upstream peer | -{{}} +{{< /table >}} ### NGINX system statistics -{{}} +{{< table >}} | **Metric** | **Display Name** | **Dimensions** | **Type** | **Description** | **Roll-up per** | |----------------------------------------|------------------|-----------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------|---------------| @@ -254,11 +254,11 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio | system.interface.total_bytes| Interface total bytes | interface | count | System Interface Total Bytes, sum of bytes_sent and bytes_rcvd. | deployment | | system.interface.egress_throughput| Interface egress throughput | interface | count | System Interface Egress Throughput, i.e. bytes sent per second| deployment | -{{}} +{{< /table >}} ### NGINX stream statistics -{{}} +{{< table >}} | **Metric** | **Display Name** | **Dimensions** | **Type** | **Description** | **Roll-up per** | |----------------------------------------|-------------------------------|-----------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------|---------------| @@ -310,11 +310,11 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio | plus.stream.zone_sync.zones.records_pending | Zone sync records pending | build, version, shared_memory_zone | avg | The average number of records that need to be sent to the cluster during the aggregation interval. | shared memory zone | | plus.stream.zone_sync.zones.records_total | Zone sync records total | build, version, shared_memory_zone | avg | The average number of records stored in the shared memory zone by all nodes during the aggregation interval. | shared memory zone | -{{}} +{{< /table >}} ### NGINX resolver statistics -{{}} +{{< table >}} | **Metric** | **Display Name** | **Dimensions** | **Type** | **Description** | **Roll-up per** | |---------------------------------------|------------------------------|--------------------------------|----------|--------------------------------------------------------------------------------------------|-----------------| @@ -330,4 +330,4 @@ The metrics are categorized by the namespace used in Azure Monitor. The dimensio | plus.resolvers.responses.timedout | Timed out requests | build, version, resolver_zone | count | The number of timed out requests during the aggregation interval. | resolver zone | | plus.resolvers.responses.unknown | Unknown error responses | build, version, resolver_zone | count | The number of requests completed with an unknown error during the aggregation interval. | resolver zone | -{{}} +{{< /table >}} diff --git a/content/nginxaas-azure/overview/feature-comparison.md b/content/nginxaas-azure/overview/feature-comparison.md index f30da905f..0e2582423 100644 --- a/content/nginxaas-azure/overview/feature-comparison.md +++ b/content/nginxaas-azure/overview/feature-comparison.md @@ -1,5 +1,5 @@ --- -title: Feature comparison +title: Feature overview weight: 300 description: Compare NGINXaaS for Azure with other NGINX offerings. toc: false @@ -9,63 +9,124 @@ type: - concept --- -{{}} - -|**Load Balancer**
   |**NGINX Open
Source** |**NGINX Plus
 ** |**F5 NGINXaaS
for Azure** | -|----------------------------------------|---------------------|---------------------|--------------------------| -|  [HTTP](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/) and [TCP/UDP](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/) support |{{}} |{{}} |{{}} | -|  [Layer 7 request routing](https://www.nginx.org/en/docs/http/ngx_http_core_module.html#location) |{{}} |{{}} |{{}} | -|  [Session persistence](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#enabling-session-persistence) |{{}} |{{}} |{{}} | -|  [Active health checks](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/) | |{{}} |{{}} | -|  [DNS service-discovery integration](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service) | |{{}} |{{}} | -|**Content Cache** |**NGINX Open
Source** |**NGINX Plus
 ** |**NGINXaaS
for Azure** | -|  [Static and dynamic content caching](https://docs.nginx.com/nginx/admin-guide/content-cache/content-caching/)|{{}} |{{}} |{{}} | -|  [Cache-purging API](https://docs.nginx.com/nginx/admin-guide/content-cache/content-caching/#purging-content-from-the-cache) | |{{}} | | -|  MQTT protocol support for IOT devices | |{{}} |{{}} | -|**Web Server and Reverse Proxy** |**NGINX Open
Source** |**NGINX Plus
 ** |**NGINXaaS
for Azure** | -|  Origin server for static content |{{}} |{{}} |{{}} | -|  Reverse proxy: [HTTP](https://nginx.org/en/docs/http/ngx_http_proxy_module.html), [FastCGl](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html),
  [memcached](https://nginx.org/en/docs/http/ngx_http_memcached_module.html), [SCGI](https://nginx.org/en/docs/http/ngx_http_scgi_module.html), [uwsgi](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html) |{{}} | {{}} |{{}} | -|  [HTTP/2 gateway](https://www.nginx.org/en/docs/http/ngx_http_v2_module.html) |{{}} |{{}} |{{}} | -|  [gRPC proxy](https://nginx.org/en/docs/http/ngx_http_grpc_module.html) |{{}} |{{}} |{{}} | -|  [HTTP/2 server push](https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_push) |{{}} |{{}} |{{}} | -|  [HTTP/3 over QUIC](https://nginx.org/en/docs/http/ngx_http_v3_module.html) |{{}} |{{}} |{{}} | -|**Security Controls** |**NGINX Open
Source** |**NGINX Plus
 ** |**NGINXaaS
for Azure** | -|  [HTTP basic authentication](https://www.nginx.org/en/docs/http/ngx_http_auth_basic_module.html) |{{}} |{{}} |{{}} | -|  [HTTP authentication subrequests](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html) |{{}} |{{}} |{{}} | -|  [IP address-based access control lists](https://nginx.org/en/docs/http/ngx_http_access_module.html) |{{}}|{{}} |{{}} | -|  [Rate limiting](https://blog.nginx.org/blog/rate-limiting-nginx) |{{}} |{{}} |{{}} | -|  Dual-stack RSA/ECC SSL/TLS offload |{{}} |{{}} |{{}} | -|  TLS 1.3 support |{{}} |{{}} |{{}} | -|  [JWT authentication](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html) | |{{}} |{{}} | -|  OpenID Connect single sign-on
  (SSO) | |{{}} |{{}} | -|  Internal redirect | |{{}} | | -|  NGINX as a SAML Service Provider | |{{}} |{{}} | -|  [NGINX App Protect WAF](https://www.f5.com/products/nginx/nginx-app-protect) (additional cost) | |{{}} |{{}} | -|  [NGINX App Protect DoS](https://www.f5.com/products/nginx/nginx-app-protect) (additional cost) | |{{}} | | -|**Monitoring** |**NGINX Open
Source** |**NGINX Plus
 ** |**NGINXaaS
for Azure** | -|  Export to [external monitoring tools](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/) |{{}} |{{}} |Export metrics to
Azure Monitor | -|  Built-in dashboard | |{{}} |[Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/overview)
and [Azure Portal](https://azure.microsoft.com/en-us/get-started/azure-portal) | -|  [Extended status with 100+
  additional metrics](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/) | |{{}} |{{}} | -|  Native Open Telemetry Tracing | |{{}} | | -|**High Availability (HA)** |**NGINX Open
Source** |**NGINX Plus
 ** |**NGINXaaS
for Azure** | -|  [Active-active](https://docs.nginx.com/nginx/admin-guide/high-availability/) | |{{}} |{{}} | -|  [Active-passive](https://docs.nginx.com/nginx/admin-guide/high-availability/) | |{{}} | Not Applicable | -|  [Configuration synchronization
  across cluster](https://docs.nginx.com/nginx/admin-guide/high-availability/configuration-sharing/) | |{{}} |{{}} | -|  [State sharing](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/): sticky-learn session
  persistence, rate limiting, key-value
  stores | |{{}} |{{}} | -|**Programmability** |**NGINX Open
Source** |**NGINX Plus
 ** |**NGINXaaS
for Azure** | -|  [NGINX JavaScript module](https://www.f5.com/company/blog/nginx/harnessing-power-convenience-of-javascript-for-each-request-with-nginx-javascript-module) |{{}} |{{}} |{{}} | -|  [NGINX Plus API for dynamic
  reconfiguration](https://docs.nginx.com/nginx/admin-guide/load-balancer/dynamic-configuration-api/) | |{{}} | | -|  [Key-value store](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) | |{{}} |{{}} | -|  Dynamic reconfiguration without
  process reloads | |{{}} | | -|**Streaming Media** |**NGINX Open
Source** |**NGINX Plus
 ** |**NGINXaaS
for Azure** | -|  Live streaming: RTMP, HLS, DASH |{{}} |{{}} |{{}} | -|  VOD: Flash (FLV), MP4 |{{}} |{{}} |{{}} | -|  Adaptive bitrate VOD: [HLS](https://nginx.org/en/docs/http/ngx_http_hls_module.html), [HDS](https://nginx.org/en/docs/http/ngx_http_f4f_module.html) | |{{}} | | -|  [MP4 bandwidth controls](https://nginx.org/en/docs/http/ngx_http_mp4_module.html) | |{{}} | | -|**Third-party ecosystem** |**NGINX Open
Source** |**NGINX Plus
 ** |**NGINXaaS
for Azure** | -|  [Ingress controller](https://www.f5.com/products/nginx/nginx-ingress-controller) |{{}} |{{}} | | -|  OpenShift Router |{{}} |{{}} | | -|  [Dynamic modules repository](https://www.f5.com/go/product/nginx-modules) | |{{}} |[Image-Filter](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html)
[njs](https://nginx.org/en/docs/njs/)
[OpenTelemetry](https://nginx.org/en/docs/ngx_otel_module.html)
[XSLT](https://nginx.org/en/docs/http/ngx_http_xslt_module.html) | -|  Deployable as a service | | |Microsoft Azure | -|  [Commercial support](https://my.f5.com/manage/s/article/K000140156/) | |{{}} |{{}} | -{{}} +NGINXaaS for Azure delivers the core capabilities of NGINX as a managed service, integrated with Microsoft Azure. It provides most of the features of NGINX Open Source and many from NGINX Plus, but some capabilities are not included. + +Below is a feature breakdown with notes on support and limitations. + + +## Load balancing + +- [HTTP and TCP/UDP load balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/) +- [Layer 7 request routing](https://www.nginx.org/en/docs/http/ngx_http_core_module.html#location) +- [Session persistence](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#enabling-session-persistence) +- [Active health checks](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/) +- [DNS-based service discovery](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service) + +--- + +## Content caching + +- [Static and dynamic content caching](https://docs.nginx.com/nginx/admin-guide/content-cache/content-caching/) +- MQTT protocol support for IoT devices + +**Limitation:** + +- [Cache purging API](https://docs.nginx.com/nginx/admin-guide/content-cache/content-caching/#purging-content-from-the-cache) is not available + +--- + +## Web server and reverse proxy + +- Origin server for static content +- Reverse proxy for [HTTP](https://nginx.org/en/docs/http/ngx_http_proxy_module.html), [FastCGI](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html), [memcached](https://nginx.org/en/docs/http/ngx_http_memcached_module.html), [SCGI](https://nginx.org/en/docs/http/ngx_http_scgi_module.html), and [uwsgi](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html) +- [HTTP/2 gateway](https://www.nginx.org/en/docs/http/ngx_http_v2_module.html) +- [gRPC proxy](https://nginx.org/en/docs/http/ngx_http_grpc_module.html) +- [HTTP/2 server push](https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_push) +- [HTTP/3 over QUIC](https://nginx.org/en/docs/http/ngx_http_v3_module.html) + +--- + +## Security + +- [HTTP basic authentication](https://www.nginx.org/en/docs/http/ngx_http_auth_basic_module.html) +- [Authentication subrequests](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html) (For external authentication systems) +- [IP-based access controls](https://nginx.org/en/docs/http/ngx_http_access_module.html) +- [Rate limiting](https://blog.nginx.org/blog/rate-limiting-nginx) +- Dual-stack RSA/ECC SSL/TLS offload +- TLS 1.3 support +- [JWT authentication](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html) +- OpenID Connect SSO +- NGINX as a SAML Service Provider +- [NGINX App Protect WAF](https://www.f5.com/products/nginx/nginx-app-protect) (Available at an extra cost) + +**Limitations:** + +- Internal redirect and App Protect DoS are not available + +--- + +## Monitoring + +- Export metrics directly into [Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/overview) +- Dashboards in [Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/overview) and [Azure Portal](https://azure.microsoft.com/en-us/get-started/azure-portal) +- [Extended status with 100+ metrics](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/) + +**Limitations:** + +- No built-in live dashboard like NGINX Plus; visibility is provided through Azure Monitor instead +- Native OpenTelemetry tracing is not available + +--- + +## High availability (HA) + +- [Active-active HA](https://docs.nginx.com/nginx/admin-guide/high-availability/) +- [Configuration synchronization across the cluster](https://docs.nginx.com/nginx/admin-guide/high-availability/configuration-sharing/) +- [State sharing](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/) for session persistence, rate limiting, and key-value store + +**Limitation:** + +- [Active-passive HA](https://docs.nginx.com/nginx/admin-guide/high-availability/) is not applicable in the managed service model + +--- + +## Programmability + +- [NGINX JavaScript (njs) module](https://www.f5.com/company/blog/nginx/harnessing-power-convenience-of-javascript-for-each-request-with-nginx-javascript-module) +- [Key-value store](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) + +**Limitations:** + +- [NGINX Plus API for dynamic reconfiguration](https://docs.nginx.com/nginx/admin-guide/load-balancer/dynamic-configuration-api/) is not available + +--- + +## Streaming media + +- Live streaming: RTMP, HLS, DASH +- VOD: Flash (FLV), MP4 + +**Limitations:** + +- Adaptive bitrate streaming (HLS/HDS) and [MP4 bandwidth controls](https://nginx.org/en/docs/http/ngx_http_mp4_module.html) are not available + +--- + +## Ecosystem and extensibility + +- Dynamic module support for: + - [Image-Filter](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html) + - [njs](https://nginx.org/en/docs/njs/) + - [OpenTelemetry](https://nginx.org/en/docs/ngx_otel_module.html) + - [XSLT](https://nginx.org/en/docs/http/ngx_http_xslt_module.html) +- Delivered as a managed service in Microsoft Azure +- [Commercial support](https://my.f5.com/manage/s/article/K000140156/) from F5 + +**Limitations:** + +- [Ingress Controller](https://www.f5.com/products/nginx/nginx-ingress-controller) and OpenShift Router are not included +- Dynamic module repository is limited compared to NGINX Plus + +--- + +{{< include "/nginx-plus/oss-plus-comparison.md" >}} diff --git a/content/nginxaas-azure/overview/overview.md b/content/nginxaas-azure/overview/overview.md index 01c6b65d2..1dac9cbb8 100644 --- a/content/nginxaas-azure/overview/overview.md +++ b/content/nginxaas-azure/overview/overview.md @@ -8,9 +8,9 @@ type: - concept --- -## What Is F5 NGINX as a Service for Azure? +## What Is F5 NGINXaaS for Azure? -NGINX as a Service for Azure is a service offering that is tightly integrated into Microsoft Azure public cloud and its ecosystem, making applications fast, efficient, and reliable with full lifecycle management of advanced NGINX traffic services. +NGINXaaS for Azure is a service offering that is tightly integrated into Microsoft Azure public cloud and its ecosystem, making applications fast, efficient, and reliable with full lifecycle management of advanced NGINX traffic services. NGINXaaS for Azure is available in the Azure Marketplace. NGINXaaS for Azure is powered by [NGINX Plus](https://www.nginx.com/products/nginx/), which extends NGINX Open Source with advanced functionality and provides customers with a complete application delivery solution. Initial use cases covered by NGINXaaS include L4 TCP and L7 HTTP load balancing and reverse proxy which can be managed through various Azure management tools. @@ -43,11 +43,11 @@ The key capabilities of NGINXaaS for Azure are: ## Supported regions NGINXaaS for Azure is supported in the following regions: -{{< bootstrap-table "table table-striped table-bordered" >}} +{{< table >}} | **North America** | **South America** | **Europe** | **Asia Pacific** | |----------------------------------------------------------|--------------------------------------------|--------------------------------------------|-------------------------| | West Central US
West US
East US 2
West US 2
West US 3
East US
Central US
North Central US
Canada Central | Brazil South | West Europe
North Europe
Sweden Central
Germany West Central
UK West
UK South | Australia East
Japan East
Korea Central
Southeast Asia
Central India
South India | -{{< /bootstrap-table >}} +{{< /table >}} ## NGINXaaS architecture @@ -82,4 +82,4 @@ With the Standard V2 Plan, NGINXaaS uses the following redundancy features to ke ## What's next -To get started, check the [NGINX as a Service for Azure prerequisites]({{< ref "/nginxaas-azure/getting-started/prerequisites.md" >}}) +To get started, check the [NGINXaaS for Azure prerequisites]({{< ref "/nginxaas-azure/getting-started/prerequisites.md" >}}) diff --git a/content/nginxaas-azure/quickstart/basic-caching.md b/content/nginxaas-azure/quickstart/basic-caching.md index 40b16402d..9c8060bfc 100644 --- a/content/nginxaas-azure/quickstart/basic-caching.md +++ b/content/nginxaas-azure/quickstart/basic-caching.md @@ -8,7 +8,7 @@ type: - how-to --- -F5 NGINX as a Service for Azure (NGINXaaS) supports caching using the [ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html) module, improving performance by allowing content to be served from cache without having to contact upstream servers. For more information on caching with NGINX, see [NGINX Content Caching](https://docs.nginx.com/nginx/admin-guide/content-cache/content-caching/). +F5 NGINXaaS for Azure (NGINXaaS) supports caching using the [ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html) module, improving performance by allowing content to be served from cache without having to contact upstream servers. For more information on caching with NGINX, see [NGINX Content Caching](https://docs.nginx.com/nginx/admin-guide/content-cache/content-caching/). ## Configuring caching ```nginx diff --git a/content/nginxaas-azure/quickstart/geoip2.md b/content/nginxaas-azure/quickstart/geoip2.md index 184f6530a..d5dd28639 100644 --- a/content/nginxaas-azure/quickstart/geoip2.md +++ b/content/nginxaas-azure/quickstart/geoip2.md @@ -9,7 +9,7 @@ type: ## Overview -F5 NGINX as a Service for Azure (NGINXaaS) supports GeoIP2 using the [`ngx_http_geoip2_module` or `ngx_stream_geoip2_module`](https://github.com/leev/ngx_http_geoip2_module) dynamic modules, enabling NGINXaaS to implement various user differentiation strategies. For more information on GeoIP2 with NGINX, see [NGINX GeoIP2](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/geoip2/). +F5 NGINXaaS for Azure (NGINXaaS) supports GeoIP2 using the [`ngx_http_geoip2_module` or `ngx_stream_geoip2_module`](https://github.com/leev/ngx_http_geoip2_module) dynamic modules, enabling NGINXaaS to implement various user differentiation strategies. For more information on GeoIP2 with NGINX, see [NGINX GeoIP2](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/geoip2/). NGINXaaS uses your MaxMind license to download GeoIP2 databases, puts them in the right place before NGINX starts, and updates the databases daily to reduce your operational overhead. All GeoIP2 data is deleted once you stop using GeoIP2 or delete your deployment. MaxMind provides a variety of [databases](https://www.maxmind.com/en/geoip-databases), including a lower accuracy [free option](https://www.maxmind.com/en/geolite2/signup). NGINXaaS uses a modified form of [MaxMind's `geoipupdate`](https://github.com/maxmind/geoipupdate). @@ -51,11 +51,11 @@ All licenses are [validated with MaxMind](https://dev.maxmind.com/license-key-va To view the status of your MaxMind license, [enable monitoring]({{< ref "/nginxaas-azure/monitoring/enable-monitoring.md" >}}) for your NGINXaaS deployment and navigate to the Metrics tab. View the `nginxaas.maxmind` metric under the `nginxaas statistics` metric namespace. The `nginxaas.maxmind` metric reports the health of your license through the `status` dimension: - {{}} + {{< table >}} | Status | Description | | -------------- | ------------------------------------------------------------------------------------------ | | `active` | The license is valid and in use to update GeoIP2 databases. | | `unauthorized` | MaxMind returned an license error, which usually indicates an issue with the `GeoIP.conf`. | - {{}} + {{< /table >}} diff --git a/content/nginxaas-azure/quickstart/hosting-static-content.md b/content/nginxaas-azure/quickstart/hosting-static-content.md index e72669cf7..13ad23211 100644 --- a/content/nginxaas-azure/quickstart/hosting-static-content.md +++ b/content/nginxaas-azure/quickstart/hosting-static-content.md @@ -8,7 +8,7 @@ type: - how-to --- -F5 NGINX as a Service for Azure (NGINXaaS) supports hosting static content which allows users to serve static websites from their deployment. +F5 NGINXaaS for Azure (NGINXaaS) supports hosting static content which allows users to serve static websites from their deployment. ## Uploading static files as a tarball @@ -32,7 +32,7 @@ http { The following shows the structure of a directory containing an NGINX configuration and an `index.html` file that we will be served from the deployment. -```bash +```shell test-static-files $ tree . . ├── nginx.conf @@ -46,7 +46,7 @@ test-static-files $ tree . 3. Create the tarball. -```bash +```shell test-static-files $ tar -cvzf /test.tar.gz * ``` diff --git a/content/nginxaas-azure/quickstart/njs-support.md b/content/nginxaas-azure/quickstart/njs-support.md index d3948e7a1..6dff418a1 100644 --- a/content/nginxaas-azure/quickstart/njs-support.md +++ b/content/nginxaas-azure/quickstart/njs-support.md @@ -8,7 +8,7 @@ type: - how-to --- -F5 NGINX as a Service for Azure (NGINXaaS) supports the open-source [njs module](https://nginx.org/en/docs/http/ngx_http_js_module.html), allowing the extension of NGINX functionality with a subset of the Javascript language. +F5 NGINXaaS for Azure (NGINXaaS) supports the open-source [njs module](https://nginx.org/en/docs/http/ngx_http_js_module.html), allowing the extension of NGINX functionality with a subset of the Javascript language. ## Upload NGINX configuration with njs diff --git a/content/nginxaas-azure/quickstart/rate-limiting.md b/content/nginxaas-azure/quickstart/rate-limiting.md index 59101ceb9..87749a864 100644 --- a/content/nginxaas-azure/quickstart/rate-limiting.md +++ b/content/nginxaas-azure/quickstart/rate-limiting.md @@ -8,7 +8,7 @@ type: - how-to --- -F5 NGINX as a Service for Azure (NGINXaaS) supports rate limiting using the [ngx_http_limit_req_module](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html) module to limit the processing rate of requests. For more information on rate limiting with NGINX, see [NGINX Limiting Access to Proxied HTTP Resources](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-http/) and [Rate Limiting with NGINX and NGINX Plus](https://www.nginx.com/blog/rate-limiting-nginx/). +F5 NGINXaaS for Azure (NGINXaaS) supports rate limiting using the [ngx_http_limit_req_module](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html) module to limit the processing rate of requests. For more information on rate limiting with NGINX, see [NGINX Limiting Access to Proxied HTTP Resources](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-http/) and [Rate Limiting with NGINX and NGINX Plus](https://www.nginx.com/blog/rate-limiting-nginx/). ## Configuring basic rate limiting diff --git a/content/nginxaas-azure/quickstart/recreate.md b/content/nginxaas-azure/quickstart/recreate.md index 06b515b5a..f2cf10cc6 100644 --- a/content/nginxaas-azure/quickstart/recreate.md +++ b/content/nginxaas-azure/quickstart/recreate.md @@ -8,7 +8,7 @@ type: - how-to --- -Learn how to recreate an existing F5 NGINX as a Service for Azure (NGINXaaS) deployment using an Azure Resource Manager (ARM) template. +Learn how to recreate an existing F5 NGINXaaS for Azure (NGINXaaS) deployment using an Azure Resource Manager (ARM) template. There are two ways to replicate a current NGINXaaS for Azure deployment using ARM templates. You can either delete and recreate the deployment, or you can update the DNS to smoothly transition to the new deployment. @@ -39,7 +39,7 @@ To recreate the deployment: 1. Delete the original deployment. 1. Use the exported ARM template to recreate the deployment using the Azure CLI: -```bash +```shell az deployment group create \ --subscription= \ --resource-group= \ diff --git a/content/nginxaas-azure/quickstart/runtime-state-sharing.md b/content/nginxaas-azure/quickstart/runtime-state-sharing.md index 4a0f3df87..1099542dc 100644 --- a/content/nginxaas-azure/quickstart/runtime-state-sharing.md +++ b/content/nginxaas-azure/quickstart/runtime-state-sharing.md @@ -8,7 +8,7 @@ type: - how-to --- -F5 NGINX as a Service for Azure (NGINXaaS) supports runtime state sharing using the [Zone Synchronization module](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html) to synchronize shared memory zones across NGINXaaS instances. +F5 NGINXaaS for Azure (NGINXaaS) supports runtime state sharing using the [Zone Synchronization module](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html) to synchronize shared memory zones across NGINXaaS instances. With runtime state sharing, NGINXaaS instances can share some state data between them, including: @@ -16,7 +16,7 @@ With runtime state sharing, NGINXaaS instances can share some state data between - [Rate limiting](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone) - [Key‑value store](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone) -{{< call-out "note" >}} Can not add the `sync` parameter with a directive describing shared memory zones to an existing memory zone that was not configured to sync. It also cannot be removed from an existing memory zone configured to sync. To switch, remove the directive before reapplying it with the desired parameters.{{< /call-out >}} +{{< call-out "note" >}} It's not possible to add the `sync` parameter with a directive describing shared memory zones to an existing memory zone that was not configured to sync. It also cannot be removed from an existing memory zone configured to sync. To switch, remove the directive before reapplying it with the desired parameters.{{< /call-out >}} For information on enabling synchronization for rate limiting with NGINXaaS for Azure, please visit the [Rate Limiting]({{< ref "/nginxaas-azure/quickstart/rate-limiting.md" >}}) documentation. diff --git a/content/nginxaas-azure/quickstart/scaling.md b/content/nginxaas-azure/quickstart/scaling.md index cf98d9656..afbff47df 100644 --- a/content/nginxaas-azure/quickstart/scaling.md +++ b/content/nginxaas-azure/quickstart/scaling.md @@ -8,7 +8,7 @@ type: - how-to --- -F5 NGINX as a Service for Azure (NGINXaaS) supports manual and automatic scaling of your deployment, allowing you to adapt to application traffic demands while controlling cost. +F5 NGINXaaS for Azure (NGINXaaS) supports manual and automatic scaling of your deployment, allowing you to adapt to application traffic demands while controlling cost. {{< call-out "note" >}}This feature is only available for Standard plan(s).{{< /call-out >}} @@ -65,12 +65,12 @@ To avoid creating a loop between scaling rules, NGINXaaS will not apply a scalin The following table outlines constraints on the specified capacity based on the chosen Marketplace plan, including the minimum capacity required for a deployment to be highly available, the maximum capacity, and what value the capacity must be a multiple of. By default, an NGINXaaS for Azure deployment will be created with the corresponding minimum capacity. -{{}} +{{< table >}} | **Marketplace Plan** | **Minimum Capacity (NCUs)** | **Maximum Capacity (NCUs)** | **Multiple of** | |------------------------------|-----------------------------|-----------------------------|----------------------------| | Standard plan(s) | 10 | 500 | 10 | -{{}} +{{< /table >}} {{< call-out "note" >}}If you need a higher maximum capacity, please [open a request](https://my.f5.com/manage/s/) and specify the Resource ID of your NGINXaaS deployment, the region, and the desired maximum capacity you wish to scale to.{{< /call-out >}} diff --git a/content/nginxaas-azure/quickstart/security-controls/auth-basic.md b/content/nginxaas-azure/quickstart/security-controls/auth-basic.md index fad9f819a..d9aee1f78 100644 --- a/content/nginxaas-azure/quickstart/security-controls/auth-basic.md +++ b/content/nginxaas-azure/quickstart/security-controls/auth-basic.md @@ -14,7 +14,7 @@ For more information on configuring HTTP Basic Authentication please refer to th ## Uploading a password file -F5 NGINX as a Service for Azure (NGINXaaS) accepts a file containing usernames and passwords using any of the password types specified in the [NGINX documentation](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html#auth_basic_user_file). The password file can be uploaded as a "protected file" when creating or updating your NGINX configuration to protect the file's contents from being read. The password file can alternatively be uploaded as a regular file. +F5 NGINXaaS for Azure (NGINXaaS) accepts a file containing usernames and passwords using any of the password types specified in the [NGINX documentation](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html#auth_basic_user_file). The password file can be uploaded as a "protected file" when creating or updating your NGINX configuration to protect the file's contents from being read. The password file can alternatively be uploaded as a regular file. {{< img src="nginxaas-azure/auth-basic-htpasswd.png" alt="Screenshot of the Azure portal showing the password file upload" >}} diff --git a/content/nginxaas-azure/quickstart/security-controls/certificates.md b/content/nginxaas-azure/quickstart/security-controls/certificates.md index 089347888..cfce20494 100644 --- a/content/nginxaas-azure/quickstart/security-controls/certificates.md +++ b/content/nginxaas-azure/quickstart/security-controls/certificates.md @@ -9,7 +9,7 @@ type: ## Overview -This tutorial walks through a complete example of using SSL/TLS certificates from Azure Key Vault in an F5 NGINX as a Service for Azure (NGINXaaS) deployment to secure traffic. In this guide, you will create all necessary resources to add a certificate to an NGINXaaS deployment using the [Azure portal](https://portal.azure.com/). +This tutorial walks through a complete example of using SSL/TLS certificates from Azure Key Vault in an F5 NGINXaaS for Azure (NGINXaaS) deployment to secure traffic. In this guide, you will create all necessary resources to add a certificate to an NGINXaaS deployment using the [Azure portal](https://portal.azure.com/). ## Create an Azure Key Vault (AKV) @@ -20,14 +20,14 @@ NGINXaaS enables customers to securely store SSL/TLS certificates in Azure Key V 1. Select **Create**. 1. On the Create a key vault **Basics** tab, provide the following information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | | Subscription | Select the appropriate Azure subscription that you have access to. | | Resource group | Specify whether you want to create a new resource group or use an existing one.
For more information, see [Azure Resource Group overview](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview). | | Key vault name | Provide a unique name for your key vault. For this tutorial, we use `nginxaas-kv`. | | Region | Select the region you want to deploy to. | - {{}} + {{< /table >}} For all other fields, you can leave them set to the default values. 1. Select **Review + Create** and then **Create**. @@ -46,14 +46,14 @@ Next, you can add an SSL/TLS certificate to your key vault by following [Azure's 1. Select **Certificates** in the left menu. 1. Select {{< icon "plus">}}**Generate/Import** and provide the following information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | | Method of Certificate Creation | Select **Generate** | | Certificate Name | Provide a unique name for your certificate. For this tutorial, we use `nginxaas-cert`. | | Type of Certificate Authority (CA) | Select **Self-signed certificate**. | | CN | Provide the IP address of your NGINXaaS deployment as the CN. For example, `CN=135.237.74.224` | - {{}} + {{< /table >}} For all other fields, you can leave them set to the default values. @@ -70,14 +70,14 @@ In order for your NGINXaaS deployment to access your key vault, it must have an 1. Under **System assigned**, select **Azure role assignments**. 1. Select {{< icon "plus">}}**Add role assignment** and provide the following information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | | Scope | Select **Key Vault**. | | Subscription | Select the Azure subscription your key vault is in. | | Resource | Select your key vault, `nginxaas-kv`. | | Role | Select **Key Vault Secrets User**. | - {{}} + {{< /table >}} 1. Select **Save**. @@ -88,22 +88,22 @@ Now, you can add your SSL/TLS certificate from your key vault to your NGINXaaS d 1. Go to your NGINXaaS deployment. 1. Select **NGINX certificates** in the left menu. 1. Select {{< icon "plus">}}**Add certificate** and provide the following information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | | Name | A unique name for the certificate. For this tutorial, we use `my-cert`. | | Certificate path | Set to `/etc/nginx/ssl/example.crt`. | | Key path | Set to `/etc/nginx/ssl/example.key`. | - {{}} + {{< /table >}} 1. Select **Select certificate** and provide the following information: - {{}} + {{< table >}} | Field | Description | |----------------------- | ---------------------------- | | Key vault | Select `nginxaas-kv`. | | Certificate | Select `nginxaas-cert`. | - {{}} + {{< /table >}} 1. Select **Add certificate**. @@ -168,7 +168,7 @@ If you want to disable public access to your key vault, you can configure a [Net 1. In the Search box, enter **Network Security Perimeters** and select **Network Security Perimeters** from the search results. 1. Select {{< icon "plus">}}**Create**. 1. In the **Basics** tab, provide the following information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | | Subscription | Select the appropriate Azure subscription that you have access to. | @@ -176,17 +176,17 @@ If you want to disable public access to your key vault, you can configure a [Net | Name | Provide a unique name for your network security perimeter. For this tutorial, we use `nginxaas-nsp`. | | Region | Select the region you want to deploy to. Refer to any [regional limitations](https://learn.microsoft.com/en-us/azure/private-link/network-security-perimeter-concepts#regional-limitations) NSP has while in public preview. | | Profile name | Leave the profile name as the default `defaultProfile`. | - {{}} + {{< /table >}} 1. In the **Resources** tab, select {{< icon "plus">}}**Add**. 1. Search for your key vault, `nginxaas-kv`, select it, and click **Select**. 1. In the **Inbound access rules** tab, select {{< icon "plus">}}**Add** and provide the following information: - {{}} + {{< table >}} | Field | Description | |---------------------------- | ---------------------------- | | Rule Name | Set to `allow-nginxaas-deployment-sub`. | | Source Type | Select **Subscriptions**. | | Allowed sources | Select the subscription of your NGINXaaS deployment. | - {{}} + {{< /table >}} 1. Select **Review + Create** and then **Create**. By default, the key vault will be associated to the NSP in [Learning mode](https://learn.microsoft.com/en-us/azure/private-link/network-security-perimeter-concepts#access-modes-in-network-security-perimeter). This means traffic will be evaluated first based on the NSP's access rules. If no rules apply, evaluation will fall back to the key vault's firewall configuration. To fully secure public access, it is reccommended to [transition to Enforced mode](https://learn.microsoft.com/en-us/azure/private-link/network-security-perimeter-transition#transition-to-enforced-mode-for-existing-resources). diff --git a/content/nginxaas-azure/quickstart/security-controls/jwt.md b/content/nginxaas-azure/quickstart/security-controls/jwt.md index 0d176ebcf..f3c9f3513 100644 --- a/content/nginxaas-azure/quickstart/security-controls/jwt.md +++ b/content/nginxaas-azure/quickstart/security-controls/jwt.md @@ -8,7 +8,7 @@ type: - how-to --- -F5 NGINX as a Service for Azure (NGINXaaS) provides the option to control access to your resources using JWT authentication. With JWT authentication, a client provides a JSON Web Token, and the token will be validated against a local key file or a remote service. This document will explain how to validate tokens using Microsoft Entra as the remote service. +F5 NGINXaaS for Azure (NGINXaaS) provides the option to control access to your resources using JWT authentication. With JWT authentication, a client provides a JSON Web Token, and the token will be validated against a local key file or a remote service. This document will explain how to validate tokens using Microsoft Entra as the remote service. For more information on JWT authentication with NGINX+, please refer to [ngx_http_auth_jwt_module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html) and [NGINX Plus Setting up JWT Authentication](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-jwt-authentication/). diff --git a/content/nginxaas-azure/quickstart/security-controls/oidc.md b/content/nginxaas-azure/quickstart/security-controls/oidc.md index e67db825a..2ac04588c 100644 --- a/content/nginxaas-azure/quickstart/security-controls/oidc.md +++ b/content/nginxaas-azure/quickstart/security-controls/oidc.md @@ -10,7 +10,7 @@ type: ## Overview -Learn how to configure F5 NGINX as a Service (NGINXaaS) for Azure with OpenID Connect (OIDC) authentication. +Learn how to configure F5 NGINXaaS for Azure with OpenID Connect (OIDC) authentication. ## Prerequisites @@ -21,7 +21,7 @@ Learn how to configure F5 NGINX as a Service (NGINXaaS) for Azure with OpenID Co 3. [Configure the IdP](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#configuring-your-idp). For example, you can [register a Microsoft Entra Web application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) as the IdP. -## Configure NGINX as a Service for Azure with IdP +## Configure NGINXaaS for Azure with IdP Configuring NGINXaaS for Azure with OIDC is similar as [Configuring NGINX Plus](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#configuring-nginx-plus) in [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) but it also has its own specific configurations that must be completed to work normally. diff --git a/content/nginxaas-azure/quickstart/security-controls/private-link-to-upstreams.md b/content/nginxaas-azure/quickstart/security-controls/private-link-to-upstreams.md index 39b285b1a..69089b5b3 100644 --- a/content/nginxaas-azure/quickstart/security-controls/private-link-to-upstreams.md +++ b/content/nginxaas-azure/quickstart/security-controls/private-link-to-upstreams.md @@ -38,7 +38,7 @@ The following example demonstrates this process using an existing virtual machin Please ensure the following environment variables are exported before copying the below Azure CLI commands. -{{}} +{{< table >}} | Name | Description | |------------------ | ----------------- | | APP_LOCATION | Location of the resource group @@ -48,11 +48,11 @@ Please ensure the following environment variables are exported before copying th | APP_VM_NAME | Name of the workload virtual machine | | APP_NIC_NAME | Name of the network interface of the virtual machine | | APP_IP_CONFIG_NAME | Name of the IP configuration associated with the NIC | -{{}} +{{< /table >}} ### Create a load balancer -```bash +```shell $ az network lb create \ --resource-group $APP_RESOURCE_GROUP \ --name load-balancer \ @@ -75,7 +75,7 @@ upstream { Create a health probe monitoring on port `8000`: -```bash +```shell $ az network lb probe create \ --resource-group $APP_RESOURCE_GROUP \ --lb-name load-balancer \ @@ -86,7 +86,7 @@ $ az network lb probe create \ Create a load balancing rule listening on port `8000`: -```bash +```shell $ az network lb rule create \ --resource-group $APP_RESOURCE_GROUP \ --lb-name load-balancer \ @@ -103,7 +103,7 @@ $ az network lb rule create \ ### Configure the workload VM behind the load balancer -```bash +```shell $ az network nic ip-config address-pool add \ --address-pool backend-pool \ --ip-config-name $APP_IP_CONFIG_NAME \ @@ -116,7 +116,7 @@ $ az network nic ip-config address-pool add \ The `privateLinkServiceNetworkPolicies` setting must be disabled to add a private link service in a virtual network. -```bash +```shell $ az network vnet subnet update \ --name $APP_SUBNET_NAME \ --vnet-name $APP_VNET_NAME \ @@ -126,7 +126,7 @@ $ az network vnet subnet update \ ### Create a private link service -```bash +```shell $ az network private-link-service create \ --resource-group $APP_RESOURCE_GROUP \ --name private-link-service \ @@ -161,20 +161,20 @@ The following example demonstrates this process using an existing NGINXaaS deplo Please ensure the following environment variables are exported before copying the below Azure CLI commands. -{{}} +{{< table >}} | Name | Description | |------------------ | ----------------- | | DEP_RESOURCE_GROUP | Name of the resource group the NGINXaaS deployment is in | | DEP_VNET_NAME | Name of the virtual network the NGINXaaS deployment is in | | PRIVATE_ENDPOINT_SUBNET_ADDRESS_SPACE | Desired address space of the private endpoint's subnet | | PRIVATE_LINK_SERVICE_ID | Resource ID of the Private Link service | -{{}} +{{< /table >}} ### Create a new subnet You must create a new subnet for the private endpoint because the existing NGINXaaS deployment's subnet is already delegated. -```bash +```shell $ az network vnet subnet create \ --resource-group $DEP_RESOURCE_GROUP \ --vnet-name $DEP_VNET_NAME \ @@ -184,7 +184,7 @@ $ az network vnet subnet create \ ### Create a private endpoint -```bash +```shell $ az network private-endpoint create \ --connection-name connection-1 \ --name private-endpoint \ @@ -199,7 +199,7 @@ $ az network private-endpoint create \ First, get the IP address of the private endpoint: -```bash +```shell $ export nic_id=$(az network private-endpoint show \ --resource-group $DEP_RESOURCE_GROUP \ --name private-endpoint \ diff --git a/content/nginxaas-azure/quickstart/security-controls/securing-upstream-traffic.md b/content/nginxaas-azure/quickstart/security-controls/securing-upstream-traffic.md index a3c4fcedd..e26d7d8d7 100644 --- a/content/nginxaas-azure/quickstart/security-controls/securing-upstream-traffic.md +++ b/content/nginxaas-azure/quickstart/security-controls/securing-upstream-traffic.md @@ -8,7 +8,7 @@ type: - how-to --- -Learn how to encrypt HTTP traffic between F5 NGINX as a Service for Azure (NGINXaaS) and an upstream group or a proxied server. To secure TCP traffic to upstream servers, follow the [NGINX Plus guide](https://docs.nginx.com/nginx/admin-guide/security-controls/securing-tcp-traffic-upstream/). As with securing HTTP traffic, you will need to [add the SSL/TLS client certificate]({{< ref "/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-portal.md">}}) to the NGINXaaS deployment. +Learn how to encrypt HTTP traffic between F5 NGINXaaS for Azure (NGINXaaS) and an upstream group or a proxied server. To secure TCP traffic to upstream servers, follow the [NGINX Plus guide](https://docs.nginx.com/nginx/admin-guide/security-controls/securing-tcp-traffic-upstream/). As with securing HTTP traffic, you will need to [add the SSL/TLS client certificate]({{< ref "/nginxaas-azure/getting-started/ssl-tls-certificates/ssl-tls-certificates-portal.md">}}) to the NGINXaaS deployment. ### Prerequisites diff --git a/content/nginxaas-azure/quickstart/upgrade-channels.md b/content/nginxaas-azure/quickstart/upgrade-channels.md index f4f5db09b..fb9f5be31 100644 --- a/content/nginxaas-azure/quickstart/upgrade-channels.md +++ b/content/nginxaas-azure/quickstart/upgrade-channels.md @@ -10,14 +10,14 @@ type: ## Overview -Maintaining the latest version NGINX Plus, operating system (OS), and other software dependencies is a key feature offered by F5 NGINX as a Service for Azure (NGINXaaS). The **Upgrade Channel** is an upgrade path to which you can subscribe your NGINXaaS deployment to control the timing of software upgrades. The following channels are available: +Maintaining the latest version NGINX Plus, operating system (OS), and other software dependencies is a key feature offered by F5 NGINXaaS for Azure (NGINXaaS). The **Upgrade Channel** is an upgrade path to which you can subscribe your NGINXaaS deployment to control the timing of software upgrades. The following channels are available: -{{}} +{{< table >}} | Channel | Description | |-------------|---------------------------| | preview | Selecting this channel automatically upgrades your deployment to the latest supported version of NGINX Plus and its dependencies soon after they become available. We recommend using this setting to try out new capabilities in deployments running in your development, testing, and staging environments. Do not use the **Preview** channel in your production environment. | | stable | A deployment running on this channel will receive updates on NGINX Plus and its dependencies at a slower rate than the **Preview** channel. We recommend using this setting for production deployments where you might want stable features instead of the latest ones. This is the **default channel** if you do not specify one for your deployment. | -{{}} +{{< /table >}} {{< call-out "note" >}} All channels will receive continuous updates related to OS patches, and security fixes. {{< /call-out >}} @@ -26,12 +26,12 @@ Maintaining the latest version NGINX Plus, operating system (OS), and other soft ### NGINX Plus and related modules -{{}} +{{< table >}} | Channel | Availablity of NGINX Plus and related modules | |-------------|-----------------------------------------------| | preview | No sooner than 14 days of a new NGINX Plus [release](https://docs.nginx.com/nginx/releases/). | | stable | No sooner than 45 days of a new NGINX Plus [release](https://docs.nginx.com/nginx/releases/). | -{{}} +{{< /table >}} A new version of NGINX Plus and its related modules is first introduced to the **preview** channel, where it is goes through our acceptance testing. Once we have baked the software in the **preview** channel for a reasonable time, it is eventually graduated to the **stable** channel. The actual promotion timelines can vary, and you can view our [Changelog]({{< ref "/nginxaas-azure/changelog.md" >}}) for latest updates. diff --git a/content/nic/_index.md b/content/nic/_index.md index d6187bf7a..cbde101dc 100644 --- a/content/nic/_index.md +++ b/content/nic/_index.md @@ -1,6 +1,6 @@ --- # The title is the product name -title: NGINX Ingress Controller +title: F5 NGINX Ingress Controller # The URL is the base of the deployed path, becoming "docs.nginx.com//" url: /nginx-ingress-controller/ # The cascade directive applies its nested parameters down the page tree until overwritten diff --git a/content/nic/configuration/global-configuration/command-line-arguments.md b/content/nic/configuration/global-configuration/command-line-arguments.md index 07f5d6f98..f59e990fc 100644 --- a/content/nic/configuration/global-configuration/command-line-arguments.md +++ b/content/nic/configuration/global-configuration/command-line-arguments.md @@ -658,6 +658,20 @@ The default value is `false`. --- +### -enable-directive-autoadjust + +Automatically adjusts NGINX buffer directives to prevent configuration errors. + +The default value is `false`. + +When enabled, the controller automatically adjusts `proxy_buffers`, `proxy_buffer_size`, and `proxy_busy_buffers_size` to ensure they work together properly and NGINX can start successfully. + +More explanation about this feature can be found in the guide [here](). + + + +--- + ### -enable-telemetry-reporting Enable gathering and reporting of software telemetry. diff --git a/content/nic/configuration/global-configuration/configmap-resource.md b/content/nic/configuration/global-configuration/configmap-resource.md index d854bebc6..4910a66d2 100644 --- a/content/nic/configuration/global-configuration/configmap-resource.md +++ b/content/nic/configuration/global-configuration/configmap-resource.md @@ -28,7 +28,7 @@ that make sense for your setup: client-max-body-size: "2m" ``` - See the section [Summary of ConfigMap Keys](#summary-of-configmap-keys) for the explanation of the available ConfigMap keys (such as `proxy-connect-timeout` in this example). + See the section [Summary of ConfigMap Keys](#configmap-keys) for the explanation of the available ConfigMap keys (such as `proxy-connect-timeout` in this example). 1. Create a new (or update the existing) ConfigMap resource: @@ -75,6 +75,7 @@ For more information, view the [VirtualServer and VirtualServerRoute resources]( |*proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | |*proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | |*proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +|*proxy-busy-buffers-size* | Sets the value of the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. | Depends on the platform. | | |*proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | |*set-real-ip-from* | Sets the value of the [set_real_ip_from](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A | | |*real-ip-header* | Sets the value of the [real_ip_header](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | *X-Real-IP* | | @@ -171,7 +172,7 @@ If you encounter the error `error [emerg] 13#13: "zone_sync" directive is duplic |ConfigMap Key | Description | Default | | ---| ---| ---| -|*zone-sync* | Enables zone synchronization between NGINX Ingress Controller Pods. This autogenerates a [zone_sync_server](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_server) and a headless service using the `ReplicaSet` or `DaemonSet` name. Please note that this headless service will be automatically cleaned up when uninstalling via Helm or by removing the value from the ConfigMap. The headless service will need to be manually removed if the `controller.customConfigMap` value is set via Helm or the deployment is uninstalled via Manifests. Each Ingress Controller manages its own headless service. NGINX Plus Required. | *False* | +|*zone-sync* | Enables zone synchronization between NGINX Ingress Controller Pods. This autogenerates a [zone_sync_server](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_server) and a headless service using the `ReplicaSet`, `DaemonSet` or `StatefulSet` name. Please note that this headless service will be automatically cleaned up when uninstalling via Helm or by removing the value from the ConfigMap. The headless service will need to be manually removed if the `controller.customConfigMap` value is set via Helm or the deployment is uninstalled via Manifests. Each Ingress Controller manages its own headless service. NGINX Plus Required. | *False* | |*zone-sync-port* | Specifies the optional port on which NGINX Ingress Controller listens for zone sync traffic. NGINX Plus & `zone-sync` Required. | *12345* | |*zone-sync-resolver-addresses* | Configures optional addresses used in the [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync. This field takes a comma separated list of addresses. NGINX Plus & `zone-sync` Required | `kube-dns.kube-system.svc.cluster.local` | |*zone-sync-resolver-ipv6* | Configures whether the optional [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync will look up IPv6 addresses. NGINX Plus & `zone-sync` Required | `true` | diff --git a/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md b/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md index 7bbdb4685..f378fdddf 100644 --- a/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -108,6 +108,7 @@ The table below summarizes the available annotations. | *nginx.org/proxy-buffering* | *proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | | *nginx.org/proxy-buffers* | *proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | | *nginx.org/proxy-buffer-size* | *proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +| *nginx.org/proxy-busy-buffers-size* | *proxy-busy-buffers-size* | Sets the value of the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. | Depends on the platform. | | | *nginx.org/proxy-max-temp-file-size* | *proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | | *nginx.org/server-tokens* | *server-tokens* | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the “Server” field. | *True* | | | *nginx.org/path-regex* | N/A | Enables regular expression modifiers for Ingress path parameter. This translates to the NGINX [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive. You can specify one of these values: "case_sensitive", "case_insensitive", or "exact". The annotation is applied to the entire Ingress resource and its paths. While using Master and Minion Ingresses i.e. Mergeable Ingresses, this annotation can be specified on Minion types. The `path-regex` annotation specified on Master is ignored, and has no effect on paths defined on Minions. | N/A | [path-regex](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/path-regex) | diff --git a/content/nic/configuration/policy-resource.md b/content/nic/configuration/policy-resource.md index fd4fb4df8..5edf8b2d0 100644 --- a/content/nic/configuration/policy-resource.md +++ b/content/nic/configuration/policy-resource.md @@ -44,6 +44,8 @@ spec: |``ingressMTLS`` | The IngressMTLS policy configures client certificate verification. | [ingressMTLS](#ingressmtls) | No | |``egressMTLS`` | The EgressMTLS policy configures upstreams authentication and certificate verification. | [egressMTLS](#egressmtls) | No | |``waf`` | The WAF policy configures WAF and log configuration policies for [NGINX AppProtect]({{< ref "/nic/installation/integrations/app-protect-waf/configuration.md" >}}) | [WAF](#waf) | No | +|``cache`` | The cache policy configures proxy caching for serving cached content. | [cache](#cache) | No | + {{% /table %}} \* A policy must include exactly one policy. @@ -446,12 +448,14 @@ This feature is implemented using the NGINX Plus directive [auth_jwt_key_request {{< /call-out >}} {{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``jwksURI`` | The remote URI where the request will be sent to retrieve JSON Web Key set| ``string`` | Yes | -|``keyCache`` | Enables in-memory caching of JWKS (JSON Web Key Sets) that are obtained from the ``jwksURI`` and sets a valid time for expiration. To disable ``keyCache``, set value to ``0s``. | ``string`` | Yes | -|``realm`` | The realm of the JWT. | ``string`` | Yes | -|``token`` | The token specifies a variable that contains the JSON Web Token. By default the JWT is passed in the ``Authorization`` header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string, for example: ``$cookie_auth_token``. Accepted variables are ``$http_``, ``$arg_``, ``$cookie_``. | ``string`` | No | +|Field | Description | Type | Required | Default | +| ---| ---| ---| --- | --- | +|``jwksURI`` | The remote URI where the request will be sent to retrieve JSON Web Key set| ``string`` | Yes | -- | +|``keyCache`` | Enables in-memory caching of JWKS (JSON Web Key Sets) that are obtained from the ``jwksURI`` and sets a valid time for expiration. | ``string`` | Yes | -- | +|``realm`` | The realm of the JWT. | ``string`` | Yes | -- | +|``token`` | The token specifies a variable that contains the JSON Web Token. By default the JWT is passed in the ``Authorization`` header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string, for example: ``$cookie_auth_token``. Accepted variables are ``$http_``, ``$arg_``, ``$cookie_``. | ``string`` | No | -- | +|``sniEnabled`` | Enables SNI (Server Name Indication) for the JWT policy. This is useful when the remote server requires SNI to serve the correct certificate. | ``bool`` | No | `false` | +|``sniName`` | The SNI name to use when connecting to the remote server. If not set, the hostname from the ``jwksURI`` will be used. | ``string`` | No | -- | {{% /table %}} {{< call-out "note" >}} @@ -738,6 +742,57 @@ policies: In this example NGINX Ingress Controller will use the configuration from the first policy reference `oidc-policy-one`, and ignores `oidc-policy-two`. +### Cache + +The cache policy configures proxy caching, which improves performance by storing and serving cached responses to clients without having to proxy every request to upstream servers. + +For example, the following policy creates a cache zone named "my-cache" with 10MB memory allocation and caches all GET response codes for 30 seconds: + +```yaml +cache: + cacheZoneName: "mycache" + cacheZoneSize: "10m" + allowedCodes: ["any"] + allowedMethods: ["GET"] + time: "30s" +``` + +Here's an example with more specific configuration: + +```yaml +cache: + cacheZoneName: "mycache" + cacheZoneSize: "100m" + allowedCodes: [200, 301, 302] + allowedMethods: ["GET", "POST"] + time: "5m" + levels: "1:2" + overrideUpstreamCache: true +``` + +{{< call-out "note" >}} + +The feature is implemented using the NGINX [ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path) proxy_cache_path and related directives. + +{{< /call-out >}} + +{{% table %}} +|Field | Description | Type | Required | +| --- | ---| ---| --- | +| ``cacheZoneName`` | CacheZoneName defines the name of the cache zone. Must start with a lowercase letter,followed by alphanumeric characters or underscores, and end with an alphanumeric character. Single lowercase letters are also allowed. Examples: "cache", "my_cache", "cache1". | ``string`` | Yes | +|``cacheZoneSize`` | CacheZoneSize defines the size of the cache zone. Must be a number followed by a size unit: 'k' for kilobytes, 'm' for megabytes, or 'g' for gigabytes. Examples: "10m", "1g", "512k". | ``string`` | Yes | +|``allowedCodes`` | AllowedCodes defines which HTTP response codes should be cached. Accepts either: - The string "any" to cache all response codes (must be the only element) - A list of HTTP status codes as integers (100-599) Examples: ["any"], [200, 301, 404], [200]. Invalid: ["any", 200] (cannot mix "any" with specific codes). | ``[]IntOrString`` | No | +|``time`` | The default cache time for responses. Required when allowedCodes is specified. Must be a number followed by a time unit: 's' for seconds, 'm' for minutes, 'h' for hours, 'd' for days. Examples: "30s", "5m", "1h", "2d". | ``string`` | No | +|``allowedMethods`` | AllowedMethods defines which HTTP methods should be cached. Only "GET", "HEAD", and "POST" are supported by NGINX proxy_cache_methods directive. GET and HEAD are always cached by default even if not specified. Maximum of 3 items allowed. Examples: ["GET"], ["GET", "HEAD", "POST"]. Invalid methods: PUT, DELETE, PATCH, etc. | ``[]string`` | No | +|``levels`` | Levels defines the cache directory hierarchy levels for storing cached files. Must be in format "X:Y" or "X:Y:Z" where X, Y, Z are either 1 or 2. This controls the number of subdirectory levels and their name lengths. Examples: "1:2", "2:2", "1:2:2". Invalid: "3:1", "1:3", "1:2:3". | ``string`` | No | +|``overrideUpstreamCache`` | OverrideUpstreamCache controls whether to override upstream cache headers (using proxy_ignore_headers directive). When true, NGINX will ignore cache-related headers from upstream servers like Cache-Control, Expires etc, Default: false. | ``bool`` | No | +|``cachePurgeAllow`` | CachePurgeAllow defines IP addresses or CIDR blocks allowed to purge cache. This feature is only available in NGINX Plus. Examples: ["192.168.1.100", "10.0.0.0/8", "::1"]. | ``[]string`` | No | +{{% /table %}} + +#### Cache Merging Behavior + +A VirtualServer/VirtualServerRoute can reference multiple cache policies. However, only one can be applied: every subsequent reference will be ignored. + ## Using Policy You can use the usual `kubectl` commands to work with Policy resources, just as with built-in Kubernetes resources. diff --git a/content/nic/configuration/proxy-buffers-configuration.md b/content/nic/configuration/proxy-buffers-configuration.md new file mode 100644 index 000000000..bfb63511d --- /dev/null +++ b/content/nic/configuration/proxy-buffers-configuration.md @@ -0,0 +1,145 @@ +--- +title: Proxy Buffer Configuration Auto-Adjustment +toc: true +weight: 850 +nd-docs: DOCS-590 +--- + +This document explains how the `--enable-directive-autoadjust` option prevents NGINX configuration errors by automatically adjusting some HTTP proxy buffer directives. + +--- +## What it does + +The `--enable-directive-autoadjust` feature automatically fixes common proxy buffer configuration mistakes that would otherwise cause NGINX to fail with errors like: + +```text +[emerg] "proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer +``` + +**What gets fixed:** +- If you don't specify `proxy_buffers`, it sets a sensible default of `8 4k` +- If your `proxy_busy_buffers_size` is too large, it reduces it to a safe value +- If the number of proxy buffers is outside the valid range (minimum 2, maximum 1024), it gets clamped to those limits +- Empty or invalid buffer settings get corrected automatically + +**Works with:** +- [ConfigMap settings]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#general-customization" >}}) +- [Ingress annotations]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations/#general-customization" >}}) +- [VirtualServer upstream buffer configurations]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources/#upstream" >}}) +--- + +## How to enable auto-adjustment +{{}} +{{% tab name="Manifests" %}} +Add the flag to the controller container: +```yaml + args: + - --enable-directive-autoadjust=true +``` +{{% /tab %}} +{{% tab name="Helm" %}} +Enable via the Helm chart values file: +```yaml +controller: + directiveAutoAdjust: "true" +``` +{{% /tab %}} +{{}} + +--- +## Examples + +### Example 1 + +**Input:** +```yaml +data: + proxy-buffer-size: "5m" + proxy-buffers: "8 1m" +``` + +{{}} + +{{% tab name="Before (Error)" %}} + +Before enabling `--enable-directive-autoadjust`, NGINX fails to start with configuration validation errors. + +```shell +stderr: "2025/08/26 14:29:49 [emerg] 196#196: "proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer in /etc/nginx/nginx.conf:121" +``` + +{{% /tab %}} + +{{% tab name="After (Fixed)" %}} + +With `--enable-directive-autoadjust`, the configuration is automatically adjusted: + +```nginx + proxy_buffers 8 1m; + proxy_buffer_size 5m; + proxy_busy_buffers_size 5m; +``` + +Logs: +```text +I20250826 14:31:54.515490 1 configmaps.go:380] Changes made to proxy values: adjusted proxy_busy_buffers_size from to 5m because it was too small +``` + +{{% /tab %}} + +{{}} + +### Example 2 + +**Input:** +```yaml +data: + proxy-buffers: "1000000 1m" # Extremely high buffer count + proxy-buffer-size: "999m" # Very large buffer size + proxy-busy-buffers-size: "500m" +``` + +{{}} + +{{% tab name="Before (Error)" %}} + +```shell +stderr: "2025/08/26 14:34:46 [emerg] 47#47: "proxy_busy_buffers_size" must be equal to or greater than the maximum of the value of "proxy_buffer_size" and one of the "proxy_buffers" in /etc/nginx/nginx.conf:121\n" +``` + +{{% /tab %}} + +{{% tab name="After (Fixed)" %}} + +With `--enable-directive-autoadjust`, sensible defaults are applied: + +```shell + proxy_buffers 1024 1m; + proxy_buffer_size 999m; + proxy_busy_buffers_size 999m; +``` + +Logs: +```shell +I20250826 14:36:47.864375 1 configmaps.go:380] Changes made to proxy values: adjusted proxy_buffers number from 1000000 to 1024 +I20250826 14:36:47.864389 1 configmaps.go:380] Changes made to proxy values: adjusted proxy_busy_buffers_size from 500m to 999m because it was too small +``` + +{{% /tab %}} + +{{}} + +--- +## Monitoring and logging + +The controller outputs a log message whenever any of the proxy buffer directives are changed. Examples: + +```text +I20250826 14:06:43.734757 1 annotations.go:341] Changes made to proxy values: adjusted proxy_buffer_size from 512k to 64k because it was too big for proxy_buffers (2 64k) +I20250826 14:06:43.734842 1 annotations.go:341] Changes made to proxy values: adjusted proxy_busy_buffers_size from to 64k because it was too small +``` + +View adjustment logs: +```bash +kubectl logs -n | grep "Changes made to proxy values" +``` \ No newline at end of file diff --git a/content/nic/configuration/security.md b/content/nic/configuration/security.md index ad561cb21..e44d99e87 100644 --- a/content/nic/configuration/security.md +++ b/content/nic/configuration/security.md @@ -53,10 +53,12 @@ The block below shows the code you will look for: # volumes: # - name: nginx-etc # emptyDir: {} -# - name: nginx-cache -# emptyDir: {} +# - name: nginx-cache # do not set this value in statefulset if volumeclaimtemplate is set +# emptyDir: {} # do not set this value in statefulset if volumeclaimtemplate is set # - name: nginx-lib # emptyDir: {} +# - name: nginx-lib-state +# emptyDir: {} # - name: nginx-log # emptyDir: {} . @@ -73,6 +75,8 @@ The block below shows the code you will look for: # name: nginx-cache # - mountPath: /var/lib/nginx # name: nginx-lib +# - mountPath: /var/lib/nginx/state +# name: nginx-lib-state # - mountPath: /var/log/nginx # name: nginx-log ``` diff --git a/content/nic/configuration/virtualserver-and-virtualserverroute-resources.md b/content/nic/configuration/virtualserver-and-virtualserverroute-resources.md index 3a0a782e4..670599c36 100644 --- a/content/nic/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/content/nic/configuration/virtualserver-and-virtualserverroute-resources.md @@ -356,6 +356,7 @@ tls: |``buffering`` | Enables buffering of responses from the upstream server. See the [proxy_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) directive. The default is set in the ``proxy-buffering`` ConfigMap key. | ``boolean`` | No | |``buffers`` | Configures the buffers used for reading a response from the upstream server for a single connection. | [buffers](#upstreambuffers) | No | |``buffer-size`` | Sets the size of the buffer used for reading the first part of a response received from the upstream server. See the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) directive. The default is set in the ``proxy-buffer-size`` ConfigMap key. | ``string`` | No | +|``busy-buffers-size`` | Sets the size of the buffer used for reading a response from the upstream server when the response is larger than the ``buffer-size``. See the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. The default is set in the ``proxy-busy-buffers-size`` ConfigMap key. | ``string`` | No | |``ntlm`` | Allows proxying requests with NTLM Authentication. See the [ntlm](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#ntlm) directive. In order for NTLM authentication to work, it is necessary to enable keepalive connections to upstream servers using the ``keepalive`` field. Note: this feature is supported only in NGINX Plus.| ``boolean`` | No | |``type`` |The type of the upstream. Supported values are ``http`` and ``grpc``. The default is ``http``. For gRPC, it is necessary to enable HTTP/2 in the [ConfigMap]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#listeners" >}}) and configure TLS termination in the VirtualServer. | ``string`` | No | |``backup`` | The name of the backup service of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname). This will be used when the primary servers are unavailable. Note: The parameter cannot be used along with the ``random`` , ``hash`` or ``ip_hash`` load balancing methods. | ``string`` | No | diff --git a/content/nic/installation/ingress-nginx.md b/content/nic/installation/ingress-nginx.md index cdfed5470..7727c56e8 100644 --- a/content/nic/installation/ingress-nginx.md +++ b/content/nic/installation/ingress-nginx.md @@ -459,6 +459,7 @@ This table maps the Ingress-NGINX Controller annotations to NGINX Ingress Contro | [_nginx.ingress.kubernetes.io/proxy-buffering_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#proxy-buffering) | [_nginx.org/proxy-buffering_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_buffering_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) | | [_nginx.ingress.kubernetes.io/proxy-buffers-number_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#proxy-buffers-number) | [_nginx.org/proxy-buffers_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_buffers_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) | | [_nginx.ingress.kubernetes.io/proxy-buffer-size_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#proxy-buffer-size) | [_nginx.org/proxy-buffer-size_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_buffer_size_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) | +| [_nginx.ingress.kubernetes.io/proxy-busy-buffers-size_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#proxy-busy-buffers-size) | [_nginx.org/proxy-busy-buffers-size_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_busy_buffers_size_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) | | [_nginx.ingress.kubernetes.io/proxy-connect-timeout_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#custom-timeouts) | [_nginx.org/proxy-connect-timeout_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_connect_timeout_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) | | [_nginx.ingress.kubernetes.io/proxy-read-timeout_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#custom-timeouts) | [_nginx.org/proxy-read-timeout_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_read_timeout_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) | | [_nginx.ingress.kubernetes.io/proxy-send-timeout_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#custom-timeouts) | [_nginx.org/proxy-send-timeout_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_send_timeout_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) | diff --git a/content/nic/installation/installing-nic/installation-with-helm.md b/content/nic/installation/installing-nic/installation-with-helm.md index 0251b146c..6e4677e97 100644 --- a/content/nic/installation/installing-nic/installation-with-helm.md +++ b/content/nic/installation/installing-nic/installation-with-helm.md @@ -110,7 +110,7 @@ When installing the NGINX Ingress Controller chart, Helm will also install the r If the CRDs are not installed, NGINX Ingress Controller pods will not become _Ready_. -If you do not use the custom resources that require those CRDs (With `controller.enableCustomResources`,`controller.appprotect.enable` and `controller.appprotectdos.enable` set to `false`), the installation of the CRDs can be skipped by specifying `--skip-crds` in your _helm install_ command. +If you do not use the custom resources that require those CRDs (With `controller.enableCustomResources`, `controller.appprotect.enable` and `controller.appprotectdos.enable` set to `false`), the installation of the CRDs can be skipped by specifying `--skip-crds` in your _helm install_ command. {{< call-out "caution" "Running multiple NGINX Ingress Controller instances">}} @@ -129,10 +129,10 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont {{< table >}} |Parameter | Description | Default | | --- | --- | --- | -| **controller.name** | The name of the NGINX Ingress Controller daemonset or deployment. | Autogenerated | -| **controller.kind** | The kind of the NGINX Ingress Controller installation - deployment or daemonset. | deployment | -| **controller.annotations** | Allows for setting of `annotations` for deployment or daemonset. | {} | -| **controller.nginxplus** | Deploys the NGINX Ingress Controller for NGINX Plus. | false | +| **controller.name** | The name of the Ingress Controller deployment, daemonset, or statefulset. | Autogenerated | +| **controller.kind** | The kind of the Ingress Controller installation - deployment, daemonset, or statefulset. | deployment | +| **controller.annotations** | Allows for setting of `annotations` for deployment, daemonset, or statefulset. | {} | +| **controller.nginxplus** | Deploys the Ingress Controller for NGINX Plus. | false | | **controller.mgmt.licenseTokenSecretName** | Configures the secret used in the [license_token](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `nginx.com/license` with the base64 encoded JWT in the `license.jwt` key. | license-token | | **controller.mgmt.enforceInitialReport** | Configures the [enforce_initial_report](https://nginx.org/en/docs/ngx_mgmt_module.html#enforce_initial_report) directive, which enables or disables the 180-day grace period for sending the initial usage report. | false | | **controller.mgmt.usageReport.endpoint** | Configures the endpoint of the [usage_report](https://nginx.org/en/docs/ngx_mgmt_module.html#usage_report) directive. This is used to configure the endpoint NGINX uses to send usage reports to NIM. | product.connect.nginx.com | @@ -152,6 +152,7 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.nginxDebug** | Enables debugging for NGINX. Uses the `nginx-debug` binary. Requires `error-log-level: debug` in the ConfigMap via `controller.config.entries`. | false | | **controller.logLevel** | The log level of the NGINX Ingress Controller. | info | | **controller.logFormat** | The log format of the NGINX Ingress Controller. | glog | +| **controller.directiveAutoAdjust** | Automatically adjusts NGINX buffer directives to prevent configuration errors. | false | | **controller.image.digest** | The image digest of the NGINX Ingress Controller. | None | | **controller.image.repository** | The image repository of the NGINX Ingress Controller. | nginx/nginx-ingress | | **controller.image.tag** | The tag of the NGINX Ingress Controller image. | {{< nic-version >}} | @@ -260,6 +261,14 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.readyStatus.enable** | Enables the readiness endpoint `"/nginx-ready"`. The endpoint returns a success code when NGINX has loaded all the config after the startup. This also configures a readiness probe for the NGINX Ingress Controller pods that uses the readiness endpoint. | true | | **controller.readyStatus.port** | The HTTP port for the readiness endpoint. | 8081 | | **controller.readyStatus.initialDelaySeconds** | The number of seconds after the NGINX Ingress Controller pod has started before readiness probes are initiated. | 0 | +| **controller.startupStatus.enable** | Enables the startup probe for the Ingress Controller. | false | +| **controller.startupStatus.port** | The port where the startup endpoint is exposed. This is a required field if `controller.startupStatus.enable` is set to true. | N/A | +| **controller.startupStatus.path** | The path to the startup endpoint. This is a required field if `controller.startupStatus.enable` is set to true. | N/A | +| **controller.startupStatus.initialDelaySeconds** | The number of seconds after the Ingress Controller pod has started before startup probes are initiated. | N/A | +| **controller.startupStatus.periodSeconds** | The number of seconds between each startup probe. | N/A | +| **controller.startupStatus.timeoutSeconds** | The number of seconds after which the startup probe times out. | N/A | +| **controller.startupStatus.successThreshold** | Minimum consecutive successes for the probe to be considered successful. | N/A | +| **controller.startupStatus.failureThreshold** | When a probe fails, Kubernetes will try failureThreshold times before giving up. | N/A | | **controller.enableLatencyMetrics** | Enable collection of latency metrics for upstreams. Requires `prometheus.create`. | false | | **controller.minReadySeconds** | Specifies the minimum number of seconds for which a newly created Pod should be ready without any of its containers crashing, for it to be considered available. [docs](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#min-ready-seconds) | 0 | | **controller.autoscaling.enabled** | Enables HorizontalPodAutoscaling. | false | @@ -273,7 +282,13 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.podDisruptionBudget.annotations** | The annotations of the NGINX Ingress Controller pod disruption budget | {} | | **controller.podDisruptionBudget.minAvailable** | The number of Ingress Controller pods that should be available. This is a mutually exclusive setting with "maxUnavailable". | 0 | | **controller.podDisruptionBudget.maxUnavailable** | The number of Ingress Controller pods that can be unavailable. This is a mutually exclusive setting with "minAvailable". | 0 | -| **controller.strategy** | Specifies the strategy used to replace old Pods with new ones. Docs for [Deployment update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) and [Daemonset update strategy](https://kubernetes.io/docs/tasks/manage-daemon/update-daemon-set/#daemonset-update-strategy) | {} | +| **controller.strategy** | Specifies the strategy used to replace old Pods with new ones. Docs for [Deployment update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy), [Daemonset update strategy](https://kubernetes.io/docs/tasks/manage-daemon/update-daemon-set/#daemonset-update-strategy) and [StatefulSet update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#update-strategies) | {} | +| **controller.statefulset.podManagementPolicy** | Controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down. Available options: `OrderedReady` or `Parallel`. Only applies when `controller.kind` is set to `statefulset`. | `OrderedReady` | +| **controller.statefulset.persistentVolumeClaimRetentionPolicy.whenDeleted** | Controls the retention policy for PVCs when the StatefulSet is deleted. Available options: `Retain` or `Delete`. Only applies when `controller.kind` is set to `statefulset`. | `Retain` | +| **controller.statefulset.persistentVolumeClaimRetentionPolicy.whenScaled** | Controls the retention policy for PVCs when the StatefulSet is scaled down. Available options: `Retain` or `Delete`. Only applies when `controller.kind` is set to `statefulset`. | `Retain` | +| **controller.statefulset.nginxCachePVC.size** | The size of the persistent volume claim for NGINX cache storage. Only applies when `controller.kind` is set to `statefulset`. | `256Mi` | +| **controller.statefulset.nginxCachePVC.storageClass** | The storage class for the persistent volume claim. Only applies when `controller.kind` is set to `statefulset`. | `""` | +| **controller.statefulset.nginxCachePVC.accessModes** | The access modes for the persistent volume claim. Only applies when `controller.kind` is set to `statefulset`. | `["ReadWriteOnce"]` | | **controller.disableIPV6** | Disable IPV6 listeners explicitly for nodes that do not support the IPV6 stack. | false | | **controller.defaultHTTPListenerPort** | Sets the port for the HTTP `default_server` listener. | 80 | | **controller.defaultHTTPSListenerPort** | Sets the port for the HTTPS `default_server` listener. | 443 | diff --git a/content/nic/installation/installing-nic/installation-with-manifests.md b/content/nic/installation/installing-nic/installation-with-manifests.md index 8df8e0a53..dbbc84935 100644 --- a/content/nic/installation/installing-nic/installation-with-manifests.md +++ b/content/nic/installation/installing-nic/installation-with-manifests.md @@ -132,10 +132,11 @@ kubectl apply -f config/crd/bases/appprotectdos.f5.com_dosprotectedresources.yam ## Deploy NGINX Ingress Controller {#deploy-ingress-controller} -You have two options for deploying NGINX Ingress Controller: +You have three options for deploying NGINX Ingress Controller: - **Deployment**. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller replicas. - **DaemonSet**. Choose this method if you want NGINX Ingress Controller to run on all nodes or a subset of nodes. +- **StatefulSet**. Choose this method when you need stable, persistent storage and ordered deployment/scaling for your NGINX Ingress Controller pods. Before you start, update the [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}) for the NGINX Ingress Controller container in the relevant manifest file to meet your specific requirements. @@ -147,6 +148,10 @@ Before you start, update the [command-line arguments]({{< ref "/nic/configuratio {{< include "/nic/installation/manifests/daemonset.md" >}} +### Using a StatefulSet + +{{< include "/nic/installation/manifests/statefulset.md" >}} + --- ## Confirm NGINX Ingress Controller is running @@ -157,9 +162,9 @@ Before you start, update the [command-line arguments]({{< ref "/nic/configuratio ## How to access NGINX Ingress Controller -### Using a Deployment +### Using a Deployment or StatefulSet -For Deployments, you have two options for accessing NGINX Ingress Controller pods. +For Deployments and StatefulSets, you have two options for accessing NGINX Ingress Controller pods. #### Option 1: Create a NodePort service diff --git a/content/nic/installation/integrations/app-protect-dos/installation.md b/content/nic/installation/integrations/app-protect-dos/installation.md index c678dcf49..f090c6712 100644 --- a/content/nic/installation/integrations/app-protect-dos/installation.md +++ b/content/nic/installation/integrations/app-protect-dos/installation.md @@ -166,6 +166,10 @@ kubectl apply -f config/crd/bases/appprotectdos.f5.com_dosprotectedresources.yam {{< include "/nic/installation/manifests/daemonset.md" >}} +### Using a StatefulSet + +{{< include "/nic/installation/manifests/statefulset.md" >}} + --- ## Install the App Protect DoS Arbitrator @@ -204,7 +208,7 @@ Alternatively, you can install the App Protect DoS Arbitrator using the YAML man To enable the NGINX App Protect DoS Module: -- Add the `enable-app-protect-dos` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect-dos" >}}) to your Deployment or DaemonSet file. +- Add the `enable-app-protect-dos` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect-dos" >}}) to your Deployment, DaemonSet, or StatefulSet file. --- diff --git a/content/nic/installation/integrations/app-protect-waf-v5/installation.md b/content/nic/installation/integrations/app-protect-waf-v5/installation.md index 421dded1c..159923821 100644 --- a/content/nic/installation/integrations/app-protect-waf-v5/installation.md +++ b/content/nic/installation/integrations/app-protect-waf-v5/installation.md @@ -132,7 +132,7 @@ docker push /waf-enforcer: ## Deploy NGINX Ingress Controller {#deploy-ingress-controller} -{{< call-out "important" >}} NGINX Ingress Controller with the AppProtect WAF v5 module works only with policy bundles. You need to modify the Deployment or DaemonSet file to include volumes, volume mounts and two WAF 5 docker images: `waf-config-mgr` and `waf-enforcer`. +{{< important >}} NGINX Ingress Controller with the AppProtect WAF v5 module works only with policy bundles. You need to modify the Deployment, DaemonSet, or StatefulSet file to include volumes, volume mounts and two WAF 5 docker images: `waf-config-mgr` and `waf-enforcer`. NGINX Ingress Controller **requires** the volume mount path to be `/etc/app_protect/bundles`. {{< /call-out >}} @@ -227,18 +227,18 @@ Create required volumes: volumes: - name: nginx-etc emptyDir: {} - - name: nginx-cache - emptyDir: {} + - name: nginx-cache # do not set this value in statefulset if volumeclaimtemplate is set + emptyDir: {} # do not set this value in statefulset if volumeclaimtemplate is set - name: nginx-lib emptyDir: {} - name: nginx-log emptyDir: {} - - emptyDir: {} - name: app-protect-bd-config - - emptyDir: {} - name: app-protect-config - - emptyDir: {} - name: app-protect-bundles + - name: app-protect-bd-config + emptyDir: {} + - name: app-protect-config + emptyDir: {} + - name: app-protect-bundles + emptyDir: {} ``` Set `controller.securityContext.readOnlyRootFilesystem` to `true`. @@ -291,6 +291,7 @@ You have two options for deploying NGINX Ingress Controller: - **Deployment**. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller replicas. - **DaemonSet**. Choose this method if you want NGINX Ingress Controller to run on all nodes or a subset of nodes. +- **StatefulSet**. Choose this method when you need stable, persistent storage and ordered deployment/scaling for your NGINX Ingress Controller pods. --- @@ -377,7 +378,7 @@ Add `waf-enforcer` image to the `containers` section: ... ``` -### Update NIC container in deployment or daemonset +### Update NIC container in deployment, daemonset, or statefulset Add `volumeMounts` as below: @@ -464,6 +465,10 @@ Add `readOnlyRootFilesystem` to the `waf-enforcer` container and set value to `t ... ``` +{{< call-out "note" >}} +**StatefulSet Volume Configuration**: When using StatefulSet deployments, the `nginx-cache` volume is automatically provided via `volumeClaimTemplates` for persistent storage. App Protect WAF v5 volumes (like app-protect-config, app-protect-bundles) are still configured as regular volumes in the `volumes` section. Use `emptyDir` for temporary data or PersistentVolumeClaims if you need persistence for App Protect configurations across pod restarts. +{{< /call-out >}} + ### Using a Deployment {{< include "/nic/installation/manifests/deployment.md" >}} @@ -472,13 +477,17 @@ Add `readOnlyRootFilesystem` to the `waf-enforcer` container and set value to `t {{< include "/nic/installation/manifests/daemonset.md" >}} +### Using a StatefulSet + +{{< include "/nic/installation/manifests/statefulset.md" >}} + --- ### Enable NGINX App Protect WAF module To enable the NGINX App Protect DoS Module: -- Add the `enable-app-protect` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment or DaemonSet file. +- Add the `enable-app-protect` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment, DaemonSet, or StatefulSet file. {{%/tab%}} diff --git a/content/nic/installation/integrations/app-protect-waf/installation.md b/content/nic/installation/integrations/app-protect-waf/installation.md index 0da5bc500..b5d8d3920 100644 --- a/content/nic/installation/integrations/app-protect-waf/installation.md +++ b/content/nic/installation/integrations/app-protect-waf/installation.md @@ -158,7 +158,7 @@ kubectl apply -f config/crd/bases/appprotect.f5.com_apusersigs.yaml {{< include "/nic/installation/deploy-controller.md" >}} -{{< call-out "note" >}} If you're using NGINX Ingress Controller with the AppProtect WAF module and policy bundles, you will need to modify the Deployment or DaemonSet file to include volumes and volume mounts. +{{< call-out "note" >}} If you're using NGINX Ingress Controller with the AppProtect WAF module and policy bundles, you will need to modify the Deployment, DaemonSet, or StatefulSet file to include volumes and volume mounts. NGINX Ingress Controller **requires** the volume mount path to be `/etc/nginx/waf/bundles`. {{< /call-out >}} @@ -183,6 +183,10 @@ volumeMounts: ... ``` +{{< call-out "note" >}} +**StatefulSet Volume Configuration**: When using StatefulSet deployments, the `nginx-cache` volume is automatically provided via `volumeClaimTemplates` for persistent storage. App Protect WAF v5 volumes (like app-protect-config, app-protect-bundles) are still configured as regular volumes in the `volumes` section. Use `emptyDir` for temporary data or PersistentVolumeClaims if you need persistence for App Protect configurations across pod restarts. +{{< /call-out >}} + ### Using a Deployment {{< include "/nic/installation/manifests/deployment.md" >}} @@ -191,13 +195,17 @@ volumeMounts: {{< include "/nic/installation/manifests/daemonset.md" >}} +### Using a StatefulSet + +{{< include "/nic/installation/manifests/statefulset.md" >}} + --- ## Enable NGINX App Protect WAF module To enable the NGINX App Protect DoS Module: -- Add the `enable-app-protect` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment or DaemonSet file. +- Add the `enable-app-protect` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment, DaemonSet, or StatefulSet file. --- diff --git a/content/nic/logging-and-monitoring/prometheus.md b/content/nic/logging-and-monitoring/prometheus.md index 0bca69823..6ebbc749f 100644 --- a/content/nic/logging-and-monitoring/prometheus.md +++ b/content/nic/logging-and-monitoring/prometheus.md @@ -35,8 +35,7 @@ curl https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/$ ``` ### Using Manifests - -If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the Ingress Controller, to enable Prometheus metrics: +If you're using *Kubernetes manifests* (Deployment, DaemonSet, or StatefulSet) to install the Ingress Controller, to enable Prometheus metrics: 1. Run the Ingress Controller with the `-enable-prometheus-metrics` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}). As a result, the Ingress Controller will expose NGINX or NGINX Plus metrics in the Prometheus format via the path `/metrics` on port `9113` (customizable via the `-prometheus-metrics-listen-port` command-line argument). 1. To enable TLS for the Prometheus endpoint, configure the `-prometheus-tls-secret` cli argument with the namespace and name of a TLS Secret. diff --git a/content/nic/logging-and-monitoring/service-insight.md b/content/nic/logging-and-monitoring/service-insight.md index 35b4c89a8..f33248bde 100644 --- a/content/nic/logging-and-monitoring/service-insight.md +++ b/content/nic/logging-and-monitoring/service-insight.md @@ -20,7 +20,7 @@ NGINX Plus determination of healthy can be tuned using advanced health checks, a ## Enabling Service Insight Endpoint -If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the Ingress Controller, to enable the Service Insight endpoint: +If you're using *Kubernetes manifests* (Deployment, DaemonSet, or StatefulSet) to install the Ingress Controller, to enable the Service Insight endpoint: 1. Run the Ingress Controller with the `-enable-service-insight` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}). This will expose the Ingress Controller endpoint via paths `/probe/{hostname}` for Virtual Servers, and `/probe/ts/{service_name}` for Transport Servers on port `9114` (customizable with the `-service-insight-listen-port` command-line argument). The `service_name` parameter refers to the name of the deployed service (the service specified under `upstreams` in the transport server). 1. To enable TLS for the Service Insight endpoint, configure the `-service-insight-tls-secret` cli argument with the namespace and name of a TLS Secret. diff --git a/content/nic/overview/product-telemetry.md b/content/nic/overview/product-telemetry.md index 08196c4ca..ca9472af7 100644 --- a/content/nic/overview/product-telemetry.md +++ b/content/nic/overview/product-telemetry.md @@ -34,7 +34,7 @@ These are the data points collected and reported by NGINX Ingress Controller: - **VirtualServers** The number of VirtualServer resources managed by NGINX Ingress Controller. - **VirtualServerRoutes** The number of VirtualServerRoute resources managed by NGINX Ingress Controller. - **TransportServers** The number of TransportServer resources managed by NGINX Ingress Controller. -- **Replicas** Number of Deployment replicas, or Daemonset instances. +- **Replicas** Number of Deployment or StatefulSet replicas, or DaemonSet instances. - **Secrets** Number of Secret resources managed by NGINX Ingress Controller. - **ClusterIPServices** Number of ClusterIP Services managed by NGINX Ingress Controller. - **NodePortServices** Number of NodePort Services managed by NGINX Ingress Controller. @@ -54,6 +54,7 @@ These are the data points collected and reported by NGINX Ingress Controller: - **EgressMTLSPolicies** Number of EgressMTLS policies. - **OIDCPolicies** Number of OIDC policies. - **WAFPolicies** Number of WAF policies. +- **CachePolicies** Number of Cache policies. - **GlobalConfiguration** Represents the use of a GlobalConfiguration resource. - **AppProtectVersion** The AppProtect version - **IsPlus** Represents whether NGINX is Plus or OSS diff --git a/content/nic/releases.md b/content/nic/releases.md index 4821b26d8..794b2868b 100644 --- a/content/nic/releases.md +++ b/content/nic/releases.md @@ -5,6 +5,43 @@ toc: true nd-content-type: reference nd-product: NIC nd-docs: DOCS-616 +--- +## 5.2.0 + +15 Sept 2025 + +This NGINX Ingress Controller release focuses on enhancing performance, simplifying configurations, and improving security to better support modern application needs. The highlights of this release are as follows: +- NGINX Content Cache using policies: This new feature introduces policy configurations that enable proxy caching. +- Support for Kubernetes `StatefulSet` Objects: Added support for Kubernetes `StatefulSet` objects, which can also be used to provide persistent storage for cached content. +- Auto-Adjusting incompatible proxy buffer directive values: A new `-enable-directive-autoadjust` parameter has been added. When enabled, this feature automatically resolves common proxy buffer configuration dependencies that could cause issues during NGINX reloads. +- Server Name Indication (SNI) support in JWT Policies: Users can now configure sniName and sniEnabled for scenarios where the remote server requires SNI to present the correct certificate + +### Features +- [8005](https://github.com/nginx/kubernetes-ingress/pull/8005) Add nginx content cache as NIC cache policy +- [8159](https://github.com/nginx/kubernetes-ingress/pull/8159) Statefulset support +- [8133](https://github.com/nginx/kubernetes-ingress/pull/8133) Add support for automatic adjustment of buffer related directives +- [8011](https://github.com/nginx/kubernetes-ingress/pull/8011) Allow startupprobe to be configured via helm +- [7993](https://github.com/nginx/kubernetes-ingress/pull/7993) Add sni to NIC jwt policy +- [8093](https://github.com/nginx/kubernetes-ingress/pull/8093) Add viol_bot_client and viol_geolocation violations support +- [8229](https://github.com/nginx/kubernetes-ingress/pull/8229) Add N+ license expiry to prometheus metrics +- [8142](https://github.com/nginx/kubernetes-ingress/pull/8142) Add globalconfigurationcustomname parameter +- [8195](https://github.com/nginx/kubernetes-ingress/pull/8195) Add support for fips 140-3 compliance + + + +### Dependencies +- [8208](https://github.com/nginx/kubernetes-ingress/pull/8208) Update Nginx agent to 3.3 +- [7959](https://github.com/nginx/kubernetes-ingress/pull/7959), [7983](https://github.com/nginx/kubernetes-ingress/pull/7983), [8037](https://github.com/nginx/kubernetes-ingress/pull/8037), [8057](https://github.com/nginx/kubernetes-ingress/pull/8057), [8083](https://github.com/nginx/kubernetes-ingress/pull/8083), [8096](https://github.com/nginx/kubernetes-ingress/pull/8096), [8126](https://github.com/nginx/kubernetes-ingress/pull/8126), [8143](https://github.com/nginx/kubernetes-ingress/pull/8143), [8183](https://github.com/nginx/kubernetes-ingress/pull/8183), [8186](https://github.com/nginx/kubernetes-ingress/pull/8186), [8200](https://github.com/nginx/kubernetes-ingress/pull/8200), [8231](https://github.com/nginx/kubernetes-ingress/pull/8231) Bump Go dependencies +- [7946](https://github.com/nginx/kubernetes-ingress/pull/7946), [7961](https://github.com/nginx/kubernetes-ingress/pull/7961), [7977](https://github.com/nginx/kubernetes-ingress/pull/7977), [7979](https://github.com/nginx/kubernetes-ingress/pull/7979), [7978](https://github.com/nginx/kubernetes-ingress/pull/7978), [7984](https://github.com/nginx/kubernetes-ingress/pull/7984), [7996](https://github.com/nginx/kubernetes-ingress/pull/7996), [8012](https://github.com/nginx/kubernetes-ingress/pull/8012), [8036](https://github.com/nginx/kubernetes-ingress/pull/8036), [8044](https://github.com/nginx/kubernetes-ingress/pull/8044), [8063](https://github.com/nginx/kubernetes-ingress/pull/8063), [8085](https://github.com/nginx/kubernetes-ingress/pull/8085), [8107](https://github.com/nginx/kubernetes-ingress/pull/8107), [8114](https://github.com/nginx/kubernetes-ingress/pull/8114), [8128](https://github.com/nginx/kubernetes-ingress/pull/8128), [8134](https://github.com/nginx/kubernetes-ingress/pull/8134), [8147](https://github.com/nginx/kubernetes-ingress/pull/8147), [8154](https://github.com/nginx/kubernetes-ingress/pull/8154), [8173](https://github.com/nginx/kubernetes-ingress/pull/8173), [8188](https://github.com/nginx/kubernetes-ingress/pull/8188), [8228](https://github.com/nginx/kubernetes-ingress/pull/8228), [8239](https://github.com/nginx/kubernetes-ingress/pull/8239), [8235](https://github.com/nginx/kubernetes-ingress/pull/8235), [8246](https://github.com/nginx/kubernetes-ingress/pull/8246) Bump Docker dependencies + +### Upgrade +- For NGINX, use the 5.2.0 images from our [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/tags?page=1&ordering=last_updated&name=5.2.0), [GitHub Container](https://github.com/nginx/kubernetes-ingress/pkgs/container/kubernetes-ingress), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [Quay.io](https://quay.io/repository/nginx/nginx-ingress). +- For NGINX Plus, use the 5.2.0 images from the F5 Container registry or build your own image using the 5.2.0 source code. +- For Helm, use version 2.3.0 of the chart. + +### Supported Platforms +We will provide technical support for NGINX Ingress Controller on any Kubernetes platform that is currently supported by its provider and that passes the Kubernetes conformance tests. This release was fully tested on the following Kubernetes versions: 1.26-1.34. + --- ## 5.1.1 @@ -2432,4 +2469,4 @@ Otherwise, the helm upgrade will not succeed. ## Previous Releases -To see the previous releases, see the [Releases page](https://github.com/nginx/kubernetes-ingress/releases) on the Ingress Controller GitHub repo. \ No newline at end of file +To see the previous releases, see the [Releases page](https://github.com/nginx/kubernetes-ingress/releases) on the Ingress Controller GitHub repo. diff --git a/content/nic/technical-specifications.md b/content/nic/technical-specifications.md index 869a87b3c..3a976b459 100644 --- a/content/nic/technical-specifications.md +++ b/content/nic/technical-specifications.md @@ -17,7 +17,8 @@ We test NGINX Ingress Controller on a range of Kubernetes platforms for each rel {{< table >}} | NIC version | Kubernetes versions tested | NIC Helm Chart version | NIC Operator version | NGINX / NGINX Plus version | End of Technical Support | | --- | --- | --- | --- | --- | --- | -| {{< nic-version >}} | 1.25 - 1.33 | {{< nic-helm-version >}} | {{< nic-operator-version >}} | 1.29.1 / R35 | - | +| {{< nic-version >}} | 1.26 - 1.34 | {{< nic-helm-version >}} | {{< nic-operator-version >}} | 1.29.1 / R35 | - | +| 5.1.1 | 1.25 - 1.33 | 2.2.2 | 3.2.3 | 1.29.1 / R35 | Aug 15, 2027 | | 5.0.0 | 1.25 - 1.32 | 2.1.0 | 3.1.0 | 1.27.4 / R34 | Apr 16, 2027 | | 4.0.1 | 1.25 - 1.32 | 2.0.1 | 3.0.1 | 1.27.4 / R33 P2 | Feb 7, 2027 | | 3.7.2 | 1.25 - 1.31 | 1.4.2 | 2.4.2 | 1.27.2 / R32 P1 | Nov 25, 2026 | @@ -25,7 +26,6 @@ We test NGINX Ingress Controller on a range of Kubernetes platforms for each rel | 3.5.2 | 1.23 - 1.30 | 1.2.2 | 2.2.2 | 1.27.0 / R32 | May 31, 2026 | | 3.4.3 | 1.23 - 1.29 | 1.1.3 | 2.1.2 | 1.25.4 / R31 P1 | Feb 19, 2026 | | 3.3.2 | 1.22 - 1.28 | 1.0.2 | 2.0.2 | 1.25.3 / R30 | Nov 1, 2025 | -| 3.2.1 | 1.22 - 1.27 | 0.18.1 | 1.5.1 | 1.25.2 / R30 | Aug 18, 2025 | {{< /table >}} ## Supported Docker images diff --git a/content/nic/troubleshooting/troubleshoot-common.md b/content/nic/troubleshooting/troubleshoot-common.md index 58f59e218..923b1c6ef 100644 --- a/content/nic/troubleshooting/troubleshoot-common.md +++ b/content/nic/troubleshooting/troubleshoot-common.md @@ -78,7 +78,7 @@ There are two places to configure more verbose logging for NGINX Ingress Control **Command line arguments** -When using `manifest` for deployment, use the command line argument `-nginx-debug` in your deployment or daemonset. +When using `manifest` for deployment, use the command line argument `-nginx-debug` in your deployment, daemonset, or statefulset. You can add the `-log-level` parameter to increase the verbosity of the NGINX Ingress Controller process. diff --git a/content/nic/tutorials/oidc-custom-configuration.md b/content/nic/tutorials/oidc-custom-configuration.md index f33ff8a08..c8281f468 100644 --- a/content/nic/tutorials/oidc-custom-configuration.md +++ b/content/nic/tutorials/oidc-custom-configuration.md @@ -111,7 +111,7 @@ This document will demonstrate how to add the `Volume` and `VolumeMount` using b ### Manifest -The below configuration shows where the `Volume` and `VolumeMount` can be added to your Deployment/Daemonset file. +The below configuration shows where the `Volume` and `VolumeMount` can be added to your Deployment, Daemonset, or StatefulSet file. The `VolumeMount` must be added the `spec.template.spec.containers` section. @@ -119,7 +119,7 @@ The `Volume` must be added the `spec.template.spec` section: ```yaml apiVersion: apps/v1 -kind: +kind: metadata: name: namespace: @@ -157,7 +157,7 @@ kubectl exec -it -n -- cat /etc/nginx/oid ### Helm Deployments using helm will need to edit their existing -Edit the NGINX Ingress Controller Deployment/Daemonset yaml to include a `Volume` and `VolumeMount`. +Edit the NGINX Ingress Controller Deployment/DaemonSet/StatefulSet yaml to include a `Volume` and `VolumeMount`. The `Volume` should be within the `spec.template.spec` section. @@ -169,15 +169,21 @@ For Deployments: kubectl edit deployments -n ``` -For Daemonsets: +For DaemonSets: ```shell kubectl edit daemonset -n ``` +For StatefulSets: + +```shell +kubectl edit statefulset -n +``` + ```yaml apiVersion: apps/v1 -kind: +kind: metadata: name: namespace: @@ -204,7 +210,7 @@ spec: readOnly: true ``` -Once the Deployment/Daemonset has been edited, save the file and exit. +Once the Deployment/DaemonSet/StatefulSet has been edited, save the file and exit. Confirm the `oidc.conf` file has been updated: diff --git a/content/nim/_index.md b/content/nim/_index.md index 9bf0baf8e..b7a0b120f 100644 --- a/content/nim/_index.md +++ b/content/nim/_index.md @@ -1,5 +1,5 @@ --- -title: NGINX Instance Manager +title: F5 NGINX Instance Manager description: Track and control NGINX Open Source and NGINX Plus instances. url: /nginx-instance-manager/ nd-landing-page: true diff --git a/content/nim/admin-guide/authentication/basic-auth/set-up-basic-authentication.md b/content/nim/admin-guide/authentication/basic-auth/set-up-basic-authentication.md index 5c3234a20..c26343eab 100644 --- a/content/nim/admin-guide/authentication/basic-auth/set-up-basic-authentication.md +++ b/content/nim/admin-guide/authentication/basic-auth/set-up-basic-authentication.md @@ -58,9 +58,9 @@ To add users, take the following steps: ## Set user passwords {#set-basic-passwords} -{{< before-you-begin >}} +{{< call-out "note" >}} Before you can set users' passwords, ensure you have [created users](#create-users) in NGINX Instance Manager. Once you've created the users, you can use one of the following options to set their passwords. -{{< /before-you-begin >}} +{{< /call-out >}} ### (Recommended) Use the provided script {#set-basic-passwords-script} diff --git a/content/nms/acm/how-to/devportals/installation/devportal-helm-chart.md b/content/nms/acm/how-to/devportals/installation/devportal-helm-chart.md index e07efbe23..cbe41c2cf 100644 --- a/content/nms/acm/how-to/devportals/installation/devportal-helm-chart.md +++ b/content/nms/acm/how-to/devportals/installation/devportal-helm-chart.md @@ -281,7 +281,9 @@ Create a Dockerfile similar to the following example: ## Push Images to Private Registry {#push-images-private-registry} -{{}}To complete this step, you need an [externally-accessible private Docker registry](https://docs.docker.com/registry/deploying/) to push the container images to.{{}} +{{< call-out "note" >}} +To complete this step, you need an [externally-accessible private Docker registry](https://docs.docker.com/registry/deploying/) to push the container images to. +{{< / call-out >}} After building or loading the Docker images, you can now tag and push the images to your private Docker registry. Replace `` in the examples below with the path to your private Docker registry. diff --git a/data/f5-sites.yaml b/data/f5-sites.yaml new file mode 100644 index 000000000..9b624d9ab --- /dev/null +++ b/data/f5-sites.yaml @@ -0,0 +1,19 @@ +- title: F5 + url: https://f5.com/ + description: Deliver and secure every app + +- title: DevCentral + url: https://community.f5.com/ + description: Connect & learn in our hosted community + +- title: MyF5 + url: https://my.f5.com/ + description: Your key to everything F5, including support, registration keys, and subscriptions + +- title: NGINX + url: https://nginx.org/ + description: Learn more about NGINX Open Source and read the community blog + +- title: Community Forum + url: https://community.nginx.org/ + description: Engage with the broader NGINX community for discussions and troubleshooting diff --git a/data/product-selector.yaml b/data/product-selector.yaml index f2bbf5310..277f5ca1e 100644 --- a/data/product-selector.yaml +++ b/data/product-selector.yaml @@ -25,5 +25,5 @@ - productGroup: NGINX as a Service products: - - title: "NGINX as a Service for Azure" + - title: "NGINXaaS for Azure" url: "nginxaas/azure/" diff --git a/layouts/shortcodes/nic-helm-version.html b/layouts/shortcodes/nic-helm-version.html index 7e541aec6..cc6612c36 100644 --- a/layouts/shortcodes/nic-helm-version.html +++ b/layouts/shortcodes/nic-helm-version.html @@ -1 +1 @@ -2.2.2 \ No newline at end of file +2.3.0 \ No newline at end of file diff --git a/layouts/shortcodes/nic-operator-version.html b/layouts/shortcodes/nic-operator-version.html index 06eda28ac..0fa4ae489 100644 --- a/layouts/shortcodes/nic-operator-version.html +++ b/layouts/shortcodes/nic-operator-version.html @@ -1 +1 @@ -3.2.3 \ No newline at end of file +3.3.0 \ No newline at end of file diff --git a/layouts/shortcodes/nic-version.html b/layouts/shortcodes/nic-version.html index 3bff05917..7cbea073b 100644 --- a/layouts/shortcodes/nic-version.html +++ b/layouts/shortcodes/nic-version.html @@ -1 +1 @@ -5.1.1 \ No newline at end of file +5.2.0 \ No newline at end of file diff --git a/layouts/shortcodes/version-ngf.html b/layouts/shortcodes/version-ngf.html index 50aea0e7a..7c3272873 100644 --- a/layouts/shortcodes/version-ngf.html +++ b/layouts/shortcodes/version-ngf.html @@ -1 +1 @@ -2.1.0 \ No newline at end of file +2.1.1 \ No newline at end of file diff --git a/static/nginxaas-azure/js/cost-calculator_v2.js b/static/nginxaas-azure/js/cost-calculator_v2.js index d2b7aa830..c2b571153 100644 --- a/static/nginxaas-azure/js/cost-calculator_v2.js +++ b/static/nginxaas-azure/js/cost-calculator_v2.js @@ -1,7 +1,7 @@ // todo [heftel] - if we are going to live with this for a while then this file should be broken up with // modules. Browser support shouldn't be a concern anymore? - https://caniuse.com/es6-module -(function () { +(() => { /** * @typedef {typeof costs} Costs * @constant @@ -167,66 +167,66 @@ }; //////// - // Keep element refs with hugo global jquery + // Keep element refs with hugo global HTMLElement //////// /** - * @type {Object.} + * @type {Object.} */ const costFormElements = { - region: $("#region"), - numNcus: $("#numNcus"), - numHours: $("#numHours"), - numListenPorts: $("#numListenPorts"), - isWAF: $("#isWAF"), + region: document.getElementById("region"), + numNcus: document.getElementById("numNcus"), + numHours: document.getElementById("numHours"), + numListenPorts: document.getElementById("numListenPorts"), + isWAF: document.getElementById("isWAF"), }; /** - * @type {Object.} + * @type {Object.} */ const costFormLabelElements = { - numNcusEstVal: $("#numNcusEstVal"), + numNcusEstVal: document.getElementById("numNcusEstVal"), }; /** - * @type {Object.} + * @type {Object.} */ const ncuFormElements = { - avgNewConnsPerSec: $("#avgNewConnsPerSec"), - avgConnDuration: $("#avgConnDuration"), - totalBandwidth: $("#totalBandwidth"), + avgNewConnsPerSec: document.getElementById("avgNewConnsPerSec"), + avgConnDuration: document.getElementById("avgConnDuration"), + totalBandwidth: document.getElementById("totalBandwidth"), }; /** - * @type {Object.} + * @type {Object.} */ const ncuEstimateElements = { - ncuEstConnRate: $("#ncuEstConnRate"), - ncuEstConnDuration: $("#ncuEstConnDuration"), - ncuEstAvgConn: $("#ncuEstAvgConn"), - ncuEstAvgConn2: $("#ncuEstAvgConn2"), - ncuEstConnRate2: $("#ncuEstConnRate2"), - ncuEstDataRate: $("#ncuEstDataRate"), - ncuEstMin1: $("#ncuEstMin1"), - ncuEstMin: $("#ncuEstMin"), - ncuEstTotal: $("#ncuEstTotal"), - ncuEstConnsPerNcu: $("#ncuEstConnsPerNcu"), - ncuEstConnsPerSecondPerNcu: $("#ncuEstConnsPerSecondPerNcu"), - ncuEstMbpsPerNcu: $("#ncuEstMbpsPerNcu"), + ncuEstConnRate: document.getElementById("ncuEstConnRate"), + ncuEstConnDuration: document.getElementById("ncuEstConnDuration"), + ncuEstAvgConn: document.getElementById("ncuEstAvgConn"), + ncuEstAvgConn2: document.getElementById("ncuEstAvgConn2"), + ncuEstConnRate2: document.getElementById("ncuEstConnRate2"), + ncuEstDataRate: document.getElementById("ncuEstDataRate"), + ncuEstMin1: document.getElementById("ncuEstMin1"), + ncuEstMin: document.getElementById("ncuEstMin"), + ncuEstTotal: document.getElementById("ncuEstTotal"), + ncuEstConnsPerNcu: document.getElementById("ncuEstConnsPerNcu"), + ncuEstConnsPerSecondPerNcu: document.getElementById("ncuEstConnsPerSecondPerNcu"), + ncuEstMbpsPerNcu: document.getElementById("ncuEstMbpsPerNcu"), }; /** - * @type {Object.} + * @type {Object.} */ const totalCostDetailElements = { - ncus: $("#cost-detail-ncus"), - hours: $("#cost-detail-hours"), - tierCost: $("#cost-detail-tier-cost"), - listenPorts: $("#cost-detail-listen-ports"), - listenPortsCost: $("#cost-detail-listen-ports-cost"), - waf: $("#cost-detail-waf"), - total: $("#cost-detail-total"), - tiersCostsTable: $("#tiers-costs-table"), + ncus: document.getElementById("cost-detail-ncus"), + hours: document.getElementById("cost-detail-hours"), + tierCost: document.getElementById("cost-detail-tier-cost"), + listenPorts: document.getElementById("cost-detail-listen-ports"), + listenPortsCost: document.getElementById("cost-detail-listen-ports-cost"), + waf: document.getElementById("cost-detail-waf"), + total: document.getElementById("cost-detail-total"), + tiersCostsTable: document.getElementById("tiers-costs-table"), }; /////// @@ -245,7 +245,7 @@ ncuEstimateValues = ncuEstimateValuesState ) => { Object.keys(costFormElements).map((elName) => { - costFormElements[elName].on("change", (evt) => { + costFormElements[elName].addEventListener("change", (evt) => { if (elName === "isWAF") { values[elName] = evt.target.checked; } else { @@ -256,13 +256,13 @@ }); Object.keys(ncuFormElements).map((elName) => { - ncuFormElements[elName].on("change", (evt) => { + ncuFormElements[elName].addEventListener("change", (evt) => { ncuEstimateValues[elName] = evt.target.value; updateNcuEstimate(ncuEstimateValues); }); }); - $("#printButton").click(() => { + document.getElementById("printButton").addEventListener('click', () => { printCostEstimate(); }); }; @@ -276,7 +276,7 @@ * @param {Costs["regionsTiers"]} regionsTiers */ const populateTierSelect = (regionsTiers) => { - const $selectTarget = $("#region"); + const $selectTarget = document.getElementById("region"); Object.keys(regionsTiers).forEach((tierKey) => { const option = document.createElement("option"); @@ -320,10 +320,10 @@ const initializeValues = (values = calculatorValuesState) => { Object.keys(costFormElements).map((elName) => { const curEl = costFormElements[elName]; - if (curEl.is("input") || curEl.is("select")) { - curEl.val(values[elName]); + if (curEl.tagName.toLowerCase() === "input" || curEl.tagName.toLowerCase() === "select") { + curEl.value = values[elName]; } else { - $(curEl).children("input").first().val(values[elName]); + $(curEl).children("input").first().value = values[elName]; } }); }; @@ -336,22 +336,21 @@ const initializeNcuEstimateValues = (values = ncuEstimateValuesState) => { Object.keys(ncuFormElements).map((elName) => { const curEl = ncuFormElements[elName]; - if (curEl.is("input") || curEl.is("select")) { - curEl.val(values[elName]); + if (curEl.tagName.toLowerCase() === "input" || curEl.tagName.toLowerCase() === "select") { + curEl.value = values[elName]; } else { - $(curEl).children("input").first().val(values[elName]); + $(curEl).children("input").first().value = values[elName]; } }); updateNcuEstimate(ncuEstimateValuesState); - ncuEstimateElements.ncuEstConnsPerNcu.text(ncuParameterVals.connsPerNcu); - ncuEstimateElements.ncuEstConnsPerSecondPerNcu.text( + ncuEstimateElements.ncuEstConnsPerNcu.textContent = ncuParameterVals.connsPerNcu; + ncuEstimateElements.ncuEstConnsPerSecondPerNcu.textContent = ( ncuParameterVals.connsPerSecPerAcu * ncuParameterVals.acusPerNcu - ).toFixed(2) - ); - ncuEstimateElements.ncuEstMbpsPerNcu.text(ncuParameterVals.mbpsPerNcu); + ).toFixed(2); + ncuEstimateElements.ncuEstMbpsPerNcu.textContent = ncuParameterVals.mbpsPerNcu; }; ////// @@ -366,30 +365,27 @@ const updateNcuEstimate = (ncuValues) => { const updatedNcuValues = utils.calculateNcuValues(ncuValues); - $("#ncuEstimateValue").text(`${updatedNcuValues.total} NCUs`); + document.getElementById("ncuEstimateValue").textContent = `${updatedNcuValues.total} NCUs`; // update cost estimate form when estimated number of NCUs changes if (calculatorValuesState.numNcus !== updatedNcuValues.total) { - costFormElements.numNcus.val(updatedNcuValues.total).trigger("change"); + costFormElements.numNcus.value = updatedNcuValues.total + costFormElements.numNcus.dispatchEvent(new Event("change")); } - ncuEstimateElements.ncuEstConnRate.text(ncuValues.avgNewConnsPerSec); - ncuEstimateElements.ncuEstConnDuration.text(ncuValues.avgConnDuration); - ncuEstimateElements.ncuEstAvgConn.text( - updatedNcuValues.avgConcurrentConnections - ); + ncuEstimateElements.ncuEstConnRate.textContent = ncuValues.avgNewConnsPerSec; + ncuEstimateElements.ncuEstConnDuration.textContent = ncuValues.avgConnDuration; + ncuEstimateElements.ncuEstAvgConn.textContent = updatedNcuValues.avgConcurrentConnections; - ncuEstimateElements.ncuEstAvgConn2.text( - updatedNcuValues.avgConcurrentConnections - ); - ncuEstimateElements.ncuEstConnRate2.text(ncuValues.avgNewConnsPerSec); - ncuEstimateElements.ncuEstDataRate.text(ncuValues.totalBandwidth); + ncuEstimateElements.ncuEstAvgConn2.textContent = updatedNcuValues.avgConcurrentConnections; + ncuEstimateElements.ncuEstConnRate2.textContent = ncuValues.avgNewConnsPerSec; + ncuEstimateElements.ncuEstDataRate.textContent = ncuValues.totalBandwidth; - ncuEstimateElements.ncuEstMin1.text((updatedNcuValues.min ?? 0).toFixed(2)); - ncuEstimateElements.ncuEstMin.text((updatedNcuValues.min ?? 0).toFixed(2)); - ncuEstimateElements.ncuEstTotal.text(updatedNcuValues.total); + ncuEstimateElements.ncuEstMin1.textContent = (updatedNcuValues.min ?? 0).toFixed(2); + ncuEstimateElements.ncuEstMin.textContent = (updatedNcuValues.min ?? 0).toFixed(2); + ncuEstimateElements.ncuEstTotal.textContent = updatedNcuValues.total; - costFormLabelElements.numNcusEstVal.text(updatedNcuValues.total); + costFormLabelElements.numNcusEstVal.textContent = updatedNcuValues.total; }; /** @@ -402,7 +398,7 @@ const updateCost = (costs, values = calculatorValuesState) => { const updatedTotalCost = utils.calculateCost(costs, values); - $("#total-value").text(utils.currencyFormatter(updatedTotalCost)); + document.getElementById("total-value").textContent = utils.currencyFormatter(updatedTotalCost); updateTotalCostDetails(values, updatedTotalCost); }; @@ -411,40 +407,34 @@ * @param {number} totalCost */ const updateTotalCostDetails = (formValues, totalCost) => { - totalCostDetailElements.hours.text(formValues.numHours); - totalCostDetailElements.ncus.text(formValues.numNcus); - totalCostDetailElements.listenPorts.text( - Math.max(formValues.numListenPorts - 5, 0) - ); - totalCostDetailElements.listenPortsCost.text( - utils.currencyFormatter(costs.listenPorts) - ); + totalCostDetailElements.hours.textContent = formValues.numHours; + totalCostDetailElements.ncus.textContent = formValues.numNcus; + totalCostDetailElements.listenPorts.textContent = Math.max(formValues.numListenPorts - 5, 0); + totalCostDetailElements.listenPortsCost.textContent = utils.currencyFormatter(costs.listenPorts); if (formValues.isWAF) { - totalCostDetailElements.tierCost.text( + totalCostDetailElements.tierCost.textContent = `(${utils.currencyFormatter( costs.tiersCosts[costs.regionsTiers[formValues.region].tier] - )} region cost + ${utils.currencyFormatter(costs.WAF, 3)} WAF cost)` - ); + )} region cost + ${utils.currencyFormatter(costs.WAF, 3)} WAF cost)`; } else { - totalCostDetailElements.tierCost.text( + totalCostDetailElements.tierCost.textContent = utils.currencyFormatter( costs.tiersCosts[costs.regionsTiers[formValues.region].tier] - ) - ); + ); } - totalCostDetailElements.total.text(utils.currencyFormatter(totalCost)); + totalCostDetailElements.total.textContent = utils.currencyFormatter(totalCost); // update highlighted tier cost const rowIndex = Object.keys(costs.regionsTiers).indexOf(formValues.region) + 1; - totalCostDetailElements.tiersCostsTable.find("tr")?.each((index, rowEl) => { + totalCostDetailElements.tiersCostsTable.querySelectorAll("tr")?.forEach((rowEl, index) => { if (index === rowIndex) { - $(rowEl).addClass("selected"); + rowEl.classList.add("selected"); } else { - $(rowEl).removeClass("selected"); + rowEl.classList.remove("selected"); } }); }; @@ -455,25 +445,25 @@ */ function printCostEstimate() { // expand the total price details if they aren't already - const totalDetails = $("#total-cost-details"); - const detailsOpen = totalDetails.attr("open"); + const totalDetails = document.getElementById("total-cost-details"); + const detailsOpen = totalDetails.hasAttribute("open"); if (!detailsOpen) { - totalDetails.attr("open", "true"); + totalDetails.setAttribute("open", "true"); } - const ncuDetails = $("#ncu-usage-details"); - const ncuDetailsOpen = ncuDetails.attr("open"); + const ncuDetails = document.getElementById("ncu-usage-details"); + const ncuDetailsOpen = ncuDetails.hasAttribute("open"); if (!ncuDetailsOpen) { - ncuDetails.attr("open", "true"); + ncuDetails.setAttribute("open", "true"); } window.print(); // collapse the total price details if it was closed initially if (!detailsOpen) { - totalDetails.attr("open", null); + totalDetails.setAttribute("open", null); } if (!ncuDetailsOpen) { - ncuDetails.attr("open", null); + ncuDetails.setAttribute("open", null); } }