Chapter 1. Getting started with Ansible in Satellite
Chapter 1. Getting started with Ansible in Satellite Use this guide to configure Satellite to use Ansible for remote execution. 1.1. Supported Ansible versions Satellite uses Ansible as provided by the base operating system of Satellite Server or any Capsules for remote execution. Therefore, the supported version of Ansible depends on your base OS configuration. 1.2. Configuring your Satellite to run Ansible roles In Satellite, you can import Ansible roles to help with automation of routine tasks. Ansible is enabled by default on Satellite Server. Ansible paths Satellite 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 . Note that Red Hat provides support only for Ansible roles and collections obtained from Red Hat. The paths are configured by Satellite. For more information, see Section 1.8, "Customizing Ansible configuration" . Procedure 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. On all Capsule Servers that you want to use to run Ansible roles on hosts, enable the Ansible plugin: 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. Import the Ansible roles into Satellite. Proceed to Chapter 2, Using Ansible roles to automate repetitive tasks on clients . 1.3. Enabling Ansible integration with Satellite Perform the following procedure to enable the Ansible plugin on your Satellite Server. Procedure Enable the Ansible plugin on your Satellite Server: 1.4. Importing Ansible roles and variables You can import Ansible roles and variables from the Ansible paths on Satellite Server or Capsule Servers that has Ansible enabled. Prerequisites Ensure that the roles and variables that you import are located in the Ansible paths on all Capsules from where you want to use the roles. Procedure In the Satellite web UI, navigate to Configure > Ansible > Roles . Click Import to select the Capsule from which you want to import. Select the roles that you want to import. Click Submit . 1.5. Overriding Ansible variables in Satellite If you run Ansible roles in Satellite, you can use Satellite to override Ansible variables for those roles. The following procedure refers to hosts and host groups. For more information, see Managing hosts . Precedence in overriding variables 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 You must have Ansible variables in Satellite. For more information, see Section 1.4, "Importing Ansible roles and variables" To use overridden Ansible variables, a user must have a role that allows them to see the attributes that are matched against hosts. Procedure In the Satellite web UI, navigate to Configure > Ansible > Variables . Select the Ansible variable that you want to override and manage with Satellite. In the Default Behavior area, select the Override checkbox. 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. In the Default Value field, enter the default value that you want to use if there is no match for the variable. 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. 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. 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. Optional: Expand the Specify Matchers area and specify criteria for selecting hosts on which the variable overrides. To save the override settings, click Submit . 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. Adding the variable to a host In the Satellite web UI, navigate to Hosts > All Hosts and select the host that you want to use. Click the Ansible tab, and in the Variables area, click the pencil icon to edit the value of the variable. 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 In the Satellite web UI, navigate to Configure > Host Groups , and select the host group that you want to use. Click the Parameters tab, and in the Host Group Parameters area, click Add Parameter . In the Name field, add the Ansible variable name. From the Type list, select the type of the variable for validation. In the Value field, enter the value for the variable. Adding the variable as a global parameter In the Satellite web UI, navigate to Configure > Global Parameters , and click Create Parameter . In the Name field, add the Ansible variable name. From the Type list, select the type of the variable for validation. In the Value field, enter the value for the variable. 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. 1.6. 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 Satellite. Using Ansible Roles in Satellite can make configuration faster and easier. Support levels for some of the Red Hat Enterprise Linux System Roles might be in Technology Preview. For up-to-date information about support levels and general information about Red Hat Enterprise Linux System Roles, see Red Hat Enterprise Linux System Roles . Before subscribing to the Extras channels, see the Red Hat Enterprise Linux Extras Product Lifecycle article. Procedure Ensure that the following repository is enabled: On Red Hat Enterprise Linux 8, ensure that the Appstream repository is enabled: 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: Install the rhel-system-roles package: 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. In the Satellite web UI, navigate to Configure > Ansible > Roles . Click the Capsule that contains the roles that you want to import. 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 Section 2.1, "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. For more information, see Red Hat Enterprise Linux (RHEL) System Roles . 1.7. Synchronizing Ansible Collections On Satellite, you can synchronize your Ansible Collections from Private Automation Hub, console.redhat.com , and other Satellite instances. Ansible Collections will appear on Satellite as a new repository type in the Satellite web UI menu under Content after the sync. Procedure In the Satellite web UI, navigate to Content > Products . Select the required product name. In the Products window, select the name of a product that you want to create a repository for. Click the Repositories tab, and then click New Repository . In the Name field, enter a name for the repository. The Label field is populated automatically based on the name. From the Type list, select ansible collection . 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/ . 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 . Authenticate. 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 . 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 . To sync Satellite from Satellite, leave both authentication fields blank. Click Save . Navigate to the Ansible Collections repository. From the Select Action menu, select Sync Now . 1.8. Customizing Ansible configuration Satellite manages essential Ansible configuration that is required for Ansible integration with Satellite. However, you can customize other Ansible configuration options as usual. Satellite stores the essential Ansible configuration as environment variables in /etc/foreman-proxy/ansible.env . This file is managed by satellite-installer . Ansible reads configuration from a configuration file and the environment provided by Capsule. 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 Satellite 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 Satellite is retained. The following table lists the essential Ansible configuration options managed by Satellite. Table 1.1. Essential Ansible configuration Environment Variable Config Key Description ANSIBLE_CALLBACKS_ENABLED callbacks_enabled Enables callback to Satellite; equivalent to callback_whitelist for cross-version compatibility ANSIBLE_CALLBACK_WHITELIST callback_whitelist Enables callback to Satellite; 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 Capsule ANSIBLE_ROLES_PATH roles_path List of paths to Ansible roles ANSIBLE_SSH_ARGS ssh_args Arguments passed to SSH connection Additional resources Ansible Configuration Settings 1.9. Using Ansible Vault with Satellite 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 If you customized /etc/ansible/ansible.cfg , copy your configuration from /etc/ansible/ansible.cfg to /usr/share/foreman-proxy/.ansible.cfg . Encrypt the sensitive file using the ansible-vault command: Note that ansible-vault changes the file permissions to 600 . Change the group and permissions of the encrypted file to ensure that the foreman-proxy user can read it: Create the /usr/share/foreman-proxy/.ansible_vault_password file and enter the Vault password into it. Change the user and permissions of the .ansible_vault_password file to ensure that only the foreman-proxy user can read it: Add the path of the Vault password file to the [defaults] section in /usr/share/foreman-proxy/.ansible.cfg : The path to the Vault password file must be absolute.
satellite-installer --enable-foreman-proxy-plugin-ansible satellite-installer --enable-foreman-plugin-ansible --enable-foreman-proxy-plugin-ansible subscription-manager repos --enable=rhel-8-for-x86_64-appstream-rpms subscription-manager repos --enable=rhel-7-server-extras-rpms satellite-maintain packages install rhel-system-roles --- collections: - name: my_namespace.my_collection version: 1.2.3 ansible-vault encrypt /etc/ansible/roles/ Role_Name /vars/main.yml chgrp foreman-proxy /etc/ansible/roles/ Role_Name /vars/main.yml chmod 0640 /etc/ansible/roles/ Role_Name /vars/main.yml chown foreman-proxy:foreman-proxy /usr/share/foreman-proxy/.ansible_vault_password chmod 0400 /usr/share/foreman-proxy/.ansible_vault_password [defaults] vault_password_file = /usr/share/foreman-proxy/.ansible_vault_password