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.
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.
