nginxinc / ansible-collection-nginx

Ansible collection for NGINX

👾 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:

Name	Description	Version
nginxinc.nginx	Install NGINX	0.24.0
nginxinc.nginx_config	Configure NGINX	0.6.0
nginxinc.nginx_app_protect	Install and configure NGINX App Protect	0.9.0

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:

Name	Description
deploy-nginx.yml	Install NGINX
deploy-nginx-web-server.yml	Install NGINX and configure a simple web server
deploy-nginx-web-server-proxy.yml	Install NGINX and configure a simple reverse proxy in front of two web servers
deploy-nginx-plus.yml	Install NGINX Plus
deploy-nginx-app-protect.yml	Install NGINX App Protect WAF/DoS
deploy-nginx-plus-app-protect.yml	Install NGINX Plus and NGINX App Protect WAF
deploy-nginx-plus-app-protect-web-server-proxy.yml	Install NGINX Plus and NGINX App Protect and configure a simple reverse proxy in front of two web servers protected by NGINX App Protect WAF/DoS

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

ansible-collection-nginx's Issues

Fails on amazon linux 2

I get the following errors:

Your OS, Amazon is not supported by NGINX Open Source

fatal: [nginx]: FAILED! => {"changed": false, "msg": "Failure talking to yum: failure: repodata/repomd.xml from nginx: [Errno 256] No more mirrors to try.\nhttps://nginx.org/packages/mainline/rhel/2/x86_64/repodata/repomd.xml: [Errno 14] HTTPS Error 404 - Not Found"}

When installing on amazon linux.

Ami is ami-0528a5175983e7f28 (amzn2-ami-hvm-2.0*).

Getting error when using collection anybody else seen this?

I have installed the collection then used a playbook to run this
ansible version is 2.10.6
Playbook is

• hosts: all
  collections:
  • nginxinc.nginx_core
    roles:
  • role: nginx

Using debian buster get a message debian supported
"msg": "Your OS, Debian is supported by NGINX Open Source"

then an error and then stops not sure why it is checking for apline when it has alredy checked that it is debian?

TASK [nginxinc.nginx_core.nginx : Install dependencies] ********************************************************************************************************
fatal: [abc]: FAILED! => {"reason": "couldn't resolve module/action 'apk'. This often indicates a misspelling, missing collection, or incorrect module path.\n\nThe error appears to be in '/home/abc/ansibleplaybooks/ansible_collections/nginxinc/nginx_core/roles/nginx/tasks/prerequisites/install-dependencies.yml': line 2, column 3, but may\nbe elsewhere in the file depending on the exact syntax problem.\n\nThe offending line appears to be:\n\n---\n- name: (Alpine Linux) Install dependencies\n ^ here\n"}.

nginx_config not deploying the correct config in nginx.conf file

I am trying to execute the following playbook

---
- name: Basic setup
  hosts: gates
  collections:
    - nginxinc.nginx_core
  tasks:
    - name: Install NGINX
      include_role:
        name: nginx
    - name: Configure NGINX
      include_role:
        name: nginx_config
      vars:
        nginx_config_debug_output: true

        nginx_config_cleanup: true
        nginx_config_cleanup_paths:
          - directory:
              - /etc/nginx/conf.d
            recurse: false
        nginx_config_cleanup_files:
          - /etc/nginx/conf.d/default.conf
        nginx_config_main_template_enable: false
        nginx_config_main_template:
          template_file: nginx.conf.j2
          conf_file_name: nginx.conf
          conf_file_location: /etc/nginx/
          user: nginx
          worker_processes: auto
          worker_rlimit_nofile: 1024
          pid: /var/run/nginx.pid
          error_log:
            location: /var/log/nginx/error.log
            level: warn
          worker_connections: 1024
          http_enable: true
          access_log_format:
            - name: upstream_info
              format: |-
                '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
                'rt=$request_time uct="$upstream_connect_time" uht="$upstream_header_time" urt="$upstream_response_time"'
          access_log_location:
            - name: upstream_info
              location: /var/log/nginx/access.log

but the nginx.conf is getting the default values:

user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;


events {
    worker_connections  1024;
}


http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    #gzip  on;

    include /etc/nginx/conf.d/*.conf;
}

I am running Ansible 4.1 and I have the 0.3.3 nginxinc.nginx_core collection

(cluster) joan@DESKTOP-OM8Q4NE:~/Abzu/cluster$ ansible --version
ansible [core 2.11.1]
  config file = /home/joan/Abzu/cluster/ansible.cfg
  configured module search path = ['/home/joan/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /home/joan/.local/share/virtualenvs/cluster-DtMsh1G5/lib/python3.8/site-packages/ansible
  ansible collection location = /home/joan/.ansible/collections:/usr/share/ansible/collections
  executable location = /home/joan/.local/share/virtualenvs/cluster-DtMsh1G5/bin/ansible
  python version = 3.8.5 (default, Jan 27 2021, 15:41:15) [GCC 9.3.0]
  jinja version = 3.0.0
  libyaml = True

RHEL - Equivalent distribution for use in ansible project and collection

Is your feature request related to a problem? Please describe

I'm using a lot RHEL and Centos distribution, Now with Centos "stream" moving from v.8 distribution i'm interested in using Rocky Linux.

Describe the solution you'd like

Extend "limitation" in use only whit distribution indicated in vars/main.yml also with Rocky linux distribution

Describe alternatives you've considered

change the following variable available from

nginx_distributions: [
  'Alpine', 'Amazon', 'CentOS', 'Debian', 'FreeBSD', 'RedHat', 'SLES', 'Ubuntu',
  'NetBSD', 'OpenBSD', 'DragonFlyBSD', 'HardenedBSD',
]

--- to ---

nginx_distributions: [
  'Alpine', 'Amazon', 'CentOS', 'Debian', 'FreeBSD', 'RedHat', 'SLES', 'Ubuntu',
  'NetBSD', 'OpenBSD', 'DragonFlyBSD', 'HardenedBSD', 'Rocky',
]

Additional context

The preliminary test can be done correct and installation can be made.

##Add any other context or screenshots about the feature request here.
Tested proficiency with Rocky Linux 8.5 version using the following play:

---
- name: install and starts the Nginx web server on server one 
  hosts: one
  pre_tasks:
  - name: ensure http is not installed
    yum:
      name: httpd
      state: absent

  collections:
    - nginxinc.nginx_core
  roles:
    - role: nginx
...

iS it possible to point ngninx-config role to the latest version?

Is your feature request related to a problem? Please describe

Some bug fixing are existing on the latest version of the role ansible-role-nginx-config
but not available to the people who installed it via the collection

Describe the solution you'd like

Point the role ansible-role-nginx-config to the latest version

Describe alternatives you've considered

Installing the two roles inside the collection independently and not using the collection anymore
IT would work without problems, some refactoring needed but it defeats a bit the purpose of having a collection

Possibility to use SNI Routing

At https://gist.github.com/kekru/c09dbab5e78bf76402966b13fa72b9d2
we see how TLS termination with backend servers depending on SNI would work. (not sure if theres another solution)

Is this possible with this collection?

Cheers

Upload new version to ansible galaxy

Describe the bug
Currently only the release 0.2.0 is available on the galaxy

ansible-playbook deploy-nginx-web-server.yml -e "inventory=192.168.2.14"

Describe the bug

A clear and concise description of what the bug is.

To reproduce

Steps to reproduce the behavior:

1. Deploy NGINX collection using playbook.yml
2. View output/logs/configuration on '...'
3. See error

Expected behavior

A clear and concise description of what you expected to happen.

Your environment

• Version of the NGINX collection or specific commit
• Version of Ansible
• Version of Jinja2 (if you are using any templating capability)
• Target deployment platform

Additional context

Add any other context about the problem here.
failed: [192.168.2.14] (item={u'config': {u'servers': [{u'core': {u'server_name': u'localhost', u'listen': [{u'port': 80}]}, u'sub_filter': {u'sub_filters': [{u'string': u'server_hostname', u'replacement': u'$hostname'}, {u'string': u'server_address', u'replacement': u'$server_addr:$server_port'}, {u'string': u'server_url', u'replacement': u'$request_uri'}, {u'string': u'remote_addr', u'replacement': u'$remote_addr:$remote_port'}, {u'string': u'server_date', u'replacement': u'$time_local'}, {u'string': u'client_browser', u'replacement': u'$http_user_agent'}, {u'string': u'request_id', u'replacement': u'$request_id'}, {u'string': u'nginx_version', u'replacement': u'$nginx_version'}, {u'string': u'document_root', u'replacement': u'$document_root'}, {u'string': u'proxied_for_ip', u'replacement': u'$http_x_forwarded_for'}], u'once': False}, u'log': {u'access': [{u'path': u'/var/log/nginx/access.log', u'format': u'main'}]}, u'locations': [{u'core': {u'index': u'index.html', u'root': u'/usr/share/nginx/html'}, u'location': u'/'}]}]}, u'template_file': u'http/default.conf.j2', u'deployment_location': u'/etc/nginx/conf.d/default.conf'}) => {"ansible_loop_var": "item", "changed": false, "item": {"config": {"servers": [{"core": {"listen": [{"port": 80}], "server_name": "localhost"}, "locations": [{"core": {"index": "index.html", "root": "/usr/share/nginx/html"}, "location": "/"}], "log": {"access": [{"format": "main", "path": "/var/log/nginx/access.log"}]}, "sub_filter": {"once": false, "sub_filters": [{"replacement": "$hostname", "string": "server_hostname"}, {"replacement": "$server_addr:$server_port", "string": "server_address"}, {"replacement": "$request_uri", "string": "server_url"}, {"replacement": "$remote_addr:$remote_port", "string": "remote_addr"}, {"replacement": "$time_local", "string": "server_date"}, {"replacement": "$http_user_agent", "string": "client_browser"}, {"replacement": "$request_id", "string": "request_id"}, {"replacement": "$nginx_version", "string": "nginx_version"}, {"replacement": "$document_root", "string": "document_root"}, {"replacement": "$http_x_forwarded_for", "string": "proxied_for_ip"}]}}]}, "deployment_location": "/etc/nginx/conf.d/default.conf", "template_file": "http/default.conf.j2"}, "msg": "TemplateAssertionError: no test named 'boolean'"}