diff --git a/site/content/contribute/dev-environment-setup.md b/site/content/contribute/dev-environment-setup.md index 17cada7f68..d56c064cba 100644 --- a/site/content/contribute/dev-environment-setup.md +++ b/site/content/contribute/dev-environment-setup.md @@ -17,7 +17,7 @@ Ubuntu is the recommended operating system for development, as it comes with mos To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< ref "/installation-upgrade/install.md" >}}). +- A [working NGINX Agent instance]({{< ref "/install-upgrade/install.md" >}}). - A [Go installation](https://go.dev/dl/) of version 1.22.2 or newer. - A [Protocol Buffer Compiler](https://grpc.io/docs/protoc-installation/) installation. @@ -29,7 +29,7 @@ git clone git@github.com:nginx/agent.git Read [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for more information -Follow the steps in the [Installation]({{< relref "/installation-upgrade/install.md" >}}) topic to install NGINX Agent. +Follow the steps in the [Installation]({{< relref "/install-upgrade/install.md" >}}) topic to install NGINX Agent. ## Install prerequisite packages Depending on the operating system distribution, it may be necessary to install the following packages in order to build NGINX Agent. diff --git a/site/content/contribute/start-mock-interface.md b/site/content/contribute/start-mock-interface.md index baf3430067..2c148de78e 100644 --- a/site/content/contribute/start-mock-interface.md +++ b/site/content/contribute/start-mock-interface.md @@ -13,7 +13,7 @@ The mock interface is useful when developing NGINX Agent, as it allows you to vi To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< ref "/installation-upgrade/install.md" >}}). +- A [working NGINX Agent instance]({{< ref "/install-upgrade/install.md" >}}). - A [Go installation](https://go.dev/dl/) of version 1.22.2 or newer. - A [go-swagger](https://goswagger.io/go-swagger/install/) installation. diff --git a/site/content/how-to/export-metrics.md b/site/content/how-to/export-metrics.md index a686921c63..7bbd3a6871 100644 --- a/site/content/how-to/export-metrics.md +++ b/site/content/how-to/export-metrics.md @@ -24,7 +24,7 @@ This document describes how to export the metrics data from F5 NGINX Agent. To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< ref "/installation-upgrade/install.md" >}}). +- A [working NGINX Agent instance]({{< ref "/install-upgrade/install.md" >}}). - - diff --git a/site/content/installation-upgrade/_index.md b/site/content/install-upgrade/_index.md similarity index 100% rename from site/content/installation-upgrade/_index.md rename to site/content/install-upgrade/_index.md diff --git a/site/content/installation-upgrade/container-environments/_index.md b/site/content/install-upgrade/container-environments/_index.md similarity index 100% rename from site/content/installation-upgrade/container-environments/_index.md rename to site/content/install-upgrade/container-environments/_index.md diff --git a/site/content/installation-upgrade/container-environments/docker-images.md b/site/content/install-upgrade/container-environments/docker-images.md similarity index 100% rename from site/content/installation-upgrade/container-environments/docker-images.md rename to site/content/install-upgrade/container-environments/docker-images.md diff --git a/site/content/installation-upgrade/container-environments/docker-support.md b/site/content/install-upgrade/container-environments/docker-support.md similarity index 92% rename from site/content/installation-upgrade/container-environments/docker-support.md rename to site/content/install-upgrade/container-environments/docker-support.md index 558b08118a..f6e41ad6fd 100644 --- a/site/content/installation-upgrade/container-environments/docker-support.md +++ b/site/content/install-upgrade/container-environments/docker-support.md @@ -7,7 +7,7 @@ docs: DOCS-000 ## Overview -The F5 NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/main/scripts/docker) that can be used to [build custom container images]({{< relref "installation-upgrade/container-environments/docker-images.md" >}}). Images are created with an NGINX Open Source or NGINX Plus instance and are available for various operating systems. +The F5 NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/main/scripts/docker) that can be used to [build custom container images]({{< relref "/install-upgrade/container-environments/docker-images.md" >}}). Images are created with an NGINX Open Source or NGINX Plus instance and are available for various operating systems. See the [Technical Specifications]({{< relref "/technical-specifications.md#container-support" >}}) for a list of supported operationg systems. diff --git a/site/content/installation-upgrade/install.md b/site/content/install-upgrade/install.md similarity index 100% rename from site/content/installation-upgrade/install.md rename to site/content/install-upgrade/install.md diff --git a/site/content/installation-upgrade/migrate-v3.md b/site/content/install-upgrade/migrate-v3.md similarity index 92% rename from site/content/installation-upgrade/migrate-v3.md rename to site/content/install-upgrade/migrate-v3.md index f77206fefa..fe9a0533f3 100644 --- a/site/content/installation-upgrade/migrate-v3.md +++ b/site/content/install-upgrade/migrate-v3.md @@ -24,7 +24,7 @@ This topic describes how to migrate from F5 NGINX Agent v2 to NGINX Agent v3. To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< ref "/installation-upgrade/install.md" >}}). +- A [working NGINX Agent instance]({{< ref "/install-upgrade/install.md" >}}). - - diff --git a/site/content/installation-upgrade/uninstall.md b/site/content/install-upgrade/uninstall.md similarity index 100% rename from site/content/installation-upgrade/uninstall.md rename to site/content/install-upgrade/uninstall.md diff --git a/site/content/installation-upgrade/upgrade.md b/site/content/install-upgrade/upgrade.md similarity index 100% rename from site/content/installation-upgrade/upgrade.md rename to site/content/install-upgrade/upgrade.md diff --git a/site/content/installation-upgrade/getting-started.md b/site/content/installation-upgrade/getting-started.md deleted file mode 100644 index e3be8c8095..0000000000 --- a/site/content/installation-upgrade/getting-started.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: "Getting started" -draft: false -weight: 100 -toc: true -tags: [ "docs" ] -categories: ["configuration"] -doctypes: ["task"] ---- - -## Overview - -Follow these steps to configure and run NGINX Agent and a mock interface ("control plane") to which NGINX Agent will report. - -## Install NGINX - -Follow the steps in the [Installation]({{< relref "/installation-upgrade/installation-github.md" >}}) section to download, install, and run NGINX. - -## Clone the NGINX Agent Repository - -Using your preferred method, clone the NGINX Agent repository into your development directory. See [Cloning a GitHub Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for additional help. - -## Install Go - -NGINX Agent and the Mock Control Plane are written in Go. Go 1.23.0 or higher is required to build and run either application from the source code directory. You can [download Go from the official website](https://go.dev/dl/). - -## Start the gRPC Mock Control Plane - -Start the mock control plane by running the following command from the `agent` source code root directory: - -```shell -go run sdk/examples/server.go - -# Command Output -INFO[0000] http listening at 54790 # mock control plane port -INFO[0000] grpc listening at 54789 # grpc control plane port which NGINX Agent will report to -``` - -## NGINX Agent Settings - -If it doesn't already exist, create the `/etc/nginx-agent/` directory and copy the `nginx-agent.conf` file into it from the project root directory. - -```shell -sudo mkdir /etc/nginx-agent -sudo cp /nginx-agent.conf /etc/nginx-agent/ -``` - -Create the `agent-dynamic.conf` file, which is required for NGINX Agent to run. - -In Linux environments: -```shell -sudo touch /var/lib/nginx-agent/agent-dynamic.conf -``` - -In FreeBSD environments: -```shell -sudo touch /var/db/nginx-agent/agent-dynamic.conf -``` - -### Enable the gRPC interface - -Add the the following settings to `/etc/nginx-agent/nginx-agent.conf`: - -```yaml -server: - host: 127.0.0.1 # mock control plane host - grpcPort: 54789 # mock control plane gRPC port - -# gRPC TLS options - DISABLING TLS IS NOT RECOMMENDED FOR PRODUCTION -tls: - enable: false - skip_verify: true -``` - -For more information, see [Agent Protocol Definitions and Documentation](https://github.com/nginx/agent/tree/main/docs/proto/README.md). - -### Enable the REST interface - -The NGINX Agent REST interface can be exposed by validating the following lines in the `/etc/nginx-agent/nginx-agent.conf` file are present: - -```yaml -api: - # Set API address to allow remote management - host: 127.0.0.1 - # Set this value to a secure port number to prevent information leaks - port: 8038 - # REST TLS parameters - cert: ".crt" - key: ".key" -``` - -The mock control plane can use either gRPC or REST protocols to communicate with NGINX Agent. - -## Launch Swagger UI - -Swagger UI requires goswagger be installed. See [instructions for installing goswagger](https://goswagger.io/install.html) for additional help. - -To launch the Swagger UI for the REST interface run the following command: - -```shell -make launch-swagger-ui -``` - -## Extensions - -An extension is a piece of code, not critical to the main functionality that NGINX agent is responsible for. This generally falls outside the remit of managing NGINX Configuration and reporting NGINX metrics. - -To enable an extension, it must be added to the extensions list in the `/etc/nginx-agent/nginx-agent.conf`. -Here is an example of enabling the advanced metrics extension: - -```yaml -extensions: - - advanced-metrics -``` - -## Start NGINX Agent - -If already running, restart NGINX Agent to apply the new configuration. Alternatively, if NGINX Agent is not running, you may run it from the source code root directory. - -Open another terminal window and start NGINX Agent. Issue the following command from the `agent` source code root directory. - -```shell -sudo make run - -# Command Output snippet -WARN[0000] Log level is info -INFO[0000] setting displayName to XXX -INFO[0000] NGINX Agent at with pid 12345, clientID=XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX name=XXX -INFO[0000] NginxBinary initializing -INFO[0000] Commander initializing -INFO[0000] Comms initializing -INFO[0000] OneTimeRegistration initializing -INFO[0000] Registering XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX -INFO[0000] Metrics initializing -INFO[0000] MetricsThrottle initializing -INFO[0000] DataPlaneStatus initializing -INFO[0000] MetricsThrottle waiting for report ready -INFO[0000] Metrics waiting for handshake to be completed -INFO[0000] ProcessWatcher initializing -INFO[0000] Extensions initializing -INFO[0000] FileWatcher initializing -INFO[0000] FileWatchThrottle initializing -INFO[0001] Events initializing -INFO[0001] OneTimeRegistration completed -``` - -Open a web browser to view the mock control plane at [http://localhost:54790](http://localhost:54790). The following links will be shown in the web interface: - -- **registered** - shows registration information of the data plane -- **nginxes** - lists the nginx instances on the data plane -- **configs** - shows the protobuf payload for NGINX configuration sent to the management plane -- **configs/chunked** - shows the split-up payloads sent to the management plane -- **configs/raw** - shows the actual configuration as it would live on the data plane -- **metrics** - shows a buffer of metrics sent to the management plane (similar to what will be sent back in the REST API) - -For more NGINX Agent use cases, refer to the [NGINX Agent SDK examples](https://github.com/nginx/agent/tree/main/sdk/examples). - -## Start and Enable Start on Boot - -To start NGINX Agent on `systemd` systems, run the following command: - -```shell -sudo systemctl start nginx-agent -``` - -To enable NGINX Agent to start on boot, run the following command: - -```shell -sudo systemctl enable nginx-agent -``` - -## Logs - -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 >}} -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]({{< relref "configuration/configuration-overview.md#nginx-agent-log-rotation" >}}). -{{< /important >}} diff --git a/site/content/v2/installation-upgrade/container-environments/docker-support.md b/site/content/v2/installation-upgrade/container-environments/docker-support.md index 7123d9ee12..7736fa9512 100644 --- a/site/content/v2/installation-upgrade/container-environments/docker-support.md +++ b/site/content/v2/installation-upgrade/container-environments/docker-support.md @@ -12,7 +12,7 @@ docs: "DOCS-909" ## Overview -The NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/main/scripts/docker) that can be used to [build custom container images]({{< relref "installation-upgrade/container-environments/docker-images.md" >}}). Images are created with an NGINX Open Source or NGINX Plus instance and are available for various operating systems. +The NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/main/scripts/docker) that can be used to [build custom container images]({{< relref "/v2/installation-upgrade/container-environments/docker-images.md" >}}). Images are created with an NGINX Open Source or NGINX Plus instance and are available for various operating systems. See the [Technical Specifications]({{< relref "/technical-specifications.md#container-support" >}}) for a list of supported operationg systems.