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
  1. 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.

  2. 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.

    1. 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:
    2. 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:
    3. In the tasks: section, define the tasks that you want your playbook to perform.

  3. 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.

  4. 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