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

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

Configuring S2S authorization using the UI witihin 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. Click Manage > Access (IAM). Manage access and users is displayed.

3. Click Authorizations.

4. Click Create.

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

6. For Target service select Cloud Object Storage for How do you want to scope the access? select Resources based on selected attributes.

7. Select Service instance and string equals the name of your COS instance.

8. For Service access select Object writer.

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

You will only be able to authorize to the IBM Cloud Object Storage instance using the UI. If you want to limit authorization to a specific IBM Cloud Object Storage bucket, you need to configure authorization using the API.

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] (/docs/cli?topic=cli-ibmcloud_cli#ibmcloud_login) 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 cloud-object-storage "Object Writer" [--target-service-instance-id <COS_SERVICE_INSTANCE>
   

   Where:

   COS_SERVICE_INSTANCE is the bucket instance CRN of the COS instance to be authorized.

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:ObjectWriter"
           }
       ],
       "resources": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "cloud-object-storage"
                   },
                   {
                       "name": "serviceInstance",
                       "value": "COS_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.

   COS_SERVICE_INSTANCE is the bucket instance CRN of the COS instance to be authorized.

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 a COS target using the CLI

Use this command to create a IBM Cloud Object Storage target to be used to configure a destination for activity events.

 ibmcloud atracker target create --name TARGET_NAME --type TARGET_TYPE ( [--file COS_ENDPOINT_DEFINITION_JSON_FILE] |  ( [--endpoint COS_ENDPOINT] [--bucket COS_BUCKET] [--target-crn COS_TARGET_CRN] ( [--api-key ( COS_API_KEY | @COS_API_KEY_FILE )] |  [--service-to-service-enabled ( TRUE | FALSE )] ) ) ) [--region REGION] [--output FORMAT]

Target
Name:               		my-target
ID:                 		000000000-00000000-0000-0000-00000000
CRN:                		crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Type:               		cloud_object_storage
COS Endpoint:       		s3.us-west.cloud-object-storage.appdomain.cloud
COS Target CRN:     		crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
COS Bucket:         		cloud-object-my-target
Service to Service Enabled:	true
Write Status:   		success
Created:            		2021-07-21T16:04:15.174Z
Updated:            		2021-07-21T16:04:15.174Z

Updating a COS target using the CLI

Use this command to update a COS 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 COS_ENDPOINT_DEFINITION_JSON_FILE] |  ( [--endpoint COS_ENDPOINT] [--bucket COS_BUCKET] [--target-crn COS_TARGET_CRN] ( [--api-key ( COS_API_KEY | @COS_API_KEY_FILE )] | [--service-to-service-enabled ( TRUE | FALSE )]))] [--output FORMAT]

Target
Name:               		new-target-name
ID:                 		xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN:               		crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Type:               		cloud_object_storage
COS Endpoint:       		s3.us-west.cloud-object-storage.appdomain.cloud
COS Target CRN:    		crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
COS Bucket:         		cloud-object-my-target
Service to Service Enabled:	true
Write Status:   		success
Created:            		2021-07-21T16:04:15.174Z
Updated:           		2021-07-21T17:49:56.452Z

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:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Type:               		cloud_object_storage
COS Endpoint:       		s3.us-west.cloud-object-storage.appdomain.cloud
COS Target CRN:     		crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
COS Bucket:         		cloud-object-my-target
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:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Type:               		cloud_object_storage
COS Endpoint:      		s3.us-west.cloud-object-storage.appdomain.cloud
COS Target CRN:     		crn:v1:staging:public:cloud-object-storage:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
COS Bucket:         		cloud-object-my-target
Service to Service Enabled:	true
Write Status:   		success
Created:           		2021-07-21T16:04:15.174Z
Updated:            		2021-07-21T17: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                     Service to Service Enabled	Created
target-01                  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   us-south    cloud_object_storage    true				2020-11-18T03:52:08.603Z
target-02                  yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy   us-south    cloud_object_storage    true				2020-11-18T03:52:01.592Z
target-02-backup           zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz   us-east     cloud_object_storage    false				2021-02-26T06:53:13.466Z

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 a COS target using the API

You can use the following cURL command to create a IBM Cloud Object Storage (COS) target:

curl -X POST  <ENDPOINT>/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "cloud_object_storage",
    "cos_endpoint": {
      "endpoint": "PRIVATE_COS_ENDPOINT",
      "target_crn": "COS_CRN",
      "bucket": "BUCKET_NAME",
      "api_key": "API_KEY",
      "service_to_service_enabled": SERVICE_TO_SERVICE
    }
  }'

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. The valid type is cloud_object_storage.

• cos_endpoint includes information about the target. For more information on how to get the bucket details, see Getting the bucket configuration details.

  PRIVATE_COS_ENDPOINT indicates the IBM Cloud Activity Tracker Event Routing endpoint to look for this bucket. Use the private endpoint.

  COS_CRN indicates the CRN of the COS instance where you provisioned the bucket.

  BUCKET_NAME indicates the name of the bucket.

  API_KEY contains the API key that has permissions to upload objects into the bucket. This value is ignore if service_to_service_enabled is true.

  SERVICE_TO_SERVICE indicates if service-to-service authorization has been enabled for the bucket. Specify true if service-to-service authorization is enabled and false if service-to-service authorization is not enable. By default, service-to-service authorization is false.

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 COS target",
    "target_type": "cloud_object_storage",
    "cos_endpoint": {
      "endpoint": "s3.private.us-south.cloud-object-storage.appdomain.cloud",
      "target_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<instance-id>::",
      "bucket": "my-activity-tracking-bucket",
      "api_key": "xxxxxxxxxxxxxxxxxx",
      "service_to_service_enabled": false
    }
  }'

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 COS target using the API

