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: 1.0.4
    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: 1.0.4
    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)

두 Operator 는 kube-apiserver 가 접속하는 HTTPS(8443) 서버입니다. MutatingWebhookConfiguration 과 APIService 가 인증서를 검증하므로 인증서 없이는 설치되지 않습니다.

값	무엇
`openmaruApmMuatingOperator.caBundle`	서버 인증서를 서명한 CA 인증서 (PEM, base64)
`openmaruSecret.tlsCrt`	서버 인증서 (PEM, base64)
`openmaruSecret.tlsKey`	서버 개인키 (PEM, base64)

🔴 인증서의 SAN 에 아래 둘이 반드시 있어야 합니다. kube-apiserver 가 이 이름으로 접속합니다.

*.openmaru-apm.svc
*.openmaru-apm.svc.cluster.local

세 값을 비워 두면 helm 이 렌더 단계에서 멈춥니다. 전에는 차트에 인증서와 개인키가 기본값으로 들어 있었으나, 차트를 받은 누구나 같은 키로 Operator 를 흉내 낼 수 있어 없앴습니다.

OPENMARU COP 환경은 추가 작업이 필요 없습니다. 설치 과정에서 레지스트리 인증서를 만드는 자리에서 Operator 인증서도 함께 만들고 값을 채웁니다.

그 밖의 Kubernetes 에 Helm 으로 직접 설치할 때는 차트의 hack/gen-webhook-cert.sh 로 인증서와 값 파일을 만듭니다. cfssl 이 있으면 cfssl 로, 없으면 openssl 로 만들며 결과는 같습니다.

./hack/gen-webhook-cert.sh ./webhook-certs

helm install openmaru-apm <차트> -n openmaru-apm --create-namespace \
  -f ./webhook-certs/webhook-cert-values.yaml

🔴 만들어진 webhook-cert-values.yaml 과 *-key.pem 에는 개인키가 들어 있습니다. 형상관리에 커밋하지 마십시오.

인증서를 교체할 때는 세 값을 helm upgrade 로 한 번에 넘기고 Operator 를 재시작합니다. caBundle 이 바뀌면 MutatingWebhookConfiguration 과 APIService 도 함께 바뀌어야 합니다.

helm upgrade openmaru-apm <차트> -n openmaru-apm -f ./webhook-certs/webhook-cert-values.yaml
kubectl -n openmaru-apm rollout restart deploy/openmaru-operator-apm-agent
kubectl -n openmaru-apm rollout restart deploy/openmaru-operator-apm-hpa

개요​

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

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

3. 설치 확인​

4. 핵심 설정 항목 요약​

5. 인증서 (TLS)​

개요

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

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

3. 설치 확인

4. 핵심 설정 항목 요약

5. 인증서 (TLS)