Foreman Ansible Modules Guide

The foreman-ansible-modules are a collection of modules for Ansible that can communicate with the API of orcharhino. This can help to automate certain workflows around the provisioning and the content infrastructure.

ATIX offers Ansible trainings for beginners and advanced users on how to use Ansible as a configuration management tool. This helps you manage your infrastructure more efficiently using Ansible roles. It communicates how to create, use, and maintain Ansible roles, inventories, and playbooks based on best practices. Refer to the Ansible trainings website for more information or contact us.

This guide uses orcharhino specific terminology. If you are new to orcharhino or unsure about certain terms, have a look at our glossary.

Installation

The collection of foreman modules can be installed from the orcharhino repositories with the following command:

# yum install ansible-collection-theforeman-foreman

They will appear in the collection namespace theforeman.foreman. You can use the modules from the same machine, your orcharhino is installed, or on a different one. In all cases, ensure you have ansible in version at least 2.9 and python2-apypie installed. For some modules you might also need the python packages python-debian, rpm, or ipaddress.

Usage

Full documentation for each individual module can be obtained with the ansible-doc command as follows:

# ansible-doc theforeman.foreman.architecture

Therefore this documentation describes some general ways to use those modules.

Ansible Ad-Hoc Commands

With Ansible, you can invoke individual modules with so called ad-hoc commands. It is recommended to run those modules on the local machine. The module name (after the -m parameter) must be specified with the fully qualified name. Module parameter must be specified after -a. All modules require the parameters server_url, which is the address of your orcharhino (or localhost if executed on that machine), username, the user with which you want to perform actions and password, the password or an API token for that user. Further parameters describe the entity you want to manipulate, or whether it should exist or not.

For example, if we wanted to ensure a specific processor architecture is registered with orcharhino, we could call:

# ansible --connection=local \
    localhost \
    -m theforeman.foreman.architecture \
    -a "server_url=https://orcharhino.example.com username=admin password=password name=ppc64 state=present"

The result would tell us whether anything was changed and additional information about the affected architecture:

localhost | CHANGED => {
    "changed": true,
    "entity": {
        "architectures": [
            {
                "created_at": "2021-06-01 09:00:00 UTC",
                "id": 42,
                "images": [],
                "name": "ppc64",
                "operatingsystems": [],
                "updated_at": "2021-06-01 09:00:00 UTC"
            }
        ]
    }
}

Tasks

Using Ansible, you can perform a series of tasks in a non-interactive way. Every call to a module is called a task and a so called playbook consists of a list of tasks that are performed on a set of hosts. Ansible playbooks are written in YAML format. In the following example, we assume that a valid API token for the user admin is available to Ansible in the vaulted_password variable. With that, we first create a product and then a file repository in that product:

---
- hosts: localhost
  tasks:
    - name: Create Product
      theforeman.foreman.katello_product:
        server_url: "https://orcharhino.example.com"
        username: admin
        password: "{{ vaulted_password }}"
        organization: Example
        name: My Project
        state: present

    - name: Create Repository
      theforeman.foreman.katello_repository:
        server_url: "https://orcharhino.example.com"
        username: admin
        password: "{{ vaulted_password }}"
        organization: Example
        name: My Project Files
        product: My Project
        content_type: file
        url: https://example.com/files/my_product
        state: present
...

Note how we access a possibly remote orcharhino while still running the modules locally.

This playbook, assuming it is saved as play.yaml, can be executed via:

# ansible-playbook -i localhost, play.yaml

Other Resources

The official Foreman Ansible Modules documentation is a good starting point. It contains a list of available Ansible modules, e.g. architecture to manage architectures or user to manage users on your orcharhino.

You can check what version of the Foreman Ansible Modules is available on your orcharhino by running yum info ansible-collection-theforeman-foreman or by checking the about page.