Migration for existing users

Edit online

Migrate your existing watsonx Orchestrate external logging setup on AWS to use Role Chaining and External ID for enhanced security and controlled cross-account access.

If you previously configured external logging for watsonx Orchestrate on AWS, this guide helps you migrate your existing setup to use two security enhancements, role chaining and external ID that provide stronger, more controlled cross-account access to your AWS logging resources.

What is changing and why

Previously, your IAM roles trusted the root of watsonx Orchestrate’s AWS account (239621575091) directly. The new setup introduces:

Role chaining - Instead of trusting IBM's entire AWS account, your IAM roles now trust a specific, tightly scoped watsonx Orchestrate IAM role (logging-processor). This reduces the permission surface and provides better access isolation.

External ID - A unique secret identifier tied to your tenant is added as a condition to your IAM trust policy. This ensures that only IBM's legitimate logging service that presents the correct identifier can assume your role, protecting against unauthorized access.

You can now avail external logging using any one of the following approaches:

With role chaining only
With external ID only
With both role chaining and external ID

What changes in your AWS account

No changes to your S3 bucket or CloudWatch log group configurations.
No changes to log format or delivery frequency.
Required change: Changes the trust policy for the S3 role and CloudWatch role to:
- Set "Principal": { "AWS": "arn:aws:iam::<ServiceLine-AccountID>:role/logging-processor" } (if enabling Role Chaining), or retain legacy principal as directed by IBM support.
- Enforce "Condition": { "StringEquals": { "sts:ExternalId": "<EXTERNAL_ID>" } }
Create two new IAM roles in your AWS account - one for S3 and one for CloudWatch.

Note: The only required changes are to the trust policies of your existing IAM roles. Your S3 bucket, CloudWatch log group, and all policy permissions remain unchanged.

Decide your way of external logging: it can be role chaining, external ID, or both.
Identify the existing IAM roles in your AWS account used for watsonx Orchestrate logging, one for S3 and one for CloudWatch.
Contact IBM support to initiate the migration. IBM support:
- Provides the external ID value for your tenant (if enabling external ID).
- Confirm when the backend switch is complete so you can safely remove old trust entries.

Note: Do not remove existing trust entries from your IAM roles until IBM support explicitly confirms the migration is complete. Premature removal interrupts your log flow.

Path A: Role chaining only

In this path, you update the trust policy of your existing IAM roles to add IBM's scoped logging-processor role as an additional trusted principal alongside the existing entry.

Update the trust policy of the existing IAM roles
Update the trust policy for both your S3 and CloudWatch IAM roles. Add the watsonx Orchestrate logging-processor role ARN as an additional principal. Do not remove the existing 239621575091:root entry yet.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::239621575091:root",
          "arn:aws:iam::239621575091:role/logging-processor"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```
Why both entries? Keeping the old entry active during the transition ensures that your logs are not interrupted while IBM's operations team completes the backend switch to use the new role.
Notify IBM support
Inform IBM support that you have updated your trust policies. IBM support completes the backend configuration to switch over to role chaining.
Wait for IBM confirmation, then clean up
Verify that logs are flowing correctly to your new S3 bucket and CloudWatch log group. Once confirmed, you can safely remove the old 239621575091:root entry from the trust policies of both your S3 and CloudWatch IAM roles, leaving only the logging-processor role:
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::239621575091:role/logging-processor"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

Path B: External ID only

In this path, you create new IAM roles with an external ID condition. IBM recommends creating new roles rather than editing existing ones to avoid any log disruption during the transition.

Create new IAM roles
Create two new IAM roles in your AWS account - one for S3 and one for CloudWatch - with the same permissions as your existing roles.

For each new role, set the following trust policy at this stage. The external ID condition will be added in a later step once IBM provides it:
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::239621575091:root"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```
Share new role ARNs with support team
Copy the ARNs of both new IAM roles and provide them to IBM support by opening a support case. IBM support :
- Generate an external ID specific to your tenant.
- Enable the backend configuration to use your new roles and share the external ID value back with you.
- Activate new roles only after customers added the external ID.
Update trust policies with the external ID condition
Update your trust policies after receiving the external ID from watsonx Orchestrate support team. watsonx Orchestrate team activates the backend configuration at this point, so logs does not flow until your trust policy is updated.

Update the trust policy of both new IAM roles to add the external ID condition. Replace <YOUR_EXTERNAL_ID> with the value provided by IBM support:
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::239621575091:root"
        ]
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<YOUR_EXTERNAL_ID>"
        }
      }
    }
  ]
}
```
Let the support team know that external ID is configured
Notify the support team so that they can register the new roles with external ID.
Verify and clean up
Once support team confirms external ID is enabled, verify that logs are flowing correctly to your new S3 bucket and CloudWatch log group. Once confirmed, you can safely delete the older IAM roles from your AWS account.

Path C: Role chaining and external ID

Create new IAM roles
Create two new IAM roles in your AWS account - one for S3 and one for CloudWatch - with the same permissions as your existing roles.

For each new role, set the following trust policy at this stage. The external ID condition will be added in a later step once IBM provides it:
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::239621575091:role/logging-processor"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```
Share new role ARNs with watsonx Orchestrate support team
Copy the ARNs of both new IAM roles and provide them to watsonx Orchestrate support via a support case. IBM support:
- Generate an external ID specific to your tenant
- Enable the backend configuration to use your new roles and share the external ID value back with you
- Activate new roles only after customers added the external ID
Update trust policies with the external ID condition
Update your trust policies promptly after receiving the external ID from watsonx Orchestrate support team. watsonx Orchestrate has already activated the backend configuration at this point, so logs will not flow until your trust policy is updated.

Update the trust policy of both new IAM roles to add the external ID condition. Replace <YOUR_EXTERNAL_ID> with the value provided by IBM support:
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::239621575091:role/logging-processor"
        ]
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<YOUR_EXTERNAL_ID>"
        }
      }
    }
  ]
}
```
Let the support team know that external ID is configured
Notify the support team so that they can register the new roles with external ID.
Verify and clean up
Verify that logs are flowing correctly to your new S3 bucket and CloudWatch log group. Once confirmed, you can safely delete the older IAM roles from your AWS account.