Chapter 6. Creating content

Use the guidelines in this section of the Creator Guide to learn more about the developing the content you will use in Red Hat Ansible Automation Platform.

6.1. Creating playbooks

Playbooks contain one or more plays. A basic play contains the following sections:

  • Name: a brief description of the overall function of the playbook, which assists in keeping it readable and organized for all users.
  • Hosts: identifies the target(s) for Ansible to run against.
  • Become statements: this optional statement can be set to true/yes to enable privilege escalation using a become plugin (such as sudo, su, pfexec, doas, pbrun, dzdo, ksu).
  • Tasks: this is the list actions that get executed against each host in the play.

Example playbook

- name: Set Up a Project and Job Template
  hosts: host.name.ip
  become: true

  tasks:
    - name: Create a Project
      awx.awx.project:
        name: Job Template Test Project
        state: present
        scm_type: git
        scm_url: https://github.com/ansible/ansible-tower-samples.git

    - name: Create a Job Template
      awx.awx.job_template:
        name: my-job-1
        project: Job Template Test Project
        inventory: Demo Inventory
        playbook: hello_world.yml
        job_type: run
        state: present

6.2. Creating collections

You can create your own Collections locally with the Ansible Galaxy CLI tool. All of the Collection-specific commands can be activated by using the collection subcommand.

Prerequisites

  • You have Ansible version 2.9 or newer installed in your development environment.

Procedure

  1. In your terminal, navigate to where you want your namespace root directory to be. For simplicity, this should be a path in COLLECTIONS_PATH but that is not required.

  2. Run the following command, replacing my_namespace and my_collection_name with the values you choose: 

    $ ansible-galaxy collection init <my_namespace>.<my_collection_name>
    Note

    Make sure you have the proper permissions to upload to a namespace by checking under the "My Content" tab on galaxy.ansible.com or cloud.redhat.com/ansible/automation-hub

The above command will create a directory named from the namespace argument above (if one does not already exist) and then create a directory under that with the Collection name. Inside of that directory will be the default or "skeleton" Collection. This is where you can add your roles or plugins and start working on developing your own Collection.

In relation to execution environments, Collection developers can declare requirements for their content by providing the appropriate metadata via Ansible Builder.

Requirements from a Collection can be recognized in these ways:

  • A file meta/execution-environment.yml references the Python and/or bindep requirements files
  • A file named requirements.txt, which contains information on the Python dependencies and can sometimes be found at the root level of the Collection
  • A file named bindep.txt, which contains system-level dependencies and can be sometimes found in the root level of the Collection
  • If any of these files are in the build_ignore of the Collection, Ansible Builder will not pick up on these since this section is used to filter any files or directories that should not be included in the build artifact

Collection maintainers can verify that ansible-builder recognizes the requirements they expect by using the introspect command: 

$ ansible-builder introspect --sanitize ~/.ansible/collections/

Additional resources

  • For more information on creating collections, see Creating collections in the Ansible Developer Guide.

6.3. Creating roles

You can create roles using the Ansible Galaxy CLI tool. Role-specific commands can be accessed from the roles subcommand. 

ansible-galaxy role init <role_name>

Standalone roles outside of Collections are still supported, but new roles should be created inside of a Collection to take advantage of all the features Ansible Automation Platform has to offer.

Procedure

  1. In your terminal, navigate to the roles directory inside a collection.

  2. Create a role called role_name inside the collection created previously: 

    $ ansible-galaxy role init my_role

    The collection now contains a role named my_role inside the roles directory: 

    ~/.ansible/collections/ansible_collections/<my_namespace>/<my_collection_name>
...
└── roles/
    └── my_role/
        ├── .travis.yml
        ├── README.md
        ├── defaults/
        │   └── main.yml
        ├── files/
        ├── handlers/
        │   └── main.yml
        ├── meta/
        │   └── main.yml
        ├── tasks/
        │   └── main.yml
        ├── templates/
        ├── tests/
        │   ├── inventory
        │   └── test.yml
        └── vars/
            └── main.yml

  3. A custom role skeleton directory can be supplied using the --role-skeleton argument. This allows organizations to create standardized templates for new roles to suit their needs. 

    ansible-galaxy role init my_role --role-skeleton ~/role_skeleton

This will create a role named my_role by copying the contents of ~/role_skeleton into my_role. The contents of role_skeleton can be any files or folders that are valid inside a role directory.

Additional resources

  • For more information on creating roles, see Creating roles in the Ansible Galaxy documentation.

6.4. Creating automation execution environments

An automation execution environments definition file will specify
  • An Ansible version
  • A Python version (defaults to system Python)
  • A set of required Python libraries
  • Zero or more Content Collections (optional)
  • Python dependencies for those specific Collections

The concept of specifying a set of Collections for an environment is to resolve and install their dependencies. The Collections themselves are not required to be installed on the machine that you are generating the automation execution environments on.

An automation execution environments is built from this definition, and results in a container image. Please read the Ansible Builder documentation to learn the steps involved in creating these images.