2018-01-10 23:40:01 +01:00
Ansible NGINX Role
==================
[![Ansible Galaxy ](https://img.shields.io/badge/galaxy-nginxinc.nginx-5bbdbf.svg )](https://galaxy.ansible.com/nginxinc/nginx)
[![Build Status ](https://travis-ci.org/nginxinc/ansible-role-nginx.svg?branch=master )](https://travis-ci.org/nginxinc/ansible-role-nginx)
2020-02-28 16:11:29 +01:00
This role installs NGINX Open Source, NGINX Plus, the NGINX Amplify agent, or NGINX Unit on your target host.
2018-01-10 23:40:01 +01:00
2018-08-03 01:05:41 +02:00
**Note:** This role is still in active development. There may be unidentified issues and the role variables may change as development continues.
2018-01-10 23:40:01 +01:00
Requirements
------------
2019-11-29 04:32:17 +01:00
**Ansible**
2019-12-13 21:11:30 +01:00
This role was developed and tested with [maintained ](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#release-status ) versions of Ansible. Backwards compatibility is not guaranteed.
Instructions on how to install Ansible can be found in the [Ansible website ](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html ).
**Molecule**
Molecule is used to test the various functionailities of the role. Instructions on how to install Molecule can be found in the [Molecule website ](https://molecule.readthedocs.io/en/stable/installation.html ).
Installation
------------
2019-11-29 04:32:17 +01:00
**Ansible Galaxy**
2018-01-10 23:40:01 +01:00
2019-12-13 21:11:30 +01:00
Use `ansible-galaxy install nginxinc.nginx` to install the latest stable release of the role on your system.
**Git**
2018-01-10 23:40:01 +01:00
2019-12-13 21:11:30 +01:00
Use `git clone https://github.com/nginxinc/ansible-role-nginx.git` to pull the latest edge commit of the role from GitHub.
Platforms
---------
2020-02-28 16:11:29 +01:00
The NGINX Ansible role supports all platforms supported by [NGINX Open Source ](https://nginx.org/en/linux_packages.html#mainline ), [NGINX Plus ](https://www.nginx.com/products/technical-specs/ ), the [NGINX Amplify agent ](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-faq.md#21-what-operating-systems-are-supported ), and [NGINX Unit ](https://unit.nginx.org/installation/#official-packages ):
2018-01-10 23:40:01 +01:00
2018-09-11 20:26:56 +02:00
**NGINX Open Source**
2018-01-10 23:40:01 +01:00
2018-07-19 00:01:16 +02:00
```yaml
2019-05-20 18:32:08 +02:00
Alpine:
versions:
- 3.8
- 3.9
2019-11-18 17:14:00 +01:00
- 3.10
2018-07-19 00:01:16 +02:00
CentOS:
versions:
- 6
2019-12-06 22:37:16 +01:00
- 7
2019-05-20 18:32:08 +02:00
- 8
2018-07-19 00:01:16 +02:00
Debian:
versions:
- stretch
2019-08-07 22:16:27 +02:00
- buster
2019-11-18 17:14:00 +01:00
FreeBSD:
2018-07-19 00:01:16 +02:00
versions:
2019-11-18 17:14:00 +01:00
- 11.2+
- 12
RedHat:
versions:
- 6
- 7.4+
- 8
2018-07-19 00:01:16 +02:00
SUSE/SLES:
versions:
- 12
2019-05-20 18:32:08 +02:00
- 15
2019-11-18 17:14:00 +01:00
Ubuntu:
2018-07-19 00:01:16 +02:00
versions:
2019-11-18 17:14:00 +01:00
- xenial
- bionic
2018-07-19 00:01:16 +02:00
```
2018-01-10 23:40:01 +01:00
2018-09-11 20:26:56 +02:00
**NGINX Plus**
2018-01-10 23:40:01 +01:00
2018-07-19 00:01:16 +02:00
```yaml
2019-05-20 18:32:08 +02:00
Alpine:
2018-07-19 00:01:16 +02:00
versions:
2019-05-20 18:32:08 +02:00
- 3.8
- 3.9
2019-11-18 17:14:00 +01:00
- 3.10
2019-05-20 18:32:08 +02:00
Amazon Linux:
2018-07-19 00:01:16 +02:00
versions:
2019-05-20 18:32:08 +02:00
- 2018.03
Amazon Linux 2:
versions:
- LTS
CentOS:
versions:
- 6.5+
- 7.4+
2019-11-18 17:14:00 +01:00
- 8
2018-07-19 00:01:16 +02:00
Debian:
versions:
- stretch
2019-08-07 22:16:27 +02:00
- buster
2019-05-20 18:32:08 +02:00
FreeBSD:
2018-07-19 00:01:16 +02:00
versions:
2019-05-20 18:32:08 +02:00
- 11.2+
- 12
2018-07-19 00:01:16 +02:00
Oracle Linux:
versions:
2019-05-20 18:32:08 +02:00
- 6.5+
- 7.4+
RedHat:
2018-07-19 00:01:16 +02:00
versions:
2019-05-20 18:32:08 +02:00
- 6.5+
- 7.4+
- 8
2019-05-21 17:23:06 +02:00
SUSE/SLES:
versions:
- 12
- 15
2019-05-20 18:32:08 +02:00
Ubuntu:
2018-07-19 00:01:16 +02:00
versions:
2019-05-20 18:32:08 +02:00
- xenial
- bionic
2018-07-19 00:01:16 +02:00
```
2018-04-09 23:22:13 +02:00
2019-11-18 17:14:00 +01:00
**NGINX Amplify Agent**
2018-09-11 20:26:56 +02:00
```yaml
2019-05-20 18:32:08 +02:00
Amazon Linux:
2018-09-11 20:26:56 +02:00
versions:
2019-05-20 18:32:08 +02:00
- 2017.09
CentOS:
2018-09-11 20:26:56 +02:00
versions:
- 6
- 7
Debian:
versions:
- jessie
- stretch
Ubuntu:
versions:
- xenial
2019-05-21 17:23:06 +02:00
- bionic
2019-05-20 18:32:08 +02:00
RedHat:
2018-09-11 20:26:56 +02:00
versions:
2019-05-20 18:32:08 +02:00
- 6
- 7
2018-09-11 20:26:56 +02:00
```
**NGINX Unit**
2018-04-09 23:22:13 +02:00
2018-07-19 00:01:16 +02:00
```yaml
CentOS:
versions:
- 6
- 7
RedHat:
versions:
- 6
- 7
Debian:
versions:
- jessie
- stretch
2019-08-07 22:16:27 +02:00
- buster
2018-07-19 00:01:16 +02:00
Ubuntu:
versions:
- xenial
- bionic
Amazon Linux:
versions:
- 2018.03
2019-05-20 18:32:08 +02:00
Amazon Linux 2:
versions:
2018-07-19 00:01:16 +02:00
- 2
FreeBSD:
versions:
- 10
- 11
```
2018-01-10 23:40:01 +01:00
Role Variables
--------------
2019-12-06 22:37:16 +01:00
This role has multiple variables. The descriptions and defaults for all these variables can be found in the directory ** `defaults/main` ** in the following files:
2018-01-10 23:40:01 +01:00
2019-12-06 22:37:16 +01:00
- ** [defaults/main/main.yml ](./defaults/main/main.yml ):** NGINX installation variables
- ** [defaults/main/amplify.yml ](./defaults/main/amplify.yml ):** NGINX Amplify agent installation variables
- ** [defaults/main/template.yml ](./defaults/main/template.yml ):** NGINX configuration templating variables
- ** [defaults/main/upload.yml ](./defaults/main/upload.yml ):** NGINX configuration/HTML/SSL upload variables
- ** [defaults/main/linux.yml ](./defaults/main/linux.yml ):** Linux installation variables
- ** [defaults/main/bsd.yml ](./defaults/main/bsd.yml ):** BSD installation variables
- ** [defaults/main/unit.yml ](./defaults/main/unit.yml ):** NGINX Unit installation variables
2018-07-12 00:41:10 +02:00
2018-01-10 23:40:01 +01:00
Dependencies
------------
None
Example Playbook
----------------
This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost and installing the open source version of NGINX.
2018-07-19 00:01:16 +02:00
```yaml
---
- hosts: localhost
become: true
roles:
- role: nginxinc.nginx
```
2018-01-10 23:40:01 +01:00
2018-09-11 20:26:56 +02:00
This is a sample playbook file for deploying the Ansible Galaxy NGINX role to a dynamic inventory containing the `nginx` tag.
```yaml
---
- hosts: tag_nginx
remote_user: root
roles:
- role: nginxinc.nginx
```
2018-11-14 19:18:38 +01:00
This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost and installing the open source version of NGINX as a simple web server.
```yaml
---
- hosts: localhost
become: true
roles:
2019-02-06 13:39:48 +01:00
- role: nginxinc.nginx
2018-11-14 19:18:38 +01:00
vars:
nginx_http_template_enable: true
nginx_http_template:
2018-11-14 19:48:51 +01:00
default:
2019-02-06 13:39:48 +01:00
template_file: http/default.conf.j2
conf_file_name: default.conf
conf_file_location: /etc/nginx/conf.d/
2019-12-13 21:11:30 +01:00
servers:
server1:
listen:
listen_localhost:
# ip: 0.0.0.0
port: 80
server_name: localhost
error_page: /usr/share/nginx/html
autoindex: false
web_server:
locations:
default:
location: /
html_file_location: /usr/share/nginx/html
html_file_name: index.html
autoindex: false
http_demo_conf: false
2018-11-14 19:18:38 +01:00
```
This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost and installing the open source version of NGINX as a reverse proxy.
```yaml
---
- hosts: localhost
become: true
roles:
2019-02-06 13:39:48 +01:00
- role: nginxinc.nginx
2018-11-14 19:18:38 +01:00
vars:
nginx_http_template_enable: true
nginx_http_template:
2019-01-14 17:26:37 +01:00
default:
2019-02-06 13:39:48 +01:00
template_file: http/default.conf.j2
conf_file_name: default.conf
conf_file_location: /etc/nginx/conf.d/
2019-11-26 00:46:03 +01:00
servers:
2019-12-06 22:37:16 +01:00
server1:
2019-11-26 00:46:03 +01:00
listen:
listen_localhost:
2019-12-13 21:11:30 +01:00
# ip: 0.0.0.0
2019-11-26 00:46:03 +01:00
port: 80
opts:
- default_server
server_name: localhost
error_page: /usr/share/nginx/html
autoindex: false
reverse_proxy:
locations:
frontend:
location: /
proxy_pass: http://frontend_servers
backend:
location: /backend
proxy_pass: http://backend_servers
2019-01-14 17:26:37 +01:00
upstreams:
upstream_1:
name: frontend_servers
lb_method: least_conn
zone_name: frontend
zone_size: 64k
sticky_cookie: false
servers:
frontend_server_1:
2019-10-13 21:26:47 +02:00
address: 0.0.0.0
port: 8081
2019-01-14 17:26:37 +01:00
weight: 1
health_check: max_fails=3 fail_timeout=5s
upstream_2:
name: backend_servers
lb_method: least_conn
zone_name: backend
zone_size: 64k
sticky_cookie: false
servers:
backend_server_1:
2019-10-13 21:26:47 +02:00
address: 0.0.0.0
port: 8082
2019-01-14 17:26:37 +01:00
weight: 1
health_check: max_fails=3 fail_timeout=5s
2019-10-13 21:26:47 +02:00
frontend:
template_file: http/default.conf.j2
conf_file_name: frontend_default.conf
conf_file_location: /etc/nginx/conf.d/
2019-11-26 00:46:03 +01:00
servers:
server1:
listen:
listen_localhost:
ip: 0.0.0.0
port: 8081
2020-01-09 16:40:36 +01:00
ssl: false
2019-11-26 00:46:03 +01:00
opts: []
server_name: localhost
error_page: /usr/share/nginx/html
autoindex: false
web_server:
locations:
frontend_site:
location: /
proxy_hide_headers:
- X-Powered-By
html_file_location: /usr/share/nginx/html
html_file_name: index.html
autoindex: false
http_demo_conf: false
2019-10-13 21:26:47 +02:00
backend:
template_file: http/default.conf.j2
conf_file_name: backend_default.conf
conf_file_location: /etc/nginx/conf.d/
2019-11-26 00:46:03 +01:00
servers:
server1:
listen:
listen_localhost:
ip: 0.0.0.0
port: 8082
2020-01-09 16:40:36 +01:00
ssl: false
2019-11-26 00:46:03 +01:00
opts: []
server_name: localhost
error_page: /usr/share/nginx/html
autoindex: false
web_server:
locations:
backend_site:
location: /
html_file_location: /usr/share/nginx/html
html_file_name: index.html
autoindex: false
http_demo_conf: false
2018-11-14 19:18:38 +01:00
```
2018-01-10 23:40:01 +01:00
This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost and installing NGINX Plus.
2018-07-19 00:01:16 +02:00
```yaml
---
- hosts: localhost
become: true
roles:
- role: nginxinc.nginx
vars:
2018-09-15 01:28:20 +02:00
nginx_type: plus
2018-07-19 00:01:16 +02:00
```
2018-01-10 23:40:01 +01:00
2018-07-12 03:02:42 +02:00
This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost to install NGINX Unit and the PHP/Perl NGINX Unit language modules.
2018-04-09 23:22:13 +02:00
2018-09-11 20:26:56 +02:00
```yaml
2018-07-19 00:01:16 +02:00
---
- hosts: localhost
become: true
roles:
- role: nginxinc.nginx
vars:
nginx_enable: false
2018-09-15 01:28:20 +02:00
nginx_unit_enable: true
nginx_unit_modules:
2018-07-19 00:01:16 +02:00
- unit-php
- unit-perl
```
2018-04-09 23:22:13 +02:00
2018-01-10 23:40:01 +01:00
To run any of the above sample playbooks create a `setup-nginx.yml` file and paste the contents. Executing the Ansible Playbook is then as simple as executing `ansible-playbook setup-nginx.yml` .
Alternatively, you can also clone this repository instead of installing it from Ansible Galaxy. If you decide to do so, replace the role variable in the previous sample playbooks from `nginxinc.nginx` to `ansible-role-nginx` .
2020-02-28 16:11:29 +01:00
Other NGINX Roles
-----------------
You can find an Ansible collection of roles to help you install and configure NGINX Controller [here ](https://github.com/nginxinc/ansible-collection-nginx_controller )
2018-01-10 23:40:01 +01:00
License
-------
[Apache License, Version 2.0 ](https://github.com/nginxinc/ansible-role-nginx/blob/master/LICENSE )
Author Information
------------------
2019-05-21 17:23:06 +02:00
[Alessandro Fael Garcia ](https://github.com/alessfg )
[Grzegorz Dzien ](https://github.com/gdzien )
2018-01-10 23:40:01 +01:00
2020-01-29 19:37:09 +01:00
© [NGINX, Inc. ](https://www.nginx.com/ ) 2018 - 2020