dsw, data science workshop, ram, ram role, instance ram role, sts, accesskey, pai-Platform For AI(PAI)-阿里云帮助中心

What is an instance RAM role

An instance RAM role provides a temporary, role-based identity for a DSW instance. When a DSW instance is granted a RAM role:

Processes within the instance can automatically obtain short-term STS credentials from the local metadata service or a credential file.
The credentials grant permissions defined by the attached permission policy, enabling secure access to authorized cloud services such as OSS, MaxCompute, and PAI-DLC.
It completely avoids storing an AccessKey in plaintext within your code or configuration files, helping you meet security and compliance requirements.

Key benefits include:

Secure: Uses automatically refreshed short-term STS credentials instead of long-term AccessKeys, eliminating the risks of hard-coded keys and credential leakage.
Easy to manage: Centralizes permission management through RAM role policies. Policy changes take effect immediately without restarting instances or updating code.
Natively trusted: Credentials are issued by the Alibaba Cloud Security Token Service (STS), making them trusted by default without requiring additional authentication middleware.

Limitations

You can associate only one RAM role with a DSW instance at a time.

Procedure

Step 1: Configure a RAM role

On the DSW instance configuration page, you can choose one of the following three role options:

PAI default role

Platform for AI (PAI) provides a default role. After you grant this role to an instance, it automatically gains access to the following resources without a configured AccessKey:

Submit jobs to MaxCompute projects where the instance owner has execution permissions by using the ODPS SDK.
Access data in the default storage path bucket configured for the current workspace by using the OSS SDK.
Use the Tongyi Lingma service in the WebIDE.
Create and submit training jobs to the current workspace by using the PAI or PAI-DLC SDK.

Custom role

Log on to the RAM console and create a RAM role. For detailed instructions, see Create a RAM role for a trusted Alibaba Cloud service.

Configure the key parameters as follows:
- Trusted entity type: Alibaba Cloud service
- Trusted entity name: Platform for AI (pai.aliyun.cs.com)
Grant permissions to the RAM role.

Click Add Authorization and attach a system or custom permission policy to the RAM role. This grants the role permissions to access or operate the required resources. For example, add the AliyunOSSFullAccess policy. For more information, see Step 3: Grant permissions to a RAM role.
Note
If you are using a RAM user to operate the DSW instance, ask your root account administrator to create and attach the following permission policy to your RAM user. This policy allows your RAM user to use the instance RAM role.

The following code shows the required permission policy. Replace ${RoleName} with the name of the DSW instance RAM role.
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ram:PassRole",
      "Resource": "acs:ram::*:role/${RoleName}"
    }
  ]
}
```

No associated role

If your instance is publicly visible within the workspace, we recommend not associating a RAM role with it to prevent permission exposure. When you create an instance or change its configuration, in the Advanced Information section, set Instance RAM Role to Does Not Associate Role.

Update RAM role configuration

Go to the DSW page.
1. Log on to the PAI console and select your target region and workspace.
2. In the navigation pane on the left, choose Model Training > Data Science Workshop (DSW) to go to the DSW page.
Click Change Settings on the right of the DSW instance.
In the Roles and Permissions section, configure the instance RAM role.

Important
If you switch the RAM role of a running instance 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, the instance is immediately restarted. Please make sure that you have saved the instance.
After completing the configuration, click OK.

Step 2: Obtain temporary credentials

After you associate a RAM role with an instance, you can obtain and use its temporary credentials in several ways to access cloud services.

Credentials tool

We recommend using the Credentials tool from the Alibaba Cloud SDKs. It automatically handles credential acquisition and refreshing, which is the best practice for accessing cloud services.

Install the dependency (Python example):
```
pip install alibabacloud_credentials
```

Example usage:

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CredConfig
credentialsConfig = CredConfig(
	type='credentials_uri'   # Optional. If you have not configured other access methods in the default credential chain, you do not need to explicitly specify the type. The Credentials SDK obtains temporary credentials by using the URI method.
)
credentialsClient = CredClient(credentialsConfig)

For more SDK examples in other languages, see Best practices for using credentials to access Alibaba Cloud OpenAPI.

Local service

In the DSW instance, run the following command in the terminal to obtain credentials from the locally injected service.

# Obtain temporary access credentials for the instance RAM role
curl $ALIBABA_CLOUD_CREDENTIALS_URI

The following is a sample response:

SecurityToken: The temporary token for the instance RAM role.
Expiration: The expiration time of the temporary access credentials.

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

Local file

In a DSW instance, PAI automatically injects and periodically refreshes a file containing temporary credentials for the instance RAM role. You can obtain these credentials by reading the file from the path /mnt/.alibabacloud/credentials. The file's content is as follows:

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

Step 3: Access other cloud services

Access OSS

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

# Install the credentials tool
pip install alibabacloud_credentials
# Install the OSS SDK
pip install oss2

Use the instance RAM role's temporary credentials to access OSS and list 10 objects in a specified bucket. For OSS region endpoints, see Regions and endpoints.

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  with the endpoint of the region where your OSS bucket is located.
                     '<oss_bucket>'# Replace  with your OSS bucket name.
                    )
for b in islice(oss2.ObjectIterator(bucket), 10):
    print(b.key)

Access MaxCompute

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

# Install the credentials tool
pip install alibabacloud_credentials
# Install the ODPS SDK
pip install odps

Use the instance RAM role's temporary credentials to access MaxCompute and retrieve the list of tables in a specified project. For MaxCompute region endpoints, see Endpoints.

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  with your project name.
             endpoint="<odps_endpoint>"# Replace  with the endpoint of the region where your project is located.
            )
    for t in o.list_tables():
        print(t)

Access PAI-DLC

Run the following commands to install the Credentials tool, OpenAPI SDK, and PAI-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 instance RAM role's temporary credentials to access PAI-DLC and list the PAI-DLC jobs in a specified 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 PAI-DLC client.
credentialsClient = CredClient()
config = Config(credential=credentialsClient)
config.endpoint = '<dlc_endpoint>' # Replace  with the endpoint of your region.
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  with your workspace ID.
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

Resolve PassRoleFailedError

Log on to the RAM console to verify that the role exists.

If the role does not exist, change the instance RAM role to an existing role.
If the role exists, ask your root account administrator to grant your RAM user permission to use this role. The required permission policy is as follows (replace ${RoleName} with the name of the RAM role):
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ram:PassRole",
      "Resource": "acs:ram::*:role/${RoleName}"
    }
  ]
}
```

Resolve AssumeRoleFailedError

This error usually occurs because your role's trust policy is configured incorrectly. Follow these steps to resolve the issue:

Log on to the RAM console as a RAM administrator.
In the navigation pane on the left, choose Identity Management > Roles.
On the Roles page, click the name of the target RAM role.
On the Trust Policy tab, click Edit Trust Policy.

Modify the trust policy to add pai.aliyuncs.com to the Service principal, and then click OK.

For example, if the original trust policy is:

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

Update the policy to include pai.aliyuncs.com:

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