Managing configurations using Ansible integration

Procedure

1. Add the roles to a directory in an Ansible path on Satellite Server and all Capsule Servers from where you want to use the roles. If you want to use custom or third party Ansible roles, ensure to configure an external version control system to synchronize roles between Satellite Server and Capsule Servers.

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

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

3. Distribute SSH keys to enable Capsules to connect to hosts using SSH. For more information, see Distributing SSH Keys for Remote Execution in Managing hosts. Satellite runs Ansible roles the same way it runs remote execution jobs.
4. Import the Ansible roles into Satellite.
5. Proceed to Chapter 2, Using Ansible roles to automate repetitive tasks on clients.

Procedure

1. In the Satellite web UI, navigate to Configure > Ansible > Roles.
2. Click Import to select the Capsule from which you want to import.
3. Select the roles that you want to import.
4. Click Submit.

Procedure

1. In the Satellite web UI, navigate to Configure > Ansible > Variables.
2. Select the Ansible variable that you want to override and manage with Satellite.
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 Satellite 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.

Adding the variable to a host

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

Adding the variable to a host group

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

Adding the variable as a global parameter

1. In the Satellite 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 Satellite web UI.

Procedure

1. Ensure that the following repository is enabled:

   • On Red Hat Enterprise Linux 8, ensure that the Appstream repository is enabled:

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

     You must enable an Appstream repository that is designated for your architecture. For more information, see RHEL 8 repositories.

   • On Red Hat Enterprise Linux 7, ensure that the Extras repository is enabled:

     # subscription-manager repos --enable=rhel-7-server-extras-rpms

2. Install the rhel-system-roles package:

   # satellite-maintain packages 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 Satellite web UI, navigate to Configure > Ansible > Roles.
4. Click the Capsule 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.

Procedure

1. In the Satellite web UI, navigate to Content > Products.
2. Select the required product name.
3. In the Products window, select the name of a product that you want to create a repository for.
4. Click the Repositories tab, and then click New Repository.

5. In the Name field, enter a name for the repository.

   The Label field is populated automatically based on the name.

6. From the Type list, select ansible collection.

7. In the Upstream URL field, enter the URL for the upstream collections repository.

   The URL can be any Ansible Galaxy endpoint. For example, https://console.redhat.com/api/automation-hub/.

8. Optional: In the Requirements.yml field, you can specify the list of collections you want to sync from the endpoint, as well as their versions.

   If you do not specify the list of collections, everything from the endpoint will be synced.

   ---
   collections:
   - name: my_namespace.my_collection
     version: 1.2.3

   For more information, see Installing roles and collections from the same requirements.yml file in the Galaxy User Guide.

9. Authenticate.

   1. To sync Satellite from Private Automation Hub, enter your token in the Auth Token field.

      For more information, see Connect Private Automation Hub in Connect to Hub.

   2. To sync Satellite from console.redhat.com, enter your token in the Auth Token field and enter your SSO URL in the the Auth URL field.

      For more information, see Getting started with automation hub.

   3. To sync Satellite from Satellite, leave both authentication fields blank.
10. Click Save.
11. Navigate to the Ansible Collections repository.
12. From the Select Action menu, select Sync Now.

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.

Procedure

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

Procedure

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

Procedure

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

Procedure

1. In the Satellite web UI, navigate to Hosts > All Hosts.
2. Select the checkbox of the host that contains the Ansible role you want to run.
3. From the Select Action list, select Run all Ansible roles.

Procedure

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

Procedure

1. In the Satellite web UI, navigate to Configure > Host Groups.
2. From the list in the Actions column for the host group, select Run all Ansible roles.

Procedure

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

1. Satellite finds the host’s interfaces that have the Remote execution checkbox selected.
2. Satellite finds the subnets of these interfaces.
3. Satellite finds remote execution Capsules assigned to these subnets.
4. From this set of Capsules, Satellite selects the Capsule that has the least number of running jobs. By doing this, Satellite ensures that the jobs load is balanced between remote execution Capsules.

Procedure

