aws_cloud_supporter

コンセプト

AWSを使って構築しているクラウドアプリケーションの運用を支援するツール基本的にCLIツールとして提供し、ビジュアライズはWebブラウザを利用する

現在の機能

1. CloudWatchメトリクス推奨生成

CloudFormationテンプレートを解析して、各AWSリソースに対する最適なCloudWatchメトリクスとアラーム推奨設定を自動生成します。

2. CDKコード自動生成 ✨NEW!

メトリクス分析結果から、実際にAWSにデプロイ可能なCDK TypeScriptコードを自動生成します。手動でのCloudWatchアラーム設定を完全自動化し、最適なしきい値と通知設定を含む本番対応のモニタリングシステムを即座に構築できます。

エンタープライズ機能:

🔐 セキュリティ保護: 機密情報自動サニタイズ、ディレクトリトラバーサル攻撃防止
📊 品質検証: TypeScript構文チェック、AWS制限監視、CDK best practices検証
🚨 SNS通知統合: 新規SNSトピック作成または既存トピック使用
⚡ 高性能: 252アラーム/2秒生成、メモリ効率99.8%
🎯 柔軟性: リソースタイプフィルタ、カスタムスタック名、ファイル出力制御

サポートリソース

AWS::RDS::DBInstance - 26種類のRDSメトリクス
AWS::Lambda::Function - 18種類のLambdaメトリクス
AWS::Serverless::Function - 18種類のSAM Lambdaメトリクス
AWS::ECS::Service - 17種類のECS（Fargate）メトリクス
AWS::ElasticLoadBalancingV2::LoadBalancer - 20種類のALBメトリクス
AWS::DynamoDB::Table - 22種類のDynamoDBメトリクス
AWS::ApiGateway::RestApi - 14種類のAPI Gatewayメトリクス
AWS::Serverless::Api - 14種類のSAM APIメトリクス

基本的な使い方

メトリクス分析（既存機能）

# CloudFormationテンプレートを解析してJSON形式で出力
npm run dev -- examples/web-application-stack.yaml

# HTML形式のレポートを生成
npm run dev -- examples/web-application-stack.yaml --output html --file report.html

# 特定のリソースタイプのみを対象
npm run dev -- examples/web-application-stack.yaml --resource-types "AWS::RDS::DBInstance,AWS::Lambda::Function"

# 低重要度メトリクスも含めて詳細出力
npm run dev -- examples/web-application-stack.yaml --include-low --verbose

CDKコード生成 ✨NEW!

# CDK TypeScriptコードを生成（標準出力）
npm run dev -- examples/serverless-api-sam.yaml --output cdk

# CDKコードをファイルに保存
npm run dev -- examples/serverless-api-sam.yaml --output cdk --cdk-output-dir ./cdk

# SNS通知付きCDKコードを生成
npm run dev -- examples/serverless-api-sam.yaml --output cdk --cdk-enable-sns

# 既存SNSトピックを使用
npm run dev -- examples/serverless-api-sam.yaml --output cdk --cdk-sns-topic-arn "arn:aws:sns:us-east-1:123456789012:my-topic"

# カスタムスタック名とコード検証
npm run dev -- examples/serverless-api-sam.yaml --output cdk --cdk-stack-name "ProductionAlarmsStack" --validate-cdk

# 特定リソースのみでCDK生成
npm run dev -- examples/web-application-stack.yaml --output cdk --resource-types "AWS::RDS::DBInstance"

出力例

JSON出力（メトリクス分析）:

{
  "metadata": {
    "version": "1.0.0",
    "generated_at": "2025-09-09T12:00:00.000Z",
    "template_path": "template.yaml",
    "total_resources": 10,
    "supported_resources": 8
  },
  "resources": [
    {
      "logical_id": "MyDatabase",
      "resource_type": "AWS::RDS::DBInstance",
      "metrics": [
        {
          "metric_name": "CPUUtilization",
          "namespace": "AWS/RDS",
          "unit": "Percent",
          "recommended_threshold": { "warning": 70, "critical": 90 },
          "evaluation_period": 300,
          "category": "Performance",
          "importance": "High"
        }
      ]
    }
  ]
}

CDK出力（CDKコード生成）:

import * as cdk from 'aws-cdk-lib';
import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
import * as sns from 'aws-cdk-lib/aws-sns';
import * as cloudwatchActions from 'aws-cdk-lib/aws-cloudwatch-actions';
import { Construct } from 'constructs';

/**
 * CloudWatch Alarms Stack for AWS Resources
 * Generated by AWS Cloud Supporter v1.0.0
 */
export class CloudWatchAlarmsStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // SNS Topic for alarm notifications
    const alarmTopic = new sns.Topic(this, 'AlarmNotificationTopic', {
      topicName: 'CloudWatchAlarmNotifications',
      displayName: 'CloudWatch Alarm Notifications'
    });

    // CPU利用率監視アラーム（Warning）
    const myDatabaseCPUUtilizationWarningAlarm = new cloudwatch.Alarm(this, 'MyDatabaseCPUUtilizationWarningAlarm', {
      alarmName: 'MyDatabase-CPUUtilization-Warning',
      alarmDescription: 'データベースインスタンスのCPU使用率',
      metric: new cloudwatch.Metric({
        namespace: 'AWS/RDS',
        metricName: 'CPUUtilization',
        dimensionsMap: {
          DBInstanceIdentifier: 'MyDatabase',
        },
        statistic: cloudwatch.Stats.AVERAGE,
        period: cdk.Duration.seconds(300)
      }),
      threshold: 70,
      evaluationPeriods: 1
    });

    // SNS通知アクション追加
    myDatabaseCPUUtilizationWarningAlarm.addAlarmAction(new cloudwatchActions.SnsAction(alarmTopic));
  }
}

3. CloudFormationテンプレートのビジュアライゼーション（cfn-diagram）

cfn-diagramを使用して、CloudFormation/SAM/CDKテンプレートを様々な形式の図に変換できます。

インストール

npm install -g @mhlabs/cfn-diagram

基本的な使い方

# インタラクティブなHTML図を生成
cfn-dia html -t examples/web-application-stack.yaml -o examples/output

# Mermaid形式でMarkdownに埋め込み可能な図を生成
cfn-dia mermaid -t examples/serverless-api-sam.yaml -o examples/output.md

# Draw.io形式で編集可能な図を生成
cfn-dia draw.io -t examples/container-microservices-ecs.yaml

詳細な使い方はusage-for-cfn-diagram.mdを参照してください。

サンプルテンプレート（examples/）

様々なAWSアーキテクチャパターンのCloudFormationテンプレートを提供しています。これらはcfn-diagramでの可視化テストに使用でき、実際にAWSにデプロイ可能です。

提供テンプレート一覧

テンプレート	説明	主なリソース
basic-cloudformation.yaml	基本的なWebアプリケーション構成	S3, Lambda, DynamoDB, API Gateway
web-application-stack.yaml	本格的な3層Webアプリケーション	ALB, Auto Scaling, RDS, ElastiCache, VPC
serverless-api-sam.yaml	イベント駆動型サーバーレスAPI	SAM, EventBridge, SQS, SNS, DynamoDB
data-pipeline-analytics.yaml	リアルタイムデータ分析パイプライン	Kinesis, Glue, Athena, S3, Lambda
container-microservices-ecs.yaml	コンテナベースのマイクロサービス	ECS Fargate, ALB, Service Discovery
static-website-hosting.yaml	静的Webサイトホスティング	S3, CloudFront, Route53, ACM, WAF

使用例

1. CloudWatchメトリクス推奨生成

# 開発環境でのテスト実行
npm run dev -- examples/web-application-stack.yaml

# プロダクション用：ビルドしてから実行
npm run build
aws-cloud-supporter examples/serverless-api-sam.yaml --output html --file metrics-report.html

# 特定リソースのメトリクス分析
aws-cloud-supporter examples/container-microservices-ecs.yaml --resource-types "AWS::ECS::Service,AWS::ElasticLoadBalancingV2::LoadBalancer" --verbose

2. CDKコード生成とデプロイ ✨NEW!

# CDK監視スタックを生成
npm run dev -- examples/serverless-api-sam.yaml --output cdk --cdk-output-dir ./monitoring-cdk

#生成されたCDKスタックをデプロイ
cd monitoring-cdk
npm install aws-cdk-lib@^2.80.0 constructs@^10.0.0
npx cdk init --language typescript
cp CloudWatchAlarmsStack.ts lib/
npx cdk deploy CloudWatchAlarmsStack

# SNS通知付きで本番環境向け監視システム構築
npm run dev -- examples/web-application-stack.yaml --output cdk --cdk-enable-sns --cdk-stack-name "ProductionMonitoringStack" --validate-cdk

3. テンプレートの可視化

# HTML形式で出力（ブラウザでインタラクティブに探索可能）
cfn-dia html -t examples/web-application-stack.yaml -o output/web-app
# ブラウザで output/web-app/index.html を開く

# Mermaid形式で出力（GitHubやドキュメントに埋め込み可能）
cfn-dia mermaid -t examples/serverless-api-sam.yaml > architecture.mmd

# Draw.io形式で出力（編集・カスタマイズ可能）
cfn-dia draw.io -t examples/container-microservices-ecs.yaml -o ecs.drawio

4. AWSへのデプロイ

# 基本的なWebアプリケーション
aws cloudformation create-stack \
  --stack-name my-basic-app \
  --template-body file://examples/basic-cloudformation.yaml \
  --parameters ParameterKey=Environment,ParameterValue=dev \
  --capabilities CAPABILITY_IAM

# SAMアプリケーション（SAM CLIが必要）
cd examples
sam build --template serverless-api-sam.yaml
sam deploy --guided

# コンテナアプリケーション
aws cloudformation create-stack \
  --stack-name my-container-app \
  --template-body file://examples/container-microservices-ecs.yaml \
  --capabilities CAPABILITY_IAM

出力例

HTML出力

インタラクティブなネットワーク図
ノードのドラッグ＆ドロップ
リソースタイプでのフィルタリング
詳細情報のツールチップ表示

Mermaid出力

flowchart TB;
    subgraph &nbsp;
    rootApiGateway[ApiGateway<br/>Serverless::Api]-->rootCreateOrderFunction[[CreateOrderFunction<br/>Serverless::Function]]
    rootCreateOrderFunction[[CreateOrderFunction<br/>Serverless::Function]]-->rootOrdersTable[(OrdersTable<br/>DynamoDB::Table)]
    end

テンプレートの特徴

本番環境対応: セキュリティ、可用性、スケーラビリティを考慮
ベストプラクティス: AWS Well-Architectedフレームワークに準拠
パラメータ化: 環境ごとの設定が容易
コメント付き: リソースの役割と設定理由を説明
検証済み: 文法エラーなし、デプロイ可能

開発・品質情報

コード品質基準

このプロジェクトはCLAUDE.mdで定義された厳格な品質基準に準拠しています：

✅ Zero Type Errors: TypeScript strict mode で型エラー0個
✅ No any types: 型安全性を重視、any型の使用禁止
✅ Build Success: 全ビルドが成功
✅ Test Driven Development: 475+個の自動テストで品質保証（CDKテスト80件追加）

開発コマンド

# 依存関係のインストール
npm install

# 開発モードでの実行
npm run dev template.yaml

# プロダクションビルド
npm run build

# テストスイート実行
npm test

# 型チェック
npm run typecheck

# テストカバレッジ
npm run test:coverage

ロードマップ

✅ CloudFormationからリソースを抽出してビジュアライズする（cfn-diagram統合）
✅ CloudFormationからリソースを抽出して、それぞれのリソースがサポートしているメトリクスを一覧化する
✅ CloudFormationからリソースを抽出して、それぞれのリソースがサポートしているメトリクスに対してアラームを張るためのCDKコードを生成する
CloudFormationからリソースを抽出して、それぞれのリソースがサポートしているメトリクスに対して張るアラームを選択できるようにする
CloudFormationからリソースを抽出して、コストを算出する
CloudFormationからリソースを抽出して、コストを最適化するための提案を行う
✅ CDKにも対応する（完全実装：8種類AWSリソース + SNS統合 + セキュリティ機能）
Terraformにも対応する

プロジェクト構成

aws_cloud_supporter/
├── README.md                      # このファイル
├── CLAUDE.md                      # Claude Codeの設定ファイル
├── package.json                   # Node.js依存関係とスクリプト
├── tsconfig.json                  # TypeScript設定（開発用）
├── tsconfig.build.json            # TypeScript設定（ビルド用）
├── usage-for-cfn-diagram.md       # cfn-diagramの詳細な使い方
├── visualization-tool-report.md   # ビジュアライゼーションツールの調査結果
├── src/                           # メインソースコード
│   ├── cli/                       # CLIエントリーポイント
│   ├── core/                      # 解析エンジン
│   ├── generators/                # メトリクス生成器 + CDK生成器
│   ├── config/                    # メトリクス定義
│   ├── types/                     # TypeScript型定義（CDK型含む）
│   ├── interfaces/                # インターフェース定義
│   ├── templates/                 # CDKコード生成テンプレート
│   ├── security/                  # セキュリティ機能（機密情報保護）
│   ├── validation/                # CDKコード品質検証
│   └── utils/                     # ユーティリティ
├── tests/                         # 自動テストスイート（475+テスト）
│   ├── unit/                      # 単体テスト（CDKテスト含む）
│   ├── integration/               # 統合テスト（CDK E2Eテスト含む）
│   ├── security/                  # セキュリティテスト
│   ├── e2e/                       # E2Eテスト
│   ├── fixtures/                  # テストデータ
│   └── helpers/                   # テストヘルパー
├── dist/                          # ビルド済みファイル
├── coverage/                      # テストカバレッジレポート
└── examples/                      # CloudFormationテンプレート集
    ├── basic-cloudformation.yaml  # 基本的なWebアプリケーション
    ├── web-application-stack.yaml # 3層Webアプリケーション
    ├── serverless-api-sam.yaml    # サーバーレスAPI（SAM）
    ├── data-pipeline-analytics.yaml # データ分析パイプライン
    ├── container-microservices-ecs.yaml # ECSマイクロサービス
    ├── static-website-hosting.yaml # 静的サイトホスティング
    └── output/                    # 生成された可視化ファイル（例）
        ├── index.html
        ├── data.js
        └── icons.js

