You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Aug 9, 2022. It is now read-only.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+27-26Lines changed: 27 additions & 26 deletions
Original file line number
Diff line number
Diff line change
@@ -11,29 +11,30 @@ The following is a set of guidelines for contributing to the NGINX Controller Ge
11
11
[Contributing](#contributing)
12
12
13
13
[Code Guidelines](#code-guidelines)
14
-
*[Git Guidelines](#git-guidelines)
15
-
*[Ansible Guidelines](#ansible-guidelines)
16
14
17
-
[Code of Conduct](https://github.com/nginxinc/ansible-role-nginx-controller-generate-token/blob/main/CODE_OF_CONDUCT.md)
15
+
*[Git Guidelines](#git-guidelines)
16
+
*[Ansible Guidelines](#ansible-guidelines)
17
+
18
+
[Code of Conduct](https://github.com/nginxinc/ansible_role_nginx_controller_generate_token/blob/main/CODE_OF_CONDUCT.md)
18
19
19
20
## Ask a Question
20
21
21
22
Don't know how something works? Curious if the role can achieve your desired functionality? Please open an Issue on GitHub with the label `question`.
22
23
23
24
## Getting Started
24
25
25
-
Follow our [Installation Guide](https://github.com/nginxinc/ansible-role-nginx-controller-generate-token/blob/main/README.md#Installation) to install Ansible and Molecule and get ready to use the NGINX Controller Generate Token Ansible role.
26
+
Follow our [Installation Guide](https://github.com/nginxinc/ansible_role_nginx_controller_generate_token/blob/main/README.md#Installation) to install Ansible and Molecule and get ready to use the NGINX Controller Generate Token Ansible role.
26
27
27
28
### Project Structure
28
29
29
-
*The NGINX Controller Generate Token Ansible role is written in `yaml` and supports NGINX Controller.
30
-
*The project follows the standard [Ansible role directory structure](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html)
31
-
*The main code is found in [`tasks/`](https://github.com/nginxinc/ansible-role-nginx-controller-generate-token/blob/main/tasks/).
32
-
*Variables can be found in [`defaults/main/`](https://github.com/nginxinc/ansible-role-nginx-controller-generate-token/blob/main/defaults/main/).
33
-
*"Constant" variables can be found in [`vars/main.yml`](https://github.com/nginxinc/ansible-role-nginx-controller-generate-token/blob/main/vars/main.yml).
34
-
*Configuration templates for NGINX can be found in [`templates/`](https://github.com/nginxinc/ansible-role-nginx-controller-generate-token/blob/main/templates/).
35
-
*[Molecule](https://molecule.readthedocs.io/) tests can be found in [`molecule/`](https://github.com/nginxinc/ansible-role-nginx-controller-generate-token/blob/main/molecule/).
36
-
*CI/CD is done via GitHub actions using the workflow files found in [`.github/workflows/`](https://github.com/nginxinc/ansible-role-nginx-controller-generate-token/blob/main/.github/workflows/).
30
+
* The NGINX Controller Generate Token Ansible role is written in `yaml` and supports NGINX Controller.
31
+
* The project follows the standard [Ansible role directory structure](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html)
32
+
*The main code is found in [`tasks/`](https://github.com/nginxinc/ansible_role_nginx_controller_generate_token/blob/main/tasks/).
33
+
*Variables can be found in [`defaults/main/`](https://github.com/nginxinc/ansible_role_nginx_controller_generate_token/blob/main/defaults/main/).
34
+
*"Constant" variables can be found in [`vars/main.yml`](https://github.com/nginxinc/ansible_role_nginx_controller_generate_token/blob/main/vars/main.yml).
35
+
*Configuration templates for NGINX can be found in [`templates/`](https://github.com/nginxinc/ansible_role_nginx_controller_generate_token/blob/main/templates/).
36
+
*[Molecule](https://molecule.readthedocs.io/) tests can be found in [`molecule/`](https://github.com/nginxinc/ansible_role_nginx_controller_generate_token/blob/main/molecule/).
37
+
*CI/CD is done via GitHub actions using the workflow files found in [`.github/workflows/`](https://github.com/nginxinc/ansible_role_nginx_controller_generate_token/blob/main/.github/workflows/).
37
38
38
39
## Contributing
39
40
@@ -47,27 +48,27 @@ To suggest an enhancement, please create an issue on GitHub with the label `enha
47
48
48
49
### Open a Pull Request
49
50
50
-
*Fork the repo, create a branch, implement your changes, add any relevant Molecule tests, submit a PR when your changes are **tested** (using Molecule) and ready for review.
51
-
*Fill in [our pull request template](https://github.com/nginxinc/ansible-role-nginx-controller-generate-token/blob/main/.github/pull_request_template.md).
51
+
* Fork the repo, create a branch, implement your changes, add any relevant Molecule tests, submit a PR when your changes are **tested** (using Molecule) and ready for review.
52
+
* Fill in [our pull request template](https://github.com/nginxinc/ansible_role_nginx_controller_generate_token/blob/main/.github/pull_request_template.md).
52
53
53
54
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.
54
55
55
56
## Code Guidelines
56
57
57
58
### Ansible Guidelines
58
59
59
-
*Run `molecule lint` over your code to automatically resolve a lot of `yaml` and Ansible style issues.
60
-
*Run `molecule test` on your code before you submit a PR to catch any potential issues. If you are testing a specific molecule scenario, run `molecule test -s <scenario>`.
61
-
*Follow these guides on some good practices for Ansible:
* Run `molecule lint` over your code to automatically resolve a lot of `yaml` and Ansible style issues.
61
+
* Run `molecule test` on your code before you submit a PR to catch any potential issues. If you are testing a specific molecule scenario, run `molecule test -s <scenario>`.
62
+
* Follow these guides on some good practices for Ansible:
*Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR
68
-
*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
69
-
* In the subject line, use the present tense ("Add feature" not "Added feature")
70
-
* In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
71
-
* Limit the subject line to 72 characters or less
72
-
* Reference issues and pull requests liberally after the subject line
73
-
* 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`)
68
+
* Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR
69
+
* 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
70
+
* In the subject line, use the present tense ("Add feature" not "Added feature")
71
+
* In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
72
+
* Limit the subject line to 72 characters or less
73
+
* Reference issues and pull requests liberally after the subject line
74
+
* 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`)
A running [NGINX Controller](https://www.nginx.com/products/nginx-controller/) instance.
13
10
14
-
-- All the below variables are required --
11
+
### Ansible
15
12
16
-
`nginx_controller_user_email` - The email address of the NGINX Controller user.
13
+
* This role is developed and tested with [maintained](https://docs.ansible.com/ansible/devel/reference_appendices/release_and_maintenance.html) versions of Ansible core (above `2.11`).
14
+
* You will need to run this role as a root user using Ansible's `become` parameter. Make sure you have set up the appropriate permissions on your target hosts.
15
+
* Instructions on how to install Ansible can be found in the [Ansible website](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#upgrading-ansible-from-version-2-9-and-older-to-version-2-10-or-later).
17
16
18
-
`nginx_controller_user_password` - The password that corresponds to the controller.user_email.
17
+
### Molecule (Optional)
19
18
20
-
`nginx_controller_fqdn` - The DNS name of your NGINX Controller installation.
19
+
* Molecule is used to test the various functionalities of the role. The recommended version of Molecule to test this role is `3.3`.
20
+
* Instructions on how to install Molecule can be found in the [Molecule website](https://molecule.readthedocs.io/en/latest/installation.html). _You will also need to install the Molecule Docker driver._
21
21
22
-
`nginx_controller_auth_token` - Variable returned by this Role and consumed by others to authenticate to the NGINX Controller API.
22
+
## Installation
23
23
24
-
Dependencies
25
-
------------
24
+
### Ansible Galaxy
26
25
27
-
none
26
+
Use `ansible-galaxy install nginxinc.nginx_controller_generate_token` to install the latest stable release of the role on your system. Alternatively, if you have already installed the role, use `ansible-galaxy install -f nginxinc.nginx_controller_generate_token` to update the role to the latest release.
28
27
29
-
Example Playbook
30
-
----------------
28
+
### Git
29
+
30
+
Use `git clone https://github.com/nginxinc/ansible_role_nginx_controller_generate_token.git` to pull the latest edge commit of the role from GitHub.
31
+
32
+
## Platforms
33
+
34
+
The NGINX Controller generate token Ansible role supports all platforms that support Ansible `2.11`, some of them being:
35
+
36
+
```yaml
37
+
Alpine:
38
+
- all
39
+
Amazon Linux:
40
+
- all
41
+
Amazon Linux 2:
42
+
- all
43
+
CentOS:
44
+
- all
45
+
Debian:
46
+
- all
47
+
FreeBSD:
48
+
- all
49
+
RHEL:
50
+
- all
51
+
Ubuntu:
52
+
- all
53
+
```
54
+
55
+
## Role Variables
56
+
57
+
| Variable | Default | Description | Required |
58
+
| -------- | ------- | ----------- | -------- |
59
+
| `nginx_controller_user_email` | `""` | The email address of the NGINX Controller user | Yes |
60
+
| `nginx_controller_user_password` | `""` | The password of the NGINX Controller user | Yes |
61
+
| `nginx_controller_fqdn` | `""` | The FQDN of NGINX Controller | Yes |
62
+
| `nginx_controller_validate_certs` | `false` | Whether NGINX Controller SSL cert should be validated or not | No |
63
+
64
+
In addition, this role returns the following variable:
65
+
`nginx_controller_auth_token`- Authentication token used to authenticate to the NGINX Controller API.
66
+
67
+
## Example Playbook
31
68
32
69
To use this role you can create a playbook such as the following:
33
70
34
71
```yaml
72
+
---
35
73
- hosts: localhost
36
74
gather_facts: no
37
-
38
75
tasks:
39
76
- name: Retrieve the NGINX Controller auth token
40
77
include_role:
@@ -46,24 +83,30 @@ To use this role you can create a playbook such as the following:
46
83
nginx_controller_validate_certs: false
47
84
```
48
85
49
-
You can then run `ansible-playbook nginx_controller_generate_token.yaml` to execute the playbook.
86
+
## Other NGINX Ansible Collections and Roles
50
87
51
-
Alternatively, you can also pass/override any variables at run time using the `--extra-vars` or `-e` flag like so `ansible-playbook nginx_controller_generate_token.yaml -e "[email protected] nginx_controller_user_password=notsecure nginx_controller_fqdn=controller.example.local nginx_controller_validate_certs=false"`
88
+
You can find the Ansible NGINX Core collection of roles to install and configure NGINX Open Source, NGINX Plus, and NGINX App Protect [here](https://github.com/nginxinc/ansible-collection-nginx).
52
89
53
-
You can also pass/override any variables by passing a `yaml` file containing any number of variables like so `ansible-playbook nginx_controller_generate_token.yaml -e "@nginx_controller_token_vars.yaml"`
90
+
You can find the Ansible NGINX role to install NGINX OSS and NGINX Plus [here](https://github.com/nginxinc/ansible-role-nginx).
54
91
55
-
License
56
-
-------
92
+
You can find the Ansible NGINX configuration role to configure NGINX [here](https://github.com/nginxinc/ansible-role-nginx-config).
57
93
58
-
[Apache License, Version 2.0](./LICENSE)
94
+
You can find the Ansible NGINX App Protect role to install and configure NGINX App Protect WAF and NGINX App Protect DoS [here](https://github.com/nginxinc/ansible-role-nginx-app-protect).
59
95
60
-
Author Information
61
-
------------------
96
+
You can find the Ansible NGINX Controller collection of roles to install and configure NGINX Controller [here](https://github.com/nginxinc/ansible-collection-nginx_controller).
62
97
63
-
[Brian Ehlert](https://github.com/brianehlert)
98
+
You can find the Ansible NGINX Unit role to install NGINX Unit [here](https://github.com/nginxinc/ansible-role-nginx-unit).
99
+
100
+
## License
101
+
102
+
[Apache License, Version 2.0](https://github.com/nginxinc/ansible-role-nginx-config/blob/main/LICENSE)
0 commit comments