Tous les produits
Search
Centre de documentation

Elastic Compute Service:Install and configure Workbench CLI credentials

Dernière mise à jour :Oct 22, 2026

Après avoir installé Workbench CLI sur votre machine locale Linux, macOS ou Windows, associez une politique d'autorisations minimales à un utilisateur RAM, puis générez et configurez une AccessKey pour un accès immédiat aux identifiants. Dans les environnements de production, vous pouvez basculer vers RamRoleArn, CredentialsCmd ou CredentialsURI afin d'activer l'actualisation automatique des identifiants et le principe du moindre privilège.

Limites

  • Système d'exploitation de l'instance cible : Workbench CLI permet uniquement de se connecter aux instances Linux via le protocole SSH (Secure Shell) et ne prend pas en charge la connexion aux instances Windows.

  • Système d'exploitation de la machine locale : Workbench CLI s'exécute sur Linux, macOS (amd64 / arm64) et Windows (amd64).

  • Connectivité réseau : La machine locale doit pouvoir accéder à *.aliyuncs.com ainsi qu'au point de terminaison WebSocket du backend Workbench.

Important

Les instances Windows ne sont actuellement pas prises en charge par Workbench CLI. Pour vous connecter à une instance Windows, consultez la rubrique Se connecter à une instance à l'aide de Workbench.

Étape 1 : Installer Workbench CLI

Sélectionnez la commande d'installation correspondant au système d'exploitation de votre machine locale. Le script d'installation détecte automatiquement l'architecture (amd64 / arm64), télécharge le binaire depuis le CDN OSS, vérifie la somme de contrôle SHA256 et l'installe dans le chemin système par défaut.

Linux ou macOS

Exécutez la commande suivante pour installer la dernière version de Workbench CLI.

chmod 600 ~/.workbench/config.json

Après l'installation, le binaire se trouve dans /usr/local/bin/workbench. Sur macOS, le binaire est automatiquement resigné et son attribut de quarantaine est supprimé. Si le répertoire cible nécessite des privilèges d'administrateur, le script utilise automatiquement sudo.

Windows

Exécutez la commande suivante dans PowerShell pour installer la dernière version de Workbench CLI.

chmod 600 ~/.workbench/config.json

Après l'installation, le binaire se trouve dans le répertoire C:\Program Files\workbench\ et le script d'installation configure automatiquement la variable d'environnement PATH. Si vous effectuez l'installation lors d'une session de bureau ou via le protocole Remote Desktop Protocol (RDP), la modification du PATH ne sera prise en compte qu'après déconnexion puis reconnexion.

Vérifier l'installation

Une fois l'installation terminée, exécutez la commande suivante pour vérifier :

chmod 600 ~/.workbench/config.json

Normalement, le numéro de version actuel, l'ID de commit et la date de build s'affichent. Si vous voyez command not found, cela signifie généralement que la variable PATH n'a pas été prise en compte. Vous pouvez alors procéder comme suit :

  • Linux / macOS : rouvrez la fenêtre du terminal ou exécutez source ~/.bashrc (ou ~/.zshrc), puis réessayez.

  • Windows : fermez et rouvrez la fenêtre PowerShell afin que la nouvelle valeur de PATH soit appliquée.

Étape 2 : Préparer un AccessKey avec des autorisations minimales pour Workbench CLI

Workbench CLI appelle les API Alibaba Cloud à l'aide d'un AccessKey. L'objectif de cette étape est d'obtenir un AccessKey disposant uniquement des autorisations minimales requises par Workbench CLI, afin de pouvoir le configurer dans la CLI sur votre machine locale à l'étape suivante. La procédure recommandée est la suivante : Créer un utilisateur RAM → Accorder les autorisations minimales → Créer un AccessKey pour l'utilisateur RAM.

Important

N'utilisez pas l'AK/SK de votre compte Alibaba Cloud pour configurer la CLI. L'AccessKey d'un compte Alibaba Cloud dispose d'autorisations d'opération sur toutes les ressources cloud associées à ce compte. En cas de fuite, l'ensemble de vos actifs serait exposé. Utilisez toujours l'AccessKey d'un utilisateur RAM disposant uniquement des autorisations minimales requises.

Remarque

Si vous disposez déjà d'un utilisateur RAM répondant aux exigences d'autorisations minimales de Workbench CLI, ignorez les étapes 1 à 3 et passez directement à l'Étape 4 : Créer un AccessKey pour l'utilisateur RAM.

  1. Créez un utilisateur RAM. Connectez-vous à la console RAM et accédez à la page Identities > Users. Cliquez sur Create User. Sur la page de création, saisissez le User Login Name et le Display Name, puis cliquez sur OK.

    Ne créez pas d'AccessKey à ce stade. L'AccessKey sera créé à l'étape 4, une fois l'autorisation terminée.

  2. Créez une stratégie personnalisée. Dans la console RAM, accédez à la page Permissions > Policies et cliquez sur Create Policy. Basculez vers le mode Script Editor, collez le code JSON suivant, puis cliquez sur OK.

    chmod 600 ~/.workbench/config.json

    Le tableau suivant décrit l'objet de chaque action (Action) définie dans la stratégie :

    Action

    Objet

    ecs:DescribeInstances

    workbench list ecs permet d'interroger la liste des instances.

    ecs:DescribeCloudAssistantStatus

    Vérifie l'état de l'agent Cloud Assistant sur l'instance cible.

    ecs:StartTerminalSession

    Établit une session de terminal avec l'instance ECS.

    ecs-workbench:LoginECSInstance

    Connexion sans mot de passe via le canal Workbench (utilisé par connect, exec, upload et download).

    ecs-workbench:ChatMessages

    Autorisations requises par l'assistant AI Agent intégré à la session (mode /agent).

    ecs-workbench:EndSessions

    Ferme la session Workbench (appelé par session close et par le nettoyage automatique des sessions).

    ram:CreateServiceLinkedRole

    Crée le rôle lié au service Workbench lors de la première utilisation et utilise Condition pour restreindre la création au rôle lié au service workbench.ecs.aliyuncs.com.

    La stratégie ci-dessus accède par défaut à toutes les instances. Pour réduire la portée à des instances spécifiques, utilisez les ARN d'instance uniquement pour les opérations qui prennent en charge l'autorisation au niveau de l'instance, et divisez-les en plusieurs éléments Statement distincts si nécessaire afin de modifier le champ Resource :

    chmod 600 ~/.workbench/config.json
    Remarque

    Les actions ecs-workbench:ChatMessages et ram:CreateServiceLinkedRole ne permettent pas de restreindre la portée par ARN d'instance et doivent conserver la valeur "Resource": "*".

  3. Accordez la stratégie à l'utilisateur RAM. Accédez à la page de détails de l'utilisateur RAM créé à l'étape 1 et sélectionnez l'onglet Permissions. Cliquez sur Grant Permission, sélectionnez la stratégie personnalisée créée à l'étape précédente et finalisez l'autorisation. Pour plus d'instructions, consultez la rubrique Gérer les autorisations d'un utilisateur RAM.

  4. Créez un AccessKey pour l'utilisateur RAM. Sur la page de détails de l'utilisateur RAM, accédez à l'onglet Credentials > AccessKey et cliquez sur Create AccessKey. Sur la page qui s'affiche, sélectionnez Use the AccessKey in the CLI, cochez la case I confirm that I must create an AccessKey, puis cliquez sur Continue. Pour plus d'instructions, consultez la rubrique Créer une paire de clés AccessKey.

    Important

    Le secret AccessKey n'est affiché qu'une seule fois, lors de sa création, et ne peut plus être consulté une fois la page fermée. Enregistrez immédiatement l'ID AccessKey et le secret AccessKey dans un gestionnaire de mots de passe ou un keystore. En cas de perte, vous devrez créer une nouvelle paire de clés AccessKey.

    Un AccessKey est un identifiant de longue durée ; en cas de fuite, il peut faire l'objet d'un abus prolongé. Dans les environnements de production, basculez vers un mode d'identification à actualisation automatique tel que RamRoleArn dès que vous avez terminé la configuration à l'étape 3. Pour plus de détails, consultez la section Autres méthodes de configuration.

