sebclem/ansible-role-nginx
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update docs (#257)

Browse Source
This commit is contained in:
Alessandro Fael Garcia 2020-06-04 13:05:38 +02:00 committed by GitHub
parent b254348851
commit 19fcdf0158
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 241 additions and 281 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/pull_request_template.md vendored
View File

@ -5,6 +5,6 @@ Describe the use case and detail of the change. If this PR addresses an issue on
Before creating a PR, run through this checklist and mark each as complete.
- [ ] I have read the [CONTRIBUTING](https://github.com/nginxinc/ansible-role-nginx/blob/master/CONTRIBUTING.md) document
- [ ] I have added Molecule tests that prove my fix is effective or that my feature works
- [ ] If necessary, I have added Molecule tests that prove my fix is effective or that my feature works
- [ ] I have checked that all unit tests pass after adding my changes
- [ ] If required, I have updated necessary documentation (`defaults/main/` and `README.md`)

201
CHANGELOG.md Normal file
View File

@ -0,0 +1,201 @@
# Changelog
## 0.14.0
This is a relatively minor release, but it includes a potential breaking change (hence the version bump). The one major new feature is the ability to install/build NGINX Open Source from source.
Features:
* Install/build NGINX from source options now available
* Implement NGINX http sub module templating
* NGINX config is now correctly validated each run
* SSL Private Key data is hidden when running the role with the --diff flag
Bug fixes:
* The role should no longer sporadically cause apt update to fail in amd64 systems when installing NGINX from an official repository
* Modules should now correctly install when using a specific NGINX Plus version
Breaking changes:
* The NGINX Controller agent can no longer be installed using this role. Please use the Ansible collection linked in the README
## 0.13.0
Features:
* Improve NGINX http templating:
* Multiple server support in HTTP contexts
* Header support
* OCSP stapling
* Improved proxy settings
* Logging settings
* Improved SSL settings
* Improved authentication settings
* Max body size support
* Improved listen templating
* Switch to Molecule for testing
* Add support for Debian Buster
* Support for specifying which version of NGINX to install
* Split default variables into multiple functional files
* Improve support for Alpine distributions
* Support for updating or removing NGINX from your system
* Implemented tags to support running specific tasks instead of the whole role
Bug fixes:
* Module installation when using NGINX Plus has been fixed
* Websockets templating has been reenabled after being accidentally deleted
* When deleting your NGINX Plus license from the system, the NGINX Plus repository will also be deleted to prevent issues further down the line if you run a repository update since there will not be a license anymore to authenticate into the NGINX Plus repository.
Breaking changes:
* The new listen templating options are not backwards with the previous listen templating options. Check the `README` or `molecule/template_module/playbook.yml` for examples on how to use the new listen template.
* BSD and Linux NGINX installation tasks have undergone some major changes. As such, you may have to update your playbooks accordingly.
## 0.12.0
Features:
* Improve NGINX http templating - following parameters are now supported:
* Websockets
* Basic authentication
* Proxy cache
* Proxy redirect
* Proxy timeouts
* SSL
* Root (in server context)
* Add basic NGINX stream templating
* Add support for RHEL 8 and Alpine Linux
Bug fixes:
* Fix module installation tasks
## 0.11.0
Features:
* Allow setting a custom apt and rpm signing key host
* Add support for enabling an http to https redirects
* Add ansible_managed to templates
* Rename html_app_name to web_server_name
* Rename load_balancer block to reverse_proxy
* Allow setting the listen port when using SSL
* Improve SSL defaults
* Allow setting http or https server locations in proxy_pass
Bug fixes:
* Ignore undefined values for autoindex and health check
* Clarify that the redirect variable refers to a http to https redirect
## 0.10.1
Bug fixes:
* Fix HTML template to use correct variable name
## 0.10.0
Features:
* Improve templating support for health checks, multiple location blocks, and auto indexing
Bug fixes:
* Fetching the NGINX signing key is now more reliable
* Fixed HTML templating
## 0.9.0
Features:
* Refactor NGINX templating and file uploading
* Add ability to upload and template HTML files
* Add ability to upload SSL keys and certificates
## 0.8.0
Features:
* Add ability to install NGINX Plus Controller agent
* Refactor installation of NGINX Amplify agent
* Rename variables to be prefixed with `nginx_`
Bug fixes:
* Correct spelling of name in `tasks/prerequisites/setup-debian.yml`
## 0.7.1
Features:
* Add enabled parameter to NGINX and NGINX Unit handlers
## 0.7.0
Features:
* Add Amazon Linux 2 support for NGINX Plus
* Add ability to delete NGINX Plus license after installation
Bug fixes:
* GeoIP module can now be properly installed
* Module installation will no longer fail if only one module is specified
## 0.6.0
Features:
* Improve NGINX Unit related documentation
* Add FreeBSD and Amazon Linux 2 support for NGINX Unit
* Allow users to install NGINX Unit without having to also install NGINX
## 0.5.0
Features:
* Add support for NGINX Unit
## 0.4.0
Features:
* Implement support for FreeBSD
* Allow users to select the default NGINX repository
## 0.3.0
New features:
* Improve Travis CI testing strategy
Bug fixes:
* Fix templating and push tasks
## 0.2.0
New features:
* Add support for all first party NGINX modules
Bug fixes:
* Role should now work correctly in distros with old versions of Python
* Rest API configuration will now only be created when rest_api_enable is set to true (an empty file would be created in previous versions if rest_api_enable was set to false)
* Uploading/dynamically generating files should now result in the files being uploaded/created to/in the correct directory
## 0.1.0 - Initial release
Initial release of the NGINX Ansible role. Features include:
* Install NGINX Open Source or NGINX Plus.
* Choose between stable or mainline NGINX Open Source.
* Install NGINX Amplify.
* Install NGINX Javascript, Perl, and ModSecurity WAF NGINX modules.
* Enable the NGINX Plus REST API and dashboard.
* Upload NGINX configuration files.
* Templated NGINX configuration system.

10
CONTRIBUTING.md
View File

@ -28,11 +28,11 @@ Follow our [Installation Guide](https://github.com/nginxinc/ansible-role-nginx/b
* The NGINX Ansible role is written in `yaml` and supports open source NGINX, NGINX Plus, NGINX Amplify, and NGINX Unit.
* The project follows the standard [Ansible role directory structure](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html)
* The main code is found at `tasks/`
* The main variables can be found at `defaults/main/`
* Configuration templates for NGINX can be found at `templates/`
* The main code is found in `tasks/`
* The main variables can be found in `defaults/main/`
* Configuration templates for NGINX can be found in `templates/`
* [Molecule](https://molecule.readthedocs.io/) tests can be found in `molecule/`.
* CI/CD is done via Travis using `.travis.yml` Deployment yaml files, and Helm files are found at `deployments/`
* CI/CD is done via Travis using `.travis.yml` deployment yaml files
## Contributing
@ -46,7 +46,7 @@ To suggest an enhancement, please create an issue on GitHub with the label `enha
### Open a Pull Request
* Fork the repo, create a branch, submit a PR when your changes are tested and ready for review
* Fork the repo, create a branch, submit a PR when your changes are tested (ideally using Molecule) and ready for review
* Fill in [our pull request template](https://github.com/nginxinc/ansible-role-nginx/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
Note: if you’d like to implement a new feature, please consider creating a feature request issue first to start a discussion about the feature.

282
README.md
View File

@ -180,279 +180,37 @@ FreeBSD:
Role Variables
--------------
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:
This role has multiple variables. The descriptions and defaults for all these variables can be found in the **`defaults/main`** directory in the following files:
- **[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
- **[defaults/main/main.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/defaults/main/main.yml):** NGINX installation variables
- **[defaults/main/amplify.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/defaults/main/amplify.yml):** NGINX Amplify agent installation variables
- **[defaults/main/template.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/defaults/main/template.yml):** NGINX configuration templating variables
- **[defaults/main/upload.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/defaults/main/upload.yml):** NGINX configuration/HTML/SSL upload variables
- **[defaults/main/linux.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/defaults/main/linux.yml):** Linux installation variables
- **[defaults/main/bsd.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/defaults/main/bsd.yml):** BSD installation variables
- **[defaults/main/unit.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/defaults/main/unit.yml):** NGINX Unit installation variables
Dependencies
------------
Example Playbooks
-----------------
None
Working functional playbook examples can be found in the **`molecule/common`** directory in the following files:
Example Playbook
----------------
- **[molecule/common/playbook_default.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/molecule/common/playbook_default.yml):** Install a specific version of NGINX and set up logrotate
- **[molecule/common/playbook_module.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/molecule/common/playbook_module.yml):** Install various NGINX supported modules
- **[molecule/common/playbook_source.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/molecule/common/playbook_source.yml):** Install NGINX from source
- **[molecule/common/playbook_stable_push.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/molecule/common/playbook_stable_push.yml):** Install NGINX using the stable branch and push a preexisting config from your system to your NGINX instance
- **[molecule/common/playbook_template.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/molecule/common/playbook_template.yml):** Use the NGINX configuration templating variables to create an NGINX configuration file
- **[molecule/common/playbook_unit.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/molecule/common/playbook_unit.yml):** Install NGINX Unit
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/
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
```
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
ssl: false
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
ssl: false
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 changes logs permission with custom logrotate config.
```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
server_name: localhost
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
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
nginx_logrotate_conf_enable: true
nginx_logrotate_conf:
paths:
- "/var/log/nginx/*.log"
options:
- daily
- missingok
- rotate 14
- compress
- delaycompress
- notifempty
- create 0644 www-data adm # Changes nginx logs permissions
- sharedscripts
```
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 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`.
Do note that if you install this repository via Ansible Galaxy, you will have to replace the role variable in the sample playbooks from `ansible-role-nginx` to `nginxinc.nginx`.
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)
You can find an Ansible role to help you install and configure NGINX App Protect [here](https://github.com/nginxinc/ansible-role-nginx-app-protect)
License
-------

14
molecule/common/playbook_default.yml
View File

@ -17,4 +17,18 @@
roles:
- role: ansible-role-nginx
vars:
nginx_debug_output: true
nginx_version: "{{ version }}"
nginx_logrotate_conf_enable: true
nginx_logrotate_conf:
paths:
- "/var/log/nginx/*.log"
options:
- daily
- missingok
- rotate 14
- compress
- delaycompress
- notifempty
- sharedscripts

13
molecule/common/playbook_template.yml
View File

@ -351,16 +351,3 @@
port: 8091
weight: 1
health_check: max_fails=1 fail_timeout=10s
nginx_logrotate_conf_enable: true
nginx_logrotate_conf:
paths:
- "/var/log/nginx/*.log"
options:
- daily
- missingok
- rotate 14
- compress
- delaycompress
- notifempty
- sharedscripts