본문으로 건너뛰기

설치 문제 해결

Helm 차트 기준 설치 문제 해결​

이름이 whatap 다른 Helm 리포지토리가 있을 경우​

"whatap" already exists with the same configuration, skipping

이미 동일한 이름의 다른 whatap 리포지토리가 존재할 경우 다음 명령어를 통해 기존 whatap 리포지토리 삭제 후 설치를 진행하세요.

helm repo remove whatap

이름이 whatap-monitoring인 다른 네임스페이스가 클러스터에 있을 경우​

Error: INSTALLATION FAILED: Unable to continue with install: Namespace "whatap-monitoring" in namespace "" exists and cannot be imported into the current release

클러스터에 whatap-monitoring 네임스페이스가 존재한다면 사용자가 yaml 파일 기준으로 이미 와탭 쿠버네티스 에이전트를 설치했기 때문입니다. 이 경우 다음 명령어를 통해 기존 whatap-monitoring 네임스페이스 및 관련 리소스를 삭제하세요.

kubectl delete namespace whatap-monitoring
kubectl delete clusterrolebinding whatap
kubectl delete clusterrole whatap

clusterrole, clusterrolebinding 리소스가 이미 클러스터에 있을 경우​

Error: INSTALLATION FAILED: Unable to continue with install: ClusterRole "whatap" in namespace "" exists and cannot be imported into the current release

클러스터에 clusterrole, clusterrolebinding 리소스가 이미 존재할 경우 다음 명령어를 통해 해당 리소스를 삭제하세요.

kubectl delete clusterrolebinding whatap
kubectl delete clusterrole whatap

whatap-monitoring 네임스페이스를 사용할 수 없는 경우​

기본적으로 와탭 쿠버네티스 에이전트는 whatap-monitoring 네임스페이스에 설치됩니다. 그러나 해당 네임스페이스를 사용할 수 없거나 또는 사용자가 특정 네임스페이스를 지정해야 하는 경우, 다음 과정을 참고하여 원하는 네임스페이스에 에이전트 설치를 진행하세요.

사전 준비​

  • 차트 버전: whatap/kube 1.7.11 이상

    다음 명령어를 통해 차트 버전을 확인하세요.

    helm search repo whatap/kube --versions

    1.7.11 버전 미만인 경우 다음 명령어를 통해 차트 버전을 업데이트하세요.

    helm repo update

  • Helm 버전: Helm 3 이상

설치 과정​

사용하고자 하는 네임스페이스 이름을 <namespace> 자리에 입력한 후 다음 명령어를 실행하여 에이전트를 설치하세요.

helm install whatap-kube-agent whatap/kube --create-namespace --namespace <namespace> --set namespaceOverrideEnabled=true --wait -f values.yaml

업데이트 및 삭제​

  • 업데이트

    다음 명령어를 통해 에이전트를 업데이트하세요.

    helm update whatap-kube-agent whatap/kube --namespace <namespace> --wait

  • 삭제

    다음 명령어를 통해 에이전트를 삭제하세요.

    helm uninstall whatap-kube-agent whatap/kube --namespace <namespace>


에이전트 기동 시 발생하는 문제 해결​

구형 YAML 파일을 통해 와탭 쿠버네티스 모니터링 설치한 경우​

Unrecognized VM option 'UseCGroupMemoryLimitForHeap'
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

2022년 8월 24일 이전에 다운로드한 설치 YAML을 통해 와탭 쿠버네티스 모니터링을 설치한 경우 노드 에이전트(whatap-node-agent) 기동 시 오류가 발생하며 기동에 실패하는 경우가 있습니다.

원인은 다음과 같습니다. 2022년 8월 24일 이전에 다운로드한 설치 YAML 파일 내 UseCGroupMemoryLimitForHeap JVM 옵션을 사용한 노드 에이전트 실행 스크립트가 포함되어 있습니다.

와탭 노드 에이전트 1.2.0 이상(2022년 11월 21일 배포) 버전부터 에이전트 내부에서 사용하는 JDK가 업그레이드 되었으며 업그레이드된 JDK 버전은 더 이상 UseCGroupMemoryLimitForHeap 옵션을 제공하지 않습니다. 2022년 8월 24일 이전에 다운로드한 YAML 파일로 와탭 쿠버네티스 모니터링을 설치한 상태로 노드 에이전트 1.2.0 이상 버전을 기동하는 경우 Unrecognized VM option 'UseCGroupMemoryLimitForHeap’ 메세지가 발생하며 기동에 실패하게 됩니다.

해결 방법​

이 문제를 해결하기 위해 다음과 같이 쿠버네티스 모니터링을 재설치하세요.

  1. 관리 > 에이전트 설치 화면에서 최신 YAML 파일을 다운로드하세요.

  2. 사용자 쿠버네티스 환경에서 다운로드한 YAML 파일을 사용하여 에이전트를 설치하세요.

  3. 사용자 쿠버네티스 환경에서 설치 과정 중 오류 출력 여부를 확인하세요.

  4. 와탭 모니터링 에이전트 Pod가 Running 상태인지 확인하세요.

    노트

    사용자 쿠버네티스 환경 및 워크로드 > Pod 목록 메뉴에서 확인하세요.

  5. 관리 > 쿠버네티스 에이전트 목록 메뉴에서 각 모니터링 에이전트에서 발생하는 로그를 확인하세요.

