Skip to content

Latest commit

 

History

History
207 lines (141 loc) · 8.18 KB

README.md

File metadata and controls

207 lines (141 loc) · 8.18 KB
Raw

insights-client

Installs, configures, and registers a system to the Red Hat Insights service. This role is intended to work on Red Hat Enterprise Linux, though it will generally work on any yum based system that has access to the insights-client RPM or the redhat-access-insights RPM.

NB: this role is deprecated, and it will be removed in version 2.0.0. Use the rhc system role instead, which provides equivalent functionalities.

Requirements

Note on managing RHEL 8 systems:

RHEL 8 changed the default path for the python interpreter so this role will need to know the new path. Ansible version 2.8+ can determine the correct path automatically, but if you are using Ansible version 2.7 or lower the path will need to be supplied to the role. This can be done by configuring the ansible_python_interpreter parameter via the configuration file (shown in the examples further down), playbook invocation, inventory, etc.

RHEL 8 platform-python path: /usr/libexec/platform-python

This is only required when managing RHEL 8 systems with Ansible version 2.7 or lower.

Note on managing RHEL 6 SELinux systems:

Almost all uses of Ansible that target SELinux machines require that the python module 'selinux' is installed. On RHEL that module is provided by the rpm 'python-selinux'. This rpm will need to be installed prior to using this role on RHEL 6 (it is already included in RHEL 7).

Role Variables / Configuration

The following variables can be used to perform some initial configuration for the insights-client install. These variables can be passed in directly with the playbook invocation or placed in a configuration yaml file. See the section 'Example Playbook' for information on various ways to use these variables.

  • insights_display_name: (optional)

    Sets or resets the Display Name/System Name within Insights. Insights needs an easily identifiable name for each system. If no explicit display name is given to a system, Insights uses it's hostname. If a system's hostname is not easily identifiable, like "localhost" or "d4098731408", you can give it a better name by setting 'insights_display_name'

    If undefined (not set at all), this role will not make changes to a system's display name.

    If defined (set) to be the empty string, this role will remove any previously set display name for the system, and cause it to use the systems hostname as it's Display name/System name.

    If defined to be a non-empty string, this role will replace any previously set display name for the system with the given string.

  • redhat_portal_username: (optional)

  • redhat_portal_password: (optional)

    If defined, these set, change, or remove the username and password in the Insights configuration. If undefined, this role will make no changes to the Insights configuration.

    If defined to a non-empty string this role will set or change the username and password. If defined to an empty string this role will remove the username and password.

    These should be valid username/password for Insights/Red Hat Portal/Red Hat Subscription Manager.

    If the username and password are set in the Insights configuration, they will be used as credentials for all future interactions with the Insights server.

    These credentials are only necessary if the client system is not registered with Red Hat Subscription Manager. If the username and password are not set in the Insights configuration, which is the default initial state, all interactions with the Insights server will use the CERT provided by RHSM.

  • auto_config: (optional)

    True/False - attempt to auto-configure the network connection with Satellite or RHSM. Default behavior is True.

  • authmethod: (optional)

    BASIC/CERT - This parameter is used to set the authentication method for the Portal. Default bahavior is BASIC. Note: when 'auto_config' is enabled (set to True), CERT will be used if RHSM or Satellite is detected.

  • insights_proxy: (optional)

    If the insights client is behind a proxy or firewall, a proxy can be specified. Default is unspecified. Ex: http://user:pass@192.168.100.50:8080

  • insights_tags: (optional) If defined, the key value pairs defined by insights_tags will be deployed to the host to define tags in the Insights portal. Ex:

    insights_tags:
  environment: prod
  application: web
  location:
    country: us
    state: nc
    city: durham

  • ansible_python_interpreter: (see Requirements above to determine if this is needed)

    This variable allows you to provide the python interpreter path for ansible to use. This is needed when managing RHEL 8 with older versions of Ansible (2.7 and lower).

    RHEL 8 platform-python path: /usr/libexec/platform-python

Facts Installed

This role installs a new fact 'insights' that provides the system's Insights' System Id. This System Id can be used to query about the system with the Insights Service API.

Once this role is run against a system, any future playbook run against that same system will have the system's Insights System Id in the fact 'ansible_local.insights.system_id'.

For example the task:

- debug: var=ansible_local.insights.system_id

will display the System Id.

Dependencies

N/A

Example Playbook

In the examples directory is a very basic playbook utilizing this role:

---
- hosts: all
  collections:
    - redhatinsights.insights
    
  tasks:
    - include_role: 
        name: insights_client
      when: ansible_os_family == 'RedHat'

Here is an example with additional configuration (though using a separate file is preferred if including usernames or passwords):

- hosts: all
  collections:
    - redhatinsights.insights
  vars:
    insights_display_name: 'example_system'
    ansible_python_interpreter: '/usr/libexec/platform-python'

  tasks:
    - include_role: 
        name: insights_client
      when: ansible_os_family == 'RedHat'

Example Configuration File

The insights-client install can be configured by using a configuration yaml file to modify various parameters. Here's an example, insights-client-config.yml, that configures the insights-client to register via basic auth using the provided username/password and display_name:

redhat_portal_username: example_user
redhat_portal_password: example_password
insights_display_name: example_system
autoconfig: False
authmethod: BASIC

Reminder: Check Requirements above to determine if ansible_python_interpreter should be configured prior to running.

If you need to run the Insights Client on a system that is not registered to Red Hat Subscription Manager, as often happens in testing and demoing, set the redhat_portal_username/redhat_portal_password.

Note: Any of the role variables mentioned earlier can be placed in this configuration file

Change the permissions on the file so that only you can read them (in case usernames/passwords are listed), and then any time you invoke this role, add the ansible-playbook --extra-vars option:

$ ansible-playbook ... --extra-vars @insights-client-config.yml ...

Note: One of the really useful features of Ansible Tower is role based management of credentials.

Example Use

  1. On a system where Ansible is installed, run the following command:

    $ ansible-galaxy collection install redhat.insights

    This will install the latest version of the collection to ansible's default collection directory.

  2. Copy the Example Playbook to a file named 'install-insights.yml'.

  3. Run the following command, replacing 'myhost.example.com' with the name of the system where you want to install, configure, and register the insights client.

    $ ansible-playbook --limit=myhost.example.com install-insights.yml --extra-vars @insights-client-config.yml

    Note: The ansible-playbook invocation will depend on ansible configuration

License and Author

License: Apache License 2.0 Author: Red Hat, Inc.