Ansible NGINX Role

This role helps you install NGINX (the open-source version), NGINX Plus, the NGINX Agent, or the NGINX Amplify agent on your servers.

Important: This role is still in development. Some problems might exist, and settings may change over time.

Requirements

NGINX

You may need a license or API key depending on which version of NGINX you are using:

Ansible

To use this role, ensure you have a supported version of Ansible and Jinja2 installed. You can set this up by running these commands on your Ansible host:

pip install --upgrade -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 --force -r requirements_collections.yml
rm -f requirements_collections.yml

Installing Ansible

Make sure you're using a supported version of Ansible. You can find installation instructions in the Ansible documentation.

You will also need some specific Ansible collections:

---
collections:
  - name: ansible.posix
    version: 1.5.4
  - name: community.general
    version: 9.2.0

Tip: You can install the community distribution of Ansible if you prefer not to manage individual collections.

Jinja2

The role uses Jinja2 for templates. Make sure you have Jinja2 version 3.1 or later. Find installation instructions on the Jinja2 website.

Optional Testing Suite

If you want to contribute to this role, you may want to install additional tools like Ansible Lint and Molecule for testing.

Ansible Lint

Ansible Lint checks for best practices and potential issues. You can install it from the Ansible Lint website and run it with:

ansible-lint

Molecule

Molecule is used for testing the role's functionalities. Installation instructions are available on the Molecule website.

Installing the Role

You can install the role via Ansible Galaxy or by cloning the repository.

Ansible Galaxy

To install, run:

ansible-galaxy install nginxinc.nginx

Include the role in your playbook like this:

- name: Install NGINX
  ansible.builtin.include_role:
    name: nginxinc.nginx

Git

To clone the repo, run:

git clone https://github.com/nginxinc/ansible-role-nginx.git

Include the role in your playbook:

- name: Install NGINX
  ansible.builtin.include_role:
    name: <path/to/repo>

Supported Platforms

The role works on most platforms that support NGINX Open Source and Plus:

• AlmaLinux
• Amazon Linux
• Debian
• Ubuntu
• Red Hat, etc.

Role Variables

This role has various variables that can be found in the defaults/main/ directory.

Example Playbooks

Examples of playbooks can be found in the molecule/ folder for different use cases, like installing NGINX, configuring agents, or downgrading NGINX.

Other NGINX Roles

You can find more NGINX-related roles in the NGINX GitHub repository.

License

This role is under the Apache License, Version 2.0.

Authors

• Alessandro Fael Garcia
• Grzegorz Dzien
• Tom Gamull

© F5, Inc. 2018 - 2024