ansible-role-nginx: installing NGINX across fleets with Ansible

One role covering three products with different licensing

The scope of this role is wider than the name suggests. It installs NGINX Open Source, NGINX Plus and NGINX Agent, and the way those three differ is expressed as a licensing table in the project documentation rather than as separate roles.

Open Source needs nothing beyond the role itself. NGINX Plus requires a license key and crt files, and the community.crypto collection is listed as a dependency only for that case. NGINX Agent needs a compatible control plane, plus optionally a data plane token for an NGINX One SaaS console.

That table is the practical reason to use this role rather than writing your own. The awkward parts of an NGINX rollout are the licensed variants: the repository you point at, the certificate and key pair, the Agent registration, and the difference between a test that installs freely and a test that needs a certificate mounted into it. A single role with product specific branches keeps that in one place.

The role lives in the nginx organisation on GitHub and is published on Ansible Galaxy as nginxinc/nginx, with a community forum behind it. The licence is Apache 2.0 and the repository carries a Contributor Covenant, a security policy, a support policy and a changelog, which is the paperwork you would expect from a role used by people who did not write it.

The requirements file pins collections, not just Ansible

Installing the role is the easy part. The interesting decision is what you install alongside it, because the documentation asks you to bring Ansible core, Jinja2 and four collections to versions the role is actually tested against, and it offers four commands that do it for you.

pip install --upgrade -r https://raw.githubusercontent.com/nginx/ansible-role-nginx/main/.github/workflows/requirements/requirements_ansible.txt
curl -O https://raw.githubusercontent.com/nginx/ansible-role-nginx/main/.github/workflows/requirements/requirements_collections.yml
ansible-galaxy install --force -r requirements_collections.yml
rm -f requirements_collections.yml

The third command is the one to understand. It installs the collections listed in the requirements file, which pins ansible.posix at 2.2.2, community.general at 11.4.9, community.crypto at 2.26.9 and community.docker at 5.2.2. The last two are marked as only required in specific cases, the first for NGINX Plus and the second if you plan to use Molecule, but the file installs all of them together.

The collections file itself is worth reading before you install it, because ansible-galaxy install --force replaces whatever is already there for those names. If your platform shares a control host with other roles that need different versions of community.general, running this in the same virtual environment is a decision with consequences. The documentation notes that you can install the Ansible community distribution instead if you would rather not manage individual collections at all, which trades version control for convenience.

Jinja2 has its own floor. The role uses Jinja2 templates, and the minimum version required for it to function properly is 3.1, because Ansible core installs Jinja2 by default and your upgrade path may leave an older copy in place. The role also expects to be run as root using Ansible's become parameter, so the target host needs the matching permissions set up before the first run.

Molecule scenarios are the only way to see the Plus path work

Testing infrastructure is part of the role, not an afterthought, and it comes in two pieces. Ansible Lint checks the role against Ansible best practices and flags potential Ansible and YAML issues. Molecule exercises the actual functionality.

Lint is a one command check once installed:

  ansible-lint

Molecule is more interesting because of how the licensed product is handled. To run the NGINX Plus scenarios you must first copy your NGINX Plus license into the role's files/license directory, or export the certificate and key into the environment as base64 variables:

  export NGINX_CRT=$( cat <path to your certificate file> | base64 )
  export NGINX_KEY=$( cat <path to your key file> | base64 )
  molecule test -s plus

The plus scenario is selected with the -s flag, so the same command runs other scenarios by name. The exported variables are how a CI environment avoids checking a licence into the repository, which is a real problem when the certificate and key are the one thing you must not commit.

Contributors also need the Molecule plugins package and the Docker Python SDK, since the scenarios run in containers. That container requirement is a real constraint for an organisation whose CI runners are hardened against Docker, and it applies to the community.docker collection too, which is one of the four collections installed by the requirements file.

A role that is still in development and says so

The project documentation carries an explicit warning: the role is still in active development, there may be unidentified issues, and the role variables may change as development continues. That statement sits in an important callout near the top, which is where you would expect it if the maintainers meant it.

It matters because an Ansible role is an interface to your infrastructure, not a library. The variables a team sets in group_vars are the contract they then depend on across environments, and if a variable name changes between role versions, the failure mode is a changed server rather than a failed playbook. Teams that treat role variables as public API will want to pin the role version in their requirements and read the changelog before upgrading, which the repository provides.

The version numbers themselves are small and unremarkable, 0.26.0 being the most recent, and the release history shows a long gap between 0.25.0 in November 2024 and 0.26.0 in July 2026. The gap does not mean the project stopped, since the last push was on 2026-10-19, but it does mean the release tag lags the work in the branch. If you consume the role from the main branch rather than Galaxy, you are taking untagged changes to your production hosts.

The role is also published from a main default branch, and the documentation offers cloning the repository as an alternative to installing from Galaxy, so both consumption paths are supported.

Why not just write the install tasks yourself

The alternative is a short set of playbooks: install the package, drop a template, register a service, and repeat for three products. It is entirely reasonable for a team that only needs Open Source on one host, and it avoids the version pinning, the become requirement and the container based test suite that come with this role.

The difference shows up the moment the fleet grows or the product set widens. A hand written set of tasks has to be extended for NGINX Plus, where the key pair and the custom repository have to be handled, and for NGINX Agent, where the agent is pointed at a control plane. The role already has those branches, and the collection it declares as a Plus-only dependency exists because that path is implemented.

The other difference is where the knowledge sits. A role published by the NGINX organisation on Ansible Galaxy carries the vendor's own view of how its product should be installed, and it is linted and molecule tested against a range of configurations that a single team rarely reproduces. A local playbook carries your view, which may be better for your specific setup, and which nobody else maintains for you.

The trade off runs in the other direction too. The role is opinionated about how NGINX gets installed, so if your setup needs something unusual, you will be fighting the role's variables rather than a small playbook you can read top to bottom. For a widely used product with a well documented installation, that opinionation is usually worth taking.

Editorial conclusion

Adopt ansible-role-nginx if you standardise NGINX deployment on Ansible and want the same role to cover Open Source, Plus and Agent rather than maintaining your own package and template tasks. Do not adopt it if your infrastructure team treats role variables as a stable public interface, because the README states the role is still in active development and the variables may change. Before you commit, install the pinned collection versions listed in the requirements, run ansible-lint, and execute molecule test -s plus with your NGINX Plus certificate exported, since that is the only path that exercises the licensed product.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. nginx/ansible-role-nginx on GitHub
3. Project website
4. README
5. Releases