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. For additional examples, see Example playbooks based on modules from Foreman Ansible Collection.

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

3. Example playbooks based on modules from Foreman Ansible Collection

All playbooks based on modules from Foreman Ansible Collection must include parameters detailing how to connect to the Foreman API. The following examples use Ansible vault and module defaults group to provide these parameters, and they authenticate using a username and password. For more information, see Creating a playbook with modules from Foreman Ansible Collection.

Additional resources

Use the ansible-doc --list theforeman.foreman command to display the Foreman Ansible modules installed on your system.
See Ansible Galaxy for a complete list of Foreman Ansible modules and other related information.

3.1. Playbook example: Enable repositories and create a content view

This example playbook uses the following modules:

theforeman.foreman.repository_set
theforeman.foreman.content_view

The playbook ensures repositories are enabled and a content view that contains these repositories exists.

Before you run this playbook, ensure that you have uploaded a manifest and can access the Red Hat CDN.

- name: Ensure RHEL 9 repositories are enabled and a content view exists
  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 RHEL 9 BaseOS repositories are enabled
      theforeman.foreman.repository_set:
        name: "Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs)"
        organization: "Default Organization"
        product: "Red Hat Enterprise Linux for x86_64"
        repositories:
        - releasever: "9"
        state: enabled
    - name: Ensure RHEL 9 AppStream repositories are enabled
      theforeman.foreman.repository_set:
        name: "Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs)"
        organization: "Default Organization"
        product: "Red Hat Enterprise Linux for x86_64"
        repositories:
        - releasever: "9"
        state: enabled
    - name: Ensure a content view for RHEL 9 repositories exists
      theforeman.foreman.content_view:
        name: "RHEL 9 content view"
        organization: "Default Organization"
        repositories:
          - name: "Red Hat Enterprise Linux 9 for x86_64 - BaseOS RPMs 9"
            product: "Red Hat Enterprise Linux for x86_64"
          - name: "Red Hat Enterprise Linux 9 for x86_64 - AppStream RPMs 9"
            product: "Red Hat Enterprise Linux for x86_64"

For more information, see the Ansible module documentation with the following commands:

ansible-doc theforeman.foreman.repository_sync
ansible-doc theforeman.foreman.content_view

3.2. Playbook example: Synchronize repositories and publish a content view

This example playbook uses the following modules:

theforeman.foreman.repository_sync
theforeman.foreman.content_view_version

The playbook synchronizes repositories and publishes the content view that includes them.

Before you run this playbook, ensure that you have enabled the required repositories and created a content view. For an example playbook that ensures this, see Playbook example: Enable repositories and create a content view.

- name: Ensure RHEL 9 repositories are synced and content view is published
  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: Sync RHEL repositories
      theforeman.foreman.repository_sync:
        product: "Red Hat Enterprise Linux for x86_64"
        organization: "Default Organization"
    - name: Publish RHEL 9 content view
      theforeman.foreman.content_view_version:
        content_view: "RHEL 9 content view"
        organization: "Default Organization"

For more information, see the Ansible module documentation with the following commands:

ansible-doc theforeman.foreman.repository_sync
ansible-doc theforeman.foreman.content_view_version