본문으로 건너뛰기

EC2 인스턴스 상태 전달 설정

AWS EC2 인스턴스가 종료돼도 서버 프로젝트에는 해당 서버가 등록된 채로 남을 수 있습니다. OpenAgent의 EC2 인스턴스 상태 전달 기능을 켜면 EC2 State Exporter가 조회한 인스턴스 상태를 서버 프로젝트로 보내고, 수집 서버가 종료된 인스턴스의 서버 등록을 자동으로 해지합니다. 오토 스케일링 등으로 EC2 인스턴스가 자주 생성·종료되는 환경에서 OpenAgent와 서버 모니터링을 함께 운영하는 관리자를 대상으로 합니다.

동작 방식​

AWS EC2 상태 조회
  → EC2 State Exporter: /metrics
  → OpenAgent: 등록한 서버 프로젝트별로 상태 전달
  → 수집 서버: 해당 프로젝트의 서버 식별 및 등록 해지

  • EC2 State Exporter는 CPU·네트워크 지표를 수집하는 CloudWatch Exporter와 별개의 프로그램입니다. CloudWatch Exporter만 설치했다면 EC2 State Exporter를 추가로 설치해야 합니다.

  • Exporter 하나가 인증된 AWS 계정의 리전 하나에 있는 EC2 인스턴스 전체의 상태를 조회합니다. 모든 EC2 인스턴스에 설치할 필요는 없습니다. 여러 계정·리전을 자동으로 탐색하지 않습니다.

  • OpenAgent는 등록한 서버 프로젝트마다 관측한 상태를 전달합니다. 프로젝트 코드나 인스턴스 ID와 에이전트의 매핑을 따로 입력하지 않습니다.

  • 인스턴스 상태가 shutting-down(32) 또는 terminated(48)이면, 해당 프로젝트에서 instance-id가 같은 서버를 모두 등록 해지합니다. 같은 EC2 인스턴스에 에이전트를 다시 설치해 이전 서버와 새 서버가 함께 남아 있어도 모두 해지 대상입니다.

  • 이 기능은 와탭의 서버 등록만 정리합니다. AWS의 EC2 인스턴스를 중지하거나 삭제하지 않습니다.

사전 준비​

다음 버전이 필요합니다.

ComponentVersion
OpenAgent1.8.11 이상
EC2 State Exporter0.1.0 이상
수집 서버3.1.10 이상
주의

OpenAgent 1.8.10 이하에서는 이 문서의 설정만으로 동작하지 않습니다. 대상 수집 서버가 이 기능을 지원하는지 확인하기 전에는 ec2_state_forwarding_enabled를 false로 유지하세요. 구버전 수집 서버는 전달받은 상태를 무시하므로, OpenAgent에 오류가 없다는 사실만으로 지원 여부를 판단할 수 없습니다.

EC2 State Exporter가 실행되는 EC2 인스턴스의 IAM 역할에 다음 읽기 권한을 추가하세요. 이미 허용돼 있다면 추가하지 않습니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ec2:DescribeInstances",
      "Resource": "*"
    }
  ]
}

Exporter는 AWS SDK의 기본 인증 경로를 사용합니다. EC2 역할을 사용하는 환경에서는 Access Key와 Secret Key를 따로 입력하지 않으며, whatap.conf에도 AWS 키를 넣지 않습니다. 리전은 SDK 환경변수와 프로필 설정을 먼저 사용하고, 없으면 EC2 메타데이터(IMDS)에서 확인합니다.

EC2 State Exporter 실행​

다음 명령어로 바이너리를 내려받아 실행하세요. arm64 호스트는 경로의 amd64를 arm64로 바꿉니다.

mkdir -p bin
curl -fLo bin/ec2_state_exporter https://repo.whatap.io/exporter/ec2_state_exporter/0.1.0/amd64/ec2_state_exporter
chmod +x bin/ec2_state_exporter
./bin/ec2_state_exporter --version
./bin/ec2_state_exporter

기본 수신 주소는 http://127.0.0.1:9107/metrics입니다. 리전을 자동으로 확인할 수 없거나 다른 리전을 조회하려면 --region 인자를 지정하세요.

./bin/ec2_state_exporter --region=ap-northeast-2

위 명령은 서비스 등록이나 재부팅 시 자동 시작을 설정하지 않습니다. 운영 환경에서는 사용하는 서비스 관리 방식으로 프로세스를 유지하세요.

다른 터미널에서 다음 명령어로 출력을 확인하세요.

curl --fail --show-error --max-time 15 http://127.0.0.1:9107/metrics

