Skip to content

Latest commit

 

History

History
275 lines (198 loc) · 12.5 KB

tenant-create.md

File metadata and controls

275 lines (198 loc) · 12.5 KB
Raw
copyright lastupdated keywords subcollection
years
2023, 2024
2024-10-23
logs-router

{{site.data.keyword.attribute-definition-list}}

Creating a tenant and a target destination

{: #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}

Before you begin

{: #tenant-create-prereqs}

Complete the following steps:

Retrieving the IAM bearer token

{: #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}

Choosing the management endpoint

{: #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.

Creating a tenant and target through the UI

{: #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:

  1. Log in to your {{site.data.keyword.cloud_notm}} account{: external}.

  2. Click the Menu icon Menu icon > Observability.

  3. Click Logging > Routing.

  4. Click Set target.

  5. 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 Menu icon > 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}}.

  6. 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}

Creating a tenant and target by using the API

{: #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.

{{site.data.keyword.logs_full_notm}} 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.

{{site.data.keyword.la_full_notm}} destination

{: #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.

Creating a tenant and target by using Terraform

{: #tenant-create-tf} {: terraform}

{{site.data.keyword.logs_full_notm}} destination

{: #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.

{{site.data.keyword.la_full_notm}} destination

{: #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.