Managing routes

CLI prerequisites

Before you use the the CLI to manage routes, install the latest Activity Tracker Event Routing CLI V2 plugin in your local system. See Installing the Activity Tracker Event Routing CLI.

Next, log in to the IBM Cloud. Run the following command: ibmcloud login

Creating a route using the CLI

Use this command to create a new route for an Activity Tracker Event Routing target.

ibmcloud atracker route create --name ROUTE_NAME  ( --target-ids TARGETS  [--locations REGIONS] | --rules RULES | --file RULES_DEFINITION_JSON_FILE ) [--output FORMAT]

OK
Route
Name:                    dev-eu-de-route
ID:                      44444444-4444-4444-4444-444444444444
CRN:                     crn:v1:staging:public:atracker:eu-de:a/11111111111111111111111111111111::route:44444444-4444-4444-4444-444444444444
Version:                 0
Rules:                   [locations: [us-south], target_ids: [33333333-3333-3333-3333-333333333333]]
Created:                 2022-02-24T21:10:09.996Z
Updated:                 2022-02-24T21:10:09.996Z

Updating a route using the CLI

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

ibmcloud atracker route update --route ROUTE [--name ROUTE_NAME] [--force] ( [--target-ids TARGETS]  [--locations REGIONS] | [--rules RULES] | [--file RULES_DEFINITION_JSON_FILE] ) [--output FORMAT] [--output FORMAT]

OK
Route
Name:                    dev-eu-de-route
ID:                      44444444-4444-4444-4444-444444444444
CRN:                     crn:v1:staging:public:atracker:eu-de:a/11111111111111111111111111111111::route:44444444-4444-4444-4444-444444444444
Version:                 1
Rules:                   [locations: [*], target_ids: [55555555-5555-5555-5555-555555555555]]
Created:                 2022-02-24T21:10:09.996Z
Updated:                 2022-02-24T21:13:37.218Z

Deleting a route using the CLI

Use this command to delete an Activity Tracker Event Routing route.

ibmcloud atracker route rm --route ROUTE [--force]

Are you sure you want to remove the route with the Route ID 44444444-4444-4444-4444-444444444444? [y/N]> y
OK
Route with route ID 44444444-4444-4444-4444-444444444444 was successfully removed.

FAILED
No route found with route name - 33333333-3333-3333-3333-333333333333

Viewing a route using the CLI

Use this command to get information about an Activity Tracker Event Routing route.

ibmcloud atracker route get --route ROUTE [--output FORMAT]

OK
Route
Name:                    dev-eu-de-route-0
ID:                      44444444-4444-4444-4444-444444444444
CRN:                     crn:v1:staging:public:atracker:eu-de:a/11111111111111111111111111111111::route:44444444-4444-4444-4444-444444444444
Version:                 2
Rules:                   [locations: [us-south], target_ids: [55555555-5555-5555-5555-555555555555]]
Created:                 2022-02-24T21:10:09.996Z
Updated:                 2022-02-24T21:15:07.281Z

Listing all routes using the CLI

Use this command to list all the configured routes for Activity Tracker Event Routing .

ibmcloud atracker route ls [--output FORMAT]

Name                      ID                                     Rules                                              Route Version   API version   CreatedAt                  UpdatedAt
my-global-route           aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa   [[11111111-1111-1111-1111-111111111111],[global]]  5               2             2022-05-04T20:18:00.595Z   2022-05-05T19:04:58.374Z
send-all-to-us-east       bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb   [[22222222-2222-2222-2222-222222222222],[*]]       0               2             2022-05-06T12:02:47.832Z   2022-05-06T12:02:47.832Z

API routes and actions

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

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

• You can manage routes from the private network using an API endpoint with the following format: https://private.REGION.atracker.cloud.ibm.com.

• You can manage routes from the public network using an API endpoint with the following format: https://REGION.atracker.cloud.ibm.com.

• Since the routes are global configurations, you can use any regional endpoint to manage the routes for the account.

• 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 Routes.

API prerequsites

To make API calls to manage routes, 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 route. For more information, see Endpoints.

Creating a route using the API

You must create a target before you create a route.

You can use the following cURL command to create a route:

curl -X POST  <ENDPOINT>/api/v2/routes   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"  -d '{
    "name": "ROUTE_NAME",
    "rules": [
      {
        "locations": ["LOCATIONS"],
        "target_ids": ["TARGET_ID"]
      }
    ]
  }'

Where

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

• ROUTE_NAME is the name of the route. The maximum length of the name is 180 characters and cannot include any of the following special characters:-, ., _, :.

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

• LOCATIONS is a list of locations associated with the route. Specify global to include global events. To include all locations specify *. If you have multiple rules, along with a rule with a * location, then the other rules will route events to the specified targets with any events not matching any other rule routing the remaining events to the target specified by the rule with the * location.

• TARGET_ID is the GUID of the target that defines where auditing events are routed and collected. This can include GUIDs of targets in other regions. If TARGET_ID is empty, any events matching the rule will be discarded.

For example, you can use the following cURL request to create a route that defines how global and US-South location-based events are collected and routed in the account:

curl -X POST   https://private.us-south.atracker.cloud.ibm.com/api/v2/routes   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"  -d '{
    "name": "my-route",
    "rules": [
      {
        "locations": ["us-south", "global"],
        "target_ids": ["22222222-2222-2222-2222-222222222222"]
      }
    ]
  }'

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

Updating a route using the API

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

• You must pass all fields.
• Update the fields that need changing.

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

curl -X PUT  <ENDPOINT>/api/v2/routes/<ROUTE_ID>   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"  -d '{
    "name": "ROUTE_NAME",
    "rules": [
      {
        "locations": ["LOCATIONS"],
        "target_ids": ["TARGET_ID"]
      }
    ]
  }'

Where

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

• <ROUTE_ID> is the ID of the route to be updated

• ROUTE_NAME is the name of the route. The maximum length of the name is 180 characters and cannot include any of the following special characters:-, ., _, :.

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

• LOCATIONS is a list of locations associated with the route. Specify global to include global events. To include all locations specify *. If you have multiple rules, along with a rule with a * location, then the other rules will route events to the specified targets with any events not matching any other rule routing the remaining events to the target specified by the rule with the * location.

• TARGET_ID is the GUID of the target that defines where auditing events are routed and collected. This can include GUIDs of targets in other regions. If TARGET_ID is empty, any events matching the rule will be discarded.

For example, you can use the following cURL request to update a route that defines how global and US-South and US-East location-based events are collected and routed in the account:

curl -X PUT https://private.us-south.atracker.cloud.ibm.com/api/v2/routes/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"  -d '{
    "name": "my-route",
    "rules": [
      {
        "locations": ["us-south", "global", "us-east],
        "target_ids": ["22222222-2222-2222-2222-222222222222"]
      }
    ]
  }'

Deleting a route using the API

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

curl -X DELETE   <ENDPOINT>/api/v2/routes/<ROUTE_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 route. For more information, see Endpoints.
• <ROUTE_ID> is the ID of the route to be deleted

For example, you can run the following cURL request to delete the route with the ID aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:

curl -X DELETE  https://private.us-south.atracker.cloud.ibm.com/api/v2/routes/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"

Viewing a route using the API

You can use the following cURL command to view 1 route:

curl -X GET   <ENDPOINT>/api/v2/routes/<ROUTE_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 route. For more information, see Endpoints.
• <ROUTE_ID> is the ID of the route to be fetched

For example, you can run the following cURL request to get information about a route with the ID aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:

curl -X GET   https://private.us-south.atracker.cloud.ibm.com/api/v2/routes/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa    -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"

Listing all routes in a region using the API

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

curl -X GET   <ENDPOINT>/api/v2/routes   -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 route. For more information, see Endpoints.

For example, you can run the following cURL request to get information about the routes that are defined in US South:

curl -X GET   https://private.us-south.atracker.cloud.ibm.com/api/v2/routes    -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"

HTTP response codes

When you use the 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 route 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 Routes.
6. Click Create to open the create page.
7. Enter a meaningful name for the route.
8. In Routing rules, modify Rule 1:
   • Send audit events from: Select the auditing event locations that will match this rule.
   • To targets: Select a target that will be attached to this rule. Click Add target to add more targets to the rule.
9. Click Add rule to add additional rules to the route.
   • The order of route rules affects the routing behavior. Rules are processed in order and once a rule is matched, the subsequent rules are not processed.
10. Each rule has an up and down arrow that lets you to change the rule order.
11. Each rule has a Remove button that lets you delete a rule from a route.
12. Review the route definition ensuring the order of the rules is as intended.
13. Click Create.

Updating a route 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 Routes.
6. Determine which route to update and click the .
7. Click Rename to rename the route.
8. Click Edit to update the route rules.
9. If desired, edit the existing rules:
   • Send audit events from: Select the auditing event locations that will match this rule.
   • To targets: Select a target that will be attached to this rule. Click Add target to add more targets to the rule.
10. Click Add rule to add additional rules to the route.
    • The order of route rules affects the routing behavior. Rules are processed in order and once a rule is matched, the subsequent rules are not processed.
11. Each rule has an up and down arrow that lets you to change the rule order.
12. Each rule has a Remove button that lets you delete a rule from a route.
13. Click Update to make changes to your route.

Viewing a route 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 Routes.
6. The routes table is ordered by creation date. The order of the routes does not affect the routing behavior.
7. Each route block displays the route name and rules.
8. The routes page also displays Routing guidance with additional information about configuring routing.

Deleting a route 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 Routes.
6. Determine which route to update and click the .
7. Click Delete to delete the entire route. You must enter the route name before the route is deleted.