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. 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 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 - [ ] I have checked that all unit tests pass after adding my changes
- [ ] If required, I have updated necessary documentation (`defaults/main/` and `README.md`) - [ ] 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 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 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 code is found in `tasks/`
* The main variables can be found at `defaults/main/` * The main variables can be found in `defaults/main/`
* Configuration templates for NGINX can be found at `templates/` * Configuration templates for NGINX can be found in `templates/`
* [Molecule](https://molecule.readthedocs.io/) tests can be found in `molecule/`. * [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 ## Contributing
@ -46,7 +46,7 @@ To suggest an enhancement, please create an issue on GitHub with the label `enha
### Open a Pull Request ### 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) * 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. 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 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/main.yml](https://github.com/nginxinc/ansible-role-nginx/blob/master/defaults/main/main.yml):** NGINX installation variables
- **[defaults/main/amplify.yml](./defaults/main/amplify.yml):** NGINX Amplify agent 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](./defaults/main/template.yml):** NGINX configuration templating 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](./defaults/main/upload.yml):** NGINX configuration/HTML/SSL upload 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](./defaults/main/linux.yml):** Linux installation 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](./defaults/main/bsd.yml):** BSD 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](./defaults/main/unit.yml):** NGINX Unit 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. 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`.
```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`.
Other NGINX Roles 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 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 License
------- -------

14
molecule/common/playbook_default.yml
View File

@ -17,4 +17,18 @@
roles: roles:
- role: ansible-role-nginx - role: ansible-role-nginx
vars: vars:
nginx_debug_output: true
nginx_version: "{{ version }}" 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 port: 8091
weight: 1 weight: 1
health_check: max_fails=1 fail_timeout=10s 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