DO374 - ch09s02

Bookmark this page

Guided Exercise: Writing Ansible Content Collections

Create a content collection and publish it to a private automation hub.

Outcomes

Create a collection directory structure.
Add content to the collection.
Build the collection.
Publish the collection.

As the student user on the workstation machine, use the lab command to prepare your system for this exercise.

This command deploys the Ansible environment. It also prepares an Ansible project in the /home/student/create-writing/ directory on the workstation machine.

[student@workstation ~]$ lab start create-writing

Procedure 9.1. Instructions

Change to the /home/student/create-writing/ directory, and run the following command to create a collection:

[student@workstation ~]$ cd ~/create-writing/
[student@workstation create-writing]$ ansible-galaxy collection \
> init student.testcollection
- Collection student.testcollection was created successfully

Review the new collection.

Use the tree command to review the directory structure of the new collection.

[student@workstation create-writing]$ tree student/testcollection/
student/testcollection/
├── docs
├── galaxy.yml
├── plugins
│   └── README.md
├── README.md
└── roles

3 directories, 3 files

Review the collection metadata, such as namespace, name, and version in the galaxy.yml file. The following grep command displays any line that does not start with the # character and is not a blank line.

[student@workstation create-writing]$ cd student/testcollection/
[student@workstation testcollection]$ grep -Ev "^#|^$" galaxy.yml | head
namespace: student
name: testcollection
version: 1.0.0
readme: README.md
authors:
- your name <example@domain.com>
description: your collection description
license:
- GPL-2.0-or-later
license_file: ''

Create the meta/runtime.yml file to specify that the collection requires Ansible 2.9.10 or later to work.
1. Create the ~/create-writing/student/testcollection/meta/ directory.
```
[student@workstation testcollection]$ mkdir meta
```
2. Create the ~/create-writing/student/testcollection/meta/runtime.yml file with the following content:
```
---
requires_ansible: '>=2.9.10'
```

Place a module in this collection. Copy the myping.py module provided in the /home/student/create-writing/ directory.

[student@workstation testcollection]$ ls plugins/
README.md
[student@workstation testcollection]$ mkdir plugins/modules
[student@workstation testcollection]$ cp ~/create-writing/myping.py \
> plugins/modules/
[student@workstation testcollection]$ ls plugins/modules/
myping.py

Create a role inside the collection.

Use the ansible-galaxy command to create the mymotd role, and then change to the mymotd directory.

[student@workstation testcollection]$ cd roles/
[student@workstation roles]$ ansible-galaxy role init mymotd
- Role mymotd was created successfully
[student@workstation roles]$ cd mymotd/

Create the templates/motd.j2 template in the role with the following content. This example shows setting the_date variable with Jinja2 so that a date such as September 26, 2022 displays as 26-Sep-2022. The date(1) man page contains information about formatting options.
```
{% set the_date = '%d-%b-%Y' | strftime(ansible_facts['date_time']['epoch']) %}
Connected to: {{ ansible_facts['fqdn'] }}
Ansible last updated the /etc/motd file on {{ the_date }}.
```

Create the tasks/main.yml task file in the role with following content.

---
# tasks file for mymotd
- name: update the /etc/motd file
  ansible.builtin.template:
    src: motd.j2
    dest: /etc/motd
    owner: root
    group: root
    mode: '0444'

Use the tree command to review the new directory structure of the collection.

[student@workstation mymotd]$ cd ~/create-writing/student/testcollection/
[student@workstation testcollection]$ tree
.
├── docs
├── galaxy.yml
├── meta
│   └── runtime.yml
├── plugins
│   ├── modules
│   │   └── myping.py
│   └── README.md
├── README.md
└── roles
    └── mymotd
        ├── defaults
        │   └── main.yml
        ├── files
        ├── handlers
        │   └── main.yml
        ├── meta
        │   └── main.yml
        ├── README.md
        ├── tasks
        │   └── main.yml
        ├── templates
        │   └── motd.j2
        ├── tests
        │   ├── inventory
        │   └── test.yml
        └── vars
            └── main.yml

14 directories, 14 files

Delete the unneeded files and directories created by the ansible-galaxy collection init and the ansible-galaxy role init commands. Red Hat recommends that you delete unneeded files and directories.

[student@workstation testcollection]$ rm -vr docs \
> roles/mymotd/{defaults,files,handlers,tests,vars}
removed directory 'docs'
removed 'roles/mymotd/defaults/main.yml'
removed directory 'roles/mymotd/defaults/'
removed directory 'roles/mymotd/files'
removed 'roles/mymotd/handlers/main.yml'
removed directory 'roles/mymotd/handlers'
removed 'roles/mymotd/tests/inventory'
removed 'roles/mymotd/tests/test.yml'
removed directory 'roles/mymotd/tests'
removed 'roles/mymotd/vars/main.yml'
removed directory 'roles/mymotd/vars'
[student@workstation testcollection]$ tree
.
├── galaxy.yml
├── meta
│   └── runtime.yml
├── plugins
│   ├── modules
│   │   └── myping.py
│   └── README.md
├── README.md
└── roles
    └── mymotd
        ├── meta
        │   └── main.yml
        ├── README.md
        ├── tasks
        │   └── main.yml
        └── templates
            └── motd.j2

8 directories, 9 files

Use the ansible-galaxy command to build the collection.

[student@workstation testcollection]$ ansible-galaxy collection build
Created collection for student.testcollection at /home/student/create-writing/student/testcollection/student-testcollection-1.0.0.tar.gz
[student@workstation testcollection]$ ls
galaxy.yml  meta  plugins  README.md  roles  student-testcollection-1.0.0.tar.gz

