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. |
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 with the ansible-doc
command as follows:
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 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 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"
The result would tell us whether anything was changed and additional 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://orcharhino.example.com"
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://orcharhino.example.com"
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
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 oruser
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.