Tous les produits
Search
Centre de documentation

Elastic Compute Service:Rôles RAM d'instance

Dernière mise à jour :Aug 18, 2026

Attachez un rôle RAM d'instance à une instance ECS pour obtenir des jetons STS permettant d'appeler d'autres API Alibaba Cloud sans exposer de paire AccessKey.

Avantages

  • Appels d'API sécurisés : Obtenez des jetons STS depuis ECS sans intégrer de paire AccessKey dans votre code, ce qui réduit le risque de fuite d'identifiants.

  • Changement d'identité simplifié : Changez l'identité RAM en modifiant le rôle RAM d'instance plutôt qu'en adaptant le code ou en redémarrant le service.

  • Contrôle d'accès granulaire : Attribuez des rôles RAM avec des politiques spécifiques à différentes instances ECS pour une gestion fine des autorisations.

Limites

Vous ne pouvez attacher qu'un seul rôle RAM à une instance ECS.

Procédure

Si vous utilisez un utilisateur RAM ou un rôle RAM, accordez d'abord les autorisations requises à cette identité.

Autorisations types

La politique doit inclure les autorisations suivantes :

  • Gérer les rôles RAM : Créer des rôles RAM et attacher des politiques.

  • Attacher ou détacher des rôles RAM : Attacher ou détacher un rôle RAM sur la page des détails de l'instance.

  • Transmettre des rôles aux services : L'autorisation ram:PassRole est requise pour attribuer un rôle à un service 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": "*"
        }
    ]
}

Créer un rôle RAM et l'attacher à une instance ECS

Console

  1. Connectez-vous à la console RAM pour créer un rôle RAM et attacher des politiques.

    1. Créez un rôle RAM pour un service Alibaba Cloud de confiance.

      Sélectionnez Identities > Roles, cliquez sur Create Role, puis suivez les instructions à l'écran. Tenez compte des paramètres suivants. Consultez la rubrique Créer un rôle RAM pour un service Alibaba Cloud de confiance :

      • Principal Type : Sélectionnez Cloud Service.

      • Pour Principal Name, sélectionnez ECS.

    2. Accordez des autorisations au rôle RAM créé.

      Attachez une politique système ou une politique personnalisée au rôle RAM. Par exemple, attachez la politique système AliyunOSSReadOnlyAccess.

      Pour créer des politiques personnalisées, consultez la rubrique Créer une politique personnalisée .
  2. Attachez le rôle RAM à une instance ECS.

    1. Accédez à Console ECS - Instances. Dans le coin supérieur gauche, sélectionnez la région et le groupe de ressources de la ressource cible.

    2. Localisez l'instance ECS cible, puis choisissez icon > Instance Settings > Attach/Detach RAM Role.

    3. Dans la boîte de dialogue, sélectionnez le rôle RAM d'instance que vous avez créé, puis cliquez sur OK.

API

  1. Créez un rôle RAM et attachez-y des politiques.

    1. Appelez l'opération CreateRole pour créer un rôle RAM.

      Définissez AssumeRolePolicyDocument avec la politique de confiance suivante :

      {
           "Statement": [
             {
                 "Action": "sts:AssumeRole",
                 "Effect": "Allow",
                 "Principal": {
                   "Service": [
                     "ecs.aliyuncs.com"
                   ]
                 }
             }
           ],
           "Version": "1"
       }
    2. (Facultatif) Appelez l'opération CreatePolicy pour créer une politique d'accès.

      Ignorez cette étape si vous disposez déjà d'une politique d'accès appropriée.

      Définissez PolicyDocument comme suit :

      {
           "Statement": [
               {
               "Action": [
                   "oss:Get*",
                   "oss:List*"
               ],
               "Effect": "Allow",
               "Resource": "*"
               }
           ],
           "Version": "1"
       }
    3. Appelez l'opération AttachPolicyToRole pour attacher la politique au rôle RAM.

  2. Appelez l'opération AttachInstanceRamRole pour attacher le rôle RAM à l'instance ECS.

Obtenir des identifiants temporaires

Obtenez des identifiants temporaires depuis une instance ECS en accédant au service de métadonnées. La validité des identifiants est gérée automatiquement. Consultez la rubrique Métadonnées d'instance.

Utiliser l'outil Credentials

L'outil Credentials encapsule l'ECS IMDS pour obtenir et actualiser périodiquement les jetons STS.

Python

  1. Installez l'outil Credentials.

    Le mode de renforcement de la sécurité nécessite alibabacloud_credentials 0.3.6 ou une version ultérieure.
    pip install alibabacloud_credentials
  2. Configurez le rôle RAM d'instance ECS comme identifiant d'accès.

    from alibabacloud_credentials.client import Client as CredClient
    from alibabacloud_credentials.models import Config as CredConfig
    
    credentialsConfig = CredConfig(
    	type='ecs_ram_role',
    	# Optional. The name of the instance RAM role. If you do not specify this parameter, the name is automatically retrieved. We recommend that you specify this parameter to reduce requests. You can also set the role name using the ALIBABA_CLOUD_ECS_METADATA environment variable.
    	role_name='<role_name>',
    	# Optional. The default value is false. If you set this to true, security hardening mode is enforced. If you set this to false, the system first tries to retrieve credentials in security hardening mode. If the attempt fails, the system tries again in normal mode (IMDSv1).
    	disable_imds_v1=False,
    )
    credentialsClient = CredClient(credentialsConfig)
    

    Consultez la rubrique Méthode 5 : Rôle RAM d'instance ECS.

Java

  1. Ajoutez la dépendance credentials.

    Le mode de renforcement de la sécurité nécessite credentials-java 0.3.10 ou une version ultérieure.
    <!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java -->
    <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>credentials-java</artifactId>
       <version>0.3.10</version>
    </dependency>
  2. Configurez le rôle RAM d'instance ECS comme identifiant d'accès.

    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");
            // Optional. The name of the instance RAM role. If you do not specify this parameter, the name is automatically retrieved. We recommend that you specify this parameter to reduce requests. You can also set the role name using the ALIBABA_CLOUD_ECS_METADATA environment variable.
            credentialConfig.setRoleName("<RoleName>");
            // Optional. The default value is false. If you set this to true, security hardening mode is enforced. If you set this to false, the system first tries to retrieve credentials in security hardening mode. If the attempt fails, the system tries again in normal mode (IMDSv1).
            credentialConfig.setDisableIMDSv1(true);
            Client credentialClient = new Client(credentialConfig);
        }
    }

    Consultez la rubrique Méthode 5 : Rôle RAM d'instance ECS.

Go

  1. Installez l'outil Credentials.

    Le mode de renforcement de la sécurité nécessite credentials-go 1.3.10 ou une version ultérieure.
    • Utilisez go get pour l'installation :

      go get -u github.com/aliyun/credentials-go
    • Si vous utilisez dep pour gérer les dépendances :

      dep ensure -add github.com/aliyun/credentials-go
  2. Configurez le rôle RAM d'instance ECS comme identifiant d'accès.

    package main
    
    import (
    	"fmt"
    	"github.com/aliyun/credentials-go/credentials"
    )
    
    func _main(args []*string) {
    	credentialsConfig := new(credentials.Config).
    		SetType("ecs_ram_role").
    		// Optional. The name of the instance RAM role. If you do not specify this parameter, the name is automatically retrieved. We recommend that you specify this parameter to reduce requests. You can also set the role name using the ALIBABA_CLOUD_ECS_METADATA environment variable.
    		SetRoleName("<RoleName>").
    		// Optional. The default value is false. If you set this to true, security hardening mode is enforced. If you set this to false, the system first tries to retrieve credentials in security hardening mode. If the attempt fails, the system tries again in normal mode (IMDSv1).
    		SetDisableIMDSv1(true)
    	credentialClient, err := credentials.NewCredential(credentialsConfig)
    	if err != nil {
    		panic(err)
    	}
    }

    Consultez la rubrique Méthode 5 : Utilisation des rôles RAM d'instance ECS.

