IBM Cloud Docs
About routes

About routes

You can manage routes in your account by using the IBM Cloud Metrics Routing UI, the IBM Cloud Metrics Routing CLI, the IBM Cloud Metrics Routing REST API, and the IBM Cloud Metrics Routing Terraform provider. A route defines the rules that indicate what metrics 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® Metrics Routing is deployed.

  • You can define a route from any of the supported locations where IBM Cloud Metrics Routing is available. For more information, see Locations.

  • Routes may be accessed from any regional IBM Cloud Metrics 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 metric data, that data will be sent to multiple targets.

  • Rules in 1 route definition are processed in order. The first matching rule (for example, location) that matches metrics data is used to process that data. When metrics are processed, they will not be processed by a subsequent rule within that route's definition. If you want to specify a default rule for all metrics that are not processed by other rules, you would specify the rule ("locations" : ["*"]) as the final rule in your rules definition for the route.

  • If metrics data doesn't match any rule and no default target is configured, the metrics 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.

    If you do not configure a primary metadata location, the location is set to the location where you define your first target in the account. For more information, see Configuring account settings.

  • 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://private.REGION.metrics-router.cloud.ibm.com

    • You can manage routes from the public network by using an API endpoint with the following format: https://REGION.metrics-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 Metrics 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 metrics-router.route.create Account Administrator
Editor
List all routes metrics-router.route.list Account Administrator
Editor
Operator
Viewer
Get details of a route metrics-router.route.read Account Administrator
Editor
Operator
Viewer
Modify a route metrics-router.route.update Account Administrator
Editor
Delete a route metrics-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 Tracker auditing event actions
Task Activity Tracker auditing event action
Create a route metrics-router.route.create
List all routes metrics-router.route.list
Get details of a route metrics-router.route.read
Modify a route metrics-router.route.update
Delete a route metrics-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 Metrics Routing CLI.

Managing routes using the UI

You can manage your route definition using the IBM Cloud Metrics 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 metrics-router route create
Update a route ibmcloud metrics-router route update
Delete a route ibmcloud metrics-router route rm
Read a route ibmcloud metrics-router route get
List all routes ibmcloud metrics-router route ls

For more information, see IBM Cloud Metrics 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 Metrics Routing REST API
Action REST API Method API_URL
Create a route POST <ENDPOINT>/api/v3/routes
Update a route PATCH <ENDPOINT>/api/v3/routes/<ROUTE_ID>
Delete a route DELETE <ENDPOINT>/api/v3/routes/<ROUTE_ID>
Get information about a route GET <ENDPOINT>/api/v3/routes/<ROUTE_ID>
List all routes GET <ENDPOINT>/api/v3/routes

For more information about the REST API, see Routes.

HTTP response codes

When you use the IBM Cloud Metrics 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 Metrics Routing processing.