Merge pull request #20 from alessfg/improve-docs-and-use-vars

Bring docs up to speed with other NGINX roles

Author: aknot242

.github/ISSUE_TEMPLATE/bug_report.md

@@ -12,15 +12,15 @@ A clear and concise description of what the bug is.
 
 **To reproduce**
 Steps to reproduce the behavior:
-1. Deploy NGINX Config role using playbook.yml
+1. Deploy NGINX App Protect role using playbook.yml
 2. View output/logs/configuration on '...'
 3. See error
 
 **Expected behavior**
 A clear and concise description of what you expected to happen.
 
 **Your environment:**
--   Version of the NGINX Config Role or specific commit
+-   Version of the NGINX App Protect role or specific commit
 -   Version of Ansible
 -   Target deployment platform
 

.github/pull_request_template.md

@@ -7,4 +7,4 @@ 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-app-protect/blob/main/CONTRIBUTING.md) document
 -   [ ] I have added Molecule tests that prove my fix is effective or that my feature works
 -   [ ] I have checked that all Molecule tests pass after adding my changes
--   [ ] I have updated any relevant documentation (`defaults/main/*.yml` and `README.md`)
+-   [ ] I have updated any relevant documentation (`defaults/main.yml`, `README.md` and `CHANGELOG.md`)

CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.2.0 (September 10, 2020)
+
+BREAKING CHANGES:
+
+*   All of the variables have been updated to prevent naming collisions when using other roles. Please see README.MD for new variable names.
+*   Example playbook has been removed by collection authors in favor of using the Molecule configuration as a 'known-working' implementation.
+
+ENHANCEMENTS:
+
+*   Huge refactoring by @alessfg to better unify this role with the structures present in the other nginxinc Ansible roles.
+*   Update Ansible to 2.9.13 and Ansible Lint to 4.3.4.
+*   Explicitly defined mode in relevant tasks for breaking changes in Ansible.
+*   Role refactored to separate install and configure operations in preparation for an upcoming role split.
+
+FEATURES:
+
+*   Molecule 3 testing foundation is in the project, and linting is being performed by TravisCI. Now time to write tests!
+
+BUG FIXES:
+
+*   The CentOS, RHEL, Debian and Ubuntu repositories have slightly changed to respond to a NAP repository deprecation activity. You may run into some duplication issues when running the role on a preexisting target that already has had NGINX installed using the role. To fix this, manually remove the old repository source.
+*   The RHEL and CentOS repository setups were incorrectly using a static gpgkey instead of using the variable as a source.
+
+## 0.1.0 (September 9, 2020)
+
+Supports App Protect 2.0, which brings a number of features including support for Ubuntu 18.04.
+
+Release notes for NGINX App Protect 2.0: docs.nginx.com/nginx-app-protect/releases/#release-2-0

CONTRIBUTING.md

