Ansible

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

In orcharhino, you can import Ansible roles to help with automation of routine tasks. To enable Ansible on orcharhino Server, see Enabling Ansible Integration with orcharhino.

orcharhino imports Ansible roles and variables from paths based on configuration in /etc/ansible/ansible.cfg. orcharhino then runs imported roles from paths based on configuration in /etc/foreman-proxy/ansible.cfg. In both cases, orcharhino reads the paths from roles_path and collections_paths directives. Keep these two cfg files in sync, otherwise you might import roles that cannot be run or you will not see roles you can run.

If none of the paths are specified in the configuration files, the following default paths are used:

Perform the following procedure to enable the Ansible plug-in on your orcharhino Server.

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

Note that some roles take longer to import than others.

If you run Ansible roles in orcharhino, you can use orcharhino to override Ansible variables for those roles.

The following procedure refers to hosts and host groups. For more information, see Managing Hosts.

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?

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.

Enterprise Linux System Roles is a configuration interface to remotely manage Enterprise Linux servers. You can use Enterprise Linux System Roles to add Ansible roles in orcharhino. Using Ansible Roles in orcharhino can make configuration faster and easier.

Support levels for some of the Enterprise Linux System Roles might be in Technology Preview. For up-to-date information about support levels and general information about Enterprise Linux System Roles, see Enterprise Linux System Roles.

Before subscribing to the Extras channels, see the Enterprise Linux Extras Product Life Cycle article.

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.

On orcharhino, you can synchronize your Ansible Collections from any Ansible Galaxy and other orcharhino instances. Ansible Collections will appear on orcharhino as a new repository type in the orcharhino management UI menu under Content after the sync.

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.

You can use Ansible roles for remote management of orcharhino clients.

After you assign Ansible roles to hosts, you can use Ansible for remote execution. For more information, see Distributing SSH Keys for Remote Execution.

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.

Use the following procedure to remove Ansible roles from a host.

Use the following procedure to change the order of Ansible roles applied to a host.

You can run Ansible roles on a host through the orcharhino management UI.

You can view the status of your Ansible job on the Run Ansible roles page. To rerun a job, click the Rerun button.

You can use Ansible roles for remote management of orcharhino clients.

You can run Ansible roles on a host group through the orcharhino management UI.

You can view the status of your Ansible job on the Run Ansible roles page. To rerun a job, click the Rerun button.

You can run Ansible roles in check mode through the orcharhino management UI.

You can run jobs on hosts remotely from orcharhino Proxies using shell scripts or Ansible tasks and playbooks. This is referred to as remote execution.

For custom Ansible roles that you create, or roles that you download, you must install the package containing the roles on the orcharhino Proxy base operating system. Before you can use Ansible roles, you must import the roles into orcharhino from the orcharhino Proxy where they are installed.

Communication occurs through orcharhino Proxy, which means that orcharhino Server does not require direct access to the target host, and can scale to manage many hosts. For more information, see transport modes for remote execution.

orcharhino uses ERB syntax job templates. For more information, see Template Writing Reference in Managing Hosts.

Several job templates for shell scripts and Ansible are included by default. For more information, see Setting up Job Templates in Managing Hosts.

You can run jobs on multiple hosts at once, and you can use variables in your commands for more granular control over the jobs you run. You can use host facts and parameters to populate the variable values.

In addition, you can specify custom values for templates when you run the command.

For more information, see Executing a Remote Job in Managing Hosts.

When you run a remote job on hosts, for every host, orcharhino performs the following actions to find a remote execution orcharhino Proxy to use.

orcharhino searches only for orcharhino Proxies that have the Ansible feature enabled.

If you have enabled Prefer registered through orcharhino Proxy for remote execution, orcharhino runs the REX job using the orcharhino Proxy the host is registered to.

By default, Prefer registered through orcharhino Proxy for remote execution is set to No. To enable it, in the orcharhino management UI, navigate to Administer > Settings, and on the Content tab, set Prefer registered through orcharhino Proxy for remote execution to Yes. This ensures that orcharhino performs REX jobs on hosts by the orcharhino Proxy to which they are registered to.

If orcharhino does not find a remote execution orcharhino Proxy at this stage, and if the Fallback to Any orcharhino Proxy setting is enabled, orcharhino adds another set of orcharhino Proxies to select the remote execution orcharhino Proxy from. orcharhino selects the most lightly loaded orcharhino Proxy from the following types of orcharhino Proxies that are assigned to the host:

