rhc

An ansible role which connects RHEL systems to Red Hat.

Requirements

The role requires subscription-manager, which is available from the standard RHEL repositories, and usually installed by default on RHEL. On other distributions it will be installed if not already.

The role requires also insights-client, which is available from the standard RHEL repositories, in case the Insights support is enabled (and it is by default).

In addition, the role requires rhc, which is available from the standard RHEL repositories, in case the Insights remediation is enabled (and it is by default).

Collection requirements

The role requires modules from external collections. Use the following command to install them:

ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Role Variables

    rhc_state: present

Whether the system is connected to Red Hat; valid values are present (the default, to ensure connection), absent, and reconnect.

When using reconnect, the system will be first disconnected in case it was already connected; because of this, the role will always report a "changed" status.

    rhc_organization: "your-organization"

The organization of the user. This must be specified when connecting if either:

the user belongs to more than one organization
using activation keys (see rhc_auth below)

    rhc_auth: {}

The authentication method used to connect a system. This must be specified in case a system may need to connect (e.g. in case it was not before). There are few possible authentication methods; only one can be specified at a time.

NB: the variables used for authentication are considered secrets, and thus they ought to be secured. We recommend the usage of Ansible Vault as source for them. The references below only describe which keys exists and what they are for.

For authenticating using username & password, specify the login dictionary using the following mandatory keys:

rhc_auth:
  login:
    username: "your-username"
    password: "your-password"

using rhc_organization if needed.

For authenticating using activation keys, specify the activation_keys dictionary using the following mandatory keys, together with rhc_organization:

rhc_auth:
  activation_keys:
    keys: ["key-1", ...]
rhc_organization: "your-organization"

    rhc_server: {}

The details of the registration server to connect to; it can contain the following optional keys:

rhc_server:
  hostname: "hostname"
  port: 443
  prefix: "server-prefix"
  insecure: false

hostname is the hostname of the server
port is the port to which connect to on the server
prefix is the prefix (starting with /) for the API calls to the server
insecure specifies whether to disable the validation of the SSL certificate of the server

To register to Red Hat, leave rhc_server unset (default {}). Set it only to connect to Red Hat Satellite or another registration server.

    rhc_baseurl: ""

The base URL for receiving content from the subscription server.

    rhc_repo_ca_cert_fetch_from_satellite: false

CA certificate used for CDN content (maps to the rhsm_repo_ca_cert parameter of community.general.redhat_subscription). The three path and content variables are unset by default.

To connect to a Satellite server, set at least one of rhc_repo_ca_cert, rhc_repo_ca_cert_src, or rhc_repo_ca_cert_content to provide its CA certificate, or set rhc_repo_ca_cert_fetch_from_satellite: true to download it from Satellite. This certificate file is usually found at /etc/pki/katello/certs/katello-server-ca.crt on the Satellite server machine, but the path may differ depending on your installation.

rhc_repo_ca_cert is the path on the managed node. When set alone, the file is assumed to already exist on the managed node.
rhc_repo_ca_cert_src is a path on the control node; the role copies that file to rhc_repo_ca_cert on the managed node.
rhc_repo_ca_cert_content is the PEM string content to write to rhc_repo_ca_cert on the managed node.

For example, in a registration playbook, provide the certificate inline:

- hosts: all
  vars:
    rhc_repo_ca_cert_content: |
      -----BEGIN CERTIFICATE-----
      <base64-encoded certificate content>
      -----END CERTIFICATE-----
    # Optional; omit to use the default destination.
    rhc_repo_ca_cert: /etc/pki/ca-trust/source/anchors/satellite-ca.pem
  roles:
    - linux-system-roles.rhc

rhc_repo_ca_cert_src, rhc_repo_ca_cert_content, and enabling rhc_repo_ca_cert_fetch_from_satellite are mutually exclusive. The role rejects combining any of these certificate sources. If a source is set or fetching is enabled and rhc_repo_ca_cert is not set, the destination defaults to /etc/pki/ca-trust/source/anchors/katello-server-ca.pem. When the certificate file is changed by the role, update-ca-trust is run.

rhc_repo_ca_cert_fetch_from_satellite is a boolean that defaults to false. When enabled, the role uses ansible.builtin.get_url to download the certificate from https://{{ rhc_server["hostname"] }}/unattended/public/foreman_raw_ca on the managed node. If rhc_server.port is set, it is included after the hostname; otherwise HTTPS uses its default port, 443. rhc_server.hostname must be set when downloading the certificate.

Security warning: This download uses validate_certs: false, so the Satellite server's TLS certificate is not validated. This is potentially insecure and should only be used if the connection to Satellite is trusted.

    rhc_repositories: []

A list of repositories to enable or disable in the system. Each item is a dictionary containing two keys:

name is the name of a repository; this keys is mandatory
state is the state of that repository in the system, and it can be enabled or disabled; this key is optional, and enabled if not specified

rhc_repositories:
  - {name: "repository-1", state: enabled}
  - {name: "repository-2", state: disabled}

    rhc_release: "release"

A release to set for the system. Typically used for locking a RHEL system to a certain minor version of RHEL.

Use {"state":"absent"} (and not "") to actually unset the release set for the system.

    rhc_insights:
      state: present

Whether the system is connected to Insights; valid values are present (the default, to ensure connection), and absent.

    rhc_insights:
      autoupdate: true

Whether the system automatically updates the dynamic configuration. It is enabled by default.

    rhc_insights:
      ansible_host: "example-host"

