Utilisation du mode de mise à niveau et de débogage pour mettre à niveau la version 1 de la AWS CLI vers la version 2 de la AWS CLI

Nous recommandons aux utilisateurs de la version 1 de la AWS CLI de passer à la version 2 de la AWS CLI pour accéder à de nouvelles fonctionnalités et à des performances améliorées. Certains changements de comportement entre la version 1 de la AWS AWS CLI et la version 2 de la CLI peuvent vous obliger à mettre à jour vos scripts ou commandes pour obtenir le même comportement. Le mode de débogage de mise à niveau dans la version 1 de la AWS CLI génère des avertissements lorsque vous utilisez des fonctionnalités dont le comportement est différent dans la version 2 de la AWS CLI. Cette fonctionnalité améliore l'expérience de mise à niveau en détectant automatiquement les commandes de la version 1 de votre AWS CLI qui doivent être modifiées avant la mise à niveau vers la version 2 de la AWS CLI afin d'éviter des problèmes inattendus.

Pour en savoir plus, consultez Changements majeurs entre AWS CLI la version 1 et AWS CLI la version 2.

Lorsque vous passez de la version 1 de la AWS CLI à la version 2, Changements majeurs entre AWS CLI la version 1 et AWS CLI la version 2 cela peut affecter vos scripts et flux de travail existants. Le mode de mise à niveau et de débogage vous aide à identifier ces problèmes avant de terminer la migration.

Le mode de débogage de mise à niveau détecte lorsque vous utilisez des fonctionnalités présentant des modifications importantes dans la version 2 de la AWS CLI. Lorsque vous exécutez une commande qui s'interrompt après la mise à niveau, le mode affiche un avertissement avec des étapes spécifiques pour résoudre le problème. Cela vous fait gagner du temps en détectant automatiquement les problèmes potentiels au lieu de rechercher manuellement votre code.

Comment ça marche

S'il est activé, le mode de débogage de mise à niveau détecte l'utilisation des fonctionnalités mises à jour avec des modifications majeures dans la version 2 de la AWS CLI. Si vous utilisez une commande ou une fonctionnalité répertoriée dans notre Changements majeurs entre AWS CLI la version 1 et AWS CLI la version 2 après la mise à niveau vers la version 2 de la AWS CLI, un avertissement s'affichera dans le résultat. La détection des modifications intempestives est basée sur la commande utilisée, les arguments fournis, l'environnement d'exécution (par exemple, les variables d'environnement, les paramètres de configuration, etc.) et, dans certains cas, le contenu ou la configuration des ressources du AWS compte utilisé.

L'exemple suivant montre à quoi ressemblent ces avertissements. Cette commande illustre un exemple d'avertissement. Tout le texte d'avertissement commence par « AWS  CLI V2 UPGRADE WARNING », suivi du message d'avertissement spécifique. Dans ce cas, un avertissement est affiché car la commande s'appuie sur la AWS CLI pour récupérer le contenu de l'URL et utiliser le contenu comme valeur de --template-body paramètre, fonctionnalité supprimée dans la version 2 de la AWS CLI.

L'exemple suivant montre à quoi ressemble un avertissement :

$ aws cloudformation create-stack \
  --stack-name "stack012345" \
  --template-body "https://s3.amazonaws.com/amzn-s3-demo-bucket/template.json"

AWS CLI v2 UPGRADE WARNING: For input parameters that have a prefix of http:// or 
https://, AWS CLI v2 will not automatically request the content of the URL for 
the parameter, and the `cli_follow_urlparam` option has been removed. See 
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-paramfile.

Le tableau suivant présente toutes les modifications importantes et explique comment éviter de faire face à une modification radicale dans la version 2 de la AWS CLI. Les actions de correction qui résolvent les avertissements en mode débogage apparaissent en gras.

Un changement radical	Sur la v1, migrer vers le comportement v2	Sur la v2, conserver le comportement de la v1
Ajout d’une variable d’environnement pour définir l’encodage de fichiers texte	Dédéfinissez les variables PYTHONUTF8 d'PYTHONIOENCODINGenvironnement et.	Définissez la variable d'AWS_CLI_FILE_ENCODINGenvironnement sur le codage spécifié dans la version 1.
Les paramètres binaires sont transmis en tant que chaînes codées en base64 par défaut.	Codez la valeur du paramètre en base64. Si le paramètre est chargé depuis un fichier, codez le contenu du fichier en base64.	Réglez le cli_binary_format paramètre surraw-in-base64-out.
Amélioration de la gestion par Amazon S3 des propriétés des fichiers et des balises pour les copies partitionnées	N/A. Impossible de migrer vers le comportement de la version 2 dans la version 1.	Utilisez le --copy-props none paramètre.
Aucune récupération automatique de http:// ou https:// URLs pour les paramètres	Utilisez curl (ou d'autres outils) pour télécharger le contenu du dans URLs un fichier local. Chargez ensuite le contenu du fichier dans le paramètre avec file ://. Vous pouvez également cli_follow_urlparam configurer sur false pour spécifier l'URL brute comme valeur du paramètre.	N/A. Impossible de conserver le comportement de la version 1 dans la version 2.
Pager utilisé par défaut pour toutes les sorties	N/A. Impossible de migrer vers le comportement de la version 2 dans la version 1.	Définissez le cli_pager paramètre ou la AWS_PAGER variable sur une chaîne vide.
Normalisation de toutes les valeurs de sortie d’horodatage au format ISO 8601	Définissez le paramètre cli_timestamp _format suriso8601.	Réglez le cli_timestamp_format réglage sur câble.
Gestion améliorée des CloudFormation déploiements qui n'entraînent aucune modification	Utilisez le --no-fail-on-empty-changeset paramètre.	Utilisez le --fail-on-empty-changeset paramètre.
Modification du comportement par défaut du point de terminaison Amazon S3 régional pour la région us-east-1	Définissez la variable d'AWS_ENDPOINT_URL_S3environnement ou l'option de ligne de --endpoint-url commande sur l'URL régionale us-east-1.	Utilisez l'option --region aws-global de ligne de commande.
Retrait de la commande ecr get-login, remplacée par ecr get-login-password	(1.17.10 ou version ultérieure) Utilisez Retrait de la commande ecr get-login, remplacée par ecr get-login-password et dirigez la sortie vers une commande docker.	N/A. Impossible de conserver le comportement de la version 1 dans la version 2.
AWS CLI le support de la version 2 pour les plugins est en train de changer	N/A. Impossible de migrer vers le comportement de la version 2 dans la version 1.	Configurez le cli_legacy_plugin_path dans la section du fichier de configuration. [plugins] Testez les plugins dans la version 2, verrouillez votre version 2 et testez vos plugins à chaque mise à niveau.
Suppression de la prise en charge des alias masqués	Passez de l'alias masqué obsolète à Suppression de la prise en charge des alias masqués celui qui fonctionne dans toutes les versions.	N/A. Impossible de conserver le comportement de la version 1 dans la version 2.
Paramètre de fichier de configuration api_versions non pris en charge	Migrez et testez votre utilisation des anciennes versions d'API vers la dernière version d'API, et supprimez api_versions de vos paramètres de configuration.	N/A. Impossible de conserver le comportement de la version 1 dans la version 2.
AWS CLI la version 2 utilise uniquement Signature v4 pour authentifier les demandes Amazon S3	Spécifiez la version de signature jusqu'à la version 4 (voir Spécification de la version de signature dans l'authentification de la demande).	N/A. Impossible de conserver le comportement de la version 1 dans la version 2.
AWS CLI la version 2 est plus cohérente avec les paramètres de pagination	Déplacez les paramètres de pagination du paramètre JSON d'entrée vers la commande elle-même.	Supprimez les paramètres de pagination du paramètre JSON d'entrée.
AWS CLI la version 2 fournit des codes de retour plus cohérents pour toutes les commandes	N/A. Impossible de migrer vers le comportement de la version 2 dans la version 1.	N/A. Impossible de conserver le comportement de la version 1 dans la version 2.

Limitations

Nous recommandons vivement aux clients de consulter notreChangements majeurs entre AWS CLI la version 1 et AWS CLI la version 2.

Détection de changements brusques non prise en charge

La fonctionnalité du mode de mise à niveau et de débogage prend en charge toutes les modifications importantes, sauf celle-ciAWS CLI la version 2 fournit des codes de retour plus cohérents pour toutes les commandes. Ce mode ne peut pas prendre en compte la manière dont vous utilisez les codes d'erreur renvoyés par la AWS CLI en aval.

Détection des modifications par rupture conditionnelle

