インフラストラクチャ検証スキル

技術スタック: AWS CLI、Terraform、VPC、CloudWatch、bash

出典: PDF S3 アップロードタイムアウト調査(2026-01-05)およびインフラストラクチャ・アプリケーション契約原則から抽出

---

このスキルを使用する場合

以下の場合にインフラストラクチャ検証スキルを使用してください:

• ✓ Lambda-in-VPC コードをデプロイする前
• ✓ Lambda 接続タイムアウトを調査する場合
• ✓ 決定的なエラーパターン(最初の N 個は成功、最後の M 個が失敗)をデバッグする場合
• ✓ AWS サービス(S3、DynamoDB、RDS)へのネットワークパスを検証する場合
• ✓ VPC エンドポイント追加後
• ✓ Lambda 同時実行を実行する前

このスキルを使用しないでください:

• ✗ アプリケーションコードのデバッグ(error-investigation を使用)
• ✗ パフォーマンス最適化(焦点が異なります)
• ✗ IAM パーミッション問題(AWS CLI を直接使用)

---

コア検証原則

原則 1: インフラストラクチャ依存性の検証

CLAUDE.md 原則 #15 から:

「AWS インフラストラクチャ(S3、VPC エンドポイント、NAT Gateway)に依存するコードをデプロイする前に、インフラストラクチャが存在し、正しく構成されていることを確認してください。ネットワークパスの問題は決定的なエラーパターンを引き起こします。」

検証を行う場合:

• Lambda 関数が AWS サービス呼び出しを行う場合のデプロイ前
• Terraform インフラストラクチャの変更後
• Lambda タイムアウトパターンを調査する場合
• 同時実行制限を増加させる前

原則 2: パターン認識

エラーパターンの種類:

パターン	根本原因	調査優先度
最初の N 個成功、最後の M 個失敗	インフラストラクチャボトルネック(NAT、接続制限)	高 - VPC エンドポイント欠落
ランダムな分散エラー	パフォーマンス問題(低速 API、メモリ)	中 - コード最適化
すべての操作が失敗	設定の問題(パーミッション、エンドポイント)	高 - 設定を修正
間欠的なエラー	レート制限、一時的なネットワーク問題	低 - リトライを追加

決定的なパターン(最初の N 個成功、最後の M 個失敗)はインフラストラクチャボトルネックの最も強い信号です。

---

検証ワークフロー

ワークフロー 1: VPC エンドポイント検証

使用する場合: Lambda-in-VPC が S3 または DynamoDB にアクセスする必要がある場合

手順:

# 1. VPC エンドポイントが存在するか確認
aws ec2 describe-vpc-endpoints \
  --filters "Name=vpc-id,Values=vpc-xxx" \
            "Name=service-name,Values=com.amazonaws.ap-southeast-1.s3" \
  --query 'VpcEndpoints[*].{ID:VpcEndpointId,State:State,Service:ServiceName}' \
  --output table

# 予想される出力(エンドポイントが存在する場合):
# -----------------------------------------
# | DescribeVpcEndpoints                  |
# +-------+-------+------------------------+
# | ID    | State | Service                |
# +-------+-------+------------------------+
# | vpce-xxx | available | com.amazonaws.ap-southeast-1.s3 |
# +-------+-------+------------------------+

# 空の場合 → S3 VPC エンドポイントがない(トラフィックは NAT Gateway を通る)

# 2. エンドポイントの状態を確認
aws ec2 describe-vpc-endpoints \
  --vpc-endpoint-ids vpce-xxx \
  --query 'VpcEndpoints[0].State' \
  --output text

# 予想: "available"
# "pending" の場合 → 作成完了を待つ
# "failed" の場合 → Terraform ログを確認

# 3. ルートテーブルアタッチを確認
aws ec2 describe-vpc-endpoints \
  --vpc-endpoint-ids vpce-xxx \
  --query 'VpcEndpoints[0].RouteTableIds' \
  --output table

# 予想: ルートテーブル ID のリスト(Lambda サブネットのルートテーブルを含む必要があります)

# 4. Lambda サブネットのルートテーブルを確認
aws lambda get-function-configuration \
  --function-name my-function \
  --query 'VpcConfig.SubnetIds' \
  --output text | xargs -I {} aws ec2 describe-subnets --subnet-ids {}

# 比較: Lambda サブネットのルートテーブルは VPC エンドポイントの RouteTableIds に含まれるべき

# 5. ルートテーブル内の S3 プレフィックスリストを確認
ROUTE_TABLE_ID=$(aws ec2 describe-route-tables \
  --filters "Name=vpc-id,Values=vpc-xxx" \
  --query 'RouteTables[0].RouteTableId' \
  --output text)

aws ec2 describe-route-tables \
  --route-table-ids $ROUTE_TABLE_ID \
  --query 'RouteTables[*].Routes[?GatewayId==`vpce-xxx`]'

# 予想: DestinationPrefixListId を持つルート(S3 プレフィックスリスト)

検証チェックリスト:

• VPC エンドポイントが存在する(describe-vpc-endpoints が結果を返す)
• 状態が「available」である(「pending」または「failed」ではない)
• ルートテーブルがアタッチされている(Lambda サブネットのルートテーブルを含む)
• S3 プレフィックスリストルートが作成されている(ルートテーブルを確認)

一般的な問題:

• VPC エンドポイント欠落 → Terraform で作成
• 状態「pending」 → 2～3 分待つ
• ルートテーブルが未アタッチ → Terraform の route_table_ids を更新
• Lambda サブネットが未対応 → サブネットのルートテーブル ID を確認

ワークフロー 2: NAT Gateway 診断

使用する場合: 外部サービスとの Lambda 接続タイムアウトを調査する場合

手順:

# 1. NAT Gateway が存在するか確認
aws ec2 describe-nat-gateways \
  --filter "Name=vpc-id,Values=vpc-xxx" \
  --query 'NatGateways[*].{ID:NatGatewayId,State:State,PublicIp:NatGatewayAddresses[0].PublicIp}' \
  --output table

# 予想: 状態「available」

# 2. NAT Gateway を使用しているルートテーブルを確認
aws ec2 describe-route-tables \
  --filters "Name=vpc-id,Values=vpc-xxx" \
  --query 'RouteTables[*].Routes[?NatGatewayId!=`null`].[RouteTableId,DestinationCidrBlock,NatGatewayId]' \
  --output table

# 予想: ルート 0.0.0.0/0 → nat-xxx(NAT 経由のデフォルトルート)

# 3. 接続飽和パターンを分析
# この分析は Lambda 同時実行中に実行
aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --start-time $(date -d '5 minutes ago' +%s)000 \
  --filter-pattern "START RequestId" \
  --query 'events[*].timestamp' \
  --output text | xargs -n1 date -d @

# 実行パターンを確認:
# - すべてが 1 秒以内に開始 → 同時実行
# - 600 秒後にタイムアウト → NAT Gateway 飽和

# 4. 接続タイムアウトエラーを確認
aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --filter-pattern "ConnectTimeoutError" \
  --query 'events[*].message' \
  --output text

# エラーが見つかった場合 → NAT Gateway 接続制限に達しています

# 5. 同時接続需要を計算
CONCURRENT_LAMBDAS=$(aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --start-time $(date -d '1 minute ago' +%s)000 \
  --filter-pattern "START RequestId" \
  --query 'length(events)' \
  --output text)

echo "Concurrent Lambdas: $CONCURRENT_LAMBDAS"
echo "NAT Gateway connection limit: ~55,000 (但し確立レートに制限あり)"

NAT Gateway 飽和の指標:

• ✅ 決定的なパターン(最初の N 個成功、最後の M 個失敗)
• ✅ ログ内の ConnectTimeoutError
• ✅ 長い実行時間(600 秒 = boto3 デフォルトタイムアウト)
• ✅ タイムラインに同時開始を表示 → 成功/失敗の分割

解決策: S3/DynamoDB 用の VPC Gateway エンドポイントを追加して NAT をバイパス

ワークフロー 3: ネットワークパス検証

使用する場合: Lambda が AWS サービスに到達できることを確認する場合

手順:

# 1. Lambda VPC 設定を特定
aws lambda get-function-configuration \
  --function-name my-function \
  --query 'VpcConfig.{VpcId:VpcId,SubnetIds:SubnetIds,SecurityGroupIds:SecurityGroupIds}' \
  --output json

# VPC ID、サブネット ID、セキュリティグループ ID を保存

# 2. セキュリティグループのエグレスルールを確認
aws ec2 describe-security-groups \
  --group-ids sg-xxx \
  --query 'SecurityGroups[*].IpPermissionsEgress[*].{Proto:IpProtocol,Port:FromPort,Dest:IpRanges[0].CidrIp}' \
  --output table

# 予想: 0.0.0.0/0 許可(すべてのエグレス)
# 制限されている場合 → 宛先サービス用のルールを追加

# 3. Lambda サブネットのルートテーブルを確認
SUBNET_ID=$(aws lambda get-function-configuration \
  --function-name my-function \
  --query 'VpcConfig.SubnetIds[0]' \
  --output text)

ROUTE_TABLE_ID=$(aws ec2 describe-route-tables \
  --filters "Name=association.subnet-id,Values=$SUBNET_ID" \
  --query 'RouteTables[0].RouteTableId' \
  --output text)

aws ec2 describe-route-tables \
  --route-table-ids $ROUTE_TABLE_ID \
  --query 'RouteTables[*].Routes[*].[DestinationCidrBlock,GatewayId,NatGatewayId]' \
  --output table

# 予想されるルート:
# - local → vpc-xxx(VPC 内部)
# - 0.0.0.0/0 → nat-xxx(NAT 経由のインターネット) または vpce-xxx(エンドポイント経由の S3)

# 4. 実際のネットワークパスをテスト(テスト Lambda 呼び出しが必要)
# テンポラリテスト Lambda をデプロイ:
# - S3 への接続を試行
# - 接続詳細をログに記録
# - 成功/失敗を報告

# 5. テスト結果を分析
aws logs tail /aws/lambda/network-test --since 1m

# 以下を探す:
# - Connection established(成功)
# - Connection timeout(NAT 飽和)
# - Connection refused(セキュリティグループがブロック)
# - DNS resolution failure(VPC DNS 問題)

ネットワークパスチェックリスト:

• Lambda が VPC 内に存在する(VpcConfig が空でない)
• セキュリティグループが宛先へのエグレスを許可している
• ルートテーブルが宛先へのパスを持つ(NAT または VPC エンドポイント)
• AWS サービスの VPC エンドポイントが存在する(S3、DynamoDB)
• テスト呼び出しが接続性を確認している

ワークフロー 4: デプロイ後のインフラストラクチャ検証

使用する場合: インフラストラクチャ変更(VPC エンドポイント、セキュリティグループ)をデプロイした後

手順:

# 1. Terraform 出力を確認
cd terraform
terraform output s3_vpc_endpoint_id        # vpce-xxx を返すべき
terraform output s3_vpc_endpoint_state     # 「available」を返すべき

# 2. スモークテスト Lambda 呼び出しを実行
aws lambda invoke \
  --function-name my-function \
  --payload '{"test": true}' \
  /tmp/response.json

# 応答を確認
cat /tmp/response.json | jq .

# 3. CloudWatch ログで成功を確認
aws logs tail /aws/lambda/my-function --since 1m --follow

# 予想:
# - ConnectTimeoutError なし
# - 操作が予想時間で完了(600 秒ではなく 2～3 秒)
# - 成功メッセージが記録されている

# 4. 同時実行テスト(本番負荷をシミュレート)
for i in {1..10}; do
  aws lambda invoke \
    --function-name my-function \
    --payload "{\"id\": $i}" \
    --invocation-type Event \
    /tmp/response_$i.json &
done
wait

# 5. 同時実行結果を分析
aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --start-time $(date -d '5 minutes ago' +%s)000 \
  --filter-pattern "ConnectTimeoutError" \
  --query 'length(events)' \
  --output text

# 予想: 0(タイムアウトエラーなし)
# 0 より大きい場合 → インフラストラクチャの問題はまだ存在

# 6. 100% 成功率を確認
aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --start-time $(date -d '5 minutes ago' +%s)000 \
  --filter-pattern "✅" \
  --query 'length(events)' \
  --output text

# 予想: 10(すべての同時実行が成功)

デプロイ後チェックリスト:

• Terraform 出力がリソース作成を確認している
• スモークテスト呼び出しが成功している
• CloudWatch ログにエラーがない
• 同時実行テスト(10 個以上の呼び出し)
• 100% 成功率(タイムアウトなし)
• 実行時間が予想範囲内(600 秒ではなく 2～3 秒)

---

一般的なインフラストラクチャの問題

問題 1: S3 VPC エンドポイント欠落

症状:

• Lambda が 600 秒後にタイムアウト
• エラー: ConnectTimeoutError: Connect timeout on endpoint URL: "https://bucket.s3.region.amazonaws.com/..."
• パターン: 最初の N 個の同時操作が成功、最後の M 個がタイムアウト

診断:

# S3 VPC エンドポイントを確認
aws ec2 describe-vpc-endpoints \
  --filters "Name=vpc-id,Values=vpc-xxx" \
            "Name=service-name,Values=com.amazonaws.region.s3"

# 空の場合 → エンドポイントなし(S3 トラフィックは NAT を通る)

修正:

# terraform/s3_vpc_endpoint.tf
data "aws_route_tables" "vpc_route_tables" {
  vpc_id = data.aws_vpc.default.id
}

resource "aws_vpc_endpoint" "s3" {
  vpc_id            = data.aws_vpc.default.id
  service_name      = "com.amazonaws.${var.aws_region}.s3"
  vpc_endpoint_type = "Gateway"

  route_table_ids = data.aws_route_tables.vpc_route_tables.ids

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = "*"
      Action    = "s3:*"
      Resource  = "*"
    }]
  })

  tags = {
    Name = "s3-endpoint"
  }
}

output "s3_vpc_endpoint_id" {
  value = aws_vpc_endpoint.s3.id
}

output "s3_vpc_endpoint_state" {
  value = aws_vpc_endpoint.s3.state
}

検証:

cd terraform
terraform apply
terraform output s3_vpc_endpoint_state  # 「available」であるべき

# Lambda 呼び出しをテスト
aws lambda invoke --function-name my-function --payload '{}' /tmp/response.json
aws logs tail /aws/lambda/my-function --since 1m
# 予想: タイムアウトなし、2～3 秒で完了

問題 2: NAT Gateway 接続飽和

症状:

• 決定的なエラーパターン(最初の 5 個成功、最後の 5 個タイムアウト)
• すべてのタイムアウトが約 10 分後に発生(boto3 デフォルト + リトライ)
• タイムラインの分析に同時 Lambda 開始を表示

診断:

# Lambda 実行のタイムラインを確認
aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --start-time $(date -d '30 minutes ago' +%s)000 \
  --filter-pattern "START RequestId" \
  | jq -r '.events[] | .timestamp as $ts | ($ts/1000 | strftime("%H:%M:%S")) + " " + (.message | split(" ")[2])'

# 以下を探す:
# - すべてが 1 秒以内に開始(同時実行)
# - どの RequestId にエラーがあるか確認
aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --filter-pattern "ConnectTimeoutError" \
  | jq -r '.events[].message' | grep -o "RequestId: [a-z0-9-]*"

# パターン: 最後の N 個の RequestId が一貫して失敗

根本原因:

• NAT Gateway は接続確立レートが制限されている
• 同時 Lambda が S3 接続を同時に確立しようとする
• 最初の N 個の接続が成功 → アップロードが 2～3 秒で完了
• 最後の M 個の接続がキュー登録 → 最終的に 600 秒後にタイムアウト

修正: S3 VPC Gateway エンドポイントを追加(問題 1 を参照)

この修正が機能する理由:

• VPC Gateway エンドポイントは NAT Gateway をバイパス
• S3 トラフィックは AWS ネットワーク内で直接ルーティング
• 接続確立制限がない
• 無料(Gateway エンドポイントに時間単位の料金なし)

問題 3: セキュリティグループがエグレスをブロック

症状:

• Lambda が AWS サービスに接続できない
• エラー: 接続拒否またはタイムアウト
• すべての呼び出しが失敗(決定的なパターンではない)

診断:

# セキュリティグループのエグレスルールを確認
aws lambda get-function-configuration \
  --function-name my-function \
  --query 'VpcConfig.SecurityGroupIds[0]' \
  --output text | xargs -I {} aws ec2 describe-security-groups --group-ids {}

# HTTPS(ポート 443)を許可するエグレスルールを探す
# 予想: 0.0.0.0/0 または特定の AWS サービスプレフィックスリスト

修正:

# terraform/security_groups.tf
resource "aws_security_group_rule" "lambda_egress_https" {
  type              = "egress"
  from_port         = 443
  to_port           = 443
  protocol          = "tcp"
  cidr_blocks       = ["0.0.0.0/0"]
  security_group_id = aws_security_group.lambda.id
}

問題 4: ルートテーブルが VPC エンドポイントにアタッチされていない

症状:

• VPC エンドポイントが存在し「available」である
• Lambda は依然 S3 接続がタイムアウト
• 決定的なまたはランダムなエラー

診断:

# VPC エンドポイントのルートテーブルアタッチを確認
aws ec2 describe-vpc-endpoints \
  --vpc-endpoint-ids vpce-xxx \
  --query 'VpcEndpoints[0].RouteTableIds' \
  --output table

# Lambda サブネットのルートテーブルを取得
aws lambda get-function-configuration \
  --function-name my-function \
  --query 'VpcConfig.SubnetIds[0]' \
  --output text | xargs -I {} aws ec2 describe-route-tables \
  --filters "Name=association.subnet-id,Values={}" \
  --query 'RouteTables[0].RouteTableId' \
  --output text

# 比較: Lambda のルートテーブルはエンドポイントの RouteTableIds に含まれるべき

修正:

# terraform/s3_vpc_endpoint.tf
data "aws_route_tables" "vpc_route_tables" {
  vpc_id = data.aws_vpc.default.id
}

resource "aws_vpc_endpoint" "s3" {
  # ... その他の設定 ...

  # すべてのルートテーブルにアタッチ(Lambda サブネットを含む)
  route_table_ids = data.aws_route_tables.vpc_route_tables.ids
}

---

他のスキルとの統合

error-investigation との連携

• 以下の場合、error-investigation の前に infrastructure-verification を使用:
  • Lambda タイムアウトパターンを調査している
  • 接続エラーをデバッグしている
  • 決定的なエラーパターンを分析している
• 以下の場合、infrastructure-verification の後に error-investigation を使用:
  • インフラストラクチャが確認されたが、エラーが続く場合
  • アプリケーションログを分析する必要がある
  • ビジネスロジックのエラーをデバッグしている

デプロイスキルとの連携

• インフラストラクチャ検証を以下の場合に使用:
  • Lambda-in-VPC コードをデプロイする前
  • インフラストラクチャ変更をデプロイした後(Terraform apply)
  • デプロイ後検証中
• デプロイのスモークテストをインフラストラクチャ固有のチェックで補完

testing-workflow との連携

• インフラストラクチャ検証はデプロイ前テストの一形態
• インフラストラクチャ・アプリケーション契約を検証(CLAUDE.md 原則 #15)
• コードデプロイ前に設定問題をキャッチ

---

クイックリファレンス

VPC エンドポイントタイプ

タイプ	サービス	コスト	ユースケース
Gateway	S3、DynamoDB	無料	高スループットデータアクセス
Interface	ほとんどの AWS サービス	約 $7.50/月	その他のサービス(Secrets Manager など)

NAT Gateway 制限

制限	値	影響
同時接続数	55,000	理論上の最大値
接続確立レート	制限あり	同時 Lambda で飽和を引き起こす
データ転送コスト	$0.045/GB	大規模転送の場合は高コスト

推奨: S3/DynamoDB の VPC Gateway エンドポイントを使用(無料、無制限、高速)

一般的な AWS CLI コマンド

# VPC エンドポイント
aws ec2 describe-vpc-endpoints --vpc-endpoint-ids vpce-xxx

# NAT Gateway
aws ec2 describe-nat-gateways --nat-gateway-ids nat-xxx

# セキュリティグループ
aws ec2 describe-security-groups --group-ids sg-xxx

# ルートテーブル
aws ec2 describe-route-tables --route-table-ids rtb-xxx

# Lambda VPC 設定
aws lambda get-function-configuration --function-name my-function --query 'VpcConfig'

---

ファイル構成

.claude/skills/infrastructure-verification/
└── SKILL.md              # このファイル(完全なスキル)

---

参考資料

• VPC エンドポイント
• NAT Gateway
• Lambda VPC 設定
• バグハント報告書 - 実装調査
• CLAUDE.md 原則 #15(インフラストラクチャ・アプリケーション契約)
• CLAUDE.md 原則 #2(段階的なエビデンス強化)