Migration CLI

Use the migration CLI to migrate your IBM® Log Analysis or IBM Cloud Activity Tracker instance configuration to IBM Cloud Logs.

This topic is still very much a work in progress and subject to significant change.

Installing the CLI

Install the IBM Cloud CLI.
Install the CLI by running the following command:
```
ibmcloud plugin install logging
```

You're notified on the command line when updates to the IBM Cloud CLI and plug-ins are available. Be sure to keep your CLI up-to-date so that you can use the most current commands. You can view the current version of all installed plug-ins by running ibmcloud plugin list.

ibmcloud logging migrate generate-terraform

Use this command to create Terraform scripts to create new IBM Cloud Logs instances from existing IBM Log Analysis or IBM Cloud Activity Tracker instances and migrate the Cloud Identity and Access Management permissions that are associated with those instances.

This command does not automatically create the new instances. The Terraform scripts must be used with the Terraform CLI or API to create the new instances. To create new instances directly by using a command, use ibmcloud logging migrate create-resources.

ibmcloud logging migrate generate-terraform --scope SCOPE [--instance-crn CRN] [--service SERVICE] [--iam-scope IAM_ENTITY] [--directory DIRECTORY]

Command options

--scope|-s

The scope of the configuration to be migrated.

account: All IBM Log Analysis or IBM Cloud Activity Tracker instances in the account.
instance: Migrate only a specific instance. Specify the instance type by using --service and the instance CRN by using --instance-crn.
iam: Migrate the Cloud Identity and Access Management permissions that are associated with the account.

--instance-crn|--crn

The CRN of the IBM Log Analysis or IBM Cloud Activity Tracker instance to be migrated. Required when --scope instance is specified. --instance-crn does not apply to other --scope options.

--service|--sv

The type of service to migrate.

logdna: The instance to be migrated is an IBM Log Analysis instance.
logdnaat: The instance to be migrated is an IBM Cloud Activity Tracker instance.

--iam-scope|--is

The Cloud Identity and Access Management configuration to be migrated. Specify only one. If not specified, all is assumed.

all: The entire Cloud Identity and Access Management configuration that is associated with the account is migrated.
users: Only the Cloud Identity and Access Management users configuration is migrated.
trusted-profiles: Only the Cloud Identity and Access Management trusted proviles configuration is migrated.
service-ids: Only the Cloud Identity and Access Management service IDs configuration is migrated.
access-groups: Only the Cloud Identity and Access Management access groups configuration is migrated.
authorizations: Only the Cloud Identity and Access Management authorizations configuration is migrated.

--directory

The directory on your local computer where migration files are written. If not specified, the directory where the command is run is used.

Examples

Generate the Terraform to migrate all IBM Log Analysis and IBM Cloud Activity Tracker instances in the account.

ibmcloud logging migrate generate-terraform --scope account

Generate the Terraform to migrate all IBM Log Analysis and IBM Cloud Activity Tracker instances in the account and write the migration files to the directory specified by DIRECTORY.

ibmcloud logging migrate generate-terraform --scope account --directory DIRECTORY

Generate the Terraform to migrate the single IBM Log Analysis or IBM Cloud Activity Tracker instance that is associated with the CRN value.

ibmcloud logging migrate generate-terraform --scope instance --crn CRN

Generate the Terraform to migrate all IBM Log Analysis or IBM Cloud Activity Tracker instances in the account of the service type SERVICE.

ibmcloud logging migrate generate-terraform --scope account --service SERVICE

Generate the Terraform to migrate the Cloud Identity and Access Management configuration associated with the account.

ibmcloud logging migrate generate-terraform --scope iam

ibmcloud logging migrate create-resources

You can use this command to migrate IBM Log Analysis or IBM Cloud Activity Tracker instances and their associated configurations.

Use this command to create a new IBM Cloud Logs instance from a single existing IBM Log Analysis or IBM Cloud Activity Tracker instance.
Use this command to reconfigure IBM Cloud Activity Tracker Event Routing targets and routes currently configured to IBM Cloud Activity Tracker instances to point to newly created IBM Cloud Logs instances.
Use this command to configure the IBM Cloud Logs instance where platform logs will be sent in the region.. Only one IBM Cloud Logs instance can be configured in each region to receive platform logs.

