Install NGINX Agent

CONTRIBUTING.md

@@ -27,7 +27,7 @@ Follow our [Installation Guide](https://github.com/nginxinc/ansible-role-nginx/b
 
 ### Project Structure
 
-- The NGINX Ansible role is written in `yaml` and supports NGINX Open Source, NGINX Plus, and NGINX Amplify.
+- The NGINX Ansible role is written in `yaml` and supports NGINX Open Source, NGINX Plus, NGINX Agent and NGINX Amplify.
 - The project follows the standard [Ansible role directory structure](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html):
   - The main code is found in [`tasks/`](https://github.com/nginxinc/ansible-role-nginx/blob/main/tasks/).
   - Variables can be found in [`defaults/main/`](https://github.com/nginxinc/ansible-role-nginx/blob/main/defaults/main/).

README.md

@@ -8,7 +8,7 @@
 
 # Ansible NGINX Role
 
-This role installs NGINX Open Source, NGINX Plus, or the NGINX Amplify agent on your target host.
+This role installs NGINX Open Source, NGINX Plus, NGINX Agent or the NGINX Amplify agent on your target host.
 
 **Note:** This role is still in active development. There may be unidentified issues and the role variables may change as development continues.
 
@@ -183,6 +183,48 @@ Ubuntu:
   - jammy (22.04)
 ```
 
+### NGINX Agent
+
+```yaml
+AlmaLinux:
+  - 8
+  - 9
+Alpine:
+  - 3.13
+  - 3.14
+  - 3.15
+  - 3.16
+  - 3.17
+Amazon Linux 2:
+  - any
+Debian:
+  - buster (10)
+  - bullseye (11)
+CentOS:
+  - 7.4+
+FreeBSD:
+  - 12.1+
+  - 13
+Oracle Linux:
+  - 7.4+
+  - 8
+  - 9
+Red Hat:
+  - 7
+  - 8
+  - 9
+Rocky Linux:
+  - 8
+  - 9
+SUSE/SLES:
+  - 12
+  - 15
+Ubuntu:
+  - bionic
+  - focal
+  - jammy
+```
+
 **Note:** You can also use this role to compile NGINX Open Source from source, install NGINX Open Source on compatible yet unsupported platforms, or install NGINX Open Source on BSD systems at your own risk.
 
 ## Role Variables

defaults/main/agent.yml

@@ -0,0 +1,22 @@
+---
+# Install NGINX Agent.
+# Requires access to either the NGINX stub_status or the NGINX Plus REST API.
+# Default is null.
+nginx_agent_enable: false
+nginx_agent_repo: packages.nginx.org
+
+# Specify the grpc server
+nms_server_host: null # host of the control plane
+nms_server_port: 443 # port of the control plane
+
+# Enable tls in the nginx-agent setup for grpc
+# Default to enable to connect with tls connection but without client cert for mtls
+nms_tls_enable: true
+nms_tls_skip_verify: true
+
+# Path to ca certificate file used for server cert validation
+nms_tls_ca: ""
+
+# Path to cert and key files for mTLS
+nms_tls_cert: ""
+nms_tls_key: ""

handlers/main.yml

@@ -42,6 +42,12 @@
     name: amplify-agent
     state: started
 
+- name: (Handler) Start/reloaded NGINX Agent
+  ansible.builtin.service:
+    name: nginx-agent
+    state: restarted
+    enabled: true
+
 - name: (Handler) Start logrotate
   ansible.builtin.command:
     cmd: logrotate -f /etc/logrotate.d/nginx

tasks/agent/config-nms.yml

@@ -0,0 +1,25 @@
+---
+
+- name: Add NGINX Management Suite config to NGINX Agent config
+  ansible.builtin.blockinfile:
+    backup: true
+    mode: "0644"
+    path: /etc/nginx-agent/nginx-agent.conf
+    block: |
+      # specify the server grpc port to connect to
+      server:
+        # host of the control plane
+        host: {{ nms_server_host }}
+        grpcPort: {{ nms_server_port }}
+
+      # tls options
+      tls:
+        # enable tls in the nginx-agent setup for grpcs
+        # default to enable to connect with tls connection but without client cert for mtls
+        enable: {{ nms_tls_enable | lower }}
+        skip_verify: {{ nms_tls_skip_verify | lower }}
+        # path to ca certificate file used for server cert validation
+        ca: {{ nms_tls_ca }}
+        # path to cert and key files for mTLS
+        cert: {{ nms_tls_cert }}
+        key: {{ nms_tls_key }}

tasks/agent/install-agent.yml

@@ -0,0 +1,14 @@
+---
+- name: Configure NGINX Agent repository
+  ansible.builtin.include_tasks: "{{ role_path }}/tasks/agent/setup-{{ ansible_facts['os_family'] | lower }}.yml"
+  when: ansible_facts['os_family'] in ['Debian', 'RedHat']
+
+- name: Install NGINX Agent
+  ansible.builtin.package:
+    name: nginx-agent
+    state: present
+  notify: (Handler) Start/reloaded NGINX Agent
+
+- name: Configure NGINX Agent with NGINX Management Suite
+  ansible.builtin.include_tasks: "{{ role_path }}/tasks/agent/config-nms.yml"
+  when: nms_server_host is defined

tasks/agent/setup-debian.yml

@@ -0,0 +1,7 @@
+---
+- name: (Debian/Ubuntu) Add NGINX Agent repository
+  ansible.builtin.apt_repository:
+    filename: nginx-agent
+    repo: deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://{{ nginx_agent_repo }}/nginx-agent/{{ ansible_facts['distribution'] | lower }} {{ ansible_facts['distribution_release'] | lower}} agent
+    update_cache: true
+    mode: "0644"

tasks/agent/setup-redhat.yml

@@ -0,0 +1,12 @@
+---
+- name: (RHEL/CentOS/Rocky Linux/AlmaLinux/Oracle Linux) Add NGINX Agent repository
+  ansible.builtin.yum_repository:
+    name: nginx-agent
+    file: nginx-agent
+    baseurl: https://{{ nginx_agent_repo }}/nginx-agent/{{ (ansible_facts['distribution'] == 'Amazon') | ternary('amzn', 'centos') }}/$releasever/$basearch/
+    description: NGINX Agent
+    enabled: true
+    gpgcheck: true
+    gpgkey: https://nginx.org/keys/nginx_signing.key
+    module_hotfixes: true
+    mode: "0644"

tasks/main.yml

@@ -78,3 +78,9 @@
   ansible.builtin.include_tasks: "{{ role_path }}/tasks/amplify/install-amplify.yml"
   when: nginx_amplify_enable | bool
   tags: nginx_install_amplify
+
+- name: Install NGINX Agent
+  ansible.builtin.include_tasks: "{{ role_path }}/tasks/agent/install-agent.yml"
+  when:
+    - nginx_agent_enable | bool
+  tags: nginx_install_agent