Managing Monitoring targets

CLI prerequisites

Before you use the CLI to manage targets, complete the following steps:

1. Install the IBM Cloud CLI.

2. Install the IBM Cloud Metrics Routing CLI.

3. Log in to IBM Cloud. Run the following command: ibmcloud login

4. Before you configure IBM Cloud Metrics Routing routes or targets, you must configure a primary metadata region. The primary metadata region is configured using the ibmcloud metrics-router setting update command --primary-metadata-region option.

Creating a Monitoring target by using the CLI

Use this command to create a Monitoring target to be used to configure a destination for platform metrics.

Target names are unique in the account.

ibmcloud metrics-router target create --name TARGET_NAME --destination-crn CRN_VALUE [--region REGION] [--output FORMAT]

Target
Name:               		my-target
ID:                 		000000000-00000000-0000-0000-00000000
REGION:                         us-east
Type:               		sysdig_monitor
Destination CRN:     		crn:v1:bluemix:public:sysdig-monitor:au-syd:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
CreatedAt:            		2021-07-21T16:04:15.174Z
UpdatedAt:            		2021-07-21T16:04:15.174Z

Updating a Monitoring target using the CLI

Use this command to update a Monitoring target. You can modify the name of a target and the destination CRN. Any specified value that is different from when the target was originally created will be updated to the value specified in the command.

Target names are unique in the account.

ibmcloud metrics-router target update --target TARGET [--name TARGET_NAME] [--destination-crn DESTINATION_TARGET_CRN] [--output FORMAT]

Target
Name:               		my-new-target-name
ID:                 		000000000-00000000-0000-0000-00000000
REGION:                         us-east
CRN:                		crn:v1:bluemix:public:metrics-router:us-south:a/xxxxxxxxxx:000000000-00000000-0000-0000-00000000
Type:               		sysdig_monitor
Destination CRN:     		crn:v1:bluemix:public:sysdig-monitor:au-syd:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
CreatedAt:            		2021-07-21T16:04:15.174Z
UpdatedAt:            		2021-07-21T16:04:15.174Z

Deleting a target using the CLI

Use this command to delete a target.

ibmcloud metrics-router target rm --target TARGET [--force]

Are you sure you want to remove the target with target ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx? [y/N]>y
OK
Target with target ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx was successfully removed.

Getting information about a target using the CLI

Use this command to get information about a target for an IBM Cloud Metrics Routing region.

ibmcloud metrics-router target get --target TARGET [--output FORMAT]

Name:               		my-target
ID:                 		000000000-00000000-0000-0000-00000000
REGION:                         us-east
CRN:                		crn:v1:bluemix:public:metrics-router:us-south:a/xxxxxxxxxx:000000000-00000000-0000-0000-00000000
Type:               		sysdig_monitor
Destination CRN:     		crn:v1:bluemix:public:sysdig-monitor:au-syd:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
CreatedAt:            		2021-07-21T16:04:15.174Z
UpdatedAt:            		2021-07-21T16:04:15.174Z

Listing all targets in a region

Use this command to list the configured targets for an IBM Cloud Metrics Routing region.

ibmcloud metrics-router target ls [--output FORMAT]

Name                       ID                                     Region     Type              	CreatedAt                   UpdatedAt
target-01                  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   us-south    sysdig_monitor    2020-11-18T03:52:08.603Z    2020-11-19T03:52:08.603Z
target-02                  yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy   us-south    sysdig_monitor    2020-11-18T03:52:01.592Z    2020-11-19T03:52:08.603Z
target-02-backup           zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz   us-east     sysdig_monitor    2021-02-26T06:53:13.466Z    2020-11-19T03:52:08.603Z

API targets and actions

The following table lists the actions that you can run to manage targets:

You can use private and public endpoints to manage targets. For more information about the list of ENDPOINTS that are available, see Endpoints.

• You can manage targets from the private network using an API endpoint with the following format: https://private.REGION.metrics-router.cloud.ibm.com

• You can manage targets from the public network using an API endpoint with the following format: https://REGION.metrics-router.cloud.ibm.com

• You can disable the public endpoints by updating the account settings. For more information, see Configuring target and region settings.

For more information about the REST API, see Targets.

API prerequisites

To make API calls to manage targets, complete the following steps:

