Ansible Modules Usage 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.

The Ansible Modules Usage Guide contains the following subsections:

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, you should make sure, 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 like for example:

ansible-doc theforeman.foreman.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 full 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 make sure, a specific processor architecture is registered with orcharhino we could call:

ansible --connection=local localhost -m theforeman.foreman.foreman_architecture \
  -a "server_url=https://localhost username=admin password=<...> name=ppc64 state=present"

And the result would tell us, whether anything was changed, and some information about the affected architecture:

localhost | CHANGED => {
    "changed": true,
    "entity": {
        "id": 3,
        "name": "ppc64",
        <...>
    }
}

Tasks

With Ansible, you usually want to perform a series of tasks in a non-interactive way. In that mindset, every call to a module is called a task, and a so called playbook consists, in it’s easiest form of a list of tasks that are meant to be performed on a set of hosts. Those playbooks are written in a 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 afterwards a file repository in that product:

---
- hosts: localhost
  tasks:
    - name: Create Product
      theforeman.foreman.katello_product:
        server_url: "https://your-orcharhino"
        username: admin
        password: "{{ vaulted_password }}"
        organization: Corp und co. ltd
        name: My crazy Project
        state: present

    - name: Create Repository
      theforeman.foreman.katello_repository:
        server_url: "https://your-orcharhino"
        username: admin
        password: "{{ vaulted_password }}"
        organization: Corp und co. ltd
        name: My crazy Project files
        product: My crazy Project
        content_type: file
        url: http://labs.corp.tld/products/crazy
        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