Developing Advanced Automation with Red Hat Ansible Automation Platform
- Section Reusing Content from Ansible Content Collections
- Guided Exercise: Reusing Content from Ansible Content Collections
- Finding and Installing Ansible Content Collections
- Guided Exercise: Finding and Installing Ansible Content Collections
- Selecting an Execution Environment
- Guided Exercise: Selecting an Execution Environment
- Lab: Managing Content Collections and Execution Environments
- Summary
Abstract
| Goal |
Run playbooks that use content collections not included in |
| Objectives |
|
| Sections |
|
| Lab |
|
Describe how Ansible Content Collections are used to distribute modules and plug-ins, and create plays that use content from them.
Ansible Content Collections are a distribution format for Ansible content. A collection provides a set of related modules, roles, and plug-ins that you can download to your control node and then use in your playbooks.
For example:
The
redhat.insightscollection groups modules and roles that you can use to register a system with Red Hat Insights for Red Hat Enterprise Linux.The
cisco.ioscollection groups modules and plug-ins that manage Cisco IOS network appliances. The Cisco company supports and maintains that collection.The
community.cryptocollection provides modules that create SSL/TLS certificates.
You can use collections to separate core Ansible code updates from updates to modules and plug-ins. Vendors and developers can then maintain and distribute their collections at their own pace, independently of Ansible releases. You can develop your own collections to provide custom roles and modules to your teams.
Collections also give you more flexibility. By using collections, you can install only the content you need instead of installing all supported modules. You can also select a specific version of a collection (possibly an earlier or a later one) or choose between a version of a collection supported by Red Hat and one provided by the community.
Upstream Ansible unbundled most modules from the core Ansible code in Ansible Base 2.10 and Ansible Core 2.11 and placed them in collections. Red Hat Ansible Automation Platform 2.2 provides automation execution environments based on Ansible Core 2.13 that inherit this feature.
To make it easier to specify collections and their contents by name, collection names are organized into namespaces. Vendors, partners, developers, and content creators can use namespaces to assign unique names to their collections without conflicting with other developers.
The namespace is the first part of a collection name.
For example, all the collections that the Ansible community maintain are in the community namespace, and have names such as community.crypto, community.postgresql, and community.rabbitmq.
Collections that Red Hat maintain and support might use the redhat namespace, and have names such as redhat.rhv, redhat.satellite, and redhat.insights.
Names of namespaces are limited to ASCII lowercase letters, numbers, and underscores, must be at least two characters long, and must not start with an underscore.
The automation execution environments that Red Hat provides already include some collections. You can install additional collections on your local system or create a custom automation execution environment that incorporates these collections. Other sections of the course present those subjects in more detail.
Use the ansible-navigator collections command to list the collections available in automation execution environments.
The following output shows the collections available in the ee-supported-rhel8 automation execution environment:
Name Version Shadowed Type Path 0│amazon.aws 3.2.0 False contained /usr/share/ansible/collec 1│ansible.builtin 2.13.3 False contained /usr/lib/python3.9/site-p 2│ansible.controller 4.2.1 False contained /usr/share/ansible/collec 3│ansible.netcommon 3.0.0 False contained /usr/share/ansible/collec 4│ansible.network 1.2.0 False contained /usr/share/ansible/collec 5│ansible.posix 1.3.0 False contained /usr/share/ansible/collec 6│ansible.security 1.0.0 False contained /usr/share/ansible/collec 7│ansible.utils 2.6.1 False contained /usr/share/ansible/collec 8│ansible.windows 1.9.0 False contained /usr/share/ansible/collec 9│ansible.yang 1.0.0 False contained /usr/share/ansible/collec 10│arista.eos 5.0.0 False contained /usr/share/ansible/collec ...output omitted... 21│redhat.insights 1.0.7 False contained /usr/share/ansible/collec 22│redhat.openshift 2.1.0 False contained /usr/share/ansible/collec ...output omitted...
To list the modules and plug-ins for a collection, type the associated collection number.
If the collection number is greater than nine, type a colon before the collection number, for example, :21, for line 21, and then press Enter.
The following output shows the modules available in the redhat.insights collection.
Redhat.insights Type Added Deprecated Description 0│compliance role Unknown Unknown Install and configure Red 1│insights inventory None False insights inventory source 2│insights_client role Unknown Unknown Install and configure Red 3│insights_config module None False This module handles initi 4│insights_register module None False This module registers the
Enter the module number to access its documentation.
The ansible-navigator collections command renders the documentation in the YAML format by default.
You can use the --mode stdout (or -m stdout) option of the ansible-navigator doc command to render the documentation in plain text.
For example, the following command displays the documentation of the insights_register module:
[user@host ~]$ansible-navigator doc redhat.insights.insights_register \>--mode stdout> REDHAT.INSIGHTS.INSIGHTS_REGISTER (/usr/share/ansible/collections/ansible_> This module will check the current registration status, unregister if needed, and then register the insights client (and update the display_name if needed) OPTIONS (= is mandatory): - display_name This option is here to enable registering with a display_name outside of using a configuration file. Some may be used to doing it this way so I left this in as an optional parameter. [Default: (null)] type: str - force_reregister This option should be set to true if you wish to force a reregister of the insights-client. Note that this will remove the existing machine-id and create a new one. Only use this option if you are okay with creating a new machine-id. [Default: False] type: bool ...output omitted...
To use a module or a role from a collection, refer to it with its fully qualified collection name (FQCN).
For example, use redhat.insights.insights_register to refer to the insights_register module.
The play in the following playbook includes a task that calls the insights_register module.
---
- name: Register new systems
hosts: db.example.com
tasks:
- name: Ensure the new system is registered with Red Hat Insights
redhat.insights.insights_register:
state: present
force_reregister: trueThe play in the following playbook uses the organizations role from the redhat.satellite collection.
---
- name: Add the test organizations to Red Hat Satellite
hosts: localhost
tasks:
- name: Ensure the organizations exist
ansible.builtin.include_role:
name: redhat.satellite.organizations
vars:
satellite_server_url: https://sat.example.com
satellite_username: admin
satellite_password: Sup3r53cr3t
satellite_organizations:
- name: test1
label: tst1
state: present
description: Test organization 1
- name: test2
label: tst2
state: present
description: Test organization 2The play in the following playbook uses the k8s lookup plug-in from the kubernetes.core collection:
---
- name: Fetch the namespaces from Kubernetes
hosts: localhost
tasks:
- name: Retrieve the namespaces as a list
ansible.builtin.set_fact:
ns: "{{ lookup('kubernetes.core.k8s', kind='Namespace') }}"If you plan to update legacy playbooks that use modules moved to collections, then you need to identify in which collection these modules are now available.
The https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_runtime.yml file maps earlier module names from Ansible 2.9 to their new FQCNs.
For example, the following extract from that file shows that the acl module is now part of the ansible.posix collection, which uses ansible.posix.acl as its FQCN.
...output omitted...acl: redirect:ansible.posix.aclsynchronize: redirect: ansible.posix.synchronize at: redirect: ansible.posix.at authorized_key: redirect: ansible.posix.authorized_key mount: redirect: ansible.posix.mount seboolean: redirect: ansible.posix.seboolean selinux: redirect: ansible.posix.selinux ...output omitted...
This redirection mechanism is also used by many Ansible Content Collections to translate short names to FQCNs, so that playbooks written for Ansible 2.9 (Red Hat Ansible Automation Platform 1.2) require less immediate migration work.
Note
For playbooks that do not use Ansible Content Collections, you can manage the migration process by using the ee-29-rhel8 automation execution environment.
That automation execution environment provides Ansible 2.9, which does not require collections.
Ansible always includes a special collection named ansible.builtin.
This collection includes a set of common modules, such as copy, template, file, yum, command, and service.
You can use the short names of these modules in your playbooks.
For example, you can use file to refer to the ansible.builtin.file module.
This mechanism allows many existing Ansible Playbooks to work without modification, although you might need to install additional collections for modules that are not included in the ansible.builtin special collection.
However, Red Hat recommends that you use the FQCN notation to prevent conflicts with collections that might use the same module names.
The following playbook uses the FQCN notation for the yum, copy, and service modules.
---
- name: Install and start Apache HTTPD
hosts: web
tasks:
- name: Ensure the httpd package is present
ansible.builtin.yum:
name: httpd
state: present
- name: Ensure the index.html file is present
ansible.builtin.copy:
src: files/index.html
dest: /var/www/html/index.html
owner: root
group: root
mode: 0644
setype: httpd_sys_content_t
- name: Ensure the httpd service is started
ansible.builtin.service:
name: httpd
state: started
enabled: true