All IBM Cloud Activity Tracker instances associated with IBM Cloud Activity Tracker Event Routing targets and routes must be migrated to IBM Cloud Logs instances before migrating the IBM Cloud Activity Tracker Event Routing targets and routes.

The command generates Terraform similar to the generate-terraform command and applies the generated Terraform by using a single command.

ibmcloud logging migrate create-resources --scope SCOPE [--instance-crn CRN] [--single] [--instance-name instance-name] [--cos-instance-crn cos-instance-crn] [--cos-kms-key-crn cos-kms-key-crn] [--data-bucket-name data-bucket-name] [--metrics-bucket-name metrics-bucket-name] [--plan-retention plan-retention] [--platform platform] [--instance-resource-group-id instance-resource-group-id] [--region region] [--en-instance-crn en-instance-crn] [--ingestion-key ingestion-key] [--ingress-endpoint-type ingress-endpoint-type] [--api | --terraform] [--directory DIRECTORY] [--predefined-resources] [--force]

Command options

--scope|-s

The scope of the configuration to be migrated.

instance: Migrate only a specific instance. Specify the instance CRN by using --instance-crn.
atracker: Migrate IBM Cloud Activity Tracker Event Routing targets and routes associated with migrated IBM Cloud Activity Tracker instances.
platform-logs: Sets the target IBM Cloud Logs location within the region where platform logs will be sent.

--api|-a

Use the API method to create IBM Cloud Logs instances and resources. If not specified, --terraform is the default.

--terraform|-t

Use the Terraform method to create IBM Cloud Logs instances and resources. If not specified, --terraform is the default.

Terraform is not supported for --scope platform-logs.

--instance-crn|--crn

The CRN of the IBM Log Analysis or IBM Cloud Activity Tracker instance to be migrated.

--instance-name|--cl

The name of the IBM Cloud Logs instance to be created when --scope atracker is specified.

--cos-instance-crn|--cos

The IBM Cloud Object Storage CRN where buckets are created for the IBM Cloud Logs instance when --scope atracker is specified.

--data-bucket-name|--db

The name of the IBM Cloud Object Storage data bucket created for the IBM Cloud Logs instance when --scope atracker is specified.

--metrics-bucket-name|--mb

The name of the IBM Cloud Object Storage metrics bucket created for the IBM Cloud Logs instance when --scope atracker is specified.

--plan-retention|--rp

Sets the Priority insights retention period for the created IBM Cloud Logs instance. Supported values are 30-days, 14-days, or 7-days. If not specified, 7-days will be used.

--platform|-p

If specified, the tool will create a configuration that continues sending logs to your IBM Log Analysis instance while also sending logs to the newly created IBM Cloud Logs instance. This dual destination configuration will help you verify your migration.

--instance-resource-group-id|--rg

The resource group ID to be used when creating the IBM Cloud Logs instance.

--region|-r

The region where IBM Cloud Activity Tracker Event Routing targets will be configured.

--single

Migrate all existing IBM Cloud Activity Tracker instances to 1 IBM Cloud Logs instance.

--instance-resource-group-id|--rg

The resource group ID used when creating the IBM Cloud Logs instance.

--ingress-endpoint-type

Defines the ingress endpoint type of the configured IBM Cloud Logs instance to be used to receive platform logs. Valid values are private and public. If not specified the default is public.

This option is only used when --scope platform-logs is specified.

--en-instance-crn|--ecrn

The CRN of an IBM Cloud Event Notifications instance. Migrated alerts will be configured to be sent to this instance.

If --en-instance-crn is not specified, Terraform files are created to migrate alerts, however manual configuration will have to be done after migration to configure IBM Cloud Event Notifications to receive the alerts. If the --api option is used, and the user does not specify yes when prompted to configure alerting to IBM Cloud Event Notifications, the user will have to manally configure sending alerts to IBM Cloud Event Notifications.

--ingestion-key|-k: The IBM Cloud Activity Tracker or IBM Cloud Logs ingestion key. This key is required to migrate IBM Cloud Activity Tracker Event Routing or IBM Cloud Logs Routing configurations associated with the instance.
--directory|-d: The directory on your local computer where migration files are written. If not specified, the directory where the command is run is used.
--force|-f: Runs the command without further prompting of the user.

Examples

In this example, Terraform is generated for the IBM Log Analysis or IBM Cloud Activity Tracker instance that is indicated by the CRN value and that Terraform applied to create a new IBM Cloud Logs instance.

