diff --git a/.cloudcannon/schemas/default.md b/.cloudcannon/schemas/default.md index e3a9186f0..474baab89 100644 --- a/.cloudcannon/schemas/default.md +++ b/.cloudcannon/schemas/default.md @@ -39,7 +39,7 @@ To do xzy, take the following steps: 2. Format as numbered lists. - {{< note >}}Add notes like this.{{}} + {{< call-out "note" >}}Add notes like this.{{< /call-out >}} 3. If there is only one step, you don't need to format it as a numbered list. diff --git a/.cloudcannon/schemas/nms/policy.md b/.cloudcannon/schemas/nms/policy.md index 4f5d0054c..bd2d670c3 100644 --- a/.cloudcannon/schemas/nms/policy.md +++ b/.cloudcannon/schemas/nms/policy.md @@ -81,7 +81,7 @@ The following table lists the configurable settings and their default values for {{%tab name="API"%}} -{{}}{{< include "acm/how-to/access-acm-api.md" >}}{{}} +{{< call-out "note" >}}{{< include "acm/how-to/access-acm-api.md" >}}{{< /call-out >}} To create an XYZ policy using the REST API, send an HTTP `POST` request to the Add-Endpoint-Name-Here endpoint. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 47978539f..09f9c2eea 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,35 +1,31 @@ ### Proposed changes -Write a clear and concise description that helps reviewers understand the purpose and impact of your changes. Use the -following format: +[//]: # "Write a clear and concise description of what the pull request changes." +[//]: # "You can use our Commit messages guidance for this." +[//]: # "https://github.com/nginx/documentation/blob/main/documentation/git-conventions.md#commit-messages" -Problem: Give a brief overview of the problem or feature being addressed. +[//]: # "First, explain what was changed, and why. This should be most of the detail." +[//]: # "Then how the changes were made, such as referring to existing styles and conventions." +[//]: # "Finish by noting anything beyond the scope of the PR changes that may be affected." -Solution: Explain the approach you took to implement the solution, highlighting any significant design decisions or -considerations. +[//]: # "Include information on testing if relevant and non-obvious from the deployment preview." +[//]: # "For expediency, you can use screenshots to show small before and after examples." -Testing: Describe any testing that you did. +[//]: # "If the changes were defined by a GitHub issue, reference it using keywords." +[//]: # "https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests" -Please focus on (optional): If you any specific areas where you would like reviewers to focus their attention or provide -specific feedback, add them here. - -If this PR addresses an [issue](https://github.com/nginx/documentation/issues) on GitHub, ensure that you link to it here: - -Closes #ISSUE +[//]: # "Do not like to any internal, non-public resources. This includes internal repository issues or anything in an intranet." +[//]: # "You can make reference to internal discussions without linking to them: see 'Referencing internal information'." +[//]: # "https://github.com/nginx/documentation/blob/main/documentation/closed-contributions.md#referencing-internal-information" ### Checklist -Before merging a pull request, run through this checklist and mark each as complete. +Before sharing this pull request, I completed the following checklist: -- [ ] I have read the [contributing guidelines](https://github.com/nginx/documentation/blob/main/CONTRIBUTING.md) -- [ ] I have signed the [F5 Contributor License Agreement (CLA)](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md) -- [ ] I have rebased my branch onto main -- [ ] I have ensured my PR is targeting the main branch and pulling from my branch from my own fork -- [ ] I have ensured that the commit messages adhere to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) -- [ ] I have ensured that documentation content adheres to [the style guide](/documentation/style-guide.md) -- [ ] If the change involves potentially sensitive changes[^1], I have assessed the possible impact -- [ ] If applicable, I have added tests that prove my fix is effective or that my feature works -- [ ] I have ensured that existing tests pass after adding my changes -- [ ] If applicable, I have updated [`README.md`](/README.md) +- [ ] I read the [Contributing guidelines](https://github.com/nginx/documentation/blob/main/CONTRIBUTING.md) +- [ ] My branch adheres to the [Git conventions](https://github.com/nginx/documentation/blob/main/documentation/git-conventions.md) +- [ ] My content changes adhere to the [F5 NGINX Documentation style guide](https://github.com/nginx/documentation/blob/main/documentation/style-guide.md) +- [ ] If my changes involve potentially sensitive information[^1], I have assessed the possible impact +- [ ] I have waited to ensure my changes pass tests, and addressed any discovered issues -[^1]: Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to [our style guide](/documentation/style-guide.md) for guidance about placeholder content. \ No newline at end of file +[^1]: Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the [style guide](https://github.com/nginx/documentation/blob/main/documentation/style-guide.md) for guidance about placeholder content. diff --git a/.github/workflows/build-push.yml b/.github/workflows/build-push.yml index aedf4214e..2bca0af56 100644 --- a/.github/workflows/build-push.yml +++ b/.github/workflows/build-push.yml @@ -101,6 +101,11 @@ jobs: value: `${{ github.event.client_payload.author }}`, short: true }, + { + title: 'Description', + value: `${{ github.event.client_payload.description }}`, + short: false + }, { title: 'Preview URL', value: `${{ env.PREVIEW_URL }}`, diff --git a/.github/workflows/coveo.yml b/.github/workflows/coveo.yml index 3f1bf42fd..b3ae31ded 100644 --- a/.github/workflows/coveo.yml +++ b/.github/workflows/coveo.yml @@ -41,6 +41,11 @@ jobs: "type": "User", "name": "anonymous", "provider": "Email Security Provider" + }, + { + "type": "User", + "name": "community.guestuser@f5.com", + "provider": "Email Security Provider" } ] }') @@ -72,7 +77,7 @@ jobs: needs: generate-coveo-search-token steps: - name: Download Coveo search token - uses: actions/download-artifact@v4 + uses: actions/download-artifact@v5 - name: View files run: ls -R diff --git a/.github/workflows/dot-org-content.yml b/.github/workflows/dot-org-content.yml new file mode 100644 index 000000000..653562207 --- /dev/null +++ b/.github/workflows/dot-org-content.yml @@ -0,0 +1,56 @@ +name: Detect changes in documentation within nginx/nginx.org + +on: + schedule: + - cron: "0 */23 * * *" +permissions: + contents: write + pull-requests: write + issues: write + +jobs: + detect-changes: + name: Detect changes in 'en' docs of nginx/nginx.org + runs-on: ubuntu-latest + outputs: + IS_CHANGES_DETECTED: ${{ steps.check_changes.outputs.changed }} + steps: + - name: Checkout Repository + uses: actions/checkout@85e6279cec87321a52edac9c87bce653a07cf6c2 # v4.2.2 + with: + fetch-depth: 0 + - name: Clone the nginx/nginx-org repository + run: | + git clone --depth=2 https://github.com/nginx/nginx.org.git dot-org-repo + - name: Check for changes in xml/en folder + id: check_changes + run: | + cd dot-org-repo + + if git whatchanged --since="1 day ago" -- _xml/en/; then + echo "Changes detected in /en" + echo "changed=true" >> $GITHUB_OUTPUT + else + echo "No changes in /en" + echo "changed=false" >> $GITHUB_OUTPUT + fi + - name: Execute make target 'make hugo-md' to generate markdown + if: steps.check_changes.outputs.changed == 'true' + run: | + cd dot-org-repo + make module-markdown + - name: Create PR + uses: peter-evans/create-pull-request@v7 + if: steps.check_changes.outputs.changed == 'true' + with: + commit-message: "chore: Update nginx plus module reference from detected changes in nginx/nginx.org" + labels: product/nginx-plus, dependencies, module-reference + base: main + branch: update-nginx-module-ref + title: 'NGINX Plus - Module Ref: Update content for content/nginx due to detected changes' + add-paths: | + dot-org-repo/libxslt-md/ + dot-org-repo/yaml/nginx_api.yaml + body: | + ### Proposed Changes + Updated NGINX Plus docs. diff --git a/.github/workflows/linkchecker.yml b/.github/workflows/linkchecker.yml index bf148bda9..815f3aed7 100644 --- a/.github/workflows/linkchecker.yml +++ b/.github/workflows/linkchecker.yml @@ -31,7 +31,7 @@ env: --ignore-url ^https://lightstep.com --ignore-url ^https://www.owasp.org/ --ignore-url ^https://www.maxmind.com --ignore-url ^https://www.splunk.com/ --ignore-url ^https://oauth2.googleapis.com --ignore-url ^https://openidconnect.googleapis.com --ignore-url ^https://www.base64url.com/ --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 ^http://www.redirectpage.com/ --ignore-url ^https://www.gnu.org/ --ignore-url ^https://insert_your_tenant_name.console.ves.volterra.io --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 diff --git a/.github/workflows/ossf_scorecard.yml b/.github/workflows/ossf_scorecard.yml index 864924b3a..79b6ee6f4 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@181d5eefc20863364f96762470ba6f862bdef56b # v3.29.2 + uses: github/codeql-action/upload-sarif@76621b61decf072c1cee8dd1ce2d2a82d33c17ed # v3.29.5 with: sarif_file: results.sarif diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7a0af1f48..3988f3345 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,6 +41,7 @@ To understand how we use Git in this repository, read our [Git conventions](/doc The broad workflow is as follows: - Fork the NGINX repository + - If you're an F5/NGINX user, you can work from a clone - Create a branch - Implement your changes in your branch - Submit a pull request (PR) when your changes are ready for review diff --git a/_banners/eos-acm.md b/_banners/eos-acm.md new file mode 100644 index 000000000..e69f51b6b --- /dev/null +++ b/_banners/eos-acm.md @@ -0,0 +1,8 @@ +{{< banner "warning" "End of Sale Notice:" >}} +
+ F5 NGINX is announcing the End of Sale (EoS) for NGINX Management Suite API Connectivity Manager Module, effective January 1, 2024. +

+ F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing API Connectivity Manager Module customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024. +

+ See our End of Sale announcement for more details. +{{}} \ No newline at end of file diff --git a/_banners/eos-mesh.md b/_banners/eos-mesh.md index e69f51b6b..f2b11d535 100644 --- a/_banners/eos-mesh.md +++ b/_banners/eos-mesh.md @@ -1,8 +1,8 @@ {{< banner "warning" "End of Sale Notice:" >}} -
- F5 NGINX is announcing the End of Sale (EoS) for NGINX Management Suite API Connectivity Manager Module, effective January 1, 2024. -

- F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing API Connectivity Manager Module customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024. -

- See our End of Sale announcement for more details. +

+ Commercial support for NGINX Service Mesh is available to customers who currently have active NGINX Microservices Bundle subscriptions. F5 NGINX announced the End of Sale (EoS) for the NGINX Microservices Bundles as of July 1, 2023. +

+

+ See our End of Sale announcement for more details. +