Create the student namespace in private automation hub and then upload and approve the new collection.
1. Navigate to https://hub.lab.example.com and log in as the student user with redhat123 as the password.
2. From the private automation hub web UI, navigate to Collections → Namespaces and then click Create.
3. On the Create new namespace page, complete the details as follows and then click Create to create the namespace.
  Field Value
  Name student
  Namespace owners Content Developers
  Important
  The Content Developers group must be a namespace owner for group members, such as the student user, to upload to the namespace.
4. Click Upload collection.
5. Click Select file. Select the archive located at /home/student/create-writing/student/testcollection/student-testcollection-1.0.0.tar.gz and then click Upload.
  Even though the private automation hub web UI displays a message about a missing CHANGELOG.rst file, the collection uploads successfully.
6. Click Collections → Approval and then click Approve to approve the student.testcollection collection.
7. Navigate to Collections → Collections and verify that the private automation hub server displays the testcollection automation content collection.

Field	Value
Name	`student`
Namespace owners	`Content Developers`

Use the ansible-galaxy command to install the student.testcollection collection from private automation hub.

Change to the /home/student/create-writing/ directory.

[student@workstation testcollection]$ cd ~/create-writing/

From the private automation hub web UI, navigate to Collections → Repository Management. Copy the CLI configuration for the published repository.

Update the /home/student/create-writing/ansible.cfg file to include the published repository. Paste the configuration copied in the previous step.

[defaults]
inventory = ./inventory
remote_user = devops
collections_paths = ./collections:/usr/share/ansible/collections

[galaxy]
server_list = published_repo

[galaxy_server.published_repo]
url=https://hub.lab.example.com/api/galaxy/content/published/
token=<put your token here>

From the private automation hub web UI, navigate to Collections → API token management and then click Load token. Click the Copy to clipboard icon.

Update the /home/student/create-writing/ansible.cfg file. Modify the token line to use the API token copied in the previous step. Your token is different from the one displayed in this example.

[defaults]
inventory = ./inventory
remote_user = devops
collections_paths = ./collections:/usr/share/ansible/collections

[galaxy]
server_list = published_repo

[galaxy_server.published_repo]
url=https://hub.lab.example.com/api/galaxy/content/published/
token=adc9fea87c50206c439ca3bb39a9404c6c600cf3

The project includes a ~/create-writing/collections/requirements.yml file that references the student.testcollection collection. Review the file to confirm that the contents are as follows:
```
---
collections:
  - name: student.testcollection
```

Ensure that you are in the /home/student/create-writing directory, and install the collection using the ansible-galaxy command. The collection is installed into the ./collections directory so that it is loaded into the automation execution environment.

[student@workstation create-writing]$ ansible-galaxy collection \
> install -r collections/requirements.yml -p collections/
Starting galaxy collection install process
Process install dependency map
Starting collection install process
Downloading https://hub.lab.example.com/api/galaxy/v3/plugin/ansible/content/published/collections/artifacts/student-testcollection-1.0.0.tar.gz to /home/student/.ansible/tmp/ansible-local-247766f2gkx05/tmptvok5tde/student-testcollection-1.0.0-nb_d_xxi
Installing 'student.testcollection:1.0.0' to '/home/student/create-writing/collections/ansible_collections/student/testcollection'
student.testcollection:1.0.0 was installed successfully

Review and run the site.yml playbook to test the student.testcollection collection.

Review the site.yml playbook.

---
- name: Test custom collection
  hosts: serverd.lab.example.com
  become: true

  roles:
    - role: student.testcollection.mymotd

Use the ansible-navigator run command to run the site.yml playbook.

[student@workstation create-writing]$ ansible-navigator run site.yml \
> -m stdout

PLAY [Test custom collection] **************************************************

TASK [Gathering Facts] *********************************************************
ok: [serverd.lab.example.com]

TASK [student.testcollection.mymotd : update the /etc/motd file] ***************
changed: [serverd.lab.example.com]

PLAY RECAP *********************************************************************
serverd.lab.example.com    : ok=2    changed=1    unreachable=0    failed=0  ...

Log in to serverd to verify that the play was successful. The date displayed on your server is different from this example.

[student@workstation create-writing]$ ssh serverd
Connected to: serverd.lab.example.com
Ansible last updated the /etc/motd file on 16-Jan-2023.
...output omitted...
[student@serverd ~]$ logout
Connection to serverd closed.
[student@workstation create-writing]$

Finish

On the workstation machine, change to the student user home directory and use the lab command to complete this exercise. This step is important to ensure that resources from previous exercises do not impact upcoming exercises.

[student@workstation ~]$ lab finish create-writing

This concludes the section.

Discuss Developing Advanced Automation with Red Hat Ansible Automation Platform

Go to community

Welcome to the Developing Advanced Automation with Red Hat Ansible Automation (DO374) group!

Deanna

12 wrz 2023

We are excited to launch a space dedicated to the Red Hat Training course Developing Advanced Automation with Red Hat Ansible Automation Platform! To gain the most value from this group - click the "Join Group" button in the upper right hand corner of the group home page.We encourage group members to collaborate in this group to discuss topics, ask questions, share best practices and tips, provide course feedback, and share their accomplishments as it relates to DO374.Read more about Developing Advanced Automation with Red Hat Ansible Automation Platform here.

2367

Revision: do374-2.2-82dc0d7

Developing Advanced Automation with Red Hat Ansible Automation Platform

Guided Exercise: Writing Ansible Content Collections

Important