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)
2018-06-25 23:35:09 +02:00
This role installs NGINX Open Source, NGINX Plus, 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
------------
This role was developed using Ansible 2.4.0.0. Backwards compatibility is not guaranteed.
Use `ansible-galaxy install nginxinc.nginx` to install the role on your system.
2018-04-12 19:20:39 +02:00
It supports all platforms supported by [NGINX Open Source ](https://nginx.org/en/linux_packages.html#mainline ) and [NGINX Plus ](https://www.nginx.com/products/technical-specs/ ):
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
CentOS:
versions:
- 6
- 7
RedHat:
versions:
- 6
- 7
Debian:
versions:
- jessie
- stretch
Ubuntu:
versions:
- trusty
- xenial
- artful
- bionic
SUSE/SLES:
versions:
- 12
FreeBSD:
versions:
- 10
- 11
```
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
CentOS:
versions:
- 6
- 7
RedHat:
versions:
- 6
- 7
Debian:
versions:
- jessie
- stretch
Ubuntu:
versions:
- trusty
- xenial
- artful
- bionic
Oracle Linux:
versions:
- 6.5
- 7
Amazon Linux:
versions:
- 2018.03
SUSE/SLES:
versions:
- 12
FreeBSD:
versions:
- 10
- 11
```
2018-04-09 23:22:13 +02:00
2018-09-11 20:26:56 +02:00
**NGINX Amplify**
```yaml
CentOS:
versions:
- 6
- 7
RedHat:
versions:
- 6
- 7
Debian:
versions:
- jessie
- stretch
Ubuntu:
versions:
- trusty
- xenial
- artful
- bionic
Amazon Linux:
versions:
- 2017.09
```
**NGINX Controller**
```yaml
CentOS:
versions:
- 7
RedHat:
versions:
- 7
Debian:
versions:
- jessie
- stretch
Ubuntu:
versions:
- xenial
- artful
```
**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
Ubuntu:
versions:
- xenial
- artful
- bionic
Amazon Linux:
versions:
- 2018.03
- 2
FreeBSD:
versions:
- 10
- 11
```
2018-01-10 23:40:01 +01:00
Role Variables
--------------
This role has multiple variables. The defaults for all these variables are the following:
2018-07-19 00:01:16 +02:00
```yaml
---
# Install NGINX.
# Default is true.
nginx_enable: true
# Specify which version of NGINX you want to install.
# Options are 'opensource' or 'plus'.
# Default is 'opensource'.
2018-09-15 01:28:20 +02:00
nginx_type: opensource
2018-07-19 00:01:16 +02:00
# Specify repository origin for NGINX Open Source.
# Options are 'nginx_repository' or 'os_repository'.
2018-09-15 01:28:20 +02:00
# Only works if 'nginx_type' is set to 'opensource'.
2018-07-19 00:01:16 +02:00
# Default is nginx_repository.
2018-09-15 01:28:20 +02:00
nginx_install_from: nginx_repository
2018-07-19 00:01:16 +02:00
# Specify source repository for NGINX Open Source.
# Only works if 'install_from' is set to 'nginx_repository'.
# Defaults are the official NGINX repositories.
nginx_repository:
debian:
2018-08-03 01:05:41 +02:00
- deb https://nginx.org/packages/{{ (branch == 'mainline') | ternary('mainline/', '') }}{{ ansible_distribution|lower }}/ {{ ansible_distribution_release }} nginx
- deb-src https://nginx.org/packages/{{ (branch == 'mainline') | ternary('mainline/', '') }}{{ ansible_distribution|lower }}/ {{ ansible_distribution_release }} nginx
2018-07-19 00:01:16 +02:00
redhat:
2018-08-03 01:05:41 +02:00
- https://nginx.org/packages/{{ (branch == 'mainline') | ternary('mainline/', '') }}{{ (ansible_distribution == "RedHat") | ternary('rhel/', 'centos/') }}{{ ansible_distribution_major_version|int }}/$basearch/
2018-07-19 00:01:16 +02:00
suse:
2018-08-03 01:05:41 +02:00
- https://nginx.org/packages/{{ (branch == 'mainline') | ternary('mainline/', '') }}sles/12
2018-07-19 00:01:16 +02:00
# Specify which branch of NGINX Open Source you want to install.
# Options are 'mainline' or 'stable'.
# Only works if 'install_from' is set to 'nginx_repository'.
# Default is mainline.
2018-09-15 01:28:20 +02:00
nginx_branch: mainline
2018-07-19 00:01:16 +02:00
2018-09-11 20:26:56 +02:00
# Location of your NGINX Plus license in your local machine.
# Default is the files folder within the NGINX Ansible role.
2018-09-15 01:28:20 +02:00
nginx_license:
2018-09-11 20:26:56 +02:00
certificate: license/nginx-repo.crt
key: license/nginx-repo.key
# Delete NGINX Plus license after installation for security purposes.
# Default is true.
2018-09-15 01:28:20 +02:00
nginx_delete_license: true
2018-09-11 20:26:56 +02:00
2018-07-19 00:01:16 +02:00
# Install NGINX JavaScript, Perl, ModSecurity WAF (NGINX Plus only), GeoIP, Image-Filter, RTMP Media Streaming, and/or XSLT modules.
# Default is false.
2018-09-15 01:28:20 +02:00
nginx_modules:
2018-07-19 00:01:16 +02:00
njs: false
perl: false
waf: false
geoip: false
image_filter: false
rtmp: false
xslt: false
# Install NGINX Amplify.
# Use your NGINX Amplify API key.
2018-09-11 22:08:15 +02:00
# Requires access to either the NGINX stub status or the NGINX Plus REST API.
2018-07-19 00:01:16 +02:00
# Default is null.
2018-09-15 01:28:20 +02:00
nginx_amplify_enable: false
nginx_amplify_api_key: null
2018-07-19 00:01:16 +02:00
2018-09-11 20:26:56 +02:00
# Install NGINX Controller.
# Use your NGINX Controller API key and NGINX Controller API endpoint.
2018-09-11 22:08:15 +02:00
# Requires NGINX Plus and write access to the NGINX Plus REST API.
2018-09-11 20:26:56 +02:00
# Default is null.
2018-09-15 01:28:20 +02:00
nginx_controller_enable: false
nginx_controller_api_key: null
nginx_controller_api_endpoint: null
2018-09-11 20:26:56 +02:00
# Install NGINX Unit and NGINX Unit modules.
# Use a list of supported NGINX Unit modules.
# Default is false.
2018-09-15 01:28:20 +02:00
nginx_unit_enable: false
nginx_unit_modules: null
2018-09-11 20:26:56 +02:00
2018-07-19 00:01:16 +02:00
# Enable NGINX status data.
# Will enable 'stub_status' in NGINX Open Source and 'status' in NGINX Plus.
# Default is false.
2018-09-15 01:28:20 +02:00
nginx_status_enable: false
2018-07-19 00:01:16 +02:00
# Enable NGINX Plus REST API, write access to the REST API, and NGINX Plus dashboard.
2018-09-11 20:26:56 +02:00
# Requires NGINX Plus.
2018-07-19 00:01:16 +02:00
# Default is false.
2018-09-15 01:28:20 +02:00
nginx_rest_api_enable: false
nginx_rest_api_write: false
nginx_rest_api_dashboard: false
2018-07-19 00:01:16 +02:00
# Enable uploading NGINX configuration files to your system.
# Default for uploading files is false.
# Default location of files is the files folder within the NGINX Ansible role.
2018-09-15 01:28:20 +02:00
nginx_main_push_enable: false
nginx_main_push_location: conf/nginx.conf
nginx_http_push_enable: false
nginx_http_push_location: conf/http/*.conf
nginx_stream_push_enable: false
nginx_stream_push_location: conf/stream/*.conf
2018-07-19 00:01:16 +02:00
# Configuration variables to create a templated NGINX configuration.
# Defaults are the values found in a fresh NGINX installation.
2018-09-15 01:28:20 +02:00
nginx_main_template_enable: false
nginx_main_template_user: nginx
nginx_main_template_worker_processes: auto
nginx_main_template_error_level: warn
nginx_main_template_worker_connections: 1024
nginx_http_template_enable: false
nginx_http_template_keepalive_timeout: 65
nginx_http_template_listen: 80
nginx_http_template_server_name: localhost
nginx_stream_template_enable: false
nginx_stream_template_listen: 12345
2018-07-19 00:01:16 +02:00
```
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:
- nginxinc.nginx
vars:
nginx_http_template_enable: true
nginx_http_template:
web_server:
locations:
default:
location: /
html_file_location: /usr/share/nginx/html
html_file_name: index.html
```
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:
- nginxinc.nginx
vars:
nginx_http_template_enable: true
nginx_http_template:
load_balancer:
locations:
frontend:
location: /
proxy_pass: frontend_servers
backend:
location: /backend
proxy_pass: backend_servers
upstreams:
upstream_1:
name: frontend_servers
lb_method: least_conn
zone_name: frontend
zone_size: 64k
sticky_cookie: false
servers:
frontend_server_1:
address: localhost
port: 80
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:
address: localhost
port: 8080
weight: 1
health_check: max_fails=3 fail_timeout=5s
```
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-09-11 20:26:56 +02:00
This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost to install NGINX Plus and the NGINX Controller agent.
2018-01-10 23:40:01 +01:00
2018-09-11 20:26:56 +02:00
```yaml
- hosts: localhost
become: true
2018-07-19 00:01:16 +02:00
roles:
- role: nginxinc.nginx
2018-09-11 20:26:56 +02:00
vars:
2018-09-15 01:28:20 +02:00
nginx_type: plus
nginx_rest_api_enable: true
nginx_rest_api_write: true
nginx_controller_enable: true
nginx_controller_api_key: < API_KEY_HERE >
nginx_controller_api_endpoint: https://< FQDN > /1.4
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` .
License
-------
[Apache License, Version 2.0 ](https://github.com/nginxinc/ansible-role-nginx/blob/master/LICENSE )
Author Information
------------------
Alessandro Fael Garcia
[NGINX Inc ](https://www.nginx.com/ )