1. Configuration management with Ansible in Foreman

By using Ansible as a configuration management tool in Foreman, you can define the desired state of your hosts and maintain it over time. Foreman combines Ansible features with recurring job runs and centralized orchestration, which helps you manage host configurations consistently.

1.1. High-level steps for configuration management with Ansible

You use Ansible roles to define the desired state of the hosts registered to Foreman. Running the roles enforces the configuration.

Configuration management with Ansible involves the following high-level steps:

  1. Import Ansible roles into Foreman.

  2. Assign specific roles to a host or host group.

  3. Optional: Override Ansible variables per host or host group in Foreman.

  4. Run the roles on the host or host group.

As a result, your hosts maintain a consistent configuration over time. The Ansible roles become a part of their definition.

Note

Running an Ansible role on a host triggers a remote execution job in the background but the use case is different. The typical use case for a remote execution job is to run an ad-hoc task or orchestration. The typical use case for configuration management by using Ansible and Ansible roles is long-term state management.
Additional resources

1.2. Ansible versions supported for integration with Foreman

Supported Ansible versions follow the Ansible versions provided by the base operating system of Foreman server or any Smart Proxies for remote execution.

Foreman uses Ansible as provided by the base operating system of Foreman server or any Smart Proxies for remote execution. Therefore, the supported version of Ansible depends on your base operating system configuration.

2. Enabling the Ansible plugin

Before you can use Ansible for configuration management in Foreman, enable Ansible integration in Foreman and on all Smart Proxy servers that you want to use to run Ansible roles on hosts.

Procedure

  1. Enable the Ansible plugin on your Foreman server:

    # foreman-installer \
--enable-foreman-plugin-ansible \
--enable-foreman-proxy-plugin-ansible

  2. On all Smart Proxy servers that you want to use to run Ansible roles on hosts, enable the Ansible plugin:

    # foreman-installer --enable-foreman-proxy-plugin-ansible

3. Configuring Ansible definitions to apply to hosts

Configure and organize Ansible definitions in Foreman to control which configurations are available for your hosts. Keeping definitions organized helps you apply consistent changes across your hosts.

3.1. Importing Ansible roles and variables

You can import Ansible roles and variables from the Ansible paths on Foreman server or Smart Proxy servers that have Ansible enabled.

Procedure

  1. Place the roles and variables in the appropriate Ansible paths on all Smart Proxies from where you want to use the roles. For more information, see Ansible role and collection paths in Foreman.

    If you want to use custom or third party Ansible roles, ensure to configure an external version control system to synchronize roles between Foreman server and Smart Proxy servers.

  2. In the Foreman web UI, navigate to Configure > Ansible > Roles.

  3. Click Import to select the Smart Proxy from which you want to import.

  4. Select the roles that you want to import.

  5. Click Submit.

Additional resources

3.2. Overriding Ansible variables in Foreman

You can use Foreman to override Ansible variables for roles imported into Foreman. This helps you customize the behavior of imported roles to fit your specific needs.

Note

If you use an Ansible role to run a task as a user that is not the Effective User, there is a strict order of precedence for overriding Ansible variables. To ensure the variable that you override follows the correct order of precedence, see Variable precedence: Where should I put a variable?.
Prerequisites

  • Ansible variables are available in Foreman. For more information, see Importing Ansible roles and variables

  • To use overridden Ansible variables, your user account has a role that allows viewing the attributes that are matched against hosts.

