2.1. 설치

개요

본 장은 OPENMARU APM Operator 를 설치하는 방법을 다룹니다. OPENMARU COP 환경은 별도 설치가 필요 없고, 직접 구축한 Kubernetes / OpenShift 클러스터는 Helm 차트로 설치합니다.

1. OPENMARU COP 환경 — 자동 구성 (설치 불필요)

OPENMARU COP(클라우드 운영 플랫폼, Kubernetes/OpenShift 기반) 환경에서는 본 Operator 가 플랫폼에 기본 포함되어 자동으로 배포·구성됩니다. 즉 COP 사용자는 아래의 수동/Helm 설치 절차를 거치지 않아도 됩니다.

• Operator(APM Agent · APM HPA) 파드가 COP 구성 시 함께 기동됩니다.
• 이미지 레지스트리, APM 서버 접속 정보(OMAPM_HOST/OMAPM_PORT), apmAlias 매핑 등 기본 환경이 COP 에서 채워집니다.
• 따라서 COP 사용자는 바로 301 자동 계측(라벨 부착)과 302 오토스케일링 부터 시작하면 됩니다.

COP 가 채운 값을 바꿔야 할 때(예: 다른 APM 서버를 추가로 등록)는 아래 설정 항목과 동일한 키를 COP 의 Operator 설정에서 조정합니다. 설정의 의미는 아래 절을 참고하십시오.

아래 절차는 COP 를 사용하지 않는(직접 구축한 Kubernetes/OpenShift) 환경 에서 수동으로 설치하는 방법입니다.

2. Helm 으로 설치 (COP 미사용 환경)

Operator 는 OPENMARU APM Helm 차트(openmaru-cop-helm-chart 의 openmaru-apm 서브차트) 로 설치합니다. Agent 와 HPA 는 values.yaml 의 서로 다른 두 키 로 구성합니다. 아래처럼 각 키로 Operator 를 활성화하고 환경을 지정합니다.

## 1) APM Agent (자동 계측 Webhook)
openmaruApmWasAgentOperator:
  enabled: true
  imageAgent:
    repository: registry.openmaru.io/images/openmaru-operator-apm-agent
    # OpenShift 내부 레지스트리 사용 시:
    # repository: image-registry.openshift-image-registry.svc.cluster.local:5000/openshift/openmaru-operator-apm-agent
    tag: latest
    pullPolicy: IfNotPresent
  envAgent:
    - name: IMAGE_REGISTRY        # 주입할 khan-agent 이미지 레지스트리
      value: "registry.openmaru.io"
    - name: IMAGE_NAMESPACE       # 레지스트리 내 네임스페이스(앞에 / 포함)
      value: "/images"
    ## OMAPM_HOST/PORT: 기본 APM 서버 정보 (개별 Deployment 설정이 우선)
    - name: OMAPM_HOST
      value: "openmaru-apm-server.openmaru-apm.svc.cluster.local"
    - name: OMAPM_PORT
      value: "8080"

## 2) APM HPA (오토스케일링 외부 지표)
openmaruApmHpaOperator:
  enabled: true
  imageHpa:
    repository: registry.openmaru.io/images/openmaru-operator-apm-hpa
    tag: latest
    pullPolicy: IfNotPresent
  ## envHpa — apmAlias 별로 APM 서버 주소를 등록
  ## (HPA 의 matchLabels.apmAlias 와 name 이 일치해야 함)
  ## <apmAlias>_ACCESS_KEY 로 해당 APM 서버의 API 액세스 키를 지정
  envHpa:
    - name: APM-INTERNAL
      value: "http://openmaru-apm-server.openmaru-apm.svc.cluster.local:8080"
    - name: APM-SERVER
      value: "http://192.168.80.190"
    - name: APM-SERVER_ACCESS_KEY
      value: "<APM API access key>"

Agent 만 또는 HPA 만 쓰려면 해당 키의 enabled 를 끄면 됩니다. replicas, strategy, resources 도 각 키 하위에서 조정할 수 있습니다.

설치는 상위 COP Helm 차트와 함께 수행합니다.

helm install openmaru-cop <chart> \
  --namespace openmaru-apm --create-namespace -f values.yaml

3. 설치 확인

OPENMARU APM/COP 를 함께 설치하면 server·mongo·redis·influx·rabbitmq·sys-agent 등 다른 파드도 같이 뜹니다. 여기서는 Operator 파드 2개 만 확인합니다.

아래 두 Operator 파드가 Running 이면 정상입니다(라벨로 한정 조회).

kubectl get pod -n openmaru-apm -l 'app in (openmaru-operator-apm-agent,openmaru-operator-apm-hpa)'

NAME                                           READY   STATUS    RESTARTS   AGE
openmaru-operator-apm-agent-xxxxxxxxxx-xxxxx   1/1     Running   0          5m
openmaru-operator-apm-hpa-xxxxxxxxxx-xxxxx     1/1     Running   0          5m

• openmaru-operator-apm-agent : 자동 계측 Webhook
• openmaru-operator-apm-hpa : 오토스케일링 지표 어댑터

4. 핵심 설정 항목 요약

항목	위치	의미
openmaruApmWasAgentOperator.enabled	최상위 키	APM Agent(자동 계측) 설치 여부
openmaruApmHpaOperator.enabled	최상위 키	APM HPA(오토스케일링) 설치 여부
imageAgent / imageHpa (repository/tag/pullPolicy)	각 키 하위	Operator 컨테이너 이미지
IMAGE_REGISTRY / IMAGE_NAMESPACE	envAgent	주입할 khan-agent 이미지를 가져올 위치
OMAPM_HOST / OMAPM_PORT	envAgent	계측 대상이 기본으로 바라볼 APM 서버 (Deployment 에 직접 지정 시 그 값 우선)
envHpa 항목들 (APM-*)	envHpa	apmAlias → APM 서버 URL 매핑. <apmAlias>_ACCESS_KEY 로 액세스 키. HPA 가 어느 서버에 질의할지 결정

APM 서버가 여러 대인 경우, envHpa 에 서로 다른 name(=apmAlias) 으로 각각 등록하고 HPA 에서 matchLabels.apmAlias 로 골라 씁니다. 자세한 내용은 302 오토스케일링 을 참고하십시오.

5. 인증서 참고 (TLS)

APM HPA 는 Kubernetes API 확장으로 동작하므로 HTTPS(8443)와 인증서가 필요합니다. Helm 차트가 기본 인증서를 포함하므로 일반적으로 추가 작업은 필요 없습니다. 인증서를 직접 교체해야 하는 경우(만료·도메인 변경 등) 저장소 루트 README.md 의 "keystore / caBundle 생성 방법" 절을 참고하십시오.

---