エラーハンドリングシステム

概要

AWS Cloud Supporterは統一されたエラーハンドリングシステムを採用しており、型安全で一貫性のあるエラー処理を提供します。すべてのエラーはCloudSupporterErrorクラスを通じて処理され、サービス別のファクトリーメソッドで簡単に生成できます。

基本的な使用方法

1. シンプルなエラー生成

import { Errors } from './src/errors';

// Lambda関連のエラー
throw Errors.Lambda.metricsNotFound();

// DynamoDB関連のエラー
throw Errors.DynamoDB.metricsNotFound();

// 一般的なバリデーションエラー
throw Errors.Common.validationFailed('Invalid parameter value');

// ファイル操作エラー
throw Errors.Common.fileNotFound('/path/to/file.yaml');

2. 詳細情報付きエラー生成

import { ErrorBuilder, ErrorCatalog } from './src/errors';

// ビルダーパターンを使用した詳細なエラー
throw ErrorBuilder
  .fromCatalog(ErrorCatalog.validationFailed('CloudFormation template validation failed'))
  .withFilePath('/templates/web-app.yaml')
  .withLineNumber(42)
  .withDetails({
    resourceId: 'MyDatabase',
    resourceType: 'AWS::RDS::DBInstance',
    reason: 'Missing required property: DBInstanceClass'
  })
  .build();

3. エラーの判定と処理

import { CloudSupporterError, isFileError, isParseError } from './src/errors';

try {
  // 何らかの処理
} catch (error) {
  if (error instanceof CloudSupporterError) {
    console.log(`Error Code: ${error.code}`);
    console.log(`Error Type: ${error.type}`);
    console.log(`Message: ${error.message}`);

    // 特定のエラータイプの判定
    if (isFileError(error)) {
      console.log('ファイル関連のエラーです');
    } else if (isParseError(error)) {
      console.log('パース関連のエラーです');
    }

    // 詳細情報の取得
    if (error.details) {
      console.log('Error Details:', error.details);
    }
  }
}

利用可能なエラーファクトリー

AWS サービス別エラー

// Lambda関連
Errors.Lambda.metricsNotFound()
Errors.Lambda.invalidRuntime(runtime)
Errors.Lambda.timeoutTooHigh(timeout)

// DynamoDB関連
Errors.DynamoDB.metricsNotFound()
Errors.DynamoDB.invalidBillingMode(mode)
Errors.DynamoDB.throughputExceeded(requested, limit)

// RDS関連
Errors.RDS.metricsNotFound()

// ECS関連
Errors.ECS.metricsNotFound()
Errors.ECS.onlyFargateSupported()

// ALB関連
Errors.ALB.metricsNotFound()
Errors.ALB.onlyApplicationLoadBalancerSupported()

// API Gateway関連
Errors.APIGateway.metricsNotFound()

共通エラー

// ファイル操作
Errors.Common.fileNotFound(filePath)
Errors.Common.fileReadError(filePath, reason)
Errors.Common.fileWriteError(filePath, reason)

// パース/バリデーション
Errors.Common.parseError(message, filePath, lineNumber, details)
Errors.Common.validationFailed(message, details)

// 出力処理
Errors.Common.outputError(message, details)

// リソース関連
Errors.Common.resourceUnsupportedType(resourceType, supportedTypes)

エラーハンドリングのベストプラクティス

1. 適切なエラータイプの選択

// ❌ 間違い: 汎用的すぎるエラー
throw new Error('Something went wrong');

// ✅ 正しい: 具体的で分類されたエラー
throw Errors.Lambda.invalidRuntime('python2.7');

2. 詳細情報の提供

// ❌ 間違い: 情報不足
throw Errors.Common.validationFailed('Invalid input');

// ✅ 正しい: 詳細な情報を含む
throw Errors.Common.validationFailed('Invalid CloudFormation template', {
  templatePath: '/path/to/template.yaml',
  resourceId: 'MyResource',
  missingProperty: 'Type'
});

3. 一貫性のあるエラーメッセージ

// 各サービスのメトリクスが見つからない場合
throw Errors.Lambda.metricsNotFound();     // "Lambda metrics configuration not found"
throw Errors.DynamoDB.metricsNotFound();   // "DynamoDB metrics configuration not found"
throw Errors.RDS.metricsNotFound();        // "RDS metrics configuration not found"

開発者向け情報

カスタムエラーの作成

新しいサービスやエラータイプを追加する場合：

エラーコードの追加 (src/errors/error.types.ts)

export const ERROR_CODES = {
  // 既存のコード...
  NEW_SERVICE_ERROR: 'NEW_SERVICE_ERROR'
} as const;

ファクトリーの作成 (src/errors/factories/newservice.ts)

export const NewServiceErrors = {
  metricsNotFound: (): CloudSupporterError =>
    ErrorBuilder.fromCatalog(ErrorCatalog.metricsNotFound('NewService'))
      .withDetails({ resourceType: 'AWS::NewService::Resource' })
      .build()
};

統合の追加 (src/errors/index.ts)

export const Errors = {
  // 既存のサービス...
  NewService: NewServiceErrors
} as const;

テストでのエラー検証

import { Errors, CloudSupporterError, ERROR_CODES, ErrorType } from '../src/errors';

describe('Error Handling', () => {
  it('should throw appropriate Lambda error', () => {
    expect(() => {
      throw Errors.Lambda.metricsNotFound();
    }).toThrow(CloudSupporterError);

    try {
      throw Errors.Lambda.metricsNotFound();
    } catch (error) {
      expect(error.code).toBe(ERROR_CODES.METRICS_NOT_FOUND);
      expect(error.type).toBe(ErrorType.RESOURCE_ERROR);
      expect(error.message).toContain('Lambda metrics configuration not found');
    }
  });
});

エラーコード一覧

コード	タイプ	説明
`METRICS_NOT_FOUND`	RESOURCE_ERROR	メトリクス設定が見つからない
`RESOURCE_UNSUPPORTED_TYPE`	RESOURCE_ERROR	サポートされていないリソースタイプ
`VALIDATION_FAILED`	VALIDATION_ERROR	バリデーション失敗
`FILE_NOT_FOUND`	FILE_ERROR	ファイルが見つからない
`FILE_READ_ERROR`	FILE_ERROR	ファイル読み込みエラー
`FILE_WRITE_ERROR`	FILE_ERROR	ファイル書き込みエラー
`PARSE_ERROR`	PARSE_ERROR	パースエラー
`OUTPUT_ERROR`	OUTPUT_ERROR	出力エラー

このエラーハンドリングシステムにより、開発者は一貫性があり、デバッグしやすいエラー処理を実装できます。

Name		Name	Last commit message	Last commit date
Latest commit History 111 Commits
.github/workflows		.github/workflows
.serena		.serena
examples		examples
src		src
tests		tests
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
README.md		README.md
design.md		design.md
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
knip.json		knip.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
usage-for-cfn-diagram.md		usage-for-cfn-diagram.md

lapinChiro/aws_cloud_supporter

Folders and files

Latest commit

History

Repository files navigation

aws_cloud_supporter

コンセプト

現在の機能

1. CloudWatchメトリクス推奨生成

2. CDKコード自動生成 ✨NEW!

サポートリソース

基本的な使い方

メトリクス分析（既存機能）

CDKコード生成 ✨NEW!

出力例

3. CloudFormationテンプレートのビジュアライゼーション（cfn-diagram）

インストール

基本的な使い方

サンプルテンプレート（examples/）

提供テンプレート一覧

使用例

1. CloudWatchメトリクス推奨生成

2. CDKコード生成とデプロイ ✨NEW!

3. テンプレートの可視化

4. AWSへのデプロイ

出力例

HTML出力

Mermaid出力

テンプレートの特徴

開発・品質情報

コード品質基準

開発コマンド

ロードマップ

プロジェクト構成

エラーハンドリングシステム

概要

基本的な使用方法

1. シンプルなエラー生成

2. 詳細情報付きエラー生成

3. エラーの判定と処理

利用可能なエラーファクトリー

AWS サービス別エラー

共通エラー

エラーハンドリングのベストプラクティス

1. 適切なエラータイプの選択

2. 詳細情報の提供

3. 一貫性のあるエラーメッセージ

開発者向け情報

カスタムエラーの作成

テストでのエラー検証

エラーコード一覧

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages