Alibaba Cloud CLI:Migrate from legacy to plugin-based Alibaba Cloud CLI

Exemple de comparaison

Pour l'API DescribeRegions, la commande basée sur les plugins est la suivante :

aliyun ecs describe-regions --accept-language zh-CN

L'ancienne commande est la suivante :

aliyun ecs DescribeRegions --AcceptLanguage zh-CN

Dans ce cas, seul le style de nommage change. Cependant, certaines commandes de plugins redéfinissent entièrement les paramètres. Par exemple, --biz-region-id remplace --region-id, ce qui ne correspond pas à une simple conversion de casse de l'ancien paramètre --RegionId. Vérifiez toujours les noms des paramètres avec <command> --help ou via OpenAPI Explorer.

Différences principales

Exécutez la commande suivante pour vérifier votre version. Si le résultat indique la version 3.3.0 ou ultérieure, votre CLI prend déjà en charge les commandes basées sur les plugins. Sinon, effectuez d'abord la mise à niveau.

aliyun version

Pour déterminer si une commande spécifique utilise la version basée sur les plugins ou l'ancienne version, exécutez aliyun <command> <sub-command> --help :

• Version basée sur les plugins : La sortie d'aide inclut une section de paramètres globaux et les noms des paramètres utilisent généralement le style kebab-case (par exemple, --region-id).

• Ancienne version : La sortie d'aide inclut uniquement une section de paramètres et les noms des paramètres utilisent généralement le style PascalCase (par exemple, --RegionId).

Rechercher via OpenAPI Explorer

Si vous connaissez le nom de l'ancienne commande (le nom de l'action API), il s'agit de la méthode la plus directe :

1. Ouvrez OpenAPI Explorer.

2. Dans la zone de recherche, saisissez le nom de l'ancienne commande (par exemple, DescribeInstances). Les résultats de la recherche répertorient les API correspondantes.

3. Cliquez sur l'API cible pour accéder à sa page de détails, renseignez les valeurs des paramètres requis, puis basculez vers l'onglet CLI Example à droite.

4. La commande basée sur les plugins s'affiche sous CLI Style (New) et l'ancienne commande s'affiche sous API Native Style (Old). Copiez la nouvelle commande pour remplacer l'ancienne dans votre script.

Parcourir la page d'accueil de la CLI

La page d'accueil de la CLI sur OpenAPI Explorer répertorie toutes les commandes basées sur les plugins prises en charge, organisées par service cloud, ainsi que les descriptions des paramètres.

Découvrir les commandes avec --help

Après avoir installé un plugin de service cloud, utilisez --help à chaque niveau pour parcourir les commandes et paramètres disponibles. Par exemple, pour afficher toutes les commandes du plugin ECS :

aliyun ecs --help

Pour afficher l'utilisation et les paramètres d'une commande spécifique :

aliyun ecs describe-instances --help

Interroger à l'aide de CLI Skills

Accédez à CLI Skills, installez la compétence et décrivez vos besoins en langage naturel via un agent pour obtenir la commande basée sur les plugins correspondante.

Étape 1 : Mettre à niveau la CLI

Vérifiez votre version actuelle :

aliyun version

Si la version est antérieure à la 3.3.0, suivez les instructions de la rubrique Installer et mettre à jour Alibaba Cloud CLI pour effectuer la mise à niveau. Il n'est pas nécessaire de désinstaller l'ancienne version ; votre configuration d'identifiants (~/.aliyun/config.json) est conservée.

Après la mise à niveau, les anciennes commandes restent fonctionnelles. Les nouvelles fonctionnalités, la prise en charge des produits et les correctifs de sécurité sont fournis exclusivement dans la version basée sur les plugins.

Étape 2 : Installer les plugins

Installez les plugins de service cloud dont vous avez besoin :

# Install a single plugin
aliyun plugin install --name ecs

# Install multiple plugins
aliyun plugin install --names ecs oss vpc

Vous pouvez également activer l'installation automatique des plugins. Lorsque vous exécutez une commande dont le plugin est manquant, la CLI l'installe automatiquement :

export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

Étape 3 : Vérifier une commande

Exécutez une commande basée sur les plugins pour vérifier que tout fonctionne correctement :

aliyun ecs describe-regions

Une liste JSON des régions confirme que la CLI basée sur les plugins fonctionne.

Étape 4 : Mettre à jour vos scripts

Remplacez progressivement les anciennes commandes de vos scripts par la syntaxe basée sur les plugins :

1. Identifiez les anciennes commandes dans vos scripts. Un indicateur courant est que le deuxième argument utilise le style PascalCase (par exemple, aliyun ecs DescribeInstances).

2. Recherchez le nom de l'ancienne commande dans OpenAPI Explorer pour trouver son équivalent basé sur les plugins.

3. Remplacez l'ancienne commande par son équivalent basé sur les plugins et mettez à jour les noms des paramètres en conséquence.

4. Testez le script mis à jour.

Les anciennes commandes restent fonctionnelles dans la nouvelle version, ce qui vous permet de migrer par lots en fonction des priorités.

Pipelines CI/CD

Dans les environnements non interactifs, la CLI ne peut pas demander l'installation de plugins. Utilisez l'une des approches suivantes :

• Préinstallez les plugins dans votre script de pipeline :

  aliyun plugin install --names ecs oss vpc

• Ou définissez une variable d'environnement pour activer l'installation automatique :

  export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

Ajoutez cette variable à la configuration d'environnement global de votre pipeline (le bloc environment dans un Jenkinsfile ou la section env dans GitHub Actions) afin qu'elle s'applique à chaque build.

Scripts d'analyse de sortie

Les commandes basées sur les plugins peuvent renvoyer des structures JSON différentes de celles des anciennes commandes, qui transmettent les réponses API brutes. Si vos scripts analysent la sortie avec jq, grep ou des outils similaires, vérifiez le format de sortie après la transition.

Migration de commandes complexes

Les commandes comportant des paramètres complexes constituent la partie la plus sujette aux erreurs lors de la migration.

aliyun slb AddBackendServers \
  --LoadBalancerId lb-xxx \
  --BackendServers '[{"ServerId":"i-aaa","Weight":100},{"ServerId":"i-bbb","Weight":80}]'

aliyun slb add-backend-servers \
  --load-balancer-id lb-xxx \
  --backend-servers '[{"ServerId":"i-aaa","Weight":100},{"ServerId":"i-bbb","Weight":80}]'

aliyun ecs run-instances \
  --region cn-hangzhou \
  --instance-type ecs.g7.large \
  --image-id ubuntu_22_04_x64_20G_alibase_20230China.vhd \
  --security-group-id sg-xxx \
  --vswitch-id vsw-xxx \
  --system-disk "$(cat <<'EOF'
{"Size":40,"Category":"cloud_essd","PerformanceLevel":"PL1"}
EOF
)"

aliyun ecs DescribeInstances --RegionId cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

# Plugin-based version: first, check the output structure, then adjust the jq expression.
aliyun ecs describe-instances --region cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

Affichage de l'aide de l'ancienne version

Après l'installation d'un plugin de produit, aliyun <command> --help affiche par défaut l'aide du plugin. Pour afficher l'aide de l'ancienne version à la place, définissez :

export ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true

Puis-je toujours utiliser les anciennes commandes PascalCase après la mise à niveau ?

Oui. Les versions 3.3.0 et ultérieures assurent la rétrocompatibilité. Toutefois, seule la version basée sur les plugins reçoit les nouvelles fonctionnalités et les correctifs.

Dois-je reconfigurer mes identifiants après la migration ?

Non. La CLI basée sur les plugins partage le même magasin d'identifiants (~/.aliyun/config.json). Toutes les entrées profile et les identifiants définis via les variables d'environnement sont conservés.

Puis-je mélanger les anciennes commandes et les commandes basées sur les plugins dans le même script ?

Oui. Les deux styles coexistent dans le même script. Remplacez progressivement les anciennes commandes en fonction des priorités.

Que faire si l'installation du plugin échoue ?

Procédez au dépannage dans l'ordre suivant :

1. Vérifiez si votre réseau peut accéder à aliyuncli.alicdn.com.

2. Vérifiez que le répertoire d'installation des plugins (~/.aliyun/plugins/) dispose des autorisations d'écriture.

3. Confirmez que votre version de la CLI est la 3.3.0 ou ultérieure (les versions antérieures ne prennent pas en charge les plugins). Exécutez aliyun version pour vérifier.