aws ec2 describe-instances: Query EC2 in CI

List EC2 instances, filtered by tag, state, or other attributes.

aws ec2 describe-instances returns detailed instance data. Its nested Reservations/Instances structure makes --filters and --query essential. In CI it locates instances by tag to read an IP, instance ID, or state for follow-up steps.

Common flags

--filters "Name=tag:Name,Values=web" - filter by tag or attribute
--instance-ids - target specific instances
--query "Reservations[].Instances[].InstanceId" - flatten the nested structure
--output text - emit plain text for shell capture

Example in CI

Find running instance IDs by tag.

shell

aws ec2 describe-instances --filters "Name=tag:env,Values=ci" "Name=instance-state-name,Values=running" --query "Reservations[].Instances[].InstanceId" --output text

Common errors in CI

An error occurred (UnauthorizedOperation) - role lacks ec2:DescribeInstances
An error occurred (InvalidInstanceID.NotFound) - instance ID is wrong or terminated
Empty output - the filter matched nothing (often a tag-key typo)

Key takeaways

Output is nested under Reservations[].Instances[] - flatten it with --query.
Combine multiple --filters to narrow by tag and instance state.
An empty result usually means a tag-key typo, not a permissions issue.