If orcharhino does not find a remote execution orcharhino Proxy at this stage, and if the Enable Global orcharhino Proxy setting is enabled, orcharhino selects the most lightly loaded remote execution orcharhino Proxy from the set of all orcharhino Proxies in the host’s organization and location to execute a remote job.

You can control which roles can run which jobs within your infrastructure, including which hosts they can target. The remote execution feature provides two built-in roles:

You can clone the Remote Execution User role and customize its filter for increased granularity. If you adjust the filter with the view_job_templates permission on a customized role, you can only see and trigger jobs based on matching job templates. You can use the view_hosts and view_smart_proxies permissions to limit which hosts or orcharhino Proxies are visible to the role.

The execute_template_invocation permission is a special permission that is checked immediately before execution of a job begins. This permission defines which job template you can run on a particular host. This allows for even more granularity when specifying permissions.

You can run remote execution jobs against orcharhino and orcharhino Proxy registered as hosts to orcharhino with the execute_jobs_on_infrastructure_hosts permission. Standard Manager and Site Manager roles have this permission by default. If you use either the Manager or Site Manager role, or if you use a custom role with the execute_jobs_on_infrastructure_hosts permission, you can execute remote jobs against registered orcharhino and orcharhino Proxy hosts.

For more information on working with roles and permissions, see Creating and Managing Roles in Administering orcharhino.

The following example shows filters for the execute_template_invocation permission:

Use the first line in this example to apply the Reboot template to one selected host. Use the second line to define a pool of hosts with names ending with .staging.example.com. Use the third line to bind the template with a host group.

You can configure your orcharhino to use two different modes of transport for remote job execution.

On orcharhino Proxies in ssh mode, remote execution uses the SSH service to transport job details. This is the default transport mode. The SSH service must be enabled and active on the target hosts. The remote execution orcharhino Proxy must have access to the SSH port on the target hosts. Unless you have a different setting, the standard SSH port is 22.

On orcharhino Proxies in pull-mqtt mode, remote execution uses Message Queueing Telemetry Transport (MQTT) to publish jobs it receives from orcharhino Server. The host subscribes to the MQTT broker on orcharhino Proxy for job notifications using the yggdrasil pull client. After the host receives a notification, it pulls job details from orcharhino Proxy over HTTPS, runs the job, and reports results back to orcharhino Proxy.

To use the pull-mqtt mode, you must enable it on orcharhino Proxy and configure the pull client on the target hosts.

For orcharhino Proxies configured to use pull-mqtt mode, hosts can subscribe to remote jobs using the remote execution pull client. Managed hosts do not require an SSH connection to their orcharhino Proxy.

Use this procedure to create a job template. To use the CLI instead of the orcharhino management UI, see the CLI procedure.

You can extend and customize job templates by including other templates in the template syntax. For more information, see Template Writing Reference and Job Template Examples and Extensions in Managing Hosts.

You can import Ansible playbooks by name to orcharhino from collections installed on orcharhino Proxy.

You can import all the available Ansible playbooks to orcharhino from collections installed on orcharhino Proxy.

You can enable the Fallback to Any orcharhino Proxy setting to configure orcharhino to search for remote execution orcharhino Proxies from the list of orcharhino Proxies that are assigned to hosts. This can be useful if you need to run remote jobs on hosts that have no subnets configured or if the hosts' subnets are assigned to orcharhino Proxies that do not have the remote execution feature enabled.

If the Fallback to Any orcharhino Proxy setting is enabled, orcharhino adds another set of orcharhino Proxies to select the remote execution orcharhino Proxy from. orcharhino also selects the most lightly loaded orcharhino Proxy from the set of all orcharhino Proxies assigned to the host, such as the following:

By default, orcharhino searches for remote execution orcharhino Proxies in hosts' organizations and locations regardless of whether orcharhino Proxies are assigned to hosts' subnets or not. You can disable the Enable Global orcharhino Proxy setting if you want to limit the search to the orcharhino Proxies that are assigned to hosts' subnets.

If the Enable Global orcharhino Proxy setting is enabled, orcharhino adds another set of orcharhino Proxies to select the remote execution orcharhino Proxy from. orcharhino also selects the most lightly loaded remote execution orcharhino Proxy from the set of all orcharhino Proxies in the host’s organization and location to execute a remote job.

Ansible puts its own files it requires into the $HOME/.ansible/tmp directory, where $HOME is the home directory of the remote user. You have the option to set a different directory if required.

For orcharhino Proxies in ssh mode, remote execution connections are authenticated using SSH. The public SSH key from orcharhino Proxy must be distributed to its attached hosts that you want to manage.

Ensure that the SSH service is enabled and running on the hosts. Configure any network or host-based firewalls to enable access to port 22.

Use one of the following methods to distribute the public SSH key from orcharhino Proxy to target hosts:

orcharhino distributes SSH keys for the remote execution feature to the hosts provisioned from orcharhino by default.

If the hosts are running on Amazon Web Services, enable password authentication. For more information, see New User Accounts.

To distribute SSH keys manually, complete the following steps:

To use the orcharhino API to download the public key from orcharhino Proxy, complete this procedure on each target host.

You can add a remote_execution_ssh_keys snippet to your custom AutoYaST template to deploy SSH Keys to hosts during provisioning. AutoYaST templates that orcharhino ships include this snippet by default. orcharhino copies the SSH key for remote execution to the systems during provisioning.

You can add a remote_execution_ssh_keys snippet to your custom Kickstart template to deploy SSH Keys to hosts during provisioning. Kickstart templates that orcharhino ships include this snippet by default. orcharhino copies the SSH key for remote execution to the systems during provisioning.

You can add a remote_execution_ssh_keys snippet to your custom Preseed template to deploy SSH Keys to hosts during provisioning. Preseed templates that orcharhino ships include this snippet by default. orcharhino copies the SSH key for remote execution to the systems during provisioning.

Use this procedure to configure orcharhino to use a keytab to obtain Kerberos ticket granting tickets. If you do not set up a keytab, you must manually retrieve tickets.

You can use Kerberos authentication to establish an SSH connection for remote execution on orcharhino hosts.

orcharhino provides default job templates that you can use for executing jobs. To view the list of job templates, navigate to Hosts > Job templates. If you want to use a template without making changes, proceed to Executing a Remote Job in Managing Hosts.

You can use default templates as a base for developing your own. Default job templates are locked for editing. Clone the template and edit the clone.

Job templates use the Embedded Ruby (ERB) syntax. For more information about writing templates, see the Template Writing Reference in Managing Hosts.

To create an Ansible job template, use the following procedure and instead of ERB syntax, use YAML syntax. Begin the template with ---. You can embed an Ansible playbook YAML file into the job template body. You can also add ERB syntax to customize your YAML Ansible template. You can also import Ansible playbooks in orcharhino. For more information, see Synchronizing Repository Templates in Managing Hosts.

At run time, job templates can accept parameter variables that you define for a host. Note that only the parameters visible on the Parameters tab at the host’s edit page can be used as input parameters for job templates. If you do not want your Ansible job template to accept parameter variables at run time, in the orcharhino management UI, navigate to Administer > Settings and click the Ansible tab. In the Top level Ansible variables row, change the Value parameter to No.

You can execute a job that is based on a job template against one or more hosts.

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

You can schedule a recurring job to run Ansible roles on hosts.

You can schedule a recurring job to run Ansible roles on host groups.

You can monitor the progress of a job while it is running. This can help in any troubleshooting that may be required.

Ansible jobs run on batches of 100 hosts, so you cannot cancel a job running on a specific host. A job completes only after the Ansible playbook runs on all hosts in the batch.

When creating a job template, you can include an existing template in the template editor field. This way you can combine templates, or create more specific templates from the general ones.

The following template combines default templates to install and start the nginx service on clients:

The above template specifies parameter values for the rendered template directly. It is also possible to use the input() method to allow users to define input for the rendered template on job execution. For example, you can use the following syntax:

With the above template, you have to import the parameter definition from the rendered template. To do so, navigate to the Jobs tab, click Add Foreign Input Set, and select the rendered template from the Target template list. You can import all parameters or specify a comma separated list.

This example shows how to create a template called Run Command - restorecon that restores the default SELinux context for all files in the selected directory on target hosts.

This example shows how to create a template derived from the Run command - restorecon template created in Example restorecon Template. This template does not require user input on job execution, it will restore the SELinux context in all files under the /home/ directory on target hosts.

Create a new template as described in Setting up Job Templates, and specify the following string in the template editor:

This example shows how to run a job based on the template created in Example restorecon Template on multiple hosts. The job restores the SELinux context in all files under the /home/ directory.

This example shows how to set up a job template for performing power actions, such as reboot. This procedure prevents orcharhino from interpreting the disconnect exception upon reboot as an error, and consequently, remote execution of the job works correctly.

Create a new template as described in Setting up Job Templates, and specify the following string in the template editor: