클라우드 에이전트 설정

AWS 환경에서 WhaTap 클라우드 에이전트를 설정하는 방법을 안내합니다. 주요 설정 항목, 필드 설명, 권한 구성과 실행 명령을 확인할 수 있습니다.

에이전트 설정

AWS DocumentDB 에이전트 설정 방법입니다.

AWS DocumentDB 에이전트

config.yaml
input:
  csp: "aws" # 클라우드 서비스 제공자를 입력합니다.
  namespace: "docdb"
  region: "ap-northeast-2"
  # assume_role_arn: "arn:aws:iam::123456789012:role/WhatapReadOnly" # (선택) 모든 AWS 호출에 쓸 기본 role입니다. 생략하면 EC2 Instance Profile의 role을 씁니다.
  instances: # 명시한 인스턴스는 항상 수집합니다. 클러스터 내의 인스턴스를 이 속성에 명시하면, 오토스케일 여부와 관계없이 항상 수집합니다.
    - name: "docdb-instance-name"
  clusters:
    autoscale:
      enabled: false # 오토스케일이 활성화되면, 오토스케일된 인스턴스들을 수집 대상에서 추가하거나 삭제합니다.
      interval: 60 # 명시한 클러스터들의 오토스케일 체크 주기입니다. (단위: 초)
    names:
      - "docdb-cluster-name"
  # metrics_interval: 1m # (선택) 메트릭 수집 주기입니다. 1m, 5m, 15m, 1h 중 선택하며 단위를 반드시 붙입니다. (기본값: 1m)
  metrics: # 수집할 메트릭을 입력합니다.
    - "CPUUtilization"
    - "FreeableMemory"
    - "ReadLatency"   
    - "WriteLatency"  
    - "DatabaseConnections"
  logs:
    enabled: false # 로그 수집을 활성화/비활성화 할 수 있습니다. 로그 수집을 활성화하려면 true를 입력합니다.
    groups: # 원하는 AWS log group을 추가합니다.
      - "/aws/rds/cluster/docdb-cluster-name/error"
      - "/aws/lambda/MyLambda"

output: # 수집한 메트릭 데이터를 받는 WhaTap 정보를 입력합니다.
  license: "4544ee05-wfwefwefb205-2987709519af"
  host: "127.0.0.1"

Field	Description
`csp`	클라우드 서비스 제공자로 `aws` (Amazon Web Services)를 의미
`namespace`	수집 대상 서비스의 네임스페이스 - AWS DocumentDB 설정 시 고정값으로 `docdb` 입력
`region`	AWS 리전 코드 - 예: `ap-northeast-2` (서울 리전)
`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`	(선택) 와탭 화면에 표시할 인스턴스 이름(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은 최소 권한으로 두고, 와탭 수집용 읽기 권한은 전용 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를 모니터링할 수 있습니다. 멀티 계정(환경별 분리, 파트너 계정 등)을 사용하는 경우, 계정마다 에이전트를 설치할 필요 없이 하나의 에이전트에서 STS AssumeRole로 다른 계정의 리소스를 조회합니다.

항목	내용
지원 대상	AWS DocumentDB
인증 방식	EC2 Instance Profile(또는 `input.assume_role_arn`) + STS AssumeRole

설정 방식 선택

클러스터 설정에는 두 가지 방식이 있으며, 동시에 사용할 수 없습니다.

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 필드

Field	Required	Description
`assume_role_arn`	X	STS AssumeRole ARN. 생략하면 에이전트 기본 role(`input.assume_role_arn`, 없으면 EC2 role) 사용
`clusters`	△	DocumentDB 클러스터 이름. 소속 인스턴스를 자동으로 찾아줌
`instances`	△	클러스터에 속하지 않는 standalone 인스턴스 이름

△: clusters와 instances 중 하나 이상을 입력해야 합니다.

노트

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는 다음 항목을 확인한 뒤 결과를 출력하고 종료합니다. 하나라도 실패하면 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 요금​