Manual migration from v1 to v3 for existing accounts (With V1 Setup)

If you prefer to manually configure your v3 environment, the process differs depending on whether you have an existing v1 setup or are starting fresh with a new account.

If you have an existing v1 configuration and want to manually migrate to v3, follow these steps:

Before you begin

You must have the administrator platform role to migrate from V1 to V3. For more information about IAM roles and permissions, see IAM roles.
Read about migration scenarios. For more information, see Common Migration Scenarios.
Choose a migration approach. For more information, see Migration Approaches.
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 a V3 configuration from your existing V1 configuration

The current migration process requires that you begin the migration by generating a configuration from the existing V1 setup. This step will create routes and targets based on the V1 targets.

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

Once the routes and targets are generated, review the generated configurations.

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: Create Targets

Create target destinations for your v3 configuration:

For more information, see Create target and Creating a target.

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

Where:

<NAME> is a descriptive name for your target
<CRN> is the Cloud Resource Name of your destination IBM Cloud Logs instance

Save the target ID from the response for use in the next step. Repeat this step for each target you need based on your migration scenario.

Step 5: Create Routes

Create routes to define how logs should be directed to your targets:

For detailed information about route configuration options, including filtering capabilities, see Create route and Creating a route.

curl -X POST \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/routes" \
  -H "Authorization: Bearer <IAM_TOKEN>" \
  -H 'content-type: application/json' \
  -d '{
    "name": "<NAME>",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "<TARGET_ID>"
          }
        ]
      }
    ]
  }'

Where:

<NAME> is a descriptive name for your route
<TARGET_ID> is the target ID from the previous step

You can add filters to customize log routing. For example, to route logs from specific regions:

curl -X POST \
  "https://api.<region>.logs-router.cloud.ibm.com/v3/routes" \
  -H "Authorization: Bearer <IAM_TOKEN>" \
  -H 'content-type: application/json' \
  -d '{
    "name": "<NAME>",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "<TARGET_ID>"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "in",
            "values": ["us-south", "us-east"]
          }
        ]
      }
    ]
  }'

Step 6: 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 7: Complete the migration by switching to V3

Once you have configured all your v3 targets and routes, switch your account to use the v3 API version.

This action is irreversible and will migrate your account from v1 to v3.

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

After running this command:

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

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.

Manual migration from v1 to v3 for existing accounts (With V1 Setup)

Manual migration from v1 to v3 for existing accounts (With V1 Setup)

Before you begin

Step 1: Set Primary Metadata Region

Step 2: Generate a V3 configuration from your existing V1 configuration

Step 3: Check Migration Status

Step 4: Create Targets

Step 5: Create Routes

Step 6: Review Generated Targets and Routes

Review targets

Review routes

Step 7: Complete the migration by switching to V3

Next