Update docs (#257)
This commit is contained in:
parent
b254348851
commit
19fcdf0158
2
.github/pull_request_template.md
vendored
2
.github/pull_request_template.md
vendored
@ -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
201
CHANGELOG.md
Normal 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.
|
@ -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
282
README.md
@ -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
|
||||
-------
|
||||
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user