Configures the ansible host name with a custom value for the system record in Host Based Inventory (HBI). This host name is used in playbooks by remediations. It is null by default and will use the system host name if not specified.

Possible values of this variable:

null or an empty string: the ansible host name is not changed.
{state: absent}: the ansible host name is unset in the insights-client config file and Host Based Inventory (HBI) is updated to use the system host name.
any other string value: the ansible host name is changed in Host Based Inventory (HBI).

    rhc_insights:
      display_name: "Example Host"

Configures the display name with a custom value for the system record in Host Based Inventory (HBI). This display name is only used to identify the host in the Inventory. It is null by default and will use the system host name if not specified.

Possible values of this variable:

null or an empty string: the display name is not changed
any other string value: the display name is changed in Host Based Inventory (HBI).

Note: If not set explicitly on registration, the display name is set to the hostname by default. It is not possible to automatically revert it to the hostname, but it can be set so manually.

    rhc_insights:
      remediation: present

Whether the system is configured to run the Insights remediation; valid values are present (the default, to ensure remediation), and absent.

Please note that the Insights remediation is supported only on RHEL 8.4 or greater, as the needed packages are available only starting from that version; on older versions, this parameter has no effect.

    rhc_insights:
      tags: {}

A dictionary of tags that is added to the system record in Host Based Inventory (HBI); typically used for the grouping and tagging of systems, and to search for systems in the inventory.

Possible values of this variable:

null or an empty value (e.g.: {}): the tags file content is not changed
{state: absent}: all the tags are removed (by removing the tags file)
any other value: the file is created with the specified tags

Since the tags are arbitrary values for the tagging of systems, there is no fixed format. In the specified dictionary, the keys are strings, and the type of the values can be any data type (strings, numbers, lists, dictionaries, etc).

Example of the tags configured in the insights-client documentation:

rhc_insights:
  tags:
    group: _group-name-value_
    location: _location-name-value_
    description:
      - RHEL8
      - SAP
    key 4: value

    rhc_proxy: {}

The details of the proxy server to use for connecting:

rhc_proxy:
  hostname: "proxy-hostname"
  scheme: http
  port: 4321
  username: "proxy-hostname"
  password: "proxy-password"

hostname is the hostname of the proxy server
scheme is the scheme to use for the proxy server, usually "http" or "https", defaulting to "http"
port is the port to which connect to on the proxy server
username is the username to use for authenticating on the proxy server; it can be not specified if the proxy server does not require authentication
password is the password to use for authenticating on the proxy server; it can be not specified if the proxy server does not require authentication

Use {"state":"absent"} to reset all the proxy configurations to empty (effectively disabling the proxy server).

NB: the variables used for the authentication on the proxy server are considered secrets, and thus they ought to be secured. We recommend the usage of Ansible Vault as source for them.

    rhc_environments: []

The list of environments to which register to when connecting the system.

NB:

this only works when the system is being connected from an unconnected state -- it cannot change the environments of already connected systems
this requires the environments to be enabled on the registration server; in Red Hat Satellite or Katello, this feature is called "Content Views"

Example Playbooks

Register systems to Red Hat, including Insights, authenticating using username and password (rhc_server is not set, so the default Red Hat server is used):

- name: Register systems
  hosts: all
  vars:
    rhc_auth:
      login:
        username: "your-username"
        password: !vault |
          $ANSIBLE_VAULT;1.2;AES256;dev
          ....
  roles:
    - linux-system-roles.rhc

Connect systems to a Satellite server using its CA certificate:

This example assumes the inventory defines satellite-server and satellite-client. Set satellite_hostname to the Satellite server hostname that matches its TLS certificate, and provide satellite_username and satellite_password through Ansible Vault. Adjust the certificate path if needed for your installation.

- name: Register systems with Satellite
  hosts: satellite-client
  become: true
  vars:
    satellite_hostname: satellite.example.com
  tasks:
    - name: Register with Satellite
      ansible.builtin.include_role:
        name: linux-system-roles.rhc
      vars:
        rhc_repo_ca_cert_fetch_from_satellite: true
        rhc_auth:
          login:
            username: "{{ satellite_username }}"
            password: "{{ satellite_password }}"
        rhc_insights:
          state: absent
        rhc_organization: your-organization
        rhc_server:
          hostname: "{{ satellite_hostname }}"
          port: 443
          prefix: /rhsm
          insecure: false
        rhc_baseurl: "https://{{ satellite_hostname }}/pulp/content"

Ensure that certain RHEL 9 repositories are enabled, and another one is not:

- name: Ensure RHEL 9 repositories are enabled
  hosts: all
  vars:
    rhc_repositories:
      - {name: "rhel-9-for-x86_64-baseos-rpms", state: enabled}
      - {name: "rhel-9-for-x86_64-appstream-rpms", state: enabled}
      - {name: "codeready-builder-for-rhel-9-x86_64-rpms", state: disabled}
  roles:
    - linux-system-roles.rhc

Ensure that a RHEL 8 system is locked on RHEL 8.6:

- name: Ensure systems are locked at RHEL 8.6
  hosts: all
  vars:
    rhc_release: 8.6
  roles:
    - linux-system-roles.rhc

Ensure that a system is connected to Insights, without optional features such as automatic updates and remediation:

- name: Ensure systems are connected to Insights
  hosts: all
  vars:
    rhc_insights:
      autoupdate: false
      remediation: absent
  roles:
    - linux-system-roles.rhc

License

MIT