Getting Started with AWX

This file is intended to be a quick guide to deploying and utilizing AWX resources. It is not a replacement for the AWX documentation available here, within the GitHub repos, or the official AWX documentation.

Overview

The CaC for Epic on Azure, or OHEMR, is managed through the ohemr-issue-tracker repository. You must file an issue for AWX CaC actions and choose the appropriate resource type (ex. job_template) and action (create or destroy). This will create a branch, a blank template file, and open a PR for you to complete. Once the PR is merged, the GitHub Actions will take over and process the request sending the changes to the AWX API.

It needs to be pointed out that for almost everything that is created such as inventories or job templates, a second PR will be required for assigning access. It is not possible to combine this into a single request.

Workflow

This is the general order of operations because of what each item references (i.e. job template must be after inventory to reference the inventory). Not all items are required each time. A full list, in order, is available in the AWX CaC Module docs.

1. Credential
2. Inventory
3. Job Template (references Inventory, Credential)
4. Schedule (references Job Template)
5. Role(s)
   • This can be done one at a time after each item or in bulk at the end, however you will not be able to view or verify items or their IDs in the UI without a role assigned

In this example, we will make a job template but the process is nearly identical for most resources.

1. Open the OHEMR-Issue-Tracker issues list
2. Click New Issue
3. Choose Request Change to AWX CaC
4. Enter your own title for Add a Title but do not modify the prefix (ex. [AWX_CaC_Request]: Adding Epic Role Job)
5. For awx_cac_module choose job_template
6. For awx_req_type choose create
7. Click Create

At this point, your issue will trigger a GitHub Action that creates the branch and PR for you. The Action will update your issue with a link to the template file to modify on the correct branch, directly within GitHub if desired, and a link to the PR it opened on your behalf.

1. Click the link for the template file: Direct Link to AWX CaC Request File

2. Click Edit in GitHub, or clone the repository and use the branch you are provided

3. Paste the appropriate contents, below is a sample of a job template:

   ---
   awx_job_template_list:
     - name: Job Title
         description: A description for the job
         job_type: run
         inventory: Inventory Name
         project: OHEMR Epic on Azure
         playbook: playbooks/epic-on-azure/pb_file_name.yml
         become_enabled: true
         execution_environment: awx-ee-omni-default
         credentials:
          - "Hashicorp Vault Token - eoavault"
          - "Other Credentials As Needed"
         ask_job_type_on_launch: true
   

   Each file is a list of objects that are fed directly into the appropriate module from the Awx.Awx collection. For example, awx_job_template_list is a list of objects that define job_template parameters. So, the parameters to use and which are required are called out by this documentation. The examples provided are not accurate since we are not calling the modules directly, so ignore any invocation metadata.

   Documentation example:

   - name: Add start notification to Job Template
     job_template:
       name: "Ping"
       notification_templates_started:
         - Notification1
         - Notification2
   

   Equivalent AWX example:

   awx_job_template_list:
     - name: "Ping"
       notification_templates_started:
         - Notification1
         - Notification2
   

4. Save and Commit the file

5. From the Issue, Open the Pull Request: Click here to view and finalize your pull request

   • Do NOT change the title of the PR, doing so can break automation

6. Click Ready for Review and go through the standard approval process to merge

Once an item is created, you need to assign the OHEMR team a role to be able to use it. This is the same process as above, so start with a new issue:

1. Open the OHEMR-Issue-Tracker issues list

2. Click New Issue

3. Choose Request Change to AWX CaC

4. Enter your own title for Add a Title but do not modify the prefix (ex. [AWX_CaC_Request]: Adding Role to Job)

5. For awx_cac_module choose role

6. For awx_req_type choose create

7. Click Create

8. Click the link for the template file: Direct Link to AWX CaC Request File

9. Click Edit in GitHub, or clone the repository and use the branch you are provided

10. Paste the appropriate contents, below is a sample of a role:

    ---
    awx_role_list:
      - teams:
          - Epic on Azure Infrastructure Operations Team
        role: Access
        job_templates:
          - This is a Job Title
        credentials:
          - This is a Credential Name
    

    It is critical that the team Epic on Azure Infrastructure Operations Team is included. From there you can assign access to one or more items, even different types of items, in the same request. Using different keys such as inventories, instance_groups, projects, credentials, and more, you can specify the Name, ID, or URL for each resource. Names are easy, but if that resource changes it could be confusing. IDs can be gathered after a resource has been created.

    For more information, see the parameters available for the AWX.AWX.role module.

11. Save and Commit the file

12. From the Issue, Open the Pull Request: Click here to view and finalize your pull request

    • Do NOT change the title of the PR, doing so can break automation

13. Click Ready for Review and go through the standard approval process to merge