A.1. 레퍼런스 및 문제 해결

개요

본 장은 자동 계측 라벨과 주입 환경변수, HPA 지표의 전체 목록과 자주 묻는 질문, 점검 명령을 모아 둔 참고 자료입니다.

1. 라벨 레퍼런스 (자동 계측)

spec.template.metadata.labels 에 지정합니다.

라벨	필수	기본값	허용 값 / 예시
openmaru.io/was-agent	필수	—	'true'
openmaru.io/container-names	선택	전체	컨테이너 이름 (예: testapp)
openmaru.io/was-agent-version	선택	5.1.0	이미지 태그 (예: 5.1.0-10.3)
openmaru.io/was-agent-image-pull-policy	선택	IfNotPresent	IfNotPresent / Always
openmaru.io/java-version	선택	11	1.7 / 1.8 / 11 / 21

2. 주입 환경변수 레퍼런스

이미 같은 이름이 있으면 덮어쓰지 않습니다. JAVA_TOOL_OPTIONS 만 Append 입니다.

환경변수	기본 동작
OMAPM_HOST	미지정 시 Operator 의 OMAPM_HOST
OMAPM_PORT	미지정 시 Operator 의 OMAPM_PORT
OMAPM_APPLICATION_NAME	<container>-${HOSTNAME:-:2}
OMAPM_INSTANCE_ID	<container>-${HOSTNAME:-:2}-${HOSTNAME:-:3}
OMAPM_TRANSACTION_TRACE_THRESHOLD	500 (ms)
JAVA_TOOL_OPTIONS	-javaagent:/khan-agent/khan-agent-<version>.jar (Append)
JAVA_OPTS	java-version 이 8 초과일 때 add-opens 옵션 주입

3. Operator 설치 환경변수 레퍼런스

키	컴포넌트	의미
IMAGE_REGISTRY	Agent	주입할 khan-agent 이미지 레지스트리
IMAGE_NAMESPACE	Agent	레지스트리 내 네임스페이스(앞에 / 포함)
OMAPM_HOST / OMAPM_PORT	Agent	계측 대상 기본 APM 서버
envHpa 의 각 name/value	HPA	apmAlias → APM 서버 URL 매핑
<apmAlias>_ACCESS_KEY	HPA	(선택) 해당 APM 서버 API 액세스 키

4. HPA 지표 레퍼런스

지표	selector 라벨	질의 대상
tps	apmAlias, groupName	{APM}/monitoring/api/metrics/apps/info/{groupName} 의 TPS

5. 자주 묻는 질문 (FAQ)

Q. 애플리케이션 이미지를 바꿔야 하나요?

아니요. 라벨만 추가하면 됩니다. 에이전트는 Init 컨테이너로 주입되어 원본 이미지를 건드리지 않습니다.

Q. 이미 -javaagent 나 OMAPM_HOST 를 쓰고 있습니다.

사용자가 설정한 환경변수가 우선합니다(덮어쓰지 않음). JAVA_TOOL_OPTIONS 는 기존 값 뒤에 이어 붙습니다.

Q. 컨테이너가 여러 개인 파드는 어떻게 하나요?

openmaru.io/container-names 로 계측할 컨테이너 하나를 지정하십시오.

Q. CPU/메모리 HPA 와 같이 쓸 수 있나요?

네. 표준 HPA 의 metrics 배열에 Resource(cpu/memory)와 External(tps)를 함께 넣을 수 있습니다.

Q. APM 서버가 여러 대입니다.

envHpa 에 별칭(name)별로 등록하고 HPA 의 apmAlias 로 선택합니다(302 오토스케일링 참고).

6. 문제 해결 빠른 표

영역	증상	해결
설치	Operator 파드가 안 뜸	kubectl get pod -n openmaru-apm 로 상태·로그 확인, Helm enabled: true 확인
계측	에이전트 미주입	라벨 위치(spec.template.metadata.labels)와 값 'true' 확인
계측	이미지 Pull 실패	IMAGE_REGISTRY/IMAGE_NAMESPACE + was-agent-version 조합 이미지 존재 확인
계측	APM 콘솔 미표시	OMAPM_HOST/OMAPM_PORT 도달성 확인
HPA	TARGETS <unknown>	groupName/apmAlias 정확성, APM 도달성 확인
HPA	스케일 안 됨	minReplicas/maxReplicas, target.value 재검토

7. 점검 명령 모음

# Operator 상태
kubectl get pod -n openmaru-apm
kubectl logs deploy/openmaru-operator-apm-agent -n openmaru-apm
kubectl logs deploy/openmaru-operator-apm-hpa  -n openmaru-apm

# 계측 적용 확인
kubectl describe pod <pod> | grep -E "khan-agent-init|khan-data"
kubectl set env pod/<pod> --list | grep -E "OMAPM_|JAVA_TOOL_OPTIONS"

# HPA / 외부 지표
kubectl get hpa
kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/<ns>/tps" | jq .

---