From 19fcdf01580848cdc1dc1275d459db99b42c97f5 Mon Sep 17 00:00:00 2001 From: Alessandro Fael Garcia Date: Thu, 4 Jun 2020 13:05:38 +0200 Subject: [PATCH] Update docs (#257) --- .github/pull_request_template.md | 2 +- CHANGELOG.md | 201 ++++++++++++++++++ CONTRIBUTING.md | 10 +- README.md | 282 ++------------------------ molecule/common/playbook_default.yml | 14 ++ molecule/common/playbook_template.yml | 13 -- 6 files changed, 241 insertions(+), 281 deletions(-) create mode 100644 CHANGELOG.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d2cf8ae..8adcac4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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`) diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..1cd878b --- /dev/null +++ b/CHANGELOG.md @@ -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b71585a..4073958 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index 5c1bf38..02d7ab2 100644 --- a/README.md +++ b/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 ------- diff --git a/molecule/common/playbook_default.yml b/molecule/common/playbook_default.yml index aa04765..4591f6a 100644 --- a/molecule/common/playbook_default.yml +++ b/molecule/common/playbook_default.yml @@ -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 diff --git a/molecule/common/playbook_template.yml b/molecule/common/playbook_template.yml index a492a0a..3ff9e57 100644 --- a/molecule/common/playbook_template.yml +++ b/molecule/common/playbook_template.yml @@ -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