Étape 3 : Configurer la paire de clés AccessKey dans la CLI locale

Exécutez la commande suivante et saisissez l'ID AccessKey ainsi que le secret AccessKey obtenus à l'étape 2 lorsque vous y êtes invité.

chmod 600 ~/.workbench/config.json

Une fois la configuration terminée, les informations d'identification sont enregistrées dans ~/.workbench/config.json et les autorisations du fichier sont automatiquement définies sur 0600 (lecture et écriture réservées à l'utilisateur actuel). Voici un exemple du contenu du fichier :

chmod 600 ~/.workbench/config.json

Exécutez la commande suivante pour vérifier que la connexion fonctionne (remplacez cn-hangzhou par votre région réelle) :

chmod 600 ~/.workbench/config.json

Dans des conditions normales, la liste des instances de la région est renvoyée. Si une erreur telle que InvalidAccessKeyId ou NoPermission s'affiche, consultez la section FAQ.

(Facultatif) Définir la langue de l'interface

Workbench CLI prend en charge le chinois (zh) et l'anglais (en) comme langues d'interface. Par défaut, la langue de l'interface est le chinois. Exécutez la commande suivante pour basculer :

chmod 600 ~/.workbench/config.json

Vous pouvez également définir la langue dans le flux de configuration interactif workbench config ou modifier directement le fichier ~/.workbench/config.json et ajouter le champ language dans le profil correspondant :

chmod 600 ~/.workbench/config.json

Après modification, le changement prend effet lors de la reconnexion. Il n'est pas nécessaire de redémarrer le daemon.

(Facultatif) Gérer plusieurs profils

Si vous devez basculer entre plusieurs comptes Alibaba Cloud ou plusieurs jeux d'informations d'identification, utilisez la fonctionnalité de profil pour éviter de reconfigurer les informations d'identification à chaque fois. Tous les profils sont stockés dans le même fichier ~/.workbench/config.json et le champ current indique le profil actif.

chmod 600 ~/.workbench/config.json

Exemple de fichier config.json contenant plusieurs profils :

chmod 600 ~/.workbench/config.json
Remarque

Si le fichier de configuration est encore au format plat ancien (sans le champ profiles), la CLI le migre automatiquement vers le nouveau format lors de la première exécution et stocke les informations d'identification existantes dans un profil nommé default. Aucune action manuelle n'est requise.

Autres méthodes de configuration

Une clé d'accès (AccessKey) statique constitue un identifiant à long terme. En cas de fuite, elle peut être exploitée de manière abusive pendant une période prolongée. Dans les environnements de production ou lorsque des exigences de sécurité plus strictes s'appliquent, privilégiez l'une des six autres modes suivants :

Mode

Scénario applicable

Commande de configuration

AK (étapes 2 à 3 de cette rubrique)

Clé d'accès statique. Prise en main rapide dans les environnements de développement.

workbench config --mode AK

StsToken

