Daramu

Spring Cloud Gateway 와 KeyCloak 의 구조

Daramu — Tue, 2 Jun 2026 13:22:14 +0900

이전 포스팅으로 Spring Cloud Gateway(이하 SCG)에 대한 내용을 다뤘다.

https://daramu.tistory.com/91

Spring boot - Spring Cloud Gateway(SCG) 란?

MSA에서 코드를 구성하는 방식은 여러개가 있다. 그 중 피할 수 없는 건 프론트-백엔드간의 연계이다. 이렇게 생각해보자. 당신은 쇼핑몰 웹을 운영중이다.이 쇼핑몰 앱은 여러개의 백엔드 API가

daramu.tistory.com

여기서는 프론트는 SCG라는 단일 진입점을 통해 관리와 통신에 대한 이점을 소개했지만,

한가지 예외 사항이 있다.

바로 KeyCloak을 사용할때다.

아래 그림처럼 브라우저(프론트)는 여러 백엔드에 대하여 SCG 하나만 바라보는게 맞다.

하지만 여기서 KeyCloak은 예외로 두고 프론트가 직접 통신할 수 있게 할 것이다.

의문을 가질 수 있다.

왜 KeyCloak은 SCG로 제어하지 않는가?

가능은 하다.

SCG의 라우팅 설정에서 /login 등의 호출이 있을시 KeyCloak으로 라우팅해줄 수 있다.

하지만 사용자는 KeyCloak자체에 들어가 로그인을 해야하기 때문에, 사용자는 어찌되었든 KeyCloak으로 접속을 해야한다.

그리고 브라우저가 접속을 해야한다는 것은, KeyCloak자체가 외부에 노출되어 있어야 한다는 의미이다.

(물론 Keycloak에 허용된 클라이언트와 redirect URI만 등록해두는 등의 보안 설정은 필요하다)

고로 SCG를 사용한다 하여도 중간에 통신 과정만 추가될 뿐이지 결과적으로 KeyCloak으로 접속하게 되니,

네트워크의 복잡성을 줄이기 위해 KeyCloak만큼은 SCG로 관리하지 않는 예외로 둘 것이다.

이것이 싫다면 Keycloak을 SCG에 등록하는 방법도 있다.

하지만 그렇게 하려면 결국 Keycloak의 리다이렉트 방식을 포기하고 직접 JWT를 발급하는 auth 서비스를 만들어야 하는데, 그건 앞서 살펴보았듯이 Keycloak의 장점을 모두 삭제하는 행위이기에 본 포스팅에서는 KeyCloak을 사용할 것이며 SCG에 등록하지 않을 것이다.

참고로 이 모든 내용은 현대식 브라우저 기반 프론트엔드(React, Vue...etc..)에서 PKCE 플로우를 사용한다는 가정하에 하는 말이다.

웹페이지인 이상 브라우저 기반 프론트를 사용하면 모든 코드가 사용자에게 100%노출된다는 가정하에서 하는 말이며,

생각해보면 KeyCloak을 호출하는 것은 사용자(브라우저)뿐 아니라 백엔드 API일 수 있다.

API to API 방식만 사용한다면 굳이 별도로 분리하는게 아닌, SCG로 관리하여도 무방하다.

(단, 실무에서는 대부분 브라우저 기반 플로우를 사용하기 때문에 이 방식은 흔하지 않다.)

차후 있을 포스팅에서 "사용자 - KeyCloak"과 "백엔드 API - API" 두가지 상황 모두 확인해볼 것이다.

후자를 사용하는 경우는 SCG가 Keycloak의 공개키로 JWT를 자체 검증하거나,

Keycloak 인트로스펙션 엔드포인트에 직접 요청하는 방식 모두 SCG - Keycloak 간 API to API 통신이 발생하기 때문이다.

한칸 정리:

Spring boot - Spring Cloud Gateway(SCG) 란?

Daramu — Tue, 2 Jun 2026 12:50:25 +0900

MSA에서 코드를 구성하는 방식은 여러개가 있다.

그 중 피할 수 없는 건 프론트-백엔드간의 연계이다.

이렇게 생각해보자.

당신은 쇼핑몰 웹을 운영중이다.

이 쇼핑몰 앱은 여러개의 백엔드 API가 있을 것이다.

그 중에는 동일한 서비스(도메인)의 주소도 있을 것이고, 아예 다른 도메인도 있을 것이다.

예를 들어, 제품에 대한 API를 제공하는 Product 라는 서비스가 있고, 또 결제를 담당하는 payment 라는 서비스가 있을 수 있고, 결제 완료나 안내사항을 작성하는 Notification 이라는 서비스도 있을 수 있다.

이 모든 것을 하나의 서비스에 몰아둘 수 있지만, 그건 MSA 철학에 맞지 않는다. 아주 높은 확률로 다른 서비스로 떠 있을 것이다.

이때 당신의 프론트 엔드가 백엔드를 호출하는 상황을 가정해보자.

사용자가 처음 웹 페이지를 방문할 때는 제품 정보를 받아오기 위해 API를 호출한다.

const response = await fetch('http://localhost:8081');

그리고 제품을 고르고 결제를 한다면 다시 다른 서비스의 API를 호출한다.

const response = await fetch('http://localhost:8082');

결가 완료되었다면 그 안내를 위한 다른 서비스의 API를 호출한다.

const response = await fetch('http://localhost:8083');

여기서 편의상 localhost라고 적었지만 실제 도메인을 사용한다면 더욱 복잡해질 것이다.

만약 payment의 주소가 바뀐다면?

모든 코드의 호출 주소를 바꿔야 한다.

거기에 보안가지 생각해야 한다.

JWT 방식으로 사용자에게 토큰을 주어 사용자 식별을 한다고 가정해보자.

그럼 product 서비스는 jwt를 분석할 수 있는 로직이 있어야하고,

또 payment또한 jwt를 분석할 수 있는 로직이 있어야한다.

물론 notification또한 동일하다.

이처럼 많은 중복 포인트와 복잡한 로직, 수정의 어려움을 겪게 되는데, 그때 사용하면 좋은 것이 Spring Cloud Gateway(이하 SCG)이다.

간단히 말해, 프론트(브라우저)와 백엔드 사이에 SCG를 둠으로,

프론트의 입장에서 연결될 백엔드는 오로지 SCG하나밖에 없으니 모든 코드를 이렇게 바꿀 수 있다.

const response = await fetch('http://localhost:8081'); -> const response = await fetch('http://localhost:8080');

const response = await fetch('http://localhost:8082'); -> const response = await fetch('http://localhost:8080');

const response = await fetch('http://localhost:8083'); -> const response = await fetch('http://localhost:8080');

거기에 jwt에 대한 검증도 마찬가지다.

기존에는 각기 모든 백엔드 서비스가 jwt에 대한 유효성 검사로 자체적인 jwt분석 로직이 있거나, 요청때마다 별도의 auth 서비스를 오고가야 했다면, 이제는 프론트 입장에서 단일 진입점은 SCG이므로, SCG에서 jwt의 유효성을 검사하고 맞는 사용자라면 별도의 헤더로 백엔드에 내려줄 수 있다.

예시로 test@test.com 이라는 유저가 결제 요청을 했다고 해보자.

이 API요청에는 jwt토큰또한 들어있을 것이다.

기존에는 payment 서비스가 jwt를 분석하고, 유효성을 판단하며, jwt안에 있는 test@test.com 이라는 유저의 Id나 Email을 뽑아내어 사용했다면,

이제는 SCG가 jwt유효성을 검사하고 헤더값에 (X-User-Id: test@test.com) 이라는 헤더를 넣어 payment에 주면 된다.

그럼 payment 서비스는 SCG를 신뢰하여 jwt분석로직 없이 오로지 헤더의 test@test.com 이라는 값만 사용하여 비지니스 로직을 짜면 된다.

물론 백엔드는 SCG가 JWT검증 후 내려주는 별도의 헤더를 신뢰한다면 그것이 변조 되는 것(해킹)을 고려해야 한다.

백엔드 자체에 jwt 분석 및 검증 로직이 있다면 상관없지만, SCG를 통해 헤더로 X-User-Id 를 받기만 하면 되면, 반대로 집어넣기만 하면 통신이 된다는 의미이기 때문이다.

