Configuring account settings

You can configure the Activity Tracker Event Routing account settings in your account by using the Activity Tracker Event Routing CLI, the Activity Tracker Event Routing REST API, and Terraform scripts. Set these settings to define where and how auditing events are collected, routed, and managed in your account.

When you configure or modify the Activity Tracker Event Routing account settings, consider the following information:

Every time you modify the Activity Tracker Event Routing account settings, the data that is passed in the new request replaces any existing configuration data. You must ensure that any existing data is not deleted when you run an update of the account settings by including it in the new request.
Before you disable public endpoints by setting --private-api-endpoint-only TRUE, make sure your account has access to the private endpoint. You can do this by running the command ibmcloud account show. If VRF Enabled is true and Service Endpoint Enabled is true then you have access to the private endpoint. If you do not have access to the private endpoint, you will be unable to re-enable the public endpoint since private endpoint access is required to re-enable the public endpoint.

What data can you configure through the IBM Cloud® Activity Tracker Event Routing account settings?

You can define any of the following information:

The location in your IBM Cloud account where the Activity Tracker Event Routing account configuration metadata is stored.

By metadata, we refer to the target/route/settings data that is available across the account in any region.

You can choose any of the supported locations where Activity Tracker Event Routing is available. For more information, see Locations.

Take into account any corporate or industry compliance requirements such as Financial Services Validated locations, or EU-managed regions.
The type of endpoints that are allowed to manage the Activity Tracker Event Routing account configuration in the account.

You can configiure public endpoints, private endpoints, or both.
The locations where an account administrator can define targets to collect auditing events.

You can choose any of the supported locations where Activity Tracker Event Routing is available. For more information, see Locations.

Take into account any corporate or industry compliance requirements such as Financial Services Validated locations, or EU-managed regions.
1 or more targets in the account that will collect auditing events from supported Activity Tracker Event Routing locations where you have not configured how you want to collect the auditing data.

If you define more than 1 target, all default targets get a copy of auditing events that do not have a routing rule to indicate where to collect them in the account. You can define up to 2 default targets per account.

IAM permissions

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

When you define a policy, you can must set the scope of the policy to the account. A route is a global resource that is not bound to a specific region.

Table 1. Required IAM roles
IAM action	IAM Policy scope	IAM Roles	Description
`atracker.setting.get`	Account	`Administrator` `Editor` `Viewer` `Operator`	Get settings information
`atracker.setting.update`	Account	`Administrator`	Update settings

CLI prerequisites

Before you use the the CLI to manage Activity Tracker Event Routing account settings, Install the IBM Cloud Activity Tracker Event Routing CLI.

Check that you have IAM permissions to read, update, or both the Activity Tracker Event Routing account settings.

Getting account settings using the CLI

Use this command to get the settings for the IBM Cloud Activity Tracker Event Routing account configurations.

ibmcloud atracker setting get [--output FORMAT]

Command options

--output FORMAT: If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.
help | --help | -h: List options available for the command.

Example

The following is an example where no default or permitted targets have been set and the API version is V2.

Atracker settings
Metadata region primary:     us-south
Metadata region backup:      us-east
Default targets:             []
Permitted target regions:    []
Private api endpoint only:   false
API version:                 2

Updating settings using the CLI

Use this command to modify current account settings such as the default targets, permitted target regions, and the primary metadata region.

ibmcloud atracker setting update [--metadata-region-primary REGION] [--metadata-region-backup REGION] [--default-targets TARGET] [--permitted-target-regions REGIONS] [--private-api-endpoint-only ( TRUE | FALSE )] [--output FORMAT] [--force]

Command options

default-targets: Is a list of target IDs. If no routing rules cause events to be sent to other targets, these targets will received the events. TARGETS is a comma-separated list of target IDs.
permitted-target-regions: Is the list of regions that can be used to define a target. REGIONS is a comma-separated list of regions. A maximum of two permitted target regions can be specified.
metadata-region-primary: Specify the REGION where the metadata associated with route and target definitions is stored.
metadata_region_backup: Is the region where the metadata associated with route and target definitions is stored as a backup location.
private-api-endpoint-only: Specifies whether nor not a private endpoint can be used. If true only a private endpoint can be used.
--output FORMAT: If JSON specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.
help | --help | -h: List options available for the command.

If the update is successful, the current settings will be displayed.

API settings and actions

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

Table 1. Settings actions by using the IBM Cloud Activity Tracker Event Routing REST API
Action	REST API Method	API_URL
Get settings information	`GET`	`<ENDPOINT>/api/v2/settings`
Update settings	`PUT`	`<ENDPOINT>/api/v2/settings`

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

By default, you can manage settings from the private network. You must use an API endpoint with the following format: https://private.<region>.atracker.cloud.ibm.com
You can also enable public endpoints in a region to manage settings. For more information, see Managing endpoints.

For more information about the REST API, see the settings API.

API prerequsites

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

Getting settings using the API

You can use the following cURL command to get existing settings information:

curl -X GET  ENDPOINT/api/v2/settings   -H "Authorization:  $ACCESS_TOKEN"

Where:

ENDPOINT: Is the API endpoint in the region where you plan to configure or manage a target. For more information, see Endpoints.

For example, you can use the following cURL request settings information the US South region:

curl -X GET   https://private.us-south.atracker.cloud.ibm.com/api/v2/settings   -H "Authorization:  $ACCESS_TOKEN"

A response similar to the following is returned:

{
 "default_targets": ["50375218-0000-4234-bbb4-171bebab8408", "c7519d8a-5f97-498b-0000-8542f60955cd"],
 "permitted_target_regions": ["us-south", "us-east"],
 "metadata_region_primary": "us-south",
 "metadata_region_backup": "eu-de",
 "private_api_endpoint_only": false
}

Where:

default_targets: Is a list of target IDs. If no routing rules cause events to be sent to other targets, these targets will received the events.
permitted_target_regions: Is the list of regions that can be used to define a target. A maximum of two permitted target regions are allowed.
metadata_region_primary: Is the region where the metadata associated with route and target definitions is stored.
metadata_region_backup: Is the region where the metadata associated with route and target definitions is stored as a backup location.
private_api_endpoint_only: Specifies whether nor not a private endpoint can be used. If true only a private endpoint can be used.

Updating settings using the API

When you update settings, you must include the settings 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 settings:

curl -X PUT  <ENDPOINT>/api/v2/settings
-H "Authorization:  $ACCESS_TOKEN"
-H "content-type: application/json"
-d '{
   "default_targets": ["IDs"],
   "permitted_target_regions": ["REGIONS"],
   "metadata_region_primary": "REGION",
   "metadata_region_backup": "REGION",
   "private_api_endpoint_only": false
}'

Where:

ENDPOINT: Is the API endpoint in the region where you plan to configure or manage a target. For more information, see Endpoints.
default_targets: Is a list of target IDs. If no routing rules cause events to be sent to other targets, these targets will received the events.
permitted_target_regions: Is the list of regions that can be used to define a target. A maximum of two permitted target regions can be specified.
metadata_region_primary: Is the region where the metadata associated with route and target definitions is stored.
metadata_region_backup: Is the region where the metadata associated with route and target definitions is stored as a backup location.
private_api_endpoint_only: Specifies whether nor not a private endpoint can be used. If true only a private endpoint can be used.

HTTP response codes

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

Table 2. 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.
`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 hit the API too quickly.
`500`	Internal Server Error	Something went wrong in IBM Cloud Activity Tracker Event Routing processing.