From 2a0babee43b901ff641fe6a25f414b0331ef32a7 Mon Sep 17 00:00:00 2001 From: nazunalika Date: Sun, 31 Jan 2021 02:04:46 -0700 Subject: [PATCH] Initial --- .pre-commit-config.yaml | 33 ++++++++++++ README.md | 112 ++++++++++++++++++++++++++++++++++++++++ defaults/main.yml | 2 + files/README.md | 1 + handlers/main.yml | 2 + tasks/main.yml | 4 ++ templates/README.md | 1 + tests/README.md | 3 ++ tests/inventory | 1 + tests/test.yml | 5 ++ vars/main.yml | 2 + 11 files changed, 166 insertions(+) create mode 100644 .pre-commit-config.yaml create mode 100644 README.md create mode 100644 defaults/main.yml create mode 100644 files/README.md create mode 100644 handlers/main.yml create mode 100644 tasks/main.yml create mode 100644 templates/README.md create mode 100644 tests/README.md create mode 100644 tests/inventory create mode 100644 tests/test.yml create mode 100644 vars/main.yml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..5f5065c --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,33 @@ +--- +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v3.4.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-added-large-files + - id: check-case-conflict + - id: check-executables-have-shebangs + - id: check-json + - id: pretty-format-json + - id: detect-private-key + + - repo: local + hooks: + - id: ansible-lint + name: Ansible-lint + description: This hook runs ansible-lint. + entry: ansible-lint --force-color + language: python + # do not pass files to ansible-lint, see: + # https://github.com/ansible/ansible-lint/issues/611 + pass_filenames: false + always_run: true + + - repo: https://github.com/adrienverge/yamllint.git + rev: v1.26.0 + hooks: + - id: yamllint + files: \.(yaml|yml)$ + types: [file, yaml] + entry: yamllint diff --git a/README.md b/README.md new file mode 100644 index 0000000..5393565 --- /dev/null +++ b/README.md @@ -0,0 +1,112 @@ +# Ansible AWX Template: Template + +Ansible AWX is the method used for the Rocky Linux infrastructure, as a replacement for using the CLI. This template should be copied, as to manage playbooks and tasks into reproducible, repeatable, and organized manner. + +## Provides / Information + +This repository is for AWX templates. + +``` +. +├── README.md +├── defaults +│   └── main.yml +├── files +│   └── README.md +├── handlers +│   └── main.yml +├── tasks +│   └── main.yml +├── templates +│   └── README.md +├── tests +│   ├── README.md +│   ├── inventory +│   └── test.yml +└── vars + └── main.yml +``` + +## Guidelines + +These are the general guidelines for creating and maintaining these repositories. Please read carefully to ensure that you are meeting the criteria. + +1. Copy this template into a new repository with the format `ansible-type-usage`. For example, if this is for ipa management, you could use a name like `ansible-ipa-management`. +2. Change the top of the `README.md` from "Template" to an appropriate name for your repo. +3. Modify the `README.md` file at the Provides/Information section of what these tasks do. Please be descriptive and list all of the playbooks and accompanying tasks (see the example). Hint: Use the `tree` command. +4. List any requirements to run the playbooks, such as vars, mandatory or optional in playbooks. Optionally, you may list them in the `README.md` here. +5. Run `pre-commit install` - There is already a provided `.pre-commit-config.yaml` with some default settings. +6. (Optional) Remove everything starting at "Guidelines" in this README to reduce clutter. + +## Designing Playbooks + +Generally, your playbooks should be doing the following: + +1. Checking if ansible can be ran on a specific host +2. Asserting if variables are filled and are correctly formed +3. Importing tasks from the `./tasks` directory +4. Importing roles, if necessary +5. Post tasks, if necessary + +**Note**: At no point should you be using `./tasks/main.yml` + +### Pre-flight and Post-flight tasks + +``` + pre_tasks: + - name: Check if ansible cannot be run here + stat: + path: /etc/no-ansible + register: no_ansible + + - name: Verify if we can run ansible + assert: + that: + - "not no_ansible.stat.exists" + success_msg: "We are able to run on this node" + fail_msg: "/etc/no-ansible exists - skipping run on this node" + + # Assertions and other checks here + + # Import roles/tasks here + + post_tasks: + - name: Touching run file that ansible has ran here + file: + path: /var/log/ansible.run + state: touch + mode: '0644' + owner: root + group: root +``` + +### Comments + +Each playbook should have comments or a name descriptor that explains what the playbook does or how it is used. If not available, README-... files can be used in place, especially in the case of adhoc playbooks that take input. Documentation for each playbook/role does not have to be on this wiki. Comments or README's should be sufficient. + +### Tags + +Ensure that you use relevant tags where necessary for your tasks. + +### Playbook naming + +``` +init-* -> Starting infrastructure playbooks that run solo or import other + playbooks that start with import- +adhoc -> These playbooks are one-off playbooks that can be used on the CLI or + in AWX. These are typically for basic tasks. +import -> Playbooks that should be imported from the top level playbooks +role-* -> These playbooks call roles specifically for infrastructure tasks. + Playbooks that do not call a role should be named init or adhoc based + on their usage. +``` + +### Pre-commits / linting + +When pushing to your own forked version of this repository, pre-commit must run to verify your changes. They must be passing to be pushed up. This is an absolute requirement, even for roles. + +When the linter passes, the push will complete and you will be able to open a PR. + +## How are these repositories used? + +These repositories are generally cloned/pulled into AWX for the latest version, so they can be called within AWX either by hand or at a scheduled time. diff --git a/defaults/main.yml b/defaults/main.yml new file mode 100644 index 0000000..858c8da --- /dev/null +++ b/defaults/main.yml @@ -0,0 +1,2 @@ +--- +# Defaults diff --git a/files/README.md b/files/README.md new file mode 100644 index 0000000..f154f20 --- /dev/null +++ b/files/README.md @@ -0,0 +1 @@ +Files come here diff --git a/handlers/main.yml b/handlers/main.yml new file mode 100644 index 0000000..03692d8 --- /dev/null +++ b/handlers/main.yml @@ -0,0 +1,2 @@ +--- +# Handlers diff --git a/tasks/main.yml b/tasks/main.yml new file mode 100644 index 0000000..68a6567 --- /dev/null +++ b/tasks/main.yml @@ -0,0 +1,4 @@ +--- +# No tasks +- debug: msg="No tasks are provided here. Please import the task as needed in your playbook." +... diff --git a/templates/README.md b/templates/README.md new file mode 100644 index 0000000..25a2632 --- /dev/null +++ b/templates/README.md @@ -0,0 +1 @@ +Templates go here diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..9876b7a --- /dev/null +++ b/tests/README.md @@ -0,0 +1,3 @@ +# Tests + +Basic tests for the playbooks and tasks come here. Generally you need a `test.yml` and `inventory` file with at least `localhost` diff --git a/tests/inventory b/tests/inventory new file mode 100644 index 0000000..2fbb50c --- /dev/null +++ b/tests/inventory @@ -0,0 +1 @@ +localhost diff --git a/tests/test.yml b/tests/test.yml new file mode 100644 index 0000000..27fe873 --- /dev/null +++ b/tests/test.yml @@ -0,0 +1,5 @@ +--- +- hosts: localhost + remote_user: root + tasks: + - import_tasks: example.yml diff --git a/vars/main.yml b/vars/main.yml new file mode 100644 index 0000000..7af2db9 --- /dev/null +++ b/vars/main.yml @@ -0,0 +1,2 @@ +--- +# Vars that should not be overridden