고로 백엔드가 외부에서 직접 접근 가능하다면 보안에 취약함으로, 백엔드 서비스는 SCG를 통한 접근만 가능하도록 내부망 격리, 혹은 네트워크 정책으로 막아야할 필요성은 분명 존재한다.

KeyCloak 설치

Daramu — Tue, 2 Jun 2026 11:40:36 +0900

keycloak(이하 키클록)을 설치할 것이다.

키클록에 대한 것과, 어떤 방식으로 구현할 것인지 궁금하다면 아래 포스팅 참고 바란다.

https://daramu.tistory.com/89

Keycloak 이란?

Keycloak(이하 키클록)이란 레드햇에서 개발한 오픈 소스 통합 인증 솔루션으로, 애플리케이션의 복잡한 로그인, 회원가입, 권한 부여 기능을 중앙에서 쉽게 통합하고 관리할 수 있게 해준다. MSA환

daramu.tistory.com

그럼 설치전에 여러가지 옵션이 있다.

키클록 공식 홈페이지를 보면 아래와 같은 설치 옵션을 제공해준다.

https://www.keycloak.org/guides

만약 본인 로컬 환경이라면 OpenJDK나 Docker, 특히 Docker를 추천한다.

윈도우 환경이라 하여도 Docker Desktop을 통해 충분히 올릴 수 있으며, 이미지화 되어있기에 설치도 한줄로 간단하게 진행할 수 있다.

하지만 본 포스팅에서는 NCP의 NKS(Naver Kubernetes Service)를 사용하고 있는 만큼, Kubernetes 를 사용해서 올릴 것이다.

두려워할 필요 없다. Docker라면 한줄로 하면 되고, 쿠버네티스라면 함께 구축하면 된다.

위 링크의 쿠버네티스에 들어가면 다음과 같은 명령어가 표시된다.

kubectl create -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/refs/heads/main/kubernetes/keycloak.yaml

위 명령어의 https URL로 직접 접속하면 yaml파일이 있으며, service 세개와 statefulset한개, 그리고 deployment 한개가있다.

여기서 한개의 deployment와 service는 postgresql에 대한 것이다.

가장 위에 있는 주석처리된 경고문 처럼, 해당 deployment는 임시 테스트를 위한 저장소인 postgresql의 쿠버네티스 리소스로, pod가 멈추면 데이터가 손실된다.

바로 밑에 두번째 주석으로 프로덕션 셋업시에는 지속가능한 DB로 변경하라 나와있기에 그렇게 진행할 것이다.

나머지 두개의 service와 한개의 statefulset은 keycloak에 대한 것이다.

여기서 가장 위의 keycloak, 밑에 keycloak-discovery 둘 모두 selector로 app: keycloak으로 된것을 알 수 있다.

동일한 statefulset인 keycloak을 바라보며 discovery는 내부에서 클러스터링을 위한 서비스이니, 실제 접속은 가장 상단의 keycloak service(port:8080)을 사용하게 될 것이다.

statefulset은 익히 알듯이, 고유한 네트워크 식별자가 필요할때 사용하며, 이는 기존 파드가 죽으면 같은 이름과 볼륨으로 재생성된다는 것이다. (일반 deployment는 replicasname으로 무작위로 생성된다.)

주로 데이터 영속성이 필요하며, 파드가 재시작 되어도 반드시 자신의 원래 데이터를 다시 마운트할때 사용한다.

롤링 업데이트 시 Pod가 하나씩 순서대로 재시작되도록 보장함과 동시에 JGroups 클러스터링을 위한 안정적인 네트워크 식별자 확보를 위해 Statefulset을 사용한다(주석에 설명되어있다.)

추가로 statefulset의 세부항목을 보면 pod로 띄웠던 postgresql을 연결하는 항목도 찾을 수 있다.

이제 기본제공하는 yaml파일을 보았으니, 설치하기 전에 아까 말했듯 pod로 올린 postgresql이 아닌 서버나 rds등을 사용한 영속성이 있는 DB가 필요하다.

본 포스팅에서는 NCP의 CDB(Cloud for DB) Postgresql을 사용할 것이다.

AWS의 RDS postgresql도 동일하며, 어차피 URL로 로그인하는 것은 똑같기에 AWS로 진행해도 문제는 없다.

생성하였다면 접속 URL과 생성시 만들었던 계정이 있을 것이다.

DB를 생성했다면, 이제 Postgresql의 설정을 진행할 차례다.

keycloak은 DB연결시 테이블(스키마)를 자동으로 생성하지만 DB 자체는 직접 만들어야한다.

위에 검은색으로 가린 부분의 URL을 통해 Postgresql에 접속한다.

그 후 아래의 쿼리를 통해 DB를 생성한다.

CREATE DATABASE keycloak;
CREATE USER keycloak WITH PASSWORD '실제패스워드';
GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak;

\c keycloak
GRANT ALL ON SCHEMA public TO keycloak;

NCP의 경우 추가가 안될 수 있는데, 콘솔 -> CDB Postgresql -> Database 관리 에서 User와 Database를 추가하거나 삭제할 수 있다.

마지막으로 공식 yaml파일에 있듯이, secret을 사용하여 username와 password를 생성하여 db에 연결하라 권장하니 그렇게 따라준다.

당연한 말이지만 keycloak이 아래 생성할 secret정보를 가지고 db에 접속하니, 만든 db의 username,password와 secret의 username,password는 같게 해야한다.

#패스워드에 특수문자 있을경우 따옴표 사용 '실제패스워드'
kubectl create secret generic keycloak-db-secret \
  --from-literal=username=keycloak \
  --from-literal=password=실제패스워드

이정보를 가지고 키클록을 생성하자.

yaml 파일에서 username, password부분만 아래와 같이 변경해준다.

- name: 'KC_DB_USERNAME'
  valueFrom:
    secretKeyRef:
      name: keycloak-db-secret
      key: username
- name: 'KC_DB_PASSWORD'
  valueFrom:
    secretKeyRef:
      name: keycloak-db-secret
      key: password

그리고 DB URL 부분을 실제 host명으로 변경한다.

- name: 'KC_DB_URL_HOST'
  value: 'postgres'
  #실제 host로 변경. 기존은 postgres라는 service를 찾게 설정 되어있음

추가로 cdb(혹은 aws rdb, ec2...etc)를 사용 중이므로, 전체 yaml파일에서 가장 하단에 postgresql 에 대한 deployment와 service를 삭제한다.

이 deployment와 service를 삭제한다.

그럼 최종적으로 아래와 같은 yaml파일이 된다.

...(생략)
            - name: 'KC_DB_URL_HOST'
              value: 실제 DB 호스트 입력(IP OR URL)
            - name: 'KC_DB'
              value: 'postgres'
            - name: 'KC_DB_PASSWORD'
              valueFrom:
                secretKeyRef:
                  name: keycloak-db-secret
                  key: password
            - name: 'KC_DB_USERNAME'
              valueFrom:
                secretKeyRef:
                  name: keycloak-db-secret
                  key: username
          ports:
            - name: http
              containerPort: 8080
            - name: jgroups
              containerPort: 7800
            - name: jgroups-fd
              containerPort: 57800
          startupProbe:
            httpGet:
              path: /health/started
              port: 9000
            periodSeconds: 1
            failureThreshold: 600
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 9000
            periodSeconds: 10
            failureThreshold: 3
          livenessProbe:
            httpGet:
              path: /health/live
              port: 9000
            periodSeconds: 10
            failureThreshold: 3
          resources:
            limits:
              cpu: 2000m
              memory: 2000Mi
            requests:
              cpu: 500m
              memory: 1700Mi

해당 파일을 실행하면 pod와 service가 뜬 것을 확인할 수 있다.

default namespaces가 거슬린다면 yaml파일에서 metadata.namespace 에서 원하는 네임스페이스를 지정하면 된다.

본 포스팅은 어디까지나 테스트 용이므로 기본 namespace를 사용하겠다.

이제 이렇게 올렸다면 문제가 하나 있다.

웹페이지에 접속할 방법이 없다.

yaml파일 최상단에 service가 있지만, 타입은 ClusterIP타입이다.

apiVersion: v1
kind: Service
metadata:
  name: keycloak
  labels:
    app: keycloak