@@ -14,25 +14,25 @@ The following is a set of guidelines for contributing to the NGINX App Protect A
 *   [Git Guidelines](#git-guidelines)
 *   [Ansible Guidelines](#ansible-guidelines)
 
-[Code of Conduct](CODE_OF_CONDUCT.md)
+[Code of Conduct](https://github.com/nginxinc/ansible-role-nginx-app-protect/blob/main/CODE_OF_CONDUCT.md)
 
 ## Ask a Question
 
-Please open an Issue on GitHub with the label `question`.
+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`.
 
 ## Getting Started
 
-Follow our [Installation Guide](README.md#Installation) to install Ansible and Molecule and get ready to use the NGINX App Protect Ansible role.
+Follow our [Installation Guide](https://github.com/nginxinc/ansible-role-nginx-app-protect/blob/main/README.md#Installation) to install Ansible and Molecule and get ready to use the NGINX Ansible role.
 
 ### Project Structure
 
-*   The NGINX App Protect Ansible role is written in `yaml` and supports open source NGINX Plus.
+*   The NGINX Ansible role is written in `yaml` and supports NGINX App Protect.
 *   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.yml`
+    *   Configuration templates for NGINX Plus and NGINX App Protect 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,27 +46,27 @@ 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
-*   Fill in [our pull request template](https://github.com/nginxinc/ansible-role-nginx-app-protect/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
+*   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-app-protect/blob/main/.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
 
+### 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 before you submit a PR to catch any potential 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>
+
 ### 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 summarized in the next few points
+*   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>

README.md

@@ -53,7 +53,13 @@ Ubuntu:
 Role Variables
 --------------
 
-This role has multiple variables. The descriptions and defaults for all these variables can be found in the **[defaults/main.yml](https://github.com/nginxinc/ansible-role-nginx-app-protect/blob/main/defaults/main.yml)**.
+This role has multiple variables. The descriptions and defaults for all these variables can be found in the **`defaults`** directory in the following files:
+
+-   **[defaults/main.yml](https://github.com/nginxinc/ansible-role-nginx-app-protect/blob/main/defaults/main.yml)**: NGINX App Protect installation and configuration variables
+
+Similarly, descriptions and defaults for preset variables can be found in the **`vars`** directory in the following files:
+
+-   **[vars/main.yml](https://github.com/nginxinc/ansible-role-nginx-app-protect/blob/main/vars/main.yml):** List of supported NGINX App Protect platforms
 
 Dependencies
 ------------
@@ -67,119 +73,31 @@ Dependencies
 Example Playbook
 ----------------
 
-This is a sample playbook file for using the role to install NGINX App Protect on NGINX Plus and configure it using basic settings to all `wafs` inventory hosts.
-
-A copy of this is in the sample-playbook directory in this repo.
-
-First create a file for all the variables as `nginx-app-protect-vars.yml`
-
-```yaml
----
-# Specify whether you want to maintain your version of NGINX App Protect, upgrade to the latest version, or remove NGINX App Protect.
-# Can be used with `nginx_app_protect_version` to achieve fine grained control on which version of NGINX App Protect is installed/used on each playbook execution.
-# Using 'present' will install the latest version (or 'nginx_app_protect_version') of NGINX App Protect on a fresh install.
-# Using 'latest' will upgrade NGINX App Protect to the latest version (that matches your 'nginx_app_protect_version') of NGINX App Protect on every playbook execution.
-# Using 'absent' will remove NGINX App Protect from your system.
-# Default is present.
-nginx_app_protect_state: present
-
-# OPTIONAL: Installs a specific version of NGINX App Protect
-nginx_app_protect_version: 22
-
-# The installation of NGINX App Protect includes a base signature set, which may be out of date.
-# This option installs the latest NGINX App Protect signatures.
-nginx_app_protect_install_signatures: true
-
-# The installation of NGINX App Protect can include a page of frequently-updated, high-accuracy signatures called Threat Campaigns.
-# This option installs the latest NGINX App Protect Threat Campaigns signatures.
-nginx_app_protect_install_threat_campaigns: true
-
-# Creates basic configuration files and enables NGINX App Protect on the target host
-nginx_app_protect_configure: true
-
-# Removes the license (certificate and key) for the NGINX App Protect repositories on the target host(s) when playbook run is complete.
-nginx_app_protect_delete_license: true
-
-# If you have a RHEL subscription, NGINX App Protect's dependencies will use subscription repos.
-# Otherwise, it will source packages from CentOS' repositories.
-nginx_app_protect_use_rhel_subscription_repos: false
-
-# OPTIONAL: Choose where to fetch the NGINX App Protect and Security Updates signing keys from.
-# Default settings are the official NGINX signing key hosts.
-nginx_app_protect_signing_keys:
-  nginx_plus: https://cs.nginx.com/static/keys/nginx_signing.key
-  app_protect: https://cs.nginx.com/static/keys/app-protect.key
-  security_updates: https://cs.nginx.com/static/keys/app-protect-security-updates.key
-
-# For use with the nginx_app_protect_configure option to determine if the default security policy will be written to the target host
-# Used when `nginx_app_protect_configure: true`.
-nginx_app_protect_security_policy_template_enable: true
-
-# Default app protect enforcement mode. Values can be `blocking` or `transparent`.
-# Used when `nginx_app_protect_configure: true` and `nginx_app_protect_security_policy_template_enable: true`.
-nginx_app_protect_security_policy_enforcement_mode: blocking
-
-# For use with the nginx_app_protect_configure option to determine if the default log policy will be written to the target host.
-# Used when `nginx_app_protect_configure: true`.
-nginx_app_protect_log_policy_template_enable: true
-
-# Which violation types to log. Possible values: all, illegal, blocked
-# Used when `nginx_app_protect_configure: true` and `nginx_app_protect_log_policy_template_enable: true`.
-nginx_app_protect_log_policy_filter_request_type: all
-
-# For use with the nginx_app_protect_configure option to determine if the sample nginx.conf will be written to the target host.
-# Since this can be dangerous, this value is default to false in the role defaults.
-# Used when `nginx_app_protect_configure: true`.
-nginx_app_protect_conf_template_enable: true
-
-# For use with the nginx_app_protect_configure option to determine the syslog target to be injected
-# into the default log policy that will be written to the target host.
-# Used when `nginx_app_protect_conf_template_enable: true`.
-nginx_app_protect_log_policy_syslog_target: 10.1.1.8:5144
-
-# DEPRECATED: A proxy pass workload used in the sample nginx.conf for demo purposes.
-# Will be removed from this role in the future.
-# Used when `nginx_app_protect_conf_template_enable: true`.
-nginx_app_protect_demo_workload: http://10.1.10.105:8080
-
-# The location of the certificate and key to be used when downloading the packages onto the host.
-nginx_app_protect_license:
-  certificate: "{{ playbook_dir }}/license/nginx-repo.crt"
-  key: "{{ playbook_dir }}/license/nginx-repo.crt"
-```
-
-This is a sample playbook file for deploying the Ansible Galaxy NGINX App Protect role in a localhost and installing NGINX App Protect on NGINX Plus.
+A working functional playbook example can be found in the **`molecule/default`** directory in the following file:
 
-```yaml
----
-- hosts: wafs
-  remote_user: centos
-  pre_tasks:
-  - name: load the vars
-    include_vars:
-      file: "{{ playbook_dir }}/nginx-app-protect-vars.yml"
-  roles:
-    - nginxinc.nginx_app_protect
-```
-
-
-To run any of the above sample playbooks create a `nginx-app-protect-playbook.yml` file and paste the contents. Executing the Ansible Playbook is then as simple as executing `ansible-playbook nginx-app-protect-playbook.yml -b -i inventory`.
-
-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_app_protect` to `ansible-role-nginx-app-protect`.
+-   **[molecule/default/converge.yml](https://github.com/nginxinc/ansible-role-nginx-app_protect/blob/main/molecule/default/converge.yml):** Install and configure NGINX App Protect
 
 Other NGINX Roles
 -----------------
 
+You can find an Ansible role to install NGINX [here](https://github.com/nginxinc/ansible-role-nginx)
+
+You can find an Ansible role to configure NGINX [here](https://github.com/nginxinc/ansible-role-nginx-config)
+
 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 install NGINX Unit [here](https://github.com/nginxinc/ansible-role-nginx-unit)
+
 License
 -------
 
-[Apache License, Version 2.0](https://github.com/nginxinc/ansible-role-nginx-app-protect/blob/master/LICENSE)
+[Apache License, Version 2.0](https://github.com/nginxinc/ansible-role-nginx-app-protect/blob/main/LICENSE)
 
 Author Information
 ------------------
 
 [Daniel Edgar](https://github.com/aknot242)
 
+[Alessandro Fael Garcia](https://github.com/alessfg)
+
 © [F5 Networks, Inc.](https://www.f5.com/) 2020

defaults/main.yml

@@ -45,38 +45,6 @@ nginx_app_protect_timeout: 180
 # App Protect Temporary Directory to use (Default: /tmp)
 nginx_app_protect_tempdir: /tmp
 
-# populate this dictionary of lists with appropriate values from the ansible_distribution and ansible_distribution_version facts
-nginx_app_protect_linux_families:
-  CentOS:
-    - 7.4
-    - 7.5
-    - 7.6
-    - 7.7
-    - 7.8
-  RedHat:
-    - 7.4
-    - 7.5
-    - 7.6
-    - 7.7
-    - 7.8
-  Debian:
-    - 9.0
-    - 9.1
-    - 9.2
-    - 9.3
-    - 9.4
-    - 9.5
-    - 9.6
-    - 9.7
-    - 9.8
-    - 9.9
-    - 9.10
-    - 9.11
-    - 9.12
-    - 9.13
-  Ubuntu:
-    - 18.04
-
 nginx_app_protect_security_policy_template_enable: true
 nginx_app_protect_security_policy_template:
   template_file: app-protect-security-policy.j2

molecule/Dockerfile.j2

@@ -17,27 +17,27 @@ ENV {{ var }} {{ value }}
 RUN \
   if [ $(command -v apt-get) ]; then \
     apt-get update \
-    && DEBIAN_FRONTEND=noninteractive apt-get install -y python3 sudo bash ca-certificates iproute2 python3-apt python-apt aptitude systemd systemd-sysv procps curl \
+    && DEBIAN_FRONTEND=noninteractive apt-get install -y aptitude bash ca-certificates curl iproute2 python-apt python3 python3-apt procps sudo systemd systemd-sysv \
     && apt-get clean; \
   elif [ $(command -v dnf) ]; then \
     dnf makecache \
-    && dnf --assumeyes install /usr/bin/python3 /usr/bin/python3-config /usr/bin/dnf-3 bash iproute \
+    && dnf --assumeyes install bash iproute /usr/bin/dnf-3 /usr/bin/python3 /usr/bin/python3-config \
     && dnf clean all; \
   elif [ $(command -v yum) ]; then \
     yum makecache fast \
-    && yum install -y /usr/bin/python /usr/bin/python2-config sudo yum-plugin-ovl bash iproute \
+    && yum install -y bash iproute /usr/bin/python /usr/bin/python2-config sudo yum-plugin-ovl \
     && sed -i 's/plugins=0/plugins=1/g' /etc/yum.conf \
     && yum clean all; \
   elif [ $(command -v zypper) ]; then \
     zypper refresh \
-    && zypper install -y python3 sudo bash iproute2 \
+    && zypper install -y bash iproute2 python3 sudo \
     && zypper clean -a; \
   elif [ $(command -v apk) ]; then \
     apk update \
-    && apk add --no-cache python3 sudo bash ca-certificates curl openrc; \
+    && apk add --no-cache bash ca-certificates curl openrc python3 sudo; \
     echo 'rc_provide="loopback net"' >> /etc/rc.conf; \
   elif [ $(command -v xbps-install) ]; then \
     xbps-install -Syu \
-    && xbps-install -y python3 sudo bash ca-certificates iproute2 \
+    && xbps-install -y bash ca-certificates iproute2 python3 sudo \
     && xbps-remove -O; \
   fi

vars/main.yml

@@ -1 +1,32 @@
 ---
+# Populate this dictionary of lists with appropriate values from ansible_distribution and ansible_distribution_version facts
+nginx_app_protect_linux_families:
+  CentOS:
+    - 7.4
+    - 7.5
+    - 7.6
+    - 7.7
+    - 7.8
+  RedHat:
+    - 7.4
+    - 7.5
+    - 7.6
+    - 7.7
+    - 7.8
+  Debian:
+    - 9.0
+    - 9.1
+    - 9.2
+    - 9.3
+    - 9.4
+    - 9.5
+    - 9.6
+    - 9.7
+    - 9.8
+    - 9.9
+    - 9.10
+    - 9.11
+    - 9.12
+    - 9.13
+  Ubuntu:
+    - 18.04