Set up your automation environment for Configuration as Code

Configuration as Code is a way of working where you define and manage the configuration of Ansible Automation Platform using version-controlled configuration files, such as YAML, instead of clicking through the web UI.

Before you begin

You have a Git account.
Your platform gateway instance is accessible.
You have a valid platform gateway token or user credentials for platform gateway authentication. Legacy automation controller PATs are not supported.
You built and registered your own execution environment. Alternatively, you have available the supported execution environment to run playbooks that use the ansible.platform collection. For more information, see Creating and using execution environments.

About this task

Important

Direct API access to individual service components (automation controller, automation hub, and Event-Driven Ansible) is not supported. All CasC playbooks must authenticate through platform gateway. If you previously used automation controller Personal Access Tokens (PATs), replace them with platform gateway tokens. Ensure that the aap_hostname variable in your playbooks points to your platform gateway URL.

For more information about creating tokens, see Adding tokens in Access management and authentication.

As an Ansible content developer, you can use the Configuration as Code approach to apply settings on your automation controller to get the following benefits:

Predictable job behavior
Easier and faster scaling to new clusters
Change history with diffs and rollback capability thanks to version control support
Faster recovery after outages or migrations
Reduced risk of errors because changes flow through CI/CD pipelines and pull requests, where peer reviews and automated testing are applied

Procedure

Create a new Git repository.

On your local machine, encrypt your password for platform gateway:

$ ansible-vault encrypt_string 'gateway_password' --name 'aap_password'
New Vault password: vault_password
Confirm New Vault password: vault_password
Encryption successful
aap_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          63633763653530343566363864333130656433613634333465363733326261336465333362623635
          3061333439626238616332313663633431663962353735320a633732346232396165373931653039
          64326462306162396366373565316631343033656230363038623237313036613166313331623533
          3363636462646534330a616437646665393738386235306361653333313338656563346633396434
          35346164656437326231326433323934643133353436323562373762616531326463

You encrypted the value of the aap_password variable, which you will use in the next step.

Create the /my_ansible_project/vars/all.yml file with variables for connecting to your Ansible Automation Platform and variables for creating Role-Based Access Control (RBAC) objects:

---
# Ansible Automation Platform related variables
aap_hostname: "<GATEWAY>"
aap_username: "<GATEWAY_USER>"
aap_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          63633763653530343566363864333130656433613634333465363733326261336465333362623635
          3061333439626238616332313663633431663962353735320a633732346232396165373931653039
          64326462306162396366373565316631343033656230363038623237313036613166313331623533
          3363636462646534330a616437646665393738386235306361653333313338656563346633396434
          35346164656437326231326433323934643133353436323562373762616531326463
aap_validate_certs: false

# Details for creating organization, team, and user
org_name: "Demo-Organization"
team_name: "Demo-Team"
user_username: "Demo-User"
user_email: "demo.user@example.com"
user_password: "3ncrypt3d_P@$$word"

# Role names as they exist in your Ansible Automation Platform
role_for_team_in_org: "Organization Inventory Admin" # "Executor"
role_for_user_in_org: "Organization Auditor"

# Custom role definition details
custom_role_name: "NetOps ReadOnly"
custom_role_description: "Read-only access to network objects"

Note

The aap_hostname variable must point to your platform gateway URL, not to individual service endpoints such as automation controller or automation hub. The aap_username and aap_password variables are your platform gateway credentials.

Alternatively, you can authenticate by using a platform gateway OAuth 2 token instead of a username and password. Replace the aap_username and aap_password variables with aap_token:

aap_hostname: "<GATEWAY>"
aap_token: "<GATEWAY_OAUTH2_TOKEN>"
aap_validate_certs: false

For more information about creating tokens, see Adding tokens in Access management and authentication.

Compose the /my_ansible_project/RBAC_settings.yml playbook, which creates RBAC objects and assigns roles to those objects:

