Refactor role to bring it up to par with other NGINX Ansible roles

.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,22 +6,27 @@ labels: ''
 assignees: ''
 ---
 ### Describe the bug
+
 A clear and concise description of what the bug is.
 
 ### To reproduce
+
 Steps to reproduce the behavior:
+
 1. Deploy NGINX Controller Agent role using playbook.yml
 2. View output/logs/configuration on '...'
 3. See error
 
 ### Expected behavior
+
 A clear and concise description of what you expected to happen.
 
-### Your environment:
--   Version of the NGINX Controller Agent role or specific commit
--   Version of Ansible
--   Version of Jinja2 (if you are using any templating capability)
--   Target deployment platform
+### Your environment
+
+- Version of the NGINX Controller Agent role or specific commit
+- Version of Ansible
+- Target deployment platform
 
 ### Additional context
+
 Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -6,13 +6,17 @@ labels: ''
 assignees: ''
 ---
 ### Is your feature request related to a problem? Please describe
+
 A clear and concise description of what the problem is. Ex. I'm always frustrated when ...
 
 ### Describe the solution you'd like
+
 A clear and concise description of what you want to happen.
 
 ### Describe alternatives you've considered
+
 A clear and concise description of any alternative solutions or features you've considered.
 
 ### Additional context
+
 Add any other context or screenshots about the feature request here.

.github/pull_request_template.md

@@ -1,10 +1,12 @@
 ### Proposed changes
+
 Describe the use case and detail of the change. If this PR addresses an issue on GitHub, make sure to include a link to that issue using one of the [supported keywords](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue) here in this description (not in the title of the PR).
 
 ### Checklist
+
 Before creating a PR, run through this checklist and mark each as complete.
 
--   [ ] I have read the [CONTRIBUTING](https://github.com/nginxinc/ansible-role-nginx-controller-agent/blob/main/CONTRIBUTING.md) document
--   [ ] I have added Molecule tests that prove my fix is effective or that my feature works
--   [ ] I have checked that any relevant Molecule tests pass after adding my changes
--   [ ] I have updated any relevant documentation (`defaults/main/*.yml`, `README.md` and `CHANGELOG.md`)
+- [ ] I have read the [CONTRIBUTING](https://github.com/nginxinc/ansible_role_nginx_controller_agent/blob/main/CONTRIBUTING.md) document
+- [ ] I have added Molecule tests that prove my fix is effective or that my feature works
+- [ ] I have checked that any relevant Molecule tests pass after adding my changes
+- [ ] I have updated any relevant documentation (`defaults/main/*.yml`, `README.md` and `CHANGELOG.md`)

.github/release-drafter.yml

@@ -88,12 +88,12 @@ template: |
 
   ## Install & Upgrade
 
-  *   To install the Ansible NGINX Controller Agent role on a fresh environment, run `ansible-galaxy install nginxinc.nginx_controller_agent`.
-  *   To upgrade the Ansible NGINX Controller Agent role to the latest release, run `ansible-galaxy install -f nginxinc.nginx_controller_agent`.
-  *   To install or upgrade to this specific Ansible NGINX Controller Agent role release ($RESOLVED_VERSION), run `ansible-galaxy install -f nginxinc.nginx_controller_agent,v$RESOLVED_VERSION`.
+  * To install the Ansible NGINX Controller Agent role on a fresh environment, run `ansible-galaxy install nginxinc.nginx_controller_agent`.
+  * To upgrade the Ansible NGINX Controller Agent role to the latest release, run `ansible-galaxy install -f nginxinc.nginx_controller_agent`.
+  * To install or upgrade to this specific Ansible NGINX Controller Agent role release ($RESOLVED_VERSION), run `ansible-galaxy install -f nginxinc.nginx_controller_agent,v$RESOLVED_VERSION`.
 
   ## Resources
 
-  *   Functional configuration examples (check `converge.yml` under each `molecule` scenario) -- [github.com/nginxinc/ansible-role-nginx-controller-agent/tree/$RESOLVED_VERSION/molecule](https://github.com/nginxinc/ansible-role-nginx-controller-agent/tree/$RESOLVED_VERSION/molecule).
-  *   Ansible Galaxy repository -- [galaxy.ansible.com/nginxinc/nginx_controller_agent](https://galaxy.ansible.com/nginxinc/nginx_controller_agent).
-  *   NGINX: Better with Ansible demo -- [github.com/alessfg/nginx-ansible-demo](https://github.com/alessfg/nginx-ansible-demo).
+  * Functional configuration examples (check `converge.yml` under each `molecule` scenario) -- [github.com/nginxinc/ansible_role_nginx_controller_agent/tree/$RESOLVED_VERSION/molecule](https://github.com/nginxinc/ansible_role_nginx_controller_agent/tree/$RESOLVED_VERSION/molecule).
+  * Ansible Galaxy repository -- [galaxy.ansible.com/nginxinc/nginx_controller_agent](https://galaxy.ansible.com/nginxinc/nginx_controller_agent).
+  * NGINX: Better with Ansible demo -- [github.com/alessfg/nginx-ansible-demo](https://github.com/alessfg/nginx-ansible-demo).

.github/workflows/molecule.yml

@@ -38,5 +38,5 @@ jobs:
       - name: Run Molecule tests
         run: molecule test -s ${{ matrix.scenario }}
         env:
-          PY_COLORS: "1"
-          ANSIBLE_FORCE_COLOR: "1"
+          PY_COLORS: 1
+          ANSIBLE_FORCE_COLOR: 1

CHANGELOG.md

@@ -2,11 +2,12 @@
 
 ## 0.1.0 (Unreleased)
 
-BUG FIXES:
+ENHANCEMENTS:
 
-Updated Controller agent script download URL for Controller 3.20 and beyond.
+* Refactor role to bring it up to par with other NGINX Ansible roles.
+* Implement GitHub Actions CI/CD workflow for repo.
+* Add Molecule tests for role.
 
-ENHANCEMENTS:
+BUG FIXES:
 
-*   Implement GitHub Actions CI/CD workflow for repo.
-*   Add Molecule tests for role.
+Updated Controller agent script download URL for Controller 3.20 and beyond.

CODE_OF_CONDUCT.md

@@ -68,9 +68,9 @@ members of the project's leadership.
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
 
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+<https://www.contributor-covenant.org/faq>

CONTRIBUTING.md

@@ -14,26 +14,26 @@ The following is a set of guidelines for contributing to the NGINX Controller Ag
 *   [Git Guidelines](#git-guidelines)
 *   [Ansible Guidelines](#ansible-guidelines)
 
-[Code of Conduct](https://github.com/nginxinc/ansible-role-nginx-controller-agent/blob/main/CODE_OF_CONDUCT.md)
+[Code of Conduct](https://github.com/nginxinc/ansible_role_nginx_controller_agent/blob/main/CODE_OF_CONDUCT.md)
 
 ## Ask a Question
 
 Don't know how something works? Curious if the role can achieve your desired functionality? Please open an Issue on GitHub with the label `question`.
 
 ## Getting Started
 
-Follow our [Installation Guide](https://github.com/nginxinc/ansible-role-nginx-controller-agent/blob/main/README.md#Installation) to install Ansible and Molecule and get ready to use the NGINX Controller Agent Ansible role.
+Follow our [Installation Guide](https://github.com/nginxinc/ansible_role_nginx_controller_agent/blob/main/README.md#Installation) to install Ansible and Molecule and get ready to use the NGINX Controller Agent Ansible role.
 
 ### Project Structure
 
 *   The NGINX Controller Agent Ansible role is written in `yaml` and supports NGINX Controller.
 *   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-controller-agent/blob/main/tasks/).
-    *   Variables can be found in [`defaults/main/`](https://github.com/nginxinc/ansible-role-nginx-controller-agent/blob/main/defaults/main/).
-    *   "Constant" variables can be found in [`vars/main.yml`](https://github.com/nginxinc/ansible-role-nginx-controller-agent/blob/main/vars/main.yml).
-    *   Configuration templates for NGINX can be found in [`templates/`](https://github.com/nginxinc/ansible-role-nginx-controller-agent/blob/main/templates/).
-    *   [Molecule](https://molecule.readthedocs.io/) tests can be found in [`molecule/`](https://github.com/nginxinc/ansible-role-nginx-controller-agent/blob/main/molecule/).
-    *   CI/CD is done via GitHub actions using the workflow files found in [`.github/workflows/`](https://github.com/nginxinc/ansible-role-nginx-controller-agent/blob/main/.github/workflows/).
+    *   The main code is found in [`tasks/`](https://github.com/nginxinc/ansible_role_nginx_controller_agent/blob/main/tasks/).
+    *   Variables can be found in [`defaults/main/`](https://github.com/nginxinc/ansible_role_nginx_controller_agent/blob/main/defaults/main/).
+    *   "Constant" variables can be found in [`vars/main.yml`](https://github.com/nginxinc/ansible_role_nginx_controller_agent/blob/main/vars/main.yml).
+    *   Configuration templates for NGINX can be found in [`templates/`](https://github.com/nginxinc/ansible_role_nginx_controller_agent/blob/main/templates/).
+    *   [Molecule](https://molecule.readthedocs.io/) tests can be found in [`molecule/`](https://github.com/nginxinc/ansible_role_nginx_controller_agent/blob/main/molecule/).
+    *   CI/CD is done via GitHub actions using the workflow files found in [`.github/workflows/`](https://github.com/nginxinc/ansible_role_nginx_controller_agent/blob/main/.github/workflows/).
 
 ## Contributing
 
@@ -48,7 +48,7 @@ To suggest an enhancement, please create an issue on GitHub with the label `enha
 ### Open a Pull Request
 
 *   Fork the repo, create a branch, implement your changes, add any relevant Molecule tests, submit a PR when your changes are **tested** (using Molecule) and ready for review.
-*   Fill in [our pull request template](https://github.com/nginxinc/ansible-role-nginx-controller-agent/blob/main/.github/pull_request_template.md).
+*   Fill in [our pull request template](https://github.com/nginxinc/ansible_role_nginx_controller_agent/blob/main/.github/pull_request_template.md).
 
 Note: if you’d like to implement a new feature, please consider creating a feature request issue first to start a discussion about the feature.
 

README.md

@@ -1,111 +1,144 @@
-NGINX Controller Agent
-======================
+# Ansible NGINX Controller Agent Role
 
-This Role installs, configures, and upgrades the NGINX Controller agent alongside an NGINX Plus instance in a machine.
+This role installs, configures, and upgrades the NGINX Controller agent alongside an NGINX Plus instance in a machine.
 
-Requirements
-------------
+## Requirements
 
-*   [NGINX Plus](https://www.nginx.com/products/nginx/)
-*   [NGINX Controller](https://www.nginx.com/products/nginx-controller/)
+### NGINX Controller and NGINX Plus
 
-Role Variables
---------------
+* [NGINX Plus](https://www.nginx.com/products/nginx/)
+* [NGINX Controller](https://www.nginx.com/products/nginx-controller/)
 
-### Required Variables
+### Ansible
 
-`nginx_controller_fqdn` - FQDN of the NGINX Controller instance
+* This role is developed and tested with [maintained](https://docs.ansible.com/ansible/devel/reference_appendices/release_and_maintenance.html) versions of Ansible core (above `2.11`).
+* You will need to run this role as a root user using Ansible's `become` parameter. Make sure you have set up the appropriate permissions on your target hosts.
+* Instructions on how to install Ansible can be found in the [Ansible website](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#upgrading-ansible-from-version-2-9-and-older-to-version-2-10-or-later).
 
-`nginx_controller_api_key` - The API key used to authenticate to NGINX Controller.
+### Molecule (Optional)
 
-### Optional Variables
+* Molecule is used to test the various functionalities of the role. The recommended version of Molecule to test this role is `3.3`.
+* 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._
 
-`nginx_controller_hostname` - The name of the NGINX instance as reflected in NGINX Controller. Must be unique per instance.  (currently redundant with nginx_controller_instance_name)
+## Installation
 
-`nginx_controller_location` - The location in NGINX Controller this instance will be automatically added to. Otherwise the location will be 'unspecified' in NGINX Controller.
+### Ansible Galaxy
 
-`nginx_controller_instance_name` - The name of the instance as reflected in Controller. Must be unique per instance.
+Use `ansible-galaxy install nginxinc.nginx_controller_agent` to install the latest stable release of the role on your system. Alternatively, if you have already installed the role, use `ansible-galaxy install -f nginxinc.nginx_controller_agent` to update the role to the latest release.
 
-Dependencies
-------------
+### Git
 
-Example Playbook
-----------------
+Use `git clone https://github.com/nginxinc/ansible_role_nginx_controller_agent.git` to pull the latest edge commit of the role from GitHub.
+
+## Platforms
+
+The NGINX Controller agent Ansible role supports all platforms supported by the [NGINX Controller agent](https://docs.nginx.com/nginx-controller/admin-guides/install/nginx-controller-tech-specs/):
+
+```yaml
+Amazon:
+  - 2017.09
+Amazon Linux 2:
+  - any
+CentOS:
+  - 7.4+
+Debian:
+  - stretch (9)
+  - buster (10)
+RHEL:
+  - 7.4+
+Ubuntu:
+  - bionic (18.04)
+  - focal (20.04)
+```
+
+## Role Variables
+
+| Variable | Default | Description | Required |
+| -------- | ------- | ----------- | -------- |
+| `nginx_controller_fqdn` | `""` | FQDN of the NGINX Controller instance | Yes |
+| `nginx_controller_api_key` | `""` | The API key used to authenticate to NGINX Controller | Yes |
+| `nginx_controller_location` | `"unspecified"` | The location in NGINX Controller this instance will be automatically added to | No |
+| `nginx_controller_hostname` | `""` | The unique name of the NGINX instance as reflected in NGINX Controller -- currently redundant with `nginx_controller_instance_name` | No |
+| `nginx_controller_instance_name` | `""` | The unique name of the NGINX instance as reflected in NGINX Controller -- currently redundant with `nginx_controller_hostname` | No |
+
+## Example Playbook
 
 To use this role you can create a playbook such as the following:
 
 ```yaml
 ---
-- hosts: localhost
-  gather_facts: false
+- name: Fetch NGINX Controller API Key
+  hosts: localhost
   connection: local
-
+  gather_facts: false
   vars:
     nginx_controller_user_email: "[email protected]"
     nginx_controller_user_password: "mySecurePassword"
     nginx_controller_fqdn: "controller.mydomain.com"
     nginx_controller_validate_certs: false
-
   tasks:
-  - include_role:
-      name: nginxinc.nginx_controller.nginx_controller_generate_token
-
-  - name: Get controller api key for agent registration
-    uri:
-      url: "https://{{ nginx_controller_fqdn }}/api/v1/platform/global"
-      method: "GET"
-      return_content: yes
-      status_code: 200
-      validate_certs: false
-      headers:
-        Cookie: "{{nginx_controller_auth_token}}"
-    register: ctrl_globals
-
-  - name: Copy api_key to a variable
-    set_fact:
-      api_key: "{{ctrl_globals.json.currentStatus.agentSettings.apiKey}}"
-
-- hosts: tag_new_gateway
+    - name: Fetch NGINX Controller auth token
+      include_role:
+        name: nginxinc.nginx_controller_generate_token
+
+    - name: Fetch NGINX Controller API Key for the NGINX Controller agent registration
+      uri:
+        url: "https://{{ nginx_controller_fqdn }}/api/v1/platform/global"
+        method: GET
+        return_content: yes
+        status_code: 200
+        validate_certs: false
+        headers:
+          Cookie: "{{ nginx_controller_auth_token }}"
+      register: ctrl_globals
+
+    - name: Filter API Key to a variable
+      set_fact:
+        api_key: "{{ ctrl_globals.json.currentStatus.agentSettings.apiKey }}"
+
+- name: Install NGINX Controller agent
+  hosts: tag_new_gateway
   remote_user: ubuntu
   become: true
   become_method: sudo
-  gather_facts: yes
-
   tasks:
-  - name: install minimal support for python2 for Agent install script
-    apt:
-      name: "{{ packages }}"
-      state: present
-    vars:
-      packages:
-      - python-minimal
-      - libxerces-c3.2
-
-  - name: install the agent
-    include_role:
-      name: nginxinc.nginx_controller.nginx_controller_agent
-    vars:
-      nginx_controller_api_key: "{{ hostvars['localhost']['api_key'] }}"
+    # - name: Install minimal support for python2 for Agent install script
+    #   apt:
+    #     name:
+    #       - python-minimal
+    #       - libxerces-c3.2
+
+    - name: Install the NGINX Controller agent
+      include_role:
+        name: nginxinc.nginx_controller_agent
+      vars:
+        nginx_controller_api_key: "{{ hostvars['localhost']['api_key'] }}"
 ```
 
-You can then run `ansible-playbook nginx_controller_agent.yaml` to execute the playbook.
+## Other NGINX Ansible Collections and Roles
 
-Alternatively, you can also pass/override any variables at run time using the `--extra-vars` or `-e` flag like so `ansible-playbook nginx_controller_agent.yaml -e "[email protected] nginx_controller_user_password=notsecure nginx_controller_fqdn=controller.example.local nginx_controller_validate_certs=false"`
+You can find the Ansible NGINX Core collection of roles to install and configure NGINX Open Source, NGINX Plus, and NGINX App Protect [here](https://github.com/nginxinc/ansible-collection-nginx).
 
-You can also pass/override any variables by passing a `yaml` file containing any number of variables like so `ansible-playbook nginx_controller_agent.yaml -e "@nginx_controller_agent_vars.yaml"`
+You can find the Ansible NGINX role to install NGINX OSS and NGINX Plus [here](https://github.com/nginxinc/ansible-role-nginx).
 
-License
--------
+You can find the Ansible NGINX configuration role to configure NGINX [here](https://github.com/nginxinc/ansible-role-nginx-config).
 
-[Apache License, Version 2.0](./LICENSE)
+You can find the Ansible NGINX App Protect role to install and configure NGINX App Protect WAF and NGINX App Protect DoS [here](https://github.com/nginxinc/ansible-role-nginx-app-protect).
 
-Author Information
-------------------
+You can find the Ansible NGINX Controller collection of roles to install and configure NGINX Controller [here](https://github.com/nginxinc/ansible-collection-nginx_controller).
 
-[Brian Ehlert](https://github.com/brianehlert)
+You can find the Ansible NGINX Unit role to install NGINX Unit [here](https://github.com/nginxinc/ansible-role-nginx-unit).
+
+## License
+
+[Apache License, Version 2.0](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/LICENSE)
+
+## Author Information
 
 [Alessandro Fael Garcia](https://github.com/alessfg)
 
+[Brian Ehlert](https://github.com/brianehlert)
+
 [Daniel Edgar](https://github.com/aknot242)
 
-© [NGINX, Inc.](https://www.nginx.com/) 2021
+© [F5 Networks, Inc.](https://www.f5.com/) 2020 - 2021