Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README updates #126

Merged
merged 14 commits into from
Dec 6, 2022
Merged

README updates #126

Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
4f638ec
updated readme to include sudo before all make run commands
mtbChef Nov 30, 2022
44b21c2
updated README references of Agent to NGINX Agent
mtbChef Nov 30, 2022
3b2cc69
updated flow diagram to appoved "nginx open source" verbiage, fixed t…
mtbChef Dec 1, 2022
7d294ee
updated readme flow diagram with slight spacing updates from visual d…
mtbChef Dec 1, 2022
be3e0f1
updated readme to include sudo before all make run commands
mtbChef Nov 30, 2022
5555b90
updated README references of Agent to NGINX Agent
mtbChef Nov 30, 2022
8449b80
updated flow diagram to appoved "nginx open source" verbiage, fixed t…
mtbChef Dec 1, 2022
243bef6
updated readme flow diagram with slight spacing updates from visual d…
mtbChef Dec 1, 2022
e3424f3
Updates for agent-dynamic conf instructions
craigell Dec 2, 2022
118c80c
Merge branch 'docs-updates' of github.com:nginx/agent into docs-updates
mtbChef Dec 2, 2022
a65821c
Updated README git repo cloning instructions
mtbChef Dec 2, 2022
33a9c24
Consolidated cloning instructions in the README
mtbChef Dec 5, 2022
ab9bc3b
Clarified instructions for adding agent-dynamic.conf in README
mtbChef Dec 5, 2022
4d7f1e6
Merge branch 'main' into docs-updates
mtbChef Dec 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 63 additions & 66 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
![Agent Banner](docs/agent-banner.png "Agent Banner")
![NGINX Agent Banner](docs/agent-banner.png "NGINX Agent Banner")

NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance. It enables:
- Remote management of NGINX configurations
- Collection and reporting of real-time NGINX performance and operating system metrics
- Notifications of NGINX events

