Maîtrise avancée du filtrage des sorties AWS CLI avec JQ

Le filtrage des sorties AWS CLI devient compliqué lorsqu'une commande renvoie du JSON profondément imbriqué. Vous n'avez peut-être besoin que d'un seul ID d'instance, d'une valeur de tag ou d'un court rapport CSV, mais des commandes comme aws ec2 describe-instances renvoient bien plus de données que cela.

L'AWS CLI dispose d'une option intégrée --query qui utilise JMESPath, et c'est souvent l'outil approprié pour les recherches simples. jq est utile lorsque vous souhaitez un remodelage JSON plus riche, une logique conditionnelle, une sortie CSV ou des filtres réutilisables dans des scripts shell.

Commencez par la sortie JSON

jq lit le JSON, donc faites en sorte que l'AWS CLI renvoie explicitement du JSON :

aws ec2 describe-instances --output json

Vous pouvez également définir JSON comme format par défaut configuré avec aws configure, mais utiliser --output json dans les exemples et scripts rend la dépendance évidente.

Installez jq avec le gestionnaire de paquets de votre système s'il n'est pas déjà disponible :

sudo apt update && sudo apt install jq

sudo dnf install jq

brew install jq

Lire et inspecter le JSON AWS

Le filtre d'identité, ., renvoie le JSON d'entrée. Il est pratique lorsque vous voulez une sortie joliment formatée tout en apprenant la structure d'une réponse :

aws ec2 describe-instances --output json | jq '.'

Pour sélectionner une clé de premier niveau, utilisez la notation par points :

aws ec2 describe-instances --output json | jq '.Reservations'

La plupart des commandes AWS encapsulent les données utiles dans des tableaux. Pour les instances EC2, la structure est Reservations[] suivie de Instances[], donc vous avez généralement besoin des deux niveaux.

Itérer à travers les tableaux

Utilisez .[] pour émettre chaque élément d'un tableau. Cette commande affiche chaque ID d'instance EC2 dans toutes les réservations :

aws ec2 describe-instances --output json | jq '.Reservations[].Instances[].InstanceId'

Par défaut, la sortie des chaînes inclut les guillemets JSON. Ajoutez -r lorsque vous avez besoin de texte brut pour une boucle shell ou une autre commande :

aws ec2 describe-instances --output json | jq -r '.Reservations[].Instances[].InstanceId'

Vous pouvez également construire un objet plus petit avec seulement les champs qui vous intéressent :

aws ec2 describe-instances --output json |
  jq '.Reservations[].Instances[] | {id: .InstanceId, state: .State.Name, type: .InstanceType}'

Cela donne des enregistrements JSON compacts au lieu de la réponse EC2 complète.

Filtrer avec select()

Utilisez select() lorsque vous voulez seulement les enregistrements qui correspondent à une condition. Cet exemple liste les IDs des instances en cours d'exécution :

aws ec2 describe-instances --output json |
  jq -r '.Reservations[].Instances[] | select(.State.Name == "running") | .InstanceId'

Les littéraux de chaîne dans un filtre jq utilisent des guillemets doubles, comme "running". Si vous encapsulez tout le programme jq dans des guillemets simples, votre shell transmettra ces guillemets doubles en toute sécurité.

Pour une vérification plus spécifique, filtrez par type d'instance :

aws ec2 describe-instances --output json |
  jq -r '.Reservations[].Instances[] | select(.InstanceType == "t3.micro") | .InstanceId'

Gérer les champs optionnels en toute sécurité

Les ressources AWS omettent souvent des champs. Les tags sont un exemple courant. Si une instance n'a pas de tableau Tags, .Tags[] peut échouer. Utilisez l'itérateur optionnel .Tags[]? :

aws ec2 describe-instances --output json |
  jq '.Reservations[].Instances[] | {id: .InstanceId, name: (.Tags[]? | select(.Key == "Name") | .Value)}'

Cela fonctionne, mais peut ne produire aucune valeur name lorsque le tag est manquant. Pour les scripts, une valeur par défaut est généralement plus facile à consommer :

aws ec2 describe-instances --output json |
  jq '.Reservations[].Instances[] | {
    id: .InstanceId,
    name: ((.Tags[]? | select(.Key == "Name") | .Value) // "unnamed")
  }'

Renvoyer un tableau au lieu d'un flux

De nombreux filtres jq émettent un flux de valeurs. Si un autre outil attend un tableau JSON valide, encapsulez l'expression entre crochets :

aws ec2 describe-instances --output json |
  jq '[.Reservations[].Instances[].InstanceId]'

Ceci est utile lorsque vous écrivez un fichier JSON pour une autre étape d'automatisation.

Exporter en CSV ou TSV

Pour des rapports compatibles avec les tableurs, construisez un tableau de champs et passez-le à @csv ou @tsv. Utilisez -r pour que jq écrive des lignes CSV brutes plutôt que des chaînes JSON :

aws ec2 describe-instances --output json |
  jq -r '.Reservations[].Instances[] | [.InstanceId, .InstanceType, .State.Name] | @csv'

Pour inclure une ligne d'en-tête, émettez-la avant les lignes de données :

aws ec2 describe-instances --output json |
  jq -r '["instance_id","instance_type","state"], (.Reservations[].Instances[] | [.InstanceId, .InstanceType, .State.Name]) | @csv'

Exemple pratique : Trouver les Elastic IPs non attachées

Les adresses Elastic IP non attachées peuvent générer des coûts évitables. Cette commande liste les IPs publiques où AWS n'a pas renvoyé d'AssociationId :

aws ec2 describe-addresses --output json |
  jq -r '.Addresses[] | select(.AssociationId == null) | .PublicIp'

Si elle affiche des adresses, examinez-les avant de les libérer :

aws ec2 release-address --allocation-id eipalloc-0123456789abcdef0

N'enchaînez pas directement les commandes de libération à partir d'une requête de découverte avant d'avoir vérifié les résultats. Une courte étape de vérification coûte moins cher que de récupérer après la suppression d'une mauvaise ressource.

Quand utiliser --query à la place

Utilisez --query de l'AWS CLI pour les projections simples car elle s'exécute avant le formatage de la sortie et maintient la commande autonome :

aws ec2 describe-instances \
  --query 'Reservations[].Instances[].InstanceId' \
  --output text

Recourez à jq lorsque le résultat nécessite plus de transformations, comme des valeurs de repli, le formatage CSV, la combinaison de champs ou des filtres plus longs qui sont plus faciles à lire en syntaxe jq.

À retenir

Utilisez --output json comme point de jonction entre l'AWS CLI et jq. Combinez ensuite .[], select(), la construction d'objets, les valeurs par défaut // et la sortie brute -r pour transformer les grandes réponses AWS en données exactes dont votre script ou rapport a besoin.