クラウドエージェント

この文書は、AWS環境でWhaTapクラウドエージェントを設定するためのガイドです。主要設定項目、フィールドの説明、権限構成、実行コマンドまで含めて、運用環境にすぐに適用できるように構成されています。

エージェント設定

AWS DocumentDBエージェントの設定方法です。

AWS DocumentDBエージェント

config.yaml
input:
  csp: "aws" # クラウドサービスのプロバイダーを入力します。
  namespace: "docdb"
  region: "ap-northeast-1" # インスタンスが位置するリージョンを設定します。
  instances: # 指定したインスタンスは常に収集されます。クラスター内のインスタンスをここに指定すると、オートスケールに関係なく収集されます。
    - name: "docdb-instance-name" # インスタンス名
      slow_query: true # スロークエリページを利用する場合は true に設定してください。
  clusters:
    autoscale:
      enabled: false # オートスケールが有効な場合、スケーリングされたインスタンスを収集対象に追加または削除します。
      interval: 60 # 指定したクラスターのオートスケール確認間隔です。（単位: 秒）
    names:
      - "docdb-cluster-name"
  metrics: # 収集するメトリクスを入力します。
    - "CPUUtilization"
    - "FreeStorageSpace"
    - "FreeableMemory"
    - "ReadLatency"
    - "WriteLatency"
  logs:
    enabled: false # ログ収集の有無を設定します。true/falseで設定できます。
    groups: # 収集するAWSロググループを入力します。
      - "/aws/rds/cluster/docdb-cluster-name/error"
      - "/aws/lambda/MyLambda"
output: # 収集したメトリックデータを受信するWhaTap情報を入力します。
  license: "abcdefg-higjgkgjk-zxcvnbnbmc"
  host: "127.0.0.1"

フィールド	説明
`csp`	クラウドサービスの提供者として`aws`(Amazon Web Services)を意味
`namespace`	収集対象サービスのネームスペース - AWS DocumentDB設定時固定値で`docdb`入力
`region`	AWSリージョンコード - 例:`ap-northeast-1` (東京リージョン)
`instances`	常に収集するインスタンスの一覧で、オートスケール有無に関係なく、指定されたインスタンスは無条件に収集する
`instances[].name`	DocumentDBインスタンス名 - 例 `docdb-2025-04-08-01-21-05`
`clusters`	DocumentDBクラスター関連設定
`clusters.autoscale.enabled`	クラスターオートスケール収集有無 - `true`: 自動的にインスタンスを追加/削除して収集 - `false`: `instances`に直接入力したインスタンスのみ収集対象に含める
`clusters.autoscale.interval`	オートスケール有無を感知する周期(単位:秒)
`clusters.names`	オートスケール有無をチェックするクラスター名の一覧
`metrics`	収集するメトリック項目のリスト - 例 `CPUUtilization`、`FreeableMemory`など - 参考 Amazon DocumentDB指標公式文書
`output.license`	収集されたデータを転送するWhaTapのライセンスキー
`output.host`	収集データを転送するWhaTapサーバーのホストアドレス(IP)

クロスアカウントモニタリング（マルチAWSアカウント）

単一のクラウドエージェントで複数のAWSアカウントのDocumentDBをモニタリングできます。マルチアカウント（環境別分離、パートナーアカウントなど）を使用する場合、アカウントごとにエージェントをインストールする必要はなく、1つのエージェントからSTS AssumeRoleで他のアカウントのリソースを照会します。

項目	内容
対応対象	AWS DocumentDB
認証方式	EC2 Instance Profile + STS AssumeRole

設定方式の選択

クラスター設定には2つの方式があり、同時に使用することはできません。

names: 単一アカウント専用（エージェントがインストールされたEC2のIAM Roleで自アカウントのみ照会）
account_configs: クロスアカウント対応（STS AssumeRoleを通じて複数アカウントを照会）

`account_configs` 設定

config.yaml
input:
  csp: "aws"
  namespace: "docdb"
  region: "ap-northeast-2"
  clusters:
    autoscale:
      enabled: true
      interval: 300
    account_configs:
      # ローカルアカウント
      - clusters: ["local-docdb-cluster"]

      # 別のアカウント
      - assume_role_arn: "arn:aws:iam::111111111111:role/DBXCRole"
        clusters: ["partner-docdb-cluster"]
  metrics:
    - "CPUUtilization"
    - "FreeableMemory"
    - "ReadLatency"
    - "WriteLatency"
    - "DatabaseConnections"

output:
  license: "your-license-key"
  host: "127.0.0.1"

表 | account_configs フィールド

フィールド	必須	説明
`assume_role_arn`	X	STS AssumeRole ARN。省略するとローカルアカウントを使用
`clusters`	O	DocumentDBクラスター名。所属インスタンスを自動検出
`instances`	X	クラスターに属さないスタンドアロンインスタンス名

ノート

clustersとinstancesの違い

	`clusters`	`instances`
対象	DocumentDBクラスター	クラスターなしで単独運用されるインスタンス
動作	クラスター名で所属インスタンスを自動ディスカバリー	インスタンス名を直接指定
オートスケール	インスタンスの追加/削除時に自動反映	該当なし

権限設定

エージェントが正常に動作するには、サービスごとに必要な権限を設定する必要があります。

AWS DocumentDB権限

クラウドエージェントはDocumentDBに対して、次の機能を実行します。

DocumentDBインスタンスとクラスター情報の照会
CloudWatchメトリック収集

DocumentDB用IAMインラインポリシー

JSONポリシーをIAMユーザーまたは役割にインラインポリシーで追加します。 EC2でエージェントを実行する場合、当該EC2インスタンスに接続されたIAMの役割に付与します。

Resource項目は、すべてのDocumentDBリソースを対象に指定されており、セキュリティポリシーによって必要な場合、リソースARNを制限できます。
エージェントは照会(Read-only) APIのみ使用します。データベースに影響を与える権限は含まれません。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DocDBPermissions",
      "Effect": "Allow",
      "Action": [
        "docdb:DescribeDBInstances",
        "docdb:DescribeDBClusters"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchMetricsPermissions",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricData",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:ListMetrics"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogsPermissions",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "logs:FilterLogEvents",
        "logs:GetLogEvents"
      ],
      "Resource": [
        "arn:aws:logs:*:*:log-group:/aws/docdb/*"
      ]
    }
  ]
}

クロスアカウントIAM権限

account_configsを使用してクロスアカウントモニタリングを設定するには、追加のIAM権限が必要です。

エージェントEC2 Instance Profile

エージェントが実行されるEC2に、対象アカウントのRoleをAssumeできる権限を付与します。

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": [
        "arn:aws:iam::111111111111:role/DBXCRole",
        "arn:aws:iam::222222222222:role/QARole"
      ]
    }
  ]
}

対象アカウントのCross-Account Role

対象アカウントでエージェントアカウントからのアクセスを許可するRoleを作成します。

Trust Relationship: エージェントアカウントを許可

{
  "Principal": {
    "AWS": "arn:aws:iam::<エージェントアカウントID>:role/DBXC-EC2-Instance-Role"
  },
  "Action": "sts:AssumeRole"
}

Permission Policy: RDS/CloudWatch照会権限

{
  "Effect": "Allow",
  "Action": [
    "rds:DescribeDBInstances",
    "rds:DescribeDBClusters",
    "cloudwatch:GetMetricData",
    "logs:FilterLogEvents"
  ],
  "Resource": "*"
}

料金案内

注意

クラウドモニタリングエージェントは無料ですが、クラウドサービスの使用によっては別途料金が発生することがありますので、確認が必要です。

AWS料金

クラウドモニタリングエージェントは別途のSaaS料金なしで提供され、エージェントのインストールだけでモニタリング機能を使用できます。ただ、AWS CloudWatchなどクラウドサービスのAPIを通じてメトリックを収集するため、CloudWatch使用量によって別途料金がかかる場合があります。

本エージェントは、基本的に1分周期でGetMetricData APIを呼び出ししてメトリックを収集し、呼び出し頻度と収集対象によって料金が増加することがあるので注意が必要です。

詳しい料金ポリシーはAWS公式文書のAmazon CloudWatch料金ページを参照してください。

注意

namesとaccount_configsは同時に使用できません。エージェント起動時にバリデーションエラーが発生します。
ARN形式を厳密に検証します。arn:aws:iam::<12桁の数字>:role/<名前> — コロン2つ(::)を省略しないよう注意してください。
各account_configには最低1つのclusterが必要です。
autoscale.enabled: trueでないとクラスターディスカバリーが動作しません。

エージェント設定​

AWS DocumentDBエージェント​

設定方式の選択​

account_configs 設定​

権限設定​

AWS DocumentDB権限​

DocumentDB用IAMインラインポリシー​

エージェントEC2 Instance Profile​

対象アカウントのCross-Account Role​

料金案内​

AWS料金​