Using the Foreman Ansible Collection

1. Introduction to Foreman Ansible Collection

Foreman Ansible Collection provides a set of Ansible modules for managing Foreman. Using the modules, you can automate many aspects of Foreman management.

1.1. Installing the Foreman Ansible modules

Modules from the Foreman Ansible Collection are provided by the ansible-collection-theforeman-foreman package. Before you can use the modules, you must install the package on the system where you run your playbooks.

Note	You can execute your playbooks on any system that can reach the Foreman API. This can also be your Foreman server itself.

Procedure

Install the ansible-collection-theforeman-foreman package:
```
# dnf install ansible-collection-theforeman-foreman
```

Verification

Display the list of Ansible modules that are now available on your system:
```
# ansible-doc --list theforeman.foreman
```

Next steps

You can now use the installed Ansible modules to execute playbooks.

1.2. Getting help with Foreman Ansible Collection

Note	To view the built-in documentation, Foreman Ansible Collection must be installed on your system. For more information, see Installing the Foreman Ansible modules.

You can view the full built-in documentation for available modules with the following command:

# ansible-doc --list theforeman.foreman

You can view the built-in documentation for a particular module with the following command:

# ansible-doc theforeman.foreman.Module_Name

For example:

# ansible-doc theforeman.foreman.location

2. Creating a playbook with modules from Foreman Ansible Collection

Ansible modules from the Foreman Ansible Collection must be able to communicate with the Foreman API over HTTPS. In your playbooks, include parameters specifying how to authenticate to enable the connection to API.

Important

Do not store sensitive credentials, such as username and password, directly in your playbooks or environment variables. The following examples use Ansible vault to manage sensitive data.

Prerequisites

A user account in Foreman exists with permissions to perform the action defined in your playbook.
You have access to one of the following types of authentication credentials for that user:
- Username and password
- Username and Personal Access Token
- Kerberos ticket, if your Foreman server is configured to use FreeIPA as an external authentication source
A system that you will execute your playbook against. The following examples use localhost.

This system must be able to reach the Foreman API. You can choose from these options:
- A system that can reach the Foreman API directly. You can use your Foreman server, your Smart Proxy servers, or any other system in your environment.
- A system without a direct connection to the Foreman API that uses an HTTP proxy to connect to Foreman.

Procedure

Store your sensitive variables in an encrypted file:
1. Create an Ansible vault. For example, to create a vault named My_Vault.yml:
  $ ansible-vault create My_Vault.yml
2. After the ansible-vault create command opens an editor, provide the required parameters in the key: value format.
  
  If you want to authenticate with Foreman username and password:
  My_Username: My_Admin_User_Account My_Password: My_Admin_Password My_Server_URL: https://foreman.example.com
  If you want to authenticate with Foreman username and Personal Access Token (PAT):
  My_Username: My_Admin_User_Account My_Password: My_PAT My_Server_URL: https://foreman.example.com
  If you want to authenticate with a Kerberos ticket:
  My_Server_URL: https://foreman.example.com
3. If you use an HTTP proxy to reach the Foreman API, store it in the vault too:
  My_HTTP_Proxy: "http://proxy.example.com:8080"
4. Save your changes and close the editor. Ansible encrypts the data in the vault.

Create a playbook file that references the vault file:

Note

The following YAML snippets include the module_defaults keyword to pass vault variables as parameters to all modules from the theforeman.foreman.foreman group that are used in the playbook. Module defaults groups simplify parameter management by enabling you to define common parameters to groups of modules rather than having to pass the parameters to each module individually.

Provide details on how to authenticate to the Foreman API.

If you are authenticating with Foreman username and password or PAT, map the username, password, and server_url parameters to the contents of My_Vault.yml:

- name: My Playbook
  hosts: localhost
  vars_files:
    - My_Vault.yml
  module_defaults:
    group/theforeman.foreman.foreman:
      username: "{{ My_Username }}"
      password: "{{ My_Password }}"
      server_url: "{{ My_Server_URL }}"
  tasks:

If you are authenticating with a Kerberos ticket, map the server_url parameter to the contents of My_Vault.yml and add use_gssapi: true to enable Kerberos authentication:

- name: My Playbook
  hosts: localhost
  vars_files:
    - My_Vault.yml
  module_defaults:
    group/theforeman.foreman.foreman:
      server_url: "{{ My_Server_URL }}"
      use_gssapi: true
  tasks:

If you need to use an HTTP proxy to reach the Foreman API, set the https_proxy environment variable:

- name: My Playbook
  hosts: localhost
  vars_files:
    - My_Vault.yml
  environment:
    https_proxy: "{{ My_HTTP_Proxy }}"
  module_defaults:
    group/theforeman.foreman.foreman:
      username: "{{ My_Username }}"
      password: "{{ My_Password }}"
      server_url: "{{ My_Server_URL }}"
  tasks:

In the tasks: section, define the tasks that you want your playbook to perform.

Validate the playbook syntax:
```
$ ansible-playbook --syntax-check --ask-vault-pass My_Playbook.yml
```
Note that this command only validates the syntax. It does not protect against a valid but incorrect configuration.

Run the playbook:

$ ansible-playbook --ask-vault-pass My_Playbook.yml

Example 1. Example Ansible playbook: Ensure that domain new.example.com exists in Foreman

The theforeman.foreman.domain module can create, update, and delete domains. This example playbook uses theforeman.foreman.domain to ensure that a domain named new.example.com exists and is managed by Foreman.

- name: Domain management
  hosts: localhost
  vars_files:
    - My_Vault.yml
  module_defaults:
    group/theforeman.foreman.foreman:
      username: "{{ My_Username }}"
      password: "{{ My_Password }}"
      server_url: "{{ My_Server_URL }}"
  tasks:
    - name: Ensure domain new.example.com exists
      theforeman.foreman.domain:
        name: new.example.com

The settings specified in the example playbook include the following:

vars_files: The name of the vault file that stores the variables My_Username, My_Password, and My_Server_URL.
module_defaults: The module defaults group that maps the variables from the vault file to the username, password, and server_url module parameters.
name: The name of the domain that you want to ensure exists in Foreman.

For more information, see the Ansible module documentation with ansible-doc theforeman.foreman.domain.

Additional resources

For information about using Ansible vault, see Protecting sensitive data with Ansible vault in Ansible Community Documentation.
For information about using module defaults, see Module defaults in Ansible Community Documentation.

Pre-release version Report issue