DockerHub 이미지 pull limit으로 에이전트가 정상적으로 설치되지 않는 경우​

여러 노드에서 동시에 이미지를 pull할 경우 아래와 같은 오류가 발생하며 설치에 실패할 수 있습니다. 문제가 발생한 경우 아래 명령어로 yaml에 이미지를 변경해 재설치가 필요합니다.

에러 조회​

kubectl describe pod/<와탭 k8s 에이전트 파드명> -n whatap-monitoring

조회 결과​

> > Failed to pull image "whatap/kube_mon:latest": rpc error: code = Unknown desc = toomanyrequests: You have reached your pull rate limit. Please try again later or log in to increase your rate limit.

이 경우, yaml 파일 내 DockerHub 이미지를 public.ecr.aws 레포로 변경한 후 재설치가 필요합니다.

  • 에이전트 설치 화면에서 기본 설치용 yaml을 다운로드한 경우 아래 명령어를 사용해 이미지를 변경할 수 있습니다. 명령어 수행 시 yaml에 있는 기존 dockerHub 이미지가 public.ecr.aws 리포지토리 이미지로 대체됩니다.

    sed -i 's|image: "whatap/kube_mon|image: "public.ecr.aws/whatap/kube_mon|g' kube_agent.yaml

애플리케이션 연동 문제 해결​

컨테이너 맵에 Java 모니터링 데이터가 표시되지 않는 경우​

사용자 쿠버네티스 환경에서 Cgroups의 설정 및 관리 방식에 따라 특정 상황에서 컨테이너 ID를 확보하지 못하는 문제가 발생할 수 있습니다. 와탭은 이러한 상황에 대응하기 위해 쿠버네티스 모니터링의 컨테이너와 애플리케이션 간 매핑 메커니즘을 변경하였습니다. 해당 변경 사항의 경우 와탭 쿠버네티스 에이전트 1.8.8 버전과 Java 에이전트 2.2.42 버전부터 적용되어 Cgroups 영향으로 컨테이너 ID가 누락되는 문제를 해결합니다.

해결 방법​

에이전트 업데이트​

쿠버네티스 환경에서 발생하는 컨테이너 ID 식별 문제를 해결하기 위해서는 와탭 쿠버네티스 에이전트와 APM이 서로 주고받는 데이터를 정확히 식별할 수 있도록 지원하는 최신 버전을 사용해야 합니다. 쿠버네티스 에이전트는 1.7.7 버전 이상을 설치하고 Java 에이전트는 2.2.42 버전 이상을 설치하세요.

노트

현재는 Java 에이전트만 지원하고 있으며 다른 언어의 APM은 추후 지원할 예정입니다.

추가 환경변수 설정​

에이전트 버전 업데이트 이후에도 컨테이너 맵에 Java 애플리케이션 정보가 표시되지 않는 경우 사용자 환경변수를 추가하여 문제를 해결할 수 있습니다. 이 설정은 Java APM이 설치된 컨테이너 매니페스트(YAML)의 환경변수에 해당 컨테이너 내 Java 에이전트의 절대 경로를 나타내는 WHATAP_JAVA_AGENT_PATH 옵션을 추가합니다.

다음은 Java APM이 설치된 컨테이너 환경변수에 해당 옵션을 추가한 예시입니다.

env:
- name: NODE_IP
  valueFrom: {fieldRef: {fieldPath: status.hostIP}}
- name: NODE_NAME
  valueFrom: {fieldRef: {fieldPath: spec.nodeName}}
- name: POD_NAME
  valueFrom: {fieldRef: {fieldPath: metadata.name}}
- name: OKIND
  value: {YOUR_OKIND_NAME}
- name: license
  value: <Project Access Key>
- name: whatap.server.host
  value: <수집서버 IP 주소>
- name: whatap.micro.enabled
  value: "true"
- name: WHATAP_JAVA_AGENT_PATH
  value: "/whatap/whatap.agent-2.2.35.jar"

컨테이너와 APM 간 정상 매핑 확인 방법​

컨테이너와 애플리케이션이 정상 매핑되었는지 확인하는 방법은 다음과 같습니다.

  • 대시보드 > 컨테이너 맵 메뉴에서 컨테이너 맵 블록 내부에 흰색 마이크로 컨테이너가 존재할 경우 정상적으로 매핑된 상태입니다.

  • 분석 > 메트릭스 조회 메뉴에서 app_counter 카테고리의 container 필드에 애플리케이션이 실행 중인 컨테이너 ID가 기록된 경우 정상적으로 매핑된 상태입니다.

최종 수정: