Red Hat Communities of Practice AAP Configuration Extended Collection

This Ansible collection extends the infra.aap_configuration collection by providing extra functionalities that allows advanced operations on the Ansible Automation Platform Configuration as Code.

Getting Help

We are on the Ansible Forums and Matrix, if you want to discuss something, ask for help, or participate in the community, please use the #infra-config-as-code tag on the form, or post to the chat in Matrix.

Ansible Forums

Matrix Chat Room

Requirements

The only one collection required by infra.aap_configuration_extended is the infra.aap_configuration (and that one is requiring other collections: ansible.platform, ansible.hub, ansible.controller and ansible.eda). You can copy this requirements.yaml file example:

---
collections:
  - name: ansible.controller
  - name: ansible.hub
  - name: ansible.platform
  - name: infra.aap_configuration
...

Python dependency

The format_yaml module uses PyYAML (import yaml), which ships with ansible-core on the controller. Managed nodes need python3-yaml (or PyYAML in the execution environment) if the module runs there. The collection no longer requires ruamel.yaml. See ansible-doc infra.aap_configuration_extended.format_yaml for options (preserve vs round-trip, !unsafe, null handling, and regex scalar quoting).

Links to Ansible Automation Platform Collections

Links to other Validated Configuration Collections for Ansible Automation Platform

Included content

Click the Content button to see the list of content included in this collection.

Installing this collection

You can install the infra.aap_configuration_extended.collection with the Ansible Galaxy CLI:

ansible-galaxy collection install infra.aap_configuration_extended

You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:

---
collections:
  - name: infra.aap_configuration_extended
    # If you need a specific version of the collection, you can specify like this:
    # version: ...

Using this collection

The awx.awx or ansible.controller collection must be invoked in the playbook in order for Ansible to pick up the correct modules to use.

The following command will invoke the collection playbook. This is considered a starting point for the collection.

ansible-playbook infra.aap_configuration_extended.configure_controller.yml

Otherwise it will look for the modules only in your base installation. If there are errors complaining about "couldn't resolve module/action" this is the most likely cause.

- name: Playbook to configure ansible controller post installation
  hosts: localhost
  connection: local
  vars:
    controller_validate_certs: true
  collections:
    - awx.awx

Define following vars here, or in controller_configs/controller_auth.yml aap_hostname: ansible-controller-web-svc-test-project.example.com

You can also specify authentication by a combination of either:

• aap_hostname, aap_username, aap_password
• aap_hostname, aap_oauthtoken

The OAuth2 token is the preferred method. You can obtain the token through the preferred controller_token module, or through the AWX CLI login command.

These can be specified via (from highest to lowest precedence):

• direct role variables as mentioned above
• environment variables (most useful when running against localhost)
• a config file path specified by the controller_config_file parameter
• a config file at ~/.controller_cli.cfg
• a config file at /etc/controller/controller_cli.cfg

Config file syntax looks like this:

[general]
host = https://localhost:8043
verify_ssl = true
oauth_token = LEdCpKVKc4znzffcpQL5vLG8oyeku6

Controller token module would be invoked with this code:

    - name: Create a new token using controller username/password
      awx.awx.token:
        description: 'Creating token to test controller jobs'
        scope: "write"
        state: present
        controller_host: "{{ aap_hostname }}"
        aap_username: "{{ aap_username }}"
        aap_password: "{{ aap_password }}"

Automate the Automation

Every Ansible Controller instance has it's own particularities and needs. Every administrator team has it's own practices and customs. This collection allows adaptation to every need, from small to large scale, having the objects distributed across multiple environments and leveraging Automation Webhook that can be used to link a Git repository and Ansible automation natively.

A complete example of how to use all of the roles present in the collection is available at the following README.md, where all the phases to allow CI/CD for the Controller Configuration are provided.

Scale at your needs

The input data can be organized in a very flexible way, letting the user use anything from a single file to an entire file tree to store the controller objects definitions, which could be used as a logical segregation of different applications, as needed in real scenarios.

Controller Export

The awx command line can export json that is compatible with this collection. In addition there is an awx.awx/ansible.controller export module that use the awx command line to export. See the export guide for more details

Template Example

See our template to use in order to start using the collections can be found

See Also

• Ansible Using collections for more details.

Release and Upgrade Notes

For details on changes between versions, please see the changelog for this collection.

Releasing, Versioning and Deprecation

This collection follows Semantic Versioning. More details on versioning can be found in the Ansible docs.

We plan to regularly release new minor or bugfix versions once new features or bugfixes have been implemented.

Releasing the current major version happens from the devel branch.

Roadmap

Adding the ability to use direct output from the awx export command in the roles along with the current data model.

Contributing to this collection

We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the Controller Configuration collection repository. More information about contributing can be found in our Contribution Guidelines.

We have a community meeting every 4 weeks. Find the agenda in the issues and the calendar invitation below:

Code of Conduct

This collection follows the Ansible project's Code of Conduct. Please read and familiarize yourself with this document.

Licensing

GNU General Public License v3.0 or later.

See LICENSE to see the full text.

Support

This collection is Ansible Validated Content. It is reviewed and tested by Red Hat but is not supported under a Red Hat SLA. For reporting issues and requesting improvements, file an issue at the AAP Configuration Extended repository. Community help is also available on the Ansible Forum.