Managing Event Streams 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.

   The atracker CLI 0.3.2 or higher is required to run Event Streams CLI commands. If you have previously installed the atracker CLI, you might need to upgrade the atracker CLI plug-in by running ibmcloud plugin update atracker.

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. 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 Message Hub 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 Event Streams instance.

8. For Service access select Writer.

9. 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 messagehub "Writer" [--target-service-instance-id <IES_SERVICE_INSTANCE>
   

   Where:

   IES_SERVICE_INSTANCE is the CRN of the Event Streams 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:Writer"
           }
       ],
       "resources": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "messagehub"
                   },
                   {
                       "name": "serviceInstance",
                       "value": "IES_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.

   IES_SERVICE_INSTANCE is the CRN of the IES 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 an Event Streams target using the CLI

Use this command to create a IBM® Event Streams for IBM Cloud® target to be used to configure a destination for activity events.

 ibmcloud atracker target create --name TARGET_NAME --type TARGET_TYPE ( [--file EVENTSTREAMS_ENDPOINT_DEFINITION_JSON_FILE] | ( [--target-crn EVENTSTREAMS_TARGET_CRN] [--brokers BROKER_LIST] [--topic TOPIC] [--api-key ( EVENTSTREAMS_API_KEY | @EVENTSTREAMS_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
Region:                   us-south
Type:                     event_streams
Event Streams Target CRN: crn:v1:bluemix:public:messagehub:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:      my-topic
Event Streams Brokers:    [broker-1:9093,broker-2:9093]
Write Status:             success
CreatedAt:                2022-10-20T19:20:38.888Z
UpdatedAt:                2022-10-20T19:20:38.888Z

Updating an Event Streams target using the CLI

Use this command to update an Event Streams 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 EVENTSTREAMS_ENDPOINT_DEFINITION_JSON_FILE] | ( [--brokers BROKER_LIST] [--target-crn EVENTSTREAMS_TARGET_CRN] [--topic TOPIC] ( [--api-key ( EVENTSTREAMS_API_KEY | @EVENTSTREAMS_API_KEY_FILE )] | [--service-to-service-enabled ( TRUE | FALSE )]))] [--output FORMAT]

Target
Name:                     my-new-target
ID:                       000000000-00000000-0000-0000-00000000
CRN:                      crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                   us-south
Type:                     event_streams
Event Streams Target CRN: crn:v1:bluemix:public:messagehub:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:      my-topic
Event Streams Brokers:    [broker-1:9093,broker-2:9093]
Write Status:             success
CreatedAt:                2022-10-20T19:20:38.888Z
UpdatedAt:                2022-10-20T19:20:38.888Z

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
Region:                     us-south
Type:                       event_streams
Event Streams Target CRN:   crn:v1:bluemix:public:messagehub:us-south:a/a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:        my-test-topic
Event Streams Brokers:      [broker-1:9093,broker-2:9093]
Write Status:               success
CreatedAt:                  2022-10-20T19:20:38.888Z
UpdatedAt:                  2022-10-20T19:20:38.888Z

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:               		    updated-target-name
ID:                 		    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN:               		      crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                     us-south
Type:                       event_streams
Event Streams Target CRN:   crn:v1:bluemix:public:messagehub:us-south:a/a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
Event Streams Topic:        my-test-topic
Event Streams Brokers:      [broker-1:9093,broker-2:9093]
Write Status:               success
CreatedAt:                  2022-10-20T19:20:38.888Z
UpdatedAt:                  2022-10-20T19:20:38.888Z

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    event_streams   -				                     2020-11-18T03:52:08.603Z
target-02                  yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy   us-south    event_streams   -				                     2020-11-18T03:52:01.592Z
target-02-backup           zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz   us-east     event_streams   -				                     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 an Event Streams target using the API

You can use the following curl command to create an IBM® Event Streams for IBM Cloud® (Event Streams) target:

curl -X POST  <ENDPOINT>/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "TARGET_TYPE",
    "eventstreams_endpoint": {
        "target_crn": "EVENTSTREAMS_CRN",
        "brokers": "BROKER_LIST",
        "topic”: "TOPIC_NAME",
        "password": "API_KEY",
        "service_to_service_enabled": false}
    }
  }'

Where

• 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 event_streams for an Event Streams target.

• BROKER_LIST is the list of Event Streams brokers (endpoints).

• TOPIC_NAME is the name of an Event Streams topic name where the events are sent.

• API_KEY is the password value found in the Event Streams service credential. This is the IAM API key.

• service_to_service_enabled determines if IBM Cloud Activity Tracker Event Routing has service to service authentication enabled. Set this flag to true if service to service is enabled and do not supply an apikey.

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

When you update an IBM® Event Streams for IBM Cloud® (Event Streams) 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",
    "eventstreams_endpoint": {
      "target_crn": "EVENTSTREAMS_CRN",
      "brokers": "BROKER_LIST",
      "topic”: "TOPIC_NAME",
      "password": "API_KEY",
      "service_to_service_enabled": false}
    }
  }'

Where

• 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 event_streams for an Event Streams target.

• BROKER_LIST is the list of Event Streams brokers (endpoints).

• TOPIC_NAME is the name of an Event Streams topic where the events are sent.

• API_KEY is the password value found in the Event Streams service credential. This is the IAM API key.

• service_to_service_enabled determines if IBM Cloud Activity Tracker Event Routing has service to service authentication enabled. Set this flag to true if service to service is enabled and do not supply an apikey.

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

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

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 Event Streams 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 Event Streams.
8. Choose destination: Pick Search by instance or Specify CRN
   • Search by instance: Select an Event Streams instance from the table or click Create to create a new Event Streams instance.
   • Specify CRN: Enter the Cloud Resource Name (CRN) of the Event Streams instance. This enables you to enter a CRN from a different account.

• Service credentials: Select one of the service credentials, it contains the brokers list username, and api_key or password.
• Event Streams topic: Select an existing topic.
• 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 Event Streams 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. You can click Unset as default to remove your target as a default target in your IBM Cloud Activity Tracker Event Routing settings. See 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 Event Streams instance, service credential, or topic 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