AWX Configuration as Code (CaC) Style Guide

Overview

These rules apply to AWX operations using the ansible_role_awx_cac Configuration as Code model in Epic on Azure (Optum).

Safety-First Principles

1. Read-Only by Default

• ALWAYS use AWX's read-only API endpoints first to inspect state
• MUST use pb_create_awx_job_launch.yml for test runs, not direct AWX UI
• NEVER bypass approval workflows for production changes

2. SCM-Based Workflow (Production)

• MUST use GitHub-based approval workflow for all production changes
• MUST submit PRs to the CaC repo with data files
• GitHub Actions automatically runs playbooks after approval
• CLI-based workflow is for development/testing ONLY

3. Branch Isolation

• MUST use feature branches for testing roles and playbooks
• MUST override branches via scm_branch in job template or launch data
• NEVER test unreviewed code in production AWX

CaC Model Patterns

Data File Structure

MUST use YAML/JSON data files with lists of objects:

# Example: job_templates.yml
awx_job_template_list:
  - name: 'Deploy Application'
    description: 'Deploys the application using role'
    organization: 'Epic Platform'
    project: 'ohemr-ansible-playbooks'
    inventory: 'azure-hosts'
    playbook: 'deploy_app.yml'
    credentials:
      - 'Azure Service Principal'
    execution_environment: 'ansible-ee-2.15'
    scm_branch: '' # Defaults to project default
    ask_scm_branch_on_launch: true # MUST enable for flexibility
    ask_variables_on_launch: true

Connection Parameters

NEVER hardcode credentials. Pass as extra-vars:

ansible-playbook pb_create_awx_job_template.yml \
  -e controller_host=awx.example.com \
  -e controller_oauthtoken=$AWX_TOKEN \
  -e @job_templates.yml

Required Fields

Field	Rule	Notes
controller_host	MUST provide	AWX controller URL
Authentication	MUST provide	controller_oauthtoken OR controller_username + controller_password
state	NEVER include in data	Set by playbook
validate_certs	NEVER set to false in prod	Defaults true

Playbook Inventory

Common CaC playbooks in ansible_role_awx_cac:

Playbook	Purpose	Data Key
pb_create_awx_job_template.yml	Create/update job templates	awx_job_template_list
pb_create_awx_job_launch.yml	Launch jobs with params	awx_job_launch_list
pb_create_awx_workflow_job_template.yml	Create workflows	awx_workflow_job_template_list
pb_create_awx_project.yml	Create/update projects	awx_project_list
pb_create_awx_inventory.yml	Create/update inventories	awx_inventory_list
pb_create_awx_credential.yml	Create/update credentials	awx_credential_list
pb_delete_awx_*.yml	Delete resources	Same as create

Dependency Order

MUST create AWX resources in this order:

1. Organizations (if not exists)
2. Credential Types (custom types)
3. Credentials (requires org, credential type)
4. Execution Environments (requires org)
5. Projects (requires org, optional credential)
6. Inventories (requires org)
7. Job Templates (requires org, project, inventory, credentials, EE)
8. Workflow Templates (requires org, job templates)

Testing Workflows

Override Branch Testing

MUST test playbook changes without modifying job template:

# test_override.yml
awx_job_launch_list:
  - name: 'existing-job-template'
    scm_branch: 'feature/my-test-branch'
    extra_vars:
      test_mode: true
    wait: true

ansible-playbook pb_create_awx_job_launch.yml \
  -e controller_host=awx-dev.example.com \
  -e controller_oauthtoken=$DEV_TOKEN \
  -e @test_override.yml

Role Feature Branch Testing

MUST follow this process:

1. Create feature branch in role repo: feature/fix-deployment
2. Create feature branch in playbooks repo: feature/test-deployment-fix
3. Update requirements.yml to reference role branch
4. Launch job with playbooks branch override

awx_job_launch_list:
  - name: 'deploy-app-job'
    scm_branch: 'feature/test-deployment-fix' # Playbooks repo branch
    extra_vars:
      ansible_galaxy_force: true # MUST force re-download
      test_mode: true

Safety Checklists

Before Creating Job Templates

