About routes

You can manage routes in your account by using the IBM Cloud Logs Routing UI, the IBM Cloud Logs Routing CLI, the IBM Cloud Logs Routing REST API V3, and the IBM Cloud Logs Routing Terraform provider. A route defines the rules that indicate what platform logs are routed in a region and where to route them.

Understanding how routes work in your account

Note the following information about routes:

  • Routes are global under an account and are evaluated in all regions where IBM Cloud Logs Routing is deployed.

  • Routes may be accessed from any regional IBM Cloud Logs Routing API endpoint.

  • You can define up to 30 routes for an account.

  • By default, the account has 0 routes configured.

  • You can configure up to 10 rules for each route.

  • You can configure up to 8 locations for each rule.

  • You can configure up to 3 targets ({ "targets": [{ "id": ID1 },{ "id": ID2 },{ "id": ID3 }] }) for each rule.

  • Routes are processed independently. If you have multiple routes with rules that match the same platform log data, that data will be sent to multiple targets.

  • Rules in a single route definition are processed in order. The first matching rule (for example, location) that matches platform logs data is used to process that data. When platform logs are processed, they will not be processed by a subsequent rule within that route's definition.

  • Rules will match a platform log if the platform log's location is within a rule location. For example, rule location eu-de will match platform log locations: eu-de, eu-de-1, eu-de-2, and eu-de-3. Or rule location jp will match all platform logs within Japan. Run ibmcloud catalog locations to see the Cloud location hierarchies.

  • If platform logs data doesn't match any rule and no default target is configured, the platform logs are dropped and not routed to any target.

  • Any update to 1 or more rules in a route definition discards the existing rule set and replaces it with the specified configuration. When you update a route, you must define all existing rules in the rule set that do not change and add the changes to the rules that must be updated.

  • Information about routes is stored as metadata in the primary location that you have set for the IBM Cloud account.

  • 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 by using an API endpoint with the following format: https://api.private.REGION.logs-router.cloud.ibm.com

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

    • You can disable the public endpoints by updating the account settings. For more information, see Enforcing private endpoints.

  • The route name must be 1000 characters or less and cannot include any special characters other than space, dash -, dot ., underscore _, and colon :.

    The name must not include any personal identifying information (PII).

After you configure a route, it might take up to 1 hour for the configuration to be enabled.

IAM Access

Ensure you have the correct IAM permissions to configure IBM Cloud Logs Routing.

IAM permissions

The following table lists the IAM actions, their scope and the roles required to manage routes.

IAM action scopes and roles for managing routes
Task IAM Action IAM Policy scope IAM Roles
Create a route logs-router.route.create Account Administrator
Editor
List all routes logs-router.route.list Account Administrator
Editor
Operator
Viewer
Get details of a route logs-router.route.read Account Administrator
Editor
Operator
Viewer
Modify a route logs-router.route.update Account Administrator
Editor
Delete a route logs-router.route.delete Account Administrator
Editor

Auditing events

The following table lists the IAM actions, their scope and the roles required to manage routes.

Activity tracking auditing event actions
Task Activity tracking auditing event action
Create a route logs-router.route.create
List all routes logs-router.route.list
Get details of a route logs-router.route.read
Modify a route logs-router.route.update
Delete a route logs-router.route.delete

CLI prerequisites

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

  1. Install the IBM Cloud CLI.

  2. Install the IBM Cloud Logs Routing CLI.

Managing routes using the UI

You can manage your route definition using the IBM Cloud Logs Routing UI. For more information, see Managing routes.

CLI commands

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

Route actions
Action Command
Create a route ibmcloud logs-router route create
Update a route ibmcloud logs-router route update
Delete a route ibmcloud logs-router route delete
Read a route ibmcloud logs-router route get
List all routes ibmcloud logs-router route list

For more information, see IBM Cloud Logs Routing v3 CLI.

API prerequsites

Before you use the API 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.

API methods

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

Route actions by using the IBM Cloud Logs Routing REST API
Action REST API Method API_URL
Create a route POST <ENDPOINT>/v3/routes
Update a route PATCH <ENDPOINT>/v3/routes/<ROUTE_ID>
Delete a route DELETE <ENDPOINT>/v3/routes/<ROUTE_ID>
Get information about a route GET <ENDPOINT>/v3/routes/<ROUTE_ID>
List all routes GET <ENDPOINT>/v3/routes

For more information about the REST API, see Routes.

HTTP response codes

When you use the IBM Cloud Logs 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:

List of HTTP response codes
Status code Status Description
200 OK The request was successful.
201 OK The request was successful. A resource is created.
204 OK The route was successfully deleted.
400 Bad Request The request was unsuccessful. You might be missing a parameter that is required.
401 Unauthorized The IAM token that is used in the API request is invalid or expired.
403 Forbidden The operation is forbidden due to insufficient permissions.
404 Not Found The requested resource doesn't exist or is already deleted.
429 Too Many Requests Too many requests reach the API too quickly.
500 Internal Server Error Something went wrong in IBM Cloud Logs Routing processing.