Creating a tenant with 2 target destinations

To manage platform logs that are generated by IBM Cloud® services in a region of IBM Cloud, you can create a tenant in a region that you operate and define up to 2 target destinations where you want to route the data.

A tenant is the account-specific configuration of IBM Cloud Logs Routing running within a region. The tenant configuration includes a maximum of 2 target definitions. The target defines where the logs are routed.

By default, the create request creates the tenant in a region and at least 1 destination. You can create a tenant with up to 2 target destinations. The 2 destinations must be of a different type.

You cannot create 1 tenant and 2 targets in the IBM Cloud Logs Routing console.

Before you begin

Complete the following steps:

Review About IBM Cloud Logs Routing to understand concepts.
Install all prerequisite tools as described in the getting started.
Set up permissions to manage targets in the account. For more information, see Setting up IAM permissions for managing tenants.
To get details on a tenant by using the API, check that you can connect to IBM Cloud Logs Routing by using the management API. For more information, see Connecting to IBM® Cloud Logs Routing.

Retrieving the IAM bearer token

You must get an IBM Cloud® Identity and Access Management (IAM) access token to authenticate your requests to the IBM® Cloud Logs Routing service. For more information, see Retrieving an access token.

For example, you can retrieve your IAM bearer token and export it as an environment variable by running the following CLI command:

export IAM_TOKEN=`ibmcloud iam oauth-tokens --output json | jq -r '.iam_token'`

Choosing the management endpoint

A tenant is the account-specific configuration of IBM Cloud Logs Routing running within a region.

To get the details of a tenant in a region, you must use the management endpoint URL for the region where the tenant is configured.

You can use private or public endpoints.

For more information, see Management endpoint URLs.

Creating a tenant and target by using the API

Run the following command to create a tenant for the IBM Cloud Logs Routing service by using the private endpoint:

curl -X POST  https://management.private.${REGION}.logs-router.cloud.ibm.com/v1/tenants \
-H "Content-Type: application/json" \
-H "Authorization: ${IAM_TOKEN}" \
-H "IBM-API-Version: API_VERSION_DATE" \
--data '{TARGET_DATA}'

Run the following command to create a tenant for the IBM Cloud Logs Routing service by using the public endpoint:

curl -X POST  https://management.${REGION}.logs-router.cloud.ibm.com/v1/tenants \
-H "Content-Type: application/json" \
-H "Authorization: ${IAM_TOKEN}" \
-H "IBM-API-Version: API_VERSION_DATE" \
--data '{
    "name": "TENANT_NAME",
    "targets": [
        {
            "log_sink_crn": "CLOUD_LOGS_INSTANCE_CRN",
            "name": "TARGET_NAME",
            "parameters": {
                "host": "CLOUD_LOGS_INSTANCE_INGRESS_ENDPOINT",
                "port": CLOUD_LOGS_INSTANCE_TARGET_PORT
            }
        },
        {
            "log_sink_crn": "LOG_ANALYSIS_INSTANCE_CRN",
            "name": "TARGET_NAME",
            "parameters": {
                "host": "LOG_ANALYSIS_INGESTION_ENDPOINT",
                "port": `LOG_ANALYSIS_INSTANCE_TARGET_PORT`,
                "access_credential": "INGESTION_KEY_TO SEND_DATA_TO_INSTANCE"
            }
        }
    ]
}'

Where

REGION defines the location where the tenant is configured.
IAM_TOKEN defines the credentials that you use to authenticate your requests.
API_VERSION_DATE defines the date of the API version that you want to use to query your tenant definition. The format must be as follows: YYYY-MM-DD
TARGET_DATA defines the information about the target destination.
TENANT_NAME: Name of the tenant. The name must be unique across tenants for this account and can be up to 35 characters long. The value can only contain these characters: a-z,0-9,-./
TARGET_NAME: Name of the target destination. The name must be unique across all targets in the region and can be up to 35 characters long. The value can only contain these characters: a-z,0-9,-./
CLOUD_LOGS_INSTANCE_CRN is the CRN of the IBM Cloud Logs instance.
CLOUD_LOGS_INSTANCE_INGRESS_ENDPOINT is the full qualified ingress endpoint for the destination of logs.
CLOUD_LOGS_INSTANCE_TARGET_PORT defines the port to use.
LOG_ANALYSIS_INGESTION_ENDPOINT is the IBM Log Analysis endpoint in the region where you plan to collect logs. For more information, see Endpoints.
CLOUD_LOGS_INSTANCE_TARGET_PORT defines the port to use.
INGESTION_KEY_TO SEND_DATA_TO_INSTANCE defines the ingestion key to use to route the data to this destination.

For example, you can run the following sample:


curl -X POST  https://management.us-south.logs-router.cloud.ibm.com/v1/tenants \
--header 'Content-Type: application/json' \
--header "Authorization: ${IAM_TOKEN}" \
--header "IBM-API-Version: 2024-08-28" \
--data '{
    "name": "my dallas-tenant",
    "targets": [
        {
            "log_sink_crn": "crn:v1:bluemix:public:logs:eu-es:a/1234567e6232019c6567c9c8de6dece:dafc3147-484f-4dee-b3c7-5555558e5c7::",
            "name": "my-logs-target",
            "parameters": {
                "host": "dafc3147-484f-4dee-b3c7-5555558e5c7.ingress.private.eu-es.logs.cloud.ibm.com",
                "port": 443
            }
        },
        {
            "log_sink_crn": "crn:v1:bluemix:public:logdna:au-syd:a/1234567e6232019c6567c9c8de6dece:88888888-08ed-49aa-b976-9380ad3d7aed::",
            "name": "my-log-analysis-target",
            "parameters": {
                "host": "logs.us-south.logging.cloud.ibm.com",
                "port": 8080,
                "access_credential": "xxxxxxxxxx"
            }
        }
    ]
    }'