クラウドエージェント

AWS環境でWhaTapクラウドエージェントを設定する方法を案内します。主要な設定項目、フィールドの説明、権限構成、実行コマンドを確認できます。

エージェント設定

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

AWS DocumentDBエージェント

config.yaml
input:
  csp: "aws" # クラウドサービスのプロバイダーを入力します。
  namespace: "docdb"
  region: "ap-northeast-1" # インスタンスが位置するリージョンを設定します。
  # assume_role_arn: "arn:aws:iam::123456789012:role/WhatapReadOnly" # （任意）すべてのAWS呼び出しに使用するデフォルトroleです。省略するとEC2 Instance Profileのroleを使用します。
  instances: # 指定したインスタンスは常に収集されます。クラスター内のインスタンスをここに指定すると、オートスケールに関係なく収集されます。
    - name: "docdb-instance-name" # インスタンス名
      slow_query: true # スロークエリページを利用する場合は true に設定してください。
  clusters:
    autoscale:
      enabled: false # オートスケールが有効な場合、スケーリングされたインスタンスを収集対象に追加または削除します。
      interval: 60 # 指定したクラスターのオートスケール確認間隔です。（単位: 秒）
    names:
      - "docdb-cluster-name"
  # metrics_interval: 1m # （任意）メトリクス収集間隔です。1m、5m、15m、1hから選択し、単位を必ず付けます。（デフォルト値: 1m）
  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` (東京リージョン)
`assume_role_arn`	（任意）エージェントがAWS APIを呼び出す際に使用するデフォルトのIAM Role ARN - 省略するとEC2 Instance Profileのroleを使用 - 形式: `arn:aws:iam::<12桁のアカウントID>:role/<名前>` - 参考エージェントのデフォルトrole
`instances`	常に収集するインスタンスの一覧で、オートスケール有無に関係なく、指定されたインスタンスは無条件に収集する
`instances[].name`	DocumentDBインスタンス名 - 例 `docdb-2025-04-08-01-21-05`
`instances[].oname`	（任意）WhaTap画面に表示するインスタンス名（oname） - 省略するとエンドポイントに基づいて自動生成
`clusters`	DocumentDBクラスター関連設定
`clusters.autoscale.enabled`	クラスターオートスケール収集有無 - `true`: 自動的にインスタンスを追加/削除して収集 - `false`: `instances`に直接入力したインスタンスのみ収集対象に含める
`clusters.autoscale.interval`	オートスケール有無を感知する周期(単位:秒) - デフォルト値: `300`
`clusters.names`	オートスケール有無をチェックするクラスター名の一覧
`metrics`	収集するメトリック項目のリスト - 例 `CPUUtilization`、`FreeableMemory`など - 参考 Amazon DocumentDB指標公式文書
`metrics_interval`	（任意）メトリクス収集間隔 - 許容値: `1m`、`5m`、`15m`、`1h`（デフォルト値: `1m`） - 単位を必ず付ける必要がある。許容値以外の値を入力するとエージェントが起動しない
`logs.enabled`	CloudWatch Logsのログ収集有無
`logs.groups`	収集するCloudWatch Logsロググループの一覧
`output.license`	収集されたデータを転送するWhaTapのライセンスキー
`output.host`	収集データを転送するWhaTapサーバーのホストアドレス(IP)

エージェントのデフォルトrole（`input.assume_role_arn`）

input.assume_role_arnを設定すると、エージェントはEC2 Instance Profileのroleの代わりに指定したroleでAWS APIを呼び出します。同一アカウントのみをモニタリングする場合でも、EC2 roleは最小権限にとどめ、WhaTap収集用の読み取り権限は専用roleにまとめて管理できます。clusters.names、clusters.account_configsのどちらの方式とも併用できます。

config.yaml
input:
  csp: "aws"
  namespace: "docdb"
  region: "ap-northeast-2"
  assume_role_arn: "arn:aws:iam::123456789012:role/WhatapReadOnly"
  clusters:
    names:
      - "docdb-cluster-name"

roleの優先順位

clusters.account_configs[].assume_role_arn > input.assume_role_arn > EC2 Instance Profileのデフォルトcredential

インスタンス探索とメトリクスは、インスタンスが属するaccount_configs項目のroleを使用し、項目にroleがなければinput.assume_role_arnを使用します。
logs.groupsは特定のクラスターに紐付かないため、常にエージェントのデフォルトrole（input.assume_role_arn、なければEC2 role）を使用します。
input.assume_role_arnを使用する場合、EC2 Instance Profileにはsts:AssumeRole権限のみがあれば十分です。収集に必要な権限は指定したroleに付与します。

注意

input.assume_role_arnはcsp: "aws"でのみ使用できます。他のcspに値を設定した場合や、ARN形式（arn:aws:iam::<12桁のアカウントID>:role/<名前>）が誤っている場合は、エージェント起動時に設定エラーが発生します。
この設定はDBXCエージェント0.7.0以降でサポートしています。

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

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

項目	内容
対応対象	AWS DocumentDB
認証方式	EC2 Instance Profile（または`input.assume_role_arn`） + STS AssumeRole

設定方式の選択

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

names: 単一アカウント専用（エージェントのデフォルトroleで自アカウントのみ照会、input.assume_role_arnがなければエージェントがインストールされた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。省略するとエージェントのデフォルトrole（`input.assume_role_arn`、なければEC2 role）を使用
`clusters`	△	DocumentDBクラスター名。所属インスタンスを自動検出
`instances`	△	クラスターに属さないスタンドアロンインスタンス名

△: clustersとinstancesのうち、少なくとも1つを入力する必要があります。

ノート

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権限

input.assume_role_arnまたはaccount_configs[].assume_role_arnでroleを指定するには、追加のIAM権限が必要です。

エージェントEC2 Instance Profile

エージェントが実行されるEC2に、指定したRoleをAssumeできる権限を付与します。input.assume_role_arnでデフォルトroleを指定した場合、EC2 Instance Profileにはこの権限のみがあれば十分で、上記のIAMインラインポリシーは指定したroleに付与します。

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

対象Role（Cross-Account Roleまたはデフォルトrole）

対象アカウントでエージェントアカウントからのアクセスを許可するRoleを作成します。同一アカウントのroleをinput.assume_role_arnで指定する場合も、同じ方法でTrust Relationshipと権限を設定します。

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

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

Permission Policy: RDS/CloudWatch/CloudWatch Logs照会権限

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

DocumentDBをモニタリングする場合は、rds:権限の代わりにdocdb:DescribeDBInstances、docdb:DescribeDBClustersを付与します。

注意

0.7.0からスロークエリーもaccount_configsのroleで照会します

0.6.0以前では、account_configs[].assume_role_arnを設定しても、スロークエリーとlogs.groupsはEC2 roleで照会していました。0.7.0からはスロークエリーを該当アカウントのroleで照会するため、そのroleにlogs:FilterLogEvents権限が必要です。権限がない場合、スロークエリーは収集されません。

logs.groupsはエージェントのデフォルトrole（input.assume_role_arn、なければEC2 role）で照会するため、そのroleにlogs:FilterLogEvents権限を付与します。

設定検証

エージェントを開始する前に、validateコマンドで設定ファイルとAWS権限を事前に確認できます。

./dbxc-ctl validate -c config.yaml

validateは次の項目を確認した後、結果を出力して終了します。1つでも失敗すると、ERRORとともに確認すべき権限を案内します。

設定ファイルの形式とフィールド値（assume_role_arnのARN形式、namesとaccount_configsの同時使用有無など）
input.assume_role_arnとaccount_configs[].assume_role_arnに指定したroleのAssumeRole可否
アカウント別のインスタンス、クラスター照会権限
logs.enabled: trueの場合、logs.groupsの各ロググループに対するlogs:FilterLogEvents権限（エージェントのデフォルトrole基準、RDS）

料金案内

注意

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

AWS料金

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

本エージェントは、基本的に1分周期でGetMetricData APIを呼び出ししてメトリックを収集し、呼び出し頻度と収集対象によって料金が増加することがあるので注意が必要です。呼び出し頻度を減らすには、metrics_intervalを5m、15m、1hのいずれかに延ばすか、収集するメトリクス数を減らします。

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

エージェント設定​

AWS DocumentDBエージェント​

エージェントのデフォルトrole（input.assume_role_arn）​

設定方式の選択​

account_configs 設定​

権限設定​

AWS DocumentDB権限​

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

エージェントEC2 Instance Profile​

対象Role（Cross-Account Roleまたはデフォルトrole）​

設定検証​

料金案内​

AWS料金​