Nouvelles fonctionnalités et modifications de la version 2 de l’AWS CLI

Cette rubrique décrit les nouvelles fonctionnalités et les changements de comportement entre la version 1 de l’AWS CLI et la version 2 de l’AWS CLI. Ces modifications peuvent vous obliger à mettre à jour vos scripts ou commandes pour obtenir le même comportement dans la version 2 que dans la version 1.

Nouvelles fonctionnalités de la version 2 de l’AWS CLI

La version 2 de l’AWS CLI est la version majeure la plus récente de l’AWS CLI, qui prend en charge toutes les dernières fonctionnalités. Certaines fonctionnalités introduites dans la version 2 ne sont pas rétrocompatibles avec la version 1, et vous devez effectuer une mise à niveau pour accéder à celles-ci. Ces fonctionnalités sont les suivantes :

Changements majeurs entre la version 1 de l’AWS CLI et la version 2 de l’AWS CLI

Cette section décrit tous les changements de comportement entre la version 1 de l’AWS CLI et la version 2 de l’AWS CLI. Ces modifications peuvent vous obliger à mettre à jour vos scripts ou commandes pour obtenir le même comportement dans la version 2 que dans la version 1.

Ajout d’une variable d’environnement pour définir l’encodage de fichiers texte

Par défaut, les fichiers texte pour Blob utilisent le même encodage que les paramètres régionaux installés. Comme la version 2 de l’AWS CLI utilise une version intégrée de Python, les variables d’environnement PYTHONUTF8 et PYTHONIOENCODING ne sont pas prises en charge. Pour définir un encodage de fichiers texte différent de celui des paramètres régionaux, utilisez la variable d’environnement AWS_CLI_FILE_ENCODING. L’exemple suivant configure l’AWS CLI pour ouvrir des fichiers texte en UTF-8 sous Windows.

AWS_CLI_FILE_ENCODING=UTF-8

Pour plus d’informations, consultez Configuration des variables d’environnement pour l’AWS CLI.

Les paramètres binaires sont transmis en tant que chaînes codées en base64 par défaut.

Dans l’AWS CLI, certaines commandes nécessitaient des chaînes codées en base64, tandis que d’autres nécessitaient des chaînes d’octets codées en UTF-8. Dans la version 1 de l’AWS CLI, le transfert de données entre deux types de chaînes codées nécessitait souvent un traitement intermédiaire. La version 2 de l’AWS CLI rend la gestion des paramètres binaires plus cohérente, ce qui permet de transmettre les valeurs d’une commande à l’autre de façon plus fiable.

Par défaut, la version 2 de l’AWS CLI transmet désormais tous les paramètres binaires d’entrée et de sortie en tant que blobs (objet binaire volumineux) de chaînes codées en base64. Pour plus d’informations, consultez Blob.

Pour revenir au comportement de la version 1 de l’AWS CLI, utilisez la configuration de fichier cli_binary_format ou le paramètre --cli-binary-format.

Amélioration de la gestion par Amazon S3 des propriétés des fichiers et des balises pour les copies partitionnées

Lorsque vous utilisez les commandes de la version 1 de l’AWS CLI dans l’espace de noms aws s3 pour copier un fichier d’un emplacement de compartiment S3 vers un autre, et que cette opération utilise la copie en plusieurs parties, aucune propriété de fichier de l’objet source n’est copiée vers l’objet de destination.

Par défaut, les commandes correspondantes de la version 2 de l’AWS CLI transfèrent toutes les balises et certaines propriétés de la source vers la copie de destination. Par rapport à la version 1 de l’AWS CLI, cela peut entraîner davantage d’appels d’API AWS vers le point de terminaison Amazon S3. Pour modifier le comportement par défaut des commandes s3 de la version 2 de l’AWS CLI, utilisez le paramètre --copy-props.

Pour plus d’informations, consultez Propriétés des fichiers et balises dans les copies partitionnées.

Aucune récupération automatique des URL http:// ou https:// pour les paramètres

La version 2 de l’AWS CLI n’effectue pas d’opération GET lorsqu’une valeur de paramètre commence par http:// ou https://, et n’utilise pas le contenu renvoyé comme valeur du paramètre. Par conséquent, l’option de ligne de commande associée cli_follow_urlparam est supprimée de la version 2 de l’AWS CLI.

Si vous devez récupérer une URL et transmettre son contenu dans la valeur d’un paramètre, nous vous recommandons d’utiliser curl ou un outil similaire pour télécharger le contenu de l’URL dans un fichier local. Ensuite, utilisez la syntaxe file:// pour lire le contenu de ce fichier et l’utiliser comme valeur du paramètre.

Par exemple, la commande suivante n'essaie plus de récupérer le contenu de la page se trouvant dans http://www.example.com et de le transmettre en tant que paramètre. Au lieu de cela, elle transmet la chaîne de texte littéral https://example.com en tant que paramètre.

