Ansible modules for interacting with the Foreman API and various plugin APIs such as Katello.
A list of all modules and their documentation can be found at theforeman.org/plugins/foreman-ansible-modules.
Modules should support any currently stable Foreman release and the matching set of plugins. Some modules have additional features/arguments that are only applied when the corresponding plugin is installed.
We actively test the modules against the latest stable Foreman release and the matching set of plugins.
The supported Ansible versions are aligned with currently maintained Ansible versions that support Collections (2.9+). You can find the list of maintained Ansible versions here.
Ansible only supports Python 2.7 and 3.5 (and higher). These are also the only Python versions we develop and test the modules against.
-
Some modules, e.g.
repository_syncandcontent_view_version, trigger long running tasks on the server side. It might be beneficial to your playbook to wait for their completion in an asynchronous manner. As Ansible has facilities to do so, the modules will wait unconditionally. See the Ansible documentation for putting tasks in the background. Please make sure to set a high enoughasyncvalue, as otherwise Ansible might abort the execution of the module while there is still a task running on the server, making status reporting fail. -
According to Ansible documentation, using loop over Ansible resources can leak sensitive data. This applies to all modules, but especially those which require more secrets than the API credentials (
auth_source_ldap,compute_resource,host,hostgroup,http_proxy,image,repository,scc_account,user). You can prevent this by usingno_log: trueon the task.eg:
- name: Create compute resources theforeman.foreman.compute_resource: server_url: https://foreman.example.com username: admin password: changeme validate_certs: true name: "{{ item.name }}" organizations: "{{ item.organizations | default(omit) }}" locations: "{{ item.locations | default(omit) }}" description: "{{ item.description | default(omit) }}" provider: "{{ item.provider }}" provider_params: "{{ item.provider_params | default(omit) }}" state: "{{ item.state | default('present') }}" loop: "{{ compute_resources }}" no_log: true
-
Modules require write access to
~/.cache(or wherever$XDG_CACHE_HOMEpoints at). Otherwise the API documentation cannot be downloaded and you get errors like[Errno 13] Permission denied: '/home/runner/.cache/apypie. If on your system~/.cacheis not writeable, please set the$XDG_CACHE_HOMEenvironment variable to a directory Ansible can write to.
There are currently two ways to use the modules in your setup: install directly from Ansible Galaxy or via packages.
You can install the collection from Ansible Galaxy by running ansible-galaxy collection install theforeman.foreman.
After the installation, the modules are available as theforeman.foreman.<module_name>. Please see the Using Ansible collections documentation for further details.
The collection is also available as ansible-collection-theforeman-foreman from the plugins repository on yum.theforeman.org for Enterprise Linux systems and from the plugins repository on deb.theforeman.org for Debian and Ubuntu systems.
After installing the package, you can use the modules in the same way as when they are installed directly from Ansible Galaxy.
For development or testing purposes, you can install the collection from source git repository. For production usage, see the instructions above on installing the latest stable release.
With Ansible >= 2.10, you can install from a Github repository (such as this one or your fork):
$ ansible-galaxy collection install git+https://github.com/theforeman/foreman-ansible-modules.gitIf you have configured GitHub to use SSH instead of HTTPS, you can do:
$ ansible-galaxy collection install [email protected]/theforeman/foreman-ansible-modules.gitYou can also specify a branch to use such as devel (below) or a feature branch that you are working with:
$ ansible-galaxy collection install git+https://github.com/theforeman/foreman-ansible-modules.git,develTo install from a requirements.yml file (useful when installing multiple collections) add a snippet to your requirements.yml like
---
collections:
- name: https://github.com/theforeman/foreman-ansible-modules.git
type: git
version: develAnd install all specified requirements with ansible-galaxy install -r requirements.yml
For all currently supported versions of Ansible (i.e. Ansible >= 2.9, and particularly Ansible < 2.10 where the above approach is not yet supported), you can build the collection locally:
$ make distAnd install it with:
$ ansible-galaxy collection install ./theforeman-foreman-*.tar.gzThese dependencies are required for the Ansible controller, not the Foreman server.
PyYAMLrequestsipaddressfor thesubnetmodule on Python 2.7rpmfor the RPM support in thecontent_uploadmoduledebianfor the DEB support in thecontent_uploadmodule
Roles using the Foreman Ansible Modules to configure Foreman and its plugins.
For individual role documentation, check the README defined at roles/rolename/README.md.
foreman_server_url: URL of the Foreman server. If the variable is not specified, the value of environment variableFOREMAN_SERVER_URLwill be used instead.foreman_username: Username accessing the Foreman server. If the variable is not specified, the value of environment variableFOREMAN_USERNAMEwill be used instead.foreman_password: Password of the user accessing the Foreman server. If the variable is not specified, the value of environment variableFOREMAN_PASSWORDwill be used instead.foreman_validate_certs: Whether or not to verify the TLS certificates of the Foreman server. If the variable is not specified, the value of environment variableFOREMAN_VALIDATE_CERTSwill be used instead.foreman_organization: Organization where configuration will be applied.