![Grafana dashboard showing Agent reported metrics](docs/grafana-dashboard-example.png "Grafana dashboard showing Agent reported metrics")
[Grafana](https://grafana.com/) dashboard showing metrics reported by Agent
![Grafana dashboard showing NGINX Agent reported metrics](docs/grafana-dashboard-example.png "Grafana dashboard showing NGINX Agent reported metrics")
[Grafana](https://grafana.com/) dashboard showing metrics reported by NGINX Agent

# Table of Contents
- [How it Works](#how-it-works)
Expand All @@ -16,21 +16,22 @@ NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus insta
- [Installation](#installation)
- [Installing NGINX](#installing-nginx)
- [Installing Go](#installing-go)
- [Installing Agent from Package Files](#installing-agent-from-package-files)
- [Installing NGINX Agent from Package Files](#installing-nginx-agent-from-package-files)
- [Starting and Enabling Start on Boot](#starting-and-enabling-start-on-boot)
- [Logging](#logging)
- [Getting Started with Agent](#getting-started-with-agent)
- [Installing NGINX and Agent](#installing-nginx-and-agent)
- [Starting the Mock Control Plane](#starting-the-mock-control-plane)
- [Agent Settings](#agent-settings)
- [Starting Agent](#starting-agent)
- [Getting Started with NGINX Agent](#getting-started-with-nginx-agent)
- [Installing NGINX and NGINX Agent](#installing-nginx-and-nginx-agent)
- [Cloning the NGINX Agent Repository](#cloning-the-nginx-agent-repository)
- [Starting the gRPC Mock Control Plane](#starting-the-grpc-mock-control-plane)
- [NGINX Agent Settings](#nginx-agent-settings)
- [Starting NGINX Agent](#starting-nginx-agent)
- [Development Environment Setup](#development-environment-setup)
- [Selecting an Operating System](#selecting-an-operating-system)
- [Installing NGINX](#installing-nginx)
- [Cloning the Agent Repository](#cloning-the-agent-repository)
- [Cloning the NGINX Agent Repository](#cloning-the-nginx-agent-repository)
- [Installing Prerequisite Packages](#installing-prerequisite-packages)
- [Building Agent from Source Code](#building-agent-from-source-code)
- [Agent Technical Specifications](#agent-technical-specifications)
- [Building NGINX Agent from Source Code](#building-nginx-agent-from-source-code)
- [NGINX Agent Technical Specifications](#nginx-agent-technical-specifications)
- [Supported Distributions](#supported-distributions)
- [Supported Deployment Environments](#supported-deployment-environments)
- [Supported NGINX Versions](#supported-nginx-versions)
Expand All @@ -41,29 +42,29 @@ NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus insta
- [License](#license)

# How it Works
Agent runs as a companion process on a system running NGINX. It provides gRPC and REST interfaces for configuration management and metrics collection from the NGINX process and operating system. Agent enables remote interaction with NGINX using common Linux tools and unlocks the ability to build sophisticated monitoring and control systems that can manage large collections of NGINX instances.
NGINX Agent runs as a companion process on a system running NGINX. It provides gRPC and REST interfaces for configuration management and metrics collection from the NGINX process and operating system. NGINX Agent enables remote interaction with NGINX using common Linux tools and unlocks the ability to build sophisticated monitoring and control systems that can manage large collections of NGINX instances.

![How agent works](docs/agent-flow.png "How it works")
![How NGINX Agent works](docs/agent-flow.png "How NGINX Agent works")

## Configuration Management
Agent provides an API interface for submission of updated configuration files. Upon receipt of a new file, it checks the output of `nginx -V` to determine the location of existing configurations. It then validates the new configuration with `nginx -t` before applying it via a NOHUP signal to the NGINX master process.
NGINX Agent provides an API interface for submission of updated configuration files. Upon receipt of a new file, it checks the output of `nginx -V` to determine the location of existing configurations. It then validates the new configuration with `nginx -t` before applying it via a NOHUP signal to the NGINX master process.

## Collecting Metrics
Agent interfaces with NGINX process information and parses NGINX logs to calculate and report metrics. When interfacing with NGINX Plus, Agent pulls relevant information from the NGINX Plus API. Reported metrics may be aggregated by [Prometheus](https://prometheus.io/) and visualized with tools like [Grafana](https://grafana.com/).
NGINX Agent interfaces with NGINX process information and parses NGINX logs to calculate and report metrics. When interfacing with NGINX Plus, NGINX Agent pulls relevant information from the NGINX Plus API. Reported metrics may be aggregated by [Prometheus](https://prometheus.io/) and visualized with tools like [Grafana](https://grafana.com/).

### NGINX Open Source
When running alongside an open source instance of NGINX, Agent requires that NGINX Access and Error logs are turned on and contain all default variables.
When running alongside an open source instance of NGINX, NGINX Agent requires that NGINX Access and Error logs are turned on and contain all default variables.

### NGINX Plus
For Agent to work properly with an NGINX Plus instance, the API needs to be configured in that instance's nginx.conf. See [Instance Metrics Overview](https://docs.nginx.com/nginx-management-suite/nim/about/overview-metrics/) for more details. Once NGINX Plus is configured with the `/api/` endpoint, Agent will automatically use it on startup.
For NGINX Agent to work properly with an NGINX Plus instance, the API needs to be configured in that instance's nginx.conf. See [Instance Metrics Overview](https://docs.nginx.com/nginx-management-suite/nim/about/overview-metrics/) for more details. Once NGINX Plus is configured with the `/api/` endpoint, NGINX Agent will automatically use it on startup.

## Event Notifications
Agent allows a gRPC connected control system to register a listener for a specific event. The control mechanism is then invoked when Agent sends an associated system signal. The source of a notification can be either the NGINX instance or Agent itself. Here's a list of currently supported events:
NGINX Agent allows a gRPC connected control system to register a listener for a specific event. The control mechanism is then invoked when NGINX Agent sends an associated system signal. The source of a notification can be either the NGINX instance or NGINX Agent itself. Here's a list of currently supported events:

| Event | Description |
| -------------------------------- | -------------------------------------------- |
| AGENT_START_MESSAGE | Agent process started |
| AGENT_STOP_MESSAGE | Agent process stopped |
| AGENT_START_MESSAGE | NGINX Agent process started |
| AGENT_STOP_MESSAGE | NGINX Agent process stopped |
| NGINX_FOUND_MESSAGE | NGINX master process detected on system |
| NGINX_STOP_MESSAGE | NGINX master process stopped |
| NGINX_RELOAD_SUCCESS_MESSAGE | NGINX master process reloaded successfully |
Expand All @@ -77,13 +78,13 @@ Agent allows a gRPC connected control system to register a listener for a specif

# Installation
## Installing NGINX
Agent interfaces directly with an NGINX server process installed on the same system. If you don't have it already, follow these steps to install [NGINX Open Source](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) or [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). Once installed, ensure the NGINX instance is running.
NGINX Agent interfaces directly with an NGINX server process installed on the same system. If you don't have it already, follow these steps to install [NGINX Open Source](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) or [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). Once installed, ensure the NGINX instance is running.

## Installing Go
Agent is written in Go and requires Go 1.19 or higher to be installed. You can [download Go from the official website](https://go.dev/dl/).
NGINX Agent is written in Go and requires Go 1.19 or higher to be installed. You can [download Go from the official website](https://go.dev/dl/).

## Installing Agent from Package Files
To install Agent on your system, go to [Releases](https://github.com/nginx/agent/releases) and download `nginx-agent.tar.gz`. Create a new subdirectory and extract the archive into it. Change into the subdirectory matching the package manager format appropriate for your operating system distribution.
## Installing NGINX Agent from Package Files
To install NGINX Agent on your system, go to [Releases](https://github.com/nginx/agent/releases) and download `nginx-agent.tar.gz`. Create a new subdirectory and extract the archive into it. Change into the subdirectory matching the package manager format appropriate for your operating system distribution.

Depending on OS distribution and CPU architecture type, use your system's package manager to install the package. Some examples:

Expand All @@ -110,30 +111,26 @@ sudo pkg add nginx-agent-<agent-version>
```

## Starting and Enabling Start on Boot
To start the Agent on systemd systems, run the following command:
To start the NGINX Agent on systemd systems, run the following command:
```
sudo systemctl start nginx-agent
```
To enable the Agent to start on boot, run the following command:
To enable the NGINX Agent to start on boot, run the following command:
```
sudo systemctl enable nginx-agent
```

## Logging
Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of Agent log files. We recommend adding a separate partition for `/var/log/nginx-agent`. 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.
NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of NGINX Agent log files. We recommend adding a separate partition for `/var/log/nginx-agent`. 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.

# Getting Started with Agent
Follow these steps to configure and run Agent and a mock interface ("control plane") to which the Agent will report.
# Getting Started with NGINX Agent
Follow these steps to configure and run NGINX Agent and a mock interface ("control plane") to which the NGINX Agent will report.

## Installing NGINX and Agent
Follow steps in the [Installation](#installation) section to download, install, and run NGINX and Agent.
## Installing NGINX and NGINX Agent
Follow steps in the [Installation](#installation) section to download, install, and run NGINX and NGINX Agent.

## Cloning the Agent Repository
Run the following command in your development directory to clone the Agent source code from the GitHub repository. See [Cloning a GitHub Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for additional help.

```
git clone [email protected]:nginx/agent.git
```
## Cloning 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.

## Starting the gRPC Mock Control Plane
Start the mock control plane by running the following command from the `agent` source code root directory:
Expand All @@ -143,14 +140,18 @@ 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
INFO[0000] gRPC listening at 54789 # gRPC control plane port which NGINX Agent will report to
```

## Agent Settings
If it doesn't already exist, create the `/etc/nginx-agent/nginx-agent.conf` file
## 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.
```
sudo mkdir /etc/nginx-agent
sudo cp nginx-agent.conf /etc/nginx-agent/
sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/
```
Create the `agent-dynamic.conf` file in the `/etc/nginx-agent/` directory, which is required for NGINX Agent to run.
```
sudo touch /etc/nginx-agent/agent-dynamic.conf
```

### Enabling the gRPC interface
Expand All @@ -168,7 +169,7 @@ tls:
```

### Enabling the REST interface
The Agent REST interface can be exposed by adding the following lines to the `nginx-agent.conf` file.
The NGINX Agent REST interface can be exposed by adding the following lines to the `nginx-agent.conf` file.

```yaml
api:
Expand All @@ -179,14 +180,14 @@ api:
key: "<PRIVATE-KEY>.key"
```

The mock control plane can use either gRPC or REST protocols to communicate with Agent.
The mock control plane can use either gRPC or REST protocols to communicate with NGINX Agent.

## Starting Agent
If already running, restart Agent to apply the new configuration. Alternatively, if Agent is not running, you may run it from the source code root directory.
## Starting 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 the Agent. Issue the following command from the `agent` source code root directory.
Open another terminal window and start the NGINX Agent. Issue the following command from the `agent` source code root directory.
```
make run
sudo make run

# Command Output snippet
WARN[0000] Log level is info
Expand Down Expand Up @@ -219,26 +220,22 @@ Open a web browser to view the mock control plane at [http://localhost:54790](ht
- configs/raw - shows the actual configuration as it would live on the dataplane
- metrics - shows a buffer of metrics sent to the management plane (similar to what will be sent back in the REST API)

For more Agent use-cases, refer to https://github.com/nginx/agent/tree/main/sdk/examples
For more NGINX Agent use-cases, refer to https://github.com/nginx/agent/tree/main/sdk/examples

# Development Environment Setup
## Selecting an Operating System
While most Linux or FreeBSD operating systems can be used to contribute to the Agent project, the following steps have been designed for Ubuntu. Ubuntu is packaged with most libraries required to build and run Agent, and is the recommended platform for Agent development.
While most Linux or FreeBSD operating systems can be used to contribute to the NGINX Agent project, the following steps have been designed for Ubuntu. Ubuntu is packaged with most libraries required to build and run NGINX Agent, and is the recommended platform for NGINX Agent development.

## Installing NGINX
Follow steps in the [Installation](#installation) section to download and install NGINX. Once installed ensure NGINX instance is running.

## Cloning the Agent Repository
Run the following command from your development directory to clone Agent source code from the GitHub repository. See [Cloning a GitHub Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for additional help.

```
git clone [email protected]:nginx/agent.git
```
## Cloning the NGINX Agent Repository
Follow steps in the Getting Started with NGINX Agent section to [clone the NGINX Agent Repository](#cloning-the-nginx-agent-repository)

## Installing Prerequisite Packages
Depending on the operating system distribution, it may be necessary to install the following packages in order to build Agent.
Depending on the operating system distribution, it may be necessary to install the following packages in order to build NGINX Agent.

Change to the Agent source directory:
Change to the NGINX Agent source directory:
```
cd <path_to_development_directory>/agent
```
Expand All @@ -248,35 +245,35 @@ Install Make:
sudo apt install make
```

Agent is written in Go. You may [download Go](https://go.dev/doc/install) and follow installation instructions on the same page or run:
NGINX Agent is written in Go. You may [download Go](https://go.dev/doc/install) and follow installation instructions on the same page or run:
```
sudo apt install golang-go
```

## Building Agent from Source Code
Run the following commands to build and run Agent:
## Building NGINX Agent from Source Code
Run the following commands to build and run NGINX Agent:
```
make build
sudo make run
```

# Agent Technical Specifications
# NGINX Agent Technical Specifications
## Supported Distributions
Agent can run in most environments. For a list of supported distributions, see the [NGINX Technical Specs](https://docs.nginx.com/nginx/technical-specs/#supported-distributions) guide.
NGINX Agent can run in most environments. For a list of supported distributions, see the [NGINX Technical Specs](https://docs.nginx.com/nginx/technical-specs/#supported-distributions) guide.

## Supported Deployment Environments
Agent can be deployed in the following environments:
NGINX Agent can be deployed in the following environments:

- Bare Metal
- Container
- Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure
- Virtual Machine

## Supported NGINX Versions
Agent works with all supported versions of NGINX Open Source and NGINX Plus.
NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plus.

## Sizing Recommendations
Minimum system sizing recommendations for Agent:
Minimum system sizing recommendations for NGINX Agent:

| CPU | Memory | Network | Storage |
|------------|----------|-----------|---------|
Expand Down
Binary file modified docs/agent-flow.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.