spec:
  ports:
    - protocol: TCP
      port: 8080
      targetPort: http
      name: http
  selector:
    app: keycloak
  type: ClusterIP

이제 접속을 위한 작업을 시작하겠다.

두가지 방법이 있는데, 하나는 저 위 코드의 type을 ClusterIP에서 LoadBalancer로 변경하는 것이다.

다른 하나는 ingress파일을 작성하여 alb나 nginx 등 ingresscontroller를 사용하여 접속하는 것이다.

본 포스팅에서는 ingress파일 방식으로 진행할 것이다.

혹시 ingress, ingressclass등 개념이 궁금하면 아래 포스팅 참고

https://daramu.tistory.com/71

Ingress와 IngressClass, 그리고 쿠버네티스의 관계

본 포스팅은 NCP환경 기준으로 작성 되었으나, 쿠버네티스 환경 자체에 대한 설명이기도 하기에 NCP에 국한되지는 않는다. 앞으로 여러 포스팅을 통해 ingress와 ingressclass, 그리고 쿠버네티스의 여

daramu.tistory.com

이제 ingress파일을 작성해주겠다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: keycloak
  annotations:
    alb.ingress.kubernetes.io/network-type: 'private'
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: keycloak
            port:
              number: 8080

annotaion에 "alb.ingress.kubernetes.io/network-type: 'private'" 이건 VPN환경이기에 공인IP가 필요없기에 설정했다. 공인IP를 사용해야 하는 환경이라면 annotation과 network-type 두개를 삭제하면 된다.(name만 남기라는 뜻.)

추가로 NCP에서는 ALB ingress 를 통해 노출시킬 서비스 type은 NodePort로 하라 되어있으니 service를 수정한다.

https://guide.ncloud-docs.com/docs/k8s-k8suse-albingress

apiVersion: v1
kind: Service
metadata:
  name: keycloak
  labels:
    app: keycloak
spec:
  ports:
    - protocol: TCP
      port: 8080
      targetPort: http
      name: http
  selector:
    app: keycloak
  type: NodePort
  .......(생략)

그리고 생성된 LB에 접속하면, keycloak이 동작중이다!

접속을 위한 접속계정은 yaml파일에 있듯 admin/admin이다. 바꾸고 싶다면 바꾸는 것도 좋다.

Keycloak 이란?

Daramu — Mon, 1 Jun 2026 15:18:50 +0900

Keycloak(이하 키클록)이란 레드햇에서 개발한 오픈 소스 통합 인증 솔루션으로, 애플리케이션의 복잡한 로그인, 회원가입, 권한 부여 기능을 중앙에서 쉽게 통합하고 관리할 수 있게 해준다.

MSA환경에서는 여러개의 Pod가 떠있고, Pod와 워커노드(서버) 모두 문제가 발생한다면 버리고 다시 생성해서 사용하는 것을 기본값으로 한다.

그렇기에 서버가 사용자의 정보를 가지고 있는 세션 방식은 MSA에서는 사용이 어렵다.

Pod A에서 로그인했는데 다음 요청이 Pod B로 라우팅되면, Pod B에는 세션이 없어 인증 실패가 발생한다. 수십 개의 Pod가 동시에 떠 있는 환경에서는 이 문제가 더욱 심각해진다.

이때 사용하는 것이 JSON Web Token (JWT)이다. 세션 방식이 사용자의 인증 정보를 서버가 가지고 있는 것이라면, JWT는 사용자(브라우저)가 가지고 있다가 요청과 함께 제출하는 것이다.

여기서 주목할 것은 사용자가 브라우저라는 것이다.
이 말의 뜻은 무엇인가?

일반적으로 MSA환경에서는 프론트와 백엔드가 분리되어 있는 경우가 많다.
MSA철학으로도 그러하다.

그런데 프론트는 html과 css, 그리고 js(혹은 ts)의 코드 뭉치일 뿐이다.
이것을 화면에 표시해주는 것은 브라우저이다.

그리고 브라우저는 기본적으로 모든것을 공개한다.

즉, 당신의 모든 프론트 코드는 공개되어있다는 가정이 필요하다.

실제로 크롬에서 F12를 통해 개발자 도구로 들어가면, Elements에서 html, css파일을, Sources에서 JS(TS는 JS로 변환되어 올라간다)를 확인할 수 있다.

이 상황에서 토큰을 발급받을 때 필요한 고정된 비밀키를 JS에 넣을 수는 없을 것이다.(공개가 되어있기 때문에)

그럼 사용자 인증을 어떻게 진행해야 하는가?

바로 PKCE 방식이다.

OAuth2 인증에서 토큰을 발급받으려면 원래 서버가 client_secret이라는 고정된 비밀키를 인증 서버에 제출해야 한다. 그런데 아까도 말했지만 React, Vue, Angular같은 현대적 브라우저 기반 앱(SPA)은 소스 코드가 100% 노출된다는 가정이 있다.

그래서 JS든 어디든 비밀키를 집어넣으면 곧바로 노출되어 문제가 발생한다.

이때 사용하는 것이 PKCE 방식이다.

그림이 복잡해 보이지만 별거 없다.

PKCE 방식은 고정된 비밀키 없이 매번 일회용 비밀키를 실시간으로 생성하겠다는 것이다. 그리고 여기에는 한 가지 목적이 더 있다. 인증 코드가 중간에 탈취되더라도, code_verifier가 없으면 토큰 교환 자체가 불가능하게 만드는 것이다.

브라우저는 일회용 난수(Verifier)를 생성하고, 이를 암호화한 챌린지(Challenge)를 생성한다.
그리고 로그인 요청과 동시에 Challenge를 함께 전송한다.
그리고 인증서버는 Challenge를 저장하며 로그인 완료 후 코드를 발급하고, 다시 브라우저는 코드에 원본 Verifier를 더해 토큰 교환을 요청한다.
그럼 인증서버는 Challenge와 Verifier를 대조해서 검증이 성공하면 JWT를 주는 방식이다.

말이 길었지만, 요점은 MSA환경에서, 특히 React등 SPA를 사용할 경우 고정된 비밀키를 숨길 수 없기에 매번 로그인할 때마다 동적으로 일회용 암호 장치를 만드는 것이다.

설령 코드가 탈취되더라도 Verifier가 없으면 토큰 교환이 불가능하다는 보안 장치도 함께 갖추고 있다.

이 방식을 PKCE라고 하며, 현재 SPA 등 Public Client에서의 OAuth2 인증의 사실상 표준이다.

위의 방식으로 인증 서버를 직접 구축하려면 많은 인력과 시간이 소요되며, 관리도 어렵다.

이때 사용하는 것이 Keycloak같은 오픈소스 인증 솔루션이다.

Keycloak은 위의 절차를 내부적으로 탑재하여 관리에 필요한 리소스를 줄여준다.

Spring boot Dockerfile

Daramu — Fri, 29 May 2026 16:13:49 +0900

스프링 부트를 이미지로 만들기 위한 도커 파일이다.

프로젝트는 Gradle - Kotlin로 생성했고, JDK는 17을 사용중이다.

아래 예시는 Java 17 기준이며, 자바 버전이 다르다면 두개의 베이스 이미지(FROM)을 변경하면 된다.

FROM eclipse-temurin:17-jdk-alpine AS builder
WORKDIR /build

COPY gradlew .
RUN chmod +x ./gradlew

COPY gradle gradle
COPY build.gradle.kts settings.gradle.kts ./

RUN ./gradlew dependencies --no-daemon || true

COPY src src
RUN ./gradlew bootJar -x test --no-daemon