출력 형식은 다음과 같습니다. 인스턴스 ID는 예시입니다.

# HELP aws_ec2_instance_state EC2 lifecycle state code reported by DescribeInstances.
# TYPE aws_ec2_instance_state gauge
aws_ec2_instance_state{instance_id="i-0123456789abcdef0",region="ap-northeast-2",state_name="running"} 16

메트릭 값은 AWS 인스턴스 상태 코드입니다.

CodeState
0pending
16running
32shutting-down
48terminated
64stopping
80stopped

수집 대상 등록​

scrape_config.yaml의 기존 features.openAgent.targets 목록에 ec2-state 항목을 추가하세요. 기존 파일을 아래 예시로 덮어쓰거나 features·openAgent 키를 중복으로 만들지 말고, 기존 YAML 구조에 항목을 병합합니다.

scrape_config.yaml
features:
  openAgent:
    enabled: true
    targets:
      - targetName: ec2-state
        type: StaticEndpoints
        enabled: true
        endpoints:
          - address: "127.0.0.1:9107"
            path: "/metrics"
            scheme: "http"
            interval: "60s"
            timeout: "15s"

  • interval의 권장값은 60s입니다.

  • Exporter는 AWS 전체 조회를 10초로 제한하므로 timeout은 그보다 긴 15s로 지정합니다.

  • 기존 CloudWatch Exporter 수집 대상은 그대로 유지합니다.

  • OpenAgent와 Exporter가 다른 호스트나 컨테이너에서 실행되면 Exporter를 --web.listen-address 인자로 OpenAgent가 접근할 수 있는 사설 주소에서 실행하고, address를 그 주소로 바꾸세요. Exporter에는 TLS와 HTTP 인증이 없으므로 방화벽이나 보안 그룹으로 OpenAgent의 접근만 허용합니다.

관리 라이선스 등록​

whatap.conf에 다음 두 옵션을 추가하세요. 처음에는 기능을 끈 상태로 등록합니다.

whatap.conf
ec2_state_forwarding_enabled=false
ec2_state_licenses=<SERVER_LICENSE_A>,<SERVER_LICENSE_B>

ec2_state_licenses에는 등록 해지를 관리할 서버 프로젝트의 라이선스를 입력합니다. OpenAgent 자신의 프로젝트 라이선스(license)를 대신하는 값이 아닙니다.

  • 프로젝트가 여러 개면 쉼표로 구분해 한 줄에 입력합니다. 마지막에 쉼표를 붙이거나 빈 항목을 넣지 않습니다.

  • 라이선스에서 프로젝트 코드를 자동으로 해석하므로 프로젝트 코드는 따로 입력하지 않습니다.

  • 등록한 프로젝트는 OpenAgent가 연결한 수집 서버로 데이터를 보낼 수 있어야 합니다. 프로젝트마다 수집 서버 주소를 다르게 지정할 수는 없습니다.

수집 서버의 지원 여부를 확인했다면 ec2_state_forwarding_enabled 값을 true로 바꾸세요. 이 설정은 실제 서버 등록 해지로 이어지므로 관리할 프로젝트가 맞는지 먼저 확인합니다.

whatap.conf
ec2_state_forwarding_enabled=true
ec2_state_licenses=<SERVER_LICENSE_A>,<SERVER_LICENSE_B>

일반 호스트에서 실행하는 OpenAgent는 whatap.conf 변경을 감지해 다시 읽고, 다음 수집부터 바뀐 설정을 사용합니다.

설정 옵션​

EC2 State Exporter를 기본값으로 연결하면 ec2_state_forwarding_enabled와 ec2_state_licenses 외에는 설정하지 않아도 됩니다.

OptionTypeDefaultDescription
ec2_state_forwarding_enabledbooleanfalseEC2 인스턴스 상태 전달 활성화 여부
ec2_state_licensesstring-등록 해지를 관리할 서버 프로젝트 라이선스. 쉼표로 구분하며 최대 64개
ec2_state_metric_namestringaws_ec2_instance_state인스턴스 상태 메트릭 이름
ec2_state_instance_id_labelstringinstance_id인스턴스 ID 레이블 이름
ec2_state_state_name_labelstringstate_name상태 이름 레이블 이름
ec2_state_state_code_sourcestringvalue상태 코드를 읽는 위치. value는 메트릭 값을 상태 코드로 사용
ec2_state_state_code_labelstringstateCode상태 코드 레이블 이름. label 방식에서만 사용
ec2_state_exporter_urlsstring-상태를 처리할 수집 대상 URL 허용 목록. 미설정 시 수집한 원본 전체에서 상태 메트릭 처리
ec2_state_param_idinteger1002수집 서버로 전달하는 명령 ID
ec2_state_resend_intervalstring5m같은 상태를 다시 전달하는 주기. 5m, 30s처럼 단위가 있는 기간 형식. 300처럼 단위가 없거나 0·음수·해석할 수 없는 값은 전달 오류 발생

ec2_state_metric_name을 기본값이 아닌 이름으로 바꾸면 레이블 기본값은 instanceId·stateName·stateCode, 코드 위치 기본값은 label로 바뀝니다.

  • ec2_state_* 옵션은 같은 이름의 환경변수로도 지정할 수 있습니다. whatap.conf에 비어 있지 않은 값이 있으면 파일 값이 우선하고, 환경변수 변경은 프로세스를 다시 시작해야 반영됩니다.

  • ec2_state_exporter_urls는 이미 등록한 수집 대상 중 처리를 허용할 URL 목록입니다. 이 옵션만 설정해서는 새 수집 작업이 생기지 않으며, 실제 수집 URL의 scheme·주소·포트·경로와 정확히 일치해야 합니다.

노트

OpenAgent 1.8.11부터 ec2_state_param_id의 기본값이 56에서 1002로 바뀌었습니다. 기존 설정에 ec2_state_param_id=56이 있다면 해당 줄을 지우거나 1002로 바꾸세요. 명시한 값을 자동으로 고치거나 이전 ID로 대체해 전달하지 않습니다. 예전 예제의 메트릭 이름이나 레이블 설정이 남아 있으면 자동 기본값을 사용하지 못하므로, 다른 Exporter를 의도적으로 운영하는 경우가 아니라면 불필요한 ec2_state_* 설정을 지우세요.

쿠버네티스 Operator 환경 설정​

WhaTap Operator로 OpenAgent를 설치했다면 Pod 안의 whatap.conf나 Operator가 만든 ConfigMap·Deployment를 직접 수정하지 마세요. Operator가 수동 변경을 되돌립니다. WhatapAgent CR의 spec.features.openAgent에 설정합니다.

ItemCR field
EC2 State Exporter 수집 대상targets
기능 활성화, 관리할 서버 프로젝트 라이선스envs
OpenAgent 이미지 버전imageVersion. 현재 버전이 1.8.11 미만일 때만 지정

  1. EC2 State Exporter를 클러스터에 배포하세요. 다른 Pod의 OpenAgent가 접근할 수 있도록 --web.listen-address=0.0.0.0:9107 인자로 실행하고, Pod에서는 EC2 메타데이터 조회가 막혀 있을 수 있으므로 --region으로 조회할 리전을 지정합니다. Exporter에는 인증이 없으므로 NetworkPolicy 등으로 OpenAgent Pod의 접근만 허용하세요. Exporter 공식 컨테이너 이미지는 제공하지 않으므로 바이너리를 담은 이미지를 직접 준비해야 합니다.

    IMDS 접근이 막힌 Pod에서는 노드 IAM 역할의 자격 증명도 가져올 수 없습니다. EKS에서는 IRSA 또는 EKS Pod Identity로 ec2:DescribeInstances 권한을 부여하세요.

  2. 다음 명령어로 CR을 백업한 뒤 편집하세요.

    umask 077
    kubectl get whatapagent whatap -o yaml > "whatapagent-backup-$(date +%Y%m%d%H%M%S).yaml"
    kubectl edit whatapagent whatap

  3. spec.features.openAgent에 다음 항목을 추가하세요. 기존 envs·targets 항목은 지우지 말고 목록에 이어서 추가합니다. kubectl patch --type merge는 목록 전체를 교체하므로 기존 항목이 있으면 사용하지 않습니다.

    spec:
      features:
        openAgent:
          enabled: true
          envs:
            - name: ec2_state_forwarding_enabled
              value: "false"
            - name: ec2_state_licenses
              value: "<SERVER_LICENSE_A>,<SERVER_LICENSE_B>"
          targets:
            - targetName: ec2-state
              type: StaticEndpoints
              enabled: true
              endpoints:
                - address: "ec2-state-exporter.whatap-monitoring.svc:9107"
                  path: "/metrics"
                  scheme: "http"
                  interval: "60s"

    • 환경변수 값은 문자열이므로 "false", "true"처럼 따옴표를 붙입니다.

    • 라이선스를 CR에 그대로 두지 않으려면 Secret을 만들고 value 대신 valueFrom.secretKeyRef로 참조하세요.

    • 수집 서버 지원을 확인한 뒤 ec2_state_forwarding_enabled 값을 "true"로 바꾸면 Operator가 Deployment를 갱신해 Pod를 다시 시작합니다. Secret 값만 바꾼 경우에는 Pod가 자동으로 다시 시작되지 않으므로 OpenAgent Pod를 삭제해 다시 만들어야 합니다.

  4. 다음 명령어로 반영 결과를 확인하세요.

    kubectl -n whatap-monitoring rollout status deploy/whatap-open-agent
    kubectl -n whatap-monitoring logs deploy/whatap-open-agent --since=10m | grep -E 'EC2_STATE_'

