👾 Help make the NGINX Ansible collection better by participating in our survey! 👾

Ansible NGINX Collection

The Ansible NGINX collection includes a variety of NGINX Ansible roles to help automate the installation and configuration of NGINX. This collection is maintained by NGINX.

Note: This collection is still in active development. There may be unidentified issues as development continues.

Included Content

The current stable release (0.8.0) of the Ansible NGINX collection includes the following roles:

Requirements

NGINX Plus (Optional)

If you wish to install NGINX Plus using this collection, 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.

NGINX App Protect (Optional)

If you wish to install NGINX App Protect WAF or NGINX App Protect DoS using this collection, you will need to obtain the corresponding NGINX App Protect license beforehand.

Ansible

• This collection is developed and tested with maintained versions of Ansible core (above 2.12).

• When using Ansible core, you will also need to install the following collections:

  ---
  collections:
    - name: ansible.posix
      version: 1.4.0
    - name: community.crypto
      version: 2.10.0
    - name: community.general
      version: 6.2.0
    - name: community.docker # Only required if you plan to use Molecule (see below)
      version: 3.4.0

  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.

• You will need to run this collection 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.

Jinja2

• This collection 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 collection to properly function is 3.1.
• Instructions on how to install Jinja2 can be found in the Jinja2 website.

Molecule (Optional)

• Molecule is used to test the various roles included in the collection. The recommended version of Molecule to test this role is 4.x.
• At the moment, there are no end to end integration tests. You will need to change directory into each role's respective directory.
• Instructions on how to install Molecule can be found in the Molecule website. You will also need to install the Molecule Docker driver.

• To run the NGINX Plus and/or NGINX App Protect Molecule tests, you must copy your corresponding license to the respective role's files/license folder.

  You can alternatively add your NGINX certificate and key to the local environment. Run the following commands to export these files as base64-encoded variables and execute the Molecule tests:

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

Installation

Ansible Galaxy

To install the latest stable release of the collection on your system, use:

ansible-galaxy collection install nginxinc.nginx_core

Alternatively, if you have already installed the collection, update the collection to the latest release:

ansible-galaxy collection install -f nginxinc.nginx_core

You can also include the collection in a requirements.yml file:

---
collections:
  - name: nginxinc.nginx_core
    version: 0.8.0

And install the collection:

ansible-galaxy collection install -r requirements.yml

Git

To pull the latest edge commit of the role from GitHub, use:

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

Usage

Sample playbooks for each use case covered by this collection can be found in the playbooks/ folder in the following files:

Development

Currently, all the NGINX roles included in this collection (found in the roles/ folder) are Git submodules, and work on the roles themselves should take place in the corresponding upstream role repository.

To update the roles included in this collection to their latest version, use:

git submodule update --recursive --remote

Other NGINX Ansible Collections and Roles

You can find the Ansible NGINX Unit role to install NGINX Unit here.

License

Apache License, Version 2.0

Author Information

Alessandro Fael Garcia

© F5, Inc. 2020 - 2023