When you update an IBM Cloud Object Storage (COS) 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": "TARGET_TYPE",
    "cos_endpoint": {
      "endpoint": "PRIVATE_COS_ENDPOINT",
      "target_crn": "COS_CRN",
      "bucket": "BUCKET_NAME",
      "api_key": "API_KEY",
      "service_to_service_enabled": SERVICE_TO_SERVICE
    }
  }'

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 cloud_object_storage for a COS target.

• cos_endpoint includes information about the target. For more information on how to get the bucket details, see Getting the bucket configuration details.

  PRIVATE_COS_ENDPOINT indicates the IBM Cloud Activity Tracker Event Routing endpoint to look for this bucket. Use the private endpoint.

  COS_CRN indicates the CRN of the COS instance where you provisioned the bucket.

  BUCKET_NAME indicates the name of the bucket.

  API_KEY contains the API key that has permissions to upload objects into the bucket. This value is ignore if service_to_service_enabled is true.

  SERVICE_TO_SERVICE indicates if service-to-service authorization has been enabled for the bucket. Specify true if service-to-service authorization is enabled and false if service-to-service authorization is not enable. By default, service-to-service authorization is false.

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

curl -X PUT   https://private.us-south.atracker.cloud.ibm.com/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "My COS target",
    "target_type": "cloud_object_storage",
    "cos_endpoint": {
      "endpoint": "s3.private.us-south.cloud-object-storage.appdomain.cloud",
      "target_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/<account-id>:<instance-id>::",
      "bucket": "my-activity-tracking-bucket",
      "service_to_service_enabled": true
    }
  }'

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 cos_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") or an IBM Cloud Activity Tracker hosted event search offering ("target_type": "logdna").

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 a COS ("target_type": "cloud_object_storage") target or an IBM Cloud Activity Tracker hosted event search offering ("target_type": "logdna") target} target.

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:

Creating a IBM Cloud Object Storage target using the UI

Only resources in your account are listed and selectable. To specify a resource in a different account, select Specify CRN under Choose destination.

1. Log in to your IBM Cloud account.
2. Click the Menu icon > Observability.
3. Select Activity Tracker.
4. Select Routing.
5. Select Targets.
6. Click Create to open the create panel.
7. Choose type: Click Object Storage.
8. Service authorization required: Service authorization is required to allow IBM Cloud Activity Tracker Event Routing to communicate with IBM Cloud Object Storage. Click Authorize now to create the policy automatically or click Grant access in IAM.
9. Choose destination: Pick Search by instance or Specify CRN
   • Search by instance: Select an IBM Cloud Object Storage instance from the table or click Create to create a new IBM Cloud Object Storage instance. After selecting an instance, select an IBM Cloud Object Storage bucket.
   • Specify CRN: Enter the Cloud Resource Name (CRN) of the IBM Cloud Object Storage bucket. This enables you to enter a CRN from a different account.

• Bucket endpoint: Use the default bucket endpoint or change it.
• Target name: Enter a meaningful name for the target.
• Target region: Select the region that will process the event data.
• Toggle Set as default target to automatically set your new target as a default target in your IBM Cloud Activity Tracker Event Routing settings. See the default targets documentation for more details.
• Click Create target.

Updating a IBM Cloud Object Storage target using the UI

Only resources in your account are listed and selectable. To specify a resource in a different account, select Specify CRN under Choose destination.

1. Log in to your IBM Cloud account.
2. Click the Menu icon > Observability.
3. Select Activity Tracker.
4. Select Routing.
5. Select Targets.
6. Determine which target to update and click the .
7. Click Unset as default to remove your target as a default target in your IBM Cloud Activity Tracker Event Routing settings. See the default targets documentation for more details.
8. Click Edit to open the update panel.
9. Details: Click Edit to update your target's name or region. You can also toggle Default target to add or remove your target as a default target in your IBM Cloud Activity Tracker Event Routing settings.
10. Click Save to update your target.
11. Destination: Click Edit to change the IBM Cloud Object Storage instance or buckets associated with your target.
12. Click Save to update your target.

Deleting a target using the UI

You cannot delete an IBM Cloud Activity Tracker Event Routing target if it is used in a route or as a default target setting.

1. Log in to your IBM Cloud account.
2. Click the Menu icon > Observability.
3. Select Activity Tracker.
4. Select Routing.
5. Select Targets.
6. Determine which target to delete and click the .
7. Click Delete and then click Delete in the confirmation panel.

Listing all targets in a region using the UI

1. Log in to your IBM Cloud account.
2. Click the Menu icon > Observability.
3. Select Activity Tracker.
4. Select Routing.
5. Select Targets.

The table details:

• Target type
• Destination name
• Destination region
• Routes: If it is used in any routes
• Target status:
  • Active: The target is working as expected
  • Error: The target is miscosfigured and events will not be routed to the destination. Update your target details or destination to fix the target configuration or delete the target if it is no longer needed