클라우드 에이전트 설정

이 문서는 AWS 환경에서 WhaTap 클라우드 에이전트를 설정하기 위한 가이드입니다. 주요 설정 항목, 필드 설명, 권한 구성, 실행 명령까지 포함하여 운영 환경에 바로 적용할 수 있도록 구성되어 있습니다.

에이전트 설정

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

AWS DocumentDB 에이전트

config.yaml
input:
  csp: "aws" # 클라우드 서비스 제공자를 입력합니다.
  namespace: "docdb"
  region: "ap-northeast-2"
  instances: # 명시한 인스턴스는 항상 수집합니다. 클러스터 내의 인스턴스를 이 속성에 명시하면, 오토스케일 여부와 관계없이 항상 수집합니다.
    - name: "docdb-instance-name"
  clusters:
    autoscale:
      enabled: false # 오토스케일이 활성화되면, 오토스케일된 인스턴스들을 수집 대상에서 추가하거나 삭제합니다.
      interval: 60 # 명시한 클러스터들의 오토스케일 체크 주기입니다. (단위: 초)
    names:
      - "docdb-cluster-name"
  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"

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

항목	내용
지원 대상	AWS DocumentDB
인증 방식	EC2 Instance Profile + STS AssumeRole

설정 방식 선택

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

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	클러스터에 속하지 않는 standalone 인스턴스 이름

노트

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 요금 페이지를 참고하시기 바랍니다.

에이전트 설정​

AWS DocumentDB 에이전트​

설정 방식 선택​

account_configs 설정​

권한 설정​

AWS DocumentDB 권한​

DocumentDB용 IAM 인라인 정책​

에이전트 EC2 Instance Profile​

대상 계정 Cross-Account Role​

요금 안내​

AWS 요금​