Merge pull request ansible#941 from giannisalinetti/pr-ansible-collections

Adding exercises for Ansible Collections

I'll merge this for now. There is some more work needed until we will add it to the main README.md and make it an official lab which can be picked and deployed. But we can work in dedicated PRs on that.

Author: Roland Wolters

exercises/ansible_collections/1-create-collections/README.md

@@ -0,0 +1,83 @@
+#!/usr/bin/python
+
+import random
+
+ANSIBLE_METADATA = {
+    'metadata_version': '1.0',
+    'status': ['preview'],
+    'supported_by': 'community'
+}
+
+DOCUMENTATION = '''
+---
+module: demo_hello
+short_description: A module that says hello in many languages
+version_added: "2.8"
+description:
+    - "A module that says hello in many languages."
+options:
+    name:
+        default: John Doe
+author:
+    - Gianni Salinetti (@giannisalinetti)
+'''
+
+EXAMPLES = '''
+# Pass in a custom name
+- name: Say hello to Linus Torwalds
+  demo_hello:
+    name: "Linus Torwalds"
+'''
+
+RETURN = '''
+fact:
+  description: Hello string
+  type: str
+  sample: Hello John Doe!
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+FACTS = [
+    "Hello {name}!",
+    "Bonjour {name}!",
+    "Hola {name}!",
+    "Ciao {name}!",
+    "Hallo {name}!",
+    "Hei {name}!",
+]
+
+
+def run_module():
+    module_args = dict(
+        name=dict(type='str', default='John Doe'),
+    )
+
+    module = AnsibleModule(
+        argument_spec=module_args,
+        supports_check_mode=True
+    )
+
+    result = dict(
+        changed=False,
+        fact=''
+    )
+
+    result['fact'] = random.choice(FACTS).format(
+        name=module.params['name']
+    )
+
+    if module.check_mode:
+        return result
+
+    module.exit_json(**result)
+
+
+def main():
+    run_module()
+
+
+if __name__ == '__main__':
+    main()
+

exercises/ansible_collections/1-create-collections/solutions/modules/demo_hello.py

@@ -0,0 +1,29 @@
+---
+language: python
+python: "2.7"
+
+# Use the new container infrastructure
+sudo: false
+
+# Install ansible
+addons:
+  apt:
+    packages:
+      - python-pip
+
+install:
+  # Install ansible
+  - pip install ansible
+
+  # Check ansible version
+  - ansible --version
+
+  # Create ansible.cfg with correct roles_path
+  - printf '[defaults]\nroles_path=../' >ansible.cfg
+
+script:
+  # Basic role syntax check
+  - ansible-playbook tests/test.yml -i tests/inventory --syntax-check
+
+notifications:
+  webhooks: https://galaxy.ansible.com/api/v1/notifications/

exercises/ansible_collections/1-create-collections/solutions/roles/demo_image_builder/.travis.yml

@@ -0,0 +1,38 @@
+Role Name
+=========
+
+A brief description of the role goes here.
+
+Requirements
+------------
+
+Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
+
+Role Variables
+--------------
+
+A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
+
+Dependencies
+------------
+
+A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
+
+Example Playbook
+----------------
+
+Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
+
+    - hosts: servers
+      roles:
+         - { role: username.rolename, x: 42 }
+
+License
+-------
+
+BSD
+
+Author Information
+------------------
+
+An optional section for the role authors to include contact information, or a website (HTML is not allowed).

exercises/ansible_collections/1-create-collections/solutions/roles/demo_image_builder/README.md

@@ -0,0 +1,6 @@
+---
+# defaults file for redhat.demo_nginx
+friend_name: "John Doe"
+build_dir_path: "/tmp/demo_nginx_build"
+image_registry: "quay.io"
+registry_username: ""

exercises/ansible_collections/1-create-collections/solutions/roles/demo_image_builder/defaults/main.yml

@@ -0,0 +1,3 @@
+FROM nginx
+
+COPY index.html /usr/share/nginx/html

exercises/ansible_collections/1-create-collections/solutions/roles/demo_image_builder/files/Dockerfile

@@ -0,0 +1,21 @@
+---
+galaxy_info:
+  author: Ansible Automation Platform Hackaton Team
+  description: Basic builder role based on podman
+  company: Red Hat
+
+  license: Apache-2.0
+
+  min_ansible_version: 2.8
+
+
+  platforms:
+    - name: Fedora
+      versions:
+        - 31
+        - 32
+        - 33
+
+  galaxy_tags: ["demo", "podman"]
+
+dependencies: []

exercises/ansible_collections/1-create-collections/solutions/roles/demo_image_builder/meta/main.yml

@@ -0,0 +1,45 @@
+---
+# tasks file for redhat.demo_nginx
+- name: Ensure podman is present in the host
+  dnf:
+    name: podman
+    state: present
+  become: true
+
+- name: Generate greeting and store result
+  demo_hello:
+    name: "{{ friend_name }}"
+  register: demo_greeting
+
+- name: Create build directory
+  file:
+    path: "{{ build_dir_path }}"
+    state: directory
+    mode: 0755
+
+- name: Copy Dockerfile
+  copy:
+    src: files/Dockerfile
+    dest: "{{ build_dir_path }}"
+    mode: 0644
+
+- name: Copy custom index.html
+  template:
+    src: templates/index.html.j2
+    dest: "{{ build_dir_path }}/index.html"
+    mode: 0644
+
+- name: Build and Push OCI image
+  podman_image:
+    name: demo-nginx
+    path: "{{ build_dir_path }}"
+    build:
+      annotation:
+        app: nginx
+        function: demo
+        info: Demo app for Ansible Collections workshop
+      format: oci
+    push: true
+    force: true
+    push_args:
+      dest: "{{ image_registry }}/{{ registry_username }}"

exercises/ansible_collections/1-create-collections/solutions/roles/demo_image_builder/tasks/main.yml

@@ -0,0 +1,21 @@
+<!doctype html>
+
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+
+  <title>Ansible Collections Workshop</title>
+  <meta name="description" content="Demo Nginx">
+  <meta name="author" content="gsalinet@redhat.com">
+
+  <link rel="stylesheet" href="css/styles.css?v=1.0">
+
+</head>
+
+<body>
+  <h1>
+    {{ demo_greeting.fact }}
+  </h1>
+</body>
+</html>
+

exercises/ansible_collections/1-create-collections/solutions/roles/demo_image_builder/templates/index.html.j2

@@ -0,0 +1,131 @@
+# Exercise 2 - Using Ansible Collections
+
+## Table of Contents
+
+- [Objective](#objective)
+- [Guide](#guide)
+    - [Step 1 - Install the Ansible Collection](#step-1---install-the-ansible-collection)
+    - [Step 2 - Write an Ansible Playbook](#step-2---write-an-ansible-playbook)
+    - [Step 3 - Test the playbook](#step-3---test-the-playbook)
+    - [Step 4 - Simplify the namespace](#step-4---simplify-the-namespace)
+    - [Step 5: Test the change](#step-5-test-the-change)
+
+# Objective
+
+In this part of the lab, you will learn how to use an Ansible Collection in your playbook. To identify a specific module from an Ansible Collection, we have to use the fully qualified collection name. This name is built from the name of the author, the name of the collection and the name of the module.
+
+    <author>.<collection>.<module>
+
+For the following exercise, we will use a collection written by the Ansible Core Team. The name of the author is therefore "ansible". You can find a list of all modules and collections written by the Ansible Core Team on [Ansible Galaxy](https://galaxy.ansible.com/ansible).
+
+As you can see they maintain several collections and roles. One of their collections is called "posix" and we can find the documentation and additional details on the [Ansible Galaxy POSIX Collection](https://galaxy.ansible.com/ansible/posix) page.
+
+One of the modules provided by this collection allows us to manage [SELinux](https://www.redhat.com/en/topics/linux/what-is-selinux) settings. The fully qualified collection name for this module is therefore `ansible.posix.selinux`.
+
+You can find more details about [using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) in the [Ansible Documentation](https://docs.ansible.com/).
+
+# Guide
+
+## Step 1 - Install the Ansible Collection
+
+The `ansible.posix.selinux` module which we want to use for this exercise, it part of the `ansible.posix` collection. We have to install this collection first, before we can use its modules. The `ansible-galaxy` command line tool can be used to automate the installation. It us preconfigured to search for roles and collections on [Ansible Galaxy](https://galaxy.ansible.com/) so we can just specify the collection name and it will take care of the rest:
+
+    ansible-galaxy collection install ansible.posix
+
+This will install collection on your system, only if it wasn't installed before. To force the installation, for example to make sure you're on the latest version, you can add the force switch `-f`.
+
+    ansible-galaxy collection install -f ansible.posix
+
+This will always download and install the latest version, even if it was already up to date. Ansible Collections can have dependencies for other Ansible Collections as well - if you want to make sure those dependencies are refreshed as well, you can use the `--force-with-deps` switch.
+
+By default the installation is stored in your local `~/.ansible` directory. This can be overwritten by using the `-p /path/to/collection` switch. Keep in mind though that `ansible-playbook` will only use that directory if you change your `ansible.cfg` accordingly.
+
+## Step 2 - Documentation
+
+The `ansible-doc` command only searches the system directories for documentation. You can still use it though to read up on modules you installed from Ansible Collections by using the fully qualified collection name.
+
+Let's have a look at the module documentation for the `selinux` module which we are going to use in the next part of the exercise:
+
+```bash
+ansible-doc ansible.posix.selinux
+```
+
+> **NOTE**: Depending on your screen resolution you might have to press `q` to leave the documentation viewer.
+
+## Step 3 - Write an Ansible Playbook
+
+We want to use the SELinux module to make sure it is configured in enforcing mode. SELinux is a kernel feature which brings extra security to our Linux system and it is highly recommended to always keep it enabled and in enforcing mode. If you're new to SELinux, there is a nice article on [What is SELinux](https://www.redhat.com/en/topics/linux/what-is-selinux) to get you started.
+
+Let's write a simple playbook which enables SELinux and sets it to enforcing mode on the local machine.
+
+```yaml
+---
+- name: set SELinux to enforcing
+  hosts: localhost
+  become: yes
+  tasks:
+  - name: set SElinux to enforcing
+    ansible.posix.selinux:
+      policy: targeted
+      state: enforcing
+```
+
+Save the playbook as `enforce-selinux.yml` for later.
+
+> **NOTE**: Pay special attention to the module name. Typically you would see something like `selinux`, but since we are using a module provided by an Ansible Collection, we have to specify the fully qualified module name.
+
+## Step 4 - Test the playbook
+
+You can run the Playbook and see what happens:
+
+    ansible-playbook enforce-selinux.yml
+
+You should see output like this:
+
+    [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
+
+    PLAY [set SELinux to enforcing] ***********************************************************************************
+
+    TASK [Gathering Facts] ********************************************************************************************
+    ok: [localhost]
+
+    TASK [set SElinux to enforcing] ***********************************************************************************
+    ok: [localhost]
+
+    PLAY RECAP ********************************************************************************************************
+    localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+
+If SELinux was not set to enforcing before, you might see "changed" instead of ok. If it did say "changed" and you run it a second time, you should now see "ok" - the magic of [Ansible idempotency](https://docs.ansible.com/ansible/latest/reference_appendices/glossary.html).
+
+## Step 5 - Simplify the namespace
+
+If you use many modules from Ansible Collections in your Playbook, the <author>.<collection> prefix can become quite annoying it reading your Playbook can become harder as well.
+
+You can use the `collections` key word to skip defining the namespace with every task.
+
+```yaml
+---
+- name: set SELinux to enforcing
+  hosts: localhost
+  become: yes
+  collections:
+  - ansible.posix
+  tasks:
+  - name: set SElinux to enforcing
+    selinux:
+      policy: targeted
+      state: enforcing
+```
+
+> **NOTE**: Although the syntax looks similar to how you specify roles, this works different. They keyword `roles` will execute the `tasks/main.yml` in each role. The `collections` keyword is merely a shortcut so you can skip the author and namespace every time you use a module in a task.
+
+## Step 6: Test the change
+
+When running the Playbook again, you shouldn't actually see any difference in the output. As explained before, the `collections` keyword only simplifies writing your Playbook.
+
+----
+**Navigation**
+<br>
+[Previous Exercise](../1-create-collections/) - [Next Exercise](../3-collections-from-roles)
+
+[Click here to return to the Ansible for Red Hat Enterprise Linux Workshop](../README.md)

exercises/ansible_collections/2-collections-from-playbook/README.md

@@ -0,0 +1,298 @@
+# Exercise 3 - Running Collections from Roles
+
+## Table of Contents
+
+- [Objective](#objective)
+- [Guide](#guide)
+    - [Step 1: Understand collections lookup](#step-1-understand-collections-lookup)
+    - [Step 2: Running collections from a role](step-2-running-collections-from-a-role)
+- [Takeaways](#takeaways)
+
+# Objective
+
+This exercise will help users understand how collections are used from within roles.
+
+Covered topics:
+
+- Explain collection resolution logic
+
+- Demonstrate how to call collections from roles using collection fully qualified collection name (FQCN)
+
+# Guide
+
+## Step 1: Understand collections lookup
+
+Ansible Collections use a simple method to define collection namespaces. Anyway, if
+your playbook loads collections using the `collections` key and one or more roles, then
+the roles will not inherit the collections set by the playbook.
+
+This leads to the main topic of this exercise: roles have an independent collection
+loading method based on the role's metadata.
+To control collections search for the tasks inside the role, users can choose between
+two approaches:
+
+- **Approach 1**: Pass a list of collections in the `collections` field inside the `meta/main.yml` file within the role.
+  This will ensure that the collections list searched by the role will have higher priority than
+  the collections list in the playbook. Ansible will use the collections list defined inside the role
+  even if the playbook that calls the role defines different collections in a separate `collections` keyword entry.
+
+  ```yaml
+  # myrole/meta/main.yml
+  collections:
+    - my_namespace.first_collection
+    - my_namespace.second_collection
+    - other_namespace.other_collection
+  ```
+
+- **Approach 2**: Use the collection fully qualified collection name (FQCN) directly from a task in the role.
+  In this way the collection will always be called with its unique FQCN, and override any other
+  lookup in the playbook
+
+  ```yaml
+  - name: Create an EC2 instance using collection by FQCN
+    amazon.aws.ec2:
+      key_name: mykey
+      instance_type: t2.micro
+      image: ami-123456
+      wait: yes
+      group: webserver
+      count: 3
+      vpc_subnet_id: subnet-29e63245
+      assign_public_ip: yes
+  ```
+
+Roles defined **within** a collection always implicitly search their own collection
+first, so there is no need to use the `collections` keyword in the role metadata to access modules, plugins, or other roles.
+
+## Step 2: Running collections from a role
+
+Create the exercise folder:
+
+```bash
+mkdir exercise-03
+cd esercise--3
+```
+
+For this lab, we will use the `ansible.posix` collection, which contains a series of POSIX
+oriented modules and plugins for systems management.
+
+```bash
+ansible-galaxy collection install ansible.posix
+```
+
+### Approach 1: Collections loaded as metadata
+
+> **TIP**: You can go though the exercise steps or copy the finished role from `solutions/selinux_manage_meta`.
+
+Create a new role using the `ansible-galaxy init` command:
+
+```bash
+ansible-galaxy init --init-path roles selinux_manage_meta
+```
+
+Edit the `roles/selinux_manage_meta/meta/main.yml` file and append the following lines at the end of the file, beginning at column 1:
+
+```yaml
+# Collections list
+collections:
+  - ansible.posix
+```
+
+Edit the `roles/selinux_manage_meta/tasks/main.yml` file and add the following tasks:
+
+```yaml
+---
+# tasks file for selinux_manage_meta
+- name: Enable SELinux enforcing mode
+  selinux:
+    policy: targeted
+    state: "{{ selinux_mode }}"
+
+- name: Enable booleans
+  seboolean:
+    name: "{{ item }}"
+    state: true
+    persistent: true
+  loop: "{{ sebooleans_enable }}"
+
+- name: Disable booleans
+  seboolean:
+    name: "{{ item }}"
+    state: false
+    persistent: true
+  loop: "{{ sebooleans_disable }}"
+```
+
+> **NOTE:** We're using the simple module name. Ansible uses the information from the
+> `collections` list in the metadata file to locate the collection(s) used.
+
+Edit the `roles/selinux_manage_meta/defaults/main.yml` to define default values for role variables:
+
+```yaml
+---
+# defaults file for selinux_manage_meta
+selinux_mode: enforcing
+sebooleans_enable: []
+sebooleans_disable: []
+```
+
+Cleanup unused folders in the role:
+
+```bash
+rm -rf roles/selinux_manage_meta/{tests,vars,handlers,files,templates}
+```
+
+We can now test the new role with a basic playbook. Create the `playbook.yml` file
+in the current folder with the following content:
+
+```yaml
+---
+- hosts: localhost
+  become: true
+  vars:
+    sebooleans_enable:
+      - httpd_can_network_connect
+      - httpd_mod_auth_pam
+    sebooleans_disable:
+      - httpd_enable_cgi
+  roles:
+    - selinux_manage_meta
+```
+
+Run the playbook and check the results:
+
+```bash
+$ ansible-playbook playbook.yml
+[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
+
+PLAY [localhost] ******************************************************************************************************
+
+TASK [Gathering Facts] ************************************************************************************************
+ok: [localhost]
+
+TASK [selinux_manage_meta : Enable SELinux enforcing mode] ************************************************************
+ok: [localhost]
+
+TASK [selinux_manage_meta : Enable booleans] **************************************************************************
+changed: [localhost] => (item=httpd_can_network_connect)
+changed: [localhost] => (item=httpd_mod_auth_pam)
+
+TASK [selinux_manage_meta : Disable booleans] *************************************************************************
+changed: [localhost] => (item=httpd_can_network_connect)
+
+PLAY RECAP ************************************************************************************************************
+localhost                  : ok=4    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+```
+
+### Approach 2: Collections loaded with FQCN
+
+The second approach uses the collection FQCN to call the related modules and plugins. To better demonstrate the differences, we will implement a new version of the previous role with the FQCN approach without changing the inner logic.
+
+> **TIP**: You can go though the exercise steps or copy the finished role from `solutions/selinux_manage_fqcn`.
+
+Create a new role using the `ansible-galaxy init` command:
+
+```bash
+ansible-galaxy init --init-path roles selinux_manage_fqcn
+```
+
+Edit the `roles/selinux_manage_fqcn/tasks/main.yml` file and add the following tasks:
+
+```yaml
+---
+# tasks file for selinux_manage_fqcn
+- name: Enable SELinux enforcing mode
+  ansible.posix.selinux:
+    policy: targeted
+    state: "{{ selinux_mode }}"
+
+- name: Enable booleans
+  ansible.posix.seboolean:
+    name: "{{ item }}"
+    state: true
+    persistent: true
+  loop: "{{ sebooleans_enable }}"
+
+- name: Disable booleans
+  ansible.posix.seboolean:
+    name: "{{ item }}"
+    state: false
+    persistent: true
+  loop: "{{ sebooleans_disable }}"
+```
+
+> **NOTE**: Notice the usage of the modules FQCN in the role tasks. Ansible will directly
+> look for the installed collection from within the role task, no matter if
+> the `collections` keyword is defined at playbook level.
+
+Edit the `roles/selinux_manage_fqcn/defaults/main.yml` to define default values for role variables:
+
+```yaml
+---
+# defaults file for selinux_manage_fqcn
+selinux_mode: enforcing
+sebooleans_enable: []
+sebooleans_disable: []
+```
+
+Cleanup unused folders in the role:
+
+```bash
+rm -rf roles/selinux_manage_meta/{tests,vars,handlers,files,templates}
+```
+
+Modify the previous `playbook.yml` file to use the new role:
+
+```yaml
+---
+- hosts: localhost
+  become: true
+  vars:
+    sebooleans_enable:
+      - httpd_can_network_connect
+      - httpd_mod_auth_pam
+    sebooleans_disable:
+      - httpd_enable_cgi
+  roles:
+    - selinux_manage_FQCN
+```
+
+Run the playbook again and check the results:
+
+```bash
+$ ansible-playbook playbook.yml
+[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
+
+PLAY [localhost] ******************************************************************************************************
+
+TASK [Gathering Facts] ************************************************************************************************
+ok: [localhost]
+
+TASK [selinux_manage_meta : Enable SELinux enforcing mode] ************************************************************
+ok: [localhost]
+
+TASK [selinux_manage_meta : Enable booleans] **************************************************************************
+changed: [localhost] => (item=httpd_can_network_connect)
+ok: [localhost] => (item=httpd_mod_auth_pam)
+
+TASK [selinux_manage_meta : Disable booleans] *************************************************************************
+changed: [localhost] => (item=httpd_can_network_connect)
+
+PLAY RECAP ************************************************************************************************************
+localhost                  : ok=4    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+```
+
+This concludes the guided exercise.
+
+# Takeaways
+
+- Collections can be called from roles using the `collections` list defined in `meta/main.yml`.
+
+- Collections can be called from roles using their FQCN directly from the role task.
+
+----
+**Navigation**
+<br>
+[Previous Exercise](../2-collections-from-playbook/) - [Next Exercise](../4-collections-from-tower)
+
+[Click here to return to the Ansible for Red Hat Enterprise Linux Workshop](../README.md)

exercises/ansible_collections/3-collections-from-roles/README.md

@@ -0,0 +1,29 @@
+---
+language: python
+python: "2.7"
+
+# Use the new container infrastructure
+sudo: false
+
+# Install ansible
+addons:
+  apt:
+    packages:
+      - python-pip
+
+install:
+  # Install ansible
+  - pip install ansible
+
+  # Check ansible version
+  - ansible --version
+
+  # Create ansible.cfg with correct roles_path
+  - printf '[defaults]\nroles_path=../' >ansible.cfg
+
+script:
+  # Basic role syntax check
+  - ansible-playbook tests/test.yml -i tests/inventory --syntax-check
+
+notifications:
+  webhooks: https://galaxy.ansible.com/api/v1/notifications/

exercises/ansible_collections/3-collections-from-roles/solutions/selinux_manage_fqcn/.travis.yml

@@ -0,0 +1,38 @@
+Role Name
+=========
+
+A brief description of the role goes here.
+
+Requirements
+------------
+
+Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
+
+Role Variables
+--------------
+
+A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
+
+Dependencies
+------------
+
+A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
+
+Example Playbook
+----------------
+
+Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
+
+    - hosts: servers
+      roles:
+         - { role: username.rolename, x: 42 }
+
+License
+-------
+
+BSD
+
+Author Information
+------------------
+
+An optional section for the role authors to include contact information, or a website (HTML is not allowed).

exercises/ansible_collections/3-collections-from-roles/solutions/selinux_manage_fqcn/README.md

@@ -0,0 +1,6 @@
+---
+# defaults file for selinux_manage_fqdn
+selinux_mode: enforcing
+
+sebooleans_enable: []
+sebooleans_disable: []

exercises/ansible_collections/3-collections-from-roles/solutions/selinux_manage_fqcn/defaults/main.yml

@@ -0,0 +1,53 @@
+---
+galaxy_info:
+  author: your name
+  description: your role description
+  company: your company (optional)
+
+  # If the issue tracker for your role is not on github, uncomment the
+  # next line and provide a value
+  # issue_tracker_url: http://example.com/issue/tracker
+
+  # Choose a valid license ID from https://spdx.org - some suggested licenses:
+  # - BSD-3-Clause (default)
+  # - MIT
+  # - GPL-2.0-or-later
+  # - GPL-3.0-only
+  # - Apache-2.0
+  # - CC-BY-4.0
+  license: license (GPL-2.0-or-later, MIT, etc)
+
+  min_ansible_version: 2.9
+
+  # If this a Container Enabled role, provide the minimum Ansible Container version.
+  # min_ansible_container_version:
+
+  #
+  # Provide a list of supported platforms, and for each platform a list of versions.
+  # If you don't wish to enumerate all versions for a particular platform, use 'all'.
+  # To view available platforms and versions (or releases), visit:
+  # https://galaxy.ansible.com/api/v1/platforms/
+  #
+  # platforms:
+  # - name: Fedora
+  #   versions:
+  #   - all
+  #   - 25
+  # - name: SomePlatform
+  #   versions:
+  #   - all
+  #   - 1.0
+  #   - 7
+  #   - 99.99
+
+  galaxy_tags: []
+  # List tags for your role here, one per line. A tag is a keyword that describes
+  # and categorizes the role. Users find roles by searching for tags. Be sure to
+  # remove the '[]' above, if you add tags to this list.
+  #
+  # NOTE: A tag is limited to a single word comprised of alphanumeric characters.
+  #       Maximum 20 tags per role.
+
+dependencies: []
+# List your role dependencies here, one per line. Be sure to remove the '[]' above,
+# if you add dependencies to this list.

exercises/ansible_collections/3-collections-from-roles/solutions/selinux_manage_fqcn/meta/main.yml

@@ -0,0 +1,20 @@
+---
+# tasks file for selinux_manage_fqdn
+- name: Enable SELinux enforcing mode
+  ansible.posix.selinux:
+    policy: targeted
+    state: "{{ selinux_mode }}"
+
+- name: Enable booleans
+  ansible.posix.seboolean:
+    name: "{{ item }}"
+    state: true
+    persistent: true
+  loop: "{{ sebooleans_enable }}"
+
+- name: Disable booleans
+  ansible.posix.seboolean:
+    name: "{{ item }}"
+    state: false
+    persistent: true
+  loop: "{{ sebooleans_disable }}"

exercises/ansible_collections/3-collections-from-roles/solutions/selinux_manage_fqcn/tasks/main.yml

@@ -0,0 +1,29 @@
+---
+language: python
+python: "2.7"
+
+# Use the new container infrastructure
+sudo: false
+
+# Install ansible
+addons:
+  apt:
+    packages:
+      - python-pip
+
+install:
+  # Install ansible
+  - pip install ansible
+
+  # Check ansible version
+  - ansible --version
+
+  # Create ansible.cfg with correct roles_path
+  - printf '[defaults]\nroles_path=../' >ansible.cfg
+
+script:
+  # Basic role syntax check
+  - ansible-playbook tests/test.yml -i tests/inventory --syntax-check
+
+notifications:
+  webhooks: https://galaxy.ansible.com/api/v1/notifications/

exercises/ansible_collections/3-collections-from-roles/solutions/selinux_manage_meta/.travis.yml

@@ -0,0 +1,38 @@
+Role Name
+=========
+
+A brief description of the role goes here.
+
+Requirements
+------------
+
+Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
+
+Role Variables
+--------------
+
+A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
+
+Dependencies
+------------
+
+A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
+
+Example Playbook
+----------------
+
+Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
+
+    - hosts: servers
+      roles:
+         - { role: username.rolename, x: 42 }
+
+License
+-------
+
+BSD
+
+Author Information
+------------------
+
+An optional section for the role authors to include contact information, or a website (HTML is not allowed).

exercises/ansible_collections/3-collections-from-roles/solutions/selinux_manage_meta/README.md

@@ -0,0 +1,6 @@
+---
+# defaults file for selinux_manage_meta
+selinux_mode: enforcing
+
+sebooleans_enable: []
+sebooleans_disable: []

exercises/ansible_collections/3-collections-from-roles/solutions/selinux_manage_meta/defaults/main.yml

@@ -0,0 +1,57 @@
+---
+galaxy_info:
+  author: your name
+  description: your role description
+  company: your company (optional)
+
+  # If the issue tracker for your role is not on github, uncomment the
+  # next line and provide a value
+  # issue_tracker_url: http://example.com/issue/tracker
+
+  # Choose a valid license ID from https://spdx.org - some suggested licenses:
+  # - BSD-3-Clause (default)
+  # - MIT
+  # - GPL-2.0-or-later
+  # - GPL-3.0-only
+  # - Apache-2.0
+  # - CC-BY-4.0
+  license: license (GPL-2.0-or-later, MIT, etc)
+
+  min_ansible_version: 2.9
+
+  # If this a Container Enabled role, provide the minimum Ansible Container version.
+  # min_ansible_container_version:
+
+  #
+  # Provide a list of supported platforms, and for each platform a list of versions.
+  # If you don't wish to enumerate all versions for a particular platform, use 'all'.
+  # To view available platforms and versions (or releases), visit:
+  # https://galaxy.ansible.com/api/v1/platforms/
+  #
+  # platforms:
+  # - name: Fedora
+  #   versions:
+  #   - all
+  #   - 25
+  # - name: SomePlatform
+  #   versions:
+  #   - all
+  #   - 1.0
+  #   - 7
+  #   - 99.99
+
+  galaxy_tags: []
+  # List tags for your role here, one per line. A tag is a keyword that describes
+  # and categorizes the role. Users find roles by searching for tags. Be sure to
+  # remove the '[]' above, if you add tags to this list.
+  #
+  # NOTE: A tag is limited to a single word comprised of alphanumeric characters.
+  #       Maximum 20 tags per role.
+
+dependencies: []
+# List your role dependencies here, one per line. Be sure to remove the '[]' above,
+# if you add dependencies to this list.
+
+# Collections list
+collections:
+  - ansible.posix

exercises/ansible_collections/3-collections-from-roles/solutions/selinux_manage_meta/meta/main.yml

@@ -0,0 +1,20 @@
+---
+# tasks file for selinux_manage_meta
+- name: Enable SELinux enforcing mode
+  selinux:
+    policy: targeted
+    state: "{{ selinux_mode }}"
+
+- name: Enable booleans
+  seboolean:
+    name: "{{ item }}"
+    state: true
+    persistent: true
+  loop: "{{ sebooleans_enable }}"
+
+- name: Disable booleans
+  seboolean:
+    name: "{{ item }}"
+    state: false
+    persistent: true
+  loop: "{{ sebooleans_disable }}"

exercises/ansible_collections/3-collections-from-roles/solutions/selinux_manage_meta/tasks/main.yml

@@ -0,0 +1,60 @@
+# Exercise 4 - How to use Collections on Red Hat Ansible Tower
+
+## Table of Contents
+
+- [Objective](#objective)
+- [Guide](#guide)
+    - [Step 1 - Write a requirements.yml](#step-1---write-a-requirementsyml)
+    - [Step 2 - Create Job Template](#step-2---create-job-template)
+- [Troubleshooting](#troubleshooting)
+
+# Objective
+
+Red Hat Ansible Tower supports Ansible Collections starting with version 3.5 - earlier version will not automatically install and configure them for you. To make sure Ansible Collections are recognized by Red Hat Ansible Tower a requirements file is needed and has to be stored in the proper directory.
+
+Ansible Galaxy is already configured by default, however if you want your Red Hat Ansible Tower to prefer and fetch content from the Red Hat Automation Hub, additional configuration changes are required. They are addressed in a the chapter [Use Automation Hub](../7-use-automation-hub/) in this lab.
+
+# Guide
+
+In this exercise you will learn how to define an Ansible Collection as a requirement in a format recognized by Red Hat Ansible Tower.
+
+## Step 1 - Write a requirements.yml
+
+Red Hat Ansible Tower can download and install Ansible Collections automatically before executing a Job Template. If a `collections/requirements.yml` exists, it will be parsed and Ansible Collections specified in this file will be automatically installed.
+
+> **NOTE**: Starting with Red Hat Ansible Tower 3.6 the working directory for the Job Template is in `/tmp`. Since the Ansible Collection is downloaded into this directory before the Job Template is executed, you will not find temporary files of your Ansible Collection in `/var/lib/awx/projects/`.
+
+The format of the `requirements.yml` for Ansible Collections is very similar to the one for roles, however it is very important to store in the folder `collections`.
+
+Here is an example to set the `ansible.posix` Ansible Collection as a requirement:
+
+```yaml
+---
+collections:
+- ansible.posix
+```
+
+## Step 2 - Create Job Template
+
+When using Ansible Collections in your Playbook, there are no additional options to set in your Red Hat Ansible Tower Job Template. You specify the repository in which your Playbook is stored, inventory, credentials and other parameters, and execute it by clicking on the **Launch** button.
+
+# Troubleshooting
+
+Since Red Hat Ansible Tower does only check for updates in the the repository in which you stored your Playbook, it might not do a refresh if there was a change in the Ansible Collection used by your Playbook. This happens particularly if you also combine Roles and Collections.
+
+In this case you should check the option **Delete on Update** which will delete the entire local directory during a refresh.
+
+If there is a problem while parsing your `requirements.yml` it worth testing it with the `ansible-galaxy` command. As a reminder, Red Hat Ansible Tower basically also just runs the command for you with the appropriate parameters, so testing this works manually makes a lot of sense.
+
+```bash
+ansible-galaxy collections install -r collections/requirements.yml -f
+```
+
+> **NOTE**: The `-f` switch will forces a fresh installation of the specified Ansible Collections, otherwise `ansible-galaxy` will only install it, if it wasn't already installed. You can also use the `--force-with-deps` switch to make sure Ansible Collections which have dependencies to others are refreshed as well.
+
+----
+**Navigation**
+<br>
+[Previous Exercise](../3-collections-from-roles/) - [Next Exercise](../5-use-automation-hub)
+
+[Click here to return to the Ansible for Red Hat Enterprise Linux Workshop](../README.md)

exercises/ansible_collections/4-collections-from-tower/README.md

@@ -0,0 +1,95 @@
+# Exercise 5 - How to use Red Hat Automation Hub?
+
+## Table of Contents
+
+- [Objective](#objective)
+- [Red Hat Automation Hub](#red-hat-automation-hub)
+    - [Certified Content](#certified-content)
+    - [Supported Automation](#supported-automation)
+- [Ansible Galaxy](#ansible-galaxy)
+- [How to use Automation Hub](#how-to-use-automation-hub)
+    - [Accessing collections](#accessing-collections)
+       - [Creating a token](#creating-a-token)
+       - [Using authentication token](#using-authentication-token)
+       - [Using Collections](#using-collections)
+    - [Authenticate Tower to Automation Hub](#authenticate-tower-to-automation-hub)
+- [Takeaways](#takeaways)
+
+# Objective
+
+In this lab you will learn the value proposition of Red Hat Automation Hub and how to use the provided content.
+
+# Red Hat Automation Hub
+
+It is a service that is provided as part of the Red Hat SaaS Offering. It consists of the location where to discover and download only supported and certified Ansible Content Collections by Red Hat and its Partners. These content collections contain ways to consume automation, how-to-guides to implement them in your infrastructure. The support for Automation Hub is included with Red Hat Automation Platform subscription.
+
+> **NOTE**: Red Hat Automation Hub resides on [https://cloud.redhat.com/ansible/automation-hub](https://cloud.redhat.com/ansible/automation-hub): requires Red Hat customer portal credentials and a valid Red Hat Automation Platform subscription.
+
+## Certified Content
+
+In the portal of Automation Hub, users have direct access to trusted content collections from Red Hat and Certified Partners. Certified collections are developed, tested, built, delivered, and supported by Red Hat and its Partners. To find more details about the scope of support, check the [Ansible Certified Content FAQ](https://access.redhat.com/articles/4916901),
+
+## Supported Automation
+
+Automation Hub is a one-stop-shop for Ansible content that is backed by support from Red Hat to deliver additional reassurance for customers. Additional supportability claims for these collections may be provided under the "Maintained and Supported By" one of Red Hat Partners.
+
+# Ansible Galaxy
+
+It is the location for wider Ansible community that initially started to provide pre-packaged units of work known as Ansible roles. Roles can be dropped into Ansible Playbooks and immediately put to work. in a recent version of Galaxy started to provide Ansible content collections as well.
+
+Ansible Galaxy resides on [https://galaxy.ansible.com/](https://galaxy.ansible.com/)
+
+# How to use Automation Hub
+
+## Accessing collections
+
+Ansible collections can be used and downloaded from multiple locations. They can either be downloaded using a requirement file, statically included in the git repository or eventually installed separately in the virtual environment.
+
+In the scope of this exercise, the focus is on how access content from Automation Hub. This requires an authentication token and authentication URL. To do, some configuration steps need to be done in Ansible Tower.
+
+## Authenticate Tower to Automation Hub
+
+### Creating a token
+
+Authenticating Ansible Tower requires a token. It can be achieved using the steps below:
+
+1. Navigate to [https://cloud.redhat.com/ansible/automation-hub/token/](https://cloud.redhat.com/ansible/automation-hub/token/)
+
+   ![Load token|845x550,20%](screenshots/create-token.png)
+
+1. Click **Load Token**.
+
+1. Click **copy icon** to copy the API token to the clipboard.
+
+   ![Copy token|845x550,20%](screenshots/copy-token.png)
+
+### Using authentication token
+
+1. As user admin, navigate to the *Settings l> Jobs*
+
+1. Set **PRIMARY GALAXY SERVER URL** to `https://cloud.redhat.com/api/automation-hub/`
+
+1. Set **PRIMARY GALAXY AUTHENTICATION** URL to `https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token`
+
+1. Set **PRIMARY GALAXY SERVER TOKEN** to <COPIED_TOKEN>
+
+> **TIP**: It is recommended using Red Hat Automation Hub as primary Galaxy Server URL to ensure using certified and supported content by Red Hat and its partners via Red Hat Ansible Automation subscription.
+
+  ![test image size](screenshots/token.png)
+
+### Using collections
+
+After authenticating Ansible Tower to access Automation Hub, using `collections/requirements.yml` file will automatically fetches the content collections from Automation Hub as first source.
+
+# Takeaways
+
+- The Red Hat Automation Hub provides certified collections that supported by Red Hat and its Partners. It's available via Red Hat Ansible Automation Platform.
+- Ansible Galaxy hosts upstream community content collections.
+- Red Hat Ansible Tower can be configured to authenticate to Red Hat Automation Hub in order to fetch certified and supported content collections that are utilized in a given project within tower.
+
+----
+**Navigation**
+<br>
+[Previous Exercise](../4-collections-from-tower/)
+
+[Click here to return to the Ansible for Red Hat Enterprise Linux Workshop](../README.md)

exercises/ansible_collections/5-use-automation-hub/README.md

@@ -0,0 +1 @@
+

exercises/ansible_collections/5-use-automation-hub/screenshots/README.md

@@ -0,0 +1,58 @@
+# Ansible Collections Workshop
+
+This workshop is a step by step series of exercises to demonstrate
+features and benefits of Ansible Collections, a unique distribution
+format of Ansible content that can be used to package and distribute
+playbooks, roles, modules, and plugins.
+
+## Time Planning
+
+The average duration of this workshop depends on the Ansible skills of
+practitioner. The average duration should be around 3 hours or less with
+advanced Ansible users.
+
+All exercises are self explanatory and guide the participants through the entire lab.
+Concepts are explained when they are introduced along with the practice exercise.
+
+## Prerequisites
+
+- Ansible v2.9
+
+- An OS of choice between RHEL/CentOS 8.x, CentOS Stream, Fedora 31+
+
+## Ansible Collections Exercises
+
+The workshop is structured in a set of progressive exercises, covering collections creation,
+usage from playbooks, roles and Tower and an introduction to Ansible Automation Hub.
+
+- [Exercise 1 - Create Collections](./1-create-collections)
+
+- [Exercise 2 - Collections from playbook](./2-collections-from-playbook)
+
+- [Exercise 3 - Collections from roles](./3-collections-from-roles)
+
+- [Exercise 4 - Collections from tower](./4-collections-from-tower)
+
+- [Exercise 5 - Use Automation Hub](./5-use-automation-hub)
+
+## Additional Information
+
+- [Ansible Docs: Using Collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html)
+
+- [Ansible Collections Overview](https://github.com/ansible-collections/overview)
+
+- [Ansible Docs: Developing Collections](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html)
+
+- [Blog Post: Introducing: The AWX and Ansible Tower Collections](https://www.ansible.com/blog/introducing-the-awx-collection)
+
+## Authors
+
+Ansible Automation Platform 1.1 Hackfest - Team 1
+
+- Christian Jung <cjung@redhat.com>
+
+- Gianni Salinetti <gsalinet@redhat.com>
+
+- David Sastre Medina <asastrem@redhat.com>
+
+- Ismail Dhaoui <idhaoui@redhat.com>