1. In the Satellite web UI, navigate to Hosts > Templates > Job templates.
2. Click New Job Template.
3. Click the Template tab, and in the Name field, enter a unique name for your job template.
4. Select Default to make the template available for all organizations and locations.
5. Create the template directly in the template editor or upload it from a text file by clicking Import.
6. Optional: In the Audit Comment field, add information about the change.
7. Click the Job tab, and in the Job category field, enter your own category or select from the default categories listed in Default Job Template Categories in Managing hosts.
8. Optional: In the Description Format field, enter a description template. For example, Install package %{package_name}. You can also use %{template_name} and %{job_category} in your template.
9. From the Provider Type list, select SSH for shell scripts and Ansible for Ansible tasks or playbooks.
10. Optional: In the Timeout to kill field, enter a timeout value to terminate the job if it does not complete.
11. Optional: Click Add Input to define an input parameter. Parameters are requested when executing the job and do not have to be defined in the template. For examples, see the Help tab.
12. Optional: Click Foreign input set to include other templates in this job.
13. Optional: In the Effective user area, configure a user if the command cannot use the default remote_execution_effective_user setting.
14. Optional: If this template is a snippet to be included in other templates, click the Type tab and select Snippet.
15. Optional: If you use the Ansible provider, click the Ansible tab. Select Enable Ansible Callback to allow hosts to send facts, which are used to create configuration reports, back to Satellite after a job finishes.
16. Click the Location tab and add the locations where you want to use the template.
17. Click the Organizations tab and add the organizations where you want to use the template.
18. Click Submit to save your changes.

Procedure

1. Fetch the available Ansible playbooks by using the following API request:

   # curl -X GET -H 'Content-Type: application/json' https://satellite.example.com/ansible/api/v2/ansible_playbooks/fetch?proxy_id=My_capsule_ID

2. Select the Ansible playbook you want to import and note its name.

3. Import the Ansible playbook by its name:

   # curl -X PUT -H 'Content-Type: application/json' -d '{ "playbook_names": ["My_Playbook_Name"] }' https://satellite.example.com/ansible/api/v2/ansible_playbooks/sync?proxy_id=My_capsule_ID

   You get a notification in the Satellite web UI after the import completes.

Procedure

1. In the Satellite web UI, navigate to Administer > Settings.
2. Click Remote Execution.
3. Configure the Fallback to Any Capsule setting.

Procedure

1. In the Satellite web UI, navigate to Administer > Settings.
2. Click Remote Execution.
3. Configure the Enable Global Capsule setting.

Procedure

1. On your Satellite Server or Capsule Server, create a new directory:

   # mkdir /My_Remote_Working_Directory

2. Copy the SELinux context from the default /tmp directory:

   # chcon --reference=/tmp /My_Remote_Working_Directory

3. Configure your Satellite Server or Capsule Server to use the new directory:

   # satellite-installer \
   --foreman-proxy-plugin-ansible-working-dir /My_Remote_Working_Directory

Procedure

1. Navigate to Administer > Settings.
2. Select the Remote Execution tab.
3. Click the value of the Effective User Method setting.
4. Select the new value.
5. Click Submit.

1. Section 4.14, “Distributing SSH keys for remote execution manually”.
2. Section 4.16, “Using the Satellite API to obtain SSH keys for remote execution”.
3. Section 4.17, “Configuring a Kickstart template to distribute SSH keys during provisioning”.
4. For new Satellite hosts, you can deploy SSH keys to Satellite hosts during registration using the global registration template. For more information, see Registering a Host to Red Hat Satellite Using the Global Registration Template in Managing hosts.

Procedure

1. On the target host, create the ~/.ssh directory to store the SSH key:

   # mkdir ~/.ssh

2. Download the SSH key from Capsule:

   # curl https://capsule.example.com:9090/ssh/pubkey >> ~/.ssh/authorized_keys

3. Configure permissions for the ~/.ssh directory:

   # chmod 700 ~/.ssh

4. Configure permissions for the authorized_keys file:

   # chmod 600 ~/.ssh/authorized_keys

Procedure

1. Find the ID of the foreman-proxy user:

   # id -u foreman-proxy

2. Modify the umask value so that new files have the permissions 600:

   # umask 077

3. Create the directory for the keytab:

   # mkdir -p "/var/kerberos/krb5/user/My_User_ID"

4. Create a keytab or copy an existing keytab to the directory:

   # cp My_Client.keytab /var/kerberos/krb5/user/My_User_ID/client.keytab

5. Change the directory owner to the foreman-proxy user:

   # chown -R foreman-proxy:foreman-proxy "/var/kerberos/krb5/user/My_User_ID"

6. Ensure that the keytab file is read-only:

   # chmod -wx "/var/kerberos/krb5/user/My_User_ID/client.keytab"

7. Restore the SELinux context:

   # restorecon -RvF /var/kerberos/krb5

Procedure

1. To install and enable Kerberos authentication for remote execution, enter the following command:

   # satellite-installer --foreman-proxy-plugin-remote-execution-script-ssh-kerberos-auth true

2. To edit the default user for remote execution, in the Satellite web UI, navigate to Administer > Settings and click the Remote Execution tab. In the SSH User row, edit the second column and add the user name for the Kerberos account.
3. Navigate to remote_execution_effective_user and edit the second column to add the user name for the Kerberos account.

Procedure

1. To clone a template, in the Actions column, select Clone.
2. Enter a unique name for the clone and click Submit to save the changes.

Procedure

1. In the Satellite web UI, navigate to Monitor > Jobs and click Run job.
2. Select the Job category and the Job template you want to use, then click Next.

3. Select hosts on which you want to run the job. If you do not select any hosts, the job will run on all hosts you can see in the current context.

   Note

   If you want to select a host group and all of its subgroups, it is not sufficient to select the host group as the job would only run on hosts directly in that group and not on hosts in subgroups. Instead, you must either select the host group and all of its subgroups or use this search query:

   hostgroup_fullname ~ "My_Host_Group*"

   Replace My_Host_Group with the name of the top-level host group.

4. If required, provide inputs for the job template. Different templates have different inputs and some templates do not have any inputs. After entering all the required inputs, click Next.
5. Optional: To configure advanced settings for the job, fill in the Advanced fields. To learn more about advanced settings, see Section 4.22, “Advanced settings in the job wizard”.
6. Click Next.

7. Schedule time for the job.

   • To execute the job immediately, keep the pre-selected Immediate execution.
   • To execute the job in future time, select Future execution.
   • To execute the job on regular basis, select Recurring execution.

8. Optional: If you selected future or recurring execution, select the Query type, otherwise click Next.

   • Static query means that job executes on the exact list of hosts that you provided.
   • Dynamic query means that the list of hosts is evaluated just before the job is executed. If you entered the list of hosts based on some filter, the results can be different from when you first used that filter.

   Click Next after you have selected the query type.

9. Optional: If you selected future or recurring execution, provide additional details:

   • For Future execution, enter the Starts at date and time. You also have the option to select the Starts before date and time. If the job cannot start before that time, it will be canceled.
   • For Recurring execution, select the start date and time, frequency, and the condition for ending the recurring job. You can choose the recurrence to never end, end at a certain time, or end after a given number of repetitions. You can also add Purpose - a special label for tracking the job. There can only be one active job with a given purpose at a time.

   Click Next after you have entered the required information.

10. Review job details. You have the option to return to any part of the job wizard and edit the information.
11. Click Submit to schedule the job for execution.

CLI procedure

1. Enter the following command on Satellite:

   # hammer settings set \
   --name=remote_execution_global_proxy \
   --value=false

2. Find the ID of the job template you want to use:

   # hammer job-template list

3. Show the template details to see parameters required by your template:

   # hammer job-template info --id My_Template_ID

4. Execute a remote job with custom parameters:

   # hammer job-invocation create \
   --inputs My_Key_1="My_Value_1",My_Key_2="My_Value_2",... \
   --job-template "My_Template_Name" \
   --search-query "My_Search_Query"

   Replace My_Search_Query with the filter expression that defines hosts, for example "name ~ My_Pattern". For more information about executing remote commands with hammer, enter hammer job-template --help and hammer job-invocation --help.

Procedure

1. In the Satellite web UI, navigate to Hosts > All Hosts and select the target host on which you want to execute a remote job.
2. On the Ansible tab, select Jobs.
3. Click Schedule recurring job.
4. Define the repetition frequency, start time, and date of the first run in the Create New Recurring Ansible Run window.
5. Click Submit.
6. Optional: View the scheduled Ansible job in host overview or by navigating to Ansible > Jobs.

Procedure

1. In the Satellite web UI, navigate to Configure > Host groups.
2. In the Actions column, select Configure Ansible Job for the host group you want to schedule an Ansible roles run for.
3. Click Schedule recurring job.
4. Define the repetition frequency, start time, and date of the first run in the Create New Recurring Ansible Run window.
5. Click Submit.

Procedure

1. In the Satellite web UI, navigate to Monitor > Jobs. This page is automatically displayed if you triggered the job with the Execute now setting. To monitor scheduled jobs, navigate to Monitor > Jobs and select the job run you wish to inspect.
2. On the Job page, click the Hosts tab. This displays the list of hosts on which the job is running.
3. In the Host column, click the name of the host that you want to inspect. This displays the Detail of Commands page where you can monitor the job execution in real time.
4. Click Back to Job at any time to return to the Job Details page.

CLI procedure

1. Find the ID of a job:

   # hammer job-invocation list

2. Monitor the job output:

   # hammer job-invocation output \
   --host My_Host_Name \
   --id My_Job_ID

3. Optional: To cancel a job, enter the following command:

   # hammer job-invocation cancel \
   --id My_Job_ID

Procedure

1. In the Satellite web UI, navigate to Administer > Remote Execution Features.
2. Find each feature whose name contains by_search.
3. Change the job template for these features from Katello Script Default to Katello Ansible Default.
4. Click Submit.

Procedure

1. In the Ansible Automation Controller web UI, create a credential for your Satellite. For more information about creating credentials, see Add a New Credential and Red Hat Satellite Credentials in the Automation Controller User Guide.

   Table 5.1. Satellite credentials

   Credential Type:	Red Hat Satellite 6
   Satellite URL:	https://satellite.example.com
   Username:	The username of the Satellite user with the integration role.
   Password:	The password of the Satellite user.

2. Add an Ansible Automation Controller user to the new credential. For more information about adding a user to a credential, see Getting Started with Credentials in the Automation Controller User Guide.
3. Add a new inventory. For more information, see Add a new inventory in the Automation Controller User Guide.

4. In the new inventory, add Satellite Server as the inventory source, specifying the following inventory source options. For more information, see Add Source in the Automation Controller User Guide.

   Table 5.2. Inventory source options

   Source	Red Hat Satellite 6
   Credential	The credential you create for Satellite Server.
   Overwrite	Select
   Overwrite Variables	Select
   Update on Launch	Select
   Cache Timeout	90

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

1. ansible_provisioning_callback
2. ansible_tower_callback_script
3. ansible_tower_callback_service

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 Satellite. For more information, see Add a New Credential in the Automation Controller User Guide.
2. Create a project. For more information, see Projects in the Ansible Automation Controller User Guide.
3. Add a job template to your project. For more information, see Job Templates in the Automation Controller User Guide.
4. 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 about job templates, see Job Templates in the Automation Controller User Guide.

Procedure

1. In the Satellite web UI, navigate to Configure > Host Group.
2. Create a host group or edit an existing host group.
3. In the Host Group window, click the Parameters tab.
4. Click Add Parameter.

5. Enter the following information for each new parameter:

   Table 5.3. Host parameters

   Name	Value	Description
   ansible_tower_provisioning	true	Enables Provisioning Callback.
   ansible_tower_fqdn	controller.example.com	The fully qualified domain name (FQDN) of your Ansible Automation Controller. Do not add https because this is appended by Satellite.
   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 Ansible Automation Controller.

6. Click Submit.
7. Create a host using the host group.

8. On the new host, enter the following command to start the ansible-callback service:

   # systemctl start ansible-callback

9. On the new host, enter the following command to output the status of the ansible-callback service:

   # systemctl status ansible-callback

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

   SAT_host systemd[1]: Started Provisioning callback to Ansible Automation Controller...

Procedure

1. In the Satellite web UI, navigate to Hosts > Templates > Job templates.
2. Click New Job Template.

3. Enter Run Command - restorecon in the Name field. Select Default to make the template available to all organizations. Add the following text to the template editor:

   restorecon -RvF <%= input("directory") %>

   The <%= input("directory") %> string is replaced by a user-defined directory during job invocation.

4. On the Job tab, set Job category to Commands.
5. Click Add Input to allow job customization. Enter directory to the Name field. The input name must match the value specified in the template editor.
6. Click Required so that the command cannot be executed without the user specified parameter.
7. Select User input from the Input type list. Enter a description to be shown during job invocation, for example Target directory for restorecon.
8. Click Submit. For more information, see Executing a restorecon Template on Multiple Hosts in Managing hosts.

Procedure

1. In the Satellite web UI, navigate to Monitor > Jobs and click Run job.
2. Select Commands as Job category and Run Command – restorecon as Job template and click Next.
3. Select the hosts on which you want to run the job. If you do not select any hosts, the job will run on all hosts you can see in the current context.
4. In the directory field, provide a directory, for example /home, and click Next.
5. Optional: To configure advanced settings for the job, fill in the Advanced fields. To learn more about advanced settings, see Section 4.22, “Advanced settings in the job wizard”. When you are done entering the advanced settings or if it is not required, click Next.

6. Schedule time for the job.

   • To execute the job immediately, keep the pre-selected Immediate execution.
   • To execute the job in future time, select Future execution.
   • To execute the job on regular basis, select Recurring execution.

7. Optional: If you selected future or recurring execution, select the Query type, otherwise click Next.

   • Static query means that the job executes on the exact list of hosts that you provided.

   • Dynamic query means that the list of hosts is evaluated just before the job is executed. If you entered the list of hosts based on some filter, the results can be different from when you first used that filter.

     Click Next after you have selected the query type.

8. Optional: If you selected future or recurring execution, provide additional details:

   • For Future execution, enter the Starts at date and time. You also have the option to select the Starts before date and time. If the job cannot start before that time, it will be canceled.

   • For Recurring execution, select the start date and time, frequency, and condition for ending the recurring job. You can choose the recurrence to never end, end at a certain time, or end after a given number of repetitions. You can also add Purpose - a special label for tracking the job. There can only be one active job with a given purpose at a time.

     Click Next after you have entered the required information.

9. Review job details. You have the option to return to any part of the job wizard and edit the information.
10. Click Submit to schedule the job for execution.