La détection de Normalisation de toutes les valeurs de sortie d’horodatage au format ISO 8601 est le seul cas où la détection dépend de l'état du AWS compte et peut être sujette à des modifications importantes si les ressources du compte sont mises à jour ultérieurement. Si aucun horodatage n'est inclus dans la réponse de l'API du service, aucune détection ne sera effectuée pour cette modification majeure.

Si vous utilisez le format d'horodatage renvoyé par les commandes de la AWS CLI et que vous n'avez pas encore configuré la AWS CLI pour utiliser la norme ISO 8601, prenez des précautions supplémentaires pour vous assurer que le traitement de l'horodatage ne sera pas interrompu après la mise à niveau vers la version 2.

Détection de changements de rupture irrésolus

Certains avertissements générés par le mode de mise à niveau et de débogage ne peuvent pas être résolus en modifiant la commande ou l'environnement. Dans les cas suivants, des avertissements sont toujours émis par le mode de mise à niveau et de débogage tant que vous utilisez la fonctionnalité correspondante :

• AWS CLI le support de la version 2 pour les plugins est en train de changer- si vous utilisez des plugins dans votre fichier de configuration, le mode de débogage de mise à niveau affichera toujours un avertissement qui ne pourra pas être résolu. Ce mode ne peut pas garantir que l'un de vos plugins fonctionnera dans la version 2 de la AWS CLI.

• Amélioration de la gestion par Amazon S3 des propriétés des fichiers et des balises pour les copies partitionnées - s'il aws s3 est utilisé pour effectuer une copie d' bucket-to-bucketAmazon Amazon S3, le mode de débogage de mise à niveau affichera toujours un avertissement qui ne pourra pas être résolu.

Fausses détections

Les avertissements émis par le mode de débogage de mise à niveau ne garantissent pas que des modifications majeures seront apportées après la mise à niveau vers la AWS CLI v2. Vous trouverez ci-dessous les cas où des avertissements seraient émis par le mode de mise à niveau et de débogage, bien qu'aucune modification majeure n'ait été introduite dans la AWS CLI v2 :

• Ajout d’une variable d’environnement pour définir l’encodage de fichiers texte- si les variables d'PYTHONIOENCODINGenvironnement PYTHONUTF8 ou sont spécifiées pour définir le codage du fichier texte et que le codage spécifié correspond déjà aux paramètres régionaux installés, l'avertissement peut être une fausse détection car le mode de débogage ne vérifie pas si le codage correspond aux paramètres régionaux installés.

• Amélioration de la gestion par Amazon S3 des propriétés des fichiers et des balises pour les copies partitionnées - si elle aws s3 est utilisée pour effectuer une copie bucket-to-bucket Amazon S3 et que la copie n'est pas en plusieurs parties parce que l'objet source est inférieur au seuil de plusieurs parties, une fausse détection sera émise.

• Normalisation de toutes les valeurs de sortie d’horodatage au format ISO 8601- si le paramètre de configuration cli_timestamp_format est défini sur wire (par défaut) et qu'un horodatage au format ISO 8601 est renvoyé par le service.

• Gestion améliorée des CloudFormation déploiements qui n'entraînent aucune modification- si le --fail-on-empty-changeset drapeau est utilisé avec la aws cloudformation deploy commande et que l'ensemble de modifications obtenu est vide, une fausse détection sera émise. De plus, si le changeset n'est pas vide et n'--no-fail-on-empty-changesetest pas utilisé, une fausse détection sera émise.

• Modification du comportement par défaut du point de terminaison Amazon S3 régional pour la région us-east-1- si aws s3 ou aws s3api est utilisé pour effectuer une opération Amazon S3, que la région est configurée pour, mais que la s3.us_east_1_regional_endpoint configuration n'est pas configurée comme régionaleus-east-1, et que le point de terminaison Amazon S3 mondial est utilisé pour la demande en raison des paramètres de configuration du point de terminaison, l'avertissement peut être une fausse détection, car le mode de débogage ne vérifie pas les paramètres du point de terminaison configurés.

Configurer le mode de mise à niveau et de débogage

Vous pouvez activer ou désactiver le mode de mise à niveau de débogage à l'aide des méthodes suivantes, répertoriées par ordre de priorité :

• Les options de ligne de commande activent ou désactivent le mode de mise à niveau pour une seule commande. Utilisez --v2-debug pour utiliser le mode de mise à niveau du débogage.

• Les variables d'environnement utilisent la variable AWS_CLI_UPGRADE_DEBUG_MODE.