---
- name: Create RBAC objects and assign roles to them
  hosts: localhost
  gather_facts: false
  vars_files:
    - ./vars/all.yml
  tasks:
    - name: Ensure new organization exists
      ansible.platform.organization:
        name: "{{ org_name }}"
        state: present
        aap_hostname: "{{ aap_hostname }}"
        aap_username: "{{ aap_username }}"
        aap_password: "{{ aap_password }}"
        aap_validate_certs: "{{ aap_validate_certs }}"

    - name: Ensure new team exists in organization
      ansible.platform.team:
        name: "{{ team_name }}"
        organization: "{{ org_name }}"
        state: present
        aap_hostname: "{{ aap_hostname }}"
        aap_username: "{{ aap_username }}"
        aap_password: "{{ aap_password }}"
        aap_validate_certs: "{{ aap_validate_certs }}"

    - name: Ensure new user exists
      ansible.platform.user:
        username: "{{ user_username }}"
        email: "{{ user_email }}"
        password: "{{ user_password }}"
        state: present
        aap_hostname: "{{ aap_hostname }}"
        aap_username: "{{ aap_username }}"
        aap_password: "{{ aap_password }}"
        aap_validate_certs: "{{ aap_validate_certs }}"

    - name: Ensure new custom role exists
      ansible.platform.role_definition:
        name: "{{ custom_role_name }}"
        description: "{{ custom_role_description }}"
        content_type: awx.inventory
        permissions:
          - awx.view_inventory
          - awx.change_inventory
        state: present
        aap_hostname: "{{ aap_hostname }}"
        aap_username: "{{ aap_username }}"
        aap_password: "{{ aap_password }}"
        aap_validate_certs: "{{ aap_validate_certs }}"

    - name: Assign already existing role to team in organization
      ansible.platform.role_team_assignment:
        team: "{{ team_name }}"
        assignment_objects:
          - name: "{{ org_name }}"
            type: "organizations"
        role_definition: "{{ role_for_team_in_org }}"
        state: present
        aap_hostname: "{{ aap_hostname }}"
        aap_username: "{{ aap_username }}"
        aap_password: "{{ aap_password }}"
        aap_validate_certs: "{{ aap_validate_certs }}"

    - name: Assign already existing role to user in organization
      ansible.platform.role_user_assignment:
        user: "{{ user_username }}"
        object_ids:
          - "{{ org_name }}"
        role_definition: "{{ role_for_user_in_org }}"
        state: present
        aap_hostname: "{{ aap_hostname }}"
        aap_username: "{{ aap_username }}"
        aap_password: "{{ aap_password }}"
        aap_validate_certs: "{{ aap_validate_certs }}"

If you are using token-based authentication, replace the aap_username and aap_password parameters with aap_token in each task.

Many values in this playbook are provided in the form of variables, such as object names, their details, Ansible Automation Platform credentials. You can easily reuse the variables throughout files in your Ansible project, which will also simplify the creation and maintenance of the project and reduce the number of errors.

Refer to the all.yml file to see the expanded values of those variables. For details about the module parameters, default values, and further examples how to use the modules, see the resources on Automation hub for the ansible.platform collection.

Push the variables and the playbook to your Git repository so that automation controller can later read in the correct data.

git add .
git commit -m "Provide variables and RBAC_settings.yml playbook resources for Ansible Automation Platform project"
git push origin relevant_branch_name

Using the platform gateway UI, create a new project with the following values:
- Name: Platform collection testing
- Description: Automation resources to test the CaC capability of RBAC modules from the ansible.platform collection
- Execution Environment: ee-supported
- Organization: Default
- Source Control Type: Git
- Source Control URL: https://my_git_url/my_git_repository/my_ansible_project
Create a credential for your Ansible Vault password of your encrypted aap_password variable:
- Name: aap_password_vault
- Description: Holds vault password for decrypting the value of the aap_password variable
- Credential type: Vault
- Vault Password: vault_password
Create a job template with the following values:
- Name: RBAC_settings
- Description: Create organization, team, user, and custom role RBAC objects. Assign a pre-existing role to the created team and assign a pre-existing role to the created user.
- Job type: Run
- Inventory: Demo Inventory
- Project: Platform collection testing
- Playbook: RBAC_settings.yml
- Execution Environment: ee-supported
- Credentials: aap_password_vault | Vault

Launch the RBAC_settings job template.

After the template job successfully finishes, the output should be similar to the following:

Vault password:

PLAY [Create RBAC objects and assign roles to them] ****************************

TASK [Ensure new organization exists] ******************************************
changed: [localhost]

TASK [Ensure new team exists in organization] **********************************
changed: [localhost]

TASK [Ensure new user exists] **************************************************
changed: [localhost]

TASK [Ensure new custom role exists] *******************************************
changed: [localhost]

TASK [Assign already existing role to team in organization] ********************
changed: [localhost]

TASK [Assign already existing role to user in organization] ********************
changed: [localhost]

PLAY RECAP *********************************************************************
localhost: ok=6 changed=6 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0

The output message shows that you ran the job template against 1 target (your localhost). At the same time, you created:

An organization.
A team that exists within the created organization. The team was assigned some pre-existing role.
A user that exists within the created organization. The user was assigned some pre-existing role.
A custom role.

Results

Verify that the resources were created correctly:

In the navigation panel, check that you see your created organization:
Check that you see your created team, which belongs to the organization and is assigned the correct pre-existing role:
Check that you see your created user, which belongs to the organization and is assigned the correct pre-existing role:
Check that you see your created custom role, which was assigned the permissions as specified in your RBAC_settings.yml playbook: