All Products
Search
Document Center

Platform For AI:Associate a RAM role with a DSW instance

Last Updated:Nov 27, 2025

To 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 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.

What is instance RAM role?

An instance RAM role allows an instance to assume a RAM role. Then, the instance can obtain the STS temporary credential of the RAM role to access authorized cloud resources. This facilitates cross-service access and has the following advantages:

  • Security and confidentiality

    You do not need to manage credentials within an 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 policy of the instance RAM role to control access to cloud resources within a DSW instance in a more convenient and refined manner.

Limits

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

Implementation steps

Step 1: Associate a RAM role with a DSW instanceimage

Scenario 1: Default Roles of PAI

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.

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 2: Custom Roles

  1. 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.

    Take note of the following key parameters:

    • Principal Type: Cloud Service

    • Principal Name: Platform for AI / PAI (pai.aliyun.cs.com)

  2. Grant permissions to the instance RAM role.

    Click Grant Permission in the Actions column to attach a system policy or custom policy to the RAM role. This way, the RAM role has permissions to access or perform operations on the related resources. For example, you can attach the AliyunOSSFullAccess policy to the RAM role. For more information, see Step 3: Grant permissions to the RAM role.

    Note

    If you use a RAM user, contact the Alibaba Cloud account owner to create the following policy and attach the policy to your RAM user. This way, the RAM user has the permissions of the instance RAM role.

    The following sample code provides an example of a policy. Replace ${RoleName} with the name of your instance RAM role.

    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "ram:PassRole",
          "Resource": "acs:ram::*:role/${RoleName}"
        }
      ]
    }
  3. Create a DSW instance and associate the instance RAM role with the instance. For more information, see Create a DSW instance.

Scenario 3: Does Not Associate 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 configurations of an instance RAM role

  1. 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.

  2. Click Change Setting in the Actions column of the DSW instance.

  3. In the Roles and Permissions section, configure the Instance RAM Role parameter.

    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.

  4. Click Yes.

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(credentialsConfig)

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

  1. 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
  2. Use the temporary credential of the instance RAM role to access MaxCompute and obtain the table list of a specific project. For information about how to obtain the endpoint of a region, 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 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

  1. 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
  2. Use the temporary credential of the instance RAM role to access OSS and list 10 objects in the specific bucket. For information about how to obtain the endpoint of a region for OSS, see OSS 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 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

  1. 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
  2. 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

Q: How do I resolve a PassRoleFailedError when creating an instance with a custom role?

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}"
        }
      ]
    }

Q: How do I resolve the AssumeRoleFailedError when creating an instance with a custom role?

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

  1. Log on to the RAM console as the administrator.

  2. In the left-side navigation pane, choose Identities > Roles.

  3. On the Roles page, find the required RAM role.

  4. On the Trust Policy tab, click Edit Trust Policy.

  5. Modify the content of the trust policy and click OK.

    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"
    }