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 Activity Tracker Event Routing CLI.

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

Configuring S2S authorization using the UI within the same account

Do the following to configure a service-to-service authorization using the IBM Cloud UI.

1. Log in to your IBM Cloud account as the account owner that will be configuring IBM Cloud Activity Tracker Event Routing targets.

   After you log in with your user ID and password, the IBM Cloud dashboard opens.

2. Select Manage > Access (IAM) > Authorizations.

3. Click Create.

4. For Source service, select Activity Tracker and for How do you want to scope the access?, select All resources.

5. For Target service select App Configuration and for How do you want to scope the access?, select Resources based on selected attributes.

6. Select Service instance and string equals. Set the name of your IBM Cloud App Configuration instance.

7. For Service access, select the Manager and Configuration Update Reporter roles.

8. Click Authorize. Your new service-to-service authorization will be listed in the Manage authorizations view.

Configuring S2S authorization using the CLI

Do the following to configure a service-to-service authorization using the IBM Cloud CLI.

1. Log in to your IBM Cloud account as the account owner that will be configuring IBM Cloud Activity Tracker Event Routing authorization.

2. Create an authorization policy defining your service-to-service authorization.

   ibmcloud iam authorization-policy-create atracker apprapp "ConfigurationUpdateReporter" [--target-service-instance-id <APPCONFIG_SERVICE_INSTANCE>
   

Configuring S2S authorization using the API

Do the following to configure a service-to-service authorization using the IBM Cloud API.

1. Log in to your IBM Cloud account as the account owner that will be configuring IBM Cloud Activity Tracker Event Routing IAM authorization.

2. Create an authorization_policy_resource.json file defining your service-to-service authorization.

   {
       "type": "authorization",
       "subjects": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "atracker"
                   }
               ]
           }
       ],
       "roles": [
           {
               "role_id": "crn:v1:bluemix:public:iam::::serviceRole:ConfigurationUpdateReporter"
           }
       ],
       "resources": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "apprapp"
                   },
                   {
                       "name": "serviceInstance",
                       "value": "APPCONFIG_SERVICE_INSTANCE"
                   }
               ]
           }
       ]
   }
   

   Where:

   CUSTOMER_ACCOUNT_ID is the account GUID for the account that will be configuring targets. This can be found by using the ibmcloud account list command.

   APPCONFIG_SERVICE_INSTANCE is the instance ID of the IBM Cloud App Configuration instance.

3. Get an IAM access token. For more information, see Retrieving IAM access tokens.

4. Run the following command to configure your service-to-service authorization:

   curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header "Authorization: $ACCESS_TOKEN" -d @authorization_policy_resource.json "https://iam.cloud.ibm.com/v1/policies"
   

Creating an IBM Cloud App Configuration target using the CLI

Use this command to create an IBM Cloud App Configuration target to be used to configure a destination for activity events.

 ibmcloud atracker target create --name TARGET_NAME --type TARGET_TYPE ( [--file APPCONFIG_ENDPOINT_DEFINITION_JSON_FILE] | ( [--target-crn APPCONFIG_TARGET_CRN] ) ) [--region REGION] [--output FORMAT]

OK
Target
Name:                         my-target
ID:                           000000000-00000000-0000-0000-00000000
CRN:                          crn:v1:bluemix:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                       us-south
Type:                         app_config
App Configuration Target CRN: crn:v1:bluemix:public:apprapp:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Write Status:                 success
CreatedAt:                    2024-05-31T19:03:35.427Z
UpdatedAt:                    2024-05-31T19:03:35.427Z

Updating an IBM Cloud App Configuration target using the CLI

Use this command to update an IBM Cloud App Configuration target for an IBM Cloud Activity Tracker Event Routing region. Any specified value that is different from when the target was originally created will be updated to the value specified in the command.

ibmcloud atracker target update --target TARGET [--name TARGET_NAME] [ [--file APPCONFIG_ENDPOINT_DEFINITION_JSON_FILE] | [--target-crn APPCONFIG_TARGET_CRN]] [--output FORMAT]

OK
Target
Name:                         new-target-name
ID:                           000000000-00000000-0000-0000-00000000
CRN:                          crn:v1:bluemix:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                       us-south
Type:                         app_config
App Configuration Target CRN: crn:v1:bluemix:public:apprapp:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Write Status:                 success
Created:                      2024-05-31T19:03:35.427Z
Updated:                      2024-05-31T19:03:35.427Z

Deleting a target using the CLI

Use this command to delete a target.

ibmcloud atracker 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.

Are you sure you want to remove the Target bearing Target ID 33333333-3333-3333-3333-333333333333? [y/N]> y
FAILED
Something went wrong. Error:
 Status Code:  404
 Incident ID:  67a33257-d5a4-46ec-94d9-14eb70e94f3d
 Code:         not_found
 Message:      The target id specified in `target_id` field is not found.

Validating a target using the CLI

Use this command to validate that a target is correctly configured for an IBM Cloud Activity Tracker Event Routing region.

ibmcloud atracker target validate --target TARGET [--region REGION] [--output FORMAT]

Target
Name:                            new-target-name
ID:                              xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN:                             crn:v1:bluemix:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Type:                            app_config
App Configuration Target CRN:    crn:v1:bluemix:public:apprapp:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Service to Service Enabled:      true
Write Status:                    success
Created:                         2021-07-21T16:04:15.174Z
Updated:                         2021-07-21T17:49:56.452Z

Getting information about a target using the CLI

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

ibmcloud atracker target get --target TARGET [--output FORMAT]

Target
Name:                            new-target-name
ID:                              xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN:                             crn:v1:bluemix:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                          us-east
Type:                            app_config
App Configuration Target CRN:    crn:v1:bluemix:public:apprapp:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Write Status:                    success
Created:                         2024-06-02T16:04:15.174Z
Updated:                         2024-06-05T17:49:56.452Z

Listing all targets in a region

Use this command to list the configured targets for an IBM Cloud Activity Tracker Event Routing region.

ibmcloud atracker target ls [--output FORMAT]

Name                       ID                                     Region     Type                Created
target-01                  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   us-south   app_config   2020-11-18T03: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.atracker.cloud.ibm.com

• You can manage targets from the public network using an API endpoint with the following format: https://REGION.atracker.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.

Creating an IBM Cloud App Configuration target using the API

You can use the following cURL command to create an IBM Cloud App Configuration target:

curl -X POST  <ENDPOINT>/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "app_config",
    "app_config_endpoint": {
      "target_crn": "APPCONFIG_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.

• TARGET_TYPE is the type of the target.

• app_config_endpoint includes information about the target.

  APPCONFIG_CRN indicates the CRN of the IBM Cloud App Configuration instance.

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

curl -X POST   https://private.us-south.atracker.cloud.ibm.com/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "My App Configuration target",
    "target_type": "app_config",
    "app_config_endpoint": {
      "target_crn": "crn:v1:bluemix:public:apprapp:us-south:a/<account-id>:<instance-id>::"
    }
  }'

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 an IBM Cloud App Configuration target using the API

When you update an IBM Cloud App Configuration 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.
• You cannot change the target_type of a target once created.

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

curl -X PUT  <ENDPOINT>/api/v2/targets/TARGET_ID  -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "app_config",
    "app_config_endpoint": {
      "target_crn": "APPCONFIG_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.

• TARGET_TYPE is the type of the target. Set the value to app_config for an IBM Cloud App Configuration target.

• app_config_endpoint includes information about the target.

  APPCONFIG_CRN indicates the CRN of the IBM Cloud App Configuration instance.

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

curl -X PUT   https://private.us-south.atracker.cloud.ibm.com/api/v2/targets/TARGET_ID   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "My new App Configuration target name",
    "target_type": "app_config",
    "app_config_endpoint": {
      "target_crn": "crn:v1:bluemix:public:apprapp:us-south: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/v2/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 in US-South with the ID 00000000-0000-0000-0000-000000000000:

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

In the response, you get an empty result if the deletion was successful:

{}

Validating a target using the API

You can use the following cURL command to validate a target by checking the credentials to write to the target.

curl -X POST <ENDPOINT>/api/v2/targets/<TARGET_ID>/validate -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 validate a target in US-South with the ID 00000000-0000-0000-0000-000000000000:

curl -X POST https://private.us-south.atracker.cloud.ibm.com/api/v2/targets/<TARGETID>/validate -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

In the response, you get information in the section write_status, for example:

"write_status": {
    "status": "success"
  },

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/v2/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.atracker.cloud.ibm.com/api/v2/targets/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Results will show if the target is COS ("target_type": "cloud_object_storage"), IBM Cloud Logs offering ("target_type": "cloud_logs"), or IBM Cloud App Configuration ("target_type": "app_config")

Listing all targets using the API

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

curl -X GET <ENDPOINT>/api/v2/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.atracker.cloud.ibm.com/api/v2/targets -H "Authorization:  $ACCESS_TOKEN" -H "content-type: application/json"

Results will show if the target is COS ("target_type": "cloud_object_storage"), IBM Cloud Logs offering ("target_type": "cloud_logs"), or IBM Cloud App Configuration ("target_type": "app_config")

HTTP response codes

When you use the IBM Cloud Activity Tracker Event 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 usually indicates an internal system error.

See the following table for some HTTP response codes: