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) This role installs NGINX Open Source, NGINX Plus, the NGINX Amplify agent, the NGINX Controller agent, or NGINX Unit on your target host. **Note:** This role is still in active development. There may be unidentified issues and the role variables may change as development continues. Requirements ------------ **Ansible** 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. **Ansible Galaxy** Use `ansible-galaxy install nginxinc.nginx` to install the role on your system. 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/): **NGINX Open Source** ```yaml Alpine: versions: - 3.8 - 3.9 - 3.10 CentOS: versions: - 6 - 7.4+ - 8 Debian: versions: - stretch - buster FreeBSD: versions: - 11.2+ - 12 RedHat: versions: - 6 - 7.4+ - 8 SUSE/SLES: versions: - 12 - 15 Ubuntu: versions: - xenial - bionic ``` **NGINX Plus** ```yaml Alpine: versions: - 3.8 - 3.9 - 3.10 Amazon Linux: versions: - 2018.03 Amazon Linux 2: versions: - LTS CentOS: versions: - 6.5+ - 7.4+ - 8 Debian: versions: - stretch - buster FreeBSD: versions: - 11.2+ - 12 Oracle Linux: versions: - 6.5+ - 7.4+ RedHat: versions: - 6.5+ - 7.4+ - 8 SUSE/SLES: versions: - 12 - 15 Ubuntu: versions: - xenial - bionic ``` **NGINX Amplify Agent** ```yaml Amazon Linux: versions: - 2017.09 CentOS: versions: - 6 - 7 Debian: versions: - jessie - stretch Ubuntu: versions: - trusty - xenial - bionic RedHat: versions: - 6 - 7 ``` **NGINX Controller Agent** ```yaml Amazon Linux: versions: - 2017.09 Amazon Linux 2: versions: - LTS CentOS: versions: - 6 - 7 Debian: versions: - jessie - stretch Ubuntu: versions: - xenial - bionic RedHat: versions: - 6 - 7 ``` **NGINX Unit** ```yaml CentOS: versions: - 6 - 7 RedHat: versions: - 6 - 7 Debian: versions: - jessie - stretch - buster Ubuntu: versions: - xenial - bionic Amazon Linux: versions: - 2018.03 Amazon Linux 2: versions: - 2 FreeBSD: versions: - 10 - 11 ``` Role Variables -------------- This role has multiple variables. The defaults for all these variables are the following: ```yaml --- # Install NGINX. # Default is true. nginx_enable: true # Start NGINX service. # Default is true. nginx_start: true # Print NGINX configuration file to terminal after executing playbook. nginx_debug_output: false # Supported systems nginx_linux_families: ['Alpine', 'Debian', 'RedHat', 'Suse'] nginx_bsd_systems: ['FreeBSD', 'NetBSD', 'OpenBSD', 'DragonFlyBSD', 'HardenedBSD'] # Specify which type of NGINX you want to install. # Options are 'opensource' or 'plus'. # Default is 'opensource'. nginx_type: opensource # Specify which version of NGINX you want to install. # Default is empty. # nginx_version: =19-1~bionic # Specify repository origin for NGINX Open Source. # Options are 'nginx_repository' or 'os_repository'. # Only works if 'nginx_type' is set to 'opensource'. # Default is nginx_repository. nginx_install_from: nginx_repository # Choose where to fetch the NGINX signing key from. # Default is the official NGINX signing key host. # nginx_signing_key: http://nginx.org/keys/nginx_signing.key # 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: deb https://nginx.org/packages/mainline/debian/ stretch nginx # Choose to install BSD packages or ports. # Options are True for packages or False for ports. # Default is True. nginx_bsd_install_packages: true # Choose to update BSD ports collection. # Options are True for update or False for do not update. # Default is True. nginx_bsd_update_ports: true # Choose to install packages built from BSD ports collection if # available. # Options are True for use packages or False for do not use packages. # Default is True. nginx_bsd_portinstall_use_packages: true # 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. nginx_branch: mainline # Location of your NGINX Plus license in your local machine. # Default is the files folder within the NGINX Ansible role. nginx_license: certificate: license/nginx-repo.crt key: license/nginx-repo.key # Delete NGINX Plus license after installation for security purposes. # Default is true. nginx_delete_license: true # Install NGINX JavaScript, Perl, ModSecurity WAF (NGINX Plus only), GeoIP, Image-Filter, RTMP Media Streaming, and/or XSLT modules. # Default is false. nginx_modules: njs: false perl: false waf: false geoip: false image_filter: false rtmp: false xslt: false # Install NGINX Amplify. # Use your NGINX Amplify API key. # Requires access to either the NGINX stub status or the NGINX Plus REST API. # Default is null. nginx_amplify_enable: false nginx_amplify_api_key: null # Install NGINX Controller. # Use your NGINX Controller API key and NGINX Controller API endpoint. # Requires NGINX Plus and write access to the NGINX Plus REST API. # Default is null. nginx_controller_enable: false nginx_controller_api_key: null nginx_controller_api_endpoint: null # Install NGINX Unit and NGINX Unit modules. # Use a list of supported NGINX Unit modules. # Default is false. nginx_unit_enable: false nginx_unit_modules: null # Remove previously existing NGINX configuration files. # Use a list of paths you wish to remove. # Default is false. nginx_cleanup_config: false nginx_cleanup_config_path: - /etc/nginx/conf.d # 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. # Upload the main NGINX configuration file. nginx_main_upload_enable: false nginx_main_upload_src: conf/nginx.conf nginx_main_upload_dest: /etc/nginx/ # Upload HTTP NGINX configuration files. nginx_http_upload_enable: false nginx_http_upload_src: conf/http/*.conf nginx_http_upload_dest: /etc/nginx/conf.d/ # Upload Stream NGINX configuration files. nginx_stream_upload_enable: false nginx_stream_upload_src: conf/stream/*.conf nginx_stream_upload_dest: /etc/nginx/conf.d/ # Upload HTML files. nginx_html_upload_enable: false nginx_html_upload_src: www/* nginx_html_upload_dest: /usr/share/nginx/html # Upload SSL certificates and keys. nginx_ssl_upload_enable: false nginx_ssl_crt_upload_src: ssl/*.crt nginx_ssl_crt_upload_dest: /etc/ssl/certs/ nginx_ssl_key_upload_src: ssl/*.key nginx_ssl_key_upload_dest: /etc/ssl/private/ # Enable creating dynamic templated NGINX HTML demo websites. nginx_html_demo_template_enable: false nginx_html_demo_template: default: template_file: www/index.html.j2 html_file_name: index.html html_file_location: /usr/share/nginx/html web_server_name: Default # Enable creating dynamic templated NGINX configuration files. # Defaults are the values found in a fresh NGINX installation. nginx_main_template_enable: false nginx_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 error_log: location: /var/log/nginx/error.log level: warn worker_connections: 1024 http_enable: true http_settings: access_log_format: - name: main format: |- '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for"' access_log_location: - name: main location: /var/log/nginx/access.log tcp_nopush: true tcp_nodelay: true keepalive_timeout: 65 cache: false rate_limit: false keyval: false #server_tokens: "off" http_global_autoindex: false #http_custom_options: [] stream_enable: false #stream_custom_options: [] #auth_request_http: /auth #auth_request_set_http: #name: $auth_user #value: $upstream_http_x_user # Enable creating dynamic templated NGINX HTTP configuration files. # Defaults will not produce a valid configuration. Instead they are meant to showcase # the options available for templating. Each key represents a new configuration file. nginx_http_template_enable: false nginx_http_template: default: template_file: http/default.conf.j2 conf_file_name: default.conf conf_file_location: /etc/nginx/conf.d/ servers: server1: listen: listen_localhost: ip: localhost # Wrap in square brackets for IPv6 addresses port: 8081 opts: [] # Listen opts like http2 which will be added (ssl is automatically added if you specify 'ssl:'). server_name: localhost include_files: [] error_page: /usr/share/nginx/html access_log: - name: main location: /var/log/nginx/access.log error_log: location: /var/log/nginx/error.log level: warn root: /usr/share/nginx/html https_redirect: false autoindex: false auth_basic: null auth_basic_user_file: null try_files: $uri $uri/index.html $uri.html =404 #auth_request: /auth #auth_request_set: #name: $auth_user #value: $upstream_http_x_user client_max_body_size: 1m proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application add_headers: strict_transport_security: name: Strict-Transport-Security value: max-age=15768000; includeSubDomains always: true #header_name: #name: Header-X #value: Value-X #always: false ssl: cert: /etc/ssl/certs/default.crt key: /etc/ssl/private/default.key dhparam: /etc/ssl/private/dh_param.pem protocols: TLSv1 TLSv1.1 TLSv1.2 ciphers: HIGH:!aNULL:!MD5 prefer_server_ciphers: true session_cache: none session_timeout: 5m disable_session_tickets: false trusted_cert: /etc/ssl/certs/root_CA_cert_plus_intermediates.crt stapling: true stapling_verify: true #custom_options: [] web_server: locations: default: location: / include_files: [] proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application add_headers: strict_transport_security: name: Strict-Transport-Security value: max-age=15768000; includeSubDomains always: true #header_name: #name: Header-X #value: Value-X #always: false html_file_location: /usr/share/nginx/html html_file_name: index.html autoindex: false auth_basic: null auth_basic_user_file: null try_files: $uri $uri/index.html $uri.html =404 #auth_request: /auth #auth_request_set: #name: $auth_user #value: $upstream_http_x_user client_max_body_size: 1m #returns: #return302: #code: 302 #url: https://sso.somehost.local/?url=https://$http_host$request_uri #custom_options: [] http_demo_conf: false reverse_proxy: locations: backend: location: / include_files: [] proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application add_headers: strict_transport_security: name: Strict-Transport-Security value: max-age=15768000; includeSubDomains always: true #header_name: #name: Header-X #value: Value-X #always: false proxy_connect_timeout: null proxy_pass: http://backend #rewrites: # - /foo(.*) /$1 break #proxy_pass_request_body: off #allows: # - 192.168.1.0/24 #denies: # - all proxy_set_header: header_host: name: Host value: $host header_x_real_ip: name: X-Real-IP value: $remote_addr header_x_forwarded_for: name: X-Forwarded-For value: $proxy_add_x_forwarded_for header_x_forwarded_proto: name: X-Forwarded-Proto value: $scheme #header_upgrade: #name: Upgrade #value: $http_upgrade #header_connection: #name: Connection #value: "Upgrade" #header_random: #name: RandomName #value: RandomValue #internal: false #proxy_store: off #proxy_store_acccess: user:rw proxy_read_timeout: null proxy_send_timeout: null proxy_ssl: cert: /etc/ssl/certs/proxy_default.crt key: /etc/ssl/private/proxy_default.key trusted_cert: /etc/ssl/certs/proxy_ca.crt protocols: TLSv1 TLSv1.1 TLSv1.2 ciphers: HIGH:!aNULL:!MD5 verify: false verify_depth: 1 session_reuse: true proxy_cache: backend_proxy_cache proxy_cache_valid: - code: 200 time: 10m - code: 301 time: 1m proxy_temp_path: path: /var/cache/nginx/proxy/backend/temp proxy_cache_lock: false proxy_cache_min_uses: 3 proxy_cache_revalidate: false proxy_cache_use_stale: - http_403 - http_404 proxy_ignore_headers: - Vary - Cache-Control proxy_cookie_path: path: /web/ replacement: / proxy_buffering: false proxy_http_version: 1.0 websocket: false auth_basic: null auth_basic_user_file: null try_files: $uri $uri/index.html $uri.html =404 #auth_request: /auth #auth_request_set: #name: $auth_user #value: $upstream_http_x_user #returns: #return302: #code: 302 #url: https://sso.somehost.local/?url=https://$http_host$request_uri #custom_options: [] health_check_plus: false returns: return301: location: / code: 301 value: http://$host$request_uri proxy_cache: proxy_cache_path: - path: /var/cache/nginx/proxy/backend keys_zone: name: backend_proxy_cache size: 10m levels: "1:2" max_size: 10g inactive: 60m use_temp_path: true proxy_temp_path: path: /var/cache/nginx/proxy/temp proxy_cache_valid: - code: 200 time: 10m - code: 301 time: 1m proxy_cache_lock: true proxy_cache_min_uses: 5 proxy_cache_revalidate: true proxy_cache_use_stale: - error - timeout proxy_ignore_headers: - Expires upstreams: upstream1: name: backend lb_method: least_conn zone_name: backend_mem_zone zone_size: 64k sticky_cookie: false servers: server1: address: localhost port: 8081 weight: 1 health_check: max_fails=1 fail_timeout=10s #custom_options: [] #custom_options: [] # Enable NGINX status data. # Will enable 'stub_status' in NGINX Open Source and 'status' in NGINX Plus. # Note - 'status' has been deprecated since NGINX Plus R13. # Default is false. nginx_status_enable: false nginx_status_location: /etc/nginx/conf.d/stub_status.conf nginx_status_port: 80 # Enable NGINX Plus REST API, write access to the REST API, and NGINX Plus dashboard. # Requires NGINX Plus. # Default is false. nginx_rest_api_enable: false nginx_rest_api_template_file: http/api.conf.j2 nginx_rest_api_file_location: /etc/nginx/conf.d/api.conf nginx_rest_api_port: 80 nginx_rest_api_write: false nginx_rest_api_dashboard: false # Enable creating dynamic templated NGINX stream configuration files. # Defaults will not produce a valid configuration. Instead they are meant to showcase # the options available for templating. Each key represents a new configuration file. nginx_stream_template_enable: false nginx_stream_template: default: template_file: stream/default.conf.j2 conf_file_name: default.conf conf_file_location: /etc/nginx/conf.d/stream/ network_streams: default: listen_address: localhost listen_port: 80 udp_enable: false include_files: [] proxy_pass: backend proxy_timeout: 3s proxy_connect_timeout: 1s proxy_protocol: false proxy_ssl: cert: /etc/ssl/certs/proxy_default.crt key: /etc/ssl/private/proxy_default.key trusted_cert: /etc/ssl/certs/proxy_ca.crt protocols: TLSv1 TLSv1.1 TLSv1.2 ciphers: HIGH:!aNULL:!MD5 verify: false verify_depth: 1 session_reuse: true health_check_plus: false #custom_options: [] upstreams: upstream1: name: backend lb_method: least_conn zone_name: backend zone_size: 64k sticky_cookie: false servers: server1: address: localhost port: 8080 weight: 1 health_check: max_fails=1 fail_timeout=10s #custom_options: [] #custom_options: [] ``` 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. ```yaml --- - hosts: localhost become: true roles: - role: nginxinc.nginx ``` 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 ``` 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: - role: nginxinc.nginx vars: nginx_http_template_enable: true nginx_http_template: default: template_file: http/default.conf.j2 conf_file_name: default.conf conf_file_location: /etc/nginx/conf.d/ 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 ``` 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: - role: nginxinc.nginx vars: nginx_http_template_enable: true nginx_http_template: default: template_file: http/default.conf.j2 conf_file_name: default.conf conf_file_location: /etc/nginx/conf.d/ servers: server1: listen: listen_localhost: #ip: 0.0.0.0 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 upstreams: upstream_1: name: frontend_servers lb_method: least_conn zone_name: frontend zone_size: 64k sticky_cookie: false servers: frontend_server_1: address: 0.0.0.0 port: 8081 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: 0.0.0.0 port: 8082 weight: 1 health_check: max_fails=3 fail_timeout=5s frontend: template_file: http/default.conf.j2 conf_file_name: frontend_default.conf conf_file_location: /etc/nginx/conf.d/ servers: server1: listen: listen_localhost: ip: 0.0.0.0 port: 8081 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 backend: template_file: http/default.conf.j2 conf_file_name: backend_default.conf conf_file_location: /etc/nginx/conf.d/ servers: server1: listen: listen_localhost: ip: 0.0.0.0 port: 8082 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 ``` This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost and installing NGINX Plus. ```yaml --- - hosts: localhost become: true roles: - role: nginxinc.nginx vars: nginx_type: plus ``` 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. ```yaml - hosts: localhost become: true roles: - role: nginxinc.nginx vars: nginx_type: plus nginx_rest_api_enable: true nginx_rest_api_port: 80 nginx_rest_api_write: true nginx_controller_enable: true nginx_controller_api_key: nginx_controller_api_endpoint: https:///1.4 ``` 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. ```yaml --- - hosts: localhost become: true roles: - role: nginxinc.nginx vars: nginx_enable: false nginx_unit_enable: true nginx_unit_modules: - unit-php - unit-perl ``` 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](https://github.com/alessfg) [Grzegorz Dzien](https://github.com/gdzien) © [NGINX, Inc.](https://www.nginx.com/) 2018 - 2019