Using Foreman Ansible Modules

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.

Installing Foreman Ansible Modules on orcharhino Server

You can install the collection of Foreman modules from the orcharhino repositories with the following command:

$ dnf 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.

Using the Latest Foreman Ansible Modules on Your Local Machine

ATIX provides the Ansible collection of Foreman modules supported for usage with orcharhino. However, if you require the latest Foreman Ansible modules, you can use the community-provided version from Ansible Galaxy.

Using FAM from Ansible Galaxy is not supported by ATIX.

Usage

You can obtain the full documentation for each individual module with the ansible-doc command as follows:

$ ansible-doc theforeman.foreman.architecture

Using 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, for example 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 on the About page. Alternatively, query the installed packages on your orcharhino Server:

    $ dnf info ansible-collection-theforeman-foreman