readme consolidation #19
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,130 +1,160 @@ | ||||||
| # NGINX Agent | ||||||
| The NGINX Agent enhances your deployment experience and enables you to monitor your system and app performance, whether you are using NGINX OSS or NGINX Plus for App Delivery, Content Caching, API Gateway, and App Security. To do so, the Agent provides an administrative entry point to remotely manage, configure and collect metrics and events on the datapath instances. | ||||||
|
|
||||||
| Simply put, Agent optimizes the operationalization of your application stack. | ||||||
|
|
||||||
| ## How it works | ||||||
| The NGINX Agent uses the Linux operating system pseudo-filesystems to interface with the process information of NGINX. The Agent checks ```nginx -V``` output to determine the relevant configuration location for NGINX. Then it validates the configuration with ```nginx -t``` before applying the NGINX configuration. | ||||||
| The Agent reads both the access and error logs from the NGINX configuration. Reading this set of files from the NGINX configuration, using the specified log formats, it parses the appropriate log files and calculates the reported metrics. For NGINX Plus, the Agent takes the relevant information from the NGINX Plus API, configurable through the NGINX configuration. | ||||||
|
|
||||||
|
|
||||||
|  | ||||||
|
|
||||||
| ## What can you do with the NGINX Agent today | ||||||
| - Circulation of NGINX configurations | ||||||
| - Reporting of metrics | ||||||
| - Publicizing of data plane events | ||||||
|
|
||||||
| ## Agent Technical Specifications | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ### Supported Distributions | ||||||
|
|
||||||
| The Agent can run in most environments. For the supported distributions, see the [NGINX Technical Specs](https://docs.nginx.com/nginx/technical-specs/#supported-distributions) guide. | ||||||
|
|
||||||
| ### Supported Deployment Environments | ||||||
| You can deploy the Agent in the following environments: | ||||||
|
|
||||||
| - Bare Metal | ||||||
| - Container | ||||||
| - Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure | ||||||
| - Virtual Machine | ||||||
|
|
||||||
| ### Supported NGINX Versions | ||||||
| The Agent works with all supported versions of NGINX OSS and NGINX Plus. | ||||||
|
|
||||||
| ### Sizing Recommendations | ||||||
| The following table lists the minimum sizing recommendations for the Agent: | ||||||
|
|
||||||
| Table: Agent sizing recommendations | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| | CPU | Memory | Network | Storage | | ||||||
| |------------|----------|-----------|---------| | ||||||
| | 1 CPU core | 1 GB RAM | 1 GbE NIC | 20 GB | | ||||||
|
|
||||||
| ### Logging | ||||||
| The Agent uses the log files and formats to collect metrics. Expanding the log formats and instance counts will also increase the size of the log files on the Agent. Adding a separate partition for /var/log/nginx-agent is always a good idea. Without log rotation or a separated partition, a log directory could cause your system to run out of space. | ||||||
|
|
||||||
| ## Getting started with Agent | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| The result of following the below steps you will locally have an NGINX instance running, Agent running, and a mock control plane to which the Agent will report. | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| Ensure you have Go installed ([download](https://go.dev/dl/)). Version 1.18 or higher is required. | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| Ensure an NGINX instance is running. See [Prebuilt Packages for Linux and BSD](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/) or if your running on Mac see [brew nginx](https://formulae.brew.sh/formula/nginx) to install NGINX. Once installed ensure NGINX instance is running. If running on Mac and you installed using brew can start NGINX by the below command. | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ``` | ||||||
| sudo brew services start nginx | ||||||
| ``` | ||||||
|
|
||||||
| Next, start the mock control plane using the below command | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
| ``` | ||||||
| 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 Agent will report to | ||||||
| ``` | ||||||
|
|
||||||
| Next change the nginx-agent.conf file within the root directory | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
| ### NGINX Agent Settings | ||||||
| ```yaml | ||||||
| server: | ||||||
| # host of the control plane | ||||||
| host: 127.0.0.1 | ||||||
| grpcPort: 54789 # control plane grpc port | ||||||
| # tls options - NOT RECOMMENDED FOR PRODUCTION | ||||||
| tls: | ||||||
| enable: false | ||||||
| skip_verify: true | ||||||
| ``` | ||||||
|
|
||||||
| Next, open up another terminal and start the Agent | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
| ``` | ||||||
| sudo mkdir /etc/nginx-agent | ||||||
| sudo touch /etc/nginx-agent/agent-dynamic.conf | ||||||
| sudo cp nginx-agent.conf /etc/nginx-agent/ | ||||||
| go run main.go | ||||||
|
|
||||||
| # 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 | ||||||
| ``` | ||||||
|
|
||||||
| Next, open up a web browser to view the mock control plane [http://localhost:54790](http://localhost:54790). 6 links will be presented on the control plane | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| - registred - Shows | ||||||
| - nginxes - Shows | ||||||
| - configs - Shows | ||||||
| - configs/chunked - Shows | ||||||
| - configs/raw - Shows | ||||||
| - metrics - Shows | ||||||
|
|
||||||
| For more use-cases of the NGINX Agent, refer to https://github.com/nginx/agent/tree/main/sdk/examples | ||||||
|
|
||||||
| ## Installation | ||||||
|
|
||||||
| ### Install from package files | ||||||
| To install Agent on your system go to [Releases](https://github.com/nginx/agent/releases) and download the packages.zip file under Assets for a given version of the Agent. | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| Depending on your OS distribution and CPU architecture type, use your system's package manager as in the following examples: | ||||||
| ``` | ||||||
| sudo apt install ./nginx-agent_<agent-version>-SNAPSHOT-<snapshot-id>_linux_<arch-type>.deb | ||||||
|
|
||||||
| sudo rpm -i nginx-agent_<agent-version>-SNAPSHOT-<snapshot-id>_linux_<arch-type>.rpm | ||||||
|
|
||||||
| sudo yum localinstall nginx-agent_<agent-version>-SNAPSHOT-<snapshot-id>_linux_<arch-type>.rpm | ||||||
| ``` | ||||||
| ### Start and Enable Agent | ||||||
| To start the NGINX Agent on systemd systems, run the following command: | ||||||
| ``` | ||||||
| sudo systemctl start nginx-agent | ||||||
| ``` | ||||||
| To enable the NGINX Agent to start on boot, run the following command: | ||||||
| ``` | ||||||
| sudo systemctl enable nginx-agent | ||||||
| ``` | ||||||
|
|
||||||
| ## Community | ||||||
|
|
||||||
| - Our [Slack channel #nginx-agent](https://nginxcommunity.slack.com/), is the go-to place to start asking questions and sharing your thoughts. | ||||||
|
|
||||||
| - Our [GitHub issues page](https://github.com/nginx/agent/issues) offers space for a more technical discussion at your own pace. | ||||||
|
|
||||||
| - Get involved with the project by contributing! See the contributing guide for details. | ||||||
|
|
||||||
| To reach the team directly, subscribe to the [mailing list](https://mailman.nginx.org/mailman/listinfo/agent). | ||||||
|
|
||||||
| ## Contributing | ||||||
|
|
||||||
| If you'd like to contribute to the project, please read our [Contributing guide](docs/CONTRIBUTING.md). | ||||||
|
|
||||||
| ## License | ||||||
|
|
||||||
| [Apache License, Version 2.0](LICENSE) | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.