diff --git a/README.md b/README.md index 24daae9..766aac8 100644 --- a/README.md +++ b/README.md @@ -29,93 +29,4 @@ This repository is for AWX templates. ## 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. - -## GitLab Steps - -1. Create a new project -2. Click "import project" -3. Click "Repo by URL" -4. Put in the URL: https://git.rockylinux.org/infrastructure/public/ansible/ansible-awx-template.git -5. Type in the project name as outlined in `Guidelines` above -6. Ensure your project URL and slug are appropriate - -## 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. +These guidelines are on the Core Wiki.