About routes

You can manage routes in your account by using the IBM Cloud® Metrics Routing CLI, IBM Cloud Metrics Routing REST API, and Terraform scripts. 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.

Table 1. 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.

Table 2. 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:

CLI commands

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

Table 3. 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:

Get an IAM access token. For more information, see Retrieving IAM access tokens.
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:

Table 4. 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:

Table 5. 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.