How to automate the process of assigning systems to groups/workspaces in Insights?

Resolution

The Managed Inventory APIs can be used to manage inventory groups/workspaces (create, read, update, delete) and automate the process of assigning systems to a group/workspace.

• Authenticating with a Service Account:

To access these APIs securely, use a service account with OAuth2 client credentials to obtain a short-lived access token. This token is then used to authorize API requests.

Note: Basic authentication was retired Dec 31, 2024 and is no longer supported. All integrations should use service account token-based authentication.

• Required permissions

Your service account must be granted specific permissions to access and manage inventory and workspace data:
- inventory:hosts:read
- inventory:hosts:write
- inventory:groups:read
- inventory:groups:write

These permissions can also be granted by assigning built-in roles such as:
- Inventory Hosts viewer
- Inventory Hosts administrator

You can assign these permissions or roles to your service account in the User Access section of the Red Hat Hybrid Cloud Console.

• Getting an Access Token

Use the following command to request an access token from Red Hat’s SSO service using your service account credentials:

# Replace with your actual service account values
export RH_CLIENT_ID='<RH_CLIENT_ID>'
export RH_CLIENT_SECRET='<RH_CLIENT_SECRET>

# access_token=$(curl 'https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode "client_id=$RH_CLIENT_ID" \
    --data-urlencode "client_secret=$RH_CLIENT_SECRET" \
    --data-urlencode 'scope=openid api.iam.service_accounts' | jq -r '.access_token')

Once obtained, this access_token can be included in the Authorization header when making API requests.

• Get a list of existing inventory groups/workspaces using Managed Inventory API:

# curl -X GET "https://console.redhat.com/api/inventory/v1/groups" -H "Authorization: Bearer $access_token" | jq '.results[] | .id +" "+ .name'

• Create an inventory group/workspace using Managed Inventory API:

# curl -X POST "https://console.redhat.com/api/inventory/v1/groups" -H "Authorization: Bearer $access_token" -H "Content-Type: application/json" -d '{ "name":"<group_name>" }' | jq

• Update the name of a group/workspace using Managed Inventory API:

# curl -X PATCH "https://console.redhat.com/api/inventory/v1/groups/<group_id>" -H "Authorization: Bearer $access_token" -H "Content-Type: application/json" -d '{ "name":"<group_name>" }' | jq

• Retrieve System IDs using Managed Inventory API:

# curl -X GET "https://console.redhat.com/api/inventory/v1/hosts" -H "Authorization: Bearer $access_token" | jq '.results[] | .id +" "+ .fqdn'

• Assign systems to an existing group/workspace using Managed Inventory API:

# curl -X POST "https://console.redhat.com/api/inventory/v1/groups/<group_id>/hosts" -H "Authorization: Bearer $access_token" -H "Content-Type: application/json" -d '[ "<system_id>" ]' | jq

or

# curl -X PATCH "https://console.redhat.com/api/inventory/v1/groups/<group_id>" -H "Authorization: Bearer $access_token" -H "Content-Type: application/json" -d '{ "host_ids": [ "<system_id>" ] }' | jq

Note: A list of system_ids to be associated with the existing group/workspace can be passed in the array by delimiting the system_ids with a comma.

• Create and assign systems to a new group/workspace using Managed Inventory API:

# curl -X POST "https://console.redhat.com/api/inventory/v1/groups" -H "Authorization: Bearer $access_token" -H "Content-Type: application/json" -d '{ "host_ids": [ "<system_id>" ], "name":"<group_name>" }' | jq

Note: A list of system_ids to be associated with the new group/workspace can be passed in the array by delimiting the system_ids with a comma.

• Remove a system from a group/workspace using Managed Inventory API:

# curl -X DELETE "https://console.redhat.com/api/inventory/v1/groups/<group_id>/hosts/<system_id>" -H "Authorization: Bearer $access_token" | jq

or

# curl -X DELETE "https://console.redhat.com/api/inventory/v1/groups/hosts/<system_id>" -H "Authorization: Bearer $access_token" | jq

Note: A list of system_ids to be removed from their group/workspace can be passed in by delimiting the system_ids with a comma.

• Delete an inventory group/workspace using Managed Inventory API:

# curl -X DELETE "https://console.redhat.com/api/inventory/v1/groups/<group_id>" -H "Authorization: Bearer $access_token" | jq

Note: A list of group_ids to be deleted can be passed in by delimiting the group_ids with a comma.

Refer to the following documentation for additional guidance:
- Creating and Managing Service Accounts
- Using the Red Hat Insights API
- Managed Inventory API