Using the Resource Group Management Service API

Use the Resource Group Management Service API to manage the lifecycle of groups of managed systems from the command line.

About this task

Complete resource group tasks such as creating, viewing, updating, and deleting groups of managed systems. Add and remove individual systems from custom groups. View a list of systems that you added to a specific custom resource group, and view a list of systems that are automatically added to the built-in groups such as the system resource group.

You can create scripts for automating such tasks as defining resource groups and assigning agents to these resource groups. The resource groups can be targets of threshold distributions and or access control policies.

The following operations are described in API Explorerand in the Example at the end of this topic.
  • Return all resource groups, agents, or a specific resource group or agent.
  • Create a custom resource group or update the definition of an existing group
  • Delete a specified custom resource group
  • Add agents to a custom resource group
  • Remove agents from a custom resource group

Procedure

Complete these steps to define and change custom resource groups with the Resource Group Management Service API. System resource groups and agents cannot be modified.

  1. Complete step 1 to step 9 in the Exploring the APIs topic.
    Step 10 and step 11 provide additional details.
  2. Click USE and select a key, for example, Key1.
    Note: Click Hide to show your client-Id and client secret. Make a note of them because, if you are making API calls with external tools outside of API Explorer, they are needed. Then, click Show to hide them.
  3. Populate all required headers, denoted with an asterisk.
    X-IBM-Service-Location
    * header is the geographic location of your subscription such as na for North America
    Authorisation
    * header is your base64-encoded string of the IBM ID and password. When you encode the IBM ID and password in the based64-encoder tool, the format must be IBMid:password, for example, Basic YXBtYWRtaW46YXBtcGFzcw==.
  4. You must include a referer header in all POST, PUT, and DELETE requests. The value for the referer header is always: 
    -H 'Referer: https://api.ibm.com'
  5. Scroll to locate and click Test.

Results

The changes that you make to custom resource groups in the API are effective immediately and displayed in the Resource Group Manager (see Resource Group Manager).

Example

This command returns the names, unique identifiers, status, hostname, version, and agent type for all agents: 
GET /1.0/topology/mgmt_artifacts?_filter=entityTypes=Agent&_field=keyIndexName&_field=online&_field=hostname&_field=version&_field=productCode&_field=description
This command returns a list of all Linux OS agents:
GET /1.0/topology/mgmt_artifacts?_filter=entityTypes=Agent&_filter=description="Linux OS"&_field=keyIndexName
This command returns a list of system and custom groups: 
GET /1.0/topology/mgmt_artifacts?_filter=entityTypes:AgentGroup,AgentSystemGroup&_field=keyIndexName&_field=displayLabel
This command returns the list of agents that are assigned to a group that has the unique identifier {id}: 
GET /1.0/topology/mgmt_artifacts/{id}/references/to/contains
The following example uses the curl command to create a custom group. 
POST /1.0/topology/mgmt_artifacts
Note: The body of the POST request must contain a JSON object that defines the group as shown by the -d parameter. 
curl -X POST \
  https://api.ibm.com/perfmgmt/run/1.0/topology/mgmt_artifacts \
  -H 'Referer: https://api.ibm.com' \
  -H 'authorization: Basic REPLACE_BASE64_ENCODED_STRING' \
  -H 'content-type: application/json' \
  -H 'x-ibm-client-id: REPLACE_KEY_VALUE' \
  -H 'x-ibm-client-secret: REPLACE_KEY_VALUE' \ 
  -d '{
  "keyIndexName": "customGroup",
  "description": "Custom group description",
  "displayLabel": "customGroupLabel",
  "entityTypes": [
    "AgentGroup"
  ],
  "arbitraryStringProperty": "Your custom property value"
}'
This command adds an agent with unique identifier {otherid} to a custom group that has unique identifier {id}: 
POST /1.0/topology/mgmt_artifacts/{id}/references/to/contains/{otherid}
This command removes an agent with unique identifier {otherid} from a custom group that has unique identifier {id}: 
DELETE /1.0/topology/mgmt_artifacts/{id}/references/to/contains/{otherid}