はじめに
本書の目的
本ドキュメントは、AWS CLIのdescribe-instancesコマンドに関する調査結果を分かりやすくまとめたものです。基本的な使い方だけでなく、出力内容の読み方や実務での使い方まで順を追って解説します。初心者から中級者まで役立つ内容を目指します。
何が学べるか
- describe-instancesコマンドの概要と役割
- コマンドが返す主な情報項目の説明
- 実際の利用例とよく使うオプション
- 実務でのユースケースと注意点
想定読者
AWSの基本知識（アカウント、リージョン、インスタンスの概念）がある方を想定します。コマンドライン操作に不慣れな方も、手順や例を追えば理解できるように配慮しました。
注意点
コマンドは実行環境の認証情報やリージョン設定に依存します。出力には機密性のある情報が含まれる場合があるため、取り扱いにご注意ください。
describe-instancesコマンドの基本概要
概要
AWSのdescribe-instancesコマンドは、EC2インスタンスの詳細情報を取得するための基本コマンドです。特定のインスタンスIDを指定して個別に情報を取ることも、条件に合う複数のインスタンスをまとめて取得することもできます。管理者や運用担当者が現在の状態を把握する際に使います。
主な用途
- インスタンスの状態（running、stoppedなど）確認
- パブリックIPやプライベートIPの取得
- タグや起動時間などのメタ情報確認
基本構文（例）
aws ec2 describe-instances –instance-ids i-0123456789abcdef0
上のようにインスタンスIDを指定すると、そのインスタンスだけの情報を返します。指定しなければアカウント内の一致するすべてのインスタンスを取得します。
よく使うオプション
- –instance-ids：特定のインスタンスを指定
- –filters：タグや状態で絞り込む
- –region：対象のリージョンを指定
- –query／–output：出力を整形する
出力の見方（簡単に）
出力はJSON形式が一般的です。Reservations配下にInstances情報が入り、そこにIPアドレス、State、InstanceType、Tagsなどが含まれます。短く整形して必要な項目だけ取り出すと見やすくなります。
注意点
アクセスには適切なIAM権限が必要です。また大量のインスタンスを取得すると出力が大きくなるため、filtersやqueryで絞り込むことをお勧めします。
コマンドの動作メカニズム
概要
describe-instancesコマンドは、指定の仕方に応じて3つの主な動作パターンを持ちます。呼び出すとコントロールプレーンに問い合わせて、該当するインスタンス情報をJSONなどで返します。
1) インスタンスIDを指定した場合
特定のインスタンスIDを渡すと、そのIDに一致するインスタンスのみを返します。複数IDを指定すれば、そのリスト分だけ結果が返ります。CLI例:
aws ec2 describe-instances –instance-ids i-0123456789abcdef0
見つからないIDを指定すると、通常は対象が存在しない旨の空の結果またはエラーが返ります。
2) フィルター条件を指定した場合
フィルターは条件に合致するインスタンスを抽出します。例:
aws ec2 describe-instances –filters Name=instance-state-name,Values=running
複数のフィルターを指定すると全ての条件を満たす（AND）インスタンスが返り、1つのフィルター内で複数値を与えるとそのいずれかに合致する（OR）扱いになります。
3) インスタンスIDもフィルターも指定しない場合
何も指定しなければ環境内の全インスタンス情報を返します。大規模環境では応答サイズが大きくなるので、ページネーション（結果を分割して取得）を使うことを推奨します。CLIでは–max-itemsや–page-size、APIではNextTokenで制御します。
その他の挙動と注意点
- 呼び出しは同期的で、レスポンスに時間がかかることがあります。負荷回避のため絞り込みやページ分割を行ってください。
- 認可エラーやレート制限が発生することがあります。その場合はアクセス権やリトライを確認します。
- 出力はReservationやInstancesなどの構造を含みます。必要な項目だけ抽出することで処理が軽くなります。
出力に含まれる主要な情報
describe-instancesの出力には、インスタンスの状態やネットワーク、配置など運用で必要な情報がまとまって出ます。以下によく使う項目と簡単な説明、例を挙げます。
- InstanceId
- インスタンスの一意識別子。例: i-0123456789abcdef0
- State / StateReason
- 現在の状態（running、stoppedなど）と理由コード・メッセージ。トラブル時の原因把握に役立ちます。
- SpotInstanceRequestId
- スポットリクエストから起動した場合のリクエストID。スポット管理で参照します。
- SubnetId / VpcId
- ネットワークの所属先。どのサブネットにいるかを示します。例: subnet-0bb1c79de3EXAMPLE
- Placement
- Availability Zone（例: ap-northeast-1a）やPlacement Group名。高可用性やレイテンシ要件で重要です。
- PrivateIpAddress / PublicIpAddress
- 内部・外部のIP。接続先やセキュリティ設定で使います。
- InstanceType / ImageId
- マシンタイプ（例: t3.medium）やAMI ID。性能・イメージ確認に必要です。
- SecurityGroups
- 適用中のセキュリティグループ。アクセス制御を確認できます。
- BlockDeviceMappings
- アタッチ済みボリューム情報。ボリュームIDやデバイス名が分かります。
- Tags
- 運用用のメタ情報（Nameや環境タグなど）。検索やフィルタリングに便利です。
- KeyName / Monitoring
- SSH鍵名やモニタリング設定（CloudWatch有効/無効）も含まれます。
これらの項目を組み合わせると、問題発生時の原因特定や構成確認を効率よく行えます。
実践的な使用例
例1：インスタンスIDとサブネットIDをJSONで表示
aws ec2 describe-instances \
--query 'Reservations[].Instances[].{InstanceId:InstanceId,SubnetId:SubnetId}' \
--output json
説明: すべてのインスタンスからInstanceIdとSubnetIdだけを抽出してJSON配列で返します。スクリプトで扱いやすい形です。
例2：t2.microのインスタンスIDをテキストで抽出
aws ec2 describe-instances \
--filters Name=instance-type,Values=t2.micro \
--query 'Reservations[].Instances[].InstanceId' \
--output text
説明: フィルターでインスタンスタイプを限定し、InstanceIdだけをスペース区切りのテキストで得ます。シェル変数に簡単に格納できます。
例3：タグ情報を含めた表形式表示
aws ec2 describe-instances \
--query 'Reservations[].Instances[].{ID:InstanceId,State:State.Name,Type:InstanceType,AZ:Placement.AvailabilityZone,Tags:Tags}' \
--output table
説明: 表形式で見やすく表示します。Tagsは配列で出るため、必要なら別途–queryで特定のタグキーを抽出してください。
例4：メタデータ（IMDS）エンドポイントが有効なインスタンス
aws ec2 describe-instances \
--query 'Reservations[].Instances[?MetadataOptions.HttpEndpoint==`enabled`].{InstanceId:InstanceId, HttpTokens:MetadataOptions.HttpTokens}' \
--output json
説明: MetadataOptionsを調べてIMDSの有効化状態を抽出します。セキュリティ確認や設定チェックに便利です。
補足: –queryで表示項目を整え、–filtersで対象を絞り、–outputで形式を切り替えると効率的です。用途に応じて組み合わせて使ってください。
コマンドのパラメータ詳細
概要
describe-instancesでよく使う主なパラメータを分かりやすく説明します。出力の絞り込みや形式指定、検索条件を簡単に設定できます。
–query（JMESPath）
出力から必要な項目だけ取り出して整形します。JMESPathは配列やオブジェクトを参照する小さな言語です。例: –query “Reservations[].Instances[].{ID:InstanceId,State:State.Name}” はインスタンスIDと状態だけを返します。複雑にすると分かりにくくなるので、段階を追って作ると良いです。
–output（出力形式）
主な形式は json（詳細）、table（人間向け）、text（スクリプト向け）です。例: –output table と –query を組み合わせると見やすい表になります。
–filters（検索条件）
検索条件を指定します。例: –filters “Name=instance-state-name,Values=running” と指定すれば稼働中のインスタンスのみ取得します。複数指定するとフィルタ間はAND、同一フィルタ内のValuesはORで評価されます。例: –filters “Name=tag:Env,Values=prod” “Name=instance-type,Values=t2.micro,m5.large”。
注意点
- シェルのクオートに注意してください。JMESPathや複数のフィルタは正しく引用する必要があります。
- JMESPathは大文字小文字を区別します。
- 欲しいフィールドが存在しない場合は null になります。
実例（簡潔）
aws ec2 describe-instances –filters “Name=instance-state-name,Values=running” –query “Reservations[].Instances[].InstanceId” –output text
必要に応じて、より具体的な例や複雑なクエリもご用意します。
実用的なユースケース
以下では、describe-instancesコマンドを日常的に役立てる具体例をやさしく説明します。
1) 稼働状況の素早い把握
- 全インスタンスの稼働（running）・停止（stopped）を確認できます。例えば朝に一括で実行し、想定外の停止がないかをチェックします。
2) 在庫管理（インスタンス台帳）
- 組織のEC2一覧を出力し、タグや名前で集約します。複数リージョンを運用している場合は、各リージョンでコマンドを実行して集めます。CSVに変換して台帳に保存すると管理が楽です。
3) 特定条件での検索
- インスタンスタイプ（例：m5.large）やタグ（例：env=prod）で絞り込みます。コスト削減やリプレース候補の洗い出しに便利です。
4) 自動化と監視への組み込み
- スクリプトや監視ツールから定期実行してアラートに繋げます。停止中の長期間インスタンスや不要なリソースの検出に使います。
5) 運用・セキュリティ確認
- 公開IPの有無やアタッチされたボリュームなど、運用上の注意点を一度に確認できます。対策が必要なインスタンスをすばやく特定できます。
これらの使い方を組み合わせると、日々の運用効率とコスト管理が改善します。初心者の方はまずタグと稼働状況の確認から始めると分かりやすいです。