예시의 네임스페이스 whatap-monitoring과 CR 이름 whatap은 Operator 기본값입니다. 설치 환경에 맞게 바꾸세요.

동작 확인​

  1. EC2 State Exporter의 /metrics가 HTTP 200과 aws_ec2_instance_state 샘플을 반환하는지 확인하세요. 해당 계정·리전에 인스턴스가 없으면 HTTP 200이어도 샘플이 없을 수 있습니다.

  2. OpenAgent 로그에 EC2_STATE_CONFIG, EC2_STATE_INPUT, EC2_STATE_SEND 오류가 없는지 확인하세요.

  3. 상태를 전송 큐에 넣으면 INFO 로그 EC2_STATE_FORWARD ... locally queued=<건수> from <수집 주소>를 남깁니다. 이 건수는 OpenAgent의 로컬 큐가 받아들인 건수이며, 수집 서버의 수신이나 등록 해지 성공 건수가 아닙니다.

  4. 실제 등록 해지 여부는 대상 서버 프로젝트의 에이전트 목록을 다시 조회해 확인하세요.

OpenAgent는 다음 시점에 상태를 전달합니다.

SituationBehavior
처음 관측한 상태해당 수집에서 전달
상태 코드·이름 변경변경을 확인한 수집에서 전달
같은 상태 반복마지막 전달 후 ec2_state_resend_interval(기본 5분) 동안 전달하지 않음
같은 상태로 재전송 주기 경과다음 수집에서 다시 전달
조회 실패, 목록에서 사라짐이전 상태를 다시 보내거나 terminated로 간주하지 않음

상태 변경은 AWS 이벤트를 즉시 받는 방식이 아니라 다음 수집에서 변경을 발견했을 때 전달합니다. AWS 조회 결과에서 이미 사라진 종료 인스턴스는 전달할 수 없습니다.

문제 해결​

SymptomCheck
9107 포트 연결 거부Exporter 프로세스, 수신 주소·포트, 컨테이너 네트워크 확인
EC2_STATE_EXPORTER: AWS region is unavailableAWS 환경·프로필의 리전 또는 IMDS 접근 확인. 필요하면 --region 지정
HTTP 503, EC2_STATE_EXPORTER: collection failedAWS 자격 증명, ec2:DescribeInstances 권한, 리전·네트워크 확인
HTTP 503, EC2_STATE_EXPORTER: scrape already in progress같은 Exporter에 중복 수집 대상이나 동시 수집이 있는지 확인
EC2_STATE_CONFIG 로그라이선스 누락·오타·빈 항목, 잘못된 선택 옵션 확인
EC2_STATE_INPUT 로그메트릭 형식, 필수 레이블, 코드와 상태 이름 일치 여부 확인
EC2_STATE_SEND 로그로컬 전송 큐 거부. 수집 서버 연결과 큐 상태 확인. 다음 수집에서 다시 시도
수집은 되지만 전달되지 않음OpenAgent 버전(1.8.11 이상), 실제 읽는 whatap.conf, 기능 활성화 여부, 예전 설정 잔존 여부 확인
locally queued 로그가 있는데 서버가 남아 있음수집 서버 버전, 대상 프로젝트 라이선스, 서버의 instance-id 일치 여부 확인. running·stopped 상태는 해지 대상 아님

기능 끄기​

whatap.conf에서 다음과 같이 바꾸세요. Operator 환경에서는 CR의 envs 값을 "false"로 바꿉니다.

whatap.conf
ec2_state_forwarding_enabled=false

설정을 다시 읽은 뒤 다음 수집부터 상태 전달을 멈춥니다. 일반 메트릭 수집은 계속되며, 이미 전송 큐에 들어간 데이터는 취소되지 않습니다. AWS 조회도 멈추려면 scrape_config.yaml에서 ec2-state 수집 대상을 비활성화하고 Exporter 프로세스를 중지하세요.

최종 수정: