Migration Guide: Automated Migration from v1 to v3

The automated migration process uses the migration APIs to generate v3 targets and routes based on your existing v1 tenant configuration.

This approach streamlines the migration by automatically creating the necessary v3 resources.

Before you begin

  1. You must have the administrator platform role to migrate from V1 to V3. For more information about IAM roles and permissions, see IAM roles.

  2. Read about migration scenarios. For more information, see Common Migration Scenarios.

  3. Choose a migration approach. For more information, see Migration Approaches.

  4. Learn about the migration states. For more information, see Migration states.

During the migration process, there will be a brief interruption period (typically a few minutes) during which platform logs will not be received. Plan your migration accordingly to minimize the impact on your operations.

WARNING: This migration is irreversible. Once you have migrated to v3, you cannot move back to v1.

Step 1: Set Primary Metadata Region

Configure the primary metadata region for your v3 setup:

curl -X PATCH \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/settings" \
  -H "Authorization: Bearer <IAM_TOKEN>" \
  -H 'content-type: application/json' \
  -d '{
    "primary_metadata_region": "<region>"
  }'

Where <region> is your desired region such as us-south, or eu-de.

For detailed information about this API endpoint, see Modify settings

Step 2: Generate the Migration Plan

The first step is to generate a migration plan.

This is an asynchronous process that analyzes your existing v1 tenants and creates corresponding v3 targets and routes.

Run the following API call to generate the migration plan:

curl -X POST \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/migrate?action=generate" \
  -H "Authorization: Bearer <IAM_TOKEN>"

Where <region> is your primary metadata region.

The authorization bearer token must have the logs-router.migration.post permission. The Administrator role for the IBM Cloud Logs Routing service has this permission. For more information, see IAM roles.

Step 3: Check Migration Status

After initiating the migration plan generation, you need to monitor its progress. Continue checking the status until the state changes to PENDING_COMPLETION.

Use the following API call to check the status:

curl -X GET \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/migrate" \
  -H "Authorization: Bearer <IAM_TOKEN>"

The authorization bearer token must have the logs-router.migration.get permission. The following roles have this permission: Administrator, Editor, Operator, or Viewer role.

The API will return one of the following responses based on the current state:

  • COMPLETE state (HTTP 200 OK):

    {
  "version": "3",
  "state": "COMPLETE",
  "message": "Migration complete"
}

  • BEFORE state (HTTP 200 OK):

    {
  "version": "1",
  "state": "BEFORE",
  "message": "Error message with reason for previous failure"
}

    If the message is empty, no previous migration attempt has been made or failed.

  • IN_PROGRESS state (HTTP 200 OK):

    {
  "version": "1",
  "state": "IN_PROGRESS",
  "message": "The migration process is still running - check back in a few minutes"
}

  • PENDING_COMPLETION state (HTTP 200 OK):

    {
  "version": "1",
  "state": "PENDING_COMPLETION",
  "message": "Your v3 routes and targets have been created - verify the content and then use action=complete to switch your account permanently to the v3 configuration."
}

Step 4: Review Generated Targets and Routes

Once the migration reaches the PENDING_COMPLETION state, you should review the automatically generated v3 targets and routes to ensure they match your requirements.

Review targets

To list all targets, use the following API call:

curl -X GET \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/targets" \
  -H "Authorization: Bearer <IAM_TOKEN>"

For more information, see List targets.

Review routes

To list all routes, use the following API call:

curl -X GET \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/routes" \
  -H "Authorization: Bearer <IAM_TOKEN>"

For more information, see List routes.

Step 5: Modify Configuration (Optional)

If you need to make changes to the generated targets or routes, you can update them using the v3 API endpoints before completing the migration.

Modify a target

To update a target, use the following API call:

curl -X PATCH \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/targets/<target_id>" \
  -H "Authorization: Bearer <IAM_TOKEN>" \
  -H 'content-type: application/json' \
  -d '{
    "name": "<NEW_NAME>"
  }'

For detailed information, see Update target and Updating a target.

Modify a route

To update a route, use the following API call:

curl -X PATCH \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/routes/<route_id>" \
  -H "Authorization: Bearer <IAM_TOKEN>" \
  -H 'content-type: application/json' \
  -d '{
    "name": "<NEW_NAME>",
    "rules": [...]
  }'

For more information, see Update route and Updating a route.

Step 6: Delete Migration Plan (Optional)

If you need to start over or cancel the migration, you can delete the generated migration plan. This will remove all automatically created v3 targets and routes.

Run the following API call to delete the migration plan:

curl -X DELETE \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/migrate" \
  -H "Authorization: Bearer <IAM_TOKEN>"

The authorization bearer token must have the logs-router.migration.delete permission. The Administrator role for the IBM Cloud Logs Routing service has this permission. For more information, see IAM roles.

After deleting the migration plan, you can start the process again from Step 1.

Step 7: Complete the migration by switching to V3

Once you have reviewed the generated v3 configuration, you can complete the migration. This action is irreversible and will switch your account from v1 to v3.

Run the following API call to complete the migration:

curl -X POST \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/migrate?action=complete" \
  -H "Authorization: Bearer <IAM_TOKEN>"

The authorization bearer token must have the logs-router.migration.post permission. The Administrator role for the IBM Cloud Logs Routing service has this permission. For more information, see IAM roles.

After running this command:

  1. The v1 service will shut down and stop processing logs.
  2. The v3 service will become active and begin routing logs according to your new configuration.

Next

You have successfully migrated from IBM Cloud Logs Routing v1 to v3. Your platform logs are now being routed according to your v3 configuration.

If you encounter any issues or need to make changes to your routing configuration, refer to the IBM Cloud Logs Routing v3 API documentation for guidance on updating settings, targets, and routes.