$ aws ssm put-parameter \
    --value http://www.example.com \
    --name prod.microservice1.db.secret \
    --type String 2

Si vous voulez récupérer et utiliser le contenu d’une URL web comme paramètre, vous pouvez effectuer les opérations suivantes dans la version 2.

$ curl https://my.example.com/mypolicyfile.json -o mypolicyfile.json
$ aws iam put-role-policy \
    --policy-document file://./mypolicyfile.json \
    --role-name MyRole \
    --policy-name MyReadOnlyPolicy

Dans l’exemple précédent, le paramètre -o indique à curl qu’il doit enregistrer le fichier dans le dossier actuel avec le même nom que le fichier source. La deuxième commande récupère le contenu de ce fichier téléchargé et le transmet en tant que valeur de --policy-document.

Pager utilisé par défaut pour toutes les sorties

Par défaut, la version 2 de l’AWS CLI renvoie toutes les sorties via le programme de pager par défaut de votre système d’exploitation. Ce programme est le programme less sous Linux et macOS, et le programme more sous Windows. Cela peut vous aider à parcourir une grande quantité de sortie d’un service en affichant cette sortie une page à la fois.

Pour ce faire, vous pouvez configurer la version 2 de l’AWS CLI afin qu’elle utilise un programme de pagination différent ou aucun programme. Pour plus d’informations, consultez Pager côté client.

Normalisation de toutes les valeurs de sortie d’horodatage au format ISO 8601

Par défaut, la version 2 de l’AWS CLI renvoie toutes les valeurs de réponse d’horodatage au format ISO 8601. Dans la version 1 de l’AWS CLI, les commandes renvoyaient des valeurs d’horodatage dans n’importe quel format retourné par la réponse de l’API HTTP, qui pouvait varier d’un service à l’autre.

Pour afficher les horodatages au format renvoyé par la réponse de l’API HTTP, utilisez la valeur wire dans votre fichier config. Pour plus d’informations, consultez cli_timestamp_format.

Gestion améliorée des déploiements CloudFormation n’entraînant aucune modification

Par défaut, dans la version 1 de l’AWS CLI, si vous déployez un modèle CloudFormation qui n’entraîne aucune modification, l’AWS CLI renvoie un code d’erreur d’échec. Cela cause des problèmes si vous ignorez cette erreur et souhaitez que votre script continue. Vous pouvez contourner ce problème dans la version 1 de l’AWS CLI en ajoutant l’indicateur -–no-fail-on-empty-changeset, qui renvoie 0.

Comme il s’agit d’un cas d’utilisation courant, la version 2 de l’AWS CLI renvoie par défaut le code de sortie réussie 0 lorsque le déploiement n’entraîne aucun changement et que l’opération renvoie un jeu de modifications vide.

Pour revenir au comportement d’origine, ajoutez l’indicateur --fail-on-empty-changeset.

Modification du comportement par défaut du point de terminaison Amazon S3 régional pour la région us-east-1

Lorsque vous configurez la version 1 de l’AWS CLI pour utiliser la région us-east-1, l’AWS CLI utilise le point de terminaison global s3.amazonaws.com qui est physiquement hébergé dans la région us-east-1. La version 2 de l’AWS CLI utilise le véritable point de terminaison régional s3.us-east-1.amazonaws.com lorsque cette région est spécifiée. Pour forcer la version 2 de l’AWS CLI à utiliser le point de terminaison global, vous pouvez définir la région sur aws-global pour une commande.

Modification du comportement par défaut des point de terminaison AWS STS

Par défaut, la version 2 de l’AWS CLI envoie toutes les demandes d’API AWS Security Token Service (AWS STS) au point de terminaison régional pour la Région AWS actuellement configurée.

Par défaut, toute version antérieure à la version 1.42.0 de la version 1 de l’AWS CLI envoie des demandes AWS STS au point de terminaison global AWS STS. Vous pouvez contrôler ce comportement par défaut dans la version 1 à l’aide du paramètre sts_regional_endpoints. Toutes les versions à partir de la version 1.42.0 (incluse) utilisent également le point de terminaison régional par défaut. Si vous migrez vers la version 2 de l’AWS CLI à partir de ces versions plus récentes, ce comportement reste inchangé.

Retrait de la commande ecr get-login, remplacée par ecr get-login-password

La version 2 de l’AWS CLI remplace la commande aws ecr get-login par la commande aws ecr get-login-password qui améliore l’intégration automatisée avec authentification du conteneur.

La commande aws ecr get-login-password réduit le risque d'exposer vos informations d'identification dans la liste des processus, l'historique du shell ou d'autres fichiers journaux. Elle améliore également la compatibilité avec la commande docker login, permettant une meilleure automatisation.

La commande aws ecr get-login-password est disponible dans les versions 1.17.10 et ultérieures de l’AWS CLI, ainsi que dans la version 2 de l’AWS CLI. L’ancienne commande aws ecr get-login est toujours disponible dans la version 1 de l’AWS CLI pour la rétrocompatibilité.

