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.
-
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>
- 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
- 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
.
- 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
.
-
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'
-
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.
-
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}