Viewing and managing system inventory


Red Hat Insights 1-latest

Using inventory to easily track and manage your infrastructure

Red Hat Customer Content Services

Abstract

This document helps Insights for Red Hat Enterprise Linux administrators to organize their system inventory into logical groups (called workspaces) and control User Access to systems.
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright's message.

Chapter 1. Inventory overview

Inventory provides a comprehensive view of all the systems in your organization, which allows you to easily track and manage your infrastructure. You can access inventory in two ways:

  • through the Hybrid Cloud Console, and
  • by the Managed inventory API

Systems must be registered with Red Hat to be visible in inventory. There are multiple ways to register with Red Hat. For more information about registering systems with Red Hat Insights, see the following resources:

Client Configuration Guide for Red Hat Insights.

Insights Analysis

When your system is registered with Red Hat Insights, Insights performs an initial analysis of the system. Status information, such as system state and whether a system is active, is stored in inventory. You can access additional details about the system from the Red Hat Insights > RHEL > Inventory page in the Hybrid Cloud Console. After the initial analysis is complete, Insights runs analyses daily, providing feedback to you and reporting system status to inventory.

Insights analysis results can include alerts that identify issues in your systems, and recommendations about how to resolve those issues.

Insights also monitors your systems for system staleness, and uses specific staleness criteria to flag systems that are not reporting regularly. If systems do not report after a specified period of time, Insights flags them for deletion.

1.1. Data governance

Red Hat Insights helps to identify and address operational and vulnerability risks, before they result in system downtime. This functionality requires that Insights collects small pieces of system metadata for processing and analysis. Here is how we ensure the security of your data:

  • Red Hat Insights collects only the minimum system metadata needed to analyze and identify issues for supported platforms.
  • Before data is sent to Red Hat, you have the option to inspect and redact your data.
  • Data is encrypted throughout the process, with a customizable collection schedule. Red Hat data collection rules are signed and the signature is verified before proceeding.
  • Only one uploaded data set is stored at a time for each cluster, host or instance.

1.1.1. Data obfuscation

You have full control over the data collected by Insights. It is possible to anonymize the data by obfuscating IP addresses and host names in the Insights client.

1.1.2. Data redaction

You can exclude specific data from the Insights client collection process, by using data redaction commands in the command line interface. This method can be used to ensure personally identifiable information (PII) is not collected. However, data redaction reduces the quantity and quality of system recommendations.

1.1.3. Data retention

The Insights client collects and uploads your data once a day with the default configuration. The collected data is kept 24 hours for analysis. Data is replaced by new uploads from the Insights client every day. Data is automatically deleted after 14 days if there is no upload from the Insights client.

Results from the analysis are retained for historical reporting purposes and might be used by Red Hat as input into feature enhancements.

Additional Resources

For more information on Red Hat data governance, see the Red Hat Insights data and application security page: Red Hat Insights data and application security

For more information on obfuscating data, see Red Hat Insights client documentation: Insights client data obfuscation

For more information on configuring a denylist, see Red Hat Insights client documentation: Insights client data redaction

1.2. Data collectors for inventory

Each system registered in inventory gets its data from one of many data collectors. Data collectors run on a regular cadence and synchronize their collected data with the Red Hat Hybrid Cloud Console.

A system can be reported by one or more collectors. When multiple collectors provide information for the same system, inventory uses a deduplication mechanism to merge the information. This process ensures that systems appear only once in inventory.

The following data collectors upload system information to the Red Hat Hybrid Cloud Console:

  • Red Hat Insights. Insights registers and aggregates system data. By default, it runs daily on each system and uploads the system data to the Red Hat Hybrid Cloud Console for processing. The data that Insights collects is used to formulate all the recommendations Insights provides.
  • Red Hat Subscription Manager (RHSM). The subscription-manager tool runs daily to provide a list of all systems in your organization that are registered with Red Hat. Note that unless Insights is also enabled, data collected by Subscription Manager alone does not provide recommendations.
  • Remote Host Configuration (rhc). The rhc client allows you to register systems to Insights and RHSM, and configure Insights connections for all RHEL systems in your organization. In addition, the rhc client makes it easy to find system issues, and to fix them with remediation playbooks generated by Insights.
  • Red Hat Discovery tool. Discovery tool scans systems for Red Hat software installations and provides a report to Red Hat Hybrid Cloud Console for inclusion in inventory. You will run this tool manually.
  • Red Hat Satellite. Satellite provides an integration with Red Hat Hybrid Cloud Console. When configured, Satellite uploads its inventory of registered systems daily and synchronizes it with the inventory application. This includes all systems registered with Satellite and Capsule servers.
Note

Data collected and reported by Subscription manager and Satellite alone will NOT result in analysis and recommendations. Red Hat Insights must also be enabled.

1.2.1. Identifying which data collector is reporting to inventory

You can determine which data collector(s) have reported for an individual system by visiting the Red Hat Hybrid Cloud Console:

Prerequisites

  • You have Inventory Hosts viewer access.

Procedure

  1. Navigate to the Red Hat Insights > RHEL > Inventory page.
  2. Click the system you want to view.
  3. You will notice that you are in the General information tab. Remain in that tab and scroll to the bottom of the page.
  4. Reference the Data collectors card at the bottom of the page. There you will see the data collector(s) Name, Status and Last upload details.
Note

You can also filter your systems by data collectors in the inventory Systems page. This is explained in Section 2.2, Refining your view of systems in inventory.

Additional Resources

Red Hat Insights client

Red Hat Satellite

Red Hat Subscription Manager (RHSM)

Getting started with the Subscriptions Service

Red Hat Discovery tool

Remote Host Configuration and Management (rhc)

Chapter 2. Assessing and filtering your inventory

Assessing and filtering your inventory will help you identify and eliminate security, operations, and business risks in your fleet.

