Using the Resource Group Management Service API

Edit online

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.

In this task you can use either access tokens or basic authorisation in the curl command:
Access tokens

Use the OpenID Connect (OIDC) protocol to get an access token from the OIDC server on the Cloud APM server. The access token gives you authorised access to the API for running operations until the token expires after 30 minutes.

Basic authorisation

Use a base64 tool to encode your Cloud APM console user ID and password into a single base64 string. The input string format is userId:password, such as apmadmin:apmpass. The output is a string such as: YXBtYWRtaW46YXBtcGFzcw==

Use base64_encoded_string in the authorisation header of every request as shown in the curl command examples.

Note the Cloud APM console user ID must be added to a role with appropriate permissions.

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

Disabling OIDC authentication, which is required before you can enable single sign-on (SSO) between Cloud APM and other IBM® products such as Tivoli® Common Reporting that require LTPA for single sign-on, does not affect the API. The RESTful API continues to use the Cloud APM internal OIDC server, even if OIDC is disabled for single sign-on between the Cloud APM console and other product user interfaces.

Resource Group Management Service API requests can be issued by using https to the port 8091 of the Cloud APM server or using http to the port 8090 of the Cloud APM server.

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. On the system where the Cloud APM server is installed, open the following file and copy the values of the client.secret.apmui and client.id.apmui variables: 
    install_dir/wlp/usr/shared/config/clientSecrets.xml
    The following example shows what the file contains: 
    <server>
  <variable name="client.secret.apmui" value="{xor}BiY3KQgIa2gRCms3CxxrMhUYL2YRJSwvCjUnJxYb" />
  <variable name="client.id.apmui" value="rpapmui" />
</server>
  2. Optional: If you plan to use an access token in your curl command, use an XOR decoder to decode the value of the client.secret.apmui variable to get the actual secret value.
    For example, when you use an XOR decoder to decode BiY3KQgIa2gRCms3CxxrMhUYL2YRJSwvCjUnJxYb, you get the following value: YyhvWW47NU4hTC4mJGp9NzspUjxxID
  3. Optional: If you plan to use an access token in your curl command, complete this step. To get an access token, contact the token endpoint of the Cloud APM OIDC server with the four required items: username, password, client_id, and client_secret, as in the following command: 
    curl --tlsv1.2 -v -k -d "grant_type=password&client_id=rpapmui&client_secret=YyhvWW47NU4hTC4mJGp9NzspUjxxID&username=apmadmin&password=apmpass&scope=openid" https://example.mycompany.com:8099/oidc/endpoint/OP/token
    Where:
    • username is the username of the Cloud APM console user
    • password is the password of a Cloud APM console user
    • clientid is the value of the client.id.apmui variable from step 1.
    • client_secret is the value created by the XOR decoder in step 2.
    Output:
    {"access_token":"jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8","token_type":"Bearer","expires_in":1800,"scope":"openid","refresh_token":"VsCWUhPHBRpidD2F1PVyZ2LNGMuQPTN837t3OoqZj71FcBfsGE"}
    Note: If the client_secret, username, or password values contain characters other than digits (0-9), ASCII letters (A-Z, a-z), and a few special characters ( "-" , "." , "_" , "~" ), you must URL encode the other characters. For example, if the decoded client secret is TEVlNjROVT8iPF9r=1dNNW8+SGFgJ0, replace the = character with %3D, replace the + character with %2B, and enter client_secret=TEVlNjROVT8iPF9r%3D1dNNW8%2BSGFgJ0 instead of client_secret=TEVlNjROVT8iPF9rO1dNNW8+SGFgJ0.
  4. Optional: If you plan to use an access token in your curl command, extract the access_token value.
    Looking at the output in the previous example, the value is jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8.
  5. Enter requests to the Resource Group Management Service API using either an access token or basic authorization.
    Access token example
    curl --tlsv1.2 -v -k --request GET --url 'https://myAPMServer.mycompany-domain.com:8091/1.0/topology/mgmt_artifacts?_field=keyIndexName' --header 'authorization: Bearer jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8' --header 'content-type: application/json'
    Basic authorization example: 
    curl --tlsv1.2 -v -k --request GET --url 'https://myAPMServer.mycompany-domain.com:8091/1.0/topology/mgmt_artifacts?_field=keyIndexName' --header 'authorization: Basic YXBtYWRtaW46YXBtcGFzcw==' --header 'content-type: application/json'
  6. For more details about API operations, see API documentation in API Explorer. For instructions about accessing API Explorer, see Exploring the APIs.
    Note: Part of the URL and some of the headers that are shown in the examples are required for Cloud APM only. For example: https://api.ibm.com/perfmgmt/run, x-ibm-service-location, X-IBM-Client-Id, X-IBM-Client-Secret. See step 5 for request examples.
  7. You must include a referer header in all POST, PUT, and DELETE requests. The value for the referer header is: 
    -H 'Referer: https://apm_server:8091'
    where apm_server is the IP address or the fully qualified host name of your Cloud APM server.

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://apm_server:8091/1.0/topology/mgmt_artifacts \
  -H 'Referer: https://apm_server:8091' \
  -H 'authorization: Bearer Your_Access_Token' \
  -H 'content-type: application/json' \
  -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}