Skip to content

Commit e26d32e

Browse files
nginx-seanmoloneynginx-seanmoloney
committed
Update README
1 parent 93c4603 commit e26d32e

File tree

1 file changed

+1
-212
lines changed

1 file changed

+1
-212
lines changed

‎README.md‎

Lines changed: 1 addition & 212 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,12 @@
22
![GitHub Release](https://img.shields.io/github/v/release/nginx/agent)
33
![GitHub License](https://img.shields.io/github/license/nginx/agent)
44
![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)
5-
[![Slack](https://img.shields.io/badge/slack-join%20us-brightgreen.svg?logo=slack)](https://nginxcommunity.slack.com/channels/nginx-agent)
65

76
![NGINX Agent Banner](docs/agent-banner.png "NGINX Agent Banner")
87

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

1412
![Grafana dashboard showing NGINX Agent reported metrics](docs/grafana-dashboard-example.png "Grafana dashboard showing NGINX Agent reported metrics")
1513
[Grafana](https://grafana.com/) dashboard showing metrics reported by NGINX Agent
@@ -18,7 +16,6 @@ NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus insta
1816
- [How it Works](#how-it-works)
1917
- [Configuration Management](#configuration-management)
2018
- [Collecting Metrics](#collecting-metrics)
21-
- [Event Notifications](#event-notifications)
2219
- [Installation](#installation)
2320
- [Installing NGINX](#installing-nginx)
2421
- [Installing NGINX Agent from Package Files](#installing-nginx-agent-from-package-files)
@@ -68,24 +65,6 @@ When running alongside an open source instance of NGINX, NGINX Agent requires th
6865
### NGINX Plus
6966
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-instance-manager/monitoring/overview-metrics/) for more details. Once NGINX Plus is configured with the `/api/` endpoint, NGINX Agent will automatically use it on startup.
7067

71-
## Event Notifications
72-
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:
73-
74-
| Event | Description |
75-
| -------------------------------- | -------------------------------------------- |
76-
| AGENT_START_MESSAGE | NGINX Agent process started |
77-
| AGENT_STOP_MESSAGE | NGINX Agent process stopped |
78-
| NGINX_FOUND_MESSAGE | NGINX master process detected on system |
79-
| NGINX_STOP_MESSAGE | NGINX master process stopped |
80-
| NGINX_RELOAD_SUCCESS_MESSAGE | NGINX master process reloaded successfully |
81-
| NGINX_RELOAD_FAILED_MESSAGE | NGINX master process failed to reload |
82-
| NGINX_WORKER_START_MESSAGE | New NGINX worker process started |
83-
| NGINX_WORKER_STOP_MESSAGE | NGINX worker process stopped |
84-
| CONFIG_APPLY_SUCCESS_MESSAGE | Successfully applied new NGINX configuration |
85-
| CONFIG_APPLY_FAILURE_MESSAGE | Failed to apply new NGINX configuration |
86-
| CONFIG_ROLLBACK_SUCCESS_MESSAGE | Successfully rolled back NGINX configuration |
87-
| CONFIG_ROLLBACK_FAILURE_MESSAGE | Failed to roll back NGINX configuration |
88-
8968
# Installation
9069
## Installing NGINX
9170
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.
@@ -168,196 +147,6 @@ If you need to make changes to the default configuration you can update the file
168147

169148
For more detail on logrotate configuration see [Logrotate Configuration Options](https://linux.die.net/man/8/logrotate)
170149

171-
## Building Docker Image
172-
To build an image that contains the latest NGINX Agent, the latest mainline version of NGINX OSS on latest Alpine run the following command:
173-
174-
```make
175-
make official-oss-image
176-
```
177-
178-
To build an image that contains the latest NGINX Agent, the latest stable version of NGINX OSS on latest Alpine run the following command:
179-
180-
```make
181-
make official-oss-stable-image
182-
```
183-
184-
For more information on how to run NGINX Agent containers and how build an image that uses NGINX Plus instead of NGINX OSS see [Docker Images](https://docs.nginx.com/nginx-agent/installation-upgrade/container-environments/docker-images/)
185-
186-
# Getting Started with NGINX Agent
187-
Follow these steps to configure and run NGINX Agent and a mock interface ("control plane") to which the NGINX Agent will report.
188-
189-
## Installing NGINX
190-
Follow steps in the [Installation](#installation) section to download, install, and run NGINX.
191-
192-
## Cloning the NGINX Agent Repository
193-
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.
194-
195-
## Installing Go
196-
NGINX Agent and the Mock Control Plane are written in Go. Go 1.23 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/).
197-
198-
## Starting the gRPC Mock Control Plane
199-
Start the mock control plane by running the following command from the `agent` source code root directory:
200-
201-
```
202-
go run sdk/examples/server.go
203-
204-
# Command Output
205-
INFO[0000] http listening at 54790 # mock control plane port
206-
INFO[0000] gRPC listening at 54789 # gRPC control plane port which NGINX Agent will report to
207-
```
208-
209-
## NGINX Agent Settings
210-
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.
211-
```
212-
sudo mkdir /etc/nginx-agent
213-
sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/
214-
```
215-
Create the `agent-dynamic.conf` file in the `/etc/nginx-agent/` directory, which is required for NGINX Agent to run.
216-
```
217-
sudo touch /var/lib/nginx-agent/agent-dynamic.conf
218-
```
219-
220-
### Enabling the gRPC interface
221-
Add the the following settings to `/etc/nginx-agent/nginx-agent.conf`:
222-
223-
```yaml
224-
server:
225-
host: 127.0.0.1 # mock control plane host
226-
grpcPort: 54789 # mock control plane gRPC port
227-
228-
# gRPC TLS options - DISABLING TLS IS NOT RECOMMENDED FOR PRODUCTION
229-
tls:
230-
enable: false
231-
skip_verify: true
232-
```
233-
234-
For more information, see [Agent Protocol Definitions and Documentation](https://github.com/nginx/agent/tree/main/docs/proto/README.md)
235-
236-
### Enabling the REST interface
237-
The NGINX Agent REST interface can be exposed by validating the following lines in the `/etc/nginx-agent/nginx-agent.conf` file are present:
238-
239-
```yaml
240-
api:
241-
# Set API address to allow remote management
242-
host: 127.0.0.1
243-
# Set this value to a secure port number to prevent information leaks
244-
port: 8038
245-
246-
# REST TLS parameters
247-
cert: "<TLS-CERTIFICATE>.crt"
248-
key: "<PRIVATE-KEY>.key"
249-
```
250-
251-
The mock control plane can use either gRPC or REST protocols to communicate with NGINX Agent.
252-
253-
### Launching Swagger UI
254-
Swagger UI requires goswagger be installed. See [instructions for installing goswagger](https://goswagger.io/go-swagger/install/) for additional help.
255-
256-
To launch the Swagger UI for the REST interface run the following command
257-
258-
```
259-
make launch-swagger-ui
260-
```
261-
262-
Open a web browser to view the Swagger UI at http://localhost:8082/docs.
263-
264-
## Extensions
265-
An extension is a piece of code, not critical to the main functionality that the NGINX agent is responsible for. This generally falls outside the remit of managing NGINX Configuration and reporting NGINX metrics.
266-
267-
To enable an extension, it must be added to the extensions list in the `/etc/nginx-agent/nginx-agent.conf`.
268-
Here is an example of enabling the advanced metrics extension:
269-
270-
```yaml
271-
extensions:
272-
- advanced-metrics
273-
```
274-
275-
## Starting NGINX Agent
276-
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.
277-
278-
Open another terminal window and start the NGINX Agent. Issue the following command from the `agent` source code root directory.
279-
```
280-
sudo make run
281-
282-
# Command Output snippet
283-
WARN[0000] Log level is info
284-
INFO[0000] setting displayName to XXX
285-
INFO[0000] NGINX Agent at with pid 12345, clientID=XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX name=XXX
286-
INFO[0000] NginxBinary initializing
287-
INFO[0000] Commander initializing
288-
INFO[0000] Comms initializing
289-
INFO[0000] OneTimeRegistration initializing
290-
INFO[0000] Registering XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX
291-
INFO[0000] Metrics initializing
292-
INFO[0000] MetricsThrottle initializing
293-
INFO[0000] DataPlaneStatus initializing
294-
INFO[0000] MetricsThrottle waiting for report ready
295-
INFO[0000] Metrics waiting for handshake to be completed
296-
INFO[0000] ProcessWatcher initializing
297-
INFO[0000] Extensions initializing
298-
INFO[0000] FileWatcher initializing
299-
INFO[0000] FileWatchThrottle initializing
300-
INFO[0001] Events initializing
301-
INFO[0001] OneTimeRegistration completed
302-
```
303-
304-
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:
305-
306-
- registered - shows registration information of the dataplane
307-
- nginxes - lists the NGINX instances on the dataplane
308-
- configs - shows the protobuf payload for NGINX configuration sent to the management plane
309-
- configs/chunked - shows the split up payloads sent to the management plane
310-
- configs/raw - shows the actual configuration as it would live on the dataplane
311-
- metrics - shows a buffer of metrics sent to the management plane (similar to what will be sent back in the REST API)
312-
313-
For more NGINX Agent use-cases, refer to https://github.com/nginx/agent/tree/main/sdk/examples
314-
315-
# Development Environment Setup
316-
## Selecting an Operating System
317-
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.
318-
319-
## Installing NGINX
320-
Follow steps in the [Installation](#installation) section to download and install NGINX. Once installed ensure NGINX instance is running.
321-
322-
## Cloning the NGINX Agent Repository
323-
Follow steps in the Getting Started with NGINX Agent section to [clone the NGINX Agent Repository](#cloning-the-nginx-agent-repository)
324-
325-
## Installing Prerequisite Packages
326-
Depending on the operating system distribution, it may be necessary to install the following packages in order to build NGINX Agent.
327-
328-
Change to the NGINX Agent source directory:
329-
```
330-
cd <path_to_development_directory>/agent
331-
```
332-
333-
Install Make:
334-
```
335-
sudo apt install make
336-
```
337-
338-
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:
339-
```
340-
sudo apt install golang-go
341-
```
342-
343-
Install Protoc:
344-
```
345-
sudo apt install -y protobuf-compiler
346-
```
347-
348-
Install NGINX Agent tools and dependencies:
349-
350-
Before starting development on the NGINX Agent, it is important to download and install the necessary tool and dependencies required by the NGINX Agent. You can do this by running the following `make` command:
351-
```
352-
make install-tools
353-
```
354-
355-
## Building NGINX Agent from Source Code
356-
Run the following commands to build and run NGINX Agent:
357-
```
358-
make build
359-
sudo make run
360-
```
361150

362151
# NGINX Agent Technical Specifications
363152
## Supported Distributions
@@ -382,7 +171,7 @@ Minimum system sizing recommendations for NGINX Agent:
382171
| 1 CPU core | 1 GB RAM | 1 GbE NIC | 20 GB |
383172

384173
# Community
385-
- Our [Slack channel #nginx-agent](https://nginxcommunity.slack.com/), is the go-to place to start asking questions and sharing your thoughts.
174+
- Our [NGINX Community](https://community.nginx.org/), is the go-to place to start asking questions and sharing your thoughts.
386175

387176
- Our [GitHub issues page](https://github.com/nginx/agent/issues) offers space for a more technical discussion at your own pace.
388177

0 commit comments

Comments
 (0)