{{}} \ No newline at end of file diff --git a/content/_index.md b/content/_index.md index d6816edad..3fb0a1782 100644 --- a/content/_index.md +++ b/content/_index.md @@ -1,4 +1,4 @@ --- title: NGINX Product Documentation description: Learn how to deliver, manage, and protect your applications using F5 NGINX products. ---- \ No newline at end of file +--- diff --git a/content/agent/_index.md b/content/agent/_index.md index 478ab4f4b..cb96121f2 100644 --- a/content/agent/_index.md +++ b/content/agent/_index.md @@ -2,7 +2,7 @@ title: NGINX Agent url: /nginx-agent/ cascade: - logo: NGINX-product-icon.png + logo: NGINX-Agent-product-icon.svg nd-banner: enabled: true type: deprecation diff --git a/content/agent/configuration/_index.md b/content/agent/configuration/_index.md index ca784b6eb..efb76f9ff 100644 --- a/content/agent/configuration/_index.md +++ b/content/agent/configuration/_index.md @@ -3,7 +3,7 @@ title: "Configuration" weight: "400" url: /nginx-agent/configuration/ cascade: - logo: NGINX-product-icon.png + logo: NGINX-product-icon.svg layout: agent-v2-migration --- diff --git a/content/agent/configuration/configuration-overview.md b/content/agent/configuration/configuration-overview.md index 41086bd8a..5afaedac4 100644 --- a/content/agent/configuration/configuration-overview.md +++ b/content/agent/configuration/configuration-overview.md @@ -9,7 +9,7 @@ nd-content-type: how-to The following sections explain how to configure NGINX Agent using configuration files, CLI flags, and environment variables. -{{}} +{{< call-out "note" >}} - NGINX Agent interprets configuration values set by configuration files, CLI flags, and environment variables in the following priorities: @@ -19,7 +19,7 @@ The following sections explain how to configure NGINX Agent using configuration - You must open any required firewall ports or add SELinux/AppArmor rules for the ports and IPs you want to use. -{{}} +{{< /call-out >}} ## Configure with Config Files @@ -30,9 +30,9 @@ Examples of the configuration files are provided below:
example nginx-agent.conf -{{}} +{{< call-out "note" >}} In the following example `nginx-agent.conf` file, you can change the `server.host` and `server.grpcPort` to connect to the control plane. -{{}} +{{< /call-out >}} ```nginx {hl_lines=[13]} # @@ -118,11 +118,11 @@ nginx_app_protect:
example dynamic-agent.conf -{{}} +{{< call-out "note" >}} Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf` Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.conf` -{{}} +{{< /call-out >}} ```yaml # Dynamic configuration file for NGINX Agent. @@ -169,13 +169,13 @@ nginx-agent ### CLI Flags and Environment Variables -{{< warning >}} +{{< call-out "warning" >}} Before version 2.35.0, the environment variables were prefixed with `NMS_` instead of `NGINX_AGENT_`. If you are upgrading from an older version, update your configuration accordingly. -{{< /warning >}} +{{< /call-out >}} {{}} | CLI flag | Environment variable | Description | @@ -218,7 +218,7 @@ If you are upgrading from an older version, update your configuration accordingl
-{{}} +{{< call-out "note" >}} Use the `--config-dirs` command-line option, or the `config_dirs` key in the `nginx-agent.conf` file, to identify the directories NGINX Agent can read from or write to. This setting also defines the location to which you can upload config files when using a control plane. NGINX Agent cannot write to directories outside the specified location when updating a config and cannot upload files to directories outside of the configured location. @@ -227,15 +227,15 @@ NGINX Agent follows NGINX configuration directives to file paths outside the des - [`ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) -{{}} +{{< /call-out >}} -{{}} Use the `--dynamic-config-path` command-line option to set the location of the dynamic config file. This setting also requires you to move your dynamic config to the new path, or create a new dynamic config file at the specified location. +{{< call-out "note" >}} Use the `--dynamic-config-path` command-line option to set the location of the dynamic config file. This setting also requires you to move your dynamic config to the new path, or create a new dynamic config file at the specified location. Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf` Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.conf` -{{}} +{{< /call-out >}} ## Log Rotation diff --git a/content/agent/configuration/encrypt-communication.md b/content/agent/configuration/encrypt-communication.md index 6a1503cf6..2d8b67dde 100644 --- a/content/agent/configuration/encrypt-communication.md +++ b/content/agent/configuration/encrypt-communication.md @@ -94,7 +94,7 @@ NGINX_AGENT_TLS_ENABLE=true ## Enable Server-Side TLS With Self-Signed Certificate -{{< warning >}}These steps are not recommended for production environments.{{< /warning >}} +{{< call-out "warning" >}}These steps are not recommended for production environments.{{< /call-out >}} To enable server-side TLS with a self-signed certificate, you must have TLS enabled and set `skip_verify` to `true`, which disables hostname validation. Setting `skip_verify` can be done done only by updating the configuration file. See the following example: diff --git a/content/agent/installation-upgrade/_index.md b/content/agent/installation-upgrade/_index.md index d17ef4d5d..9d4f84513 100644 --- a/content/agent/installation-upgrade/_index.md +++ b/content/agent/installation-upgrade/_index.md @@ -4,6 +4,6 @@ description: Learn how to install, upgrade, and uninstall NGINX Agent. weight: 300 url: /nginx-agent/v2/installation-upgrade/ cascade: - logo: NGINX-product-icon.png + logo: NGINX-product-icon.svg type: agent-v2-migration --- diff --git a/content/agent/installation-upgrade/container-environments/_index.md b/content/agent/installation-upgrade/container-environments/_index.md index bc1eeddd7..5f5968743 100644 --- a/content/agent/installation-upgrade/container-environments/_index.md +++ b/content/agent/installation-upgrade/container-environments/_index.md @@ -4,6 +4,6 @@ description: Learn how to build and run NGINX Agent docker images. weight: 800 url: /nginx-agent/v2/installation-upgrade/container-environments/ cascade: - logo: NGINX-product-icon.png + logo: NGINX-product-icon.svg type: agent-v2-migration --- diff --git a/content/agent/installation-upgrade/container-environments/docker-images.md b/content/agent/installation-upgrade/container-environments/docker-images.md index f21c23929..c881be0a0 100644 --- a/content/agent/installation-upgrade/container-environments/docker-images.md +++ b/content/agent/installation-upgrade/container-environments/docker-images.md @@ -27,7 +27,7 @@ This guide provides instructions on how to build images with NGINX Agent and NGI You can use [Docker](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/docs/installation) to manage NGINX Agent container images. Follow the installation instructions for your preferred container engine and be sure the service is running before proceeding with the instructions in this document. -{{}}The examples in this document primarily use Docker commands. You can adapt these using the appropriate [Podman commands](https://docs.podman.io/en/latest/Commands.html) if you're not using Docker.{{}} +{{< call-out "note" >}}The examples in this document primarily use Docker commands. You can adapt these using the appropriate [Podman commands](https://docs.podman.io/en/latest/Commands.html) if you're not using Docker.{{< /call-out >}} ### Install the GNU Make package @@ -112,11 +112,11 @@ docker tag docker-registry.nginx.com/nginx/agent:mainline nginx-agent docker run --name nginx-agent -d nginx-agent ``` -{{}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< ref "/agent/configuration/configuration-overview" >}}).{{}} +{{< call-out "note" >}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< ref "/agent/configuration/configuration-overview" >}}).{{< /call-out >}} ### Enable the gRPC interface -To connect your NGINX Agent container to your NGINX One or NGINX Instance Manager instance, you must enable the gRPC interface. To do this, you must edit the NGINX Agent configuration file, *nginx-agent.conf*. For example: +To connect your NGINX Agent container to your NGINX One Console or NGINX Instance Manager instance, you must enable the gRPC interface. To do this, you must edit the NGINX Agent configuration file, *nginx-agent.conf*. For example: ```yaml server: @@ -166,7 +166,7 @@ If the REST Interface is configured correctly, then you should see a JSON object ## Build the NGINX Agent images for specific OS targets -{{}}The only **officially supported** base operating system is **Alpine**. The instructions below for other operating systems are provided for informational and **testing purposes only**.{{}} +{{< call-out "important" >}}The only **officially supported** base operating system is **Alpine**. The instructions below for other operating systems are provided for informational and **testing purposes only**.{{< /call-out >}} The NGINX Agent GitHub repo has a set of Make commands that you can use to build a container image for an specific operating system and version: @@ -200,7 +200,7 @@ IMAGE_BUILD_TARGET=install-agent-repo NGINX_AGENT_VERSION=2.37.0~bullseye OS_REL ### Build NGINX Plus images -{{}}You need a license to use NGINX Agent with NGINX Plus. You must complete the steps in the [Download the certificate and key files from MyF5](#myf5-download) section before proceeding.{{}} +{{< call-out "important" >}}You need a license to use NGINX Agent with NGINX Plus. You must complete the steps in the [Download the certificate and key files from MyF5](#myf5-download) section before proceeding.{{< /call-out >}} Run the following `make` command to build the default image, which uses Ubuntu 24.04 (Noble) as the base image. diff --git a/content/agent/installation-upgrade/getting-started.md b/content/agent/installation-upgrade/getting-started.md index c7ee427af..e415d9161 100644 --- a/content/agent/installation-upgrade/getting-started.md +++ b/content/agent/installation-upgrade/getting-started.md @@ -172,8 +172,8 @@ sudo systemctl enable nginx-agent NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of the NGINX Agent log files. We recommend adding a separate partition for `/var/log/nginx-agent`. -{{< important >}} +{{< call-out "important" >}} Without log rotation or storage on a separate partition, log files could use up all the free drive space and cause your system to become unresponsive to certain services. For more information, see [NGINX Agent Log Rotation]({{< ref "/agent/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}). -{{< /important >}} +{{< /call-out >}} diff --git a/content/agent/installation-upgrade/installation-oss.md b/content/agent/installation-upgrade/installation-oss.md index ab4016d08..6d3073998 100644 --- a/content/agent/installation-upgrade/installation-oss.md +++ b/content/agent/installation-upgrade/installation-oss.md @@ -50,10 +50,10 @@ Before you install NGINX Agent for the first time on your system, you need to se module_hotfixes=true ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo yum install nginx-agent + sudo yum install -y nginx-agent-2.42.0 ``` When prompted to accept the GPG key, verify that the fingerprint matches `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. @@ -95,7 +95,7 @@ Before you install NGINX Agent for the first time on your system, you need to se uid nginx signing key ``` - {{< important >}}If the fingerprint is different, remove the file.{{< /important >}} + {{< call-out "important" >}}If the fingerprint is different, remove the file.{{< /call-out >}} 1. Add the nginx agent repository: @@ -105,11 +105,13 @@ Before you install NGINX Agent for the first time on your system, you need to se | sudo tee /etc/apt/sources.list.d/nginx-agent.list ``` -1. To install `nginx-agent`, run the following commands: - +1. To install `nginx-agent` with a specific version (example: 2.42.0): + + Update your package index and install a specific version of the nginx-agent. Replace with your current Ubuntu codename (e.g., jammy, noble). + ```shell sudo apt update - sudo apt install nginx-agent + sudo apt install -y nginx-agent=2.42.0~ ``` 1. Verify the installation: @@ -157,7 +159,7 @@ Before you install NGINX Agent for the first time on your system, you need to se uid nginx signing key ``` - {{< important >}}If the fingerprint is different, remove the file.{{< /important >}} + {{< call-out "important" >}}If the fingerprint is different, remove the file.{{< /call-out >}} 1. Add the `nginx-agent` repository: @@ -166,12 +168,13 @@ Before you install NGINX Agent for the first time on your system, you need to se http://packages.nginx.org/nginx-agent/debian/ `lsb_release -cs` agent" \ | sudo tee /etc/apt/sources.list.d/nginx-agent.list ``` -1. To install `nginx-agent`, run the following commands: +1. To install `nginx-agent` with a specific version (example: 2.42.0): + Update your package index and install a specific version of the nginx-agent. Replace with your current Debian codename (e.g., bullseye). + ```shell sudo apt update - sudo apt install nginx-agent - ``` + sudo apt install -y nginx-agent=2.42.0~ 1. Verify the installation: @@ -229,10 +232,10 @@ Before you install NGINX Agent for the first time on your system, you need to se sudo rpmkeys --import /tmp/nginx_signing.key ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo zypper install nginx-agent + sudo zypper install -y nginx-agent=2.42.0 ``` 1. Verify the installation: @@ -303,10 +306,10 @@ Before you install NGINX Agent for the first time on your system, you need to se sudo mv /tmp/nginx_signing.rsa.pub /etc/apk/keys/ ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo apk add nginx-agent + sudo apk add nginx-agent=2.42.0 ``` 1. Verify the installation: @@ -334,10 +337,10 @@ Before you install NGINX Agent for the first time on your system, you need to se module_hotfixes=true ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo dnf install nginx-agent + sudo dnf install -y nginx-agent-2.42.0 ``` 1. When prompted to accept the GPG key, verify that the fingerprint matches @@ -370,10 +373,10 @@ Before you install NGINX Agent for the first time on your system, you need to se module_hotfixes=true ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo yum install nginx-agent + sudo yum install -y nginx-agent-2.42.0 ``` 1. When prompted to accept the GPG key, verify that the fingerprint matches `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. @@ -396,10 +399,10 @@ Before you install NGINX Agent for the first time on your system, you need to se } ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo pkg install nginx-agent + sudo pkg install nginx-agent-2.42.0 ``` 1. Verify the installation: diff --git a/content/agent/installation-upgrade/installation-plus.md b/content/agent/installation-upgrade/installation-plus.md index add1272dc..744fbde26 100644 --- a/content/agent/installation-upgrade/installation-plus.md +++ b/content/agent/installation-upgrade/installation-plus.md @@ -73,10 +73,10 @@ Before you install NGINX Agent for the first time on your system, you need to se enabled=1 ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo yum install nginx-agent + sudo yum install -y nginx-agent-2.42.0 ``` When prompted to accept the GPG key, verify that the fingerprint matches `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. @@ -131,11 +131,13 @@ Before you install NGINX Agent for the first time on your system, you need to se | sudo tee /etc/apt/sources.list.d/nginx-agent.list ``` -1. To install `nginx-agent`, run the following commands: +1. To install `nginx-agent` with a specific version (example: 2.42.0): + Update your package index and install a specific version of the nginx-agent. Replace with your current Ubuntu codename (e.g., jammy, noble). + ```shell sudo apt update - sudo apt install nginx-agent + sudo apt install -y nginx-agent=2.42.0~ ``` 1. Verify the installation: @@ -183,12 +185,14 @@ Before you install NGINX Agent for the first time on your system, you need to se Acquire::https::pkgs.nginx.com::SslKey "/etc/ssl/nginx/nginx-repo.key"; ``` -1. To install `nginx-agent`, run the following commands: +1. To install `nginx-agent` with a specific version (example: 2.42.0): + Update your package index and install a specific version of the nginx-agent. Replace with your current Debian codename (e.g., bullseye). + ```shell sudo apt update - sudo apt install nginx-agent - ``` + sudo apt install -y nginx-agent=2.42.0~ + 1. Verify the installation: @@ -265,10 +269,10 @@ Before you install NGINX Agent for the first time on your system, you need to se sudo rpmkeys --import /tmp/nginx_signing.key ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo zypper install nginx-agent + sudo zypper install -y nginx-agent=2.42.0 ``` 1. Verify the installation: @@ -394,10 +398,10 @@ Before you install NGINX Agent for the first time on your system, you need to se enabled=1 ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo dnf install nginx-agent + sudo dnf install -y nginx-agent-2.42.0 ``` 1. When prompted to accept the GPG key, verify that the fingerprint matches `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. @@ -442,10 +446,10 @@ Before you install NGINX Agent for the first time on your system, you need to se enabled=1 ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo yum install nginx-agent + sudo yum install -y nginx-agent-2.42.0 ``` 1. When prompted to accept the GPG key, verify that the fingerprint matches `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. @@ -496,10 +500,10 @@ Before you install NGINX Agent for the first time on your system, you need to se SSL_CLIENT_KEY_FILE: "/etc/ssl/nginx/nginx-repo.key" } ``` -1. To install `nginx-agent`, run the following command: +1. To install `nginx-agent` with a specific version (example: 2.42.0): ```shell - sudo pkg install nginx-agent + sudo pkg install nginx-agent-2.42.0 ``` 1. Verify the installation: diff --git a/content/agent/installation-upgrade/installation-unprivileged.md b/content/agent/installation-upgrade/installation-unprivileged.md index 4bf90c9f1..b747aef1d 100644 --- a/content/agent/installation-upgrade/installation-unprivileged.md +++ b/content/agent/installation-upgrade/installation-unprivileged.md @@ -30,9 +30,9 @@ The installation process involves installing NGINX Plus without root privileges You can install NGINX Plus without root privileges following the steps on the [NGINX Plus installation page]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus/#unpriv_install" >}}). The steps include a script that will allow you to install NGINX Plus in a non-root environment. -{{< note >}} +{{< call-out "note" >}} NGINX Agent has its own user group (`nginx-agent`) which is created when NGINX Agent is installed. The user NGINX is running under is added to this user group during the installation of NGINX Agent. If you change the NGINX user after installing NGINX Agent, you will need to [manually add the new NGINX user]({{< ref "/agent/configuration/configure-nginx-agent-group.md" >}}) to the `nginx-agent` group. -{{< /note >}} +{{< /call-out >}} ### Install NGINX Agent diff --git a/content/agent/installation-upgrade/upgrade.md b/content/agent/installation-upgrade/upgrade.md index f942db01f..71beebb96 100644 --- a/content/agent/installation-upgrade/upgrade.md +++ b/content/agent/installation-upgrade/upgrade.md @@ -60,10 +60,10 @@ To upgrade NGINX Agent to a specific **v2.x version**, follow these steps: sudo apt-get install -y nginx-agent= -o Dpkg::Options::="--force-confold" ``` - Example (to upgrade to version 2.41.1~noble): + Example (to upgrade to version 2.42.0~noble): ```shell - sudo apt-get install -y nginx-agent=2.41.1~noble -o Dpkg::Options::="--force-confold" + sudo apt-get install -y nginx-agent=2.42.0~noble -o Dpkg::Options::="--force-confold" ``` - CentOS, RHEL, RPM-Based @@ -72,10 +72,10 @@ To upgrade NGINX Agent to a specific **v2.x version**, follow these steps: sudo yum install -y nginx-agent- ``` - Example (to upgrade to version `2.41.1`): + Example (to upgrade to version `2.42.0`): ```shell - sudo yum install -y nginx-agent-2.41.1 + sudo yum install -y nginx-agent-2.42.0 ``` 1. Verify the installed version: diff --git a/content/agent/technical-specifications.md b/content/agent/technical-specifications.md index b4273c922..c1fda1546 100644 --- a/content/agent/technical-specifications.md +++ b/content/agent/technical-specifications.md @@ -14,10 +14,10 @@ This document provides technical specifications for NGINX Agent. It includes inf {{< bootstrap-table "table table-striped table-bordered" >}} | NGINX Product | Agent Version | |------------------------------|----------------| -| **NGINX One Console** | 2.x | +| **NGINX One Console** | 3.x | | **NGINX Gateway Fabric** | 3.x | | **NGINX Plus** | 2.x, 3.x | -| **NGINX Ingress Controller** | 2.x | +| **NGINX Ingress Controller** | 2.x, 3.x | | **NGINX Instance Manager** | 2.x | {{< /bootstrap-table >}} @@ -26,16 +26,16 @@ This document provides technical specifications for NGINX Agent. It includes inf NGINX Agent can run in most environments. We support the following distributions: {{< bootstrap-table "table table-striped table-bordered" >}} -| | AlmaLinux | Alpine Linux | Amazon Linux | Amazon Linux 2 | CentOS | Debian | -|-|-----------|--------------|--------------|----------------|--------|--------| -|**Version**|8
9 | 3.16
3.17
3.18
3.19| 2023| LTS| 7.4+| 11
12| +| | AlmaLinux | Alpine Linux | Amazon Linux | Amazon Linux 2| Debian | +|-|-----------|--------------|--------------|----------------|--------| +|**Version**|8
9
10| 3.19
3.20
3.21
3.22| 2023| LTS| 11
12| |**Architecture**| x86_84
aarch64| x86_64
aarch64 | x86_64
aarch64 | x86_64
aarch64 | x86_64
aarch64 | x86_64
aarch64 | {{< /bootstrap-table >}} {{< bootstrap-table "table table-striped table-bordered" >}} | |FreeBSD | Oracle Linux | Red Hat
Enterprise Linux
(RHEL) | Rocky Linux | SUSE Linux
Enterprise Server
(SLES) | Ubuntu | |-|--------|--------------|---------------------------------|-------------|-------------------------------------|--------| -|**Version**|13
14|7.4+
8.1+
9|7.4+
8.1+
9.0+|8
9|12 SP5
15 SP2|20.04 LTS
22.04 LTS| +|**Version**|13
14|8.1+
9
10|8.1+
9.0+
10|8
9
10|15 SP2|22.04 LTS
24.04 LTS
25.04 LTS| |**Architecture**|amd64|x86_64|x86_64
aarch64|x86_64
aarch64|x86_64|x86_64
aarch64| {{< /bootstrap-table >}} diff --git a/content/amplify/faq/metrics-and-metadata.md b/content/amplify/faq/metrics-and-metadata.md index f91ae8dd8..6e1b43a79 100644 --- a/content/amplify/faq/metrics-and-metadata.md +++ b/content/amplify/faq/metrics-and-metadata.md @@ -10,4 +10,4 @@ nd-docs: DOCS-957 [NGINX Amplify Agent Metrics and Metadata]({{< ref "/amplify/nginx-amplify-agent/metadata-metrics-collection" >}}) -{{< note >}}For a complete list of metrics, refer to the [Metrics and Metadata documentation]({{< ref "/amplify/metrics-metadata" >}}).{{< /note >}} \ No newline at end of file +{{< call-out "note" >}}For a complete list of metrics, refer to the [Metrics and Metadata documentation]({{< ref "/amplify/metrics-metadata" >}}).{{< /call-out >}} \ No newline at end of file diff --git a/content/amplify/faq/user-interface.md b/content/amplify/faq/user-interface.md index 5bad6022b..547fadcbb 100644 --- a/content/amplify/faq/user-interface.md +++ b/content/amplify/faq/user-interface.md @@ -29,4 +29,4 @@ To completely delete a previously monitored object follow these steps: To delete a system using the web interface — find it in the [Inventory]({{< ref "/amplify/user-interface/inventory" >}}), and select the [i] icon. You can delete objects from the popup window that appears next. -{{< important >}}Deleting objects in the User Interface will not stop NGINX Amplify Agent. To completely remove a system from monitoring, please stop or uninstall NGINX Amplify Agent, clean it up in the web interface, and clean up any alerts.{{< /important >}} +{{< call-out "important" >}}Deleting objects in the User Interface will not stop NGINX Amplify Agent. To completely remove a system from monitoring, please stop or uninstall NGINX Amplify Agent, clean it up in the web interface, and clean up any alerts.{{< /call-out >}} diff --git a/content/amplify/metrics-metadata/nginx-metrics.md b/content/amplify/metrics-metadata/nginx-metrics.md index fd0e5e61c..8e4fb2278 100644 --- a/content/amplify/metrics-metadata/nginx-metrics.md +++ b/content/amplify/metrics-metadata/nginx-metrics.md @@ -241,7 +241,7 @@ To use the extended log format with your access log configuration: access_log /var/log/nginx/access.log main_ext; ``` -{{< note >}} Please keep in mind that by default, NGINX Amplify Agent will process all access logs that are found in your log directory. If you define a new log file with the extended log format that will contain the entries being already logged to another access log, your metrics might be counted twice. Please refer to the NGINX Amplify Agent configuration section above to learn how to exclude specific log files from processing.{{< /note >}} +{{< call-out "note" >}} Please keep in mind that by default, NGINX Amplify Agent will process all access logs that are found in your log directory. If you define a new log file with the extended log format that will contain the entries being already logged to another access log, your metrics might be counted twice. Please refer to the NGINX Amplify Agent configuration section above to learn how to exclude specific log files from processing.{{< /call-out >}} The [error.log](http://nginx.org/en/docs/ngx_core_module.html#error_log) log level should be set to `warn`. @@ -459,7 +459,7 @@ nginx.http.request.current = requests.current The NGINX Plus metrics below are collected *per zone*. When configuring a graph using these metrics, please make sure to pick the correct server, upstream, or cache zone. A more granular peer-specific breakdown of the metrics below is currently not supported in NGINX Amplify. -{{< note >}}NGINX Amplify Agent does not support reporting the following metrics *per zone* but it can be used to display a cumulative sum of values from each zone.{{< /note >}} +{{< call-out "note" >}}NGINX Amplify Agent does not support reporting the following metrics *per zone* but it can be used to display a cumulative sum of values from each zone.{{< /call-out >}} A cumulative metric set is also maintained internally by summing up the per-zone metrics. If you don't configure a specific zone when building graphs, this will result in an "all zones" visualization. E.g., for something like **plus.http.status.2xx** omitting zone will display the instance-wide sum of the successful requests across all zones. diff --git a/content/amplify/metrics-metadata/os-metrics.md b/content/amplify/metrics-metadata/os-metrics.md index 7de32fcb0..8ef0dbdce 100644 --- a/content/amplify/metrics-metadata/os-metrics.md +++ b/content/amplify/metrics-metadata/os-metrics.md @@ -168,7 +168,7 @@ nd-docs: DOCS-974 ## Agent Metrics -{{< note >}} Agent metrics are available only if you are using F5 NGINX Amplify Agent.{{< /note >}} +{{< call-out "note" >}} Agent metrics are available only if you are using F5 NGINX Amplify Agent.{{< /call-out >}} - #### **amplify.agent.status** diff --git a/content/amplify/metrics-metadata/other-metrics.md b/content/amplify/metrics-metadata/other-metrics.md index 2241f57e4..b35617d83 100644 --- a/content/amplify/metrics-metadata/other-metrics.md +++ b/content/amplify/metrics-metadata/other-metrics.md @@ -6,7 +6,7 @@ toc: true nd-docs: DOCS-975 --- -{{< note >}}Monitoring PHP-FPM and MySQL metrics is only supported by F5 NGINX Amplify Agent.{{< /note >}} +{{< call-out "note" >}}Monitoring PHP-FPM and MySQL metrics is only supported by F5 NGINX Amplify Agent.{{< /call-out >}} ## PHP-FPM metrics @@ -24,7 +24,7 @@ To start monitoring PHP-FPM, follow the steps below: service php7.0-fpm restart ``` -2. {{< important >}} Check that NGINX, NGINX Amplify Agent, and the PHP-FPM workers are all run under the same user ID (e.g. `www-data`). You may have to change the used ID for the nginx workers, fix the nginx directories permissions, and then restart NGINX Amplify Agent too. If there are multiple PHP-FPM pools configured with different user IDs, make sure NGINX Amplify Agent's user ID is included in the group IDs of the PHP-FPM workers. This is required in order for NGINX Amplify Agent to access the PHP-FPM pool socket when querying for metrics.{{< /important >}} +2. {{< call-out "important" >}} Check that NGINX, NGINX Amplify Agent, and the PHP-FPM workers are all run under the same user ID (e.g. `www-data`). You may have to change the used ID for the nginx workers, fix the nginx directories permissions, and then restart NGINX Amplify Agent too. If there are multiple PHP-FPM pools configured with different user IDs, make sure NGINX Amplify Agent's user ID is included in the group IDs of the PHP-FPM workers. This is required in order for NGINX Amplify Agent to access the PHP-FPM pool socket when querying for metrics.{{< /call-out >}} 3. Confirm that the listen socket for the PHP-FPM pool you want to monitor and for which you enabled `pm.status_path`, is correctly configured with `listen.owner` and `listen.group`. Look for the following directives inside the pool configuration file. @@ -219,7 +219,7 @@ To start monitoring MySQL, follow the instructions below. 353 rows in set (0.01 sec) ``` - {{< note >}} NGINX Amplify Agent doesn't use *mysql(1)* for metric collection, however it implements a similar query mechanism via a Python module.{{< /note >}} + {{< call-out "note" >}} NGINX Amplify Agent doesn't use *mysql(1)* for metric collection, however it implements a similar query mechanism via a Python module.{{< /call-out >}} 3. [Update]({{< ref "/amplify/nginx-amplify-agent/install/updating-amplify-agent.md" >}}) NGINX Amplify Agent to the most recent version. diff --git a/content/amplify/nginx-amplify-agent/amplify-agent-overview.md b/content/amplify/nginx-amplify-agent/amplify-agent-overview.md index 51cc08ccb..2e91e5443 100644 --- a/content/amplify/nginx-amplify-agent/amplify-agent-overview.md +++ b/content/amplify/nginx-amplify-agent/amplify-agent-overview.md @@ -21,6 +21,6 @@ NGINX Amplify can currently monitor and collect performance metrics for: The NGINX Amplify Agent identifies an NGINX instance as any running NGINX master process with either a unique binary path or a unique configuration. -{{< note >}}There's no need to manually add or configure anything in the web interface after installing NGINX Amplify Agent. When NGINX Amplify Agent is started, the metrics and the metadata are automatically reported to the Amplify backend and visualized in the web interface.{{< /note >}} +{{< call-out "note" >}}There's no need to manually add or configure anything in the web interface after installing NGINX Amplify Agent. When NGINX Amplify Agent is started, the metrics and the metadata are automatically reported to the Amplify backend and visualized in the web interface.{{< /call-out >}} When an NGINX instance is no longer in use it must be manually deleted in the web interface. The "Remove object" button can be found in the metadata viewer popup — see the [User Interface]({{< ref "/amplify/user-interface/">}}) documentation. \ No newline at end of file diff --git a/content/amplify/nginx-amplify-agent/configuration-analysis.md b/content/amplify/nginx-amplify-agent/configuration-analysis.md index 0c227c3a9..e73c2ae4c 100644 --- a/content/amplify/nginx-amplify-agent/configuration-analysis.md +++ b/content/amplify/nginx-amplify-agent/configuration-analysis.md @@ -10,5 +10,5 @@ F5 NGINX Amplify Agent can automatically find all relevant NGINX configuration f After NGINX Amplify Agent finds a particular NGINX configuration, it then automatically starts to keep track of its changes. When a change is detected with NGINX — for example, a master process restarts, or the NGINX config is edited, an update is sent to the Amplify backend. -{{< note >}} NGINX Amplify Agent never sends the raw unprocessed config files to the backend system. In addition, the following directives in the NGINX configuration are never analyzed — and their parameters aren't exported to the SaaS backend: -[ssl_certificate_key](http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html#ssl_certificate_key), [ssl_client_certificate](http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html#ssl_client_certificate), [ssl_password_file](http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html#ssl_password_file), [ssl_stapling_file](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_stapling_file), [ssl_trusted_certificate](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_trusted_certificate), [auth_basic_user_file](http://nginx.org/en/docs/http/ngx_http_auth_basic_module.html#auth_basic_user_file), [secure_link_secret](http://nginx.org/en/docs/http/ngx_http_secure_link_module.html#secure_link_secret).{{< /note >}} +{{< call-out "note" >}} NGINX Amplify Agent never sends the raw unprocessed config files to the backend system. In addition, the following directives in the NGINX configuration are never analyzed — and their parameters aren't exported to the SaaS backend: +[ssl_certificate_key](http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html#ssl_certificate_key), [ssl_client_certificate](http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html#ssl_client_certificate), [ssl_password_file](http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html#ssl_password_file), [ssl_stapling_file](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_stapling_file), [ssl_trusted_certificate](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_trusted_certificate), [auth_basic_user_file](http://nginx.org/en/docs/http/ngx_http_auth_basic_module.html#auth_basic_user_file), [secure_link_secret](http://nginx.org/en/docs/http/ngx_http_secure_link_module.html#secure_link_secret).{{< /call-out >}} diff --git a/content/amplify/nginx-amplify-agent/configuring-metric-collection.md b/content/amplify/nginx-amplify-agent/configuring-metric-collection.md index 311967d69..9c3bed5c9 100644 --- a/content/amplify/nginx-amplify-agent/configuring-metric-collection.md +++ b/content/amplify/nginx-amplify-agent/configuring-metric-collection.md @@ -49,7 +49,7 @@ nginx: configuration file /etc/nginx/nginx.conf test is successful Test your nginx configuration after you've added the `stub_status` section above. Make sure there's no ambiguity with either [listen](http://nginx.org/en/docs/http/ngx_http_core_module.html#listen) or [server_name](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name) configuration. NGINX Amplify Agent should be able to identify the [stub_status](http://nginx.org/en/docs/http/ngx_http_stub_status_module.html) URL and will default to use 127.0.0.1 if the configuration is incomplete. -{{< note >}} If you use the `conf.d*`directory to keep common parts of your NGINX configuration that are then automatically included in the [server](http://nginx.org/en/docs/http/ngx_http_core_module.html#server) sections across your NGINX config, do not use the snippet above. Instead, you should configure [stub_status](http://nginx.org/en/docs/http/ngx_http_stub_status_module.html) manually within an appropriate location or server block. {{< /note >}} +{{< call-out "note" >}} If you use the `conf.d*`directory to keep common parts of your NGINX configuration that are then automatically included in the [server](http://nginx.org/en/docs/http/ngx_http_core_module.html#server) sections across your NGINX config, do not use the snippet above. Instead, you should configure [stub_status](http://nginx.org/en/docs/http/ngx_http_stub_status_module.html) manually within an appropriate location or server block. {{< /call-out >}} The above is an example `nginx_status` URI for [stub_status](http://nginx.org/en/docs/http/ngx_http_stub_status_module.html). NGINX Amplify Agent will determine the correct URI automatically upon parsing your NGINX configuration. Please make sure that the directory and the actual configuration file with `stub_status` are readable by NGINX Amplify Agent; otherwise, NGINX Amplify Agent won't be able to determine the `stub_status` URL correctly. If NGINX Amplify Agent fails to find `stub_status`, please refer to the workaround described [here]({{< ref "/amplify/nginx-amplify-agent/install/configuring-amplify-agent#configuring-the-url-for-stub_status-or-status-api" >}}). @@ -95,7 +95,7 @@ You don't have to specifically point NGINX Amplify Agent to either the NGINX con NGINX Amplify Agent will also try to detect the [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) for a particular log to parse it properly and try to extract even more useful metrics, for example, [$upstream_response_time](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time). -{{< note >}}Several metrics outlined in [Metrics and Metadata]({{< ref "metrics-metadata" >}}) will only be available if the corresponding variables are included in a custom [access.log](http://nginx.org/en/docs/http/ngx_http_log_module.html) format used for logging requests. You can find a complete list of NGINX log variables [here](http://nginx.org/en/docs/varindex.html).{{< /note >}} +{{< call-out "note" >}}Several metrics outlined in [Metrics and Metadata]({{< ref "metrics-metadata" >}}) will only be available if the corresponding variables are included in a custom [access.log](http://nginx.org/en/docs/http/ngx_http_log_module.html) format used for logging requests. You can find a complete list of NGINX log variables [here](http://nginx.org/en/docs/varindex.html).{{< /call-out >}} ## Using Syslog for Metric Collection @@ -118,4 +118,4 @@ If you configured NGINX Amplify Agent for syslog metric collection (see the [con (see more [here](http://nginx.org/en/docs/control.html)) -{{< note >}}To send the NGINX logs to both the existing logging facility and NGINX Amplify Agent, include a separate [access.log](http://nginx.org/en/docs/http/ngx_http_log_module.html) directive for each destination.{{< /note >}} +{{< call-out "note" >}}To send the NGINX logs to both the existing logging facility and NGINX Amplify Agent, include a separate [access.log](http://nginx.org/en/docs/http/ngx_http_log_module.html) directive for each destination.{{< /call-out >}} diff --git a/content/amplify/nginx-amplify-agent/detecting-monitoring-instances.md b/content/amplify/nginx-amplify-agent/detecting-monitoring-instances.md index 85508a998..f513971f3 100644 --- a/content/amplify/nginx-amplify-agent/detecting-monitoring-instances.md +++ b/content/amplify/nginx-amplify-agent/detecting-monitoring-instances.md @@ -16,4 +16,4 @@ A separate instance of NGINX, as seen by NGINX Amplify Agent, would be the follo * A unique master process and its workers, started with an **absolute path** to a distinct NGINX binary * A master process running with a default config path; or with a custom path set in the command-line parameters -{{< note >}}NGINX Amplify Agent will try to detect and monitor all unique NGINX instances currently running on a host. Separate sets of metrics and metadata are collected for each unique NGINX instance. {{< /note >}} +{{< call-out "note" >}}NGINX Amplify Agent will try to detect and monitor all unique NGINX instances currently running on a host. Separate sets of metrics and metadata are collected for each unique NGINX instance. {{< /call-out >}} diff --git a/content/amplify/nginx-amplify-agent/install/configuring-amplify-agent.md b/content/amplify/nginx-amplify-agent/install/configuring-amplify-agent.md index 572725403..07619c363 100644 --- a/content/amplify/nginx-amplify-agent/install/configuring-amplify-agent.md +++ b/content/amplify/nginx-amplify-agent/install/configuring-amplify-agent.md @@ -56,7 +56,7 @@ NGINX Amplify Agent won't start unless a valid hostname is defined. The followin * localhost6.localdomain6 * ip6-localhost -{{< note >}} You can also use the above method to replace the system's hostname with an arbitrary alias. Remember that if you redefine the hostname for a live object, the existing object will be marked as failed in the web interface. Redefining the hostname in NGINX Amplify Agent's configuration creates a new UUID and a new system for monitoring. {{< /note >}} +{{< call-out "note" >}} You can also use the above method to replace the system's hostname with an arbitrary alias. Remember that if you redefine the hostname for a live object, the existing object will be marked as failed in the web interface. Redefining the hostname in NGINX Amplify Agent's configuration creates a new UUID and a new system for monitoring. {{< /call-out >}} Alternatively, you can define an "alias" for the host in the UI (see the [Graphs]({{< ref "/amplify/user-interface/graphs" >}}) section). @@ -80,7 +80,7 @@ To override the URI detection of the status API, use the `plus_status` option. plus_status = /status ``` -{{< note >}} If only the URI part is specified with the options above, NGINX Amplify Agent will use `http://127.0.0.1` to construct the full URL to access either the *stub_status* or the NGINX Plus status API metrics. {{< /note >}} +{{< call-out "note" >}} If only the URI part is specified with the options above, NGINX Amplify Agent will use `http://127.0.0.1` to construct the full URL to access either the *stub_status* or the NGINX Plus status API metrics. {{< /call-out >}} ## Configuring the Path to the NGINX Configuration File @@ -93,7 +93,7 @@ If NGINX Amplify Agent cannot find the NGINX configuration, use the following op configfile = /etc/nginx/nginx.conf ``` -{{< note >}} It is better to avoid using this option and only add it as a workaround. We'd appreciate it if you took some time to fill out a support ticket in case you had to manually add the path to the NGINX config file. {{< /note >}} +{{< call-out "note" >}} It is better to avoid using this option and only add it as a workaround. We'd appreciate it if you took some time to fill out a support ticket in case you had to manually add the path to the NGINX config file. {{< /call-out >}} ## Configuring Host Tags diff --git a/content/amplify/nginx-amplify-agent/install/installing-amplify-agent.md b/content/amplify/nginx-amplify-agent/install/installing-amplify-agent.md index 1dcbb9241..15bd68957 100644 --- a/content/amplify/nginx-amplify-agent/install/installing-amplify-agent.md +++ b/content/amplify/nginx-amplify-agent/install/installing-amplify-agent.md @@ -8,7 +8,7 @@ nd-docs: DOCS-968 To use F5 NGINX Amplify to monitor your infrastructure, you need to install NGINX Amplify Agent on each system you wish to monitor. -{{< note >}} NGINX Amplify Agent will drop *root* privileges on startup. It will then use the user ID of the user `nginx` to set its effective user ID. The package install procedure will add the `nginx` user automatically unless it's already found in the system. If the [user](https://nginx.org/en/docs/ngx_core_module.html#user) directive appears in the NGINX configuration, NGINX Amplify Agent will pick up the user specified in the NGINX config for its effective user ID (e.g. `www-data`). {{< /note >}} +{{< call-out "note" >}} NGINX Amplify Agent will drop *root* privileges on startup. It will then use the user ID of the user `nginx` to set its effective user ID. The package install procedure will add the `nginx` user automatically unless it's already found in the system. If the [user](https://nginx.org/en/docs/ngx_core_module.html#user) directive appears in the NGINX configuration, NGINX Amplify Agent will pick up the user specified in the NGINX config for its effective user ID (e.g. `www-data`). {{< /call-out >}} ## Using the Install Script diff --git a/content/amplify/nginx-amplify-agent/install/updating-amplify-agent.md b/content/amplify/nginx-amplify-agent/install/updating-amplify-agent.md index e7c0f2c57..7f898c1a3 100644 --- a/content/amplify/nginx-amplify-agent/install/updating-amplify-agent.md +++ b/content/amplify/nginx-amplify-agent/install/updating-amplify-agent.md @@ -6,9 +6,9 @@ toc: true nd-docs: DOCS-970 --- -{{< important >}} +{{< call-out "important" >}} It is *highly* recommended that you periodically check for updates and install the latest stable version of F5 NGINX Amplify Agent. -{{< /important >}} +{{< /call-out >}} 1. Updating NGINX Amplify Agent On Ubuntu/Debian diff --git a/content/amplify/user-interface/alerts.md b/content/amplify/user-interface/alerts.md index 490cc6eb7..91758e6a7 100644 --- a/content/amplify/user-interface/alerts.md +++ b/content/amplify/user-interface/alerts.md @@ -23,6 +23,6 @@ There's one special rule which is the about **amplify.agent.status** metric. Thi You shouldn't see consecutive notifications about the same alert repeatedly. Instead, there will be digest information sent out *every 60 minutes*, describing which alerts were generated and which ones were cleared. -{{< note >}} Gauges are *averaged* over the interval configured in the rule. Counters are *summed up*. Currently, this is not user configurable, and these are the only reduce functions available for configuring metric thresholds. {{< /note >}} +{{< call-out "note" >}} Gauges are *averaged* over the interval configured in the rule. Counters are *summed up*. Currently, this is not user configurable, and these are the only reduce functions available for configuring metric thresholds. {{< /call-out >}} -{{< note >}} Emails are sent using [AWS SES](https://aws.amazon.com/ses/). Make sure your mail relay accepts their traffic. Also, make sure to verify the specified email and check the verification status in the Account menu. {{< /note >}} +{{< call-out "note" >}} Emails are sent using [AWS SES](https://aws.amazon.com/ses/). Make sure your mail relay accepts their traffic. Also, make sure to verify the specified email and check the verification status in the Account menu. {{< /call-out >}} diff --git a/content/amplify/user-interface/analyzer.md b/content/amplify/user-interface/analyzer.md index 40ce6d0b5..d01d4d6f5 100644 --- a/content/amplify/user-interface/analyzer.md +++ b/content/amplify/user-interface/analyzer.md @@ -46,6 +46,6 @@ Static analysis will only include information about specific issues with the NGI In the future, the **Analyzer** page will also include *dynamic analysis*, effectively linking the observed NGINX behavior to its configuration — for example, when it makes sense to increase or decrease certain parameters like [proxy_buffers](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers), etc. -{{< note >}} Config analysis is *on* by default. If you don't want your NGINX configuration to be checked, unset the corresponding setting in either Global, or Local (per-system) settings. See [**Settings**]({{< ref "/amplify/user-interface/account-settings" >}}). {{< /note >}} +{{< call-out "note" >}} Config analysis is *on* by default. If you don't want your NGINX configuration to be checked, unset the corresponding setting in either Global, or Local (per-system) settings. See [**Settings**]({{< ref "/amplify/user-interface/account-settings" >}}). {{< /call-out >}} {{< img src="amplify/amplify-analyzer-settings.png" alt="Analyzer Settings" >}} \ No newline at end of file diff --git a/content/amplify/user-interface/dashboards.md b/content/amplify/user-interface/dashboards.md index 24dd0814d..5ee9ad389 100644 --- a/content/amplify/user-interface/dashboards.md +++ b/content/amplify/user-interface/dashboards.md @@ -38,7 +38,7 @@ To define a graph, perform these steps: 5. Last but not least, the “filter” functionality is also available for NGINX metrics collected from the log files. If you select "Add metric filter", you can add multiple criteria to define specific "metric dimensions". In the example above, we are matching the NGINX upstream response time against the **/api/feed/reports** URI. You can also build other filters, for example, displaying metric **nginx.http.status.2xx** for the responses with the status code 201. 6. Select "Save" to add the graph to the dashboard. You can also edit the graph, move it around, resize it, stack the graphs on top of each other, etc. -{{< note >}} When using filters, all the "metric dimensions" aren't stored in the F5 NGINX Amplify backend by default. A particular filter starts to slice the metric according to the specification only after the graph is created. Hence, it can be a while before the "filtered" metric is displayed on the graph — the end result depends on how quickly the log files are being populated with the new entries, but typically you should see the first data points in under 5 minutes. {{< /note >}} +{{< call-out "note" >}} When using filters, all the "metric dimensions" aren't stored in the F5 NGINX Amplify backend by default. A particular filter starts to slice the metric according to the specification only after the graph is created. Hence, it can be a while before the "filtered" metric is displayed on the graph — the end result depends on how quickly the log files are being populated with the new entries, but typically you should see the first data points in under 5 minutes. {{< /call-out >}} Because NGINX Amplify is **not** a SaaS log analyzer, the additional slicing for "metric dimensions" is implemented inside NGINX Amplify Agent. NGINX Amplify Agent can parse the NGINX access logs on-the-fly and extract all the necessary metrics **without** sending the raw log entries elsewhere. Moreover, NGINX Amplify Agent understands custom log formats automatically, and will start looking for various newly defined "metric dimensions" following a particular [log_format](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) specification. diff --git a/content/amplify/user-interface/inventory.md b/content/amplify/user-interface/inventory.md index dc7e4d198..f77c83c71 100644 --- a/content/amplify/user-interface/inventory.md +++ b/content/amplify/user-interface/inventory.md @@ -16,4 +16,4 @@ In the rightmost column of the **Inventory**, you will find the settings and the You can apply sorting, search, and filters to the **Inventory** to quickly find the system in question. You can search and filter by hostname, IP address, architecture, etc. You can use regular expressions with the search function. -{{< note >}} When removing an object from monitoring, keep in mind that you also need to stop or uninstall NGINX Amplify Agent on the systems being removed; otherwise, the objects will reappear in the User Interface. Be sure to delete any system-specific alert rules too.{{< /note >}} \ No newline at end of file +{{< call-out "note" >}} When removing an object from monitoring, keep in mind that you also need to stop or uninstall NGINX Amplify Agent on the systems being removed; otherwise, the objects will reappear in the User Interface. Be sure to delete any system-specific alert rules too.{{< /call-out >}} \ No newline at end of file diff --git a/content/amplify/user-interface/overview.md b/content/amplify/user-interface/overview.md index 02437219d..3ac91eef5 100644 --- a/content/amplify/user-interface/overview.md +++ b/content/amplify/user-interface/overview.md @@ -18,7 +18,7 @@ The cumulative [metrics]({{< ref "/amplify/metrics-metadata" >}}) displayed on t * Traffic — sum of **system.net.bytes_sent** rate * CPU Usage — average of **system.cpu.user** -{{< note >}} By default the metrics above are calculated for all monitored hosts. You can configure specific tags in the **Overview** settings popup to display the metrics for a set of hosts (e.g. only the "production environment"). {{< /note >}} +{{< call-out "note" >}} By default the metrics above are calculated for all monitored hosts. You can configure specific tags in the **Overview** settings popup to display the metrics for a set of hosts (e.g. only the "production environment"). {{< /call-out >}} You may see zero numbers if some metrics are not being gathered, for example, if the request time (P95) is 0.000s, please check that you have correctly configured NGINX log for [additional metric]() collection. diff --git a/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md b/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md index a1d53cf56..f1e211f4b 100644 --- a/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md +++ b/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md @@ -23,9 +23,9 @@ NGINX Controller automatically takes a snapshot of the embedded config database These automated config backups do not include backups of metrics data, which must be backed up separately; refer to [Backup & Restore the Metrics Database]({{< ref "/controller/admin-guides/backup-restore/backup-restore-metrics-db.md" >}}) for those instructions. -{{< tip >}} +{{< call-out "tip" >}} As a best practice, we recommend that you make scheduled backups of the entire config DB volume and keep the backups off-site for safekeeping. -{{< /tip >}} +{{< /call-out >}}   @@ -35,7 +35,7 @@ As a best practice, we recommend that you make scheduled backups of the entire c This section explains how to restore the embedded config database from the latest backup file or a specific, timestamped file. -{{< important >}}If you restore the config database on top of a new installation of NGINX Controller, make sure to follow the steps to [restore your NGINX config and encryption keys]({{< ref "/controller/admin-guides/backup-restore/backup-restore-cluster-config.md" >}}) afterward. {{< /important >}} +{{< call-out "important" >}}If you restore the config database on top of a new installation of NGINX Controller, make sure to follow the steps to [restore your NGINX config and encryption keys]({{< ref "/controller/admin-guides/backup-restore/backup-restore-cluster-config.md" >}}) afterward. {{< /call-out >}} - To restore the embedded NGINX Controller config database **from the latest automated backup**, run the following command: diff --git a/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md b/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md index bc2adbeeb..8ff44f638 100644 --- a/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md +++ b/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md @@ -33,9 +33,9 @@ To backup and restore the external config database, you'll need the following: export PGPASSWORD= ``` - {{< note >}} + {{< call-out "note" >}} If you've configured PostgreSQL to use SSL, ensure that you've placed your certs in `~/.postgresql`. For more information, see [Client Certificates](https://www.postgresql.org/docs/9.5/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT) in the PostgreSQL documentation. - {{< /note >}} + {{< /call-out >}}   @@ -75,7 +75,7 @@ Take the following steps to back up the external NGINX Controller config databas ## Restore External Config Database -{{< important >}}If you restore the config database on top of a new installation of NGINX Controller, make sure to follow the steps to [restore your NGINX config and encryption keys]({{< ref "/controller/admin-guides/backup-restore/backup-restore-cluster-config.md" >}}) afterward. {{< /important >}} +{{< call-out "important" >}}If you restore the config database on top of a new installation of NGINX Controller, make sure to follow the steps to [restore your NGINX config and encryption keys]({{< ref "/controller/admin-guides/backup-restore/backup-restore-cluster-config.md" >}}) afterward. {{< /call-out >}} To restore the external NGINX Controller config database: diff --git a/content/controller/admin-guides/config-agent/about-controller-agent.md b/content/controller/admin-guides/config-agent/about-controller-agent.md index 2ab44950d..e5efa82c0 100644 --- a/content/controller/admin-guides/config-agent/about-controller-agent.md +++ b/content/controller/admin-guides/config-agent/about-controller-agent.md @@ -29,7 +29,7 @@ The NGINX Controller Agent attempts to detect and monitor all unique NGINX proce - A unique control process and its workers, started with an **absolute path** to a distinct NGINX binary. - A control process running with a default config path, or with a custom path set in the command-line parameters. -{{< caution >}}You should not make manual changes to the `nginx.conf` file on NGINX Plus instances that are managed by NGINX Controller. Manually updating the `nginx.conf` file on managed instances may adversely affect system performance. In most cases, NGINX Controller will revert or overwrite manual updates made to `nginx.conf`.{{< /caution >}} +{{< call-out "caution" >}}You should not make manual changes to the `nginx.conf` file on NGINX Plus instances that are managed by NGINX Controller. Manually updating the `nginx.conf` file on managed instances may adversely affect system performance. In most cases, NGINX Controller will revert or overwrite manual updates made to `nginx.conf`.{{< /call-out >}}
@@ -37,7 +37,7 @@ The NGINX Controller Agent attempts to detect and monitor all unique NGINX proce NGINX Controller, the NGINX Controller Agent, and the NGINX Controller Application Security Add-on support the following distributions and architectures. -{{< see-also >}}Refer to the [NGINX Plus Technical Specifications](https://docs.nginx.com/nginx/technical-specs/) guide for the distributions that NGINX Plus supports.{{< /see-also >}} +{{< call-out "note" >}}Refer to the [NGINX Plus Technical Specifications](https://docs.nginx.com/nginx/technical-specs/) guide for the distributions that NGINX Plus supports.{{< /call-out>}} {{< bootstrap-table "table table-striped table-bordered" >}} @@ -65,9 +65,9 @@ NGINX Controller, the NGINX Controller Agent, and the NGINX Controller Applicati NGINX Controller v3.1 and later use an Analytics, Visibility, and Reporting daemon (AVRD) to aggregate and report app-centric metrics, which you can use to track and check the health of your apps. To learn more about these metrics, see the [NGINX Metrics Catalog]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) topic. -{{< see-also >}} +{{< call-out "note" >}} See the [NGINX Controller Technical Specifications]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md" >}}) for the complete list of system requirements for NGINX Controller and the NGINX Controller Agent. -{{< /see-also >}} +{{< /call-out>}} ## Supported Python Versions diff --git a/content/controller/admin-guides/config-agent/configure-metrics-collection.md b/content/controller/admin-guides/config-agent/configure-metrics-collection.md index 6fadc382c..c88443035 100644 --- a/content/controller/admin-guides/config-agent/configure-metrics-collection.md +++ b/content/controller/admin-guides/config-agent/configure-metrics-collection.md @@ -40,9 +40,9 @@ NGINX Controller uses the `/api` location on the NGINX Plus instance to collect When you push a configuration to an NGINX Plus instance, NGINX Controller automatically enables the `/api` location for that instance. -{{< note >}} +{{< call-out "note" >}} The `/api` location settings that NGINX Controller creates will override any settings that you have previously defined. -{{< /note >}} +{{< /call-out >}} If you use NGINX Controller solely to monitor your NGINX Plus instances, you may need to enable the `/api` location on your instances manually. Refer to the [Configuring the API](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#configuring-the-api) section of the NGINX Plus Admin Guide for instructions. @@ -63,12 +63,12 @@ The Agent will try to detect the [log format](https://nginx.org/en/docs/http/ngx Some metrics included in the [NGINX Metrics reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) are not available unless the corresponding variables are included in a custom [access.log](https://nginx.org/en/docs/http/ngx_http_log_module.html) format in the NGINX config. -{{< see-also >}} +{{< call-out "note" >}} - Read [Configuring Logging](https://docs.nginx.com/nginx/admin-guide/monitoring/logging/#setting-up-the-access-log) in the NGINX Admin Guide. - View the complete list of [NGINX log variables](https://nginx.org/en/docs/varindex.html). -{{< /see-also >}}. +{{< /call-out>}}. Take the steps in this section to enable the NGINX Controller Agent to collect metrics from custom `access.log` variables. @@ -93,9 +93,9 @@ Take the steps in this section to enable the NGINX Controller Agent to collect m access_log /var/log/nginx/access.log main_ext; ``` - {{< note >}} + {{< call-out "note" >}} By default, the Controller Agent processes all access logs that it finds in your log directory. If you define a new log file with the extended log format that contains entries that are already being logged to another access log, your metrics might be counted twice. Refer to the [Agent configuration]({{< ref "/controller/admin-guides/config-agent/configure-the-agent.md" >}}) guide to learn how to exclude specific log files from processing. - {{< /note >}} + {{< /call-out >}} 4. Set the [error.log](https://nginx.org/en/docs/ngx_core_module.html#error_log) log level to `warn`. @@ -135,9 +135,9 @@ Take the steps below to enable metrics collection from Syslog: For more information, see [Controlling NGINX](https://nginx.org/en/docs/control.html). -{{< note >}} +{{< call-out "note" >}} To send the NGINX logs to both the existing logging facility and the NGINX Controller Agent, include a separate [access.log](https://nginx.org/en/docs/http/ngx_http_log_module.html) directive for each destination. -{{< /note >}} +{{< /call-out >}} ## What's Next diff --git a/content/controller/admin-guides/config-agent/configure-the-agent.md b/content/controller/admin-guides/config-agent/configure-the-agent.md index 468755759..9963d0e80 100644 --- a/content/controller/admin-guides/config-agent/configure-the-agent.md +++ b/content/controller/admin-guides/config-agent/configure-the-agent.md @@ -32,9 +32,9 @@ NGINX Controller uses the `/api` location on the NGINX Plus instance to collect When you push a configuration to an NGINX Plus instance, NGINX Controller automatically enables the `/api` location for that instance. -{{< note >}} +{{< call-out "note" >}} The `/api` location settings that NGINX Controller creates will override any settings that you have previously defined. -{{< /note >}} +{{< /call-out >}} If you use NGINX Controller solely to monitor your NGINX Plus instances, you may need to enable the `/api` location on your instances manually. Refer to the [Configuring the API](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#configuring-the-api) section of the NGINX Plus Admin Guide for instructions. @@ -71,13 +71,13 @@ The hostname should be real. The NGINX Controller Agent won't start unless a val - localhost6.localdomain6 - ip6-localhost -{{< note >}} +{{< call-out "note" >}} You can use the above method to replace the system's hostname with an arbitrary alias. Keep in mind that if you redefine the hostname for a live object, the existing object will be marked as failed in the NGINX Controller user interface. Redefining the hostname in the NGINX Controller Agent's configuration creates a new UUID and a new system for monitoring. Alternatively, you can define an alias for the host in the NGINX Controller user interface. Go to the **Graphs** page, select the system that you want to update, and click the gear icon. -{{< /note >}} +{{< /call-out >}} ## Preserving the UUID across OS upgrades @@ -97,7 +97,7 @@ After restarting the Controller Agent -- `service controller-agent restart` -- t The NGINX Controller Agent detects the NGINX configuration file automatically. You shouldn't need to point the NGINX Controller Agent to the `nginx.conf` file explicitly. -{{< caution >}}You should not make manual changes to the `nginx.conf` file on NGINX Plus instances that are managed by NGINX Controller. Manually updating the `nginx.conf` file on managed instances may adversely affect system performance. In most cases, NGINX Controller will revert or overwrite manual updates made to `nginx.conf`.{{< /caution >}} +{{< call-out "caution" >}}You should not make manual changes to the `nginx.conf` file on NGINX Plus instances that are managed by NGINX Controller. Manually updating the `nginx.conf` file on managed instances may adversely affect system performance. In most cases, NGINX Controller will revert or overwrite manual updates made to `nginx.conf`.{{< /call-out >}} If, for some reason, the NGINX Controller Agent cannot find the NGINX configuration, you can use the following option in `/etc/controller-agent/agent.conf` to point to the configuration file: @@ -106,7 +106,7 @@ If, for some reason, the NGINX Controller Agent cannot find the NGINX configurat configfile = /etc/nginx/nginx.conf ``` -{{< note >}} We recommend using this option only as a workaround if needed. If you do need to add the path to the NGINX config file, we ask that you [contact NGINX Support]({{< ref "/controller/support/contact-support.md" >}}) so they can help troubleshoot the issue.{{< /note >}} +{{< call-out "note" >}} We recommend using this option only as a workaround if needed. If you do need to add the path to the NGINX config file, we ask that you [contact NGINX Support]({{< ref "/controller/support/contact-support.md" >}}) so they can help troubleshoot the issue.{{< /call-out >}} ## Set Host Tags @@ -117,15 +117,15 @@ You can define arbitrary tags on a "per-host" basis. Tags can be configured in t tags = foo bar foo:bar ``` -{{< note >}} Any changes to instance Tags made in the Controller user interface will overwrite the values stored in `agent.conf`.{{< /note >}} +{{< call-out "note" >}} Any changes to instance Tags made in the Controller user interface will overwrite the values stored in `agent.conf`.{{< /call-out >}} You can use tags to build custom graphs, configure alerts, and filter the systems on the **Graphs** page in the Controller user interface. ## Logging to Syslog -{{< see-also >}} +{{< call-out "note" >}} [NGINX Admin Guide - Logging to Syslog](https://docs.nginx.com/nginx/admin-guide/monitoring/logging/#logging-to-syslog) -{{< /see-also >}} +{{< /call-out>}} The NGINX Controller Agent can collect NGINX log files using `syslog`. This could be useful when you don't keep the NGINX logs on disk, or when monitoring a container environment such as Docker with NGINX Controller. @@ -147,9 +147,9 @@ To configure the NGINX Controller Agent to send logs to `syslog`: # service controller-agent restart ``` - {{< important >}} + {{< call-out "important" >}} Make sure you [add the `syslog` settings to your NGINX configuration file]({{< ref "/controller/admin-guides/config-agent/configure-metrics-collection.md#collect-metrics-from-syslog" >}}) as well. - {{< /important >}} + {{< /call-out >}} ## Exclude Certain NGINX Log Files @@ -182,9 +182,9 @@ Upon installation, the NGINX Controller Agent's log rotation schedule is added t The normal level of logging for the NGINX Controller Agent is `INFO`. If you ever need to debug the NGINX Controller Agent, change the level to `DEBUG` as described below. -{{< caution >}} +{{< call-out "caution" >}} The size of the NGINX Controller Agent's log file can proliferate in `DEBUG` mode. You should use `DEBUG` mode only for troubleshooting purposes. -{{< /caution >}} +{{< /call-out >}} ### Change the Agent Log Level diff --git a/content/controller/admin-guides/install/get-n-plus-cert-and-key.md b/content/controller/admin-guides/install/get-n-plus-cert-and-key.md index 55a141570..9b980d52f 100644 --- a/content/controller/admin-guides/install/get-n-plus-cert-and-key.md +++ b/content/controller/admin-guides/install/get-n-plus-cert-and-key.md @@ -19,9 +19,9 @@ This topic explains how to use the [F5 NGINX Controller REST API](https://docs.n The NGINX Controller API uses session cookies to authenticate requests. The session cookie is returned in response to a `GET /api/v1/platform/login` request. See the Login endpoint in the [NGINX Controller API Reference]({{< ref "/controller/api/_index.md" >}}) documentation for information about session cookie timeouts and invalidation. -{{< tip >}} +{{< call-out "tip" >}} You can send a GET request to the login endpoint to find the status of the session token. -{{< /tip >}} +{{< /call-out >}} For example: @@ -60,9 +60,9 @@ For example: curl -b cookie.txt -c cookie.txt -X GET --url 'https://192.0.2.0/api/v1/platform/licenses/nginx-plus-licenses/controller-provided' --output nginx-plus-certs.gz ``` -{{< note >}} +{{< call-out "note" >}} If you are using a self-signed certificate you will need to add `-k` (allow insecure connections) to your curl command to be able to download your NGINX Plus certificate and key bundle. -{{< /note >}} +{{< /call-out >}} Once you have downloaded your certificate and key bundle you will need to expand the `.gz` file to get your certificate and key pair. diff --git a/content/controller/admin-guides/install/install-agent-non-root.md b/content/controller/admin-guides/install/install-agent-non-root.md index 7d4dd31bf..8c58211cd 100644 --- a/content/controller/admin-guides/install/install-agent-non-root.md +++ b/content/controller/admin-guides/install/install-agent-non-root.md @@ -36,9 +36,9 @@ Take the following steps to add an instance to NGINX Controller: 1. Add a name for the instance. If you don't provide a name, the hostname of the instance is used by default. 1. To add the instance to an existing Location, select a Location from the list. Or to create a Location, select **Create New**. - {{< important >}} + {{< call-out "important" >}} Once set, the Location for an instance cannot be changed. If you need to change or remove the Location for an instance, you must [remove the instance from NGINX Controller]({{< ref "/controller/infrastructure/instances/manage-instances.md#delete-an-instance" >}}), and then add it back. - {{< /important >}} + {{< /call-out >}} 1. (Optional) By default, registration of NGINX Plus instances is performed over a secure connection. To use self-signed certificates with the Controller Agent, select **Allow insecure server connections to NGINX Controller using TLS**. For security purposes, we recommend that you secure the Controller Agent with signed certificates when possible. 1. Use SSH to connect and log in to the NGINX instance that you want to connect to NGINX Controller. @@ -51,7 +51,7 @@ Once set, the Location for an instance cannot be changed. If you need to change curl -sS -L https:///install/controller-agent > install.sh && API_KEY='' CONTROLLER_USER='' CONTROLLER_GROUP='' -i -l ``` - {{< note >}} + {{< call-out "note" >}} Make sure you enter the commands to download and run the `install.sh` script on the NGINX Plus system, and not on the NGINX Controller. @@ -61,7 +61,7 @@ If `CONTROLLER_USER` is not set, during the installation you will see the messag Running agent as non-root changes the nap-syslog port to `5114` in both containerized and non-containerized instances. - {{< /note >}} + {{< /call-out >}}   diff --git a/content/controller/admin-guides/install/install-nginx-controller-agent.md b/content/controller/admin-guides/install/install-nginx-controller-agent.md index 2ee592106..65aa4ab54 100644 --- a/content/controller/admin-guides/install/install-nginx-controller-agent.md +++ b/content/controller/admin-guides/install/install-nginx-controller-agent.md @@ -22,7 +22,7 @@ You can use the NGINX Controller Agent to monitor your systems with the NGINX Co ## Install the NGINX Controller Agent -{{< see-also >}} If you want to run the NGINX Controller Agent as a non-root user, follow the alternative instructions in the [Install NGINX Controller Agent for Non-root User]({{< ref "/controller/admin-guides/install/install-agent-non-root.md" >}}) guide instead of the steps provided in this section. {{< /see-also >}} +{{< call-out "note" >}} If you want to run the NGINX Controller Agent as a non-root user, follow the alternative instructions in the [Install NGINX Controller Agent for Non-root User]({{< ref "/controller/admin-guides/install/install-agent-non-root.md" >}}) guide instead of the steps provided in this section. {{< /call-out>}} Take the following steps to add an instance to NGINX Controller: @@ -35,25 +35,25 @@ Take the following steps to add an instance to NGINX Controller: 7. To add the instance to an existing [Instance Group]({{< ref "/controller/infrastructure/instances/manage-instances.md#instance-groups" >}}), select an Instance Group from the list. Or to create an Instance Group, select **Create New**. 8. To add the instance to an existing Location, select a Location from the list. Or to create a Location, select **Create New**. - {{< important >}} + {{< call-out "important" >}} Once set, the Location for an instance cannot be changed. If you need to change or remove the Location for an instance, you must [remove the instance from NGINX Controller]({{< ref "/controller/infrastructure/instances/manage-instances.md#delete-an-instance" >}}), and then add it back. - {{< /important >}} + {{< /call-out >}} - {{< important >}} + {{< call-out "important" >}} Instances and the instance groups they belong to should specify the same location; however, this requirement is not currently enforced. If different locations are specified, the instance group's location takes precedence. This is important to remember when [assigning locations to workload groups]({{< ref "/controller/app-delivery/manage-apps.md#workload-groups">}}). - {{< /important >}} + {{< /call-out >}} 9. (Optional) By default, registration of NGINX Plus instances is performed over a secure connection. To use self-signed certificates with the Controller Agent, select **Allow insecure server connections to NGINX Controller using TLS**. For security purposes, we recommend that you secure the Controller Agent with signed certificates when possible. 10. Use SSH to connect and log in to the NGINX instance that you want to connect to NGINX Controller. 11. Run the `curl` or `wget` command that's shown in the **Installation Instructions** section on the NGINX instance to download and install the Controller Agent package. When specified, the `-i` and `-l` options for the `install.sh` script refer to the instance name and Location, respectively. - {{< note >}} + {{< call-out "note" >}} Make sure you enter the commands to download and run the `install.sh` script on the NGINX Plus system, and not on the NGINX Controller. NGINX Controller 3.6 and earlier require Python 2.6 or 2.7. You'll be prompted to install Python if it's not installed already. Python is not required for NGINX Controller v3.7 and later. - {{< /note >}} + {{< /call-out >}} After a few minutes, the NGINX instance will appear on the **Instances** overview page. @@ -70,11 +70,11 @@ To update the NGINX Controller Agent, take the following steps: 1. On the **Instances** overview page, select **Create**. 1. Follow the instructions in the **Install Instructions** pane to connect to the NGINX instance and install the updated Controller Agent package. - {{< note >}} + {{< call-out "note" >}} NGINX Controller 3.6 and earlier require Python 2.6 or 2.7. You'll be prompted to install Python if it's not installed already. Python is not required for NGINX Controller 3.7 and later. - {{< /note >}} + {{< /call-out >}} ## Uninstall the Analytics, Visibility, and Reporting Daemon (AVRD) @@ -100,7 +100,7 @@ To uninstall AVRD and the supporting modules, run the following command on each Take the following steps to uninstall the Controller Agent and delete an instance. -{{< important >}}Be sure to uninstall the Controller Agent first, before you delete an instance. If you don't uninstall the Controller Agent first, the instance may reappear in NGINX Controller after it has been deleted.{{< /important >}} +{{< call-out "important" >}}Be sure to uninstall the Controller Agent first, before you delete an instance. If you don't uninstall the Controller Agent first, the instance may reappear in NGINX Controller after it has been deleted.{{< /call-out >}} 1. On your NGINX Plus instance, stop the Controller Agent service: @@ -160,7 +160,7 @@ Take the following steps to uninstall the Controller Agent and delete an instanc 1. Delete alerts: - {{< note >}}When you delete an instance, any related alerts for that instance are not deleted automatically. You can delete the alerts manually, however.{{< /note >}} + {{< call-out "note" >}}When you delete an instance, any related alerts for that instance are not deleted automatically. You can delete the alerts manually, however.{{< /call-out >}} 1. Open the NGINX Controller user interface and log in. 2. On the Analytics menu, select **Alerts > Alert Rules**. diff --git a/content/controller/admin-guides/install/install-nginx-controller.md b/content/controller/admin-guides/install/install-nginx-controller.md index 0607d2240..63ad87cb7 100644 --- a/content/controller/admin-guides/install/install-nginx-controller.md +++ b/content/controller/admin-guides/install/install-nginx-controller.md @@ -37,9 +37,9 @@ NGINX Controller uses a number of open source software packages in the product. Before installing NGINX Controller, review the following prerequisites. -{{< important >}} +{{< call-out "important" >}} NGINX Controller should be deployed on a secure, internal network only. We strongly recommend against exposing the NGINX Controller API to the internet. -{{< /important >}} +{{< /call-out >}} Things you'll need before installing NGINX Controller: @@ -93,14 +93,14 @@ To install all of the NGINX Controller prerequisites for your system at the same ./helper.sh prereqs ``` -{{< note >}} +{{< call-out "note" >}} After you've installed NGINX Controller, you can install any of the prerequisites by running the following command: ```bash /opt/nginx-controller/helper.sh prereqs [base|docker|nfs] ``` -{{< /note >}} +{{< /call-out >}}   @@ -150,10 +150,10 @@ If you are using Ubuntu-20.04 and want to install Docker on your own, choose the - [Docker Community Edition (CE)](https://docs.docker.com/engine/install/ubuntu/) 19.03 - [Containerd.io](https://containerd.io/) 1.2.13 -{{< see-also >}} -For instructions on installing Docker in offline scenarios on CentOS/RHEL 7, refer to the AskF5 [K84431427](https://support.f5.com/csp/article/K84431427) knowledge base article.{{< /see-also >}} +{{< call-out "note" >}} +For instructions on installing Docker in offline scenarios on CentOS/RHEL 7, refer to the AskF5 [K84431427](https://support.f5.com/csp/article/K84431427) knowledge base article.{{< /call-out>}} -{{< important >}} You need to enable Docker log rotation to ensure that the logs don't consume all the free disk space on the server. For instructions on how to enable Docker log rotation, see the Docker guides [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/) and [JSON File logging driver](https://docs.docker.com/config/containers/logging/json-file/).{{< /important >}}  +{{< call-out "important" >}} You need to enable Docker log rotation to ensure that the logs don't consume all the free disk space on the server. For instructions on how to enable Docker log rotation, see the Docker guides [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/) and [JSON File logging driver](https://docs.docker.com/config/containers/logging/json-file/).{{< /call-out >}}  #### Red Hat Enterprise Linux @@ -234,9 +234,9 @@ Refer to the AskF5 KB article [K49481224](https://support.f5.com/csp/article/K49 Install NGINX Controller on a dedicated node that **does not** already have Kubernetes configured. NGINX Controller does not support pre-configured Kubernetes implementations at this time. The installer for NGINX Controller will install and configure Kubernetes for you. -{{< important >}}Before installing NGINX Controller, you must **disable swap on the host**; this is required by Kubernetes in order for the kubelet to work properly. Refer to your Linux distribution documentation for specific instructions for disabling swap for your system. For more information about this requirement, see the AskF5 knowledge base article [K82655201](https://support.f5.com/csp/article/K82655201) and the [kubeadm installation guide](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) in the Kubernetes documentation.{{< /important >}} +{{< call-out "important" >}}Before installing NGINX Controller, you must **disable swap on the host**; this is required by Kubernetes in order for the kubelet to work properly. Refer to your Linux distribution documentation for specific instructions for disabling swap for your system. For more information about this requirement, see the AskF5 knowledge base article [K82655201](https://support.f5.com/csp/article/K82655201) and the [kubeadm installation guide](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) in the Kubernetes documentation.{{< /call-out >}} -{{< caution >}}**For RHEL 8 deployments**, complete the additional prerequisite steps in the [Installing NGINX on RHEL 8]({{< ref "/controller/admin-guides/install/install-nginx-controller-rhel-8.md" >}}) guide before installing NGINX Controller. RHEL 8 support is a **beta** feature.{{< /caution >}} +{{< call-out "caution" >}}**For RHEL 8 deployments**, complete the additional prerequisite steps in the [Installing NGINX on RHEL 8]({{< ref "/controller/admin-guides/install/install-nginx-controller-rhel-8.md" >}}) guide before installing NGINX Controller. RHEL 8 support is a **beta** feature.{{< /call-out >}} To install NGINX Controller, take the following steps: @@ -254,17 +254,17 @@ To install NGINX Controller, take the following steps: ./install.sh ``` - {{< important >}}Installing NGINX Controller as `root` is **not supported** on multi-node clusters. Instead, create a user with `sudo` permission for installing and performing all operations with NGINX Controller. Further, NGINX Controller scripts should also run with this dedicated user; scripts shouldn't be run as `sudo`, `sudo su`, or as the `root` user directly.{{< /important >}} + {{< call-out "important" >}}Installing NGINX Controller as `root` is **not supported** on multi-node clusters. Instead, create a user with `sudo` permission for installing and performing all operations with NGINX Controller. Further, NGINX Controller scripts should also run with this dedicated user; scripts shouldn't be run as `sudo`, `sudo su`, or as the `root` user directly.{{< /call-out >}} - {{< note >}}If an HTTPS proxy is configured for the whole system, you should disable the proxy for the IP address and hostname of the host that you're running the NGINX Controller install script on. - For example, run the command `export NO_PROXY=,`. {{< /note >}} + {{< call-out "note" >}}If an HTTPS proxy is configured for the whole system, you should disable the proxy for the IP address and hostname of the host that you're running the NGINX Controller install script on. + For example, run the command `export NO_PROXY=,`. {{< /call-out >}} The installation script walks through a series of steps and asks for the following input: - **Config database configuration**. Specify whether to use an embedded, self-hosted PostgreSQL database for the config database, or if you want to provide your own external PostgreSQL database. If you choose to provide your own database, make sure you've reviewed the [PostgreSQL prerequisites](#postgresql-optional). - **Config database volume type**: Specify the type of volume to use to store the config database: local, NFS, or AWS. We recommend choosing `local` only for demo and trial purposes. - {{< see-also >}}Refer to the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#local-or-external-storage" >}}) for more information about the volume options and requirements.{{< /see-also >}} + {{< call-out "note" >}}Refer to the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#local-or-external-storage" >}}) for more information about the volume options and requirements.{{< /call-out>}} - **Analytics database volume type**: Specify the type of volume to use to store the analytics database: local, NFS, or AWS. We recommend choosing `local` for demo and trial purposes. - **EULA**: Read the end-user license agreement. Type either `y` to accept or `n` to exit. @@ -280,10 +280,10 @@ To install NGINX Controller, take the following steps: - **Email address**: The contact email address for the initial admin user. - **Password**: The initial admin's password. Passwords must be 6-64 characters long and must include letters and digits. - **FQDN**: Fully qualified domain name (FQDN) -- a resolvable domain name for the NGINX Controller server. The FQDN is used by Controller Agents when connecting to NGINX Controller. - {{< note >}}We recommend setting the FQDN to a internal address when possible, to avoid exposing the traffic between the Agent and NGINX Controller. This also reduces the external traffic in cloud environments. {{< /note >}} + {{< call-out "note" >}}We recommend setting the FQDN to a internal address when possible, to avoid exposing the traffic between the Agent and NGINX Controller. This also reduces the external traffic in cloud environments. {{< /call-out >}} - **SSL/TLS certificates**: Type `y` to generate and use self-signed certs for running NGINX Controller over HTTPS, or type `n` to provide your own certs. - {{< important >}}If you provide your own SSL/TLS certificates, you'll need a complete certificate chain file, with the intermediate CA cert appended to the server cert; the server certificate must appear **before** the chained certificates in the combined file. If the certificate contains a wildcard Common Name (CN=*.example.com) it must also contain a Subject Alternate Name (SAN=nginx-controller.example.com). {{< /important >}} + {{< call-out "important" >}}If you provide your own SSL/TLS certificates, you'll need a complete certificate chain file, with the intermediate CA cert appended to the server cert; the server certificate must appear **before** the chained certificates in the combined file. If the certificate contains a wildcard Common Name (CN=*.example.com) it must also contain a Subject Alternate Name (SAN=nginx-controller.example.com). {{< /call-out >}} 1. Log in to the NGINX Controller browser interface by navigating to the DNS, FQDN, or IP address of the NGINX Controller host, for example, `https:///login`. Use the admin email address and password that you provided during the installation process. @@ -306,9 +306,9 @@ To add a license to NGINX Controller, take the following steps: 1. Select **Save license**. -{{< see-also >}} +{{< call-out "note" >}} To add a license using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a PUT request to the `/platform/license` endpoint. Provide your CAT or NGINX Controller license as a base64-encoded string in the JSON request body. -{{< /see-also >}} +{{< /call-out>}}   @@ -358,9 +358,9 @@ To update the NGINX Controller software, take the steps below. When complete, yo When updating NGINX Controller on a multi-node cluster, run the `update.sh` script on each node individually -- the order in which you update the nodes doesn't matter. -{{< warning >}} Do not update the nodes in a multi-node cluster in parallel. Doing so may result in race conditions for certain jobs, such as database migrations, and may cause the cluster to become unavailable.{{< /warning >}} +{{< call-out "warning" >}} Do not update the nodes in a multi-node cluster in parallel. Doing so may result in race conditions for certain jobs, such as database migrations, and may cause the cluster to become unavailable.{{< /call-out >}} -{{< caution >}} +{{< call-out "caution" >}} We strongly recommend that you make a backup of the following information before proceeding, to avoid potential data and/or configuration loss: - [Back up the NGINX Controller databases]({{< ref "/controller/admin-guides/backup-restore" >}}). @@ -376,7 +376,7 @@ We strongly recommend that you make a backup of the following information before cp /etc/controller-agent/agent.conf ``` -{{< /caution >}} +{{< /call-out >}} 1. Download the installer package from the [MyF5 Customer Portal](https://my.f5.com/manage/s/downloads). @@ -401,13 +401,13 @@ We strongly recommend that you make a backup of the following information before ./update.sh ``` - {{< note >}}If you're upgrading from an older version of NGINX Controller and you installed Controller as root user, use `--allow-with-root` flag when running an update script. {{< /note >}} + {{< call-out "note" >}}If you're upgrading from an older version of NGINX Controller and you installed Controller as root user, use `--allow-with-root` flag when running an update script. {{< /call-out >}} 1. If you are logged in to NGINX Controller using a web browser, sign out and log in again. - To sign out, select your username in the upper right-hand corner, and then select "Sign Out". For optimal performance, also flush your browser cache. -{{< important >}} After you upgrade NGINX Controller, you also need to [update the NGINX Controller Agent]({{< ref "/controller/admin-guides/install/install-nginx-controller-agent" >}}) to the latest version. {{< /important >}} +{{< call-out "important" >}} After you upgrade NGINX Controller, you also need to [update the NGINX Controller Agent]({{< ref "/controller/admin-guides/install/install-nginx-controller-agent" >}}) to the latest version. {{< /call-out >}}   @@ -426,7 +426,7 @@ To uninstall NGINX Controller, run the uninstall script: --- ## Install NGINX Controller Agent -{{< see-also >}} If you want to run the NGINX Controller Agent as a non-root user, follow the alternative instructions in the [Install NGINX Controller Agent for Non-root User]({{< ref "/controller/admin-guides/install/install-agent-non-root.md" >}}) guide instead of the steps provided in this section. {{< /see-also >}} +{{< call-out "note" >}} If you want to run the NGINX Controller Agent as a non-root user, follow the alternative instructions in the [Install NGINX Controller Agent for Non-root User]({{< ref "/controller/admin-guides/install/install-agent-non-root.md" >}}) guide instead of the steps provided in this section. {{< /call-out>}} Install the Controller Agent on each NGINX Plus instance that you want to manage and monitor. @@ -441,25 +441,25 @@ Take the following steps to add an instance to NGINX Controller: 7. To add the instance to an existing [Instance Group]({{< ref "/controller/infrastructure/instances/manage-instances.md#instance-groups" >}}), select an Instance Group from the list. Or to create an Instance Group, select **Create New**. 8. To add the instance to an existing Location, select a Location from the list. Or to create a Location, select **Create New**. - {{< important >}} + {{< call-out "important" >}} Once set, the Location for an instance cannot be changed. If you need to change or remove the Location for an instance, you must [remove the instance from NGINX Controller]({{< ref "/controller/infrastructure/instances/manage-instances.md#delete-an-instance" >}}), and then add it back. - {{< /important >}} + {{< /call-out >}} - {{< important >}} + {{< call-out "important" >}} Instances and the instance groups they belong to should specify the same location; however, this requirement is not currently enforced. If different locations are specified, the instance group's location takes precedence. This is important to remember when [assigning locations to workload groups]({{< ref "/controller/app-delivery/manage-apps.md#workload-groups">}}). - {{< /important >}} + {{< /call-out >}} 9. (Optional) By default, registration of NGINX Plus instances is performed over a secure connection. To use self-signed certificates with the Controller Agent, select **Allow insecure server connections to NGINX Controller using TLS**. For security purposes, we recommend that you secure the Controller Agent with signed certificates when possible. 10. Use SSH to connect and log in to the NGINX instance that you want to connect to NGINX Controller. 11. Run the `curl` or `wget` command that's shown in the **Installation Instructions** section on the NGINX instance to download and install the Controller Agent package. When specified, the `-i` and `-l` options for the `install.sh` script refer to the instance name and Location, respectively. - {{< note >}} + {{< call-out "note" >}} Make sure you enter the commands to download and run the `install.sh` script on the NGINX Plus system, and not on the NGINX Controller. NGINX Controller 3.6 and earlier require Python 2.6 or 2.7. You'll be prompted to install Python if it's not installed already. Python is not required for NGINX Controller v3.7 and later. - {{< /note >}} + {{< /call-out >}} After a few minutes, the NGINX instance will appear on the **Instances** overview page. @@ -476,9 +476,9 @@ If NGINX Controller isn't working how you expect, see the knowledge base article You can create a support package for NGINX Controller that you can use to diagnose issues. -{{< note >}} +{{< call-out "note" >}} You will need to provide a support package if you open a ticket with NGINX Support via the [MyF5 Customer Portal](https://account.f5.com/myf5). -{{< /note >}}  +{{< /call-out >}}  ```bash /opt/nginx-controller/helper.sh supportpkg [-o|--output ] [-s|--skip-db-dump] [-t|--timeseries-dump ] diff --git a/content/controller/admin-guides/install/nginx-controller-tech-specs.md b/content/controller/admin-guides/install/nginx-controller-tech-specs.md index 39b8a7da6..de963dce1 100644 --- a/content/controller/admin-guides/install/nginx-controller-tech-specs.md +++ b/content/controller/admin-guides/install/nginx-controller-tech-specs.md @@ -16,7 +16,7 @@ This guide lists the technical recommendations for F5 NGINX Controller v3 and NG NGINX Controller, the NGINX Controller Agent, and the NGINX Controller Application Security Add-on support the following distributions and architectures. -{{< see-also >}}Refer to the [NGINX Plus Technical Specifications](https://docs.nginx.com/nginx/technical-specs/) guide for the distributions that NGINX Plus supports.{{< /see-also >}} +{{< call-out "note" >}}Refer to the [NGINX Plus Technical Specifications](https://docs.nginx.com/nginx/technical-specs/) guide for the distributions that NGINX Plus supports.{{< /call-out>}} {{< bootstrap-table "table table-striped table-bordered" >}} @@ -118,9 +118,9 @@ NGINX Controller supports the following [NGINX Plus](https://www.f5.com/products The App Security add-on for the NGINX Controller Application Delivery module is compatible with the versions of NGINX Plus and NGINX App Protect shown in the table below. New releases of NGINX Controller ADC support the last four versions of NGINX Plus at release time. -{{< see-also >}} +{{< call-out "note" >}} Refer to [Using NGINX App Protect with NGINX Controller]({{< ref "controller/admin-guides/install/install-for-controller.md" >}}) for installation instructions and additional information. -{{< /see-also >}} +{{< /call-out>}} {{< bootstrap-table "table table-striped table-bordered" >}} @@ -160,11 +160,11 @@ NGINX Controller works best with the newest and the last prior version of these - [Safari](https://support.apple.com/downloads/safari) - [Internet Explorer](https://support.microsoft.com/en-us/help/17621/internet-explorer-downloads) and [Microsoft Edge](https://www.microsoft.com/en-us/edge) -{{< important >}} +{{< call-out "important" >}} You may need to turn off any ad blockers while using the NGINX Controller user interface. In some cases, the NGINX Controller user interface may not display analytics or security events if an ad blocker is enabled. Refer to the AskF5 KB article [K48603454](https://support.f5.com/csp/article/K48903454) to learn more about this issue and how to resolve it. -{{< /important >}} +{{< /call-out >}}   @@ -204,9 +204,9 @@ When using local storage for the analytics and/or config database, we recommend - 100 IOPS - 155–255 GB free disk space. 255 GB of free space is recommended if NGINX Controller App Security is enabled. See the [Storage Requirements]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#storage-requirements" >}}) section for a categorized list of the storage requirements. -{{< tip >}} +{{< call-out "tip" >}} To conserve IO and/or disk space, you can use a separate disk for the local storage directory `/opt/nginx-controller/clickhouse_data`. -{{< /tip >}} +{{< /call-out >}}   @@ -224,9 +224,9 @@ To use NFS for external storage for the analytics and/or config database, consid ### AWS EBS -{{< important >}} +{{< call-out "important" >}} If you plan to run NGINX Controller on AWS EC2 instances, we recommend using NFS shares for the external volumes. Using EBS shares for multi-node clusters is not recommended because of the [EBS Availability Zone limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations); for example, the requirement to have EC2 instances and EBS volumes in the same Availability Zone. -{{< /important >}} +{{< /call-out >}} If you are installing NGINX Controller on [AWS EC2 instances](https://aws.amazon.com/ec2/getting-started/) and plan to use EBS volumes for the analytics and/or config database, consider the following: @@ -361,9 +361,9 @@ NGINX Controller supports the following versions of PostgreSQL: For a system monitoring **100 NGINX Plus instances**, we recommend at least **32 GB of database storage**. Database storage requirements can vary, depending on the number of NGINX Plus instances, components, published API specs, and the churn rate for configuration changes. For monitor-only implementations, the database storage needs are small; for API Management (APIM) and/or App Delivery Controller (ADC) implementations in production, the storage needs are greater. -{{< important >}} +{{< call-out "important" >}} If you use PostgreSQL 12, we recommend disabling [Just-in-Time (JIT)](https://www.postgresql.org/docs/12/jit.html) compilation to improve NGINX Controller's performance. To disable JIT, edit the `postgresql.conf` file and set `jit=off`. -{{< /important >}} +{{< /call-out >}}   diff --git a/content/controller/admin-guides/install/resilient-cluster-aws.md b/content/controller/admin-guides/install/resilient-cluster-aws.md index 240c0edc5..839cc8f2e 100644 --- a/content/controller/admin-guides/install/resilient-cluster-aws.md +++ b/content/controller/admin-guides/install/resilient-cluster-aws.md @@ -19,8 +19,8 @@ To be resilient, a cluster requires three working nodes. That's two nodes for a If a node fails in a resilient cluster, NGINX Controller automatically redirects traffic to the other working nodes. A multi-node cluster is operational with only two nodes; however, a two-node cluster isn't resilient to further failures. If one of the nodes in a multi-node cluster becomes degraded or fails, you must take action **as soon as possible** to recover or replace the failed node or risk losing resiliency. -{{< important >}}The failover time can take **up to 5 minutes** when a node fails. During this time, NGINX Controller may be unavailable while services are migrated and restarted. Resiliency will be restored once there are **three working nodes** in the cluster. -{{< /important >}} +{{< call-out "important" >}}The failover time can take **up to 5 minutes** when a node fails. During this time, NGINX Controller may be unavailable while services are migrated and restarted. Resiliency will be restored once there are **three working nodes** in the cluster. +{{< /call-out >}} The following table shows how many nodes are needed for a cluster to have a quorum and what the failure tolerance is: @@ -72,7 +72,7 @@ Before installing or configuring NGINX Controller as a multi-node cluster, revie ### Prerequisites -{{< important >}}If you plan to run NGINX Controller on AWS EC2 instances, we recommend you use NFS shares for the external volumes. Using EBS shares for multi-node clusters is not recommended because of the [EBS Availability Zone limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations).{{< /important >}} +{{< call-out "important" >}}If you plan to run NGINX Controller on AWS EC2 instances, we recommend you use NFS shares for the external volumes. Using EBS shares for multi-node clusters is not recommended because of the [EBS Availability Zone limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations).{{< /call-out >}} Things you'll need before installing NGINX Controller as a resilient cluster: @@ -92,7 +92,7 @@ Things you'll need before installing NGINX Controller as a resilient cluster: ## Configure IAM Roles -{{< important >}}If you plan to run NGINX Controller on AWS EC2 instances, we recommend using NFS shares for the external volumes. Using EBS shares for multi-node clusters is not recommended because of the [EBS Availability Zone limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations); for example, the requirement to have EC2 instances and EBS volumes in the same Availability Zone.{{< /important >}} +{{< call-out "important" >}}If you plan to run NGINX Controller on AWS EC2 instances, we recommend using NFS shares for the external volumes. Using EBS shares for multi-node clusters is not recommended because of the [EBS Availability Zone limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations); for example, the requirement to have EC2 instances and EBS volumes in the same Availability Zone.{{< /call-out >}} If you are installing NGINX Controller on [AWS EC2 instances](https://aws.amazon.com/ec2/getting-started/) and plan to use EBS volumes for the analytics and/or config database, you will need to add an IAM role like the one shown below. This will also allow the automatic creation of Elastic Load Balancers (ELBs). Additionally, for successful automatic creation of ELBs, all the EC2 instances that are or will be part of the cluster must be tagged with the following key-value pair: `kubernetes.io/cluster/NGINX-CONTROLLER : owned` @@ -192,9 +192,9 @@ If you are installing NGINX Controller on [AWS EC2 instances](https://aws.amazon Nodes are additional control-plane hosts that you can add to your cluster to improve uptime resilience. For a resilient cluster, you should have at least three nodes, of which **two nodes must always be operational**. -{{< important >}} +{{< call-out "important" >}} When adding a third node to the cluster for the first time, NGINX Controller may become momentarily unavailable while the cluster is being created. For this reason, we recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. -{{< /important >}} +{{< /call-out >}} Take the following steps to add a node to the cluster: @@ -226,9 +226,9 @@ Take the following steps to add a node to the cluster: 1. After the installation finishes, the node status in the web interface changes to `Configured`. 1. Repeat these steps for each node that you want to add to the cluster. -{{< see-also >}} +{{< call-out "note" >}} To add nodes to your cluster using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a POST request to the `/platform/nodes` endpoint. -{{< /see-also >}} +{{< /call-out>}}   @@ -250,13 +250,13 @@ There might be situations when you need to delete a node, either temporarily for If you need to remove a node temporarily, follow the steps in the [Add Nodes to the Cluster](#add-nodes-to-the-cluster) topic when you are ready to re-add it. Make sure to uninstall NGINX Controller from the node before re-installing NGINX Controller with the new join-key. -{{< important >}} +{{< call-out "important" >}} Deleting nodes can cause NGINX Controller to become momentarily unavailable while the cluster is being updated. For this reason, we recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. When deleting nodes, make sure that **at least two nodes are always operational**. If the cluster has fewer than two working nodes, NGINX Controller may become unresponsive, and you may not be able to add new nodes. -{{< /important >}} +{{< /call-out >}} -{{< see-also >}} +{{< call-out "note" >}} To delete nodes from your cluster using the [NGINX Controller API Reference]({{< ref "/controller/api/_index.md" >}}), send a DELETE request to the Nodes endpoint. -{{< /see-also >}} +{{< /call-out>}} To delete a node from the cluster using the web interface: @@ -274,9 +274,9 @@ To delete a node from the cluster using the web interface: /opt/nginx-controller/uninstall.sh ``` -{{< see-also >}} +{{< call-out "note" >}} To delete nodes from your cluster using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a DELETE request to the `/platform/nodes` endpoint. -{{< /see-also >}} +{{< /call-out>}}   @@ -301,11 +301,11 @@ To replace a failed node: When updating NGINX Controller on a multi-node cluster, run the `update.sh` script on each node individually -- the order in which you update the nodes doesn't matter. -{{< warning >}}Do not update the nodes in a multi-node cluster in parallel. Doing so may result in race conditions for certain jobs, such as database migrations, and may cause the cluster to become unavailable.{{< /warning >}} +{{< call-out "warning" >}}Do not update the nodes in a multi-node cluster in parallel. Doing so may result in race conditions for certain jobs, such as database migrations, and may cause the cluster to become unavailable.{{< /call-out >}} -{{< important >}} +{{< call-out "important" >}} Active users will be logged out from NGINX Controller during an update. We recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. -{{< /important >}} +{{< /call-out >}} To update your cluster to a newer version of NGINX Controller, take the following steps: diff --git a/content/controller/admin-guides/install/resilient-cluster-private-cloud.md b/content/controller/admin-guides/install/resilient-cluster-private-cloud.md index cb2339eb0..5672df653 100644 --- a/content/controller/admin-guides/install/resilient-cluster-private-cloud.md +++ b/content/controller/admin-guides/install/resilient-cluster-private-cloud.md @@ -24,8 +24,8 @@ To be resilient, a cluster requires three working nodes. That's two nodes for a If a node fails in a resilient cluster, NGINX Controller automatically redirects traffic to the other working nodes. A multi-node cluster is operational with only two nodes; however, a two-node cluster isn't resilient to further failures. If one of the nodes in a multi-node cluster becomes degraded or fails, you must take action **as soon as possible** to recover or replace the failed node or risk losing resiliency. -{{< important >}}The failover time can take **up to 5 minutes** when a node fails. During this time, NGINX Controller may be unavailable while services are migrated and restarted. Resiliency will be restored once there are **three working nodes** in the cluster. -{{< /important >}} +{{< call-out "important" >}}The failover time can take **up to 5 minutes** when a node fails. During this time, NGINX Controller may be unavailable while services are migrated and restarted. Resiliency will be restored once there are **three working nodes** in the cluster. +{{< /call-out >}} The following table shows how many nodes are needed for a cluster to have a quorum and what the failure tolerance is: @@ -106,9 +106,9 @@ Things you'll need before installing NGINX Controller as a resilient cluster: Nodes are additional control-plane hosts that you can add to your cluster to improve uptime resilience. For a resilient cluster, you should have at least three nodes, of which **two nodes must always be operational**. -{{< important >}} +{{< call-out "important" >}} When adding a third node to the cluster for the first time, NGINX Controller may become momentarily unavailable while the cluster is being created. For this reason, we recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. -{{< /important >}} +{{< /call-out >}} Take the following steps to add a node to the cluster: @@ -140,9 +140,9 @@ Take the following steps to add a node to the cluster: 1. After the installation finishes, the node status in the web interface changes to `Configured`. 1. Repeat these steps for each node that you want to add to the cluster. -{{< see-also >}} +{{< call-out "note" >}} To add nodes to your cluster using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a POST request to the `/platform/nodes` endpoint. -{{< /see-also >}} +{{< /call-out>}}   @@ -154,11 +154,11 @@ To add nodes to your cluster using the [NGINX Controller REST API]({{< ref "/con A floating IP -- also called a virtual IP -- is a static, routable IPv4 address that improves service resiliency by allowing NGINX Controller to continue to receive traffic if a node becomes unavailable. The floating IP is assigned to one of the cluster nodes, and if the node fails, the floating IP is automatically transferred to another node. The floating IP should not be in any DHCP pool. -{{< important>}} +{{< call-out "important" >}} The floating IP needs to be added as an A record for the domain that's used as the Fully Qualified Domain Name (FQDN) for NGINX Controller. NGINX Controller **does not support IPv6** addresses for the floating IP. -{{< /important >}} +{{< /call-out >}} Take the following steps to add a floating IP for your private cloud cluster: @@ -171,9 +171,9 @@ Take the following steps to add a floating IP for your private cloud cluster: 1. Select **Save**. 1. Complete the steps to [update the FQDN](#update-the-fqdn) to use the floating IP. -{{< see-also >}} +{{< call-out "note" >}} To set a floating IP using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a PATCH request to the `/platform/global` endpoint. -{{< /see-also >}} +{{< /call-out>}}   --- @@ -207,9 +207,9 @@ To change the FQDN for NGINX Controller using the web interface, take the follow 1. Select **Save**. The cluster services will restart. During this time, the web interface will be briefly unavailable. 1. Follow the steps to [update the FQDN for Controller Agents](#update-the-fqdn-for-controller-agents). -{{< see-also >}} +{{< call-out "note" >}} To change the FQDN for NGINX Controller using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a PATCH request to the `/platform/global` endpoint. -{{< /see-also >}} +{{< /call-out>}}   ### Update the FQDN for Controller Agents @@ -252,9 +252,9 @@ Take the following steps to update the API Gateway SSL certificate: 1. Select **Save**. -{{< see-also >}} +{{< call-out "note" >}} To update the API Gateway SSL certificate and key using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a PATCH request to the `/platform/global` endpoint. -{{< /see-also >}} +{{< /call-out>}}   @@ -264,9 +264,9 @@ To update the API Gateway SSL certificate and key using the [NGINX Controller RE Take the following steps to view the status for a node: -{{< see-also >}} +{{< call-out "note" >}} To view a node's status using the [NGINX Controller API Reference]({{< ref "/controller/api/_index.md" >}}), send a GET request to the Nodes endpoint. -{{< /see-also >}} +{{< /call-out>}} 1. Open the NGINX Controller web interface and log in. 1. Select the NGINX Controller menu icon, then select **Platform**. @@ -283,13 +283,13 @@ There might be situations when you need to delete a node, either temporarily for If you need to remove a node temporarily, follow the steps in the [Add Nodes to the Cluster](#add-nodes-to-the-cluster) topic when you are ready to re-add it. Make sure to uninstall NGINX Controller from the node before re-installing NGINX Controller with the new join-key. -{{< important >}} +{{< call-out "important" >}} Deleting nodes can cause NGINX Controller to become momentarily unavailable while the cluster is being updated. For this reason, we recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. When deleting nodes, make sure that **at least two nodes are always operational**. If the cluster has fewer than two working nodes, NGINX Controller may become unresponsive, and you may not be able to add new nodes. -{{< /important >}} +{{< /call-out >}} -{{< see-also >}} +{{< call-out "note" >}} To delete nodes from your cluster using the [NGINX Controller API Reference]({{< ref "/controller/api/_index.md" >}}), send a DELETE request to the Nodes endpoint. -{{< /see-also >}} +{{< /call-out>}} To delete a node from the cluster using the web interface: @@ -307,9 +307,9 @@ To delete a node from the cluster using the web interface: /opt/nginx-controller/uninstall.sh ``` -{{< see-also >}} +{{< call-out "note" >}} To delete nodes from your cluster using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a DELETE request to the `/platform/nodes` endpoint. -{{< /see-also >}} +{{< /call-out>}}   @@ -334,11 +334,11 @@ To replace a failed node: When updating NGINX Controller on a multi-node cluster, run the `update.sh` script on each node individually -- the order in which you update the nodes doesn't matter. -{{< warning >}}Do not update the nodes in a multi-node cluster in parallel. Doing so may result in race conditions for certain jobs, such as database migrations, and may cause the cluster to become unavailable.{{< /warning >}} +{{< call-out "warning" >}}Do not update the nodes in a multi-node cluster in parallel. Doing so may result in race conditions for certain jobs, such as database migrations, and may cause the cluster to become unavailable.{{< /call-out >}} -{{< important >}} +{{< call-out "important" >}} Active users will be logged out from NGINX Controller during an update. We recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. -{{< /important >}} +{{< /call-out >}} To update your cluster to a newer version of NGINX Controller, take the following steps: diff --git a/content/controller/admin-guides/install/try-nginx-controller-app-sec.md b/content/controller/admin-guides/install/try-nginx-controller-app-sec.md index ecba8d0f9..7d5bfee52 100644 --- a/content/controller/admin-guides/install/try-nginx-controller-app-sec.md +++ b/content/controller/admin-guides/install/try-nginx-controller-app-sec.md @@ -15,9 +15,9 @@ This quick-start tutorial shows you how to get started using F5 NGINX Controller Take the steps in this guide to deploy NGINX Controller with App Security and deploy NGINX App Protect with NGINX Plus as a data plane instance for use with NGINX Controller. -{{< caution >}}In this tutorial, NGINX Controller will install an embedded, self-hosted PostgreSQL database suitable for demo and trial purposes only. **These instructions are not meant for use in production environments**.{{< /caution >}} +{{< call-out "caution" >}}In this tutorial, NGINX Controller will install an embedded, self-hosted PostgreSQL database suitable for demo and trial purposes only. **These instructions are not meant for use in production environments**.{{< /call-out >}} -{{< note >}}If you already have an active NGINX Controller trial and want to add App Security to it, you can start with the [Install NGINX App Protect with NGINX Plus](#install-nginx-app-protect-with-nginx-plus) section. {{< /note >}} +{{< call-out "note" >}}If you already have an active NGINX Controller trial and want to add App Security to it, you can start with the [Install NGINX App Protect with NGINX Plus](#install-nginx-app-protect-with-nginx-plus) section. {{< /call-out >}}   @@ -48,9 +48,9 @@ The following minimum hardware specifications are required for each node running The App Security add-on for the NGINX Controller Application Delivery module is compatible with the versions of NGINX Plus and NGINX App Protect shown in the table below. New releases of NGINX Controller ADC support the last four versions of NGINX Plus at release time. -{{< see-also >}} +{{< call-out "note" >}} Refer to [Using NGINX App Protect with NGINX Controller]({{< ref "controller/admin-guides/install/install-for-controller.md" >}}) for installation instructions and additional information. -{{< /see-also >}} +{{< /call-out>}} {{< bootstrap-table "table table-striped table-bordered" >}} @@ -85,7 +85,7 @@ Refer to [Using NGINX App Protect with NGINX Controller]({{< ref "controller/adm ## Sign Up for a Trial License -{{< note >}}If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.{{< /note >}} +{{< call-out "note" >}}If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.{{< /call-out >}} First, you need to sign up for a trial license for NGINX Controller. The trial includes access to NGINX Plus, the NGINX Controller Application Delivery module, and the Application Security add-on. @@ -103,7 +103,7 @@ First, you need to sign up for a trial license for NGINX Controller. The trial i ## Install NGINX Controller Prerequisites -{{< note >}}If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.{{< /note >}} +{{< call-out "note" >}}If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.{{< /call-out >}} {{< include "controller/helper-script-prereqs.md" >}} @@ -113,13 +113,13 @@ First, you need to sign up for a trial license for NGINX Controller. The trial i ## Install NGINX Controller -{{< note >}}If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.{{< /note >}} +{{< call-out "note" >}}If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.{{< /call-out >}} Install NGINX Controller on a dedicated node that **does not** already have Kubernetes configured. NGINX Controller does not support pre-configured Kubernetes implementations at this time. The installer for NGINX Controller will install and configure Kubernetes for you. -{{< important >}}Before installing NGINX Controller, you must **disable swap on the host**; this is required by Kubernetes in order for the kubelet to work properly. Refer to your Linux distribution documentation for specific instructions for disabling swap for your system. For more information about this requirement, see the AskF5 knowledge base article [K82655201](https://support.f5.com/csp/article/K82655201) and the [kubeadm installation guide](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) in the Kubernetes documentation.{{< /important >}} +{{< call-out "important" >}}Before installing NGINX Controller, you must **disable swap on the host**; this is required by Kubernetes in order for the kubelet to work properly. Refer to your Linux distribution documentation for specific instructions for disabling swap for your system. For more information about this requirement, see the AskF5 knowledge base article [K82655201](https://support.f5.com/csp/article/K82655201) and the [kubeadm installation guide](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) in the Kubernetes documentation.{{< /call-out >}} -{{< caution >}}**For RHEL 8 deployments**, complete the additional prerequisite steps in the [Installing NGINX on RHEL 8]({{< ref "/controller/admin-guides/install/install-nginx-controller-rhel-8.md" >}}) guide before installing NGINX Controller. RHEL 8 support is a **beta** feature.{{< /caution >}} +{{< call-out "caution" >}}**For RHEL 8 deployments**, complete the additional prerequisite steps in the [Installing NGINX on RHEL 8]({{< ref "/controller/admin-guides/install/install-nginx-controller-rhel-8.md" >}}) guide before installing NGINX Controller. RHEL 8 support is a **beta** feature.{{< /call-out >}} To install NGINX Controller, take the following steps: @@ -143,7 +143,7 @@ To install NGINX Controller, take the following steps: - **Config database volume type**: Specify the type of volume to use to store the config database: local, NFS, or AWS. We recommend choosing `local` for demo and trial purposes. - {{< see-also >}}Refer to the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#local-or-external-storage" >}}) for more information about the volume options and requirements.{{< /see-also >}} + {{< call-out "note" >}}Refer to the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#local-or-external-storage" >}}) for more information about the volume options and requirements.{{< /call-out>}} - **Analytics database volume type**: Specify the type of volume to use to store the analytics database: local, NFS, or AWS. We recommend choosing `local` for demo and trial purposes. - **EULA**: Read the end-user license agreement. Type either `y` to accept or `n` to exit. @@ -162,9 +162,9 @@ To install NGINX Controller, take the following steps: Additionally, the FQDN is used by Controller Agents when connecting to NGINX Controller. - **SSL/TLS certificates**: Type `y` to generate and use self-signed certs for running NGINX Controller over HTTPS, or type `n` to provide your own certs. - {{< important >}} + {{< call-out "important" >}} If you provide your own SSL/TLS certificates, you'll need a complete certificate chain file, with the intermediate CA cert appended to the server cert; the server certificate must appear **before** the chained certificates in the combined file. - {{< /important >}} + {{< /call-out >}} 1. Log in to NGINX Controller at `https:///login`. Use the admin email address and password that you provided during the installation process. @@ -186,9 +186,9 @@ To add a license to NGINX Controller, take the following steps: 1. Select **Save license**. -{{< see-also >}} +{{< call-out "note" >}} To add a license using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a PUT request to the `/platform/license` endpoint. Provide your CAT or NGINX Controller license as a base64-encoded string in the JSON request body. -{{< /see-also >}} +{{< /call-out>}}   @@ -199,11 +199,11 @@ To add a license using the [NGINX Controller REST API]({{< ref "/controller/api/ [NGINX App Protect](https://www.nginx.com/products/nginx-app-protect/) is the security data plane for NGINX Controller App Security. Your NGINX App Protect installation will include NGINX Plus. -{{< important >}} +{{< call-out "important" >}} If you are adding App Security to an existing NGINX Controller trial, we recommend that you take the steps in this section to deploy a new NGINX App Protect instance, rather than adding the App Protect module to an existing NGINX Plus instance. NGINX Controller App Security is supported for use with a limited subset of the OS distributions that are supported by the NGINX Controller Agent and NGINX Plus. If you are planning to add NGINX App Protect to an existing NGINX Plus instance, be sure to check the [Supported Distributions](#supported-distributions) section above to verify that your NGINX Plus instance supports NGINX App Protect. -{{< /important >}} +{{< /call-out >}} ### Prerequisites @@ -216,9 +216,9 @@ Take the steps below to download the cert and key files by using the NGINX Contr The NGINX Controller API uses session cookies to authenticate requests. The session cookie is returned in response to a `GET /api/v1/platform/login` request. See the Login endpoint in the [NGINX Controller API Reference]({{< ref "/controller/api/_index.md" >}}) documentation for information about session cookie timeouts and invalidation. -{{< tip >}} +{{< call-out "tip" >}} You can send a GET request to the login endpoint to find the status of the session token. -{{< /tip >}} +{{< /call-out >}} For example: @@ -253,9 +253,9 @@ For example: curl -b cookie.txt -c cookie.txt -X GET --url 'https://192.0.2.0/api/v1/platform/licenses/nginx-plus-licenses/controller-provided' --output nginx-plus-certs.gz ``` -{{< note >}} +{{< call-out "note" >}} If you are using a self-signed certificate you will need to add `-k` (allow insecure connections) to your curl command to be able to download your NGINX Plus certificate and key bundle. -{{< /note >}} +{{< /call-out >}} Once you have downloaded your certificate and key bundle you will need to expand the `.gz` file to get your certificate and key pair. @@ -272,10 +272,10 @@ gunzip nginx-plus-certs.gz Install NGINX App Protect on a host accessible by your NGINX Controller instance by following the appropriate steps for your operating system in the [Using NGINX App Protect with NGINX Controller]({{< ref "controller/admin-guides/install/install-for-controller.md" >}}) guide. -{{< note >}} +{{< call-out "note" >}} If you install NGINX App Protect by using any of the OS-specific install guides, **do not make changes to the `nginx.conf` file**. The NGINX Controller Agent manages `nginx.conf` settings and will make the appropriate adjustments for you. -{{< /note >}} +{{< /call-out >}} diff --git a/content/controller/admin-guides/install/try-nginx-controller.md b/content/controller/admin-guides/install/try-nginx-controller.md index dd2883d56..e77bf343f 100644 --- a/content/controller/admin-guides/install/try-nginx-controller.md +++ b/content/controller/admin-guides/install/try-nginx-controller.md @@ -13,9 +13,9 @@ type: This quick-start tutorial shows you how to get started using F5 NGINX Controller with NGINX Plus. -{{< caution >}}In this tutorial, NGINX Controller will install an embedded, self-hosted PostgreSQL database suitable for demo and trial purposes only. **These instructions are not meant for use in production environments**.{{< /caution >}} +{{< call-out "caution" >}}In this tutorial, NGINX Controller will install an embedded, self-hosted PostgreSQL database suitable for demo and trial purposes only. **These instructions are not meant for use in production environments**.{{< /call-out >}} -{{< see-also >}}If you want to try out NGINX Controller with the Application Security add-on, refer to [Trial NGINX Controller with App Security]({{< ref "/controller/admin-guides/install/try-nginx-controller-app-sec.md" >}}).{{< /see-also >}} +{{< call-out "note" >}}If you want to try out NGINX Controller with the Application Security add-on, refer to [Trial NGINX Controller with App Security]({{< ref "/controller/admin-guides/install/try-nginx-controller-app-sec.md" >}}).{{< /call-out>}}   @@ -29,7 +29,7 @@ Make sure to review the [NGINX Controller Technical Specifications Guide]({{< re NGINX Controller, the NGINX Controller Agent, and the NGINX Controller Application Security Add-on support the following distributions and architectures. -{{< see-also >}}Refer to the [NGINX Plus Technical Specifications](https://docs.nginx.com/nginx/technical-specs/) guide for the distributions that NGINX Plus supports.{{< /see-also >}} +{{< call-out "note" >}}Refer to the [NGINX Plus Technical Specifications](https://docs.nginx.com/nginx/technical-specs/) guide for the distributions that NGINX Plus supports.{{< /call-out>}} {{< bootstrap-table "table table-striped table-bordered" >}} @@ -116,9 +116,9 @@ First, you need to sign up for a trial license for NGINX Controller. The trial i Install NGINX Controller on a dedicated node that **does not** already have Kubernetes configured. NGINX Controller does not support pre-configured Kubernetes implementations at this time. The installer for NGINX Controller will install and configure Kubernetes for you. -{{< important >}}Before installing NGINX Controller, you must **disable swap on the host**; this is required by Kubernetes in order for the kubelet to work properly. Refer to your Linux distribution documentation for specific instructions for disabling swap for your system. For more information about this requirement, see the AskF5 knowledge base article [K82655201](https://support.f5.com/csp/article/K82655201) and the [kubeadm installation guide](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) in the Kubernetes documentation.{{< /important >}} +{{< call-out "important" >}}Before installing NGINX Controller, you must **disable swap on the host**; this is required by Kubernetes in order for the kubelet to work properly. Refer to your Linux distribution documentation for specific instructions for disabling swap for your system. For more information about this requirement, see the AskF5 knowledge base article [K82655201](https://support.f5.com/csp/article/K82655201) and the [kubeadm installation guide](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) in the Kubernetes documentation.{{< /call-out >}} -{{< caution >}}**For RHEL 8 deployments**, complete the additional prerequisite steps in the [Installing NGINX on RHEL 8]({{< ref "/controller/admin-guides/install/install-nginx-controller-rhel-8.md" >}}) guide before installing NGINX Controller. RHEL 8 support is a **beta** feature.{{< /caution >}} +{{< call-out "caution" >}}**For RHEL 8 deployments**, complete the additional prerequisite steps in the [Installing NGINX on RHEL 8]({{< ref "/controller/admin-guides/install/install-nginx-controller-rhel-8.md" >}}) guide before installing NGINX Controller. RHEL 8 support is a **beta** feature.{{< /call-out >}} To install NGINX Controller, take the following steps: @@ -142,7 +142,7 @@ To install NGINX Controller, take the following steps: - **Config database volume type**: Specify the type of volume to use to store the config database: local, NFS, or AWS. We recommend choosing `local` for demo and trial purposes. - {{< see-also >}}Refer to the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#local-or-external-storage" >}}) for more information about the volume options and requirements.{{< /see-also >}} + {{< call-out "note" >}}Refer to the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#local-or-external-storage" >}}) for more information about the volume options and requirements.{{< /call-out>}} - **Analytics database volume type**: Specify the type of volume to use to store the analytics database: local, NFS, or AWS. We recommend choosing `local` for demo and trial purposes. - **EULA**: Read the end-user license agreement. Type either `y` to accept or `n` to exit. @@ -161,9 +161,9 @@ To install NGINX Controller, take the following steps: Additionally, the FQDN is used by Controller Agents when connecting to NGINX Controller. - **SSL/TLS certificates**: Type `y` to generate and use self-signed certs for running NGINX Controller over HTTPS, or type `n` to provide your own certs. - {{< important >}} + {{< call-out "important" >}} If you provide your own SSL/TLS certificates, you'll need a complete certificate chain file, with the intermediate CA cert appended to the server cert; the server certificate must appear **before** the chained certificates in the combined file. - {{< /important >}} + {{< /call-out >}} 1. Log in to NGINX Controller at `https:///login`. Use the admin email address and password that you provided during the installation process. @@ -185,9 +185,9 @@ To add a license to NGINX Controller, take the following steps: 1. Select **Save license**. -{{< see-also >}} +{{< call-out "note" >}} To add a license using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a PUT request to the `/platform/license` endpoint. Provide your CAT or NGINX Controller license as a base64-encoded string in the JSON request body. -{{< /see-also >}} +{{< /call-out>}}   @@ -205,9 +205,9 @@ To add a license using the [NGINX Controller REST API]({{< ref "/controller/api/ The NGINX Controller API uses session cookies to authenticate requests. The session cookie is returned in response to a `GET /api/v1/platform/login` request. See the Login endpoint in the [NGINX Controller API Reference]({{< ref "/controller/api/_index.md" >}}) documentation for information about session cookie timeouts and invalidation. -{{< tip >}} +{{< call-out "tip" >}} You can send a GET request to the login endpoint to find the status of the session token. -{{< /tip >}} +{{< /call-out >}} For example: @@ -242,9 +242,9 @@ For example: curl -b cookie.txt -c cookie.txt -X GET --url 'https://192.0.2.0/api/v1/platform/licenses/nginx-plus-licenses/controller-provided' --output nginx-plus-certs.gz ``` -{{< note >}} +{{< call-out "note" >}} If you are using a self-signed certificate you will need to add `-k` (allow insecure connections) to your curl command to be able to download your NGINX Plus certificate and key bundle. -{{< /note >}} +{{< /call-out >}} Once you have downloaded your certificate and key bundle you will need to expand the `.gz` file to get your certificate and key pair. @@ -259,9 +259,9 @@ gunzip nginx-plus-certs.gz Take the following steps to install NGINX Plus: -{{< important >}} +{{< call-out "important" >}} You need the NGINX Plus certificate and public key files (`nginx-repo.crt` and `nginx-repo.key`) that were provided when you signed up for the trial license. -{{< /important >}} +{{< /call-out >}} 1. First, make sure to review the [NGINX Plus Technical Specifications Guide](https://docs.nginx.com/nginx/technical-specs/) for the requirements for your distribution and desired configuration. 2. To install NGINX Plus, follow the instructions in the [NGINX Plus Installation Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). Refer to the relevant section for your distribution. diff --git a/content/controller/admin-guides/install/using-helper-script.md b/content/controller/admin-guides/install/using-helper-script.md index 382332f63..830602bb7 100644 --- a/content/controller/admin-guides/install/using-helper-script.md +++ b/content/controller/admin-guides/install/using-helper-script.md @@ -104,7 +104,7 @@ After installing NGINX Controller, you should back up the cluster config and enc This section explains how to restore the embedded config database from the latest backup file or a specific, timestamped file. -{{< important >}}If you restore the config database on top of a new installation of NGINX Controller, make sure to follow the steps to [restore your NGINX config and encryption keys]({{< ref "/controller/admin-guides/backup-restore/backup-restore-cluster-config.md" >}}) afterward. {{< /important >}} +{{< call-out "important" >}}If you restore the config database on top of a new installation of NGINX Controller, make sure to follow the steps to [restore your NGINX config and encryption keys]({{< ref "/controller/admin-guides/backup-restore/backup-restore-cluster-config.md" >}}) afterward. {{< /call-out >}} - To restore the embedded NGINX Controller config database **from the latest automated backup**, run the following command: @@ -134,7 +134,7 @@ To install NGINX Plus as a data plane for NGINX Controller, you need to have the {{< deprecated >}}Using the helper.sh script to download your NGINX Plus certificate and key bundle is deprecated in in NGINX Controller v3.9.{{< /deprecated >}} -{{< see-also >}}If you're running NGINX Controller v3.10+, you can use the REST API to [Download the NGINX Plus Cert and Key Bundle]({{< ref "/controller/admin-guides/install/get-n-plus-cert-and-key.md" >}}). {{< /see-also >}}  +{{< call-out "note" >}}If you're running NGINX Controller v3.10+, you can use the REST API to [Download the NGINX Plus Cert and Key Bundle]({{< ref "/controller/admin-guides/install/get-n-plus-cert-and-key.md" >}}). {{< /call-out>}}  If you're running NGINX Controller 3.9 or earlier, use the `helper.sh` script to extract the NGINX repository key and certificate files: @@ -142,11 +142,11 @@ If you're running NGINX Controller 3.9 or earlier, use the `helper.sh` script to /opt/nginx-controller/helper.sh repository-cred [-c|--cert ] [-k|--key ] ``` -{{< important >}} +{{< call-out "important" >}} Make sure that you've [uploaded your license in NGINX Controller]({{< ref "licensing-controller.md" >}}) first before running the `helper.sh repository-cred` command to extract the repository files. -{{< /important >}} +{{< /call-out >}}