Documentation

25. Setting up an Insights Project

Tower supports integration with Red Hat Insights. Once a host is registered with Insights, it will be continually scanned for vulnerabilities and known configuration conflicts. Each of the found problems may have an associated fix in the form of an Ansible playbook. Insights users create a maintenance plan to group the fixes and, ultimately, create a playbook to mitigate the problems. Tower tracks the maintenance plan playbooks via an Insights project in Tower. Authentication to Insights via Basic Auth, from Tower, is backed by a special Insights Credential, which must first be established in Tower. To ultimately run an Insights Maintenance Plan in Tower, you need an Insights project, an inventory, and a Scan Job template.

25.1. Create Insights Credential

To create a new credential for use with Insights:

  1. Click the Credentials (credentials-icon) icon from the left navigation bar to access the Credentials page.

  1. Click the add button located in the upper right corner of the Credentials screen.

  1. Enter the name of the credential to be used in the Name field.

  2. Optionally enter a description for this credential in the Description field.

  3. In the Organization field, optionally enter the name of the organization with which the credential is associated, or click the search button and select it from the pop-up window.

  4. In the Credential Type field, enter Insights or click the search button and select it from the credential type pop-up window.

_images/credential-types-popup-window-insights.png
  1. Enter a valid Insights credential in the Username and Password fields. The Insights credential is the user’s Red Hat Customer Portal account username and password.

Credentials - create with demo insights credentials

  1. Click Save when done.

25.2. Create an Insights Project

To create a new Insights project:

  1. Click the Projects (projects-icon) icon from the left navigation bar to access the Projects page.

  1. Click the add button located in the upper right corner of the Projects screen.

  2. Enter the appropriate details into the required fields, at minimum. Note the following fields requiring specific Insights-related entries:

  • Name: Enter the name for your Insights project.

  • Organization: Enter the name of the organization associated with this project, or click the search button and select it from the pop-up window.

  • SCM Type: Select Red Hat Insights.

  • Upon selecting the SCM type, the Source Details field expands.

  1. The Credential field is pre-populated with the Insights credential you previously created. If not, enter the credential, or click the search button and select it from the pop-up window.

  2. Click to select the update option(s) for this project from the Options field, and provide any additional values, if applicable. For information about each option, click the Help help button next to the options.

Insights - create demo insights project form

  1. Click Save when done.

All SCM/Project syncs occur automatically the first time you save a new project. However, if you want them to be updated to what is current in Insights, manually update the SCM-based project by clicking the update button under the project’s available Actions.

This process syncs your Tower Insights project with your Insights account solution. Notice that the status dot beside the name of the project updates once the sync has run.

Insights - demo insights project success

25.3. Create Insights Inventory

The Insights playbook contains a hosts: line where the value is the hostname that Insights itself knows about, which may be different than the hostname that Tower knows about. Therefore, make sure that the hostnames in the Tower inventory match up with the system in the Red Hat Insights Portal.

To create a new inventory for use with Insights:

  1. Click the Inventories (inventories-icon) icon from the left navigation bar to access the Inventories page.

  1. Click the add options inventory button and select Inventory from the drop-down menu list to launch a New Inventory window.

  1. Enter the name and organization to be used in their respective fields.

  2. In the Insights Credential field, enter the name of the Insights credential you previously created, or click the search button and select it from the pop-up window.

Insights - example inventory

  1. Click Save and proceed to add a host.

Note

Typically, your inventory already contains Insights hosts. Tower just doesn’t know about them yet. The Insights credential allows Tower to get information from Insights about an Insights host. Tower identifying a host as an Insights host can occur without an Insights credential with the help of scan_facts.yml file. For instructions, refer to the Create a Scan Job Template section.

  1. Click the Hosts tab and click the add host button button to open the Create Host dialog.

  1. Enter the name in the Host Name field associated with the Insights host that will be used.

  2. Click Save when done.

25.4. Create a Scan Project

In order for Tower to utilize Insights Maintenance Plans, it must have visibility to them. Create and run a scan job against the inventory using a stock manual scan playbook.

  1. Click the Projects (projects-icon) icon from the left navigation bar to access the Projects page.

  2. Click the add button located in the upper right corner of the Projects screen.

  3. Enter the appropriate details into the required fields, at minimum. Note the following fields requiring specific Insights-related entries:

  • Name: Enter the name for your scan project.

  • Organization: The name of the organization is pre-populated with the organization you chose from creating the inventory.

  • SCM Type: Select Git.

  • Upon selecting the SCM type, the Source Details field expands.

  1. In the SCM URL field, enter https://github.com/ansible/awx-facts-playbooks. This is the location where the scan job template is stored.

  2. Click to select the update option(s) for this project from the Options field, and provide any additional values, if applicable. For information about each option, click the Help help button next to the options.

