feat: Install NGINX Agent (#698)

Co-authored-by: Oliver O'Mahony <[email protected]>
Co-authored-by: Chris Adams <[email protected]>

Author: 3 people

.github/workflows/molecule.yml

@@ -39,15 +39,19 @@ jobs:
     runs-on: ubuntu-22.04
     needs: ansible-lint
     env:
+      AGENT_DATA_PLANE_KEY: ${{ secrets.AGENT_DATA_PLANE_KEY }}
       AMPLIFY_API_KEY: ${{ secrets.AMPLIFY_API_KEY }}
       AMPLIFY_EMAIL: ${{ secrets.AMPLIFY_EMAIL }}
       AMPLIFY_PASSWORD: ${{ secrets.AMPLIFY_PASSWORD }}
       NGINX_CRT: ${{ secrets.NGINX_CRT }}
       NGINX_KEY: ${{ secrets.NGINX_KEY }}
+      ONE_API_TOKEN: ${{ secrets.ONE_API_TOKEN }}
+      ONE_TENANT: ${{ secrets.ONE_TENANT }}
     strategy:
       fail-fast: false
       matrix:
         scenario:
+          - agent
           - amplify
           - default
           - distribution

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 FEATURES:
 
+- Implement the ability to install the NGINX Agent.
 - Add Alpine Linux 3.19 to the list of NGINX Open Source and NGINX Plus tested and supported distributions.
 - Remove Alpine Linux 3.15 from the list of NGINX Open Source and NGINX Plus tested and supported distributions.
 

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.
 
@@ -85,7 +85,7 @@ git clone https://github.com/nginxinc/ansible-role-nginx.git
 
 ## Platforms
 
-The NGINX Ansible role supports all platforms supported by [NGINX Open Source](https://nginx.org/en/linux_packages.html), [NGINX Plus](https://docs.nginx.com/nginx/technical-specs/), and the [NGINX Amplify agent](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-faq.md#21-what-operating-systems-are-supported):
+The NGINX Ansible role supports almost all platforms supported by [NGINX Open Source](https://nginx.org/en/linux_packages.html), [NGINX Plus](https://docs.nginx.com/nginx/technical-specs/), the [NGINX Agent](https://docs.nginx.com/nginx-agent/technical-specifications/), and the [NGINX Amplify agent](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-faq.md#21-what-operating-systems-are-supported):
 
 ### NGINX Open Source
 
@@ -166,6 +166,46 @@ Ubuntu:
   - jammy (22.04)
 ```
 
+### NGINX Agent
+
+```yaml
+AlmaLinux:
+  - 8
+  - 9
+Alpine:
+  - 3.16
+  - 3.17
+  - 3.18
+  - 3.19
+Amazon Linux:
+  - 2
+Debian:
+  - bullseye (11)
+  - bookwork (12)
+CentOS:
+  - 7.4+
+FreeBSD:
+  - 13
+  - 14
+Oracle Linux:
+  - 7.4+
+  - 8
+  - 9
+Red Hat:
+  - 7
+  - 8
+  - 9
+Rocky Linux:
+  - 8
+  - 9
+SUSE/SLES:
+  - 12
+  - 15
+Ubuntu:
+  - focal (20.04)
+  - jammy (22.04)
+```
+
 ### NGINX Amplify Agent
 
 ```yaml
@@ -183,7 +223,7 @@ Ubuntu:
   - jammy (22.04)
 ```
 
-**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.
+**Note:** At your own risk, you can also use this role to compile NGINX Open Source from source, install NGINX Open Source on "compatible" yet unsupported platforms, install NGINX from your respective distribution package manager, or install NGINX Open Source on BSD systems.
 
 ## Role Variables
 
@@ -192,6 +232,7 @@ This role has multiple variables. The descriptions and defaults for all these va
 | Name | Description |
 | ---- | ----------- |
 | **[`main.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/defaults/main/main.yml)** | NGINX installation variables |
+| **[`agent.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/defaults/main/agent.yml)** | NGINX Agent installation variables |
 | **[`amplify.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/defaults/main/amplify.yml)** | NGINX Amplify agent installation variables |
 | **[`bsd.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/defaults/main/bsd.yml)** | BSD installation variables |
 | **[`logrotate.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/defaults/main/logrotate.yml)** | Logrotate configuration variables |
@@ -210,6 +251,7 @@ Working functional playbook examples can be found in the **[`molecule/`](https:/
 
 | Name | Description |
 | ---- | ----------- |
+| **[`agent/converge.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/molecule/agent/converge.yml)** | Install and configure the NGINX Agent to connect to the NGINX One SaaS control plane on F5 Distributed Cloud |
 | **[`amplify/converge.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/molecule/amplify/converge.yml)** | Install and configure the NGINX Amplify agent |
 | **[`default/converge.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/molecule/default/converge.yml)** | Install a specific version of NGINX, install various NGINX supported modules, tweak systemd and set up logrotate |
 | **[`distribution/converge.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/molecule/distribution/converge.yml)** | Install NGINX from the distribution's package repository instead of NGINX's package repository |

defaults/main/agent.yml

@@ -0,0 +1,19 @@
+---
+# Install NGINX Agent.
+# Requires access to either the NGINX stub_status or the NGINX Plus REST API.
+nginx_agent_enable: false
+
+# Specify the NGINX Agent data plane key/token.
+# This is required to authenticate the NGINX Agent with the NGINX One SaaS control plane available in F5 Distributed Cloud.
+# Default is null.
+nginx_agent_data_plane_key: null
+
+# Specify the control plane server host and port.
+# Default is the NGINX One SaaS control plane available in F5 Distributed Cloud.
+nginx_agent_server_host: agent.connect.nginx.com
+nginx_agent_server_port: 443
+
+# Enable TLS communication between data plane and control plane
+# Default is true.
+nginx_agent_tls_enable: true
+nginx_agent_tls_skip_verify: false

defaults/main/amplify.yml

@@ -1,7 +1,7 @@
 ---
 # Install NGINX Amplify.
-# Use your NGINX Amplify API key.
 # Requires access to either the NGINX stub_status or the NGINX Plus REST API.
+# Use your NGINX Amplify API key.
 # Default is null.
 nginx_amplify_enable: false
 nginx_amplify_api_key: null

handlers/main.yml

@@ -41,6 +41,13 @@
   ansible.builtin.service:
     name: amplify-agent
     state: started
+    enabled: true
+
+- name: (Handler) Start NGINX Agent
+  ansible.builtin.service:
+    name: nginx-agent
+    state: started
+    enabled: true
 
 - name: (Handler) Start logrotate
   ansible.builtin.command:

molecule/agent/cleanup.yml

@@ -0,0 +1,44 @@
+---
+- name: Cleanup
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Cleanup NGINX Agent instances
+      block:
+        - name: Wait for containers to be up
+          ansible.builtin.wait_for_connection:
+            delay: 1
+            timeout: 2
+          ignore_errors: true
+          register: container
+
+        - name: Containers are not up, quit from here
+          ansible.builtin.fail:
+          when: container['failed'] | bool
+
+        - name: Gather facts
+          ansible.builtin.setup:
+            gather_subset:
+              - "!all"
+              - "!any"
+              - distribution
+
+        - name: Get list of NGINX One dangling instance IDs
+          ansible.builtin.uri:
+            url: https://{{ lookup('env', 'ONE_TENANT') }}.console.ves.volterra.io/api/nginx/one/namespaces/default/instances?paginated=false&filter_fields=hostname&filter_ops=IN&filter_values=almalinux-8|almalinux-9|alpine-3.16|alpine-3.17|alpine-3.18|alpine-3.19|amazonlinux-2|centos-7|debian-bullseye|debian-bookworm|oraclelinux-7|oraclelinux-8|oraclelinux-9|rhel-7|rhel-8|rhel-9|rockylinux-8|rockylinux-9|sles-15|ubuntu-focal|ubuntu-jammy
+            method: GET
+            headers:
+              Authorization: APIToken {{ lookup('env', 'ONE_API_TOKEN') }}
+          register: get_ids
+
+        - name: Remove dangling instances from NGINX One
+          ansible.builtin.uri:
+            url: https://{{ lookup('env', 'ONE_TENANT') }}.console.ves.volterra.io/api/nginx/one/namespaces/default/instances/{{ item }}
+            method: DELETE
+            status_code: 204
+            headers:
+              Authorization: APIToken {{ lookup('env', 'ONE_API_TOKEN') }}
+          loop: "{{ get_ids['json']['items'] | map(attribute='object_id') | list }}"
+      rescue:
+        - name: It's ok we're at startup
+          ansible.builtin.meta: noop

molecule/agent/converge.yml

@@ -0,0 +1,10 @@
+---
+- name: Converge
+  hosts: all
+  tasks:
+    - name: Install NGINX Agent
+      ansible.builtin.include_role:
+        name: ansible-role-nginx
+      vars:
+        nginx_agent_enable: true
+        nginx_agent_data_plane_key: "{{ lookup('env', 'AGENT_DATA_PLANE_KEY') }}"