RUN java -Djarmode=layertools -jar build/libs/*-SNAPSHOT.jar extract

FROM eclipse-temurin:17-jre-alpine
WORKDIR /app

RUN apk add --no-cache tzdata && \
    cp /usr/share/zoneinfo/Asia/Seoul /etc/localtime && \
    echo "Asia/Seoul" > /etc/timezone

RUN addgroup -S spring && adduser -S spring -G spring
USER spring:spring

COPY --from=builder /build/dependencies/ ./
COPY --from=builder /build/spring-boot-loader/ ./
COPY --from=builder /build/snapshot-dependencies/ ./
COPY --from=builder /build/application/ ./

EXPOSE 8080

ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

# JDK 26이라면
FROM eclipse-temurin:26-jdk-alpine AS builder
FROM eclipse-temurin:26-jre-alpine

SSH 포트는 살아있지만 로그인이 안될때

Daramu — Fri, 29 May 2026 15:59:45 +0900

telnet이나 nc로 SSH 포트는 살아있고(Listen 중이고) 문제 없어 보이지만 로그인이 안될때가 있다.

보통 계정의 패스워드 만료인 경우가 많기에 예비 계정으로 접속하거나 NCP의 싱글모드 부팅, AWS의 직렬 콘솔로 GRUB단에 접속해서 패스워드 만료를 풀어야 한다.

chage -M 999999 root

위 명령어로 패스워드 유효일을 변경할 수 있고,

chage -d $(date +%Y-%m-%d) {계정명}

ex) chage -d $(date +%Y-%m-%d) root

위 명령어로 패스워드 최종 변경일을 오늘로 변경할 수 있다.

스프링부트(Spring boot) 설정을 통해 LGTM으로 트레이스, 로그 등 여러 정보를 한번에 모니터링

Daramu — Fri, 29 May 2026 11:10:42 +0900

이전 토스팅을 통해 LGTM + OTel 스택을 설치했다.

NCP(Naver Cloud Platform)에서 LGTM + Otel Collector 을 사용한 모니터링 설치 - dev :: Daramu

NCP(Naver Cloud Platform)에서 LGTM + Otel Collector 을 사용한 모니터링 설치 - dev

LGTM 스택 사용을 통한 모니터링 구축을 진행할 것이다. 본 포스팅은 각 컴포넌트를 간소화 하여 설치한 버전을 할 것이며, Prod용을 원한다면 해당 포스팅 참고 바란다. LGTM은 Loki, Grafana, Tempo, Mimir

daramu.tistory.com

이제는 스프링 부트에서 마무리 설정을 통해 앱 로그까지 보내볼 것인데,

설치 단계에서 함께 했다면 "opentelemetry-operator" 가 설치되어 있을 것이므로 코드 수정 없이 간단하게 로그를 수집할 수있다.

오퍼레이터는 java agent를 자동으로 주입해 주지만, 트리거가 필요하다.

순서는 operator 설치 → Instrumentation 리소스 생성 → 앱 Pod에 annotation 추가 이며, 이때 annotation 추가를 트리거로 agent를 자동으로 주입해준다.(init container 로 주입해준다.)

그럼 default namespace에 있는 spring boot 어플리케이션에 자동으로 주입되는지 바로 테스트를 진행하겠다.

# instrumentation.yaml
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: otel-instrumentation
  namespace: default
spec:
  exporter:
    endpoint: http://otel-daemonset-collector.monitoring.svc:4317
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: "1.0"
  java:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:latest
    env:
      - name: OTEL_EXPORTER_OTLP_PROTOCOL
        value: grpc

kubectl apply -f instrumentation.yaml

그리고 deployment에 annotation을 추가해준다.

kubectl patch deployment <앱이름> -n default -p '{
  "spec": {
    "template": {
      "metadata": {
        "annotations": {
          "instrumentation.opentelemetry.io/inject-java": "otel-instrumentation"
        }
      }
    }
  }
}'

앱 이름이 "cicd-demo-backend" 라면 <앱이름> 대신 그것을 집어 넣으면 된다.

그럼 deployment에 이렇게 추가된다.

물론 직접 spec.template.metadata.annotations.instrumentation.opentelemetry.io/inject-java: otel-instrumentation 을 넣어도 상관없다. 오히려 이게 더 좋아보이나, 현재 CI/CD 구조가 여러개를 테스트 중에 꼬여있어서 수정 전 kubectl로 임시 테스트 해보겠다.

참고로 namepsace에 따라 Instrumentation 와 deployment에 주입되는 값은 달라져야 한다.

가령 backend네임스페이스에 배포 했다면, Instrumentation의 namespace: Instrumentation이고,

deployment의 annotation은 backend/otel-instrumentation 이다.

그럼 화면처럼 Explore -> Tempo에서 트레이스를 확인할 수 있다.

현재는 간단한 스프링부트앱이라 / GET 요청밖에 없지만 복잡한 API나 DB연결이 있다면 해당 정보까지 한번에 볼 수 있다.

그런데 트레이스만 보는 것이 아닌, 해당 트레이스에 연계된 로그까지 볼 수 있는 방법이 있다.

이전 otel operator으로 트레이스는 자동으로 수집했지만,

트레이스와 연계하기 위해서 로그에 Logback이 JSON 형식으로 로그를 출력해야한다. 이 설정을 진행할 것이다.

스프링부트 버전에 따라 다른데, 만약 사용하는 스프링 부트 버전이 3.4 이상이라면 별도의 설정 없이 application.yaml을 수정하여 로그 설정을 진행하면 된다.

스프링 부트 3.4이후부터는 structured logging이 내장되어 있기에 그냥 로그 설정만 하면 된다.

#application.yaml
logging:
  structured:
    format:
      console: ecs

그럼 이제 어플리케이션이 올라올때 "kubectl get pod" 로 pod 네임 확인 후 "kubectl logs {pod_name}" 을 입력하면 아래처럼 span_id와 trace_id정상적으로 달고 나오는걸 알 수 있다.

참고로 Trace_id 는 시작부터 끝까지 동작하는 모든 작업의 관리 단위이다.

가령 누군가의 요청으로 스프링 부트가Controller 에서 요청을 받고 DB를 조회한다면, 이 일련의 모든 작업에는 동일한 Trace_id 가 있는거다.

그리고 span_id는 각 작업마다 붙는 식별자로, Controller에 요청을 보내는 span_id 한개, DB를 조회하는 다른 span_id한개 이런식으로 구성되며, 결과적으로 span_id는 trace_id의 하위에 존재하게 된다.

설정이 되었다면 다시 Grafana로 돌아가서 Tempo나 Loki로 들어간다. TraceID 기준이라 상관 없다.

그리고 Search에서 원하는 트래픽의 Trace ID를 누르면 트레이스를 확인할 수 있다. 단순 GET 요청이라 한개의 span밖에 없지만, 만약 여러개의 복잡한 span으로 이루어진 trace라면 그렇게 뜰 것이다.

그리고 오른쪽에 Logs for this span을 누른다면, Loki에서 바로 로그를 확인할 수 있다.

위의 로그는 GET요청밖에 없기에 모니터링 테스트를 위해 임의로 LoggerFactory로 생성한 콘솔 로그다.

이처럼 트레이스, 로그, 매트릭 여러 종류의 로그를 한번에 볼 수 있는 LGTM + OTEL 스택을 마무리 하겠다.

NCP(Naver Cloud Platform)에서 LGTM + Otel Collector 을 사용한 모니터링 설치 - prod용

Daramu — Thu, 28 May 2026 16:06:23 +0900

LGTM 스택 사용을 통한 모니터링 구축을 진행할 것이다.

본 포스팅은 각 컴포넌트를 권장사양으로 설치한 버전을 할 것이며, Dev용을 원한다면 해당 포스팅 참고 바란다.

NCP(Naver Cloud Platform)에서 LGTM + Otel Collector 을 사용한 모니터링 설치 - dev :: Daramu

NCP(Naver Cloud Platform)에서 LGTM + Otel Collector 을 사용한 모니터링 설치 - dev

daramu.tistory.com

LGTM은 Loki, Grafana, Tempo, Mimir 로, 각각 logs, 시각화(UI), trace, temric 을 담당한다.

가령 앱/서비스 가 있다고 한다면, 각 앱에 OTLP(Open Telemetry Protocol)을 보내도록 설정을 진행하고, OTC(OpenTelemetry Collector 설정을 통해 OTLP 입력을 받는다.

그리고 입력 받은 모든 데이터를 각각의 백엔드(Loki, Temp, Mimir)로 보내 데이터를 보관 및 처리하며, 결과적으로 Grafana를 통해 시각화를 제공한다.

도식화를 하면 아래와 같이 구성된다.

앱/서비스
  └─ OTLP (gRPC:4317 / HTTP:4318)
       └─ OTel Collector (DaemonSet) ──► Loki   (logs)
                                    ──► Tempo  (traces)
                                    ──► Mimir  (metrics)
                                         └─ Grafana (시각화)

그림으로 보면 아래와 같다.

출처: Grafana Labs 공식 페이지

백엔드가 Spring boot라고 했을때, OTLP 프로토콜을 사용하여 서버를 실행할때 JAR 파일만 주입하여 사용하는 방식을 주로 사용한다. 이 JAR파일을 통해 Spring boot내부의 모든 라이브러리(Web, JPA, Logback..etc..)를 자동으로 감지하여 트레이스, 메트릭, 로그를 OTLP로 수집한다.

여기에 쿠버네티스라면 OpenTelemetry Opertor(오텔 오퍼레이터)는 쿠버네티스 환경에서 Otel Collector를 자동으로 띄워 애플리케이션 코드를 건드리지 않고, Otel SDK를 Pod에 자동 주입하는 쿠버네티스 전용 자동화 관리 도구이며, 이것을 사용할 것이다.

그림에서 보이듯이, 총 6개의 Helm을 기본으로 설치해야한다.

Mimir, Loki, Tempo, Grafana, Otel Operator(Pod 자동 수집), Otel Collector(노드 수집) 이다.

거기에 내부 HTTPS 통신을 위한 cert-manager 까지 더해져 총 7개의 helm chat 설치가 필요하다.

오텔 오퍼레이터는 웹훅 통신시에 내부 HTTPS 인증서가 필수이기에 cert-manager는 피하기 어렵다.

cert-manager에 대한 내용이 궁금하면 이전 포스팅 참고바란다.

Cert Manager 란 무엇인가? :: Daramu

Cert Manager 란 무엇인가?

HTTPS 통신을 위해서는 SSL/TLS 인증서 관리가 필요하다.만료일을 깜빡하면 HTTPS 통신이 안되어 서비스가 마비되는 대참사가 간혹 나오고 있는데, 쿠버네티스에서는 cert-manager를 사용하여 이 같은

daramu.tistory.com

Grafana 공식 재단에서 grafana/lgtm-distributed 같은 통합 차트를 쓰면 하나의 명령어로 LGTM 컴포넌트를 한번에 띄울 수 있다. 하지만 이 방식을 사용하면 각기 다른 설정을 할때 어려움이 있으므로, 본 포스팅에서는 각각 설치하여 설정하는 것을 목표로 하겠다.

이제 설치 단계에 진입하겠다.

#helm 레포 등록
helm repo add grafana https://grafana.github.io/helm-charts
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo add jetstack https://charts.jetstack.io
helm repo update

#Namespace 생성
kubectl create namespace monitoring

Otel Operator의 Webhook 연결시 TLS인증서가 필수이기에 cert-manager또한 설치한다.

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

이제 다음 단계로 오브젝트 스토리지 접근을 위한 Secert을 생성한다.

각 로그는 OBJ에 저장될 것이므로, AWS라면 S3 연결을 위한 설정을 진행한다고 생각하면 된다.

본 포스팅은 NCP(Naver Cloud Platform)을 사용했다.

kubectl create secret generic ncp-objstore-secret -n monitoring \
  --from-literal=ACCESS_KEY_ID=<실제값> \
  --from-literal=SECRET_ACCESS_KEY=<실제값>

이제 매트릭을 담당할 Mimir를 설치한다.

이 중 key 부분은 secret으로 만들었으나, bucket_name은 실제 object storage 이름으로 맞춘다. endpoint의 경우 민간 수도권은 아래 예시와 같으며, 공공플랫폼일 경우 "kr.object.gov-ncloudstorage.com " 이다.

추가로 ncp nks의 경우, 쿠버네티스 내부 DNS로 coredns를 사용하고 있다.
"kubectl get service -n kube-system" 을 입력할 경우 아래 처럼 coredns라는 서비스를 볼 수 있다.

mimir는 최초 동작시 DNS에 질의를 해야하는데, 기본값으로 두면 kube-dns라는 과거 서비스를 바라보고 있기에 mimir gateway가 작동하지 않을 수 있다. global 설정에서 dns설정에 dnsservice와 namespace, clusterdomain을 넣어둔다. 아래 예시는 ncp의 nks기준이다.

#mimir-values.yaml
mimir:
  structuredConfig:
    common:
      storage:
        backend: s3
        s3:
          endpoint: kr.object.ncloudstorage.com
          region: kr-standard
          access_key_id: "${ACCESS_KEY_ID}"
          secret_access_key: "${SECRET_ACCESS_KEY}"
          insecure: false

    blocks_storage:
      s3:
        bucket_name: mimir-blocks

    alertmanager_storage:
      s3:
        bucket_name: mimir-alertmanager

    ruler_storage:
      s3:
        bucket_name: mimir-ruler

global:
  extraEnvFrom:
    - secretRef:
        name: ncp-objstore-secret
  dnsService: "coredns"
  dnsNamespace: "kube-system"
  clusterDomain: "cluster.local"

# 소규모면 monolithic 모드 사용
# 프로덕션 규모면 distributed 권장
minio:
  enabled: false  # NCP Object Storage 사용하므로 비활성화

ingester:
  replicas: 2
  zoneAwareReplication:
    enabled: false

store_gateway:
  replicas: 1

compactor:
  replicas: 1
  
gateway:
  enabled: true
  nginx:
    config:
      enableIPv6: false

helm install mimir grafana/mimir-distributed \
  --namespace monitoring \
  -f mimir-values.yaml

참고로 생성시 pod가 많이 죽을 수 있다. mimir는 내부적으로 kafka를 사용하는데, kafka pod가 뜨기 전에 다른 pod가 kafka를 사용하지 못해 Error 가 나는 것이다. kafka가 running 1/1로 바뀐 후 시간이 지나면 pod재시작으로 running으로 바뀐다.

다음으로 Log를 담당할 Loki를 설치한다.

동일하게 object storage 생성 후 만들어준다.

deploymentMode: SimpleScalable

loki:
  auth_enabled: false
  storage:
    type: s3
    bucketNames:
      chunks: loki-chunks
      chunks_cache: loki-chunks
      admin: loki-chunks
      ruler: loki-chunks
    s3:
      endpoint: https://kr.object.ncloudstorage.com
      region: kr-standard
      s3ForcePathStyle: true
      accessKeyId: ${ACCESS_KEY_ID}
      secretAccessKey: ${SECRET_ACCESS_KEY}

  schemaConfig:
    configs:
      - from: "2024-01-01"
        store: tsdb
        object_store: s3
        schema: v13
        index:
          prefix: loki_index_
          period: 24h

  limits_config:
    allow_structured_metadata: true
    otlp_config:
      resource_attributes:
        attributes_config:
          - action: index_label
            attributes:
              - k8s.namespace.name
              - k8s.pod.name
              - service.name

backend:
  replicas: 2
  persistence:
    storageClass: nks-block-storage

read:
  replicas: 2

write:
  replicas: 2

minio:
  enabled: false

gateway:
  enabled: true
  nginxConfig:
    enableIPv6: false

global:
  dnsService: "coredns"
  dnsNamespace: "kube-system"
  clusterDomain: "cluster.local"

helm install loki grafana/loki \
  --namespace monitoring \
  -f loki-values.yaml

다음으로 trace를 담당할 Tempo를 설치한다.

왜인지 key값의 시크릿을 참조 못하는 경우가 있는데, 그때는 하드코딩해서 집어넣어야한다.

#tempo-values.yaml
storage:
  trace:
    backend: s3
    s3:
      bucket: tempo-traces
      endpoint: kr.object.ncloudstorage.com
      region: kr-standard
      access_key: ${ACCESS_KEY_ID}
      secret_key: ${SECRET_ACCESS_KEY}
      forcepathstyle: true

tempo:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
        http:
          endpoint: 0.0.0.0:4318

  storage:
    trace:
      wal:
        path: /var/tempo/wal
      local:
        path: /var/tempo/blocks

  metricsGenerator:
    enabled: true
    remoteWriteUrl: "http://mimir-nginx.monitoring.svc:80/api/v1/push"

persistence:
  enabled: true
  storageClassName: nks-block-storage
  size: 10Gi

traces:
  otlp:
    grpc:
      enabled: true
    http:
      enabled: true

helm install tempo grafana/tempo-distributed \
  --namespace monitoring \
  -f tempo-values.yaml

다음으로 시각화를 담당할 Grafana를 설치한다.

VPN 환경이기에 annotations에서 private을 선언했다. 공인IP가 필요하면 해당 annotations를 삭제하면 된다.

#grafana-values.yaml
adminPassword: "your-secure-password"

persistence:
  enabled: true
  storageClassName: nks-block-storage
  size: 10Gi
  
service:
  type: NodePort

ingress:
  enabled: true
  ingressClassName: alb
  annotations:
    alb.ingress.kubernetes.io/network-type: "private"
  hosts:
    - grafana.yourdomain.com # 도메인으로 수정

datasources:
  datasources.yaml:
    apiVersion: 1
    datasources:
      - name: Mimir
        type: prometheus
        url: http://mimir-gateway.monitoring.svc:80/prometheus
        isDefault: true
        jsonData:
          httpMethod: POST
          httpHeaderName1: "X-Scope-OrgID"
          prometheusType: Mimir
        secureJsonData:
          httpHeaderValue1: "anonymous"

      - name: Loki
        type: loki
        url: http://loki-gateway.monitoring.svc:80
        jsonData:
          derivedFields:
            - datasourceUid: Tempo
              matcherType: label
              matcherRegex: trace_id
              name: TraceID
              url: "${__value.raw}"
              urlDisplayLabel: "View in Tempo"

      - name: Tempo
        type: tempo
        uid: Tempo
        url: http://tempo.monitoring.svc:3200
        jsonData:
          tracesToLogsV2:
            datasourceUid: Loki
            spanStartTimeShift: "-1m"
            spanEndTimeShift: "1m"
            filterByTraceID: true
            filterBySpanID: false
            customQuery: false
          tracesToMetrics:
            datasourceUid: Mimir
          serviceMap:
            datasourceUid: Mimir
          nodeGraph:
            enabled: true

helm install grafana grafana/grafana \
  --namespace monitoring \
  -f grafana-values.yaml

ingress(LB)생성 후 hosts 부분 수정하여 접속해보는것도 좋다.

다음으로 어플리케이션에 SDK를 Pod에 자동 주입하여 Pod의 정보를 가져오는 오텔 오퍼레이터를 설치한다.

"admissionWebhooks.certManager.enabled=true" 옵션을 통해 오텔 오퍼레이터가 가동으로 cert-manager를 통해 Issuer와 Certificate를 생성하여 Secret를 생성 및 주입한다.

helm install opentelemetry-operator open-telemetry/opentelemetry-operator \
  --namespace monitoring \
  --set "manager.collectorImage.repository=otel/opentelemetry-collector-contrib" \
  --set admissionWebhooks.certManager.enabled=true

마지막으로 노트별 로그를 수집하며 중앙 집계 및 처리를 진행할 오텔 콜렉터를 설치한다.

kubectl create serviceaccount otel-collector-sa -n monitoring

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  name: otel-collector-sa
  namespace: monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: otel-collector-role
rules:
  - apiGroups: [""]
    resources: ["nodes/stats", "nodes/proxy", "pods", "namespaces", "nodes"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["replicasets"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: otel-collector-rolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: otel-collector-role
subjects:
  - kind: ServiceAccount
    name: otel-collector-sa
    namespace: monitoring
EOF

#otelcol-daemonset.yaml
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: otel-daemonset
  namespace: monitoring
spec:
  mode: daemonset
  serviceAccount: otel-collector-sa
  config:
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
      kubeletstats:
        collection_interval: 30s
        auth_type: serviceAccount
        endpoint: "https://${env:K8S_NODE_IP}:10250"
        insecure_skip_verify: true
      filelog:
        include:
          - /var/log/pods/*/*/*.log
        include_file_path: true
        operators:
          - type: container
            id: container-parser

    processors:
      batch:
        timeout: 5s
        send_batch_size: 10000
      k8sattributes:
        passthrough: false
        extract:
          metadata:
            - k8s.pod.name
            - k8s.namespace.name
            - k8s.deployment.name
            - k8s.node.name
            - service.name
      resourcedetection:
        detectors: [env, k8snode]
        timeout: 5s
      memory_limiter:
        check_interval: 1s
        limit_mib: 400
        spike_limit_mib: 100

    exporters:
      otlphttp/loki:
        endpoint: http://loki-gateway.monitoring.svc:80/otlp
      otlp/tempo:
        endpoint: tempo.monitoring.svc:4317
        tls:
          insecure: true
      prometheusremotewrite/mimir:
        endpoint: http://mimir-gateway.monitoring.svc:80/api/v1/push
        headers:
          X-Scope-OrgID: anonymous
 
    service:
      pipelines:
        logs:
          receivers: [otlp, filelog]
          processors: [memory_limiter, k8sattributes, batch]
          exporters: [otlphttp/loki]
        traces:
          receivers: [otlp]
          processors: [memory_limiter, k8sattributes, batch]
          exporters: [otlp/tempo, spanmetrics]
        metrics:
          receivers: [otlp, kubeletstats, spanmetrics] 
          processors: [memory_limiter, k8sattributes, resourcedetection, batch]
          exporters: [prometheusremotewrite/mimir]

  volumeMounts:
    - name: varlogpods
      mountPath: /var/log/pods
      readOnly: true

  volumes:
    - name: varlogpods
      hostPath:
        path: /var/log/pods

  env:
    - name: K8S_NODE_IP
      valueFrom:
        fieldRef:
          fieldPath: status.hostIP

kubectl apply -f otelcol-daemonset.yaml

정상적으로 설치가 끝났다면 "kubectl get pod -n monitoring" 시에 pending이나 Error가 없이 여러개의 Pod가 떠있을 것이다.

모두 runnging 중이라면 Grafana 웹사이트에 접속하여 UI에서 실제 연결을 확인해 본다.

Grafana 좌측 사이드바 -> Commections -> Data sources

이곳에서 Loki, Mimir, Tempo를 모두 들어가 가장 하단에 "Test"를 통해 Connection 을 확인해준다.

세개 모두 성공했다면 설치는 끝이다.

NCP(Naver Cloud Platform)에서 LGTM + Otel Collector 을 사용한 모니터링 설치 - dev

Daramu — Thu, 28 May 2026 16:06:09 +0900

LGTM 스택 사용을 통한 모니터링 구축을 진행할 것이다.

본 포스팅은 각 컴포넌트를 간소화 하여 설치한 버전을 할 것이며, Prod용을 원한다면 해당 포스팅 참고 바란다.

NCP(Naver Cloud Platform)에서 LGTM + Otel Collector 을 사용한 모니터링 설치 - prod용 :: Daramu

LGTM은 Loki, Grafana, Tempo, Mimir 로, 각각 logs, 시각화(UI), trace, temric 을 담당한다.

가령 앱/서비스 가 있다고 한다면, 각 앱에 OTLP(Open Telemetry Protocol)을 보내도록 설정을 진행하고, OTC(OpenTelemetry Collector 설정을 통해 OTLP 입력을 받는다.

그리고 입력 받은 모든 데이터를 각각의 백엔드(Loki, Temp, Mimir)로 보내 데이터를 보관 및 처리하며, 결과적으로 Grafana를 통해 시각화를 제공한다.

도식화를 하면 아래와 같이 구성된다.

그림으로 보면 아래와 같다.

출처: Grafana Labs 공식 페이지

그림에서 보이듯이, 총 6개의 Helm을 기본으로 설치해야한다.

Mimir, Loki, Tempo, Grafana, Otel Operator(Pod 자동 수집), Otel Collector(노드 수집) 이다.

거기에 내부 HTTPS 통신을 위한 cert-manager 까지 더해져 총 7개의 helm chat 설치가 필요하다.

오텔 오퍼레이터는 웹훅 통신시에 내부 HTTPS 인증서가 필수이기에 cert-manager는 피하기 어렵다.

cert-manager에 대한 내용이 궁금하면 이전 포스팅 참고바란다.

Cert Manager 란 무엇인가? :: Daramu

Cert Manager 란 무엇인가?

daramu.tistory.com

이제 설치 단계에 진입하겠다.

#helm 레포 등록
helm repo add grafana https://grafana.github.io/helm-charts
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo add jetstack https://charts.jetstack.io
helm repo update

#Namespace 생성
kubectl create namespace monitoring

Otel Operator의 Webhook 연결시 TLS인증서가 필수이기에 cert-manager또한 설치한다.

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

이제 다음 단계로 오브젝트 스토리지 접근을 위한 Secert을 생성한다.

각 로그는 OBJ에 저장될 것이므로, AWS라면 S3 연결을 위한 설정을 진행한다고 생각하면 된다.

본 포스팅은 NCP(Naver Cloud Platform)을 사용했다.

kubectl create secret generic ncp-objstore-secret \
  --namespace monitoring \
  --from-literal=access_key_id=<NCP_ACCESS_KEY> \
  --from-literal=secret_access_key=<NCP_SECRET_KEY>

이제 매트릭을 담당할 Mimir를 설치한다.

mimir:
  structuredConfig:
    common:
      storage:
        backend: s3
        s3:
          endpoint: kr.object.gov-ncloudstorage.com
          region: kr-standard
          access_key_id: "${ACCESS_KEY_ID}"
          secret_access_key: "${SECRET_ACCESS_KEY}"
          insecure: false
    blocks_storage:
      s3:
        bucket_name: mimir-blocks-monitoring
    alertmanager_storage:
      s3:
        bucket_name: mimir-alertmanager-monitoring
    ruler_storage:
      s3:
        bucket_name: mimir-ruler-monitoring

global:
  extraEnvFrom:
    - secretRef:
        name: ncp-objstore-secret
  dnsService: "coredns"
  dnsNamespace: "kube-system"
  clusterDomain: "cluster.local"

minio:
  enabled: false

ingester:
  replicas: 1
  zoneAwareReplication:
    enabled: false
  resources:
    requests:
      cpu: "100m"
      memory: "512Mi"
    limits:
      cpu: "500m"
      memory: "1Gi"

store_gateway:
  replicas: 1
  zoneAwareReplication:
    enabled: false
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

compactor:
  replicas: 1
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

distributor:
  replicas: 1
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

querier:
  replicas: 1
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

query_frontend:
  replicas: 1
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

ruler:
  replicas: 1
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "256Mi"

alertmanager:
  replicas: 1
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "256Mi"

gateway:
  enabled: true
  nginx:
    config:
      enableIPv6: false
  resources:
    requests:
      cpu: "50m"
      memory: "64Mi"
    limits:
      cpu: "200m"
      memory: "256Mi"

helm install mimir grafana/mimir-distributed \
  --namespace monitoring \
  -f mimir-values.yaml

다음으로 Log를 담당할 Loki를 설치한다.

동일하게 object storage 생성 후 만들어준다.

deploymentMode: SingleBinary

loki:
  auth_enabled: false
  storage:
    type: s3
    bucketNames:
      chunks: loki-chunks
      admin: loki-chunks
      ruler: loki-chunks
    s3:
      endpoint: https://kr.object.ncloudstorage.com
      region: kr-standard
      s3ForcePathStyle: true
      accessKeyId: ${ACCESS_KEY_ID}
      secretAccessKey: ${SECRET_ACCESS_KEY}
  schemaConfig:
    configs:
      - from: "2024-01-01"
        store: tsdb
        object_store: s3
        schema: v13
        index:
          prefix: loki_index_
          period: 24h
  limits_config:
    allow_structured_metadata: true
    otlp_config:
      resource_attributes:
        attributes_config:
          - action: index_label
            attributes:
              - k8s.namespace.name
              - k8s.pod.name
              - service.name

singleBinary:
  replicas: 1
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "1Gi"
  persistence:
    storageClass: nks-block-storage

backend:
  replicas: 0
read:
  replicas: 0
write:
  replicas: 0

minio:
  enabled: false
  
chunksCache:
  enabled: false

resultsCache:
  enabled: false

gateway:
  enabled: true
  replicas: 1
  nginxConfig:
    enableIPv6: false

global:
  dnsService: "coredns"
  dnsNamespace: "kube-system"
  clusterDomain: "cluster.local"

helm install loki grafana/loki \
  --namespace monitoring \
  -f loki-values.yaml

다음으로 trace를 담당할 Tempo를 설치한다.

동일하게 object storage 생성 후 만들어준다.

왜인지 key값의 시크릿을 참조 못하는 경우가 있는데, 그때는 하드코딩해서 집어넣어야한다.

# tempo-values.yaml (monolithic)
extraEnvFrom:
  - secretRef:
      name: ncp-objstore-secret

tempo:
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "1Gi"

  storage:
    trace:
      backend: s3
      s3:
        bucket: tempo-traces
        endpoint: kr.object.ncloudstorage.com
        region: kr-standard
        access_key: ${ACCESS_KEY_ID}
        secret_key: ${SECRET_ACCESS_KEY}
        forcepathstyle: true
      wal:
        path: /var/tempo/wal
      local:
        path: /var/tempo/blocks

  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
        http:
          endpoint: 0.0.0.0:4318

  metricsGenerator:
    enabled: true
    remoteWriteUrl: "http://mimir-gateway.monitoring.svc:80/api/v1/push"

persistence:
  enabled: true
  storageClassName: nks-block-storage
  size: 10Gi

helm install tempo grafana/tempo \
  --namespace monitoring \
  -f tempo-values.yaml

다음으로 시각화를 담당할 Grafana를 설치한다.

VPN 환경이기에 annotations에서 private을 선언했다. 공인IP가 필요하면 해당 annotations를 삭제하면 된다.

adminPassword: "your-secure-password"

persistence:
  enabled: true
  storageClassName: nks-block-storage
  size: 10Gi

resources:
  requests:
    cpu: "100m"
    memory: "256Mi"
  limits:
    cpu: "500m"
    memory: "512Mi"

service:
  type: NodePort

ingress:
  enabled: true
  annotations:
    alb.ingress.kubernetes.io/network-type: "private"
  ingressClassName: alb
  hosts:
    - grafana.yourdomain.com

datasources:
  datasources.yaml:
    apiVersion: 1
    datasources:
      - name: Mimir
        type: prometheus
        url: http://mimir-gateway.monitoring.svc:80/prometheus
        isDefault: true
        jsonData:
          httpMethod: POST
          httpHeaderName1: "X-Scope-OrgID"
          prometheusType: Mimir
        secureJsonData:
          httpHeaderValue1: "anonymous"


      - name: Loki
        type: loki
        url: http://loki-gateway.monitoring.svc:80
        jsonData:
          derivedFields:
            - datasourceUid: Tempo
              matcherType: label
              matcherRegex: trace_id
              name: TraceID
              url: "${__value.raw}"
              urlDisplayLabel: "View in Tempo"

      - name: Tempo
        type: tempo
        uid: Tempo
        url: http://tempo.monitoring.svc:3200
        jsonData:
          tracesToLogsV2:
            datasourceUid: Loki
            spanStartTimeShift: "-1m"
            spanEndTimeShift: "1m"
            filterByTraceID: true
            filterBySpanID: false
            customQuery: false
          tracesToMetrics:
            datasourceUid: Mimir
          serviceMap:
            datasourceUid: Mimir
          nodeGraph:
            enabled: true

helm install grafana grafana/grafana \
  --namespace monitoring \
  -f grafana-values.yaml

ingress(LB)생성 후 hosts 부분 수정하여 접속해보는것도 좋다.

다음으로 어플리케이션에 SDK를 Pod에 자동 주입하여 Pod의 정보를 가져오는 오텔 오퍼레이터를 설치한다.

"admissionWebhooks.certManager.enabled=true" 옵션을 통해 오텔 오퍼레이터가 가동으로 cert-manager를 통해 Issuer와 Certificate를 생성하여 Secret를 생성 및 주입한다.

helm install opentelemetry-operator open-telemetry/opentelemetry-operator \
  --namespace monitoring \
  --set "manager.collectorImage.repository=otel/opentelemetry-collector-contrib" \
  --set admissionWebhooks.certManager.enabled=true

마지막으로 노트별 로그를 수집하며 중앙 집계 및 처리를 진행할 오텔 콜렉터를 설치한다.

kubectl create serviceaccount otel-collector-sa -n monitoring

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  name: otel-collector-sa
  namespace: monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: otel-collector-role
rules:
  - apiGroups: [""]
    resources: ["nodes/stats", "nodes/proxy", "pods", "namespaces", "nodes"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["replicasets"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: otel-collector-rolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: otel-collector-role
subjects:
  - kind: ServiceAccount
    name: otel-collector-sa
    namespace: monitoring
EOF

##otelcol-daemonset.yaml
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: otel-daemonset
  namespace: monitoring
spec:
  mode: daemonset
  serviceAccount: otel-collector-sa
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "500m"
      memory: "400Mi"
  config:
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
      kubeletstats:
        collection_interval: 30s
        auth_type: serviceAccount
        endpoint: "https://${env:K8S_NODE_IP}:10250"
        insecure_skip_verify: true
      filelog:
        include:
          - /var/log/pods/*/*/*.log
        include_file_path: true
        operators:
          - type: container
            id: container-parser

    processors:
      batch:
        timeout: 5s
        send_batch_size: 10000
      k8sattributes:
        passthrough: false
        extract:
          metadata:
            - k8s.pod.name
            - k8s.namespace.name
            - k8s.deployment.name
            - k8s.node.name
            - service.name
      resourcedetection:
        detectors: [env, k8snode]
        timeout: 5s
      memory_limiter:
        check_interval: 1s
        limit_mib: 400
        spike_limit_mib: 100

    connectors:
      spanmetrics:
        namespace: traces
        histogram:
          explicit:
            buckets: [5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s]
        dimensions:
          - name: http.method
          - name: http.status_code

    exporters:
      otlphttp/loki:
        endpoint: http://loki-gateway.monitoring.svc:80/otlp
      otlp/tempo:
        endpoint: tempo.monitoring.svc:4317
        tls:
          insecure: true
      prometheusremotewrite/mimir:
        endpoint: http://mimir-gateway.monitoring.svc:80/api/v1/push
        headers:
          X-Scope-OrgID: anonymous

    service:
      pipelines:
        logs:
          receivers: [otlp, filelog]
          processors: [memory_limiter, k8sattributes, batch]
          exporters: [otlphttp/loki]
        traces:
          receivers: [otlp]
          processors: [memory_limiter, k8sattributes, batch]
          exporters: [otlp/tempo, spanmetrics]
        metrics:
          receivers: [otlp, kubeletstats, spanmetrics] 
          processors: [memory_limiter, k8sattributes, resourcedetection, batch]
          exporters: [prometheusremotewrite/mimir]

  volumeMounts:
    - name: varlogpods
      mountPath: /var/log/pods
      readOnly: true

  volumes:
    - name: varlogpods
      hostPath:
        path: /var/log/pods

  env:
    - name: K8S_NODE_IP
      valueFrom:
        fieldRef:
          fieldPath: status.hostIP

kubectl apply -f otelcol-daemonset.yaml

정상적으로 설치가 끝났다면 "kubectl get pod -n monitoring" 시에 pending이나 Error가 없이 여러개의 Pod가 떠있을 것이다.

모두 runnging 중이라면 Grafana 웹사이트에 접속하여 UI에서 실제 연결을 확인해 본다.

Grafana 좌측 사이드바 -> Commections -> Data sources

이곳에서 Loki, Mimir, Tempo를 모두 들어가 가장 하단에 "Test"를 통해 Connection 을 확인해준다.

세개 모두 성공했다면 설치는 끝이다.

Cert Manager 란 무엇인가?

Daramu — Thu, 28 May 2026 10:47:00 +0900

HTTPS 통신을 위해서는 SSL/TLS 인증서 관리가 필요하다.

만료일을 깜빡하면 HTTPS 통신이 안되어 서비스가 마비되는 대참사가 간혹 나오고 있는데, 쿠버네티스에서는 cert-manager를 사용하여 이 같은 상황을 막는 것이 거의 표준으로 자리 잡고 있다.

위 그림은 cert-manager가 인증서를 발급하고 관리하는 전체적인 흐름이다.

크게 4가지 컴포넌트로 구성된다.

1. Issures(Cluster Issures): 인증서를 실제로 발급해주는 인증기관(CA)에 대한 정보이다. Let's Encrypt, Hashicorp Valut, 혹은 자체 생성한 CA등이 여기에 해당한다. Cluster가 붙는 것은 클러스 전체 공유 가능한 인증서이다.

2. cert-manager: 모든 과정을 컨트롤 하는 컨틀롤러(Controller)이다. 리소스를 감시하며 인증서를 자동으로 발급/갱신한다.

3. Certificates: 어떤 도메인(ex. foo.bar.com)에 대해 어떤 Issuer를 사용해 인증서를 만들 것인지에 대한 명세서이다.

4. Kubernetes Secret: cert-manager가 최종 발급 받은 개인키(Private Key)와 인증서(signed keypair)를 저장하는 공간이다. Ingress나 Application은 이 Secret을 마운트 하여 HTTPS 통신을 가능하게 한다.

내부용 HTTPS vs 외부용 HTTPS

인증서를 발급할 때, 서비스가 클러스터 내부에서만 도메인을 쓰는지, 외부에 노출되는지에 따라 내부 설정이 달라진다.

아래는 각각의 예시이다.

예시 전: cert-manager helm 설치

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

내부용 HTTPS 인증서 발급

클러스터 내부 통신용이며, 사내 개발 환경등 내부에서만 접근이 필요할때 사용할 수 있는 구성이다.

cert-manager가 직접 자체 루트 CA(root CA)역할을 하게할 수 있다.

1. cert-manager를 통해 직접 root CA 인증서 발급: 자체서명(Self-Signed)기능을 사용하여 cert-manager가 직접 루트 CA용 인증서와 비밀키를 만들고, 그걸 internal-ca-key-pair라는 이름의 secret으로 저장하게 만든다.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned-root-issuer
spec:
  selfSigned: {}

---

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: internal-root-ca
  namespace: cert-manager
spec:
  isCA: true # 중요: 이 인증서가 다른 인증서를 발행할 수 있는 'CA' 역할을 하겠다고 선언
  commonName: "my-internal-root-ca"
  secretName: internal-ca-key-pair # 여기에 입력한 이름으로 Secret이 자동 생성
  privateKey:
    algorithm: ECDSA
    size: 256
  issuerRef:
    name: selfsigned-root-issuer
    kind: ClusterIssuer

2. clusterIssuer: 먼저 내부 사설 CA 역할을 할 Issure를 정의한다.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: internal-ca-issuer
spec:
  ca:
    # 미리 생성해둔 내부 CA의 비밀키가 담긴 Secret을 지정
    secretName: internal-ca-key-pair

3. Certificate 생성 및 Secret 자동 발급: 내부에서 사용할 내부 도메인(ex. foo.bar.com)에 대한 인증서를 요청한다.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: internal-service-cert
  namespace: default
spec:
  # 위에서 만든 내부 CA Issuer를 지정
  issuerRef:
    name: internal-ca-issuer
    kind: ClusterIssuer
  # 최종 인증서(signed keypair)가 저장될 쿠버네티스 시크릿 이름
  secretName: internal-service-tls
  dnsNames:
    - "foo.bar.com"

이제 cert-manager가 internal-ca-issuer를 통해 서명한 뒤, internal-service-tls 라는 secret을 자동으로 만들어준다.

외부 도메인 연결 인증서 발급(Let's Encrypt)

인터넷을 통해 실제 유저가 접속하는 서비스(ex. example.com)을 위한 구성이다.

글로벌 공인CA인 Let's Encrypt를 사용한다.

1. clusterIssuer: Let's Encrypt와 통신하여 도메인 유효성을 체크하는 Issuer을 생성한다.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    # Let's Encrypt 프로덕션 서버 주소
    server: https://acme-v02.api.letsencrypt.org/directory
    email: devops-team@example.com  # 만료 알림 등을 받을 이메일
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
    - http01:
        ingress:
          class: nginx  # 클러스터에서 사용 중인 Ingress Controller 지정

2. Certifacate 생성: 외부용 인증서는 Certificate 리소스를 따로 열어도 되지만, 사실 대부분 Ingress설정에 어노테이션을 설정하여 관리하는 것이 대부분의 사례이다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: wwww-service-ingress
  namespace: default
  annotations:
    # 이 어노테이션을 보고 cert-manager가 알아서 Certificate를 생성
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    kubernetes.io/ingress.class: "nginx"
spec:
  rules:
  - host: "example.com"
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-service
            port:
              number: 80
  tls:
  - hosts:
    - "example.com"
    # cert-manager가 Let's Encrypt에서 받아온 공인 인증서를 이 시크릿에 담는다
    secretName: example-com-tls