2.1. Inventory Application Programming Interface (API)

Red Hat Insights provides a set of APIs that you can use to interact with specific Insights for Red Hat Enterprise Linux applications, to obtain system details and recommendations.

We have designed our APIs to ensure the security of your data. All Insights APIs are Representational State Transfer (REST) APIs. REST APIs are stateless. Statelessness means that servers do not save client data between requests. Our APIs also use token-based authentication, which provides granular control over access permissions and enhances security.

Review the following resources to learn more about how you can use the inventory API to locate information, enact edits, and automate repetitive tasks:

Additional Resources

For more information about Red Hat Insights API, see the Red Hat Insights API reference guide: API Catalog

For more information about getting started with Red Hat Insights API, see the Red Hat Insights API cheat sheet: Insights API cheat sheet

For more information about the inventory API, see Managed Inventory: Managed Inventory API

2.2. Refining your view of systems in inventory

There are several ways to refine your inventory view to help you focus on the issues and systems that matter the most. You can filter by Name, Status, Operating System, Data Collector, remote host configuration status, Last seen, Workspace, or Tags. Follow the procedure below to filter your systems:

Prerequisites

  • You have Inventory Hosts viewer access.

Procedure

  1. Navigate to Red Hat Insights > RHEL > Inventory page.
  2. Click the Name filter drop-down. Choose an option from the drop-down menu, such as Name, Status, Operating System, Data Collector, RHC status, Last seen, Workspace or Tags.
  3. Select additional filters within your query. For example, if you chose the Operating System filter, click Filter by operating system in the header to choose a specific version of RHEL.
  4. Click the checkbox next to the RHEL version you want to filter.
  5. Optional: To add multiple filters to your query, click an additional filter (such as Data Collector). A second drop-down appears to the right of the Data Collector filter, called Filter by data collector.
  6. Choose the desired data collector. This first filter then appears just below the header. If desired, choose a second filter. You can apply all 8 available filters to your query.
  7. Click Reset filters to clear your query.

Additional Resources

For information about global filters, see the following:

System filtering and groups

2.3. Deleting systems from inventory

When a system is obsolete or decommissioned, you might choose to remove it from inventory. Use the following procedure to do so:

Prerequisites

  1. You have Inventory Hosts administrator access.

Procedure

  1. Navigate to Red Hat Insights > RHEL > Inventory page.
  2. Check the box to the left of the system(s) you want to remove.
  3. Click the Delete button to the right of the filter. A Delete from Inventory confirmation dialog box appears.
  4. Click Delete to confirm this action.

A message box appears in the upper right corner of the screen, stating that the delete operation initiated. When the deletion is complete, a message box confirms that deletion was successful.

Caution

The selected system(s) will be removed from ALL console.redhat.com applications and services.

Note

A system might reappear in inventory if data collectors are uploading data from systems that are still registered and subscribed. Refer to the documentation for the specific data collector(s) to determine how to permanently unregister or unsubscribe.

Chapter 3. User access for RBAC in systems inventory

3.1. User Access for inventory

Red Hat uses role-based access control (RBAC) to manage User Access on the Red Hat Hybrid Cloud Console. You can use User Access to configure access and permissions in systems inventory.

Insights for Red Hat Enterprise Linux provides a set of predefined roles. Depending on the application, the predefined roles for each supported application can have different permissions that are tailored to that application.

3.1.1. How User Access works

The User Access feature is based on managing roles, rather than on individually assigning permissions to specific users. In User Access, each role has a specific set of permissions. For example, a role might allow read permission for an application. Another role might allow write permission for an application.

You create groups that contain roles and, by extension, the permissions assigned to each role. You also assign users to those groups. This means that each user in a group is assigned the permissions of the roles in that group.

By creating different groups and adding or removing roles for that group, you control the permissions allowed for that group. When you add one or more users to a group, those users can perform all actions that are allowed for that group.

Insights for Red Hat Enterprise Linux provides two default access groups for User Access:

  • Default admin access group. The Default admin access group is limited to Organization Administrator users in your organization. You cannot change or modify the roles in the Default admin access group.
  • Default access group. The Default access group contains all authenticated users in your organization. These users automatically inherit a selection of predefined roles.
Note

You can make changes to the Default access group. However, when you do so, the group name automatically changes to Custom default access.

3.1.2. Inventory predefined roles and permissions

Role NameDescriptionPermissions

Inventory administrator

You can perform any available operation against any Inventory resource.

inventory:*:* (* denotes all permissions on all resources)

Workspaces administrator

You can read and edit Workspaces data.

inventory: groups: write and inventory: groups: read

Workspaces viewer

You can read Workspaces data.

inventory: groups: read

Inventory Hosts administrator

You can read and edit Inventory Hosts data.

inventory: hosts: write and inventory: hosts: read

Inventory Hosts viewer

You can read Inventory Hosts data.

inventory: hosts: read

Additional Resources

Role Based Access Control

3.2. User access to Workspaces

Workspaces allow you to group systems in your inventory together into logical units, such as location, department, or purpose. Each system can belong to only one Workspace.

Workspaces also support role-based access control (RBAC). Using RBAC enables you to set custom permissions on Workspaces according to user role.

The Workspace administrator User Access role allows you to create Workspaces. This role is automatically included in the Default Access group and cannot be removed from it. However, users with this role can modify any Workspace. Provide this role only to those users who are entitled to access the entire system inventory.

For a user to be able to use Workspaces and RBAC to restrict access to specific systems, that user must either be a member of the Default Access group, or have both the Workspace administrator and the User Access Administrator roles.

Workspace users have group-level RBAC permissions. Custom permissions include the following:

  • inventory:groups:read

    • View Workspace details page
  • inventory:groups:write

    • Rename the Workspace
    • Add systems to the Workspace
  • Remove systems from the Workspace