• VERIFY project SCM URL is correct
• CONFIRM inventory exists and contains correct hosts
• CHECK credentials have minimal required permissions
• ENABLE ask_scm_branch_on_launch for flexibility
• SET ask_limit_on_launch to allow host targeting
• USE ask_variables_on_launch for environment-specific vars

Before Launching Jobs

• VERIFY target inventory/hosts are correct
• CHECK scm_branch if testing feature branch
• USE check_mode: true for dry-run first
• SET wait: true to monitor job completion
• REVIEW extra_vars for sensitive data (use vault/credentials instead)

Before Production Deployment

• VERIFY all changes tested in dev environment
• CONFIRM PR approved by team members
• CHECK job template has proper approval workflows
• DOCUMENT rollback plan
• CONFIGURE monitoring/alerting

Common Pitfalls

❌ NEVER DO

Anti-Pattern	Risk
Hardcode controller credentials	Security breach
Use personal credentials for automation	Audit failure
Test unreviewed code in production	Outage risk
Create job templates without ask_*_on_launch	No flexibility
Launch jobs without wait: true	Lose error visibility
Store sensitive data in extra_vars	Security exposure
Bypass GitHub approval workflow	Compliance violation

✅ ALWAYS DO

Best Practice	Benefit
Use OAuth tokens or service accounts	Proper audit trail
Store tokens in environment variables or vault	Security
Test in dev → qa → prod progression	Safe rollout
Enable ask_*_on_launch for flexibility	Easy testing
Use limit to target specific hosts	Safe testing
Store secrets in AWX credentials	Secure
Use SCM-based workflow for production	Governance
Document data file schemas in comments	Maintainability

Examples

Create Job Template with All Options

awx_job_template_list:
  - name: 'deploy-epic-app-prod'
    description: 'Production deployment of Epic application'
    organization: 'Epic Platform'
    project: 'ohemr-ansible-playbooks'
    playbook: 'deploy_epic_app.yml'
    inventory: 'azure-prod-hosts'

    # Credentials
    credentials:
      - 'Azure Prod Service Principal'
      - 'Epic App Secrets'

    # Execution environment
    execution_environment: 'ansible-ee-2.15-azure'

    # Launch options - MUST enable for flexibility
    ask_scm_branch_on_launch: true
    ask_limit_on_launch: true
    ask_variables_on_launch: true
    ask_tags_on_launch: true

    # Job behavior
    job_type: 'run' # or "check"
    verbosity: 1
    timeout: 1800

    # Concurrency
    allow_simultaneous: false

Launch Job with Override Branch

awx_job_launch_list:
  - name: 'deploy-epic-app-prod'
    scm_branch: 'feature/hotfix-deployment'
    limit: 'app-server-01' # Target single host
    extra_vars:
      deployment_type: 'rolling'
      max_fail_percentage: 10
    wait: true
    timeout: 1800

Create Workflow Template

awx_workflow_job_template_list:
  - name: 'epic-app-full-deployment'
    description: 'Complete Epic app deployment with pre/post checks'
    organization: 'Epic Platform'

    workflow_nodes:
      - identifier: 'pre-check'
        unified_job_template: 'health-check-pre'
        all_parents_must_converge: false

      - identifier: 'deploy-db'
        unified_job_template: 'deploy-database'
        all_parents_must_converge: true
        success_nodes:
          - 'deploy-app'
        failure_nodes:
          - 'rollback-db'

      - identifier: 'deploy-app'
        unified_job_template: 'deploy-epic-app-prod'
        all_parents_must_converge: true
        success_nodes:
          - 'post-check'
        failure_nodes:
          - 'rollback-app'

      - identifier: 'post-check'
        unified_job_template: 'health-check-post'

Troubleshooting

Issue	Cause	Solution
Job template won't launch	Project not synced	Check project sync status
Override branch not working	ask_scm_branch_on_launch disabled	Enable on job template
Role not using feature branch	Wrong requirements.yml	Check playbook branch
Credentials invalid	Token expired	Refresh OAuth token

References

• AWX.AWX Collection Docs
• ansible_role_awx_cac README
• Epic on Azure AWX Architecture