Insights - create insights project scan

  1. Click Save when done.

All SCM/Project syncs occur automatically the first time you save a new project. However, if you want them to be updated to what is current in Insights, manually update the SCM-based project by clicking the update button under the project’s available Actions.

Syncing imports into Tower any Maintenance Plans in your Insights account that has a playbook solution. It will use the default Plan resolution. Notice that the status dot beside the name of the project updates once the sync has run.

25.5. Create a Scan Job Template

Create a scan job template that uses the fact scan playbook:

  1. Click the Templates (templates-icon) icon from the left navigation bar to access the Templates page.

  1. Click the add options template button and select Job Template from the drop-down menu list to launch a New Job Template window.

  1. Enter the appropriate details into the required fields, at minimum. Note the following fields requiring specific Insights-related entries:

  • Name: Enter the name of your scan job.

  • Job Type: Choose Run from the drop-down menu list.

  • Inventory: Enter the name of the Insights inventory, or click the search button and select it from the pop-up window.

  • Project: Enter the name of the Scan project you previously created, or click the search button and select it from the pop-up window.

  • Playbook: Select scan_facts.yml from the drop-down menu list. This is the playbook associated with the Scan project you previously set up.

  • Credential: Enter the credential to use for this project or click the search button and select it from the pop-up window. The credential does not have to be an Insights credential.

  • Verbosity: Keep the default setting, or select the desired verbosity from the drop-down menu list.

  1. Click to select Enable Privilege Escalation and Enable Fact Cache from the Options field.

A scan job template for Insights should be launched with the Privilege Escalation option enabled to allow the job to access /etc/redhat-access-insights/machine-id as a root user in order to obtain the value of system_id from the target host. What this does is activate the Insights button from the Host, which is needed to remediate the Insights inventory. Otherwise, the system_id parameter in the result of your scan job is set to null and the Insights button will not appear.

Insights - scan job template

  1. Click Save when done.

  2. Click the launch icon to launch the scan job template.

Once complete, the job results display in the Job Details page.

Insights - scan job success

25.6. Remediate Insights Inventory

Remediation of an Insights inventory allows Tower to run Insights playbooks with a single click.

  1. Click the Inventories (inventories-icon) icon from the left navigation bar to access the Inventories page.

  2. In the list of inventories, click to open the details of your Insights inventory.

  3. Click the Hosts tab to access the Insights hosts that have been loaded from the scan process.

  4. Click to open the host that was loaded from Insights.

Notice the Insights tab is now shown on Hosts page. This indicates that Insights and Tower have reconciled the inventories and is now set up for one-click Insights playbook runs.

Insights - hosts tab

  1. Click Insights.

The screen below populates with a list of issues and whether or not the issues can be resolved with a playbook is shown.

Insights - host insights tab

  1. Scroll down to the bottom of the Insights inventory page, and click the Remediate Inventory button to update hosts in the inventory.

Insights - remediate inventory

Upon remediation, the New Job Template window opens. Notice the Inventory and Project fields are pre-populated.

Insights - maintenance plan template

Use this new job template to create a job template that pulls Maintenance Plans from Insights.

  1. Enter the appropriate details into the required fields, at minimum. Note the following fields requiring specific Insights-related entries:

  • Name: Enter the name of your Maintenance Plan.

  • Job Type: If not already populated, select Run from the drop-down menu list.

  • Inventory: This field is pre-populated with the Insights inventory you previously created.

  • Project: This field is pre-populated with the Insights project you previously created.

  • Playbook: Select a playbook associated with the Maintenance Plan you want to run from the drop-down menu list.

  • Credential: Enter the credential to use for this project or click the search button and select it from the pop-up window. The credential does not have to be an Insights credential.

  • Verbosity: Keep the default setting, or select the desired verbosity from the drop-down menu list.

Insights - maintenance plan template filled

  1. Click Save when done.

  2. Click the launch icon to launch the job template.

Once complete, the job results display in the Job Details page.