ansible-openqa-management/README.md

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