すべてのプロダクト
Search
ドキュメントセンター

Elastic Compute Service:インスタンス RAM ロール

最終更新日:Apr 28, 2026

インスタンス RAM ロールを Elastic Compute Service (ECS) インスタンスにアタッチすると、AccessKey ペアを公開せずに、他の Alibaba Cloud API を呼び出すための STS トークンを取得できます。

メリット

  • 安全な API コール:コードに AccessKey ペアを埋め込まずに ECS から STS トークンを取得し、認証情報漏洩のリスクを低減します。

  • シンプルなアイデンティティ切り替え:コードの変更やサービスの再起動を行わずに、インスタンス RAM ロールを変更することで RAM アイデンティティを切り替えます。

  • きめ細かいアクセス制御:特定のポリシーを持つ RAM ロールを異なる ECS インスタンスに割り当て、きめ細かい権限管理を実現します。

制限事項

1 つの ECS インスタンスにアタッチできる RAM ロールは 1 つだけです。

手順

RAM ユーザーまたは RAM ロールを使用する場合、まずそのアイデンティティに必要な権限を付与してください。

権限のサンプル

ポリシーには、以下の権限を含める必要があります:

  • RAM ロールの管理:RAM ロールを作成し、ポリシーをアタッチします。

  • RAM ロールのアタッチまたはデタッチ:インスタンス詳細ページで RAM ロールをアタッチまたはデタッチします。

  • サービスへのロールの引き渡しram:PassRole 権限は、Alibaba Cloud サービスにロールを付与するために必要です。

{
    "Version": "1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:Describe*",
                "ecs:List*",
                "ecs:AttachInstanceRamRole",
                "ecs:DetachInstanceRAMRole"
            ],
            "Resource": "*"
        },
        {
          "Effect": "Allow",
          "Action": [
            "ram:Describe*",              
            "ram:List*",
            "ram:Get*",
            "ram:CreateRole", 
            "ram:CreatePolicy", 
            "ram:AttachPolicyToRole"
          ],
          "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "ram:PassRole",
            "Resource": "*"
        }
    ]
}

RAM ロールの作成と ECS インスタンスへのアタッチ

コンソール

  1. RAM コンソールにログインし、RAM ロールを作成してポリシーをアタッチします。

    1. 信頼された Alibaba Cloud サービス用の RAM ロールを作成します。

      [アイデンティティ] > [ロール] を選択し、[ロールの作成] をクリックして、画面の指示に従います。以下のパラメーターに注意してください。詳細については、「信頼された Alibaba Cloud サービス用の RAM ロールの作成」をご参照ください:

      • [プリンシパルタイプ]:[クラウドサービス] を選択します。

      • 「プリンシパル名」で、ECS を選択します。

    2. 作成した RAM ロールに権限を付与します。

      システムポリシーまたはカスタムポリシーを RAM ロールにアタッチします。例えば、AliyunOSSReadOnlyAccess システムポリシーをアタッチします。

      カスタムポリシーの作成については、「カスタムポリシーの作成」をご参照ください。
  2. RAM ロールを ECS インスタンスにアタッチします。

    1. ECS コンソール - インスタンスに移動します。上部メニューで、対象のリージョンとリソースグループを選択します。

    2. ターゲットの ECS インスタンスを見つけて、icon > インスタンスの設定 > RAM ロールのアタッチ/デタッチ を選択します。

    3. ダイアログボックスで、作成したインスタンス RAM ロールを選択し、OK をクリックします。

API

  1. RAM ロールを作成し、ポリシーをアタッチします。

    1. CreateRole API を呼び出して RAM ロールを作成します。

      AssumeRolePolicyDocument を以下の信頼ポリシーに設定します:

      {
           "Statement": [
             {
                 "Action": "sts:AssumeRole",
                 "Effect": "Allow",
                 "Principal": {
                   "Service": [
                     "ecs.aliyuncs.com"
                   ]
                 }
             }
           ],
           "Version": "1"
       }
    2. (任意) CreatePolicy API を呼び出してアクセスポリシーを作成します。

      適切なアクセスポリシーが既にある場合は、この手順をスキップしてください。

      PolicyDocument を以下のように設定します:

      {
           "Statement": [
               {
               "Action": [
                   "oss:Get*",
                   "oss:List*"
               ],
               "Effect": "Allow",
               "Resource": "*"
               }
           ],
           "Version": "1"
       }
    3. AttachPolicyToRole API を呼び出して、ポリシーを RAM ロールにアタッチします。

  2. AttachInstanceRamRole API を呼び出して、RAM ロールを ECS インスタンスにアタッチします。

一時的な認証情報の取得

メタデータサービスにアクセスして、ECS インスタンス内から一時的な認証情報を取得します。認証情報の有効期間は自動的に管理されます。詳細については、「インスタンスメタデータ」をご参照ください。

Credentials ツールを使用する

Credentials ツールは ECS IMDS をラップし、STS トークンを定期的に取得・更新します。

Python
  1. Credentials ツールをインストールします。

    セキュリティ強化モードには、alibabacloud_credentials 0.3.6 以降が必要です。
    pip install alibabacloud_credentials
  2. ECS インスタンス RAM ロールをアクセス認証情報として設定します。

    from alibabacloud_credentials.client import Client as CredClient
    from alibabacloud_credentials.models import Config as CredConfig
    
    credentialsConfig = CredConfig(
    	type='ecs_ram_role',
    	# (任意) インスタンス RAM ロールの名前。このパラメーターを指定しない場合、名前は自動的に取得されます。リクエストを減らすために、このパラメーターを指定することを推奨します。ALIBABA_CLOUD_ECS_METADATA 環境変数を使用してロール名を設定することもできます。
    	role_name='<role_name>',
    	# (任意) デフォルト値は false です。これを true に設定すると、セキュリティ強化モードが強制されます。false に設定すると、システムはまずセキュリティ強化モードで認証情報を取得しようとします。失敗した場合は、通常モード (IMDSv1) で再試行します。
    	disable_imds_v1=False,
    )
    credentialsClient = CredClient(credentialsConfig)
    

    詳細については、「方法5:ECS インスタンス RAM ロール」をご参照ください。

Java

  1. credentials の依存関係を追加します。

    セキュリティ強化モードには、credentials-java 0.3.10 以降が必要です。
    <!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java -->
    <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>credentials-java</artifactId>
       <version>0.3.10</version>
    </dependency>
  2. ECS インスタンス RAM ロールをアクセス認証情報として設定します。

    import com.aliyun.credentials.Client;
    import com.aliyun.credentials.models.Config;
    
    public class DemoTest {
        public static void main(String[] args) throws Exception {
            Config credentialConfig = new Config();
            credentialConfig.setType("ecs_ram_role");
            // (任意) インスタンス RAM ロールの名前。このパラメーターを指定しない場合、名前は自動的に取得されます。リクエストを減らすために、このパラメーターを指定することを推奨します。ALIBABA_CLOUD_ECS_METADATA 環境変数を使用してロール名を設定することもできます。
            credentialConfig.setRoleName("<RoleName>");
            // (任意) デフォルト値は false です。これを true に設定すると、セキュリティ強化モードが強制されます。false に設定すると、システムはまずセキュリティ強化モードで認証情報を取得しようとします。失敗した場合は、通常モード (IMDSv1) で再試行します。
            credentialConfig.setDisableIMDSv1(true);
            Client credentialClient = new Client(credentialConfig);
        }
    }

    詳細については、「方法5:ECS インスタンス RAM ロール」をご参照ください。

Go

  1. Credentials ツールをインストールします。

    セキュリティ強化モードには、credentials-go 1.3.10 以降が必要です。
    • go get を使用してインストールします:

      go get -u github.com/aliyun/credentials-go
    • dep を使用して依存関係を管理する場合:

      dep ensure -add github.com/aliyun/credentials-go
  2. ECS インスタンス RAM ロールをアクセス認証情報として設定します。

    package main
    
    import (
    	"fmt"
    	"github.com/aliyun/credentials-go/credentials"
    )
    
    func _main(args []*string) {
    	credentialsConfig := new(credentials.Config).
    		SetType("ecs_ram_role").
    		// (任意) インスタンス RAM ロールの名前。このパラメーターを指定しない場合、名前は自動的に取得されます。リクエストを減らすために、このパラメーターを指定することを推奨します。ALIBABA_CLOUD_ECS_METADATA 環境変数を使用してロール名を設定することもできます。
    		SetRoleName("<RoleName>").
    		// (任意) デフォルト値は false です。これを true に設定すると、セキュリティ強化モードが強制されます。false に設定すると、システムはまずセキュリティ強化モードで認証情報を取得しようとします。失敗した場合は、通常モード (IMDSv1) で再試行します。
    		SetDisableIMDSv1(true)
    	credentialClient, err := credentials.NewCredential(credentialsConfig)
    	if err != nil {
    		panic(err)
    	}
    }

    詳細については、「方法5:ECS インスタンス RAM ロールの使用」をご参照ください。

Node.js

  1. Credentials ツールをインストールします。

    セキュリティ強化モードには、credentials 2.3.1 以降が必要です。
    npm install @alicloud/credentials
  2. ECS インスタンス RAM ロールをアクセス認証情報として設定します。

    const Credential = require('@alicloud/credentials');
    
    const credentialsConfig = new Credential.Config({
      type: 'ecs_ram_role',
      // (任意) インスタンス RAM ロールの名前。このパラメーターを指定しない場合、名前は自動的に取得されます。リクエストを減らすために、このパラメーターを指定することを推奨します。ALIBABA_CLOUD_ECS_METADATA 環境変数を使用してロール名を設定することもできます。
      roleName: '<RoleName>',
      // (任意) デフォルト値は false です。これを true に設定すると、セキュリティ強化モードが強制されます。false に設定すると、システムはまずセキュリティ強化モードで認証情報を取得しようとします。失敗した場合は、通常モード (IMDSv1) で再試行します。
      disableIMDSv1: true,
    });
    const cred = new Credential.default(credentialsConfig);
    

    詳細については、「方法5:ECS インスタンス RAM ロールの使用」をご参照ください。

.NET

  1. Credentials ツールをインストールします。

    セキュリティ強化モードには、credentials 1.4.2 以降が必要です。
    dotnet add package Aliyun.Credentials
  2. ECS インスタンス RAM ロールをアクセス認証情報として設定します。

    using Aliyun.Credentials.Models;
    
    namespace credentials_demo
    {
        class Program
        {
            static void Main(string[] args)
            {
                var config = new Config()
                {
                    Type = "ecs_ram_role",
                  	// (任意) インスタンス RAM ロールの名前。このパラメーターを指定しない場合、名前は自動的に取得されます。リクエストを減らすために、このパラメーターを指定することを推奨します。ALIBABA_CLOUD_ECS_METADATA 環境変数を使用してロール名を設定することもできます。
                    RoleName = "<RoleName>",
                    // (任意) デフォルト値は false です。これを true に設定すると、セキュリティ強化モードが強制されます。false に設定すると、システムはまずセキュリティ強化モードで認証情報を取得しようとします。失敗した場合は、通常モード (IMDSv1) で再試行します。
                    DisableIMDSv1 = true
                }
            }
        }
    }

    詳細については、「方法5:ECS インスタンス RAM ロールの使用」をご参照ください。

PHP

  1. Credentials ツールをインストールします。

    セキュリティ強化モードには、credentials 1.2.0 以降が必要です。
    composer require alibabacloud/credentials
  2. ECS インスタンス RAM ロールをアクセス認証情報として設定します。

    <?php
    
    use AlibabaCloud\Credentials\Credential;
    use AlibabaCloud\Credentials\Credential\Config;
    
    $credConfig = new Config([
        'type' => 'ecs_ram_role',
        // (任意) インスタンス RAM ロールの名前。このパラメーターを指定しない場合、名前は自動的に取得されます。リクエストを減らすために、このパラメーターを指定することを推奨します。ALIBABA_CLOUD_ECS_METADATA 環境変数を使用してロール名を設定することもできます。
        'roleName' => '<RoleName>',
        // (任意) デフォルト値は false です。これを true に設定すると、セキュリティ強化モードが強制されます。false に設定すると、システムはまずセキュリティ強化モードで認証情報を取得しようとします。失敗した場合は、通常モード (IMDSv1) で再試行します。
        'disableIMDSv1' => true,
    ]);

    詳細については、「方法5:ECS インスタンス RAM ロールの使用」をご参照ください。

シェルコマンドの使用

メタデータサービスの HTTP エンドポイントから一時的な認証情報を取得します。

セキュリティ強化モード

  • Linux インスタンス

    # メタデータサーバーのアクセストークンを取得して認証します。
    TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<validity_period_of_the_metadata_server_access_token>"` 
    # インスタンス RAM ロールの一時的なアクセス認証情報を取得します。
    curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/ram/security-credentials/<instance_RAM_role_name>
  • Windows インスタンス (PowerShell)

    # メタデータサーバーのアクセストークンを取得して認証します。
    $token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<validity_period_of_the_metadata_server_access_token>"} -Method PUT -Uri http://100.100.100.200/latest/api/token
    # インスタンス RAM ロールの一時的なアクセス認証情報を取得します。
    Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/meta-data/ram/security-credentials/<instance_RAM_role_name>

<validity_period_of_the_metadata_server_access_token>:メタデータサーバーのアクセストークンの有効期間。トークンは、一時的な認証情報を取得する前に取得する必要があります。有効期限が切れた後は、新しいトークンを取得してください。

値の範囲:1~21600。単位:秒。詳細については、「インスタンスメタデータ」をご参照ください。

<instance_RAM_role_name>:インスタンス RAM ロールの名前に置き換えます。例:EcsRamRole

説明

Cloud Assistant を使用してこれらのコマンドを実行する場合、Cloud Assistant Agent は以下の最小バージョン要件を満たす必要があります:

プラットフォーム

Cloud Assistant Agent の最小バージョン

windows

2.1.3.857

linux

2.2.3.857

linux arm

2.4.3.857

freebsd

2.3.3.857

通常モード

  • Linux インスタンス

    curl http://100.100.100.200/latest/meta-data/ram/security-credentials/<instance_RAM_role_name>
  • Windows インスタンス (PowerShell)

    Invoke-RestMethod http://100.100.100.200/latest/meta-data/ram/security-credentials/<instance_RAM_role_name>

    <instance_RAM_role_name> をインスタンス RAM ロールの名前に置き換えます。例: EcsRamRoleDocumentTesting

レスポンスの例:

  • 一時的なアクセストークンは、AccessKeyIdAccessKeySecret、および SecurityToken で構成されます。

  • Expiration:一時的な認証情報の有効期限。

    {
       "AccessKeyId" : "STS.*******6YSE",
       "AccessKeySecret" : "aj******jDU",
       "Expiration" : "2017-11-01T05:20:01Z", 
       "SecurityToken" : "CAISng********",
       "LastUpdated" : "2023-07-18T14:17:28Z",
       "Code" : "Success"
    }

CLI の使用

CLI は ECS IMDS をラップし、STS トークンを自動的に取得・更新します。

セキュリティ強化モードには、CLI 3.0.248 以降が必要です。
  1. CLI をインストールします。

  2. アイデンティティ認証情報を設定します。

    認証情報を設定します。<ProfileName> をプロファイル名に置き換えます。

    aliyun configure --profile <ProfileName> --mode EcsRamRole

    プロンプトに従って必要な情報を入力します。詳細については、「認証情報の設定」をご参照ください。

  3. API 操作を呼び出します。

    例えば、ECS インスタンスのリストをクエリします:

     aliyun ecs DescribeInstances

    詳細については、「コマンド構造」をご参照ください。

例:インスタンス RAM ロールを使用した API の呼び出し

以下の Python の例では、Linux の ECS インスタンスでインスタンス RAM ロールを使用して、OSS からファイルをダウンロードします。

pip install oss2  
pip install alibabacloud_credentials
import oss2
from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config
from oss2 import CredentialsProvider
from oss2.credentials import Credentials


class CredentialProviderWarpper(CredentialsProvider):
    def __init__(self, client):
        self.client = client

    def get_credentials(self):
        access_key_id = self.client.get_access_key_id()
        access_key_secret = self.client.get_access_key_secret()
        security_token = self.client.get_security_token()
        return Credentials(access_key_id, access_key_secret, security_token)


def download_image_using_instance_role(bucket_name, endpoint, object_key, local_file, role_name):
    config = Config(
        type='ecs_ram_role',      # アクセス認証情報のタイプ。この値は ecs_ram_role に固定されています。
        role_name=role_name
    )
    cred = Client(config)
    credentials_provider = CredentialProviderWarpper(cred)
    auth = oss2.ProviderAuth(credentials_provider)

    # OSS Bucket オブジェクトを初期化します。
    bucket = oss2.Bucket(auth, endpoint, bucket_name)
    # イメージをローカルインスタンスにダウンロードします。
    bucket.get_object_to_file(object_key, local_file)
    print("Image downloaded successfully")


if __name__ == "__main__":
    # グローバル変数を定義します。
    role_name = 'role_name'  # インスタンス RAM ロールの名前に置き換えます。
    bucket_name = 'bucket_name'  # バケット名に置き換えます。
    endpoint = 'oss-cn-beijing.aliyuncs.com'  # OSS バケットのパブリックエンドポイントに置き換えます。
    object_key = 'testfolder/example.png'  # OSS からダウンロードしたいイメージのフルパスに置き換えます。バケット名は含めないでください。
    local_file = '/localpath/to/image.png'  # イメージを保存する ECS インスタンス上のパスに置き換え、イメージ名を定義します。
    download_image_using_instance_role(bucket_name, endpoint, object_key, local_file, role_name)

その他の操作

インスタンス RAM ロールのデタッチまたは変更

コンソール

  1. ECS コンソール - インスタンスに移動します。上部メニューで、対象のリージョンとリソースグループを選択します。

  2. 管理したい ECS インスタンスを見つけて、icon > インスタンスの設定 > RAM ロールのアタッチ/デタッチ を選択します。

    • インスタンス RAM ロールをデタッチするには:[アクション]デタッチ に設定し、[確認] をクリックします。

    • インスタンス RAM ロールを変更するには:[アクション]アタッチ に設定し、目的のインスタンス RAM ロールを選択して、[確認] をクリックします。

API

  • インスタンス RAM ロールをデタッチするには、DetachInstanceRamRole API を呼び出します。

  • インスタンス RAM ロールを変更するには:

    1. DetachInstanceRamRole API を呼び出して、現在のインスタンス RAM ロールをデタッチします。

    2. AttachInstanceRamRole API を呼び出して、新しい RAM ロールをインスタンスにアタッチします。

関連ドキュメント