Configure RAM roles for a DSW instance - Platform For AI

When you access other cloud resources from a Data Science Workshop (DSW) instance, you must configure an AccessKey pair to verify your identity. You can associate a Resource Access Management (RAM) role with a DSW instance to access other cloud resources from the DSW instance by using a Security Token Service (STS) temporary credential without the need to configure a long-term AccessKey pair. This reduces the risk of key leak. This topic describes how to create a RAM role whose trusted entity is Alibaba Cloud services, grant the role the permissions to use a DSW instance, and obtain an STS temporary credential by using the instance RAM role.

Background information

An instance RAM role is a RAM role whose trusted entity is Alibaba Cloud services. A cloud service can assume an instance RAM role to access other cloud resources. For information about RAM roles, see the "What is a RAM role?" section of the RAM role overview topic.

The following section describes the benefits of using temporary access credentials based on the instance RAM role to perform identity verification and access control:

Security and confidentiality
You do not need to manage credentials within the instance. You can use STS temporary credentials instead of long-term AccessKey pairs to reduce the risk of key leak.
Convenient management
You can modify the permission policy of the instance RAM role to control access to cloud resources within the DSW instance in a more convenient and refined manner.

Limits

A DSW instance can be associated with only one RAM role.

Step 1: Configure a RAM role for a DSW instance

Scenario 1: Associate the default role of PAI with an instance

The default role of Platform for AI (PAI) has only the permissions to access PAI services, MaxCompute, and Object Storage Service (OSS). You can use this role to implement fine-grained permission management. If you use the temporary credentials issued by the default role of PAI, you are granted the same permissions as the DSW instance owner when you access PAI services and MaxCompute tables. When you access OSS, you can access only the bucket that is configured as the default storage path for the current workspace.

You can associate the default role of PAI with the instance to obtain a temporary access credential that allows you to access basic development resources without the need to create additional RAM roles.

After you associate the default role of PAI with an instance, you do not need to configure an AccessKey pair in the following scenarios:

Submit a training task to the current workspace by using the PAI SDK.
Submit a training task to the current workspace by using the DLC SDK.
Submit a task to MaxCompute projects on which the instance owner has execution permissions by using the ODPS SDK.
Access data in the bucket which is the default storage path for the current workspace by using the OSS SDK.
Use the Tongyi Lingma service in a web integrated development environment (IDE).

Scenario 1: Associate a custom role with an instance

Log on to the RAM console and create a RAM role. For more information, see Create a RAM role for a trusted Alibaba Cloud service.
The following table describes the main parameters.
- Select Trusted Entity: Alibaba Cloud Service
- Role Type: Normal Service Role
- Select Trusted Service: Platform for AI

Grant permissions to the instance RAM role.

You can attach a system policy or a custom policy to a RAM role to grant the RAM role the related permissions to access or manage resources. For more information, see Step 3: Grant permissions to a RAM role.

Optional. The following section describes a RAM policy for default roles of PAI. You can configure the policy based on your business requirements.

{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "oss:GetObject",
                "oss:PutObject",
                "oss:DeleteObject",
                "oss:ListParts",
                "oss:AbortMultipartUpload",
                "oss:ListObjects",
                "oss:ListBuckets",
                "oss:PutBucketCors",
                "oss:GetBucketCors",
                "oss:DeleteBucketCors",
                "oss:GetBucketInfo"
            ],
            "Resource": [
                "acs:oss:*:*:${bucketName}",
                "acs:oss:*:*:${bucketName}/*"
            ],
            "Effect": "Allow"
        },
        {
            "Effect": "Allow",
            "Action": [
                "odps:ActOnBehalfOfAnotherUser"
            ],
            "Resource": "acs:odps:*:*:users/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "pai:AssumeUser"
            ],
            "Resource": "acs:pai:*:*:users/*"
        }
    ]
}

Note

If you use a RAM user, contact the Alibaba Cloud account owner to obtain the permissions to use the instance RAM role.

The following section provides a sample permission policy. Replace ${RoleName} with the name of the RAM role of the DSW instance.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ram:PassRole",
      "Resource": "acs:ram::*:role/${RoleName}"
    }
  ]
}

Create a DSW instance and associate the instance RAM role with the instance. For more information, see Create a DSW instance.

Scenario 3: Do not associate the instance with a RAM role

If your instance is set to public in the workspace, we recommend that you do not associate the instance with a RAM role to prevent permission leak. When you create an instance or change the configurations of an instance, you can set the Instance RAM Role parameter in the Advanced Information section to Does Not Associate Role.

Update the RAM role configurations of an instance

Go to the Data Science Workshop (DSW) page.
1. Log on to the PAI console.
2. In the top navigation bar of the Overview page, select a region.
3. In the left-side navigation pane, click Workspaces. On the Workspace page, click the name of the workspace.
4. In the left-side navigation pane of the workspace page, choose Model Training>Data Science Workshop (DSW) to go to the DSW page.
Click Change Setting in the Actions column of the DSW instance.
In the Advanced Information section, configure the instance RAM role.
Note
A running instance that is updated is restarted in the following scenarios: the Instance RAM Role parameter is changed from Default Roles of PAI or Custom Roles to Does Not Associate Role, or from Does Not Associate Role to Default Roles of PAI or Custom Roles. Before you update the configuration, make sure that you save the instance data.
Click Confirm.

Step 2: Obtain temporary credentials by using the instance RAM role

You can use one of the following methods to obtain temporary credentials from a DSW instance that is associated with a RAM role:

Method 1: Use the Alibaba Cloud Credentials tool

The Credentials tool calls the on-premises service of the instance, which is automatically injected when the instance is created, to obtain an STS temporary credential that is periodically updated.

To use the Credentials tool to obtain the credential of the instance RAM role, run the following command to install the Alibaba Cloud Credentials tool. Sample command in Python:

pip install alibabacloud_credentials

The following section provides a sample code for using the Credentials tool. For information about how to use SDKs for other programming languages, see the "Sample code" section in the Best practices for using an access credential to call API operations topic.

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CredConfig

credentialsConfig = CredConfig(
	type='credentials_uri' # Optional. If you did not configure other access methods for the default credential chain, you do not need to specify the parameter. The Credentials SDK obtains the temporary credential by using the URI.
)
credentialsClient = CredClient(CredConfig)

Method 2: Access the on-premises service of a DSW instance

If you use a DSW instance, you can run the following command on the Terminal tab to access the server that is automatically injected into the on-premises service:

# Obtain the temporary credential of the instance RAM role.
curl $ALIBABA_CLOUD_CREDENTIALS_URI

The following section provides a sample response. Parameters:

SecurityToken: the temporary token of the instance RAM role.
Expiration: the validity period of the temporary credential of the instance RAM role.

{
	"Code": "Success",
	"AccessKeyId": "STS.N*********7",
	"AccessKeySecret": "3***************d",
	"SecurityToken": "DFE32G*******"
	"Expiration": "2024-05-21T10:39:29Z"
}

Method 3: Access an on-premises file of a DSW instance

You can access the file in the specified path within the DSW instance to obtain the temporary credential of the instance RAM role. The file is automatically injected and periodically updated. The path of the file is /mnt/.alibabacloud/credentials. Sample file content:

{
	"AccessKeyId": "STS.N*********7",
	"AccessKeySecret": "3***************d",
	"SecurityToken": "DFE32G*******"
	"Expiration": "2024-05-21T10:39:29Z"
}

Step 3: Access other cloud services by using the instance RAM role

Example 1: Access MaxCompute by using an instance RAM role

Run the following commands to install the Credentials tool and ODPS SDK:

# Install the Credentials tool.
pip install alibabacloud_credentials
# Install the ODPS SDK.
pip install odps

Use the temporary credential of the instance RAM role to access MaxCompute and obtain the table list of a specific project.

from alibabacloud_credentials import providers
from odps.accounts import CredentialProviderAccount
from odps import ODPS

if __name__ == '__main__':
    account = CredentialProviderAccount(providers.DefaultCredentialsProvider())
    o = ODPS(
             account=account,
             project="{odps_project}", # Replace the value with your project name.
             endpoint="{odps_endpoint}"# Replace the value with the endpoint of the region in which your project resides.
            )

    for t in o.list_tables():
        print(t)

Example 2: Access OSS by using an instance RAM role

Run the following commands to install the Credentials tool and OSS SDK:

# Install the Credentials tool.
pip install alibabacloud_credentials
# Install the OSS SDK.
pip install oss2

Use the temporary credential of the instance RAM role to access OSS and list 10 objects in the specific bucket.

import oss2
from alibabacloud_credentials.client import Client
from alibabacloud_credentials import providers
from itertools import islice

auth = oss2.ProviderAuth(providers.DefaultCredentialsProvider())
bucket = oss2.Bucket(auth, 
                     '{oss_endpoint}',# Replace the value with the endpoint of the region in which your OSS bucket resides.
                     '{oss_bucket}'# Replace the value with the name of your OSS bucket.
                    )

for b in islice(oss2.ObjectIterator(bucket), 10):
    print(b.key)

Example 3: Access DLC by using an instance RAM role

Run the following commands to install the Credentials tool, OpenAPI SDK, and DLC SDK:

# Install the Credentials tool.
pip install alibabacloud_credentials
# Install the Alibaba Cloud OpenAPI SDK.
pip install alibabacloud-tea-util alibabacloud_tea_openapi
# Install the PAI-DLC SDK.
pip install alibabacloud_pai_dlc20201203

Use the temporary credential of the instance RAM role to access Deep Learning Containers (DLC) and list DLC jobs in a specific workspace.

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_tea_openapi.models import Config
from alibabacloud_pai_dlc20201203.client import Client as pai_dlc20201203Client
from alibabacloud_pai_dlc20201203 import models as pai_dlc_20201203_models
from alibabacloud_tea_util.models import RuntimeOptions

# Use the Credentials tool to initialize the DLC client.
credentialsClient = CredClient()
config = Config(credential=credentialsClient)
config.endpoint = '{dlc_endpoint}' # Replace the value with the endpoint of the region in which your workspace resides.
client = pai_dlc20201203Client(config)

# Initialize the request and call the ListJobs API.
list_jobs_request = pai_dlc_20201203_models.ListJobsRequest()
list_jobs_request.workspace_id = '{workspace_id}' # Replace the value with the ID of your workspace.
runtime_options = RuntimeOptions()
headers = {}
resp = client.list_jobs_with_options(list_jobs_request, headers, runtime_options)

jobs = resp.to_map()['body']['Jobs']
print(jobs[0])

FAQ

What do I do if a PassRoleFailedError error is reported when I select a custom role during instance creation?

Log on to the RAM console and check whether the RAM role exists.

If the role does not exist, change the instance RAM role to an existing role.
If the role exists, contact your Alibaba Cloud account to grant your RAM user the permissions to use the role. The following section provides a sample policy. Replace the ${RoleName} parameter with the name of the RAM role.
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ram:PassRole",
      "Resource": "acs:ram::*:role/${RoleName}"
    }
  ]
}
```

What do I do if an AssumeRoleFailedError error is reported when I select a custom role during instance creation?

The issue occurs because the trust policy is not configured for your role. Perform the following operations:

Log on to the RAM console as the administrator.
In the left-side navigation pane, choose Identities > Roles.
On the Roles page, find the required RAM role.
On the Trust Policy tab, click Edit Trust Policy.

Modify the content of the trust policy and click Save trust policy document.

Sample original trust policy for the role:

{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "acs:ram::aaa:root"
        ],
        "Service": [
          "xxx.aliyuncs.com"
        ]
      }
    }
  ],
  "Version": "1"
}

Sample new policy:

{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "acs:ram::aaa:root"
        ],
        "Service": [
          "xxx.aliyuncs.com",
          "pai.aliyuncs.com" 
        ]
      }
    }
  ],
  "Version": "1"
}