Procedure

  1. In the Foreman web UI, navigate to Configure > Ansible > Variables.

  2. Select the Ansible variable that you want to override and manage with Foreman.

  3. In the Default Behavior area, select the Override checkbox.

  4. In the Parameter Type field, select the value type for validation such as string or boolean. The types array and hash have further options for handling upon a variable match. For more information, see the Prioritize Attribute Order area below.

  5. In the Default Value field, enter the default value that you want to use if there is no match for the variable.

  6. Optional: If you do not want to display the value of the variable as plain text in the Foreman web UI, select the Hidden Value checkbox to display the content of the variable as asterisks. This is useful for sensitive values such as passwords or secret tokens.

  7. Optional: Expand the Optional Input Validator area and specify conditions that will be used to validate concrete values of the variable:

    • Select Required if you want to enforce users to fill in this variable.

    • In the Validator Type field, select how the value will be validated:

      • list – The value will be validated against an enumeration of allowed values.

      • regex – The value will be validated against a regular expression pattern.

  8. Optional: In the Prioritize Attribute Order area, specify the order of priority to match an override with a host by host attributes. Order at the top takes higher precedence. The first match wins.

    You can combine multiple attributes into a single matcher key using a comma as the AND operation. For example, the matcher key of hostgroup, environment would expect matchers such as hostgroup = "web servers" AND environment = production.

    If you use the parameter type array or hash, you can further set:

    • Merge Overrides – Merges members of the arrays/hashes instead of replacing the whole array or hash. If the hashes contain the same key, the value is overwritten by the value of the host.

    • Merge Default – Adds the default value to the array or hash.

    • Avoid Duplicates – Ensures that the values in the array or hash are unique.

  9. Optional: Expand the Specify Matchers area and specify criteria for selecting hosts on which the variable overrides.

  10. To save the override settings, click Submit.

  11. To use the Ansible variable, add the variable as a parameter to your host or host group, or add the variable as a global parameter:

    1. To add the variable to a host:

      1. In the Foreman web UI, navigate to Hosts > All Hosts and select the host that you want to use.

      2. Click the Ansible tab, and in the Variables area, click the pencil icon to edit the value of the variable.

      3. Click the tick icon to accept the value of the changed variable or the cross icon to cancel the change.

    2. To add the variable to a host group:

      1. In the Foreman web UI, navigate to Configure > Host Groups, and select the host group that you want to use.

      2. Click the Parameters tab, and in the Host Group Parameters area, click Add Parameter.

      3. In the Name field, add the Ansible variable name.

      4. From the Type list, select the type of the variable for validation.

      5. In the Value field, enter the value for the variable.

    3. To add the variable as a global parameter:

      1. In the Foreman web UI, navigate to Configure > Global Parameters, and click Create Parameter.

      2. In the Name field, add the Ansible variable name.

      3. From the Type list, select the type of the variable for validation.

      4. In the Value field, enter the value for the variable.

      5. Optional: If you do not want to display the Ansible variable in plain text, select the Hidden Values checkbox to display the content of the variable as asterisks in the Foreman web UI.

3.3. Assigning Ansible roles to a host group

You can assign a previously imported Ansible role to a host group. This enables Foreman to apply the configuration defined by the role when you provision a new host by using the host group.

Procedure

  1. In the Foreman web UI, navigate to Configure > Host Groups.

  2. Click the host group name to which you want to assign an Ansible role.

  3. On the Ansible Roles tab, select the role that you want to add from the Available Ansible Roles list.

  4. Click the + icon to add the role to the host group. You can add more than one role.

  5. Click Submit.

3.4. Assigning Ansible roles to an existing host

You can assign a previously imported Ansible role to an existing host. This enables Foreman to apply the configuration defined by the role when you run the Ansible roles on the host.

Procedure

  1. In the Foreman web UI, navigate to Hosts > All Hosts.

  2. Select the host and click Edit.

  3. On the Ansible Roles tab, select the role that you want to add from the Available Ansible Roles list.

  4. Click the + icon to add the role to the host. You can add more than one role.

  5. Click Submit.

  6. Optional: On the Parameters tab, click Add Parameter to add any parameter variables that you want to pass to job templates at run time. This includes all Ansible Playbook parameters and host parameters that you want to associate with the host. To use a parameter variable with an Ansible job template, you must add a Host Parameter.

3.5. Changing the order of Ansible roles

Change the order of Ansible roles on a host to control how role tasks are applied. This helps prevent dependency and precedence issues during configuration runs.

Procedure

  1. In the Foreman web UI, navigate to Hosts > All Hosts.

  2. Select a host.

  3. Select the Ansible Roles tab.

  4. In the Assigned Ansible Roles area, you can change the order of the roles by dragging and dropping the roles into the preferred position.

  5. Click Submit to save the order of the Ansible roles.

3.6. Removing Ansible roles from a host

Remove Ansible roles from a host to stop applying configurations to the host.

Procedure

  1. In the Foreman web UI, navigate to Hosts > All Hosts.

  2. Select the host and click Edit.

  3. Select the Ansible Roles tab.

  4. In the Assigned Ansible Roles area, click the - icon to remove the role from the host. Repeat to remove more roles.

  5. Click Submit.

4. Applying Ansible definitions to hosts

When a host has one or more Ansible roles assigned to it, Foreman can run the roles on the host to apply and enforce the configuration state that the roles define.

4.1. Running Ansible roles on a host

Run Ansible roles on a host through the Foreman web UI to apply the assigned configuration immediately. This helps you verify and enforce the intended state of the host.

Prerequisites
Procedure

  1. In the Foreman web UI, navigate to Hosts > All Hosts.

  2. Select the host on which you want to run the assigned Ansible roles.

  3. From the Schedule a job menu, select Run Ansible roles.

Verification

  • You can view the status of your Ansible job by navigating to Monitor > Jobs.

4.2. Running Ansible roles on a host group

When a host group has one or more Ansible roles assigned to it, Foreman can run the roles on all hosts in the host group at once to apply and enforce the configuration state that the roles define.

Prerequisites
Procedure

  1. In the Foreman web UI, navigate to Configure > Host Groups.

  2. From the list in the Actions column for the host group, select Run all Ansible roles.

  3. You can view the status of your Ansible job on the Run Ansible roles page. Click Rerun to rerun a job.

4.3. Configuring a host to run Ansible roles in check mode

Run Ansible roles in check mode through the Foreman web UI to preview changes before applying them. This helps you reduce risk when validating role behavior on a host.

Procedure

  1. In the Foreman web UI, navigate to Hosts > All Hosts.

  2. Click Edit for the host you want to enable check mode for.

  3. In the Parameters tab, ensure that the host has a parameter named ansible_roles_check_mode with type boolean set to true.

  4. Click Submit.

5. Using Ansible Vault with Foreman

You can encrypt sensitive Ansible data files using the Ansible Vault tool and configure Ansible to access the encrypted files using a password stored in a file.

Procedure

  1. If you customized /etc/ansible/ansible.cfg, copy your configuration from /etc/ansible/ansible.cfg to /usr/share/foreman-proxy/.ansible.cfg.

  2. Encrypt the sensitive file using the ansible-vault command:

    # ansible-vault encrypt /etc/ansible/roles/Role_Name/vars/main.yml

    Note that ansible-vault changes the file permissions to 600.

  3. Change the group and permissions of the encrypted file to ensure that the foreman-proxy user can read it:

    # chgrp foreman-proxy /etc/ansible/roles/Role_Name/vars/main.yml
# chmod 0640 /etc/ansible/roles/Role_Name/vars/main.yml

  4. Create the /usr/share/foreman-proxy/.ansible_vault_password file and enter the Vault password into it.

  5. Change the user and permissions of the .ansible_vault_password file to ensure that only the foreman-proxy user can read it:

    # chown foreman-proxy:foreman-proxy /usr/share/foreman-proxy/.ansible_vault_password
# chmod 0400 /usr/share/foreman-proxy/.ansible_vault_password

  6. Add the path of the Vault password file to the [defaults] section in /usr/share/foreman-proxy/.ansible.cfg:

    [defaults]
vault_password_file = /usr/share/foreman-proxy/.ansible_vault_password

    The path to the Vault password file must be absolute.

6. Integrating Foreman and AWX

You can integrate Foreman and AWX to use Foreman server as a dynamic inventory source for AWX. When provisioning new hosts from Foreman server, you can use the provisioning callback function to trigger playbook runs from AWX.

6.1. Adding Foreman server to AWX as a dynamic inventory item

To add Foreman server to AWX as a dynamic inventory item, you must create a credential for a Foreman server user on AWX, add an AWX user to the credential, and then configure an inventory source.

Prerequisites

  • If your Foreman deployment is large, for example, managing tens of thousands of hosts, using a non-admin user can negatively impact performance because of time penalties that accrue during authorization checks. For large deployments, consider using an admin user.

  • For non-admin users, the Ansible Tower Inventory Reader role is assigned to your Foreman server user. For more information about managing users, roles, and permission filters, see Creating and managing roles in Administering Foreman.

  • Your Foreman server and AWX are hosted on the same network or subnet.

Procedure

  1. In the AWX web UI, create a credential for your Foreman. For more information about creating credentials, see Add a New Credential and Red Hat Satellite 6 credentials in AWX community documentation. Note that this part of the AWX documentation also applies to Foreman.

    Table 1. Foreman credentials
    Credential Type: Foreman

    Foreman URL:

    https://foreman.example.com

    Username:

    The username of the Foreman user with the integration role.

    Password:

    The password of the Foreman user.

  2. Add an AWX user to the new credential. For more information about adding a user to a credential, see Getting Started with Credentials in AWX community documentation.

  3. Add a new inventory. For more information, see Add a new inventory in AWX community documentation.

    In the new inventory, add Foreman server as the inventory source, specifying the following inventory source options.

    Table 2. Inventory source options
    Source Foreman

    Credential

    The credential you create for Foreman server.

    Overwrite

    Select

    Overwrite Variables

    Select

    Update on Launch

    Select

    Cache Timeout

    90

  4. Ensure that you synchronize the source that you add.

6.2. Configuring provisioning callback for a host

When you create hosts in Foreman, you can use AWX to run playbooks to configure your newly created hosts. This is called provisioning callback in AWX.

The provisioning callback function triggers a playbook run from AWX as part of the provisioning process. The playbook configures the host after the provisioning process.

In Foreman server, the Kickstart Default and Kickstart Default Finish templates include three snippets:

  1. ansible_provisioning_callback

  2. ansible_tower_callback_script

  3. ansible_tower_callback_service

You can add parameters to hosts or host groups to provide the credentials that these snippets can use to run Ansible Playbooks on your newly created hosts.

Prerequisites
Procedure

  1. In the AWX web UI, complete the following tasks:

    1. Create a machine credential for your new host. Ensure that you enter the same password in the credential that you plan to assign to the host that you create in Foreman. For more information, see Credentials in AWX community documentation.

    2. Create a project. For more information, see Projects in AWX community documentation.

    3. Add a job template to your project. In your job template, you must enable provisioning callbacks, generate the host configuration key, and note the template_ID of your job template. For more information, see Job Templates in AWX community documentation.

  2. In the Foreman web UI, navigate to Configure > Host Group.

  3. Create a host group or edit an existing host group.

  4. In the Host Group window, click the Parameters tab.

  5. Click Add Parameter.

  6. Enter the following information for each new parameter:

    Table 3. Host parameters
    Name Value Description

    ansible_tower_provisioning

    true

    Enables Provisioning Callback.

    ansible_tower_api_url

    https://awx.example.com/api/controller/v2

    Defines the URL of your AWX, including the required API path. For older versions of AWX, use /api/v2 instead of /api/controller/v2. If unsure, check the API endpoints of your instance to verify the correct path.

    ansible_job_template_id

    template_ID

    The ID of your provisioning template that you can find in the URL of the template: /templates/job_template/5.

    ansible_host_config_key

    config_KEY

    The host configuration key that your job template generates in AWX.

  7. Click Submit.

  8. Create a host using the host group.

  9. On your new host, start the ansible-callback service:

    # systemctl start ansible-callback

  10. On your new host, check the the status of the ansible-callback service:

    # systemctl status ansible-callback

    Provisioning callback is configured correctly if the command returns the following output:

    foreman.example.com systemd[1]: Started Provisioning callback to AWX...
    Note

    For manual provisioning callback, you can use the provisioning callback URL and the host configuration key from a host to call AWX:

    $ curl \
--data curl \
--data host_config_key=My_Host_Config_Key \
--show-error \
--silent \
https://awx.example.com/api/v2/job_templates/8/callback/

    Ensure that you use https when you enter the provisioning callback URL.

    This triggers the playbook run specified in the template against the host.
Additional resources

Appendix A: Ansible role and collection paths in Foreman

Foreman imports and runs Ansible roles and collections from specific system paths. System-installed roles and collections are located in /usr/share/ansible, while custom roles and collections should be placed in /etc/ansible.

Foreman imports and runs Ansible roles from the following paths:

  • /etc/ansible/roles

  • /usr/share/ansible/roles

  • /etc/ansible/collections

  • /usr/share/ansible/collections

Roles and collections from installed packages are placed under /usr/share/ansible. If you want to add custom roles or collections, place them under /etc/ansible.

Additional resources

Appendix B: Customizing Ansible configuration

Foreman manages essential Ansible configuration that is required for Ansible integration with Foreman. However, you can customize other Ansible configuration options as usual.

Foreman stores the essential Ansible configuration as environment variables in /etc/foreman-proxy/ansible.env. This file is managed by foreman-installer.

Ansible reads configuration from a configuration file and the environment provided by Smart Proxy. If you need to customize Ansible configuration, you can do so in the system-wide /etc/ansible/ansible.cfg file or in the /usr/share/foreman-proxy/.ansible.cfg file in the home directory of the foreman-proxy user. Note that if you use /usr/share/foreman-proxy/.ansible.cfg, Ansible spawned by Foreman ignores configuration in /etc/ansible/ansible.cfg.

Note that environment variables take precedence over values in ansible.cfg, which ensures that the essential configuration required by Foreman is retained.

The following table lists the essential Ansible configuration options managed by Foreman.

Table 4. Essential Ansible configuration
Environment Variable Config Key Description

ANSIBLE_CALLBACKS_ENABLED

callbacks_enabled

Enables callback to Foreman; equivalent to callback_whitelist for cross-version compatibility

ANSIBLE_CALLBACK_WHITELIST

callback_whitelist

Enables callback to Foreman; equivalent to callbacks_enabled for cross-version compatibility

ANSIBLE_COLLECTIONS_PATHS

collections_paths

List of paths to Ansible collections

ANSIBLE_HOST_KEY_CHECKING

host_key_checking

Disables checking of host keys during SSH connection

ANSIBLE_LOCAL_TEMP

local_tmp

Temporary directory on Smart Proxy

ANSIBLE_ROLES_PATH

roles_path

List of paths to Ansible roles

ANSIBLE_SSH_ARGS

ssh_args

Arguments passed to SSH connection
Additional resources
Pre-release version Report issue