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

Improve documentation (#206)

Browse Source 
* Create CONTRIBUTING.md
* Add PR template
* Tweak .yamllint
* Update README playbook examples
This commit is contained in:
Alessandro Fael Garcia 2019-12-13 12:11:30 -08:00 committed by GitHub
parent 36ba93a5d7
commit b5baf3a2ae
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 192 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.github/pull_request_template.md vendored Normal file
View File

@ -0,0 +1,10 @@
### Proposed changes
Describe the use case and detail of the change. If this PR addresses an issue on GitHub, make sure to include a link to that issue here in this description (not in the title of the PR).
### Checklist
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
- [ ] I have checked that all unit tests pass after adding my changes
- [ ] If required, I have updated necessary documentation (`defaults/main/` and `README.md`)

1
.yamllint
View File

@ -7,7 +7,6 @@ rules:
brackets: brackets:
max-spaces-inside: 1 max-spaces-inside: 1
level: error level: error
comments: disable
comments-indentation: disable comments-indentation: disable
line-length: disable line-length: disable
truthy: disable truthy: disable

72
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,72 @@
# Contributing Guidelines
The following is a set of guidelines for contributing to the NGINX Ansible role. We really appreciate that you are considering contributing!
#### Table Of Contents
[Ask a Question](#ask-a-question)
[Getting Started](#getting-started)
[Contributing](#contributing)
[Code Guidelines](#code-guidelines)
* [Git Guidelines](#git-guidelines)
* [Ansible Guidelines](#ansible-guidelines)
[Code of Conduct](https://github.com/nginxinc/ansible-role-nginx/blob/master/CODE_OF_CONDUCT.md)
## Ask a Question
Please open an Issue on GitHub with the label `question`.
## Getting Started
Follow our [Installation Guide](https://github.com/nginxinc/ansible-role-nginx/blob/master/README.md#Installation) to install Ansible and Molecule and get ready to use the NGINX Ansible role.
### Project Structure
* The NGINX Ansible role is written in `yaml` and supports open source NGINX, NGINX Plus, NGINX Amplify, NGINX Controller, 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/`
* [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/`
## Contributing
### Report a Bug
To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the issue has not already been reported.
### Suggest an Enhancement
To suggest an enhancement, please create an issue on GitHub with the label `enhancement` using the available feature issue template.
### Open a Pull Request
* Fork the repo, create a branch, submit a PR when your changes are tested 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.
## Code Guidelines
### Git Guidelines
* Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR
* Follow the guidelines of writing a good commit message as described here <https://chris.beams.io/posts/git-commit/> and summarised in the next few points
* In the subject line, use the present tense ("Add feature" not "Added feature")
* In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
* Limit the subject line to 72 characters or less
* Reference issues and pull requests liberally after the subject line
* Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in your text editor to write a good message instead of `git commit -am`)
### Ansible Guidelines
* Run `molecule lint` over your code to automatically resolve a lot of `yaml` and Ansible style issues.
* Run `molecule test --all` on your code to catch any other issues.
* Follow these guides on some good practices for Ansible:
* <https://www.ansible.com/blog/ansible-best-practices-essentials>
* <https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html>

55
README.md
View File

@ -13,14 +13,29 @@ Requirements
**Ansible** **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 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. Backwards compatibility is not guaranteed.
Instructions on how to install Ansible can be found in the [Ansible website](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html).
**Molecule**
Molecule is used to test the various functionailities of the role. Instructions on how to install Molecule can be found in the [Molecule website](https://molecule.readthedocs.io/en/stable/installation.html).
Installation
------------
**Ansible Galaxy** **Ansible Galaxy**
Use `ansible-galaxy install nginxinc.nginx` to install the role on your system. Use `ansible-galaxy install nginxinc.nginx` to install the latest stable release of 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/): **Git**
Use `git clone https://github.com/nginxinc/ansible-role-nginx.git` to pull the latest edge commit of the role from GitHub.
Platforms
---------
The NGINX Ansible role supports all platforms supported by [NGINX Open Source](https://nginx.org/en/linux_packages.html#mainline), [NGINX Plus](https://www.nginx.com/products/technical-specs/), the [NGINX Amplify agent](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-faq.md#21-what-operating-systems-are-supported), the [NGINX Controller agent](https://docs.nginx.com/nginx-controller/technical-specs/#nginx-controller-agent-technical-specifications), and [NGINX Unit](https://unit.nginx.org/installation/#official-packages):
**NGINX Open Source** **NGINX Open Source**
@ -120,7 +135,6 @@ Debian:
- stretch - stretch
Ubuntu: Ubuntu:
versions: versions:
- trusty
- xenial - xenial
- bionic - bionic
RedHat: RedHat:
@ -245,18 +259,23 @@ This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a
template_file: http/default.conf.j2 template_file: http/default.conf.j2
conf_file_name: default.conf conf_file_name: default.conf
conf_file_location: /etc/nginx/conf.d/ conf_file_location: /etc/nginx/conf.d/
port: 80 servers:
server_name: localhost server1:
error_page: /usr/share/nginx/html listen:
autoindex: false listen_localhost:
web_server: # ip: 0.0.0.0
locations: port: 80
default: server_name: localhost
location: / error_page: /usr/share/nginx/html
html_file_location: /usr/share/nginx/html autoindex: false
html_file_name: index.html web_server:
autoindex: false locations:
http_demo_conf: false 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. 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.
@ -278,7 +297,7 @@ This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a
server1: server1:
listen: listen:
listen_localhost: listen_localhost:
#ip: 0.0.0.0 # ip: 0.0.0.0
port: 80 port: 80
opts: opts:
- default_server - default_server

146
defaults/main/template.yml
View File

@ -17,7 +17,7 @@ nginx_main_template:
conf_file_location: /etc/nginx/ conf_file_location: /etc/nginx/
user: nginx user: nginx
worker_processes: auto worker_processes: auto
#worker_rlimit_nofile: 1024 # worker_rlimit_nofile: 1024
error_log: error_log:
location: /var/log/nginx/error.log location: /var/log/nginx/error.log
level: warn level: warn
@ -39,15 +39,15 @@ nginx_main_template:
cache: false cache: false
rate_limit: false rate_limit: false
keyval: false keyval: false
#server_tokens: "off" # server_tokens: "off"
http_global_autoindex: false http_global_autoindex: false
#http_custom_options: [] # http_custom_options: []
stream_enable: false stream_enable: false
#stream_custom_options: [] # stream_custom_options: []
#auth_request_http: /auth # auth_request_http: /auth
#auth_request_set_http: # auth_request_set_http:
#name: $auth_user # name: $auth_user
#value: $upstream_http_x_user # value: $upstream_http_x_user
# Enable creating dynamic templated NGINX HTTP configuration files. # Enable creating dynamic templated NGINX HTTP configuration files.
# Defaults will not produce a valid configuration. Instead they are meant to showcase # Defaults will not produce a valid configuration. Instead they are meant to showcase
@ -62,9 +62,9 @@ nginx_http_template:
server1: server1:
listen: listen:
listen_localhost: listen_localhost:
ip: localhost # Wrap in square brackets for IPv6 addresses ip: localhost # Wrap in square brackets for IPv6 addresses
port: 8081 port: 8081
opts: [] # Listen opts like http2 which will be added (ssl is automatically added if you specify 'ssl:'). opts: [] # Listen opts like http2 which will be added (ssl is automatically added if you specify 'ssl:').
server_name: localhost server_name: localhost
include_files: [] include_files: []
error_page: /usr/share/nginx/html error_page: /usr/share/nginx/html
@ -75,26 +75,26 @@ nginx_http_template:
location: /var/log/nginx/error.log location: /var/log/nginx/error.log
level: warn level: warn
root: /usr/share/nginx/html root: /usr/share/nginx/html
#https_redirect: $host # https_redirect: $host
autoindex: false autoindex: false
auth_basic: null auth_basic: null
auth_basic_user_file: null auth_basic_user_file: null
try_files: $uri $uri/index.html $uri.html =404 try_files: $uri $uri/index.html $uri.html =404
#auth_request: /auth # auth_request: /auth
#auth_request_set: # auth_request_set:
#name: $auth_user # name: $auth_user
#value: $upstream_http_x_user # value: $upstream_http_x_user
client_max_body_size: 1m client_max_body_size: 1m
proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
add_headers: add_headers:
strict_transport_security: strict_transport_security:
name: Strict-Transport-Security name: Strict-Transport-Security
value: max-age=15768000; includeSubDomains value: max-age=15768000; includeSubDomains
always: true always: true
#header_name: # header_name:
#name: Header-X # name: Header-X
#value: Value-X # value: Value-X
#always: false # always: false
ssl: ssl:
cert: /etc/ssl/certs/default.crt cert: /etc/ssl/certs/default.crt
key: /etc/ssl/private/default.key key: /etc/ssl/private/default.key
@ -108,63 +108,63 @@ nginx_http_template:
trusted_cert: /etc/ssl/certs/root_CA_cert_plus_intermediates.crt trusted_cert: /etc/ssl/certs/root_CA_cert_plus_intermediates.crt
stapling: true stapling: true
stapling_verify: true stapling_verify: true
#custom_options: [] # custom_options: []
web_server: web_server:
locations: locations:
default: default:
location: / location: /
include_files: [] include_files: []
proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
add_headers: add_headers:
strict_transport_security: strict_transport_security:
name: Strict-Transport-Security name: Strict-Transport-Security
value: max-age=15768000; includeSubDomains value: max-age=15768000; includeSubDomains
always: true always: true
#header_name: # header_name:
#name: Header-X # name: Header-X
#value: Value-X # value: Value-X
#always: false # always: false
html_file_location: /usr/share/nginx/html html_file_location: /usr/share/nginx/html
html_file_name: index.html html_file_name: index.html
autoindex: false autoindex: false
auth_basic: null auth_basic: null
auth_basic_user_file: null auth_basic_user_file: null
try_files: $uri $uri/index.html $uri.html =404 try_files: $uri $uri/index.html $uri.html =404
#auth_request: /auth # auth_request: /auth
#auth_request_set: # auth_request_set:
#name: $auth_user # name: $auth_user
#value: $upstream_http_x_user # value: $upstream_http_x_user
client_max_body_size: 1m client_max_body_size: 1m
#returns: # returns:
#return302: # return302:
#code: 302 # code: 302
#url: https://sso.somehost.local/?url=https://$http_host$request_uri # url: https://sso.somehost.local/?url=https://$http_host$request_uri
#custom_options: [] # custom_options: []
http_demo_conf: false http_demo_conf: false
reverse_proxy: reverse_proxy:
locations: locations:
backend: backend:
location: / location: /
include_files: [] include_files: []
proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
add_headers: add_headers:
strict_transport_security: strict_transport_security:
name: Strict-Transport-Security name: Strict-Transport-Security
value: max-age=15768000; includeSubDomains value: max-age=15768000; includeSubDomains
always: true always: true
#header_name: # header_name:
#name: Header-X # name: Header-X
#value: Value-X # value: Value-X
#always: false # always: false
proxy_connect_timeout: null proxy_connect_timeout: null
proxy_pass: http://backend proxy_pass: http://backend
#rewrites: # rewrites:
# - /foo(.*) /$1 break # - /foo(.*) /$1 break
#proxy_pass_request_body: off # proxy_pass_request_body: off
#allows: # allows:
# - 192.168.1.0/24 # - 192.168.1.0/24
#denies: # denies:
# - all # - all
proxy_set_header: proxy_set_header:
header_host: header_host:
name: Host name: Host
@ -178,18 +178,18 @@ nginx_http_template:
header_x_forwarded_proto: header_x_forwarded_proto:
name: X-Forwarded-Proto name: X-Forwarded-Proto
value: $scheme value: $scheme
#header_upgrade: # header_upgrade:
#name: Upgrade # name: Upgrade
#value: $http_upgrade # value: $http_upgrade
#header_connection: # header_connection:
#name: Connection # name: Connection
#value: "Upgrade" # value: "Upgrade"
#header_random: # header_random:
#name: RandomName # name: RandomName
#value: RandomValue # value: RandomValue
#internal: false # internal: false
#proxy_store: off # proxy_store: off
#proxy_store_acccess: user:rw # proxy_store_acccess: user:rw
proxy_read_timeout: null proxy_read_timeout: null
proxy_send_timeout: null proxy_send_timeout: null
proxy_ssl: proxy_ssl:
@ -227,15 +227,15 @@ nginx_http_template:
auth_basic: null auth_basic: null
auth_basic_user_file: null auth_basic_user_file: null
try_files: $uri $uri/index.html $uri.html =404 try_files: $uri $uri/index.html $uri.html =404
#auth_request: /auth # auth_request: /auth
#auth_request_set: # auth_request_set:
#name: $auth_user # name: $auth_user
#value: $upstream_http_x_user # value: $upstream_http_x_user
#returns: # returns:
#return302: # return302:
#code: 302 # code: 302
#url: https://sso.somehost.local/?url=https://$http_host$request_uri # url: https://sso.somehost.local/?url=https://$http_host$request_uri
#custom_options: [] # custom_options: []
health_check_plus: false health_check_plus: false
returns: returns:
return301: return301:
@ -280,8 +280,8 @@ nginx_http_template:
port: 8081 port: 8081
weight: 1 weight: 1
health_check: max_fails=1 fail_timeout=10s health_check: max_fails=1 fail_timeout=10s
#custom_options: [] # custom_options: []
#custom_options: [] # custom_options: []
# Enable NGINX status data. # Enable NGINX status data.
# Will enable 'stub_status' in NGINX Open Source and 'status' in NGINX Plus. # Will enable 'stub_status' in NGINX Open Source and 'status' in NGINX Plus.
@ -330,7 +330,7 @@ nginx_stream_template:
verify_depth: 1 verify_depth: 1
session_reuse: true session_reuse: true
health_check_plus: false health_check_plus: false
#custom_options: [] # custom_options: []
upstreams: upstreams:
upstream1: upstream1:
name: backend name: backend
@ -344,5 +344,5 @@ nginx_stream_template:
port: 8080 port: 8080
weight: 1 weight: 1
health_check: max_fails=1 fail_timeout=10s health_check: max_fails=1 fail_timeout=10s
#custom_options: [] # custom_options: []
#custom_options: [] # custom_options: []