Agent Sandbox:Configure a RAM role

Least privilege

The permission policy of a RAM role limits the resources that can be accessed and the actions that can be performed. During a mount, Agent Sandbox further limits the permissions of the STS temporary credentials based on the storage type and the mount configuration. The permissions of the temporary credentials cannot exceed the permissions granted to the RAM role. Actual access must also comply with the authorization rules of the storage service. For more information, see the Policy parameter of AssumeRole.

Grant only the storage permissions that your workloads require. Multiple volumes can share the same RAM role, as long as the permissions cover the resources required by these mounts. A separate policy for each volume or storage path is not required. If production, test, or different workloads require separate permissions, configure separate roles.

Step 1: Create a RAM role

1. Log on to the RAM console. In the left-side navigation pane, choose Identities > Roles, and then click Create Role.

2. Set Principal Type to Cloud Service, and set Principal Name to Function Compute/FC.

3. Enter a role name, such as sandbox-storage-role, and then create the role.

4. On the role details page, view the trust policy and make sure that the Function Compute service is allowed to assume the role.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "fc.aliyuncs.com"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

For more information, see Create a RAM role for Alibaba Cloud services and Use a function role to access other cloud services.

Step 2: Grant permissions to access storage

1. On the Policies page of the RAM console, create a custom policy and select JSON Editor.

2. Configure the policy based on the permission configuration document for the corresponding storage type in the following table. Limit the resource scope to the storage resources that your workloads are allowed to access, and then save the policy.

3. Go back to the role details page, and in Permissions, add the permission policy that you created to the role.

When you mount multiple volumes that require a RAM role in the same Sandbox, grant the storage access permissions required by these mounts to the same RAM role. One or more permission policies can be used.

After you grant the permissions, copy the role ARN (Alibaba Cloud Resource Name) from the role details page. The role ARN is used to configure a volume or create a Sandbox.

Role selection rules

All storage mounts in the same Sandbox share one RAM role. Agent Sandbox does not merge the permissions of different roles. When you create a Sandbox, a role is selected in the following priority order: metadata["fc.sandbox.auth.role"] takes precedence over mountConfig.role of a volume.

Roles are compared by ARN. Two roles with different ARNs are different roles, even if they have the same permissions.

Role configuration for one or more volumes

The following examples show only the role configuration fields. Replace the account UID and role name in the ARN with your actual values, and then add the creation and mount parameters as described in the corresponding Volumes document. The following three configuration methods are available:

• One volume: Specify the role in mountConfig.role of the volume.

• Multiple volumes that share one role: Configure the same role ARN for each volume.

• Multiple volumes specified through metadata: Specify the role in metadata when you create the Sandbox.

{
  "mountConfig": {
    "role": "acs:ram::<ACCOUNT-UID>:role/sandbox-storage-role"
  }
}

{
  "metadata": {
    "fc.sandbox.auth.role": "acs:ram::<ACCOUNT-UID>:role/sandbox-storage-role"
  }
}

Append mounts after creation

An append mount continues to use the current RAM role of the Sandbox. This role must have the permissions to access the additional storage resources. An append mount does not switch to the role configured in the volume.

If you plan to append mounts later, configure the RAM role and grant the storage access permissions required by the append mounts when you create the Sandbox:

• If you mount a volume at creation time, use the role configured in the volume or specify a role through metadata.

• If you do not mount a volume at creation time, configure the role through metadata.

For more information, see Append a volume mount, Append an OSS mount, Append an AgenticFS mount, and Append an AgenticBucket mount.