Note

A user cannot view the systems inside the Workspace without inventory:hosts:read permissions.

Systems users have system-level RBAC permissions. They can perform the following Workspace operations:

  • inventory:hosts:read

    • View all the systems in the Workspace and their details, or view ungrouped systems
    • View information about the systems for other Insights services
  • inventory:hosts:write

    • Rename the system
    • Delete the system

3.2.1. Managing user access to Workspaces

Note

If you do not have access to Workspaces, navigating to Inventory > Workspaces shows the message Workspace access permissions needed.

Be aware that you can still view the Workspace name assigned to the system for which you have read access, even if you do not have access to the Workspace itself. To view the Workspace that contains the system, you need to have the Workspaces Viewer role, or have Workspace view permissions assigned.

Important

Before making changes in the RBAC configuration, review the list of known limitations in the User Scenarios section.

For more information about managing user access, assigning roles, and adding members to user access groups, see User Access Configuration Guide for Role-based Access Control (RBAC).

3.2.1.1. Creating a custom User Access role

Use the User Access application to configure user access for your Workspace.

To create a custom role:

  1. Click the Settings icon (⚙) in the top right corner, and then select User Access to navigate to the User Access application. The Identity & Access Management main page displays.
  2. In the left navigation menu, click Roles.
  3. Click Create role. The Create Role wizard displays.
  4. Select whether you want to create a new role, or copy an existing role.

    1. To create a new role, select create a role from scratch.
    2. To copy an existing role, select Copy an existing role. A list of roles appears. Select the role you want to copy, and then click Next.
  5. Name the new role. If desired, add a description.
  6. Click Next. The Add permissions page displays.
  7. The Applications filter displays by default. Click the Filter by application drop-down and select inventory to display all the available inventory permissions.

    The four inventory permissions include:

    • inventory:hosts:read - Allows users to view systems (needed to view systems both inside and outside the Workspace).
    • inventory:hosts:write - Allows users to Rename or Delete systems.
    • inventory:groups:read - Allows users to view Workspaces, and general info (not including systems in it).
    • inventory:groups:write - Allows users to edit Workspace membership (add and remove systems from Workspaces).
  8. Select the inventory permissions that you need. Here are some examples:

    1. To give a user full access to the Workspace and all systems in that Workspace, select all four permissions.
    2. To give a user full access to the systems inside a Workspace without granting Workspace editing access, select inventory:hosts:read, inventory:hosts:write, and inventory:groups:read, but do not select inventory:groups:write.
    3. To give a user full access to ungrouped systems, select all four permissions (ungrouped systems are considered a Workspace).
  9. Click Next. The Define Workspace access page displays.
  10. Click the drop-down arrow next to each permission in the list, and then select the Workspaces you want to apply to those permissions. You must select at least one Workspace for each permission.
  11. Click Next. The Review details page displays.
  12. Review the permissions for the custom role and click Submit.

Repeat this process for each Workspace or for each group of users that requires specific Workspace access.

Example scenarios

These examples describe the permissions you assign to users in specific custom roles.

  • To allow users to only see systems in specific Workspaces, but to not see systems that do not belong to any Workspaces, select only those Workspaces.
  • To allow users to see systems in specific Workspaces as well as any systems that do not belong to any Workspaces, select those Workspaces for all permissions and select Ungrouped systems for inventory:hosts permissions.
  • To allow users to see everything in the inventory, you do not need to create a custom role.
  • To give a group of system administrators the same access to Workspaces A, B, and C, create a single custom role and assign permissions to those three Workspaces. However, if you want to give different users access to different Workspaces, create a separate custom role for each Workspace.
3.2.1.2. Assigning custom roles

To assign custom roles to a user or group of users, create a User Access group. The users inside a group receive the roles assigned to that group.

  1. At the top right of the screen, click the Settings icon (the Settings icon (⚙)), and then click User Access.
  2. In the left navigation menu, click User Access > Groups.
  3. Click Create group. The Create group wizard displays the Name and description page.
  4. Add a group name. If desired, add a description for the group.
  5. Click Next. The Add roles page displays.
  6. Select the custom role you created, and then click Next. The Add members page displays.
  7. Select the users to whom you want to assign the custom role.
  8. Click Next. The Add service accounts page appears.
  9. Optional. If you want to assign a service account or accounts to the selected users, select one or more service accounts from the list.
  10. Click Next. Review the details of your selections and click Submit.

Repeat this procedure for each custom role that you want to assign to one or more users.

3.2.1.3. Configuring user access

After you create and assign a custom role, all users in your organization still have full access to inventory because they still have the Inventory Hosts administrator role assigned. This allows any user to view and edit all hosts. The Default Access workspace assigns this role to all users in your organization by default.

To limit organization users' access to only the Workspaces/systems defined in your custom roles, edit the Default Access Workspace to remove the Inventory Hosts administrator role.

  1. At the top right of the screen, click the Settings icon (the Settings icon (⚙)), and then click User Access.
  2. In the left navigation menu, click User Access > Groups. The list of User access groups displays.
  3. Click the Default access group. The list of roles displays.
  4. Select the checkbox for the Inventory Hosts administrator role.
  5. Click the options icon (⋮) at the far right of the row. The Remove role option appears.
  6. Click Remove role. The Remove role dialog box appears.
  7. Click the Remove role button. If you have never edited the Default Access Workspace before, a warning message displays.
  8. Select the I understand, and I want to continue checkbox, and then click Continue.
3.2.1.4. Configuring Inventory Hosts administrator access

