copyright | lastupdated | keywords | subcollection | ||
---|---|---|---|---|---|
|
2024-10-23 |
logs-router |
{{site.data.keyword.attribute-definition-list}}
{: #tenant-create}
To manage platform logs that are generated by {{site.data.keyword.cloud}} services in a region of {{site.data.keyword.cloud_notm}}, you must create a tenant in each region that you operate. {: shortdesc}
{{site.data.content.tenant_definition_note}}
The create request requores that you create a target destination when you create the tenant in a region. {: important}
{: #tenant-create-prereqs}
Complete the following steps:
-
Review About {{site.data.keyword.logs_routing_full}} 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 {{site.data.keyword.logs_routing_full_notm}} by using the management API. For more information, see Connecting to {{site.data.keyword.logs_routing_full}}.
{: #tenant-create-retrieve-iam-token-cli}
You must get an {{site.data.keyword.iamlong}} (IAM) access token to authenticate your requests to the {{site.data.keyword.logs_routing_full}} 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'`
{: pre}
{: #tenant-create-endpoint}
A tenant is the account-specific configuration of {{site.data.keyword.logs_routing_full_notm}} 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. {: important}
You can use private or public endpoints.
For more information, see Management endpoint URLs.
{: #tenant-create-ui} {: ui}
When the {{site.data.keyword.logs_routing_full_notm}} console is first displayed, any existing target information is displayed.
If no target is configured for a region, the region displays the Set target option. When the target is set for the first time, an {{site.data.keyword.logs_routing_full_notm}} tenant is created (onboarded) and the target configured.
To create a tenant and a target for a region, complete the following steps:
-
Log in to your {{site.data.keyword.cloud_notm}} account{: external}.
-
Click Logging > Routing.
-
Click Set target.
-
Select an {{site.data.keyword.logs_full_notm}} instance or an {{site.data.keyword.la_full_notm}} instance. This is the instance where you want to receive logs that are routed by {{site.data.keyword.logs_routing_full_notm}}.
You can select an {{site.data.keyword.la_full_notm}} instance by selecting an instance from the list and an ingestion key. Only {{site.data.keyword.la_full_notm}} instances in your account can be selected by name and ingestion key. If you want to route to an {{site.data.keyword.la_full_notm}} instance in another account, you must select the target by CRN (Cloud Resource Name) and ingestion key. The CRN of an {{site.data.keyword.la_full_notm}} instance can be found by the account administrator of the {{site.data.keyword.la_full_notm}} instance by clicking > Resource list and clicking the {{site.data.keyword.la_full_notm}} instance. The CRN can be copied from the Details section.
You can select a {{site.data.keyword.logs_full_notm}} instance from the list. Before you do, check that you have a service to service authorization defined between the {{site.data.keyword.logs_routing_full_notm}} service and the {{site.data.keyword.logs_full_notm}} instance. For more information, see Creating a S2S authorization to grant access to send logs to {{site.data.keyword.logs_full_notm}}.
-
Click Save.
When you set a target in the UI, you create a tenant in that region. The name of the tenant is set as region-ID
where region is set to the region where you are located when you create the target.
{: note}
{: #tenant-create-api} {: api}
Run the following command to create a tenant for the {{site.data.keyword.logs_routing_full_notm}} 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}'
{: pre}
Run the following command to create a tenant for the {{site.data.keyword.logs_routing_full_notm}} 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 '{TARGET_DATA}'
{: pre}
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-create-api-logs} {: api}
For a target that defines an {{site.data.keyword.logs_full_notm}} destination, the TARGET_DATA
format is as follows:
{
"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
}
}
]
}
{: codeblock}
Where
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 {{site.data.keyword.logs_full_notm}} 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. For example,443
.
{: #tenant-create-api-la} {: api}
For a target that defines an {{site.data.keyword.la_full_notm}} destination, the TARGET_DATA
format is as follows:
{
"name": "tenant",
"targets": [
{
"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"
}
}
]
}
{: codeblock}
Where
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,-./
LOG_ANALYSIS_INGESTION_ENDPOINT
is the {{site.data.keyword.la_full_notm}} endpoint in the region where you plan to collect logs. For more information, see Endpoints.LOG_ANALYSIS_INSTANCE_TARGET_PORT
defines the port to use. For example,443
.INGESTION_KEY_TO SEND_DATA_TO_INSTANCE
defines the ingestion key to use to route the data to this destination.
{: #tenant-create-tf} {: terraform}
{: #tenant-create-tf-logs} {: terraform}
To create tenant with a target of type logs
, use the following:
provider "ibm" {
ibmcloud_api_key = "IBMCLOUD_API_KEY"
region = "some-region"
}
resource "ibm_logs_router_tenant" "logs_router_tenant_instance_1" {
name = "TENANT_NAME"
region = "TENANT_REGION"
targets {
log_sink_crn = "CLOUD_LOGS_INSTANCE_CRN"
name = "TARGET_NAME"
parameters {
host = "CLOUD_LOGS_INSTANCE_INGRESS_ENDPOINT"
port = CLOUD_LOGS_INSTANCE_TARGET_PORT
}
}
}
{: codeblock}
Where
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,-./
TENANT_REGION
: Region to create the tenant. The value must be in the format of a two-letter code for the region followed by a dash and the three-letter code for the zone (for example,us-south
). For a list of regions, see Locations.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
: The CRN of the {{site.data.keyword.logs_full_notm}} instance.CLOUD_LOGS_INSTANCE_INGRESS_ENDPOINT
: The full qualified ingress endpoint for the destination of logs.CLOUD_LOGS_INSTANCE_TARGET_PORT
: Defines the port to use. For example,443
.IBMCLOUD_API_KEY
: This is used to obtain an IAM token to create the tenant. The tenant will be created for the account that issued this API key.
{: #tenant-create-tf-la} {: terraform}
To create tenant with a target of type logdna
, use the following:
provider "ibm" {
ibmcloud_api_key = "IBMCLOUD_API_KEY"
region = "some-region"
}
resource "ibm_logs_router_tenant" "logs_router_tenant_instance_1" {
name = "TENANT_NAME"
region = "TENANT_REGION"
targets {
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"
}
}
}
{: codeblock}
Where
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,-./
TENANT_REGION
: Region to create the tenant. The value must be in the format of a two-letter code for the region followed by a dash and the three-letter code for the zone (for example,us-south
). For a list of regions, see Locations.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,-./
LOG_ANALYSIS_INGESTION_ENDPOINT
: The {{site.data.keyword.la_full_notm}} endpoint in the region where you plan to collect logs. For more information, see Endpoints.LOG_ANALYSIS_INSTANCE_TARGET_PORT
: Defines the port to use. For example,443
.INGESTION_KEY_TO SEND_DATA_TO_INSTANCE
: Defines the ingestion key to use to route the data to this destination.IBMCLOUD_API_KEY
: This is used to obtain an IAM token to create the tenant. The tenant will be created for the account that issued this API key.