docs: Update README

Author: alessfg

.github/ISSUE_TEMPLATE/bug_report.md

@@ -5,7 +5,7 @@ title: ""
 labels: ""
 assignees: ""
 ---
-> [!WARNING]
+> [!CAUTION]
 > Remember to redact any sensitive information such as authentication credentials or license keys.
 
 ### Describe the bug

.github/workflows/galaxy.yml

@@ -19,7 +19,7 @@ jobs:
           python-version: 3.x
 
       - name: Install Ansible core
-        run: pip3 install -r .github/workflows/requirements/requirements_galaxy.txt
+        run: pip3 install -r .github/workflows/requirements/requirements_ansible.txt
 
       - name: Import role releases to Ansible Galaxy
         run: ansible-galaxy role import --api-key ${{ secrets.GALAXY_API_KEY }} $(echo ${{ github.repository }} | cut -d/ -f1) $(echo ${{ github.repository }} | cut -d/ -f2)

.github/workflows/molecule.yml

@@ -27,7 +27,7 @@ jobs:
         run: pip3 install -r .github/workflows/requirements/requirements_ansible_lint.txt
 
       - name: Install Ansible core collection dependencies
-        run: ansible-galaxy install -r .github/workflows/requirements/requirements_ansible.yml
+        run: ansible-galaxy install -r .github/workflows/requirements/requirements_collections.yml
 
       - name: Run Ansible Lint
         run: ansible-lint --force-color
@@ -81,7 +81,7 @@ jobs:
 
       - name: Install Ansible core collection dependencies
         if: ${{ !(contains(matrix.scenario, 'plus')) || (env.NGINX_CRT != 0 && env.NGINX_KEY != 0) }}
-        run: ansible-galaxy install -r .github/workflows/requirements/requirements_ansible.yml
+        run: ansible-galaxy install -r .github/workflows/requirements/requirements_collections.yml
 
       - name: Run Molecule tests
         if: ${{ !(contains(matrix.scenario, 'plus')) || (env.NGINX_CRT != 0 && env.NGINX_KEY != 0) }}

.github/workflows/requirements/requirements_galaxy.txt renamed to .github/workflows/requirements/requirements_ansible.txt

@@ -1 +1,2 @@
 ansible-core==2.16.6
+jinja2==3.1.4

.github/workflows/requirements/requirements_ansible.yml renamed to .github/workflows/requirements/requirements_collections.yml

@@ -14,6 +14,7 @@ FEATURES:
 DOCUMENTATION:
 
 - Update community docs per the latest [NGINX template repository](https://github.com/nginxinc/template-repository) guidelines.
+- Update and tweak the README.
 
 CI/CD:
 

CHANGELOG.md

@@ -45,7 +45,8 @@ To suggest a feature or enhancement, please create an issue on GitHub with the l
 - Fork the repo, create a branch, implement your changes, add any relevant tests, and submit a PR when your changes are **tested** (using Molecule) and ready for review.
 - Fill in the [PR template](/.github/pull_request_template.md).
 
-**Note:** If you'd like to implement a new feature, please consider creating a [feature request issue](/.github/feature_request_template.md) first to start a discussion about the feature.
+> [!NOTE]
+> If you'd like to implement a new feature, please consider creating a [feature request issue](/.github/feature_request_template.md) first to start a discussion about the feature.
 
 #### F5 Contributor License Agreement (CLA)
 

CONTRIBUTING.md

@@ -11,17 +11,36 @@
 
 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.
+> [!IMPORTANT]
+> This role is still in active development. There may be unidentified issues and the role variables may change as development continues.
 
-## Requirements
+## Role Requirements
 
-### NGINX Plus (Optional)
+### NGINX
 
-If you wish to install NGINX Plus using this role, you will need to obtain an NGINX Plus license beforehand. *You do not need to do anything beforehand if you want to install NGINX OSS.*
+Depending on your target NGINX use case, you might need to obtain some data before being able to use the role.
+
+#### NGINX Open Source (NGINX OSS)
+
+You do not need to do anything beforehand if you want to install NGINX OSS.
+
+#### NGINX Plus
+
+If you wish to install NGINX Plus using this role, you will need to obtain an NGINX Plus license beforehand.
+
+#### NGINX Agent
+
+If you wish to install and configure the NGINX Agent, you will need: to have previously set up a compatible control plane. Check out the [NGINX Agent docs](https://docs.nginx.com/nginx-agent/overview/) for more info.
+
+In addition, if you wish to connect the NGINX Agent to the NGINX One SaaS control plane available in the F5 Distributed Cloud, you will also need the data plane token provided by the NGINX One SaaS control plane.
+
+#### NGINX Amplify
+
+If you wish to install the NGINX Amplify agent, you will need the API key provided within the NGINX Amplify SaaS console.
 
 ### Ansible
 
-- 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.12`).
+- This role is developed and tested with [maintained](https://docs.ansible.com/ansible/devel/reference_appendices/release_and_maintenance.html) versions of Ansible core and Python.
 - When using Ansible core, you will also need to install the following collections:
 
     ```yaml
@@ -37,20 +56,49 @@ If you wish to install NGINX Plus using this role, you will need to obtain an NG
         version: 3.10.3
     ```
 
-    **Note:** You can alternatively install the Ansible community distribution (what is known as the "old" Ansible) if you don't want to manage individual collections.
+    > [!TIP]
+    > You can alternatively install the Ansible community distribution (what is known as the "old" Ansible) if you don't want to manage individual collections.
 - 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).
 
-### Jinja2
+#### Jinja2
 
 - This role uses Jinja2 templates. Ansible core installs Jinja2 by default, but depending on your install and/or upgrade path, you might be running an outdated version of Jinja2. The minimum version of Jinja2 required for the role to properly function is `3.1`.
 - Instructions on how to install Jinja2 can be found in the [Jinja2 website](https://jinja.palletsprojects.com/en/3.1.x/intro/#installation).
 
-### Molecule (Optional)
+Alternatively, you can install `ansible-core`, a supported version of Jinja2, and the aforementioned collections by running the following three commands on your Ansible host:
+
+```bash
+pip install -r https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_ansible.txt
+curl -O https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_collections.yml
+ansible-galaxy install -r requirements_collections.yml
+```
+
+### Testing suite (Optional)
+
+If you want to contribute to this role, you will also need to install Ansible Lint and Molecule.
 
-- 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 Molecule tests, you must copy your NGINX Plus license to the role's [`files/license`](https://github.com/nginxinc/ansible-role-nginx/blob/main/files/license/) directory.
+#### Ansible Lint (Optional)
+
+- Ansible Lint is used to lint the role for both Ansible best practices and potential Ansible/YAML issues.
+- Instructions on how to install Ansible Lint can be found in the [Ansible Lint website](https://ansible.readthedocs.io/projects/lint/installing/).
+- Once installed, using Ansible Lint is as easy as running:
+
+  ```bash
+  ansible-lint
+  ```
+
+Alternatively, you can install Ansible Lint by running the following command on your Ansible host:
+
+```bash
+pip install -r https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_ansible_lint.txt
+```
+
+#### Molecule (Optional)
+
+- Molecule is used to test the various functionalities of the role.
+- 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 plugins package and the Docker Python SDK.*
+- To run any of the NGINX Plus Molecule tests, you must first copy your NGINX Plus license to the role's [`files/license`](https://github.com/nginxinc/ansible-role-nginx/blob/main/files/license/) directory.
 
   You can alternatively add your NGINX Plus 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:
 
@@ -60,9 +108,15 @@ If you wish to install NGINX Plus using this role, you will need to obtain an NG
   molecule test -s plus
   ```
 
-## Installation
+Alternatively, you can install Molecule and the aforementioned Molecule plugins and Docker Python SDK packages by running the following command on your Ansible host:
+
+```bash
+pip install -r https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_molecule.txt
+```
+
+## Role 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).
+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 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
 
@@ -234,7 +288,8 @@ Ubuntu:
   - jammy (22.04)
 ```
 
-**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.
+> [!WARNing]
+> 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
 
@@ -277,7 +332,8 @@ Working functional playbook examples can be found in the **[`molecule/`](https:/
 | **[`upgrade-plus/converge.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/molecule/upgrade-plus/converge.yml)** | Upgrade NGINX Plus |
 | **[`version/converge.yml`](https://github.com/nginxinc/ansible-role-nginx/blob/main/molecule/version/converge.yml)** | Install a specific version of NGINX and various NGINX modules |
 
-**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` to `nginxinc.nginx`.
+> [!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` to `nginxinc.nginx`.
 
 ## Other NGINX Ansible Collections and Roles