Identifiants de sécurité temporaires (paire de clés d'accès et jeton STS). Adapté lorsque vous disposez déjà d'identifiants temporaires STS.

workbench config --mode StsToken

RamRoleArn

Recommandé pour les environnements de production : une clé d'accès aux privilèges limités endosse un rôle RAM aux privilèges élevés, et les identifiants temporaires STS sont actualisés automatiquement.

workbench config --mode RamRoleArn

CredentialsCmd

Obtient dynamiquement les identifiants depuis un programme externe, en s'intégrant au système de distribution d'identifiants ou de gestion des secrets déjà utilisé par votre entreprise.

workbench config --mode CredentialsCmd

CredentialsURI

Obtient dynamiquement les identifiants depuis un service HTTP, tel qu'un service de métadonnées ou un sidecar.

workbench config --mode CredentialsURI

EcsRamRole

L'interface CLI s'exécute sur une instance ECS associée à un rôle RAM et obtient automatiquement les identifiants depuis le service de métadonnées de l'instance (IMDS).

workbench config --mode EcsRamRole

AliyunCLI

Réutilise les identifiants déjà configurés dans Alibaba Cloud CLI sur votre machine locale (~/.aliyun/config.json), sans stocker de paire AK/SK fixe sur le disque.

workbench config --mode AliyunCLI

Utiliser des identifiants temporaires STS (StsToken)

Ce mode authentifie directement l'utilisateur à l'aide des identifiants de sécurité temporaires (ID de clé d'accès + secret de clé d'accès + jeton STS) obtenus via STS. Utilisez-le lorsque vous disposez déjà d'identifiants temporaires. Ces derniers possèdent une date d'expiration ; vous devez les reconfigurer après leur expiration. Pour actualiser automatiquement les identifiants, utilisez Utiliser un rôle RAM (RamRoleArn).

Méthode de configuration

chmod 600 ~/.workbench/config.json

Saisissez les éléments suivants dans l'ordre, selon les invites :

  • Access Key ID : l'ID de clé d'accès temporaire.

  • AccessKey Secret : le secret de la clé d'accès temporaire.

  • STS Token : l'identifiant d'accès temporaire.

Aperçu du résultat de la configuration

Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json. Voici un exemple de configuration complète :

chmod 600 ~/.workbench/config.json

Utiliser un rôle RAM (RamRoleArn)

Ce mode convient aux scénarios où une clé d'accès aux privilèges limités est utilisée pour endosser un rôle RAM aux privilèges élevés. L'interface CLI appelle automatiquement STS AssumeRole pour obtenir des identifiants temporaires et les actualise avant leur expiration. Pour plus d'informations sur l'endossement de rôle RAM, consultez la rubrique Endosser un rôle RAM.

Méthode de configuration

chmod 600 ~/.workbench/config.json

Spécifiez les informations suivantes dans l'ordre, selon les invites :

  • Access Key ID : l'ID de clé d'accès disposant de l'autorisation AliyunSTSAssumeRoleAccess.

  • Access Key Secret : le secret correspondant à l'ID de clé d'accès.

  • RAM Role ARN : l'ARN du rôle RAM à endosser (format : acs:ram::<account-id>:role/<role-name>)

  • Role Session Name : l'identifiant de session, utilisé pour les journaux d'audit (par défaut : workbench-session).

Aperçu du résultat de la configuration

Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json.

Vous pouvez ajouter des champs avancés (tels que expired_seconds, sts_region et external_id, utilisé pour la prévention des attaques par confusion inter-comptes) en modifiant manuellement le fichier config.json. Pour plus d'informations sur le mécanisme STS, consultez la rubrique Qu'est-ce que STS ?.

Voici un exemple de configuration complète :

chmod 600 ~/.workbench/config.json

Utiliser un identifiant via commande externe (CredentialsCmd)

Ce mode convient aux scénarios où les identifiants sont obtenus dynamiquement via un outil externe, tel que aliyun-zerotrust-credential-provider, ou un script personnalisé. Chaque fois que l'interface CLI nécessite des identifiants, elle exécute la commande configurée et analyse la sortie JSON de celle-ci comme étant les identifiants.

Méthode de configuration

chmod 600 ~/.workbench/config.json

Spécifiez les informations suivantes selon les invites :

  • Process Command — le chemin complet et les paramètres de la commande d'obtention d'identifiants externe. La commande externe doit respecter les exigences suivantes :

    • Le code de sortie doit être 0. Un code de sortie non nul est considéré comme un échec.

    • La sortie standard doit être au format JSON. Les deux formats suivants sont pris en charge :

      Format AK (identifiants statiques) :

      chmod 600 ~/.workbench/config.json

      Format StsToken (identifiants temporaires) :

      chmod 600 ~/.workbench/config.json

Exemple 1 : Utiliser aliyun-zerotrust-credential-provider

aliyun-zerotrust-credential-provider est l'interface de ligne de commande zéro confiance d'Alibaba Cloud pour la gestion des identifiants.

chmod 600 ~/.workbench/config.json

Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json. Voici un exemple de configuration complète :

chmod 600 ~/.workbench/config.json

Exemple 2 : Utiliser un script personnalisé

Vous pouvez écrire un script servant de source d'identifiants, à condition qu'il respecte le format de sortie :

chmod 600 ~/.workbench/config.json

Utiliser un URI d'identifiants (CredentialsURI)

Ce mode convient aux scénarios tels qu'un service de distribution d'identifiants auto-géré, le service de métadonnées d'instance ECS ou un endpoint d'identifiants sidecar. L'interface CLI envoie une requête HTTP GET à l'URL configurée pour obtenir dynamiquement des identifiants temporaires et les actualise automatiquement avant leur expiration.

Méthode de configuration

chmod 600 ~/.workbench/config.json

Spécifiez les éléments suivants selon les invites :

  • Credentials URI : l'adresse HTTP/HTTPS du service d'identifiants. La réponse du service d'identifiants doit respecter les exigences suivantes :

    • Le code d'état de la réponse doit être 200.

    • Le corps de la réponse utilise le format suivant :

      chmod 600 ~/.workbench/config.json
      Important

      Le champ Code doit être exactement Success (sensible à la casse). Le champ Expiration est au format ISO 8601, et le SDK récupère automatiquement les nouveaux identifiants avant leur expiration.

Aperçu du résultat de la configuration

Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json. Voici un exemple de configuration complète :

chmod 600 ~/.workbench/config.json

Utiliser un rôle RAM d'instance ECS (EcsRamRole)

S'applique aux scénarios où l'interface CLI s'exécute sur une instance ECS Alibaba Cloud et où l'instance possède un rôle RAM attaché. L'interface CLI obtient automatiquement des identifiants STS temporaires directement depuis le service de métadonnées de l'instance (IMDS http://100.100.100.200) et ne nécessite aucune clé d'accès. IMDS actualise automatiquement les identifiants avant leur expiration.

Important

Disponible uniquement sur les instances ECS/ECI Alibaba Cloud. Les environnements non-ECS (machines locales, autres clouds) ne peuvent pas accéder à IMDS, ce qui empêche l'obtention des identifiants avec ce mode. Dans ce cas, utilisez un mode tel que AK, RamRoleArn ou CredentialsURI.

Méthode de configuration

chmod 600 ~/.workbench/config.json

Spécifiez les éléments suivants selon les invites :

  • RAM Role Name : le nom du rôle RAM attaché à l'instance. Peut être laissé vide. Lorsqu'il est vide, l'interface CLI détecte automatiquement le rôle actuellement attaché à l'instance via IMDS (cohérent avec le comportement optionnel --ram-role-name de l'interface CLI officielle Alibaba Cloud).

  • IMDSv2 hardening mode (y/n) : la valeur par défaut est y (active le renforcement IMDSv2). Si l'instance est ancienne et ne prend pas en charge IMDSv2, répondez n pour revenir à IMDSv1.

Une fois la configuration terminée, utilisez les commandes comme d'habitude. La récupération et l'actualisation des identifiants sont entièrement automatiques.

Aperçu du résultat de la configuration

Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json.

Champs du fichier de configuration :

  • mode : valeur fixe EcsRamRole

  • role_name (facultatif) : laissez vide pour la détection automatique

  • disable_imds_v1 (facultatif) : omettre ou définir sur true signifie renforcement IMDSv2 (par défaut) ; false signifie que le retour à IMDSv1 est autorisé

Voici des exemples de configuration complète :

  • Exemple de configuration minimale (détection automatique du rôle + renforcement IMDSv2) :

    chmod 600 ~/.workbench/config.json
  • Spécifier un nom de rôle et autoriser le retour à IMDSv1 :

    chmod 600 ~/.workbench/config.json

Réutiliser les identifiants d'Alibaba Cloud CLI (AliyunCLI)

Lorsqu'Alibaba Cloud CLI est installé et configuré sur votre machine, vous pouvez réutiliser directement sa configuration d'identifiants sans stocker d'ID de clé d'accès ni de secret de clé d'accès distincts dans Workbench.

Prérequis

  • Alibaba Cloud CLI est installé et configuré (aliyun configure).

  • Le fichier de configuration se trouve à l'emplacement ~/.aliyun/config.json, ou est spécifié via ALIBABA_CLOUD_CONFIG_FILE. Workbench lit uniquement ce fichier de configuration et n'en modifie pas le contenu.

Remarque

Les modes Alibaba Cloud CLI tels que AK, StsToken, RamRoleArn, EcsRamRole, OIDC, CloudSSO, OAuth et ChainableRamRoleArn sont pris en charge. Pour les identifiants dynamiques (tels que RamRoleArn), les jetons temporaires Security Token Service sont actualisés automatiquement.

Méthode de configuration

chmod 600 ~/.workbench/config.json

Spécifiez les éléments suivants selon les invites :

  • aliyun_profile (facultatif) : le nom du profil Alibaba Cloud CLI à réutiliser. Si vous laissez ce champ vide, le profil Alibaba Cloud CLI actuel est utilisé.

Aperçu du résultat de la configuration

Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json. Voici un exemple de configuration complète :

chmod 600 ~/.workbench/config.json

Mettre à niveau Workbench CLI

Workbench CLI prend en charge la mise à niveau automatique en une étape. Exécutez la commande suivante pour passer à la dernière version :

chmod 600 ~/.workbench/config.json

Le processus de mise à niveau télécharge et vérifie automatiquement le binaire de la dernière version, puis remplace la version actuelle.

Remarque

Si le binaire est installé dans un répertoire nécessitant des privilèges d'administrateur (par exemple, /usr/local/bin sous Linux ou macOS), utilisez sudo workbench upgrade.

Désinstaller

Workbench CLI n'enregistre aucun service système ni ne modifie les configurations système. Pour le désinstaller, arrêtez le démon, supprimez le binaire et, éventuellement, supprimez le répertoire de configuration local.

Remarque

Les commandes précédentes nettoient uniquement l'interface CLI locale et les informations d'identification locales. L'utilisateur RAM et la clé AccessKey dans le cloud ne sont pas supprimés. Pour les supprimer également, connectez-vous à la console RAM et supprimez l'utilisateur RAM correspondant ou désactivez la clé AccessKey.

FAQ

La commande workbench renvoie « command not found » après l'installation

Cause : Le répertoire ajouté au PATH par le script d'installation n'est pas pris en compte dans la session shell actuelle.

Solution :

  • Linux ou macOS : rouvrez le terminal, exécutez source ~/.bashrc (ou ~/.zshrc), ou utilisez le chemin absolu /usr/local/bin/workbench version pour vérifier.

  • Windows : fermez puis rouvrez la fenêtre PowerShell.

La commande workbench config renvoie une erreur d'autorisation sur le fichier de configuration

Cause : L'interface CLI rejette le fichier ~/.workbench/config.json si ses autorisations sont trop larges (par exemple, 0644 ou accessible en lecture par le groupe) afin d'empêcher les autres utilisateurs de la même machine de lire vos informations d'identification.

Solution : sous Linux ou macOS, exécutez la commande suivante pour corriger les autorisations :

chmod 600 ~/.workbench/config.json

La commande workbench list ecs renvoie InvalidAccessKeyId.NotFound ou IncompleteSignature

Cause : il s'agit généralement de l'une des situations suivantes :

  • L'ID AccessKey ou la clé secrète AccessKey saisis lors de la configuration sont incorrects (par exemple, ils comportent des espaces au début ou à la fin, ou n'ont pas été copiés intégralement).

  • La clé AccessKey correspondante a été désactivée ou supprimée dans la console RAM.

Solution : réexécutez workbench config et vérifiez que l'ID AccessKey et la clé secrète AccessKey appartiennent à la même paire, sont complets et ne contiennent aucun espace supplémentaire ; ou confirmez dans la console RAM que le statut de la clé AccessKey est Enabled.

Références

Linux ou macOS

Exécutez les commandes suivantes dans l'ordre :

chmod 600 ~/.workbench/config.json

La troisième commande (qui supprime ~/.workbench) est facultative et permet de supprimer tous les identifiants et fichiers de configuration locaux.

Windows

Exécutez les commandes suivantes dans l'ordre sous PowerShell :

chmod 600 ~/.workbench/config.json

La suppression du répertoire .workbench est facultative et permet de supprimer tous les identifiants et fichiers de configuration locaux.