After you edit the Default Access Workspace, you might want to create a new User Access group of users who should have Inventory Hosts administrator permissions.

  1. At the top right of the screen, click the Settings icon (the Settings icon (⚙)), and then click User Access.
  2. In the left navigation menu, click User Access > Groups. The list of Workspaces displays.
  3. Click Create group. The Create Group wizard appears.
  4. Add a name for the group. If desired, add a description.
  5. Click Next. The Add roles page displays.
  6. Select the Inventory Hosts administrator role from the list of roles.
  7. Click Next. The Add members page displays.
  8. Select the users to whom you want to assign the role.
  9. Click Next. The Add service accounts page appears.
  10. Optional. If you want to assign a service account or accounts to the selected users, select one or more service accounts from the list.
  11. Click Next. The Review details page displays.
  12. Review the details of your selections, and click Submit.

After you have finished configuring access, specific users within your organization have full inventory access, and others have limited inventory access.

3.3. User scenarios

This section contains two example scenarios that illustrate the features of Workspaces. These scenarios follow a procedure format, so that you can follow the required steps and test them, if desired.

3.3.1. Scenario 1: Two different IT teams must manage their systems with Insights

In this scenario, two different IT teams working for the same company share the same Insights organization within their Red Hat account.

  • Each IT team must have complete control of their systems in the Red Hat Hybrid Cloud Console, but should not be able to see or modify the systems belonging to the other team.
  • All users within the same team have the same level of access on both their Workspaces and their systems. Access levels can be adjusted as needed.
  • Regular users of both IT teams will not be able to see or modify systems that are not part of any Workspaces.
  • Organization administrators, or anyone with Workspace administrator and Inventory Hosts administrator roles, have access to the entire inventory. Any other users without those roles cannot access the entire inventory.
3.3.1.1. Initial phase

By default, organization administrators (who are members of the Default administrator access group) on the Red Hat Hybrid Cloud Console always have read/write access to all Workspaces and read/write access to all systems, regardless of how permissions are defined for the Workspace objects and systems assigned to them.

These users are the only ones who may configure user access for Workspaces. If any regular users need to manage user access, the administrators can grant them Workspace admin and Inventory Hosts admin roles separately.

By default, users who are not Organization administrators are assigned the Inventory Hosts administrator role from the Default access group. The Default access group gives these users inventory:hosts:read and inventory:hosts:write access across the entire inventory. Those permissions grant read and write permissions on all systems and all Workspaces.

Note

For more information about the Default access group, see The Default access group.

3.3.1.2. Restricting access

Prerequisites

  • You are a member of the Default administrator access group.

Step 1: Create the Workspaces

First, create two separate Workspaces. (This example shows two Workspaces, but you may create as many as you need).

  • Workspace 1: IT team A - Systems
  • Workspace 2: IT team B - Systems

Step 2: Add systems to Workspaces

Now that the Workspaces have been created, add systems to them. Click in each Workspace and select Add systems.

At this stage, all the users still have access to all systems, regardless of the Workspaces they are in. This is because they still have the Inventory hosts administrator role, which allows them to see all systems, whether or not they are grouped into Workspaces.

Step 3: Create custom roles

To customize access for different Workspaces, create custom roles for those Workspaces. To create a custom role, navigate to User Access > Roles, and click Create role. A wizard opens. Name your role (For example, IT Team - A Role), and click Next.

Step 3a: Select permissions to add to the custom role

The wizard displays the Add permissions step. This step contains four inventory permissions options. Select them depending on the level of access you want to grant.

For full access to the Workspace and its systems, select:

  • inventory:groups:read
  • inventory:groups:write
  • inventory:hosts:read
  • inventory:hosts:write

After selecting permissions, click Next. You can adjust the permissions as needed.

Step 3b: Assign permissions to selected Workspaces

In this step, choose the Workspace(s) to which you want to grant permission. This example shows how to select the Workspace that corresponds to the current role. For example, create the role IT team A - Role, and specify the Workspace IT team A - Systems for each permission.

Review the details and click Submit.

Repeat the steps in this section to create a second custom role called IT team B - Role and select the IT team B - Systems Workspace.

Note

You can grant access to systems that are not part of any Workspace to one or both IT teams. To add those systems, add the Ungrouped systems that appear in the Group definition of the host permissions to your custom role.

Step 4: Create User Access groups to assign custom roles to users

Now that the custom roles are created, create User Access groups to assign the custom roles to users.

To create a new group, navigate to User Access > Groups and click Create group. Name the group, select the newly created role, and select the users to whom you want to give the role.

For example, two IT groups have the following permissions:

  • IT team A - user group
  • IT team A - role
  • IT team B - user group
  • IT team B - role

Step 5: Remove Inventory Hosts administrator role from the Default Access group

At this stage, despite all the steps taken above, all users still have access to all systems, regardless of the Workspaces they are in. This is because they still have the Inventory Hosts administrator role, which allows them to see all systems, whether or not they are grouped into Workspaces.

To limit access to systems, navigate to User Access > Groups and select the Default Access group. Remove the Inventory Hosts administrator role from this group.

If the users are also members of additional User Access Groups, make sure to review and remove the Inventory Hosts administrator role from those groups as needed.

Once the role has been removed, the User Access controls behave as expected: Users given custom roles to limit their views to certain Workspaces and systems only see those Workspaces and systems.

3.3.1.3. Adjustment considerations
  • If you have more than two IT groups, you can create as many custom roles and user groups as you need.
  • If you are trying to grant the same people the same access to multiple Workspaces, you can select more than one Workspace to grant permissions within the same custom role.
  • You can grant access to systems that are not part of any Workspace. Add the Ungrouped systems in the Group definition of the host permissions to the custom role.
  • Remember that as long the Inventory hosts administrator role is still in the Default Access group, all users who have that role still have access to everything.
  • If you do not select Ungrouped systems in your custom roles, users with those roles will not be able to see any ungrouped systems once you remove the Inventory Hosts administrator permission from the Default access group.

3.3.2. Scenario 2: Access to ungrouped systems

In this example, an admin wants to give a group of users access to ungrouped systems, but not to grouped systems.

Step 1: Create a custom role

  1. Navigate to User Access > Roles and click Create role. The Create Role wizard displays.
  2. Set the role name and description and click Next.
  3. Add the inventory:hosts permissions and click Next.

Configure both of the permissions to apply to the Group definition named Ungrouped systems. Click Next.

Review the details of the role and click Submit.

Step 2: Add the custom role to an RBAC group

  1. Once you create the custom role, navigate to User Access > Groups and click Create Group to create a User Access (RBAC) group.
  2. Name the group, select the new custom role, and select the users to whom you want to assign this role.
Note

These steps only work when the users do not have the Inventory Hosts administrator role assigned from the Default Access group. To check this, navigate to User Access > Groups and click on the Default Access group at the top. If that role is in the group, remove it, because that role gives users access to the whole inventory - including both ungrouped and grouped systems.

After you remove the role, the selected set of users only has access to ungrouped systems in your inventory.

3.3.3. Known limitations

  • Users who are Organization Administrators (members of the Default admin access group) will always have full access to systems and Workspaces.
  • A user without permission on the system will not be able to add it to a Remediation. However, if an existing Remediation with active systems was created in the past, the user will still be able to run it, even if the permissions have been removed on that system for the current user.
Note

Before enabling Workspaces in your organization, review your Notifications configuration to ensure that only appropriate groups of users are configured to receive Email notifications. If you do not review your Notifications configuration, users might receive alerts triggered by systems outside of their Workspace permission scope.

Additional Resources

Chapter 4. Exporting inventory data

You can use the export service for inventory to export a list of systems and their data from your Insights inventory. You can specify CSV or JSON as the output format. The export process takes place asynchronously, so it runs in the background. The service is available in both the Insights UI and through the export service API.

The exported content includes the following information about each system in your inventory:

  • host_id
  • fqdn (Fully Qualified Domain Name)
  • display_name
  • group_id
  • group_name
  • state
  • os_release
  • updated
  • subscription_manager_id
  • satellite_id
  • tags
  • host_type
Note

The export service currently exports information about all systems in your inventory. Support for filters will be available in a future release.

The Inventory export service works differently from the export function in other services, such as Advisor. Some of the differences are:

  • Inventory export operates asynchronously
  • Exports the entire inventory to one continuous file (no pagination in the export file)
  • Retains generated files for 7 days
  • Uses token-based service accounts for authorization if using the export service API
Important

Your RBAC permissions affect the system information you can export. You must have inventory:hosts:read permission for a system to export system information.

4.1. Inventory data files

The inventory export process creates and downloads a zip file. The zip file contains the following files:

  • id.suffix — the export data file, with the file name format of id.json for JSON files, or id.csv for CSV files. For example: f26a57ac-1efc-4831-9c26-c818b6060ddf.json
  • README.md — the export manifest for the JSON/CSV file, which lists the downloaded files, any errors, and instructions for obtaining help
  • meta.json — describes the export operation — requestor, date, Organization ID, and file metadata (such as the filename of the JSON/CSV file)

4.2. Exporting system inventory from the Insights UI

You can export inventory data from the Insights UI. The inventory data export service works differently from the export service for other Insights services, such as Advisor.

Prerequisites

  • RBAC permissions for the systems you want to view and export

    • Inventory:hosts:read (inventory:hosts:read * for all systems in inventory)
  • A User Access role for workspaces. For more information about User Access roles, see User access to workspaces.

Procedure

  1. Navigate to Inventory > Systems. The list of systems displays.
  2. Click the Export icon next to the options icon (⋮). The drop-down menu displays.
  3. Select CSV or JSON as the export format. A status message displays: Preparing export. Once complete, your download will start automatically.
Systems inventory export showing the export icon in the UI

When the download completes, a browser window automatically opens to display the results.

If you remain on the Systems page after requesting the download, status messages from Insights appear with updates on the progress of the export operation.

4.3. Exporting system inventory using the export API

You can use the Export API to export your inventory data. Use the REST API entry point: console.redhat.com/api/export/v1.

The Export Service API supports the GET, POST, and DELETE HTTP methods. The API offers the following services:

  • POST /exports
  • GET /exports
  • GET /exports/id
  • DELETE /exports/id
  • GET /exports/id/status

The API works asynchronously. You can submit the POST /exports request for export from the Export API and receive a reply with an ID for that export. You can then use that ID to monitor the progress of the export operation with the GET /exports/id/status request. When the generated export is complete, you can download it (GET /exports/id) or delete it (DELETE /exports/id).

Successful requests return the following responses:

  • 200 — Success
  • 202 — Successfully deleted (for the DELETE method)

For more information about the operations, schemas, and objects, see Consoledot Export Service.

4.3.1. Requesting the system inventory export

Before you can request the exported data file, you need to obtain a unique ID for the download. To obtain the ID, issue a POST request. The server returns a response that includes the ID. Use the ID in any request that requires the id parameter, such as GET /exports/id.

Prerequisites

  • Token-based service account with the appropriate permissions for your systems
  • RBAC permissions for the systems you want to view and export

    • Inventory:hosts:read (inventory:hosts:read * for all systems in inventory)
  • A User Access role for workspaces. For more information about User Access roles, see User access to workspaces.

Procedure

  1. Create a request for the export service, or use this sample request code:

    {
     "name": "Inventory Export",
     "format": "json",
     "sources": [
         {
           "application": "urn:redhat:application:inventory",
           "resource": "urn:redhat:application:inventory:export:systems"
         }
      ]
    }
    Note

    You can request CSV or JSON as your export format.

  2. In the Hybrid Cloud Console, navigate to the API documentation: https://console.redhat.com/docs/api/export .

    Note

    You can use the API documentation to experiment and run queries against the API before writing your own custom client and/or use the APIs in your automation.

  3. Select POST /export.
  4. Remove the existing sample code in the Request Body window and paste the request code into the window.
  5. Click Execute. This request initiates the export process. The curl request and server response appear, along with the result codes for the POST operation.
  6. Look for the id field in the server response. Copy and save the string value for id. Use this value for id in your requests.
  7. Optional. Issue the GET /exports request. The server returns the curl request, request URL, and response codes.
  8. Optional. To request the status of the export request, issue the GET /exports/id/status request.
  9. When the export has completed, issue the GET /exports/id request, with the ID string that you copied in place of id. The server returns a link to download the export file (the payload).
  10. Click Download File. When the download completes, a notification message appears in your browser.
  11. Click the browser notification to locate the downloaded zip file.
Note

The server retains export files for 7 days.

4.3.2. Deleting export files

To delete exported files, issue the DELETE /exports/id request.

Additional resources

4.3.3. Automating inventory export using Ansible playbooks

You can use an Ansible playbook to automate the inventory export process. The playbook is a generic playbook for the export service that uses token-based service accounts for authentication.

Procedure

  1. Navigate to https://github.com/jeromemarc/insights-inventory-export .
  2. Download the inventory-export.yml playbook.
  3. Run the playbook. The playbook does everything from requesting the export id, to requesting download status, to requesting the downloaded payload.

Additional resources

For more information about service accounts, refer to the KB article: Transition of Red Hat Hybrid Cloud Console APIs from basic authentication to token-based authentication via service accounts.

4.3.4. Using the inventory export service for multiple Insights services

You can use the inventory export service for multiple services, such as inventory and notifications. To request multiple services, include source information for each service that you want to request in your POST /exports request. For example:

{
  "name": "Inventory Export multiple sources",
  "format": "json",
  "sources": [
    {
      "application": "urn:redhat:application:inventory",
      "resource": "urn:redhat:application:inventory:export:systems",
      "filters": {}
    },
    {
      "application": "urn:redhat:application:notifications",
      "resource": "urn:redhat:application:notifications:export:events",
      "filters": {}
    }
  ]
}

The POST /exports request returns a unique id for each export.

The GET /exports request returns a zip file that includes multiple JSON or CSV files, one for each service that you request.

Chapter 5. Systems lifecycle in the inventory application

A system is a Red Hat Enterprise Linux (RHEL) host that is managed by the Red Hat Insights inventory in the Red Hat Hybrid Cloud Console. System activity is automatically monitored by Red Hat. All systems registered with inventory follow a lifecycle that includes the following states: fresh, stale, and stale warning. The state that a system resides in depends on the last time it was reported by a data collector to the inventory application. Systems are automatically deleted from inventory if they do not report within a given time frame. The goal of the deletion mechanism is to maintain an up-to-date, accurate view of your inventory.

Here is a description of each state:

Fresh

The default configuration requires systems to communicate with Red Hat daily. A system with the status of fresh, is active and is regularly reported to the inventory application. It will be reported by one of the data collectors described in section 1.2. Most systems are in this state during typical operations.

Stale

A system with the status of stale, has NOT been reported to the inventory application in the last day, which is equivalent to the last 26 hours.

Stale warning

A system with the status of stale warning, has NOT been reported to the inventory application in the last 14 days. When reaching this state, a system is flagged for automatic deletion. Once a system is removed from inventory it will no longer appear in the inventory application and Insights data analysis results will no longer be available.

5.1. Determining system state in inventory

There are two ways to determine which state a sysem is currently in. Use this procedure to identify system state on the Systems page:

Prerequisites

  • You have Inventory Hosts viewer access.

Procedure

  1. Navigate to the Red Hat Insights > RHEL > Inventory page.
  2. Click the Filter drop down list, select Status.
  3. Click the Filter by status dropdown and select the state(s) you want to include in your query.
  4. Click Reset filters to clear your query.

Alternatively, you can discover system(s) state(s) on the Dashboard:

Prerequisites

  • You have Inventory Hosts administrator access.

Procedure

  1. Navigate to the Red Hat Insights for Red Hat Enterprise Linux dashboard page.
  2. Look at the top left of the screen and you will see the total number of Systems registered with Insights for Red Hat Enterprise Linux.
  3. Look to the right of the total number and you will see the number of stale systems and the number of systems to be removed.
  4. Click the blue stale systems link or the systems to be removed link, if applicable, to navigate to the inventory page and view more granular details.

5.1.1. Modifying system staleness and deletion time limits in inventory

By default, system states have the following time limits:

  • Systems are labeled stale if they are not reported in 1 day. A warning icon appears of the top of the Systems page in the Last seen: field.
  • Systems are labeled stale warning if they are not reported within 7 days. In this case the Last seen: field turns red.
  • Systems that are not reported in 14 days are deleted. git st

There are situations where a system is offline for an extended period of time, but is still being used. For example, test environments are often kept offline except when testing. Edge devices, submarines or Internet of Things (IoT) devices, can be out of range of communication for extended periods of time. You can modify the system staleness and deletion time limits (for both conventional and immutable systems), to accommodate these unique situations. Do this so that systems that are offline but still active are not deleted. Note that any changes that you make to these limits affect all of your conventional or immutable systems.

Prerequisites

  • You are logged into the Red Hat Hybrid Cloud Console as a user with the Organization staleness and deletion administrator role.

Procedure

  1. On the Red Hat Hybrid Cloud Console main page, click RHEL in the Red Hat Insights tile.
  2. In the left navigation bar, click Inventory > System Configuration > Staleness and Deletion. The Staleness and Deletion page displays the current settings for system staleness, system stale warning, and system deletion for conventional systems.
  3. Optional: To manage the staleness and configuration settings for edge (immutable) systems, select the Immutable (OSTree) tab.
  4. To change these values, click Edit. The drop-down arrows next to each value are now enabled.
  5. Click the arrow next to the value that you want to change and then select a new value.

    Note

    The system stale warning value must be less than the system deletion value.

  6. Optional: To revert to the default values for the organization, click Reset.
  7. Click Save to save your changes.

    Note

    If you set the system deletion maximum time to less than the current maximum time, systems that have been stale for longer than then new maximum time will be deleted.

Chapter 6. Workspaces

Workspaces allow you to select specific systems and group them together. You can view and manage the individual Workspaces and the system membership of each group. In addition, you can filter your system lists across applications by Workspaces. You can also manage user access to specific Workspaces to enhance security.

Workspaces have the following characteristics:

  • Workspaces are only for systems.
  • You cannot add Workspaces as children of another Workspace.
  • Each system can belong to only one Workspace.
  • Using Workspaces is not mandatory; systems that are not assigned to specific Workspaces can remain unassigned.

Additional resources

6.1. Creating Workspaces

Prerequisites

  • You must be an Organization administrator (member of the Default administrator access group) or have the Workspace administrator role.

Procedure

  1. On the Red Hat Hybrid Cloud Console, navigate to Inventory.
  2. Click the Inventory drop-down menu and select Workspaces.
  3. Click Create Workspace. The Create Workspace dialog box displays.
  4. Type a name for the Workspace in the Workspace name field. Names can consist of lowercase letters, numbers, spaces, hyphens (-), and underscores (_).
  5. Click Create. A Workspace created message displays, and the new group appears in the list of Workspaces.

6.2. Adding systems to a newly created Workspace

Note

Each system can belong to only one Workspace. In the current release of Workspaces, a system cannot be reassigned to a different group in a single step. You must first remove the system from its current group, and then assign it to a new group.

Prerequisites

  • Organization Administrator access to Insights for Red Hat Enterprise Linux, or Workspaces administrator permissions to the group, or both inventory:groups:write and inventory:groups:read permissions to the group

Procedure

  1. On the Red Hat Hybrid Cloud Console, navigate to Inventory.
  2. Select Workspaces.
  3. Click the name of the group to which you want to add systems. A page for Workspaces displays with the name of the Workspace and two tabs, Systems and Group Details.
  4. On the Systems tab, click Add systems. The Add systems dialog box displays and shows the systems available for you to view in inventory.
  5. Select the systems you want to add to the Workspace.

    Note

    If you select a system that already belongs to another Workspace, a warning message displays: One or more of the selected systems already belong to {a workspace}. Make sure that all the systems you have selected are ungrouped, or you will not be able to proceed.

  6. When you have finished selecting systems, click Add systems. The Workspaces page displays and includes the systems you added to the group.

6.2.1. Adding a system and creating a group from the Inventory systems page

Prerequisites

  • Organization administrator access to Insights for Red Hat Enterprise Linux, or Workspace administrator permissions to the group, or both inventory:groups:write and inventory:groups:read permissions to the group

Procedure

  1. On the Red Hat Hybrid Cloud Console, navigate to Inventory. The list of systems in your inventory appears.
  2. Locate the system that you want to add.
  3. Click the More options icon (⋮) on the far right side of the system listing.
  4. Select Add to Workspace from the pop-up menu. The Add to Workspace dialog box displays.
  5. Click Create a new Workspace. The Create Workspace dialog box displays.
  6. Type a name for the new group in the Name field and click Create.

The Inventory page appears and displays a status (success or failure) message.

6.3. Removing systems from the Workspace

You can remove systems from the Workspace from two pages in the Red Hat Hybrid Cloud Console: the Workspaces page and the Systems page.

6.3.1. Removing systems from the Workspace using the Workspaces page

Prerequisites

  • You must be an Organization administrator (member of the Default admin access group), or have the Workspace administrator role, or have the inventory:group:write permissions for that particular Workspace.

Procedure

  1. On the Red Hat Hybrid Cloud Console, navigate to Inventory.
  2. Click the Inventory drop-down menu and select Workspaces. The Workspaces page displays.
  3. Select the Workspace that contains the systems that you want to remove.
  4. Locate the system that you want to remove from the Workspace.
  5. Click the More options icon (⋮) on the far right side of the system listing.
  6. Select Remove from Workspace from the pop-up menu. The Remove from Workspace? dialog box displays.
  7. Optional: To remove multiple systems from the Workspace at once, select each system you want to remove, and then select Remove from Workspace from the More options menu (the options icon (⋮)) in the toolbar.
  8. Click Remove.

The Workspace page displays and shows the updated Workspace with a status (success or failure) message.

6.3.2. Removing systems from the Workspace using the Systems page

Prerequisites

  • Organization administrator access to Insights for Red Hat Enterprise Linux, or Workspace administrator permissions to the Workspace, or both inventory:groups:write and inventory:groups:read permissions to the Workspace

Procedure

  1. On the Red Hat Hybrid Cloud Console, navigate to Inventory.
  2. Click the Inventory drop-down menu and select Systems. The Systems page displays.
  3. Locate the system that you want to remove from the Workspace.
  4. Click the More options icon (⋮) on the far right side of the system listing.
  5. Select Remove from Workspace from the pop-up menu. The Remove from Workspace? dialog box displays.

    Note

    If any of the systems you selected do not belong to any Workspace, the Remove from Workspace option remains disabled. Make sure that you select only systems that belong to the Workspace.

  6. Optional: To remove multiple systems from the Workspace, select each system you want to remove, and then select Remove from Workspace from the More options (the options icon (⋮)) menu.
  7. Click Remove.

The Systems page displays and shows a status (success or failure) message.

6.4. Renaming the Workspace

Prerequisites

  • You must be an Organization administrator (member of the Default Administrator access group), or have the Workspace administrator role, or have the inventory:group:write permissions for that particular Workspace.

Procedure

  1. On the Red Hat Hybrid Cloud Console, navigate to Inventory.
  2. Click the Inventory drop-down menu and select Workspaces. The Workspaces page displays.
  3. Click the Workspace actions drop-down menu in the upper right corner of the Workspaces page.
  4. Select Rename from the drop-down menu. The Rename Workspace dialog box displays.
  5. Type the new name into the Name field, and click Save.
  6. The Workspaces page shows the renamed Workspace in the list of Workspaces.

6.5. Deleting the Workspace

Note

Before you delete a Workspace, make sure that the Workspace does not contain any systems. You can only delete empty Workspaces. If you attempt to delete a Workspace that still contains systems, Insights returns a warning message.

Prerequisites

  • You must be an Organization administrator (member of the Default admin access group), or have the Workspace administrator role, or have the inventory:group:write permissions for that particular Workspace.

Procedure

  1. On the Red Hat Hybrid Cloud Console, navigate to Inventory.
  2. Click the Inventory drop-down menu and select Workspaces. The Workspaces page displays.
  3. Click the options icon (⋮) on the far right side of the listing for the group you want to delete.
  4. Select Delete from the pop-up menu. The Delete Workspace dialog box displays.
  5. Select the checkbox to acknowledge that the delete operation cannot be undone. Click Delete.

The Workspaces page shows an updated list of Workspaces and a status (success or failure) message.

Note

You can also delete the Workspace from within the page for the Workspace itself. Navigate to the Workspace and click the Actions drop-down menu, and then select Delete.

Chapter 7. Configuring notifications for inventory events

The Inventory service triggers three types of events:

  • New system registered
  • System deleted
  • Validation error

The New system registered and System deleted events trigger when you register a new system in inventory, or when a system is removed from inventory (either manually or when it becomes stale and Insights automatically removes it).

Validation error events trigger when data in a payload from insights-client is not valid (corrupted data, incorrect values, or other issues). The validation process follows these steps:

  • insights-client runs on the system and generates a payload.
  • insights-client uploads the payload to the Hybrid Cloud Console.
  • The Hybrid Cloud Console receives the payload and validates it. The validation event triggers at this step. A validation error means that the payload cannot be processed, and that the console and Insights services cannot use its data.

You can configure notifications for these events using the Notifications service in the Red Hat Hybrid Cloud Console. The Notifications service enables you to configure responses to these events for your account. You can send email notifications to groups of users, or you can forward events to third-party applications, such as Splunk, ServiceNow, Event-Driven Ansible, Slack, Microsoft Teams, or Google Chat. You can also forward notifications, using a generic webhook with the Integrations service.

Note

To receive Notifications emails, users must subscribe to email notifications in their user preferences. Users may choose to receive each email notification individually, or they may subscribe to a daily digest email. For more information, refer to Configuring user preferences for email notifications.

The New system registered and System deleted events are particularly useful for driving automation, and for integrating Red Hat Insights into your operational workflows. For example, you can configure these events to automatically launch compliance or malware checks, validate systems assignments to Workspaces, update external CMDB records, or continuously monitor your RHEL environment.

7.1. Setting up organization notifications for inventory events

Note

Make sure that you configure third-party system integrations in the Hybrid Cloud Console, as well as any behavior groups that should receive inventory notifications. For more information about third-party system integrations, refer to Integrating the Red Hat Hybrid Cloud Console with third-party applications.

Prerequisites

  • You are logged in to the Red Hat Hybrid Cloud Console as a Notifications Administrator.

Procedure

  1. Navigate to Settings > Notifications > Configure Events.

    Configure Events screen
  2. In the Configuration tab, select the Service filter.
  3. Click Filter by service, and then select Inventory from the drop-down list. The inventory events appear in the list of events.
  4. Select the event type you want to configure (for example, New system registered).
  5. To configure the event type, click the Edit (pencil) icon at the far right of the event type. A drop-down list displays with the list of available behavior groups configured in your organization.
  6. Select the checkboxes next to the behavior groups you want to configure for the Inventory event type.
  7. When you have finished selecting behavior groups, click the checkmark next to the list of behavior groups to save your selections.

Additional resources

For more information about behavior groups, refer to Configuring notifications on the Red Hat Hybrid Cloud Console.

7.2. Setting up user email notifications for inventory events

Note

Make sure to configure email preferences for each user to receive email notifications. For more information about how to set up user preferences, refer to Configuring user preferences for email notifications.

Prerequisites

  • You are a member of a user group that receives email notifications as part of a behavior group.
  • The behavior group is configured to trigger email notifications for your systems and to send those notifications to the user group to which you belong.

Procedure

  1. Navigate to Settings > Notifications > Notification Preferences.

    Inventory notifications options
  2. Select Inventory from the list of services. The list of available notifications for Inventory displays.
  3. Click the checkbox next to each type of notification you want to receive, or click Select All to receive all notifications for all Inventory events.
  4. Click Save.
Note

Configuring instant notifications might result in a large volume of email messages.

Providing feedback on Red Hat documentation

We appreciate and prioritize your feedback regarding our documentation. Provide as much detail as possible, so that your request can be quickly addressed.

Prerequisites

  • You are logged in to the Red Hat Customer Portal.

Procedure

To provide feedback, perform the following steps:

  1. Click the following link: Create Issue
  2. Describe the issue or enhancement in the Summary text box.
  3. Provide details about the issue or requested enhancement in the Description text box.
  4. Type your name in the Reporter text box.
  5. Click the Create button.

This action creates a documentation ticket and routes it to the appropriate documentation team. Thank you for taking the time to provide feedback.

Legal Notice

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.