<inputclass="md-option"data-md-color-media="(prefers-color-scheme: light)"data-md-color-scheme="default"data-md-color-primary="teal"data-md-color-accent="teal"aria-label="Switch to dark mode"type="radio"name="__palette"id="__palette_1">
<labelclass="md-header__button md-icon"title="Switch to dark mode"for="__palette_2"hidden>
<inputclass="md-option"data-md-color-media="(prefers-color-scheme: dark)"data-md-color-scheme="slate"data-md-color-primary="teal"data-md-color-accent="teal"aria-label="Switch to light mode"type="radio"name="__palette"id="__palette_2">
<labelclass="md-header__button md-icon"title="Switch to light mode"for="__palette_1"hidden>
<ahref="https://git.resf.org/infrastructure/wiki/_edit/main/docs/guidelines/awx_scm_guidelines.md"title="Edit this page"class="md-content__button md-icon">
<p>This document covers the guidelines as set out by the Infrastructure/Core group for designing modular repositories that may be used in the Rocky AWX instance or local execution based on team needs. This is meant to supersede the guidelines in the ansible-awx-template repository.</p>
<p>This does not cover detailed examples, but is meant to get teams and their contributors started in designing or improving upon all ansible related activities for their group.</p>
<p>This section covers the basics for your AWX project. It is absolutely important that you start with these as an absolute bare minimum. While you will be forking/cloning off of <code>infrastructure/ansible-awx-template</code> and using that as the starting point, the next few sections will explain the basic structure and basic design principals.</p>
<p>You should begin by starting from the <ahref="https://git.resf.org/infrastructure/ansible-awx-template">Infrastructure Ansible AWX Template</a>.</p>
<p>The general structure will always start from this:</p>
<divclass="highlight"><pre><span></span><code>.
├── somePlaybook.yml
├── defaults
│ └── main.yml
├── files
├── handlers
│ └── main.yml
├── tasks
│ └── main.yml
├── templates
├── tests
│ ├── inventory
│ └── test.yml
└── vars
└── main.yml
</code></pre></div>
<p>This structure follows the basic expected structure for ansible (this means ignoring AWX/Tower). If you are familiar with ansible already, you may already know how these files and directories work at an operational level. The gist of it is:</p>
<ul>
<li>All playbooks should be in the root and import tasks from <code>./tasks</code> if needed</li>
<li>Vars should be clearly defined where needed in vars, defaults, and/or playbooks</li>
<li>Files and templates should be created with a purpose</li>
<li>Handlers should be clearly defined and used</li>
<li>There should be wiggle room to add callback_plugins, filter_plugins, libraries</li>
</ul>
<p>With these basic ideas in mind, we can move into playbook design.</p>
<p>Generally, your playbooks should be doing the following:</p>
<ol>
<li>Checking if ansible can be ran on a specific host</li>
<li>Asserting if variables are filled and are correctly formed, if applicable</li>
<li>Importing tasks from the <code>./tasks</code> directory</li>
<li>Importing roles, if necessary</li>
<li>Post tasks, if necessary</li>
</ol>
<p><strong>At no point should you be using</strong><code>./tasks/main.yml</code><strong>under any circumstance.</strong></p>
<h4id="pre-flight-and-post-flight-tasks">Pre-flight and Post-flight Tasks<aclass="headerlink"href="#pre-flight-and-post-flight-tasks"title="Permanent link">¶</a></h4>
<p>In majority of cases, you will need to have pre-flight and post-flight tasks. These aren't needed in <em>all</em> cases, but they should be used as a starting point.</p>
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
ansible.builtin.file:
path: /var/log/ansible.run
state: touch
mode: '0644'
owner: root
group: root
</code></pre></div>
<h4id="tasks-general-information">Tasks General Information<aclass="headerlink"href="#tasks-general-information"title="Permanent link">¶</a></h4>
<p>Ensure that your tasks are using FQCN. This means, even for the simple modules such as <code>file</code>, you should be using <code>ansible.builtin.file</code> to be compliant with ansible-lint 6+ and ansible 2.12+.</p>
<p>Each playbook should have comments or a name descriptor that explains what the playbook does or how it is used. If not available, <code>README-...</code> can be used in place, especially in the case of adhoc playbooks that take or require input. Documentation for each playbook/role does not have to be on a wiki. Comments or README's should be perfectly sufficient.</p>
<p>Ensure that you are using relevant tags where necessary for your tasks. This will allow you or the deployers to have deeper control of what is ran or called in AWX.</p>
<p>When making playbooks, there is a set of predefined prefixes you will need to set. It is highly discouraged to step outside of these prefixes.</p>
<divclass="highlight"><pre><span></span><code>init-* -> Starting playbooks that run solo or import other playbooks that start
with import-. Can also be used to run updates or repetive tasks that
adhoc may not suffice and running a role playbook is too much overhead.
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 or
used to "import" or "add" data somewhere (e.g., a database or LDAP)
role-* -> These playbooks call roles for potential tasks or even roles in general.
</code></pre></div>
<divclass="admonition note">
<pclass="admonition-title">Using the role prefix without an ansible role</p>
<p>It is perfectly fine to use <code>role-</code> as a way to say "this system will do or be X" without calling out to an ansible role. You may use <code>role</code> for this case or you can use <code>init</code>. This is <strong>not</strong> a strict requirement and you should go with what feels right for your project.</p>
<p>There will likely be multiple dynamic inventory sources used for hosts managed by AWX, and as a result, there will be a lot of groups defined with one or more hosts at a time. As this is the case, here are some things to keep in mind:</p>
<ul>
<li>Use group names where necessary</li>
<li>Use localhost if you aren't actually doing anything to a system (e.g., you're calling an API) <em>and</em> you don't have to connect to a system to use said API</li>
<li>
<p>When filling in the <code>hosts</code> directive, follow these general guidelines:</p>
<ul>
<li>If it applies to all hosts in an inventory, use <code>all</code></li>
<li>If you want the host or a group of hosts to be selectable (via dropdown or manual input), set <code>host: {{ host }}</code> and the host var can be defined as an extra var</li>
<li>If the above two are not applicable and you must set a hostname, you may do so. Note that this will require you to be more vigilant in keeping your repository up to date.</li>
<p>Generally local inventory files are not recommended. Some general rules to follow is this:</p>
<ul>
<li>If your project can be ran in AWX <em>and</em> locally outside of AWX, the inventory file should not be committed as <code>inventory</code> (the current <code>.gitignore</code> prevents this from being committed by default)</li>
<li>If your project is local only (meaning it will not be used in AWX, but your team will be using it locally), you may modify <code>.gitignore</code> to include the file</li>
</ul>
<p>We want to prevent AWX from picking up a random inventory that isn't defined within it.</p>
<p>General ansible.cfg files are not recommended as they would be picked up during normal operation. These should be provided only for special cases. Optionally, you may provide it under another name that a user can reference for local execution outside of AWX.</p>
<h4id="collections-and-roles">Collections and Roles<aclass="headerlink"href="#collections-and-roles"title="Permanent link">¶</a></h4>
<p>Collections and roles should be defined in a <code>requirements.yml</code> in their respective directories. AWX will pick them up. Optionally, you can provide a playbook or script to install roles and collections locally. Example commands that could be in a script or playbook:</p>
<p>When committing, pre-commit must run to verify your changes. They must be passing to be pushed up. This is an absolute requirement, even for roles. There are very rare exceptions to this rule and they may be granted depending on what it is.</p>
<p>When the linter passes, a push can be performed. After that, if a PR is necessary, open one. Otherwise, it should be free to use locally or in AWX.</p>
<p>A template generally comes with a <code>tests</code> directory. While not strictly required, it is recommended to create a suite of tests to ensure most, if not all of your playbooks are in working order. This is similar to providing tests to ansible collections, in that they should test at least basic functionality.</p>
<p>Complex situations can be tested for as well and is encouraged.</p>
<scriptid="__config"type="application/json">{"base":"../..","features":["navigation.expand","navigation.indexes","navigation.instant","navigation.sections","navigation.top","navigation.tracking","navigation.path","search.highlight","search.suggest","toc.integrate","content.action.edit"],"search":"../../assets/javascripts/workers/search.208ed371.min.js","translations":{"clipboard.copied":"Copied to clipboard","clipboard.copy":"Copy to clipboard","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.placeholder":"Type to start searching","search.result.term.missing":"Missing","select.version":"Select version"}}</script>
