How to Fix "AssumeRoleError" When Sharing Encrypted ECS Images in Alibaba Cloud
A step-by-step guide to resolving the AliyunECSShareEncryptImageDefaultRole configuration issue
The Problem
Have you ever tried to share an encrypted ECS image in Alibaba Cloud, only to be greeted with this frustrating error?
Requires a RAM role of AliyunECSShareEncryptImageDefaultRole before sharing encrypted image.
Details
* Error Code: AssumeRoleError
* Request ID: [REQUEST_ID]
If you're reading this, chances are you've already created the required RAM role, attached the necessary policies, and still can't figure out why the error persists. Don't worry—you're not alone, and the solution is simpler than you might think.
Understanding the Root Cause
The AssumeRoleError occurs because of a subtle but critical difference in how Alibaba Cloud handles trust policies for encrypted image sharing versus standard ECS operations. When sharing encrypted images across accounts, the trust policy requires a specific format that includes the destination account ID.
Many developers initially try the standard ECS service trust policy:
{
"Statement": [
{
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Principal": {
"Service": [
"ecs.aliyuncs.com"
]
}
}
],
"Version": "1"
}
While this works for most ECS operations, it fails for cross-account encrypted image sharing.
The Solution: Correct Trust Policy Format
The key insight is that for cross-account encrypted image sharing, you need to specify the destination account ID in the service principal. Here's the correct format:
For Cross-Account Sharing:
{
"Statement": [
{
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Principal": {
"Service": [
"[email protected]"
]
}
}
],
"Version": "1"
}
Replace 123456789012345 with your actual destination account ID.
For Same-Account Sharing:
If you're sharing within the same account (different regions), use:
{
"Statement": [
{
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Principal": {
"Service": [
"ecs.aliyuncs.com"
]
}
}
],
"Version": "1"
}
Step-by-Step Implementation Guide
Step 1: Create the Required RAM Role
If you haven't already, create the RAM role with the exact name required:
aliyun ram CreateRole --RoleName AliyunECSShareEncryptImageDefaultRole --AssumeRolePolicyDocument '{
"Statement": [
{
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Principal": {
"Service": [
"[email protected]"
]
}
}
],
"Version": "1"
}'
Step 2: Attach the Required KMS Policy
The role needs KMS permissions to handle encrypted images:
# Create a custom KMS policy for encrypted image operations
aliyun ram CreatePolicy --PolicyName ECSShareEncryptImagePolicy --PolicyDocument '{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:DescribeKey",
"kms:GenerateDataKey",
"kms:ListKeys"
],
"Resource": "*"
}
]
}'
# Attach the policy to the role
aliyun ram AttachPolicyToRole --PolicyType Custom --PolicyName ECSShareEncryptImagePolicy --RoleName AliyunECSShareEncryptImageDefaultRole
Alternatively, you can use the system policy AliyunKMSFullAccess if it's available in your region.
Step 3: Update Trust Policy via Console (Recommended)
If you need to update an existing role's trust policy:
-
Navigate to RAM Console
- Go to https://ram.console.aliyun.com/
- Click "Roles" in the left sidebar
-
Find the Role
- Search for AliyunECSShareEncryptImageDefaultRole
- Click on the role name
-
Update Trust Policy
- Click the "Trust Policy Management" tab
- Click "Edit Trust Policy"
- Replace the existing policy with the correct format
- Click "OK" to save
Step 4: Verify the Configuration
You can verify your role configuration using the CLI:
# Check if the role exists
aliyun ram GetRole --RoleName AliyunECSShareEncryptImageDefaultRole
# List attached policies
aliyun ram ListPoliciesForRole --RoleName AliyunECSShareEncryptImageDefaultRole
Troubleshooting Common Issues
Issue 1: "The policy does not exist" Error
If you encounter this error when attaching KMS policies:
ERROR: SDK.ServerError
ErrorCode: EntityNotExist.Policy
Message: The policy does not exist: AliyunKMSCryptoUserPolicy
Solution: The policy name varies by region. Try these alternatives:
- AliyunKMSFullAccess
- AliyunKMSReadOnlyAccess
- Create a custom policy as shown in Step 2
Issue 2: "DeleteConflict.Role.Policy" Error
When trying to delete and recreate the role:
ERROR: SDK.ServerError
ErrorCode: DeleteConflict.Role.Policy
Message: The role must have not any attached policies
Solution: Detach all policies first:
# List attached policies
aliyun ram ListPoliciesForRole --RoleName AliyunECSShareEncryptImageDefaultRole
# Detach each policy
aliyun ram DetachPolicyFromRole --PolicyType Custom --PolicyName [PolicyName] --RoleName AliyunECSShareEncryptImageDefaultRole
Issue 3: Multiple Destination Accounts
If you need to share with multiple accounts, add them to the service array:
{
"Statement": [
{
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Principal": {
"Service": [
"[email protected]",
"[email protected]",
"[email protected]"
]
}
}
],
"Version": "1"
}
Best Practices
Use Principle of Least Privilege
Instead of AliyunKMSFullAccess, create custom policies with only the required permissions:
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:DescribeKey",
"kms:GenerateDataKey"
],
"Resource": "*"
}
]
}
Document Your Account IDs
Keep a record of which accounts you're sharing with. Consider using account aliases in comments:
{
"Statement": [
{
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Principal": {
"Service": [
"[email protected]" // Production Account
]
}
}
],
"Version": "1"
}
Test in Development First
Always test encrypted image sharing in a development environment before implementing in production.
Alternative Approaches
Using Terraform
If you're using Infrastructure as Code, here's a Terraform example:
resource "alicloud_ram_role" "ecs_share_encrypt_image_role" {
name = "AliyunECSShareEncryptImageDefaultRole"
assume_role_policy = jsonencode({
Statement = [
{
Action = "sts:AssumeRole"
Effect = "Allow"
Principal = {
Service = [
"[email protected]"
]
}
}
]
Version = "1"
})
}
resource "alicloud_ram_role_policy_attachment" "kms_policy" {
policy_name = "AliyunKMSFullAccess"
policy_type = "System"
role_name = alicloud_ram_role.ecs_share_encrypt_image_role.name
}
Using Resource Orchestration Service (ROS)
ROSTemplateFormatVersion: '2015-09-01'
Description: ECS Encrypted Image Sharing Role
Resources:
ECSShareEncryptImageRole:
Type: ALIYUN::RAM::Role
Properties:
RoleName: AliyunECSShareEncryptImageDefaultRole
AssumeRolePolicyDocument:
Statement:
- Action: sts:AssumeRole
Effect: Allow
Principal:
Service:
- "[email protected]"
Version: "1"
PolicyAttachments:
System:
- AliyunKMSFullAccess
Conclusion
The AssumeRoleError when sharing encrypted ECS images is a common stumbling block that can be easily resolved with the correct trust policy format. The key takeaway is that cross-account encrypted image sharing requires the destination account ID to be included in the service principal as "[email protected]".
By following this guide, you should be able to:
- Create the required RAM role with the correct trust policy
- Attach the necessary KMS permissions
- Successfully share encrypted ECS images across accounts
- Troubleshoot common configuration issues
Remember to always test your configuration in a development environment first, and follow the principle of least privilege when assigning permissions.