Skip to content

Commit b63f4a8

Browse files
committed
docs: Tweak README
1 parent 589af89 commit b63f4a8

File tree

1 file changed

+35
-27
lines changed

1 file changed

+35
-27
lines changed

README.md

Lines changed: 35 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ This role installs NGINX Open Source, NGINX Plus, NGINX Agent or the NGINX Ampli
1818

1919
### NGINX
2020

21-
Depending on your target NGINX use case, you might need to obtain some data before being able to use the role.
21+
Depending on your target NGINX use case, you might need to obtain a license or API key/token before being able to use the role:
2222

2323
#### NGINX Open Source (NGINX OSS)
2424

@@ -40,40 +40,48 @@ If you wish to install the NGINX Amplify agent, you will need the API key provid
4040

4141
### Ansible
4242

43+
#### Ansible core
44+
4345
- 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.
4446
- When using Ansible core, you will also need to install the following collections:
4547

46-
```yaml
47-
---
48-
collections:
49-
- name: ansible.posix
50-
version: 1.5.4
51-
- name: community.general
52-
version: 9.0.1
53-
- name: community.crypto # Only required if you plan to install NGINX Plus
54-
version: 2.20.0
55-
- name: community.docker # Only required if you plan to use Molecule (see below)
56-
version: 3.10.3
57-
```
58-
59-
> [!TIP]
60-
> You can alternatively install the Ansible community distribution (what is known as the "old" Ansible) if you don't want to manage individual collections.
48+
```yaml
49+
---
50+
collections:
51+
- name: ansible.posix
52+
version: 1.5.4
53+
- name: community.general
54+
version: 9.0.1
55+
- name: community.crypto # Only required if you plan to install NGINX Plus
56+
version: 2.20.0
57+
- name: community.docker # Only required if you plan to use Molecule (see below)
58+
version: 3.10.3
59+
```
60+
6161
- 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.
6262
- 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).
6363

64+
> [!TIP]
65+
> You can alternatively install the [Ansible community distribution](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#selecting-an-ansible-package-and-version-to-install) (what is still known Ansible -- instead of Ansible core) if you don't want to manage individual collections. Do note that there might be potential issues when using Ansible instead of Ansible core, as the former is not tested as part of this role's CI/CD pipeline.
66+
6467
#### Jinja2
6568

6669
- 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`.
6770
- Instructions on how to install Jinja2 can be found in the [Jinja2 website](https://jinja.palletsprojects.com/en/3.1.x/intro/#installation).
6871

69-
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:
72+
#### Installation
73+
74+
For ease of use, you can install and/or upgrade Ansible core, Jinja2, and the aforementioned Ansible collections by running the following four commands on your Ansible host:
7075

7176
```bash
72-
pip install -r https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_ansible.txt
77+
pip install --upgrade -r https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_ansible.txt
7378
curl -O https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_collections.yml
74-
ansible-galaxy install -r requirements_collections.yml
79+
ansible-galaxy install --force -r requirements_collections.yml
80+
rm -f requirements_collections.yml
7581
```
7682

83+
This will also ensure you are deploying/running this role with a fully tested version of the aforementioned packages/collections.
84+
7785
### Testing suite (Optional)
7886

7987
If you want to contribute to this role, you will also need to install Ansible Lint and Molecule.
@@ -88,11 +96,11 @@ If you want to contribute to this role, you will also need to install Ansible Li
8896
ansible-lint
8997
```
9098

91-
Alternatively, you can install Ansible Lint by running the following command on your Ansible host:
99+
- For ease of use, you can install and/or upgrade Ansible Lint by running the following command on your Ansible host:
92100

93-
```bash
94-
pip install -r https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_ansible_lint.txt
95-
```
101+
```bash
102+
pip install -r https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_ansible_lint.txt
103+
```
96104

97105
#### Molecule (Optional)
98106

@@ -108,11 +116,11 @@ pip install -r https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/mai
108116
molecule test -s plus
109117
```
110118

111-
Alternatively, you can install Molecule and the aforementioned Molecule plugins and Docker Python SDK packages by running the following command on your Ansible host:
119+
- You can install and/or upgrade Molecule, the Molecule plugins package, and the Docker Python SDK by running the following command on your Ansible host:
112120

113-
```bash
114-
pip install -r https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_molecule.txt
115-
```
121+
```bash
122+
pip install --upgrade -r https://raw.githubusercontent.com/nginxinc/ansible-role-nginx/main/.github/workflows/requirements/requirements_molecule.txt
123+
```
116124

117125
## Role Installation
118126

0 commit comments

Comments
 (0)