ibmcloud logging migrate create-resources --scope instance --crn CRN --terraform

In this example, Terraform is generated to migrate IBM Cloud Activity Tracker Event Routing targets and routes associated with migrated IBM Cloud Activity Tracker instances to the newly created IBM Cloud Logs instances.

ibmcloud logging migrate create-resources --scope atracker --terraform

In this example, the API is used to configure the IBM Cloud Logs instance in the region to receive platform logs using a private ingress endpoint.

ibmcloud logging migrate create-resources -s platform-logs -i private

ibmcloud logging migrate query

Use this command to convert IBM Cloud Activity Tracker and IBM Log Analysis view queries to the equivalent Lucene queries that can be used with IBM Cloud Logs.

ibmcloud logging migrate query --input-query input-query

Command options

-input-query|--iq: The IBM Cloud Activity Tracker or IBM Log Analysis view query to be converted, enclosed in double quotes.

Example

For example, running the following command:

ibmcloud logging migrate query -input-query "(host:ibm-cloud-databases-prod label.database:postgresql )  -metrics -unknown client:111.11.111.111"

Returns the query converted to Lucene:

(app:ibm-cloud-databases-prod label.database.keyword:/postgresql.*/ ) NOT metrics NOT unknown client.keyword:/111.11.111.111.*/

ibmcloud logging migrate remove-resources-tf

Use this command to remove an IBM Cloud Logs instance that was created using the migration Terraform files. All associated resources creating during the migration will also be removed. For example, IBM Cloud Object Storage buckets and IBM Cloud® Identity and Access Management authorizations associated with the instance will be removed.

ibmcloud logging migrate remove-resources-tf --scope SCOPE --instance-crn CRN [--directory DIRECTORY]

Command options

--scope|-s

The scope of the configuration to be removed.

instance: Migrate only a specific instance. Specify the instance CRN by using --instance-crn.

--instance-crn|--crn

The CRN of the IBM Cloud Logs instance to be removed.

--directory|-d

The directory on your local computer where the Terraform migration files exist. If not specified, the directory where the command is run is used.

Example

In this example, the IBM Cloud Logs instance specified by the CRN value is removed using the migration Terraform files in the directory where the command is run. All resources associated with the IBM Cloud Logs instance are removed as well.

ibmcloud logging migrate remove-resources-tf --scope instance --crn CRN

ibmcloud logging migrate update-resources

Use this command to update an IBM Cloud Logs instance with IBM Cloud® Identity and Access Management (IAM) configuration information from an IBM Cloud Activity Tracker or IBM Log Analysis instance.

ibmcloud logging migrate update-resources --scope SCOPE [--instance-crn CRN] --cl-instance-crn CL-INSTANCE-CRN [--update-iam] [--api | --terraform] [--directory DIRECTORY] [--force]

Command options

--scope|-s

The collection of resources that will be updated.

instance: Update from a specific instance. Specify the instance CRN by using --instance-crn.

--instance-crn|--crn

The CRN of the IBM Log Analysis or IBM Cloud Activity Tracker instance to be used for the update.

--cl-instance-crn|--clcrn

The CRN of the IBM Cloud Logs instance to be updated with information from the IBM Log Analysis or IBM Cloud Activity Tracker instance specified by --instance-crn.

--update-iam

Specifies that the IBM Cloud Logs instance is to be updated with the IBM Cloud® Identity and Access Management (IAM) configuration information from the IBM Cloud Activity Tracker or IBM Log Analysis instance.

--directory

The directory on your local computer where migration files are written. If not specified, the directory where the command is run is used.

--api|-a

Use the API method to create IBM Cloud Logs instances and resources. If not specified, --terraform is the default.

--terraform|-t

Use the Terraform method to create IBM Cloud Logs instances and resources. If not specified, --terraform is the default.

--force|-f

Runs the command without further prompting of the user.

Examples

In this example the IBM Cloud® Identity and Access Management (IAM) permissions associated with an IBM Cloud Activity Tracker or IBM Log Analysis instance are migrated to the IBM Cloud Logs instance using the API.

ibmcloud logging migrate update-resources --scope instance --instance-crn CRN --cl-instance-crn CLCRN --iam -a

ibmcloud logging migrate update-resources --scope instance --instance-crn CRN --cl-instance-crn CLCRN --iam -t -f