APM 자동 설치 구성

와탭 오퍼레이터 설치 후, WhatapAgent CR(Custom Resource)을 정의하면 쿠버네티스 파드나 네임스페이스에 APM 에이전트를 자동 주입합니다.

설치 전 요구사항

Kubernetes 환경
Helm 3.2 이상
Whatap 라이선스 키(필수)
Whatap 수집 서버 정보(IP 주소와 포트)
whatap-operator(오퍼레이터 설치 가이드)

WhatapAgent CR 기본 구성

다음은 CR을 구성한 기본 샘플입니다. 추가 설정이 필요하면 APM 설정 예제를 참고하세요.

노트

이 문서의 CR 예제는 whatap-operator Helm 차트 1.9.9 기준으로 검증했습니다. 차트 버전에 따라 CR 구조가 달라질 수 있으므로, 설치한 버전과 다르면 kubectl explain whatapagent.spec으로 확인하세요.

apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: default                                # 리소스 이름
  namespace: whatap-monitoring                 # 설치 대상 네임스페이스
spec:
  features:
    apm:
      instrumentation:
        targets:
          - name: "java-sample"                # APM 대상 이름 (식별용)
            enabled: "true"                    # 자동 주입 활성화 여부
            language: "java"                   # 언어: java, python, nodejs 등
            whatapApmVersions:
              java: "2.2.58"                   # 해당 언어의 APM 에이전트 버전
            namespaceSelector:
              matchNames:
                - default                      # APM 주입 대상 네임스페이스
            podSelector:
              matchLabels:
                app: hello-world               # APM 주입 대상 파드 라벨
            config:
              mode: default                    # default 또는 custom. custom 은 configMapRef 필요
            envs:
              WHATAP_JAVA_AGENT_PATH: /whatap-agent/whatap.agent.java.jar
              OKIND: hello

APM 설정 예제

특정 네임스페이스 파드에 자동 주입

backend 네임스페이스의 app=shop 라벨을 가진 파드에 Java APM을 자동 주입합니다.
현재 Java는 latest 버전만 지원하며, 다른 언어는 추후 지원 예정입니다.
ConfigMapRef로 설정 정보를 전달합니다. ConfigMap은 대상 애플리케이션과 같은 네임스페이스에 있어야 합니다.

apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: whatap
  namespace: whatap-monitoring
spec:
  features:
    apm:
      instrumentation:
        targets:
          - name: shop-api
            enabled: "true"
            language: "java"
            whatapApmVersions:
              java: "latest"
            namespaceSelector:
              matchNames:
                - backend
            podSelector:
              matchLabels:
                app: shop
            config:
              mode: custom
              configMapRef:
                name: shop-api-config

shop-api-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: shop-api-config
  namespace: backend
data:
  whatap.conf: |
    mtrace_enabled=true
    mtrace_basetime=0
    trace_normalize_enabled=true

워크로드별 ConfigMap 분리 설정

system 네임스페이스의 app=router 파드와 backend 네임스페이스의 app=shop 파드에 각각 다른 ConfigMap(request-router-config, shop-api-config)을 주입합니다.

apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: whatap
  namespace: whatap-monitoring
spec:
  features:
    apm:
      instrumentation:
        targets:
          - name: request-router
            enabled: "true"
            language: "java"
            whatapApmVersions:
              java: "latest"
            namespaceSelector:
              matchNames:
                - system
            podSelector:
              matchLabels:
                app: router
            config:
              mode: custom
              configMapRef:
                name: request-router-config
          - name: shop-api
            enabled: "true"
            language: "java"
            whatapApmVersions:
              java: "latest"
            namespaceSelector:
              matchNames:
                - backend
            podSelector:
              matchLabels:
                app: shop
            config:
              mode: custom
              configMapRef:
                name: shop-api-config

shop-api-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: shop-api-config
  namespace: backend
data:
  whatap.conf: |
    mtrace_enabled=true
    mtrace_basetime=0
    trace_normalize_enabled=true

request-router-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: request-router-config
  namespace: backend
data:
  whatap.conf: |
    mtrace_enabled=false
    mtrace_basetime=100
    trace_normalize_enabled=true

CR 필드 레퍼런스

apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: whatap
spec:
  features:
    apm:
      instrumentation:
        targets:
          - name: <name>
            enabled: <true | false>
            language: <java | python | nodejs>
            whatapApmVersions:
              <language> : <version>
            namespaceSelector:
              matchNames:
                - <namespace>
            podSelector:
              matchLabels:
                <key>: <values>
            config:
              mode: default

기본 필드

Field	Description
`name`	타겟 이름. 모니터링에는 영향 없고 식별용입니다.
`enabled`	`"true"`일 경우 해당 타겟에 APM 에이전트를 자동 주입합니다.
`language`	타겟 애플리케이션의 언어. `java`, `python`, `nodejs` 등
`whatapApmVersions`	언어별 와탭 APM 에이전트 버전 지정
`namespaceSelector`	APM 자동 주입 대상 네임스페이스 목록
`podSelector`	APM 자동 주입 대상 파드를 라벨 기준으로 선택
`config.mode`	`"default"`(기본값) 또는 `"custom"`. `"custom"`으로 지정하면 `config.configMapRef.name`이 필수입니다.

네임스페이스 선택자 (namespaceSelector)

WhatapAgent는 쿠버네티스 표준 라벨 선택자를 지원합니다.

Field	Description
`matchNames`	대상 네임스페이스 이름 목록
`matchLabels`	키-값 쌍으로 네임스페이스 라벨 선택 (AND 조건)
`matchExpressions`	고급 라벨 선택 표현식 (AND 조건)

파드 선택자 (podSelector)

Field	Description
`matchLabels`	키-값 쌍으로 파드 라벨 선택 (AND 조건)
`matchExpressions`	고급 라벨 선택 표현식 (AND 조건)

matchExpressions 연산자

Operator	Description
`In`	라벨 값이 지정된 값 목록에 포함되어야 함
`NotIn`	라벨 값이 지정된 값 목록에 포함되지 않아야 함
`Exists`	지정된 키의 라벨이 존재해야 함 (values 필드는 비움)
`DoesNotExist`	지정된 키의 라벨이 존재하지 않아야 함 (values 필드는 비움)

K8sAgent 설정

Field	Description
`agentImageVersion`	에이전트 이미지 버전 (기본값: `latest`)
`masterAgent.enabled`	마스터 에이전트 활성화 여부
`masterAgent.resources`	마스터 에이전트의 리소스 요청 및 제한 설정
`masterAgent.envs`	마스터 에이전트에 추가할 환경 변수 목록
`nodeAgent.enabled`	노드 에이전트 활성화 여부
`nodeAgent.resources`	노드 에이전트의 리소스 요청 및 제한 설정
`nodeAgent.envs`	노드 에이전트에 추가할 환경 변수 목록
`gpuMonitoring.enabled`	GPU 모니터링 활성화 여부
`apiserverMonitoring.enabled`	API Server 모니터링 활성화 여부
`etcdMonitoring.enabled`	etcd 모니터링 활성화 여부
`schedulerMonitoring.enabled`	Scheduler 모니터링 활성화 여부

# 여러 조건을 조합한 선택자 예제
namespaceSelector:
  matchNames:
    - production
    - staging
  matchLabels:
    environment: production
  matchExpressions:
    - {key: tier, operator: In, values: [frontend, backend]}
    - {key: restricted, operator: DoesNotExist}

podSelector:
  matchLabels:
    app: web-service
    version: v2
  matchExpressions:
    - {key: tier, operator: In, values: [backend, backend2, backend3]}
    - {key: environment, operator: NotIn, values: [dev, test]}
    - {key: ready, operator: Exists}

namespaceSelector 상세 설명

네임스페이스 선택자는 세 가지 방식으로 대상 네임스페이스를 필터링합니다.
1. matchNames: 네임스페이스 이름으로 직접 선택
  - production 또는 staging 이름을 가진 네임스페이스만 선택
  - 이름 기반 필터링은 가장 기본적인 방법
2. matchLabels: 키-값 쌍으로 라벨 일치 여부 확인(AND 조건)
  - environment=production 라벨을 가진 네임스페이스만 선택
  - 모든 키-값 쌍이 일치해야 함(여러 라벨이 있을 경우 모두 만족해야 함)
3. matchExpressions: 고급 표현식으로 복잡한 조건 지정(AND 조건)
  - tier 라벨이 frontend 또는 backend 값을 가져야 함(In 연산자)
  - restricted 라벨이 존재하지 않아야 함(DoesNotExist 연산자)
  - 모든 표현식이 참이어야 함(AND 조건)
podSelector 상세 설명

파드 선택자는 두 가지 방식으로 대상 파드를 필터링합니다.
1. matchLabels: 키-값 쌍으로 라벨 일치 여부 확인(AND 조건)
  - app=web-service 및 version=v2 라벨을 모두 가진 파드만 선택
  - 지정된 모든 라벨이 정확히 일치해야 함
2. matchExpressions: 고급 표현식으로 복잡한 조건 지정(AND 조건)
  - tier 라벨이 backend, backend2, backend3 중 하나여야 함(In 연산자)
  - environment 라벨이 dev 또는 test가 아니어야 함(NotIn 연산자)
  - ready 라벨이 존재해야 함(Exists 연산자)
  - 모든 표현식이 참이어야 함(AND 조건)

테스트 샘플

APM 자동 주입을 테스트하려면 다음 YAML을 받아 설치하세요.

test-values.yaml
### 테스트 목적 샘플 자바 애플리케이션
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-world
  labels:
    app: hello-world
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hello-world
  template:
    metadata:
      labels:
        app: hello-world
    spec:
      containers:
      - name: hello-world
        image: whatap/base_java:0.0.13   # or 사용자 애플리케이션 이미지
        ports:
        - containerPort: 8080
---

apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: default                                # 리소스 이름
  namespace: whatap-monitoring                 # 설치 대상 네임스페이스
spec:
  features:
    apm:
      instrumentation:
        targets:
          - name: "java-sample"                # APM 대상 이름 (식별용)
            enabled: "true"                    # 자동 주입 활성화 여부
            language: "java"                   # 언어: java, python, nodejs 등
            whatapApmVersions:
              java: "latest"                   # 해당 언어의 APM 에이전트 버전
            namespaceSelector:
              matchNames:
                - default                      # APM 주입 대상 네임스페이스
            podSelector:
              matchLabels:
                app: hello-world               # APM 주입 대상 파드 라벨
            config:
              mode: default                    # default 또는 custom. custom 은 configMapRef 필요

설치 전 요구사항​

WhatapAgent CR 기본 구성​

APM 설정 예제​

특정 네임스페이스 파드에 자동 주입​

워크로드별 ConfigMap 분리 설정​

CR 필드 레퍼런스​

기본 필드​

네임스페이스 선택자 (namespaceSelector)​

파드 선택자 (podSelector)​

matchExpressions 연산자​

K8sAgent 설정​

테스트 샘플​