1. Configuration management with Ansible in orcharhino

By using Ansible as a configuration management tool in orcharhino, you can define the desired state of your hosts and maintain it over time. orcharhino 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 orcharhino. Running the roles enforces the configuration.

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

  1. Import Ansible roles into orcharhino.

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

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

  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 orcharhino

orcharhino repositories include ansible-core as a packaged dependency, which determines the version supported for integration with orcharhino.

orcharhino repositories include ansible-core as a packaged dependency for Ansible integration with orcharhino Server and orcharhino Proxy Servers. The supported version of Ansible is ansible-core 2.16.

2. Enabling the Ansible plugin

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

Procedure

  1. Enable the Ansible plugin on your orcharhino Server:

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

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

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

3. Configuring Ansible definitions to apply to hosts

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

3.1. Adding Red Hat Enterprise Linux System Roles

Red Hat Enterprise Linux System Roles is a configuration interface to remotely manage Red Hat Enterprise Linux servers. You can use Red Hat Enterprise Linux System Roles to add Ansible roles in orcharhino.

Procedure

  1. Ensure that the following repository is enabled:

    • On Red Hat Enterprise Linux 10, 9, or 8, ensure that the AppStream repository is enabled:

      # subscription-manager repos --enable=rhel-10-for-x86_64-appstream-rpms
# subscription-manager repos --enable=rhel-9-for-x86_64-appstream-rpms
# subscription-manager repos --enable=rhel-8-for-x86_64-appstream-rpms

      You must enable an AppStream repository that is designated for your architecture.

  2. Install the rhel-system-roles package:

    # dnf install rhel-system-roles

    The rhel-system-roles package downloads to /usr/share/ansible/roles/. You can view and make any modifications that you want to the files before you import.

  3. In the orcharhino management UI, navigate to Configure > Ansible > Roles.

  4. Click the orcharhino Proxy that contains the roles that you want to import.

  5. From the list of Ansible roles, select the checkbox of the roles you want to import, and then click Update.

    You can now assign Ansible roles to hosts or host groups. For more information, see Assigning Ansible roles to an existing host.

    You can also add the modules contained in these roles to your Ansible Playbooks by adding them to Ansible Job Templates. You must include the hosts:all line in the job template.

3.2. Importing Ansible roles and variables

You can import Ansible roles and variables from the Ansible paths on orcharhino Server or orcharhino Proxy Servers that have Ansible enabled.

Procedure

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

    If you want to use custom or third party Ansible roles, ensure to configure an external version control system to synchronize roles between orcharhino Server and orcharhino Proxy Servers.

  2. In the orcharhino management UI, navigate to Configure > Ansible > Roles.

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

  4. Select the roles that you want to import.

  5. Click Submit.

Additional resources

3.3. Overriding Ansible variables in orcharhino

You can use orcharhino to override Ansible variables for roles imported into orcharhino. 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 orcharhino. 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 orcharhino management UI, navigate to Configure > Ansible > Variables.

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

  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 orcharhino management 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 orcharhino management 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 orcharhino management 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 orcharhino management 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 orcharhino management UI.

3.4. Assigning Ansible roles to a host group

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

Procedure

  1. In the orcharhino management 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.5. Assigning Ansible roles to an existing host

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

Procedure

  1. In the orcharhino management 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.6. 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 orcharhino management 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.7. Removing Ansible roles from a host

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

Procedure

  1. In the orcharhino management 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, orcharhino 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 orcharhino management UI to apply the assigned configuration immediately. This helps you verify and enforce the intended state of the host.

Prerequisites
Procedure

  1. In the orcharhino management 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, orcharhino 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 orcharhino management 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 orcharhino management UI to preview changes before applying them. This helps you reduce risk when validating role behavior on a host.

Procedure

  1. In the orcharhino management 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 orcharhino

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 orcharhino and AWX

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

6.1. Adding orcharhino Server to AWX as a dynamic inventory item

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

Prerequisites

  • If your orcharhino 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 orcharhino Server user. For more information about managing users, roles, and permission filters, see Creating and managing roles in Administering orcharhino.

  • Your orcharhino Server and AWX are hosted on the same network or subnet.

Procedure

  1. In the AWX web UI, create a credential for your orcharhino. 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 orcharhino.

    Table 1. orcharhino credentials
    Credential Type: orcharhino

    orcharhino URL:

    https://orcharhino.example.com

    Username:

    The username of the orcharhino user with the integration role.

    Password:

    The password of the orcharhino 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 orcharhino Server as the inventory source, specifying the following inventory source options.

    Table 2. Inventory source options
    Source orcharhino

    Credential

    The credential you create for orcharhino 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 orcharhino, 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 orcharhino Server, the Preseed Default and Preseed 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

  • orcharhino is added as a dynamic inventory in AWX.

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 orcharhino. 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 orcharhino management 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:

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

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

orcharhino 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

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

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

Ansible reads configuration from a configuration file and the environment provided by orcharhino 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 orcharhino 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 orcharhino is retained.

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

Table 4. Essential Ansible configuration
Environment Variable Config Key Description

ANSIBLE_CALLBACKS_ENABLED

callbacks_enabled

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

ANSIBLE_CALLBACK_WHITELIST

callback_whitelist

Enables callback to orcharhino; 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 orcharhino Proxy

ANSIBLE_ROLES_PATH

roles_path

List of paths to Ansible roles

ANSIBLE_SSH_ARGS

ssh_args

Arguments passed to SSH connection
Additional resources