Node.js

  1. Installez l'outil Credentials.

    Le mode de renforcement de la sécurité nécessite credentials 2.3.1 ou une version ultérieure.
    npm install @alicloud/credentials
  2. Configurez le rôle RAM d'instance ECS comme identifiant d'accès.

    const Credential = require('@alicloud/credentials');
    
    const credentialsConfig = new Credential.Config({
      type: 'ecs_ram_role',
      // Optional. The name of the instance RAM role. If you do not specify this parameter, the name is automatically retrieved. We recommend that you specify this parameter to reduce requests. You can also set the role name using the ALIBABA_CLOUD_ECS_METADATA environment variable.
      roleName: '<RoleName>',
      // Optional. The default value is false. If you set this to true, security hardening mode is enforced. If you set this to false, the system first tries to retrieve credentials in security hardening mode. If the attempt fails, the system tries again in normal mode (IMDSv1).
      disableIMDSv1: true,
    });
    const cred = new Credential.default(credentialsConfig);
    

    Consultez la rubrique Méthode 5 : Utilisation d'un rôle RAM d'instance ECS.

.NET

  1. Installez l'outil Credentials.

    Le mode de renforcement de la sécurité nécessite credentials 1.4.2 ou une version ultérieure.
    dotnet add package Aliyun.Credentials
  2. Configurez le rôle RAM d'instance ECS comme identifiant d'accès.

    using Aliyun.Credentials.Models;
    
    namespace credentials_demo
    {
        class Program
        {
            static void Main(string[] args)
            {
                var config = new Config()
                {
                    Type = "ecs_ram_role",
                  	// Optional. The name of the instance RAM role. If you do not specify this parameter, the name is automatically retrieved. We recommend that you specify this parameter to reduce requests. You can also set the role name using the ALIBABA_CLOUD_ECS_METADATA environment variable.
                    RoleName = "<RoleName>",
                    // Optional. The default value is false. If you set this to true, security hardening mode is enforced. If you set this to false, the system first tries to retrieve credentials in security hardening mode. If the attempt fails, the system tries again in normal mode (IMDSv1).
                    DisableIMDSv1 = true
                }
            }
        }
    }

    Consultez la rubrique Méthode 5 : Utilisation d'un rôle RAM d'instance ECS.

PHP

  1. Installez l'outil Credentials.

    Le mode de renforcement de la sécurité nécessite credentials 1.2.0 ou une version ultérieure.
    composer require alibabacloud/credentials
  2. Configurez le rôle RAM d'instance ECS comme identifiant d'accès.

    <?php
    
    use AlibabaCloud\Credentials\Credential;
    use AlibabaCloud\Credentials\Credential\Config;
    
    $credConfig = new Config([
        'type' => 'ecs_ram_role',
        // Optional. The name of the instance RAM role. If you do not specify this parameter, the name is automatically retrieved. We recommend that you specify this parameter to reduce requests. You can also set the role name using the ALIBABA_CLOUD_ECS_METADATA environment variable.
        'roleName' => '<RoleName>',
        // Optional. The default value is false. If you set this to true, security hardening mode is enforced. If you set this to false, the system first tries to retrieve credentials in security hardening mode. If the attempt fails, the system tries again in normal mode (IMDSv1).
        'disableIMDSv1' => true,
    ]);

    Consultez la rubrique Méthode 5 : Utilisation d'un rôle RAM d'instance ECS.

Utiliser des commandes shell

Récupérez les identifiants temporaires via le point de terminaison HTTP du service de métadonnées.

Mode de renforcement de la sécurité

  • Instance Linux

    # Obtain the access token of the metadata server for authentication.
    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>"` 
    # Obtain the temporary access credentials of the instance RAM role.
    curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/ram/security-credentials/<instance_RAM_role_name>
  • Instance Windows (PowerShell)

    # Obtain the access token of the metadata server for authentication.
    $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
    # Obtain the temporary access credentials of the instance RAM role.
    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> : Durée de validité du jeton d'accès au serveur de métadonnées. Le jeton doit être obtenu avant de récupérer les identifiants temporaires. Après expiration, obtenez un nouveau jeton.

Valeurs possibles : 1 à 21600. Unité : secondes. Consultez la rubrique Métadonnées d'instance.

<instance_RAM_role_name> : Remplacez cette valeur par le nom de votre rôle RAM d'instance. Par exemple, EcsRamRole.

Remarque

Si vous utilisez Cloud Assistant pour exécuter ces commandes, l'agent Cloud Assistant doit respecter les versions minimales suivantes :

Plateforme

Version minimale de l'agent Cloud Assistant

windows

2.1.3.857

linux

2.2.3.857

linux arm

2.4.3.857

freebsd

2.3.3.857

Mode normal

  • Instance Linux

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

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

    Remplacez <instance_RAM_role_name> par le nom de votre rôle RAM d'instance. Par exemple, EcsRamRoleDocumentTesting.

Exemple de réponse :

  • Le jeton d'accès temporaire se compose de AccessKeyId, AccessKeySecret et SecurityToken.

  • Expiration : Date d'expiration des identifiants temporaires.

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

Utiliser la CLI

La CLI encapsule l'ECS IMDS pour obtenir et actualiser automatiquement les jetons STS.

Le mode de renforcement de la sécurité nécessite la CLI 3.0.248 ou une version ultérieure.
  1. Installez la CLI.

  2. Configurez les identifiants d'identité.

    Configurez les informations d'identification. Remplacez <ProfileName> par le nom de votre configuration.

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

    Suivez les invites pour saisir les informations requises. Consultez la rubrique Configurer les identifiants.

  3. Appelez une opération d'API.

    Par exemple, interrogez la liste des instances ECS :

     aliyun ecs DescribeInstances

    Consultez la rubrique Structure des commandes.

Exemple : Appeler une API avec un rôle RAM d'instance

L'exemple Python suivant télécharge un fichier depuis OSS en utilisant un rôle RAM d'instance sur une instance ECS Linux.

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',      # The type of access credential. This value is fixed as ecs_ram_role.
        role_name=role_name
    )
    cred = Client(config)
    credentials_provider = CredentialProviderWarpper(cred)
    auth = oss2.ProviderAuth(credentials_provider)

    # Initialize the OSS Bucket object.
    bucket = oss2.Bucket(auth, endpoint, bucket_name)
    # Download the image to the local instance.
    bucket.get_object_to_file(object_key, local_file)
    print("Image downloaded successfully")

if __name__ == "__main__":
    # Define global variables.
    role_name = 'role_name'  # Replace with the name of your instance RAM role.
    bucket_name = 'bucket_name'  # Replace with your bucket name.
    endpoint = 'oss-cn-beijing.aliyuncs.com'  # Replace with the public endpoint of your OSS bucket.
    object_key = 'testfolder/example.png'  # Replace with the full path of the image that you want to download from OSS. Do not include the bucket name.
    local_file = '/localpath/to/image.png'  # Replace with the root path on the ECS instance where you want to store the image, and define the image name.
    download_image_using_instance_role(bucket_name, endpoint, object_key, local_file, role_name)

Autres opérations

Détacher ou modifier un rôle RAM d'instance

Console

  1. Accédez à Console ECS - Instances. Dans le coin supérieur gauche, sélectionnez la région et le groupe de ressources de la ressource cible.

  2. Localisez l'instance ECS à gérer et choisissez icon > Instance Settings > Attach/Detach RAM Role.

    • Pour détacher un rôle RAM d'instance : Définissez Action sur Detach et cliquez sur Confirm.

    • Pour modifier le rôle RAM d'instance : Définissez Action sur Attach, sélectionnez le rôle RAM d'instance souhaité, puis cliquez sur Confirm.

API

Références