You can use the ansible-navigator collections command to view the documentation for Ansible Content Collections that are included with your current automation execution environment.

Because the ee-supported-rhel8 execution environment includes ansible.controller, you can use the following command to access its documentation:

[user@demo ~]$ ansible-navigator collections --eei ee-supported-rhel8

This displays a list of all the collections available in the execution environment. Select ansible.controller from that list by typing a colon (:) followed by its line number on the list.

A list of the modules and other plug-ins provided by the ansible.controller collection is displayed. The following example shows this list, scrolled partway through the output as indicated by the scroll bar on the right.

   Ansible.controller      Type   Added Deprecated Description
12│group                   module None  False      create, update, or destr
13│host                    module None  False      create, update, or destr
14│import                  module 3.7.0 False      import resources into Au
15│instance_group          module 4.0.0 False      create, update, or destr
16│inventory               module None  False      create, update, or destr
17│inventory_source        module None  False      create, update, or destr
18│inventory_source_update module None  False      Update inventory source(
19│job_cancel              module None  False      Cancel an Automation Pla
20│job_launch              module None  False      Launch an Ansible Job.
21│job_list                module None  False      List Automation Platform
22│job_template            module None  False      create, update, or destr
23│job_wait                module None  False      Wait for Automation Plat
24│label                   module None  False      create, update, or destr
25│license                 module None  False      Set the license for Auto
26│notification_template   module None  False      create, update, or destr
27│organization            module None  False      create, update, or destr
28│project                 module None  False      create, update, or destr
29│project_update          module None  False      Update a Project in Auto
30│role                    module None  False      grant or revoke an Autom
^b/PgUp page up ^f/PgDn page down ↑↓ scroll esc back [0-9] goto :help help

You can select the line number of any of the items on that list to get more information about how to use it.

For example, given the preceding output, if you enter :20, the documentation for the job_launch module, which launches a job, is displayed.

The documentation contains two particularly important sections. The doc: line marks the start of usage documentation.

27│doc:

If you scroll down further to the indented options: line in that output, the subsequent indented lines document options used by that module. In the following example, the first option is controller_config_file.

 38│  options:
 39│    controller_config_file:

If you scroll down further you can see the name option:

126│    name:
127│      aliases:
128│      - job_template
129│      description:
130│      - Name of the job template to use.
131│      required: true
132│      type: str

This specifies that the job_launch module has an option called name of type string. You can use job_template as a synonym for name. It contains the name of the job template to use to launch the job. You must specify this option when you use this module.

The other section of this output that is useful is the examples: section, which contains a number of examples of how to use the module.

The documentation for job_launch contains the following example, among others. The example on lines 187 to 190 is a task that launches a job from the My Job Template job template and registers a variable, job, that contains the job ID of the job that the task launched, among other data.

186│examples: |-
187│  - name: Launch a job
188│    job_launch:
189│      job_template: "My Job Template"
190│    register: job

You can also use your web browser to read documentation for the ansible.controller content collection on automation hub. After you search for the ansible.controller content collection, go to its Documentation tab to learn more about its modules and other plug-ins.

Figure 8.2: ansible.controller.user

The ansible.controller.user module adds, modifies, and deletes automation controller users.

If you do not specify that the user should have the System Administrator user type (using the is_superuser option), or System Auditor (using the is_system_auditor option), then automation controller sets up the user with the Normal User user type.

You can directly open the documentation for the ansible.controller.user module with the following command:

[user@demo ~]$ ansible-navigator doc ansible.controller.user \
> --eei ee-supported-rhel8

Documentation for the ansible.controller.user module shows the following example:

- name: Add user
  user: 
    username: jdoe
    password: foobarbaz
    email: jdoe@example.org
    first_name: John
    last_name: Doe
    state: present

Most modules in the ansible.controller Ansible Content Collection require you to specify your automation controller host and provide authentication information for that automation controller. Each module documents the following options:

You can run your playbook locally using the ansible-navigator command, or you can configure automation controller to run the playbook. Running the playbook from automation controller might require creating several resources:

The ansible.controller.team module adds, modifies, and deletes automation controller teams.

Documentation for the ansible.controller.team module shows the following example:

- name: Create team
  team: 
    name: Team Name
    description: Team Description
    organization: test-org
    state: present
    controller_config_file: "~/tower_cli.cfg" 

Just like the previous example, you can run the playbook locally using the ansible-navigator command, or you can configure automation controller to run the playbook.

The ansible.controller.role module grants or revokes automation controller roles for users and teams.

Individual resource types only allow specific roles. For example, you can only use the admin, member, and read roles when you assign a team role. At a minimum, when you create a new user, the user should have the member role in the automation controller organization.

The following example grants the jdoe user the member role on the Default organization.

- name: Add jdoe as a member of the Default organization
  ansible.controller.role:
    user: jdoe
    organization: Default
    role: member
    state: present

Add a user to a team by adding a team role for the user. The following example grants the jdoe user the member role on the My Team team.

- name: Add jdoe to the member role of My Team
  ansible.controller.role:
    user: jdoe
    target_team: "My Team"
    role: member
    state: present