Add Molecule tests covering common NGINX configurations (#420)

Author: alessfg

.github/workflows/molecule.yml

@@ -44,10 +44,15 @@ jobs:
       fail-fast: false
       matrix:
         scenario:
-          - cleanup_module
+          - api
+          - cleanup_config
+          - complete
+          - complete_plus
           - default
-          - plus
-          - push
+          - push_config
+          - reverse_proxy
+          - stub_status
+          - web_server
     needs: ansible-lint
     steps:
       - name: Check out the codebase

CHANGELOG.md

@@ -8,6 +8,7 @@ BUG FIXES:
 
 CI/CD:
 
+- Add Molecule tests covering common NGINX use cases (web server, reverse proxy), enabling the NGINX stub status metrics, and NGINX Plus API and live metrics dashboard.
 - Update the platforms used in the various Molecule scenarios.
 - Use the local role name (`ansible-role-nginx-config`) instead of the fully qualified role name (`nginxinc.nginx_config`) in Molecule to ensure tests always work as intended in environments where the role has been already installed beforehand.
 

README.md

@@ -42,7 +42,7 @@ This role configures NGINX Open Source and NGINX Plus on your target host.
 
 - Molecule is used to test the various functionalities of the role. The recommended version of Molecule to test this role is `4.x`.
 - Instructions on how to install Molecule can be found in the [Molecule website](https://molecule.readthedocs.io/en/latest/installation.html). *You will also need to install the Molecule Docker driver.*
-- To run the NGINX Plus/App Protect config Molecule tests, you must copy your NGINX Plus/App Protect license to the role's [`files/license`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/files/license/) folder.
+- To run the NGINX Plus/App Protect config Molecule tests, you must copy your NGINX Plus/App Protect license to the role's [`files/license`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/files/license/) directory.
 
   You can alternatively add your NGINX Plus/App Protect repository certificate and key to the local environment. Run the following commands to export these files as base64-encoded variables and execute the Molecule tests:
 
@@ -54,6 +54,8 @@ This role configures NGINX Open Source and NGINX Plus on your target host.
 
 ## Installation
 
+This role can be installed via either Ansible Galaxy (the Ansible community marketplace) or by cloning this repo. Once installed, you will need to include the role it in your Ansible playbook using [the `roles` keyword, the `import_role` module, or the `include_role` module](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#using-roles).
+
 ### Ansible Galaxy
 
 To install the latest stable release of the role on your system, use:
@@ -62,12 +64,20 @@ To install the latest stable release of the role on your system, use:
 ansible-galaxy install nginxinc.nginx_config
 ```
 
-Alternatively, if you have already installed the role, update the role to the latest release:
+Alternatively, if you have already installed the role, you can update the role to the latest release by using:
 
 ```bash
 ansible-galaxy install -f nginxinc.nginx_config
 ```
 
+To use the role, include the following task in your playbook:
+
+```yaml
+- name: Configure NGINX
+  ansible.builtin.include_role:
+    name: nginxinc.nginx_config
+```
+
 ### Git
 
 To pull the latest edge commit of the role from GitHub, use:
@@ -76,6 +86,14 @@ To pull the latest edge commit of the role from GitHub, use:
 git clone https://github.com/nginxinc/ansible-role-nginx-config.git
 ```
 
+To use the role, include the following task in your playbook:
+
+```yaml
+- name: Configure NGINX
+  ansible.builtin.include_role:
+    name: <path/to/repo> # e.g. <roles/ansible-role-nginx-config> if you clone the repo inside your project's roles folder
+```
+
 ## Platforms
 
 The NGINX config Ansible role supports all platforms supported by [NGINX Open Source](https://nginx.org/en/linux_packages.html#mainline) and [NGINX Plus](https://www.nginx.com/products/technical-specs/).
@@ -84,7 +102,7 @@ The NGINX config Ansible role supports all platforms supported by [NGINX Open So
 
 ## Role Variables
 
-This role has multiple variables. The descriptions and defaults for all these variables can be found in the **[`defaults/main/`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/defaults/main/)** folder in the following files:
+This role has multiple variables. The descriptions and defaults for all these variables can be found in the **[`defaults/main/`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/defaults/main/)** directory in the following files:
 
 | Name | Description |
 | ---- | ----------- |
@@ -95,16 +113,21 @@ This role has multiple variables. The descriptions and defaults for all these va
 
 ## Example Playbooks
 
-Working functional playbook examples can be found in the **[`molecule/`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/)** folder in the following files:
+Working functional playbook examples can be found in the **[`molecule/`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/)** directory in the following files:
 
 | Name | Description |
 | ---- | ----------- |
-| **[`cleanup_module/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/cleanup_module/converge.yml)** | Cleanup an NGINX config and configure NGINX supported modules |
-| **[`default/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/default/converge.yml)** | Use the NGINX config templating variables to create an NGINX config |
-| **[`plus/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/plus/converge.yml)** | Use the NGINX config templating variables to create an NGINX Plus config |
-| **[`push/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/push/converge.yml)** | Push a preexisting config from your system to your NGINX instance |
-
-Do note that if you install this repository via Ansible Galaxy, you will have to replace the role variable in the sample playbooks from `ansible-role-nginx-config` to `nginxinc.nginx_config`.
+| **[`api/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/api/converge.yml)** | Configure the NGINX Plus API and live metrics dashboard |
+| **[`cleanup_config/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/cleanup_config/converge.yml)** | Cleanup an NGINX config |
+| **[`complete/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/complete/converge.yml)** | Test all NGINX directives are correctly templated |
+| **[`complete_plus/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/complete_plus/converge.yml)** | Test all NGINX Plus specific directives are correctly templated |
+| **[`default/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/default/converge.yml)** | Configure NGINX with a config as close as possible to the default config |
+| **[`push_config/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/push_config/converge.yml)** | Push a preexisting NGINX config from your system to your NGINX instance |
+| **[`reverse_proxy/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/reverse_proxy/converge.yml)** | Configure NGINX as a reverse proxy between two web servers |
+| **[`stub_status/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/stub_status/converge.yml)** | Configure the NGINX Open Source stub status metrics |
+| **[`web_server/converge.yml`](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/molecule/web_server/converge.yml)** | Configure NGINX as a web server |
+
+**Note:** If you install this repository via Ansible Galaxy, you will need to replace the `include_role` variable in the example playbooks from `ansible-role-nginx-config` to `nginxinc.nginx_config`.
 
 ## Other NGINX Ansible Collections and Roles
 

defaults/main/template.yml

@@ -21,7 +21,7 @@ nginx_config_main_template:
       #   - modules/ngx_http_js_module.so
       user:  # nginx  # Can alternatively be set to a 'username' string
         username: nginx  # Required
-        group: nginx
+        # group: nginx
       # worker_cpu_affinity:
       #   auto: true  # Optional boolean
       #   cpumask: 0101 1010  # Optional if 'auto' is set to 'true'
@@ -37,7 +37,7 @@ nginx_config_main_template:
         # - file: /var/log/nginx/error.log  # Required
         #   level: notice
       pid: /var/run/nginx.pid
-      daemon: true  # Boolean
+      # daemon: true  # Boolean
       # debug_points: abort  # Can be set to 'abort' or 'stop'
       # env:  # MALLOC_OPTIONS  # String, a list of strings, a dictionary, or a list of dictionaries. The 'variable' variable is only required when setting a 'value'.
       #   variable: PERL5LIB  # Required

molecule/api/converge.yml

@@ -0,0 +1,20 @@
+---
+- name: Converge
+  hosts: all
+  tasks:
+    - name: Configure NGINX
+      ansible.builtin.include_role:
+        name: ansible-role-nginx-config
+      vars:
+        nginx_config_debug_output: true
+
+        nginx_config_rest_api_enable: true
+        nginx_config_rest_api_template_file: http/api.conf.j2
+        nginx_config_rest_api_file_location: /etc/nginx/conf.d/api.conf
+        nginx_config_rest_api_backup: true
+        nginx_config_rest_api_port: 8080
+        nginx_config_rest_api_write: true
+        nginx_config_rest_api_access_log:
+          path: /var/log/nginx/access.log
+          format: main
+        nginx_config_rest_api_dashboard: true

molecule/cleanup_module/molecule.yml renamed to molecule/api/molecule.yml

@@ -0,0 +1,31 @@
+---
+- name: Prepare
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Create ephemeral license certificate file from b64 decoded env var
+      ansible.builtin.copy:
+        content: "{{ lookup('env', 'NGINX_CRT') | b64decode }}"
+        dest: ../common/files/license/nginx-repo.crt
+        force: false
+        mode: "0444"
+
+    - name: Create ephemeral license key file from b64 decoded env var
+      ansible.builtin.copy:
+        content: "{{ lookup('env', 'NGINX_KEY') | b64decode }}"
+        dest: ../common/files/license/nginx-repo.key
+        force: false
+        mode: "0444"
+
+- name: Install NGINX Plus
+  hosts: all
+  tasks:
+    - name: Install NGINX Plus
+      ansible.builtin.include_role:
+        name: nginxinc.nginx
+      vars:
+        nginx_type: plus
+        nginx_license:
+          certificate: ../common/files/license/nginx-repo.crt
+          key: ../common/files/license/nginx-repo.key
+        nginx_remove_license: false

molecule/api/prepare.yml

@@ -0,0 +1,20 @@
+---
+- name: Verify
+  hosts: all
+  tasks:
+    - name: Check if NGINX Plus is installed
+      ansible.builtin.package:
+        name: nginx-plus
+        state: present
+      check_mode: true
+      register: install
+      failed_when: (install is changed) or (install is failed)
+
+    - name: Check if NGINX service is running
+      ansible.builtin.service:
+        name: nginx
+        state: started
+        enabled: true
+      check_mode: true
+      register: service
+      failed_when: (service is changed) or (service is failed)

molecule/api/verify.yml

@@ -15,6 +15,3 @@
             recurse: false
         nginx_config_cleanup_files:
           - /etc/nginx/conf.d/default.conf
-
-        nginx_config_modules:
-          - modules/ngx_http_js_module.so