Avec la commande aws ecr get-login-password, vous pouvez remplacer le code suivant qui récupère un mot de passe.

$ (aws ecr get-login --no-include-email)

Pour réduire le risque d'exposer le mot de passe à l'historique ou aux journaux du shell, utilisez plutôt l'exemple de commande suivant. Dans cet exemple, le mot de passe est transféré directement à la commande docker login, où il est affecté au paramètre password par l'option --password-stdin.

$ aws ecr get-login-password | docker login --username AWS --password-stdin MY-REGISTRY-URL

Pour plus d’informations, consultez aws ecr get-login-password dans le Guide de référence de la version 2 de l’AWS CLI.

Modification de la prise en charge des plug-ins dans la version 2 de l’AWS CLI

La prise en charge des plug-ins dans la version 2 de l’AWS CLI est complètement provisoire et destinée à aider les utilisateurs à migrer depuis la version 1 de l’AWS CLI jusqu’à ce qu’une interface de plug-ins stable et mise à jour soit publiée. Il n’existe aucune garantie qu’un plug-in particulier, ou même l’interface de plug-ins de l’AWS CLI, sera pris en charge dans les futures versions de la version 2 de l’AWS CLI. Si vous utilisez des plug-ins, assurez-vous de verrouiller une version particulière de l’AWS CLI et de tester leur fonctionnalité lorsque vous effectuez la mise à niveau.

Pour activer la prise en charge des plug-ins, créez une section [plugins] dans votre ~/.aws/config.

[plugins]
cli_legacy_plugin_path = <path-to-plugins>/python3.7/site-packages
<plugin-name> = <plugin-module>

Dans la section [plugins], définissez la variable cli_legacy_plugin_path et réglez sa valeur sur le chemin des packages du site Python sur lequel réside votre module de plug-ins. Vous pouvez ensuite configurer un plug-in en fournissant un nom pour celui-ci (plugin-name) et le nom de fichier du module Python (plugin-module) qui contient son code source. L’AWS CLI charge chaque plug-in en important son plugin-module et en appelant sa fonction awscli_initialize.

Suppression de la prise en charge des alias masqués

La version 2 de l’AWS CLI ne prend plus en charge les alias masqués suivants, qui étaient pris en charge dans la version 1.

Dans le tableau suivant, la première colonne affiche le service, la commande et le paramètre qui fonctionnent dans toutes les versions, y compris la version 2 de l’AWS CLI. La deuxième colonne affiche l’alias qui ne fonctionne plus dans la version 2 de l’AWS CLI.

Paramètre de fichier de configuration api_versions non pris en charge

La version 2 de l’AWS CLI ne prend pas en charge l’appel de versions antérieures des API de service AWS à l’aide du paramètre de fichier de configuration api_versions. Toutes les commandes AWS CLI appellent désormais la dernière version des API de service actuellement prises en charge par le point de terminaison.

Utilisation exclusive de Signature v4 dans la version 2 de l’AWS CLI pour authentifier les demandes Amazon S3

La version 2 de l’AWS CLI ne prend pas en charge les algorithmes de signature antérieurs pour authentifier de manière cryptographique les demandes de service envoyées aux points de terminaison Amazon S3. Cette signature s’effectue automatiquement à chaque demande Amazon S3 et seul le processus de Signature version 4 est pris en charge. Vous ne pouvez pas configurer la version de Signature. Toutes les URL présignées de compartiment Amazon S3 utilisent désormais uniquement SigV4 et ont une durée d’expiration maximale d’une semaine.

Meilleure cohérence de la version 2 de l’AWS CLI avec les paramètres de pagination

Dans la version 1 de l’AWS CLI, si vous spécifiez les paramètres de pagination sur la ligne de commande, la pagination automatique est désactivée comme prévu. Toutefois, lorsque vous spécifiez des paramètres de pagination à l’aide d’un fichier contenant le paramètre ‐‐cli-input-json, la pagination automatique n’est pas désactivée, ce qui peut entraîner une sortie inattendue. La version 2 de l’AWS CLI désactive la pagination automatique, quelle que soit la façon dont vous fournissez les paramètres.

Plus grande cohérence des codes de retour fournis par la version 2 de l’AWS CLI pour toutes les commandes

Par rapport à la version 1 de l’AWS CLI, la version 2 de l’AWS CLI offre une plus grande cohérence entre toutes les commandes et renvoie correctement un code de sortie approprié. Nous avons également ajouté les codes de sortie 252, 253 et 254. Pour plus d’informations sur les codes de sortie, consultez Codes de retour de ligne de commande dans l’AWS CLI.

Si vous êtes tributaire de la façon dont la version 1 de l’AWS CLI utilise les valeurs des codes de retour, nous vous recommandons de vérifier les codes de sortie pour vous assurer que vous obtenez les valeurs attendues.