Managing Resources with Tagging

Filter by tag, then trim the output with --query

• The unfiltered describe-instances output is overwhelming — most fields are not relevant for an inventory by tag.
• --filter filters server-side by tag; --query reshapes the JSON client-side using JMESPath.
• First version: list only InstanceId for every instance with Project=ERPSystem.

# Filter by tag and return only the instance IDs
aws ec2 describe-instances \
  --filter "Name=tag:Project,Values=ERPSystem" \
  --query 'Reservations[*].Instances[*].InstanceId'

The JMESPath expression Reservations[*].Instances[*].InstanceId uses wildcards to walk every reservation and every instance, projecting only that single field.

Add multi-field projection with aliases

• JMESPath supports {Alias:Field} syntax to rename fields in the output.
• Useful for building human-readable inventories where the raw schema is too noisy.

# Project ID and Availability Zone, renamed
aws ec2 describe-instances \
  --filter "Name=tag:Project,Values=ERPSystem" \
  --query 'Reservations[*].Instances[*].{ID:InstanceId,AZ:Placement.AvailabilityZone}'

Look up the value of a specific tag with a filter expression

• EC2 tags are returned as an array of {Key, Value} objects, so a direct projection on Tags.Project does not work.
• The pattern Tags[?Key==`Project`] | [0].Value filters the array to the element whose key is Project, pipes the single-element result to [0], and returns its Value.
• The same pattern is repeated for Environment and Version to build a full inventory row.

# Inventory: ID, AZ, Project, Environment, Version
aws ec2 describe-instances \
  --filter "Name=tag:Project,Values=ERPSystem" \
  --query 'Reservations[*].Instances[*].{
    ID:InstanceId,
    AZ:Placement.AvailabilityZone,
    Project:Tags[?Key==`Project`]      | [0].Value,
    Environment:Tags[?Key==`Environment`] | [0].Value,
    Version:Tags[?Key==`Version`]      | [0].Value
  }'

Add a second --filter for an AND condition

• Passing two Name=tag:... filters in the same command performs an AND: only instances matching both tags are returned.
• Here, the goal is the intersection of Project=ERPSystem and Environment=development — the development boxes of the ERP system.

# Double tag filter — ERPSystem dev only
aws ec2 describe-instances \
  --filter "Name=tag:Project,Values=ERPSystem" \
            "Name=tag:Environment,Values=development" \
  --query 'Reservations[*].Instances[*].{
    ID:InstanceId,
    AZ:Placement.AvailabilityZone,
    Project:Tags[?Key==`Project`]      | [0].Value,
    Environment:Tags[?Key==`Environment`] | [0].Value,
    Version:Tags[?Key==`Version`]      | [0].Value
  }'

Bulk-update the Version tag with a Bash script

• The script change-resource-tags.sh uses the same double-filter query but with --output text so the IDs can be piped directly into create-tags.
• aws ec2 create-tags either creates a new tag or overwrites an existing one — here it bumps Version from 1.0 to 1.1 on every ERP-dev instance in a single call.
• This is the simplest practical example of the pattern query → pipe IDs → act in bulk.

#!/bin/bash

# Collect IDs of all ERPSystem development instances
ids=$(aws ec2 describe-instances \
  --filter "Name=tag:Project,Values=ERPSystem" \
            "Name=tag:Environment,Values=development" \
  --query 'Reservations[*].Instances[*].InstanceId' \
  --output text)

# Overwrite Version tag to 1.1 on every collected instance
aws ec2 create-tags --resources $ids \
                   --tags 'Key=Version,Value=1.1'

How the script works

• Lives under ~/aws-tools/stopinator.php on the CommandHost.
• Iterates over every AWS region, calls Ec2::DescribeInstances() with a tag filter, then stops every matching instance with Ec2::StopInstances().
• Two arguments:
  • -t "Name=Value;Name=Value" — tag filter (semicolon-separated pairs). If omitted, stops every running instance in the account.
  • -s — switch to start mode instead of stop.
• Use case: shut down the dev environment at the end of the day, start it up the next morning.

Stop all ERP-dev instances

The script reports each region it scans and lists the identified instances before issuing the stop call:

cd ~/aws-tools
./stopinator.php -t"Project=ERPSystem;Environment=development"

# Output (abbreviated):
#   Region is us-east-1
#     No instances to stop in region
#   Region is us-west-2
#     Identified instance i-0798b4e50e2b64eae
#     Identified instance i-0c4838001b8a28add
#   Stopping all identified instances...

Restart the same set with -s

• Same tag filter, plus the -s flag to switch to start mode.
• No screenshot was captured of the restart; visible behaviour mirrors the stop call but with StartInstances in place of StopInstances and the instances eventually returning to Running in the console.

./stopinator.php -t"Project=ERPSystem;Environment=development" -s

Script logic in three blocks

• List tagged instances. describeInstances() with a filter for the existence of the Environment tag (any value). IDs go into a hash table.
• Diff against the subnet. Iterate over every instance in the target subnet; if its ID is not in the tagged hash, add it to a "to terminate" list.
• Terminate. A single Ec2::terminateInstances() call with the full ID list.

Preparing the test fleet

• In the EC2 console, removed the Environment tag from two private instances (Add/Edit Tags → delete the row → Save).
• This is the only way to create non-compliance in the lab, since every instance ships with the tag set.
• Copied the region (AZ minus the trailing letter) and the private subnet ID for the script arguments.

Run the script and verify

./terminate-instances.php -region us-west-2 \
                          -subnetid subnet-021318b87f05f11aa