クラウドエージェント

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

エージェント設定

AWS Aurora and RDSの設定方法です。

AWS Aurora and RDSの設定

config.yaml

input:
  csp: "aws" # クラウドサービスのプロバイダーを入力します。
  namespace: "rds"
  region: "ap-northeast-1" # インスタンスが位置するリージョンを設定します。
  # assume_role_arn: "arn:aws:iam::123456789012:role/WhatapReadOnly" # （任意）すべてのAWS呼び出しに使用するデフォルトroleです。省略するとEC2 Instance Profileのroleを使用します。
  instances: # 設定したインスタンスは常に収集します。クラスター内のインスタンスをここに指定すると、オートスケールに関係なく収集されます。
    - name: "mysql-rds" # インスタンス名
      slow_query: true # スロークエリーページを使用するには、trueに設定します。MySQL、MariaDB、PostgreSQL（Aurora含む）インスタンスで対応しています。
  slow_query: false # クラスターから自動検出したインスタンスのスロークエリー収集有無です。
  clusters:
    autoscale:
      enabled: false # オートスケールが有効な場合、スケーリングされたインスタンスを収集対象に追加または削除します。
      interval: 60 # 指定したクラスターのオートスケール確認間隔です。（単位: 秒）
    names:
      - "database-cluster-name"
  # metrics_interval: 1m # （任意）メトリクス収集間隔です。1m、5m、15m、1hから選択し、単位を必ず付けます。（デフォルト値: 1m）
  metrics: # 収集するメトリクスを入力します。
    - "CPUUtilization"
    - "FreeStorageSpace"
    - "FreeableMemory"
    - "ReadLatency"
    - "WriteLatency"
    - "ReadIOPS"
    - "WriteIOPS"
    - "NetworkReceiveThroughput"
    - "NetworkTransmitThroughput"
    - "FreeLocalStorage"
  logs:
    enabled: false # ログ収集の有無を設定します。true/falseで設定できます。
    groups: # 収集するAWSロググループを入力します。
      - "/aws/rds/cluster/database-cluster-name/error"
      - "/aws/lambda/MyLambda"
  events:
    enabled: false # RDSイベント収集を有効にするにはtrueを入力します。

output: # 収集したメトリクスデータを受信するWhaTap情報を入力します。
  license: "abcdefg-higjgkgjk-zxcvnbnbmc"
  host: "127.0.0.1"

フィールド	説明
csp	クラウドサービスの提供者としてaws(Amazon Web Services)を意味
namespace	収集対象サービスのネームスペース - 固定値: Aurora and RDSの設定時、rdsを入力
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	RDSインスタンス名 - 例 mysql-rds
instances[].slow_query	該当インスタンスのスロークエリーを収集するかどうか、MySQL、MariaDB、PostgreSQL、Aurora MySQL、Aurora PostgreSQLインスタンスで対応 - true: 収集 - false: 非収集 - スロークエリーログをCloudWatch Logsにエクスポートしている場合のみ収集（MySQL系はslowquery、PostgreSQL系はpostgresqlログ）
instances[].oname	（任意）WhaTap画面に表示するインスタンス名（oname） - 省略するとエンドポイントに基づいて自動生成
slow_query	クラスターから自動検出したインスタンス（clusters）のスロークエリー収集有無 - デフォルト値: false - クラスター所属のインスタンスはinstances[].slow_queryではなくこの値に従う
clusters	RDSクラスター関連設定
clusters.autoscale.enabled	クラスターオートスケール収集有無 - true: 自動的にインスタンスを追加/削除して収集 - false: instancesに直接入力したインスタンスのみ収集対象に含める
clusters.autoscale.interval	オートスケール有無を感知する周期(単位:秒) - デフォルト値: 300
clusters.names	オートスケール有無をチェックするクラスター名の一覧
metrics	収集するメトリック項目のリスト - 例 CPUUtilization、FreeStorageSpaceなど - 参考 Amazon RDSに対するAmazon CloudWatch指標の公式文書へのショートカット
metrics_interval	（任意）メトリクス収集間隔 - 許容値: 1m、5m、15m、1h（デフォルト値: 1m） - 単位を必ず付ける必要がある。許容値以外の値を入力するとエージェントが起動しない
logs.enabled	CloudWatch Logsのログ収集有無
logs.groups	収集するCloudWatch Logsロググループの一覧 - 参考 ログ収集設定
events.enabled	（任意）RDSイベント収集有無 - デフォルト値: false - rds:DescribeEvents権限が必要
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: "rds"
  region: "ap-northeast-2"
  assume_role_arn: "arn:aws:iam::123456789012:role/WhatapReadOnly"
  clusters:
    names:
      - "database-cluster-name"

roleの優先順位

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

roleが適用される範囲

インスタンス探索、メトリクス、クラスタースペック、スロークエリー、ログ（logs.groups）、RDSイベントの収集は、すべて上記の優先順位で決まったroleでAWS APIを呼び出します。

• インスタンス探索、メトリクス、クラスタースペック、スロークエリーは、インスタンスが属するaccount_configs項目のroleを使用し、項目にroleがなければinput.assume_role_arnを使用します。

• logs.groupsとRDSイベントは特定のクラスターに紐付かないため、常にエージェントのデフォルトrole（input.assume_role_arn、なければEC2 role）を使用します。account_configsのroleを設定するだけでは、logs.groupsの照会roleは変わりません。

• input.assume_role_arnを使用する場合、EC2 Instance Profileにはsts:AssumeRole権限のみがあれば十分です。収集に必要な権限は指定したroleに付与します。詳しくは、下記の権限設定のクロスアカウントIAM権限を参照してください。

• AssumeRoleで取得した一時credentialは有効期限まで再利用するため、リクエストのたびにSTSを呼び出すことはありません。

注意

• input.assume_role_arnはcsp: "aws"でのみ使用できます。他のcspに値を設定すると、エージェント起動時に設定エラーが発生します。

• ARN形式を検証します。arn:aws:iam::<12桁のアカウントID>:role/<名前>形式でない場合、設定エラーが発生します。

• この設定はDBXCエージェント0.7.0以降でサポートしています。

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

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

項目	内容
対応対象	AWS RDS（Aurora、スタンドアロン）、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: "rds"
  region: "ap-northeast-2"
  clusters:
    autoscale:
      enabled: true
      interval: 300
    account_configs:
      # ローカルアカウント（assume_role_arnを省略するとinput.assume_role_arn、それもなければEC2 roleを使用）
      - clusters: ["local-aurora-cluster"]
        instances: ["standalone-mysql-1"]

      # 別のアカウント A
      - assume_role_arn: "arn:aws:iam::111111111111:role/DBXCRole"
        clusters: ["partner-cluster-1", "partner-cluster-2"]

      # 別のアカウント B
      - assume_role_arn: "arn:aws:iam::222222222222:role/QARole"
        clusters: ["qa-cluster"]
        instances: ["qa-standalone-pg"]
  metrics:
    - "CPUUtilization"
    - "FreeStorageSpace"
    - "FreeableMemory"
    - "ReadLatency"
    - "WriteLatency"

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	△	Aurora/DocumentDBクラスター名。所属インスタンスを自動検出
instances	△	クラスターに属さないスタンドアロンRDSインスタンス名

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

ノート

clustersとinstancesの違い

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

設定例1. 単一アカウント + スタンドアロンインスタンス

clusters:
  autoscale:
    enabled: true
    interval: 300
  account_configs:
    - clusters: ["prod-aurora"]
      instances: ["legacy-mysql-standalone"]

設定例2. 3つのアカウント（自アカウント + パートナー + QA）

clusters:
  autoscale:
    enabled: true
    interval: 300
  account_configs:
    - clusters: ["prod-cluster", "staging-cluster"]

    - assume_role_arn: "arn:aws:iam::111111111111:role/DBXCRole"
      clusters: ["partner-prod", "partner-dev"]

    - assume_role_arn: "arn:aws:iam::222222222222:role/QADBXCRole"
      clusters: ["qa-cluster"]
      instances: ["qa-standalone-pg"]

注意

• namesとaccount_configsは同時に使用できません。エージェント起動時にバリデーションエラーが発生します。

• ARN形式を厳密に検証します。arn:aws:iam::<12桁の数字>:role/<名前>。コロン2つ(::)を省略しないよう注意してください。

• 各account_configs項目には、clustersとinstancesのうち少なくとも1つが必要です。

• autoscale.enabled: trueでないとクラスターディスカバリーが動作しません。

権限設定

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

AWS Aurora and RDS権限

クラウドエージェントは、次の機能を実行するためにAWS APIを呼び出します。

• AWS Aurora and RDSインスタンスとクラスター情報を照会して監視対象を確認
• CloudWatchメトリック収集

IAMインラインポリシー

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

• このポリシーはAuroraとRDSサービスの両方に適用されます。
• Resource項目は、すべてのAuroraとRDSリソースを対象に指定されており、セキュリティポリシーによって必要な場合、リソースARNを制限できます。
• エージェントは照会(Read-only) APIのみ使用します。 データベースに影響を与える権限は含まれません。
• rds:DescribeEventsはRDSイベント収集（events.enabled: true）に、logs:権限はスロークエリーとログ収集に使用します。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RDSPermissions",
      "Effect": "Allow",
      "Action": [
        "rds:DescribeDBInstances",
        "rds:DescribeDBClusters",
        "rds:DescribeDBClusterParameters",
        "rds:DescribeOptionGroups",
        "rds:DescribeEvents"
      ],
      "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/rds/*"
      ]
    }
  ]
}

クロスアカウント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料金ページを参照してください。