About targets

You can manage IBM Cloud Logs targets in your account by using the IBM Cloud Logs Routing UI, CLI, REST API V3, and Terraform scripts. A target is a resource where you can route platform logs that are generated in an IBM Cloud account.

Understanding how targets work in your account

Note the following information about targets:

  • You can define up to 16 targets in each account. Each account can have up to 2 default targets.

  • A target defines a resource where platform logs are collected. Routes define how platform logs that are generated in the account are routed to the targets that you configure.

  • You can define a target in any of the supported locations where IBM Cloud Logs Routing is available. For more information, see Locations.

  • Targets are created within a region but are visible across regions. That is, all targets can be accessed by any IBM Cloud Logs API endpoint.

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

    • You can manage targets from the public network 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.

Target types

You can configure any of the following target types:

List of targets
Target Type Learn more
IBM Cloud Logs cloud_logs Managing IBM Cloud Logs targets

IAM Access

You must grant users IAM permissions to manage targets. For more information, see Assign access to resources.

When you define a policy, you can indicate the scope of the permissions. You can choose from granting permissions for a specific region or for the entire account.

If you have the IAM permission to create policies and authorizations, you can grant only the level of access that you have as a user of the target service. For example, if you have viewer access for the target service, you can assign only the viewer role for the authorization. If you attempt to assign a higher permission such as administrator, it might appear that permission is granted, however, only the highest level permission you have for the target service, that is viewer, will be assigned.

Users with regional scope will be limited to access targets in their authorized region.

IAM actions and the IAM roles that include them.
IAM action IAM Policy scope IAM Roles Description
logs-router.target.read Region Administrator
Editor
Viewer
Operator		 Read (view) information about a target
logs-router.target.create Region Administrator
Editor		 Create a target
logs-router.target.update Region Administrator
Editor		 Update a target
logs-router.target.delete Region Administrator
Editor		 Delete a target
logs-router.target.list Account Administrator
Editor
Viewer
Operator		 List all targets

Authentication

When writing to a IBM Cloud Logs target, you must configure a service-to-service (S2S) authorization between IBM Cloud Logs Routing and IBM Cloud Logs.

Choose 1 of the following options:

Validating targets

When you validate a target, you check that the credentials that are configured for a target are valid. These credentials are used by IBM Cloud Logs Routing to authenticate with the destination target.

You can validate a target by using the IBM Cloud Metrics Routing CLI, the IBM Cloud Metrics Routing REST API, and Terraform scripts.

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 Logs Routing CLI.

CLI commands

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

Target actions by using the IBM Cloud Logs RoutingEvent Routing CLI
Action Command
Create a target ibmcloud logs-router target create
Update a target ibmcloud logs-router target update
Delete a target ibmcloud logs-router target delete
Read a target ibmcloud logs-router target get
List all targets ibmcloud logs-router target list

For more information, see IBM Cloud Logs Routing CLI.

API targets and actions

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 API Endpoints.
Target actions by using the IBM Cloud Logs Routing REST API
Action REST API Method API_URL
Create a target POST <ENDPOINT>/v3/targets
Update a target PATCH <ENDPOINT>/v3/targets/<TARGET_ID>
Delete a target DELETE <ENDPOINT>/v3/targets/<TARGET_ID>
Read a target GET <ENDPOINT>/v3/targets/<TARGET_ID>
List all targets GET <ENDPOINT>/v3/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://api.private.REGION.logs-router.cloud.ibm.com

  • You can manage targets from the public network 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 Configuring target and region settings.

For more information about the REST API, see IBM Cloud Logs Routing REST API v3.

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 A list of targets were successfully retrieved.
201 OK The request was successful. A resource is created.
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.
409 Conflict There is a conflict with the request data and the state of resources in system.
429 Too Many Requests Too many requests hit the API too quickly.
500 Internal Server Error Something went wrong. Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Managing targets using the UI

You can manage your IBM Cloud Logs Routing targets, routes, and settings using the IBM Console.

  1. Log in to your IBM Cloud account.
  2. Click the Menu icon Menu icon > Observability.
  3. Select Logging > Routing.

For more information, see Managing IBM Cloud Logs targets.