1. Get an IAM access token. For more information, see Retrieving IAM access tokens.
2. Identify the API endpoint in the region where you plan to configure or manage a target. For more information, see Endpoints.
3. Before you configure IBM Cloud Metrics Routing routes or targets, you must configure a primary metadata region. The primary metadata region is configured using the modify settings API method.

Creating a Monitoring target using the API

You can use the following cURL command to create a Monitoring target:

Target names are unique in the account.

curl -X POST <ENDPOINT>/api/v3/targets -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "TARGET_NAME",
    "destination_crn": "CRN"
  }'

Where

• <ENDPOINT> is the API endpoint in the region where you plan to configure or manage a target. For more information, see Endpoints.

• TARGET_NAME is the name of the target. The maximum length of the name is 256 characters.

  Do not include any personal identifying information (PII) in any resource names.

• CRN indicates the CRN of the Monitoring instance.

For example, you can use the following cURL request to create a target in Dallas:

curl -X POST https://private.us-south.metrics-router.cloud.ibm.com/api/v3/targets -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My-target",
    "target_type": "crn:v1:bluemix:public:sysdig-monitor:au-syd:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::"
  }'

In the response, you get information about the target such as the id, that indicates the GUID of the target, and the crn, that indicates the CRN of the target.

Updating a Monitoring target using the API

You can modify the name of a target and the destination CRN. Any specified value that is different from when the target was originally created will be updated to the value specified in the request.

When you update a Monitoring target, you must include the target information in the data section of the request.

• You must pass all fields.
• Update the fields that need to be changed.

Target names are unique in the account.

You can use the following cURL command to update a target:

curl -X PATCH <ENDPOINT>/api/v3/targets/TARGET_ID -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "TARGET_NAME",
    "destination_crn": "CRN"
  }'

Where

• <ENDPOINT> is the API endpoint in the region where you plan to configure or manage a target. For more information, see Endpoints.

• TARGET_ID is the ID of the target.

• TARGET_NAME is the name of the target. The maximum length of the name is 256 characters.

  Do not include any personal identifying information (PII) in any resource names.

• CRN indicates the CRN of the Monitoring instance.

For example, you can use the following cURL request to create a target in Dallas:

curl -X PATCH https://private.us-south.metrics-router.cloud.ibm.com/api/v3/targets -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My target",
    "destination_crn": "crn:v1:bluemix:public:sysdig-monitor:au-syd:a/<account-id>:<instance-id>::"
    }
  }'

Deleting a target using the API

You can use the following cURL command to delete a target:

curl -X DELETE <ENDPOINT>/api/v3/targets/<TARGET_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

• <ENDPOINT> is the API endpoint in the region where you plan to configure or manage a target. For more information, see Endpoints.
• <TARGET_ID> is the ID of the target.

For example, you can use the following cURL request to delete a target with the ID 00000000-0000-0000-0000-000000000000:

curl -X DELETE https://private.us-south.metrics-router.cloud.ibm.com/api/v3/targets/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Viewing a target using the API

You can use the following cURL command to view the configuration details of 1 target:

curl -X GET <ENDPOINT>/api/v3/targets/<TARGET_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

• <ENDPOINT> is the API endpoint in the region where you plan to configure or manage a target. For more information, see Endpoints.
• <TARGET_ID> is the ID of the target.

For example, you can run the following cURL request to get information about a target with the ID 00000000-0000-0000-0000-000000000000:

curl -X GET https://private.us-south.metrics-router.cloud.ibm.com/api/v3/targets/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Listing all targets using the API

You can use the following cURL command to view all targets:

curl -X GET <ENDPOINT>/api/v3/targets -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

• <ENDPOINT> is the API endpoint in the region where you plan to configure or manage a target. For more information, see Endpoints.

For example, you can run the following cURL request to get information about the targets that are defined in Dallas:

curl -X GET https://private.us-south.metrics-router.cloud.ibm.com/api/v3/targets -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

HTTP response codes

When you use the IBM Cloud Metrics Routing REST API, you can get standard HTTP response codes to indicate whether a method completed successfully.

• A 200 response always indicates success.
• A 4xx response indicates a failure.
• A 5xx response indicates an internal system error.

See the following table for some HTTP response codes: