KyungRyeol Yoon

[Kubernetes] 🔒 Gateway API로 HTTP→HTTPS 리다이렉트 (HTTPRoute RequestRedirect)

Wed, 10 Jun 2026 00:00:00 +0000

Gateway API에서 HTTP→HTTPS 리다이렉트는 Ingress의 annotation(ssl-redirect)이 아니라 **표준 필터 RequestRedirect**로 합니다. 이 글에서는 HTTP(80)·HTTPS(443) 리스너 2개 + HTTPRoute 2개로 구성하는 기본형과, 앱 팀이 sectionName을 빠뜨려도 평문 노출이 안 되도록 allowedRoutes로 80 리스너를 잠그는 실무 패턴, 그리고 “구성했는데 http가 계속 되는” 트러블슈팅을 정리합니다.

이 시리즈는 쿠버네티스 gRPC 삽질에서 출발해 HTTP/2·TLS·로드밸런서·Gateway API·인증서까지 풀어가는 기록입니다. 앞선 Ingress → Gateway API 편과 cert-manager TLS 편을 먼저 보면 이해가 빠릅니다.

🎯 핵심: RequestRedirect 필터 #

RequestRedirect는 클라이언트에 3XX 응답을 돌려줘 다른 위치로 다시 요청하게 하는 Gateway API 표준 필터입니다. HTTPRoute의 rules[].filters에 type: RequestRedirect를 선언하고, HTTP→HTTPS 업그레이드는 scheme: https + statusCode: 301이 정석입니다.

1rules:
2- filters:
3 - type: RequestRedirect
4 requestRedirect:
5 scheme: https
6 statusCode: 301

리다이렉트는 지정한 URL 요소만 바꾸고 나머지는 보존합니다. 예를 들어 GET http://redirect.example/cinnamon 요청은 다음과 같이 응답됩니다.

1HTTP/1.1 301 Moved Permanently
2location: https://redirect.example/cinnamon

scheme만 https로 바뀌고 host(redirect.example)·path(/cinnamon)는 그대로 유지됩니다.

⚠️ RequestRedirect와 URLRewrite는 한 rule 안에서 동시에 쓸 수 없습니다. RequestRedirect는 클라이언트에게 3XX로 “다시 요청해라"를 돌려주는 것이고, URLRewrite는 백엔드로 보내기 전에 요청을 조용히 바꾸는 것이라 성격이 다릅니다.

지원하는 상태 코드는? #

코드	의미	메모
301	영구 이동 (Moved Permanently)	HTTP→HTTPS 업그레이드 권장
302	임시 (Found)	`statusCode` 생략 시 기본값
303	See Other	POST→GET 패턴
307	임시 + 메서드 보존	Extended 지원
308	영구 + 메서드 보존	Extended 지원

💡 307/308과 path 단위 redirect는 “Extended” 지원이라 구현체(Contour·Istio·Envoy Gateway 등)별로 지원 여부가 다릅니다. 사용 전 conformance 문서로 확인하세요.

🧱 기본 구성: 리스너 2개 + 라우트 2개 #

HTTP→HTTPS 리다이렉트의 기본형은 Gateway에 80·443 리스너를 모두 두고, HTTPRoute를 2개(80=리다이렉트, 443=백엔드 전달) 만드는 것입니다.

1️⃣ Gateway — HTTP·HTTPS 리스너 둘 다 #

 1apiVersion: gateway.networking.k8s.io/v1
 2kind: Gateway
 3metadata:
 4 name: redirect-gateway
 5 namespace: gateway-system  # 플랫폼팀 소유
 6spec:
 7 gatewayClassName: foo-lb
 8 listeners:
 9 - name: http
10 protocol: HTTP
11 port: 80
12 - name: https
13 protocol: HTTPS
14 port: 443
15 tls:
16 mode: Terminate
17 certificateRefs:
18 - name: redirect-example  # TLS Secret (cert-manager가 발급)

2️⃣ HTTPRoute ① — 80 리스너에 붙여 리다이렉트 #

 1apiVersion: gateway.networking.k8s.io/v1
 2kind: HTTPRoute
 3metadata:
 4 name: http-filter-redirect
 5 namespace: gateway-system  # 80 리스너에 붙이려면 Gateway와 같은 네임스페이스
 6spec:
 7 parentRefs:
 8 - name: redirect-gateway
 9 sectionName: http  # http(80) 리스너만 선택
10 hostnames:
11 - redirect.example
12 rules:
13 - filters:
14 - type: RequestRedirect
15 requestRedirect:
16 scheme: https
17 statusCode: 301

3️⃣ HTTPRoute ② — 443 리스너에 붙여 백엔드로 전달 #

 1apiVersion: gateway.networking.k8s.io/v1
 2kind: HTTPRoute
 3metadata:
 4 name: https-route
 5 namespace: team-a  # 앱 팀 네임스페이스
 6 labels:
 7 gateway-access: "true" # 443 리스너 allowedRoutes selector와 매칭 (아래 참고)
 8spec:
 9 parentRefs:
10 - name: redirect-gateway
11 namespace: gateway-system  # Gateway가 다른 네임스페이스라 명시
12 sectionName: https
13 hostnames:
14 - redirect.example
15 rules:
16 - backendRefs:
17 - name: example-svc  # team-a 안의 Service
18 port: 80

💡 네임스페이스 배치 메모

Gateway + 리다이렉트 라우트 → gateway-system(플랫폼). 80 리스너가 기본 from: Same이라 리다이렉트 라우트도 같은 ns에 둬야 붙습니다.

백엔드 라우트 → team-a(앱 팀). Gateway가 다른 ns라 parentRefs.namespace를 명시하고, 443 리스너의 allowedRoutes가 이 ns를 허용해야 합니다.

backendRefs가 다른 ns의 Service를 가리키면 그쪽에 ReferenceGrant가 필요합니다. 같은 ns면 불필요.

모두 한 네임스페이스에 둘 거면 namespace 표기는 생략해도 됩니다(공식 가이드 예시 형태).

❓ 왜 라우트가 꼭 2개여야 하나? #

한 HTTPRoute의 rules는 그 라우트가 붙은 모든 리스너에 똑같이 적용되기 때문입니다. 그래서 “80=리다이렉트 / 443=백엔드 전달"을 한 라우트 안에서 나눌 수 없습니다. 역할별로 라우트를 분리해야 합니다.

리다이렉트 라우트는 게이트웨이당 1개로 충분합니다 #

리다이렉트 라우트에서 hostnames를 생략하면 그 80 리스너로 들어오는 모든 호스트에 적용됩니다. 따라서 앱이 여러 개여도 리다이렉트 라우트는 하나면 되고, 나머지는 각 앱의 443 백엔드 라우트만 추가하면 됩니다(어차피 만들 것).

`sectionName: https`만 박으면 404, 리다이렉트가 아닙니다 #

앱 라우트를 443에만 고정하면 80으로 온 요청은 매칭되는 라우트가 없어 404가 납니다(리다이렉트 ❌). 브라우저로 테스트했을 때 https로 넘어갔다면 그건 브라우저의 https-first 동작일 뿐, 게이트웨이가 리다이렉트한 게 아닙니다. curl·모바일 앱 등 http 클라이언트를 부드럽게 https로 보내려면 리다이렉트 라우트는 여전히 필요합니다.

🛡️ allowedRoutes로 평문 노출 원천 차단 #

앱 팀이 sectionName을 빠뜨리면 그 라우트가 80 리스너에도 바인딩돼 평문(HTTP)으로 서빙될 수 있습니다. 개별 라우트의 “예의"에 기대지 말고, 80 리스너를 플랫폼 전용으로 잠가서 막는 것이 안전합니다.

sectionName이 없으면 라우트는 호환되는 모든 리스너(80 포함)에 바인딩됩니다. 그러면 80에서 백엔드 라우트가 리다이렉트 라우트보다 더 구체적으로 매칭되어 평문 서빙이 일어날 수 있습니다. allowedRoutes로 다음처럼 잠급니다.

 1spec:
 2 listeners:
 3 - name: http
 4 port: 80
 5 protocol: HTTP
 6 allowedRoutes:
 7 namespaces:
 8 from: Same  # 게이트웨이 네임스페이스(=플랫폼 리다이렉트 라우트)만 허용
 9 - name: https
10 port: 443
11 protocol: HTTPS
12 tls:
13 mode: Terminate
14 certificateRefs:
15 - name: redirect-example
16 allowedRoutes:
17 namespaces:
18 from: Selector  # 앱 팀 라우트는 여기에만
19 selector:
20 matchLabels:
21 gateway-access: "true"

이렇게 하면 앱 팀이 sectionName을 빠뜨려도 그 라우트는 80에서는 거부되고 443에만 붙습니다. 80은 플랫폼 리다이렉트 라우트가 독점하므로 평문 노출이 원천 차단됩니다.

🔧 트러블슈팅: 구성했는데 http가 계속 될 때 #

순서대로 확인합니다.

1️⃣ 리다이렉트 라우트가 80에 진짜 붙었나?

1kubectl describe httproute http-filter-redirect -n gateway-system

status.parents[].conditions에서 Accepted: True인지 확인합니다. 안 붙는 흔한 원인:

allowedRoutes 네임스페이스 불일치(기본값이 Same)
sectionName 오타 (http인데 https로 쓰는 등)
parentRefs.namespace 오류
hostnames 불일치

2️⃣ 80에 백엔드 라우트가 끼어들었나?

앱 라우트가 sectionName 없이 80에도 붙으면 매칭 우선순위에서 백엔드가 이겨 평문으로 서빙됩니다. → 앱 라우트에 sectionName: https를 명시하거나, 위 allowedRoutes 잠금을 적용합니다.

3️⃣ 요청이 이 Gateway를 거치긴 하나?

예전 ingress-nginx가 아직 80을 서비스하고 있거나, NodePort·LB로 백엔드에 직접 접근하거나, port-forward로 테스트하는 경우 Gateway가 트래픽 경로에 없어 리다이렉트가 적용될 리 없습니다.

리다이렉트 동작 확인은 curl로 합니다.

1curl -I http://redirect.example/cinnamon
2# HTTP/1.1 301 Moved Permanently
3# location: https://redirect.example/cinnamon

❓ 자주 묻는 질문 #

Q. Ingress의 `ssl-redirect` annotation과 무엇이 다른가요? #

Ingress는 컨트롤러마다 nginx.ingress.kubernetes.io/ssl-redirect: "true" 같은 벤더 전용 annotation으로 리다이렉트했습니다. Gateway API는 이를 표준 필터 RequestRedirect로 정의해 구현체에 상관없이 동일한 스펙으로 동작하게 합니다.

Q. 301과 302 중 무엇을 써야 하나요? #

HTTP→HTTPS 영구 전환에는 **301(영구 이동)**을 권장합니다. 브라우저·검색엔진이 결과를 캐시해 다음부터 바로 https로 요청하기 때문입니다. statusCode를 생략하면 기본값은 302(임시)입니다.

Q. 리다이렉트 라우트를 빼고 443 라우트만 두면 안 되나요? #

브라우저는 https-first 동작 때문에 잘 넘어가는 것처럼 보이지만, 80으로 직접 온 요청(curl·구형 클라이언트·외부 연동)은 404가 납니다. 부드러운 리다이렉트를 보장하려면 80 리스너에 붙는 리다이렉트 라우트가 반드시 필요합니다.

Q. POST 요청도 리다이렉트되나요? #

301/302는 리다이렉트 시 메서드가 GET으로 바뀔 수 있습니다. POST 등 메서드를 보존해야 하면 307/308을 사용해야 하지만, 이는 Extended 지원이라 구현체 지원 여부를 먼저 확인하세요.

📚 참고 #

[Kubernetes] 🔏 인증서와 cert-manager: 두 갈래 PKI와 TLS 자동화

Fri, 05 Jun 2026 00:00:00 +0000

쿠버네티스를 다루다 보면 kubeadm로 클러스터를 세울 때도 인증서가 나오고, Ingress·Gateway에도 인증서가 나옵니다. 같은 걸까요? 이 글에서는 key·cert·CA·TLS 용어를 신분증 비유로 정리하고, 쿠버네티스에 **PKI가 두 갈래(클러스터 내부 mTLS vs 앱/인그레스 TLS)**로 별개라는 점, 그리고 cert-manager가 “받은 인증서를 넣는” 게 아니라 발급·갱신 행위를 자동화한다는 핵심을 다룹니다.

이 시리즈는 쿠버네티스 gRPC 삽질에서 출발해 HTTP/2·TLS·로드밸런서·Gateway API·인증서까지 풀어가는 기록입니다. 이번 6편은 인증서와 cert-manager 편입니다. 앞선 2편(h2 vs h2c), 5편(Gateway API)을 먼저 보면 좋습니다.

🪪 용어 4개 — 경쟁 관계가 아니라 한 시스템의 역할들 #

key·CA·certificate·TLS는 서로 다른 선택지가 아니라, 하나의 신분증 시스템을 이루는 역할들입니다.

용어	신분증 비유	실제 의미
key(키)	나만 만들 수 있는 서명	개인키 + 검증용 공개키. 모든 것의 토대
CA(인증기관)	신분증 발급 기관(정부)	자기 키(CA key)로 인증서에 도장을 찍음
certificate(cert/crt)	신분증 카드 그 자체	공개키 + 신원 + CA의 서명
TLS	검문소에서 신분증 제시·검증	위 재료를 실제로 쓰는 프로토콜

정리하면 “CA가 자기 키로 인증서(신분증)에 서명하고, TLS가 연결할 때 그걸 제시·검증한다.” 넷이 한 흐름의 부품이지, 서로 다른 선택지가 아닙니다.

🍴 헷갈림의 핵심: 같은 기술을 쓰는 별개의 두 체계 #

쿠버네티스에는 완전히 별개인 두 종류의 인증서 체계가 있고, 둘 다 같은 기술(X.509 + TLS)을 써서 똑같아 보입니다. 여기가 진짜 함정입니다.

① 클러스터 내부 PKI (kubeadm certs) — 컴포넌트끼리 인증용 #

클러스터에 자체 CA(ca.crt/ca.key)가 있고, 그게 API 서버·etcd·kubelet 등의 인증서를 서명합니다.
컴포넌트들은 “상대 인증서가 우리 클러스터 CA가 서명한 거냐"로 서로를 믿습니다(mTLS, 상호 인증).
이게 보통 갱신하는 그 인증서입니다. (잎사귀(leaf) 인증서는 기본 1년, CA 자체는 보통 10년)
관리 도구: kubeadm (kubeadm certs renew 등). 외부 서비스와 무관.

② 앱/인그레스 TLS (Gateway·Ingress + cert-manager) — 외부 클라이언트용 #

공인 CA(또는 사내 CA)가 a.example.com 같은 도메인 인증서를 서명합니다.
외부 브라우저·클라이언트가 “이 https 서버 믿어도 되나"를 판단하는 용도입니다.
관리 도구: cert-manager나 수동 Secret. 클러스터 내부 통신과 무관.

🧠 둘은 별개의 CA, 별개의 목적, 별개의 수명·관리 도구입니다. 클러스터 CA는 a.example.com 인증서와 아무 상관이 없고, 브라우저는 클러스터 CA를 모르며, 컴포넌트들은 Let’s Encrypt를 신경 쓰지 않습니다. 기술은 같지만(X.509+TLS), 다른 건 “누구를 위한 신뢰냐” — ①은 클러스터 식구들끼리, ②는 바깥 손님에게입니다.

구분	① 클러스터 내부 PKI	② 앱/인그레스 TLS
목적	컴포넌트 상호 인증(mTLS)	외부 클라이언트 신뢰
CA	클러스터 자체 CA	공인/사내 CA (Let’s Encrypt 등)
수명	leaf 1년, CA 10년	발급처별(Let’s Encrypt 90일)
관리	kubeadm	cert-manager / 수동 Secret

이제부터는 ②(앱/인그레스 TLS) 얘기입니다.

🏢 Gateway에서 TLS를 중앙화하기 #

Gateway API에서는 TLS 설정이 Gateway의 listener로 올라가, TLS 개인키가 플랫폼팀 한 곳에 모입니다. 5편에서 본 역할 분리가 여기서 보안 이점으로 이어집니다.

예전 Ingress 방식의 약점: Ingress의 TLS Secret은 Ingress와 같은 네임스페이스, 즉 앱팀 네임스페이스에 있어야 했습니다. 그래서 TLS 개인키가 팀마다 흩어졌고, 관리·감사 범위가 컸습니다.

Gateway API에서는 Gateway(플랫폼팀 리소스)의 listener에 TLS를 두므로, 개인키가 플랫폼팀 한 곳에 모이고 앱팀은 Route만 붙입니다.

 1kind: Gateway
 2metadata:
 3 name: shared-gateway
 4 namespace: gateway-system  # 플랫폼팀 소유
 5spec:
 6 listeners:
 7 - name: team-a
 8 port: 443
 9 protocol: HTTPS
10 hostname: "a.example.com" # 프로젝트별 도메인
11 tls:
12 mode: Terminate
13 certificateRefs:
14 - name: team-a-tls  # 프로젝트별 인증서
15 allowedRoutes:
16 namespaces:
17 from: Selector
18 selector:
19 matchLabels:
20 team: a

프로젝트별로 다른 인증서도 가능합니다. listener를 도메인별로 나누면 TLS의 SNI(접속하려는 도메인)로 인증서가 자동 선택됩니다.
추가 통제 장치: allowedRoutes로 어느 네임스페이스의 Route만 붙을지 제한하고, 다른 네임스페이스의 Secret을 참조하려면 ReferenceGrant로 명시적 허용이 필요합니다(크로스 네임스페이스 접근 기본 차단 = 보안 기능).
HTTPRoute가 어느 listener에 붙을지는 hostname 교집합으로 자동 매칭되고, 명확히 하려면 sectionName(listener 이름)을 적어주면 됩니다.

🤖 cert-manager — “받은 인증서를 넣는” 게 아니라 “받는 행위를 자동화” #

cert-manager는 담당자에게 받은 인증서를 넣어주는 도구가 아니라, 직접 개인키를 만들고 CA에 인증서를 요청해 받아오는 도구입니다. 작동 방향이 반대라는 점이 큰 오해 포인트입니다. 즉 완성된 인증서를 사람한테 받아 넣는 게 아니라, 사람의 손을 거치는 단계 자체를 없앱니다.

자동화 흐름 #

cert-manager 설치 (클러스터에 Pod로)
Issuer/ClusterIssuer 정의 — “인증서를 어디서 받을지”(Let’s Encrypt, Vault, 사내 CA 등)
Certificate 생성(또는 애너테이션) — “a.example.com 인증서 필요”
cert-manager가 발급처와 통신하고 도메인 소유를 증명(HTTP-01 / DNS-01 챌린지)
받은 인증서+키를 Secret에 자동 저장 → Gateway가 그 Secret 참조
만료 전 자동 갱신 (예: Let’s Encrypt는 90일)

핵심은 사람이 개인키를 만들거나 secret.yaml을 주고받을 일이 사라진다는 것입니다.

 1# ClusterIssuer (Let's Encrypt ACME)
 2apiVersion: cert-manager.io/v1
 3kind: ClusterIssuer
 4metadata:
 5 name: letsencrypt-prod
 6spec:
 7 acme:
 8 server: https://acme-v02.api.letsencrypt.org/directory
 9 email: admin@example.com
10 privateKeySecretRef:
11 name: letsencrypt-prod-account-key
12 solvers:
13 - http01:
14 ingress:
15 class: nginx
16---
17# Certificate — cert-manager가 발급·갱신·Secret 저장을 자동 처리
18apiVersion: cert-manager.io/v1
19kind: Certificate
20metadata:
21 name: team-a-tls
22 namespace: gateway-system
23spec:
24 secretName: team-a-tls  # Gateway가 참조하는 Secret 이름
25 dnsNames:
26 - a.example.com
27 issuerRef:
28 name: letsencrypt-prod
29 kind: ClusterIssuer

발급처(issuer) 종류도 다양합니다: ACME(Let’s Encrypt 등), HashiCorp Vault, Venafi, 사내 CA, self-signed. 핵심은 “사람이 아니라 프로그램이 자동으로 요청·수령할 수 있는 발급처"라는 점입니다.

⚠️ cert-manager가 수동 발급을 대체하려면 회사 CA가 자동 연동(ACME/Vault 등) 가능해야 합니다. 순수 수동 발급뿐이면 cert-manager가 그 발급을 자동화하지 못합니다.

수동 발급을 유지해야 한다면 적어도 secret.yaml을 손으로 쓰는 대신 이렇게 줄일 수 있습니다.

1kubectl create secret tls my-tls \
2 --cert=tls.crt --key=tls.key -n my-namespace

📝 한 줄 요약 #

key·cert·CA·TLS는 한 신분증 시스템의 역할들입니다.
쿠버네티스엔 PKI가 두 갈래 — 클러스터 내부(kubeadm, mTLS)와 앱/인그레스 TLS — 로 완전히 별개입니다.
cert-manager는 “받은 인증서를 넣는” 게 아니라 “받는 행위(발급·갱신)를 자동화” 하는 도구이며, 자동 연동 가능한 CA가 전제입니다.

❓ 자주 묻는 질문 #

Q. kubeadm 인증서와 Ingress TLS 인증서는 같은 건가요? #

아닙니다. kubeadm 인증서는 클러스터 컴포넌트끼리의 mTLS용(클러스터 자체 CA), Ingress/Gateway TLS는 외부 클라이언트용(공인/사내 CA)입니다. CA·목적·수명·관리 도구가 모두 다릅니다.

Q. cert-manager에 회사에서 받은 .pfx를 넣으면 관리해주나요? #

그게 cert-manager의 방식이 아닙니다. cert-manager는 직접 키를 만들고 CA에 발급을 요청합니다. 회사 CA가 ACME/Vault 등으로 자동 연동되지 않고 순수 수동 발급만 한다면, cert-manager로 자동화할 수 없습니다.

Q. Let’s Encrypt 인증서 유효기간은 얼마인가요? #

90일입니다. cert-manager는 만료 전에 자동으로 갱신하므로 수동 개입이 필요 없습니다.

Q. HTTP-01과 DNS-01 챌린지의 차이는? #

둘 다 도메인 소유를 증명하는 방식입니다. HTTP-01은 도메인의 특정 경로에 토큰을 노출(80 포트 필요), DNS-01은 DNS TXT 레코드로 증명합니다. 와일드카드 인증서(*.example.com)는 DNS-01만 가능합니다.

Q. Gateway API에서 다른 네임스페이스의 인증서 Secret을 참조하려면? #

ReferenceGrant로 명시적 허용이 필요합니다. 크로스 네임스페이스 접근은 기본 차단되어 있어, 이 보안 기능을 통해 어떤 네임스페이스가 어떤 리소스를 참조할 수 있는지 통제합니다.

📚 참고 #

[Kubernetes] 🌐 Ingress에서 Gateway API로: HTTPProxy vs HTTPRoute 비교

Thu, 04 Jun 2026 00:00:00 +0000

쿠버네티스에서 앱 트래픽을 라우팅하는 방법은 Ingress로 시작해 벤더별 CRD를 거쳐 표준 Gateway API(HTTPRoute·GRPCRoute)로 수렴하고 있습니다. 이 글에서는 그 진화의 흐름과 함께, 설정(API)과 엔진(Envoy)이 다른 층이라는 핵심 구분, 그리고 Contour 전용 HTTPProxy vs 표준 HTTPRoute의 차이를 실무 관점에서 정리합니다.

이 시리즈는 쿠버네티스 gRPC 삽질에서 출발해 HTTP/2·TLS·로드밸런서·Gateway API·인증서까지 풀어가는 기록입니다. 이번 5편은 Ingress → Gateway API 편입니다. 앞선 3편(L4 vs L7), 4편(트래픽 구조)을 먼저 보면 좋습니다.

🧩 먼저: API(설정)와 엔진(Envoy)은 다른 층이다 #

Ingress·HTTPProxy·Gateway API는 “설정(API)“이고, Envoy·nginx는 그 설정을 실행하는 “엔진"입니다. 이걸 안 나누면 “Gateway → Envoy → HTTPRoute” 식으로 머릿속에서 다 섞입니다. 두 층을 분리합시다.

API 층 (내가 쓰는 설정): Ingress, HTTPProxy, Gateway API(Gateway + HTTPRoute + GRPCRoute). “이렇게 라우팅해라"라고 적는 문서입니다.
데이터 플레인 엔진 (실제로 트래픽을 처리하는 것): Envoy(또는 nginx). 내가 적은 설정대로 진짜 패킷을 나르는 프록시입니다.

💡 Envoy는 API가 아니라 엔진입니다. Contour도, Istio도, Envoy Gateway도 전부 그 밑에서 Envoy를 엔진으로 씁니다. 그러니 “Gateway API라는 설정을 Envoy라는 엔진이 실행한다"가 올바른 그림입니다. Envoy를 HTTPRoute와 같은 줄에 두면 안 됩니다.

🧬 진화의 흐름 #

쿠버네티스 라우팅 API는 3세대를 거쳐 진화했습니다.

세대	대표	특징	한계
1세대	Ingress (빌트인)	1.19(2020) GA, HTTP 노출 표준	너무 단순 → 애너테이션 남발, 파편화
2세대	벤더 CRD	Contour HTTPProxy, Istio VirtualService, Traefik IngressRoute	기능은 풍부하나 벤더 락인
3세대	Gateway API	GatewayClass·Gateway·HTTPRoute·GRPCRoute	벤더 중립, 이식성 높음 (표준)

1세대: Ingress (원조, 빌트인) #

Ingress API는 쿠버네티스 1.19(2020)에서 GA가 된 기능으로, 오랫동안 HTTP 서비스를 노출하는 표준이었습니다. 하지만 너무 단순해서 컨트롤러마다 부족한 기능을 애너테이션으로 메우기 시작했고, 설정이 파편화되고 이식성이 떨어졌습니다.

2세대: 벤더별 CRD #

벤더들이 각자 풍부한 CRD를 만들어 한계를 메웠습니다 — Contour의 HTTPProxy, Istio의 VirtualService, Traefik의 IngressRoute처럼요. 기능은 좋았지만 전부 벤더 락인이었습니다.

3세대: Gateway API (표준) #

그 교훈을 모아 커뮤니티가 표준으로 수렴한 게 Gateway API입니다. GatewayClass·Gateway·HTTPRoute·GRPCRoute 같은 타입화된 리소스로, 벤더 중립적이고 이식성이 높습니다.

⚔️ HTTPProxy vs HTTPRoute #

HTTPProxy는 Contour 전용 CRD이고, HTTPRoute는 표준 Gateway API의 일부입니다. 둘 다 L7 라우팅을 하지만 출신이 다릅니다.

구분	HTTPProxy	HTTPRoute
출신	Contour 전용 CRD (벤더 독자)	Gateway API 표준
동작 범위	Contour에서만	표준 구현 게이트웨이 어디서나
성숙도	풍부·성숙	표준, 빠르게 성숙 중
gRPC 전용	(HTTPProxy 내 설정)	표준 GRPCRoute
이식성	낮음(벤더 종속)	높음

한 줄로: “한 벤더 전용이지만 성숙(HTTPProxy)” vs “표준이라 이식성 높음(HTTPRoute)”.

gRPC 라우팅을 표준으로 작성하면 다음과 같습니다.

 1# GRPCRoute (Gateway API 표준)
 2apiVersion: gateway.networking.k8s.io/v1
 3kind: GRPCRoute
 4metadata:
 5 name: my-grpc-route
 6spec:
 7 parentRefs:
 8 - name: my-gateway  # 플랫폼팀이 만든 Gateway 참조
 9 rules:
10 - matches:
11 - method:
12 service: helloworld.Greeter  # gRPC 서비스명으로 매칭
13 backendRefs:
14 - name: my-grpc-svc
15 port: 8080

🤝 역할 분리 — Gateway API의 핵심 장점 #

Gateway API는 플랫폼팀(인프라)과 앱팀(라우팅)의 책임을 공식적으로 나눕니다.

리소스	소유 주체	담당
GatewayClass / Gateway	플랫폼·인프라 팀	리스너·포트·TLS
HTTPRoute / GRPCRoute	앱·프로젝트 팀	라우팅 규칙

즉 플랫폼팀이 인프라(Gateway)를, 앱팀이 라우트를 따로 소유하는 구조입니다. 이 “관심사의 분리(separation of concerns)“가 핵심 이점입니다. (다음 6편에서 TLS 인증서를 이 구조로 중앙화하는 걸 다룹니다.)

🕸️ 왜 Istio 문서랑 비슷하게 느껴질까 #

Istio의 자체 CRD(VirtualService·Gateway·DestinationRule)가 Gateway API 설계에 큰 영향을 줬기 때문입니다. Istio는 Envoy 기반 서비스 메시이고, 지금은 Istio도 Gateway API를 지원합니다. 그래서 “어디서 본 것 같다"는 감이 정확합니다.

단, 결이 하나 다릅니다.

Gateway API / Ingress = north-south 트래픽 (외부 ↔ 클러스터)
서비스 메시 = east-west 트래픽 (서비스 ↔ 서비스)

둘은 경쟁이 아니라 보완 관계입니다.

📅 2026년 현재 상태 #

빠르게 변하는 영역이라 작성 시점(2026년 6월) 기준이며, 최신 공식 문서 확인을 권장합니다.

Gateway API: 2023년 10월 v1.0 GA에 도달했고, 2026년 들어 v1.5까지 릴리스되며 여러 기능이 Standard(Stable)로 승격된 성숙·프로덕션 레디 상태입니다. SIG Network의 공식 권고는 Gateway API로의 이전입니다.
Ingress는 사라지지 않습니다. Ingress API 자체는 폐기·제거 계획이 없고, 다만 더 이상 적극 개발되지 않는 “feature-frozen” 상태입니다.
⚠️ 주의 — ingress-nginx 은퇴: 가장 널리 쓰이던 커뮤니티 ingress-nginx 컨트롤러는 2026년 3월 retired 되었습니다. 저장소는 kubernetes-retired로 옮겨져 read-only가 되었고, 더 이상 릴리스·버그픽스·CVE 패치가 없습니다. 기존 배포는 계속 동작하지만 신규 보안 취약점은 패치되지 않으므로 마이그레이션이 권장됩니다. (이는 커뮤니티 프로젝트 얘기이며, F5/NGINX의 상용 컨트롤러는 별개입니다.) 이전을 돕는 공식 도구 ingress2gateway도 제공됩니다.
표준이라 구현체가 여럿입니다. 완전 적합 구현으로 Envoy Gateway·Istio·NGINX Gateway Fabric·Traefik·Cilium·kgateway 등이 있고, Contour·AWS LB Controller·GKE Gateway·Kong 등은 부분 적합입니다.

🎯 실무 권장 #

신규로 시작한다면 Gateway API가 자연스럽고, 잘 돌아가는 Ingress 설정이 있다면 구체적인 한계에 부딪힐 때 옮기면 됩니다. 1편에서 HTTPProxy를 썼더라도 당장 바꿀 필요는 없지만, 신규 설계·멀티 벤더·이식성이 중요하면 HTTPRoute/GRPCRoute 방향이 미래지향적입니다. 다만 ingress-nginx를 쓰고 있다면 은퇴(EOL)로 인해 이전이 사실상 필수입니다.

📝 한 줄 요약 #

Ingress(원조, 애너테이션 한계) → 벤더 CRD(HTTPProxy 등) → 표준 Gateway API(HTTPRoute·GRPCRoute)로 진화 중입니다.
HTTPProxy는 Contour 전용, HTTPRoute는 표준이라 이식성이 높습니다.
API(설정)와 Envoy(엔진)는 다른 층입니다.

❓ 자주 묻는 질문 #

Q. HTTPProxy와 HTTPRoute 중 무엇을 써야 하나요? #

이식성·표준·멀티 벤더가 중요하면 HTTPRoute(Gateway API)를 권장합니다. 이미 Contour와 HTTPProxy로 잘 돌아가고 있다면 당장 바꿀 필요는 없지만, 신규 설계는 표준 방향이 미래지향적입니다.

Q. Ingress는 이제 안 쓰나요? #

Ingress API 자체는 제거 계획이 없는 feature-frozen 상태로 계속 동작합니다. 다만 커뮤니티 ingress-nginx 컨트롤러가 2026년 3월 은퇴해 CVE 패치가 중단되었으므로, 해당 컨트롤러 사용자는 마이그레이션이 필요합니다.

Q. Gateway API와 서비스 메시(Istio)는 무엇이 다른가요? #

Gateway API는 north-south(외부↔클러스터) 트래픽을, 서비스 메시는 east-west(서비스↔서비스) 트래픽을 주로 다룹니다. 경쟁이 아니라 보완 관계이며, Istio는 Gateway API도 지원합니다.

Q. Envoy와 Gateway API의 관계는? #

Envoy는 트래픽을 실제로 처리하는 데이터 플레인 “엔진"이고, Gateway API는 “이렇게 라우팅하라"를 적는 설정(API)입니다. Contour·Istio·Envoy Gateway 등이 Gateway API 설정을 받아 Envoy 엔진으로 실행합니다.

📚 참고 #

[Kubernetes] 🚦 쿠버네티스 트래픽 구조: 로드밸런서는 어디에 들어갈까

Wed, 03 Jun 2026 00:00:00 +0000

쿠버네티스에서 로드밸런서가 정확히 어디에 들어가는지 헷갈리면 트래픽 구조 전체가 안 그려집니다. 이 글에서는 LB가 들어갈 **두 자리(마스터 API 서버 앞, 앱 인그레스 앞)**를 구분하고, “마스터가 여러 대면 LB가 필요 없다"는 흔한 오해를 정정하며, 앱 요청은 마스터를 거치지 않는다는 컨트롤 플레인 vs 데이터 플레인의 핵심 구조를 정리합니다.

이 시리즈는 쿠버네티스 gRPC 삽질에서 출발해 HTTP/2·TLS·로드밸런서·Gateway API·인증서까지 풀어가는 기록입니다. 이번 4편은 쿠버네티스 트래픽 구조 편입니다. 앞선 1편(문제와 해결), 2편(h2 vs h2c), 3편(L4 vs L7)을 먼저 보면 좋습니다.

📍 로드밸런서가 들어갈 두 자리 #

쿠버네티스에서 로드밸런서가 들어갈 자리는 두 군데입니다. 이 둘을 분리하는 게 이번 편의 전부입니다.

자리	위치	다루는 트래픽	사용 LB
자리 ①	마스터(API 서버) 앞	관리 트래픽 (kubectl·워커노드 → 마스터)	외부 L4 (HAProxy, kube-vip)
자리 ②	앱(인그레스) 앞	서비스 트래픽 (외부 사용자 → Pod)	인그레스 컨트롤러 L7 (nginx, Contour)

이 둘은 목적도, 위치도, 다루는 트래픽도 완전히 다릅니다.

🚪 자리 ②: 인그레스 — nginx·Contour·HAProxy는 서로 대안 #

앱 트래픽이 들어오는 입구이며, 3편에서 본 L7 로드밸런서가 여기 들어갑니다.

nginx·Contour·HAProxy(인그레스 컨트롤러)·Envoy Gateway 등은 같은 자리를 놓고 경쟁하는 대안들입니다. 위로 쌓는 게 아니라 하나만 고르면 됩니다. nginx나 Contour를 인그레스 컨트롤러로 쓰면, 그 역할에서 HAProxy는 따로 필요 없습니다.

🧭 자리 ①: 마스터 앞 LB — 흔한 오해 #

❓ 흔한 오해: “마스터가 여러 대면 알아서 분산하니까, LB는 필요 없는 거 아냐?”

사실은 정반대입니다. 마스터가 여러 대인 것이 곧 LB가 필요한 이유입니다.

API 서버들은 서로 클라이언트 요청을 나눠주지 않습니다. 마스터 3대 = 독립적으로 도는 API 서버 3개이고, “대표 창구"가 내장돼 있지 않습니다. LB가 없으면 kubectl이 마스터 한 대의 IP를 콕 찍어야 하고, 그 마스터가 죽으면 나머지가 멀쩡해도 접속이 끊깁니다. HA(고가용성)의 의미가 사라집니다.

1kubectl ──▶ LB ──┬─ master1 (API서버)
2 ├─ master2 (API서버) ← 한 대 죽어도 LB가 다른 데로
3 └─ master3 (API서버)

이 자리엔 인그레스 컨트롤러(nginx/Contour)를 못 씁니다. 그들은 클러스터 안에서 Pod로 도는데, 마스터 앞 LB는 클러스터가 떠 있기 전에 바깥에 있어야 하기 때문입니다(닭-달걀 문제). 그래서 자리 ①은 HAProxy·kube-vip 같은 외부 L4 LB가 필요합니다.

Tip: 마스터가 1대인 보통의 테스트/홈랩 구성이면 이 자리는 아예 필요 없습니다.

🔄 그럼 마스터들끼리 “알아서” 하는 건 뭘까 #

마스터들이 협조하긴 하지만, 그 협조는 상태 공유이지 요청 분배가 아닙니다. 오해의 뿌리가 여기 있습니다.

etcd라는 공동 저장소에 클러스터 상태를 함께 보관하고, 내부적으로 리더를 뽑아 동기화합니다.
일부 컴포넌트(스케줄러, 컨트롤러 매니저 등)도 리더를 선출해 하나만 동작합니다(leader election).

하지만 이건 전부 “데이터를 맞추는” 얘기입니다. “들어온 클라이언트 요청을 창구에서 나눠주는” 일은 아닙니다. 그 창구 분배가 바로 LB의 몫입니다.

🧠 컨트롤 플레인 vs 데이터 플레인 — 앱 요청은 마스터를 안 거친다 #

가장 중요한 구조적 사실은 앱 요청이 마스터 서버를 통과하지 않는다는 것입니다. 쿠버네티스엔 분리된 두 경로가 있습니다.

1[관리 경로 — 마스터 사용 (컨트롤 플레인)]
2kubectl / kubelet ──▶ 마스터(API서버)
3
4[앱 요청 경로 — 마스터 안 거침 (데이터 플레인)]
5클라이언트 ──▶ 인그레스(nginx/Contour) ──▶ Service ──▶ Pod

마스터는 “어떤 Pod가 있는지” 정보를 관리하고 인그레스·노드에 미리 뿌려둘 뿐, 요청을 직접 받아 전달하지 않습니다.

건물 관리실 비유 #

마스터 = 건물 관리실. 누가 몇 호에 사는지 명부를 관리하고, 입주자가 오고 가면(Pod 생성·삭제) 명부를 갱신합니다.
인그레스 = 로비의 안내 표지판. 관리실이 갱신해둔 정보로 채워져 있습니다.
방문자(요청) 는 관리실에 들르지 않습니다. 표지판만 보고 곧장 해당 호실(Pod)로 갑니다.

그래서 마스터가 잠깐 바빠도, 이미 떠 있는 앱들은 멀쩡히 요청을 처리합니다. 마스터는 “정보를 나눠주는 두뇌"이지 “요청을 나눠주는 창구"가 아닙니다.

📌 1편에서 port-forward로 앱을 격리 테스트했는데, 이건 예외입니다. port-forward 같은 디버그 통로는 관리 경로(API 서버)를 거치는 특수 케이스입니다. 일반 서비스 트래픽이 마스터를 안 거친다는 뜻입니다.

↔️ 덤: Ingress와 Egress #

같은 맥락에서 자주 나오는 짝이 Ingress / Egress이며, 트래픽의 방향을 가리킵니다.

구분	방향	예시	다루는 방법
Ingress	외부 → 클러스터 안	사용자가 앱에 접속	Ingress 객체, Gateway API
Egress	클러스터 안 → 외부	Pod가 외부 API·DB 호출	NetworkPolicy egress, Egress Gateway

Ingress는 정식 객체가 있지만 Egress라는 단일 객체는 없고, NetworkPolicy의 egress 규칙이나 Egress Gateway로 다룹니다. 홈랩 테스트 수준에선 보통 egress를 따로 신경 쓰지 않아도 됩니다(Pod는 기본적으로 외부로 자유롭게 나갑니다).

📝 한 줄 요약 #

LB가 들어갈 자리는 둘 — 마스터 앞(관리용, 외부 L4) 과 **앱 앞(서비스용, 인그레스 L7)**입니다.
마스터가 여러 대면 LB가 더 필요하고(오해 정정), 앱 요청은 마스터를 거치지 않습니다(컨트롤 플레인 ≠ 데이터 플레인).

❓ 자주 묻는 질문 #

Q. 마스터가 3대면 로드밸런서 없이도 HA가 되나요? #

안 됩니다. API 서버는 서로 요청을 분배하지 않으므로 kubectl·워커노드가 접속할 “대표 창구"인 LB가 필요합니다. LB가 없으면 특정 마스터 IP에 묶여 그 마스터가 죽을 때 접속이 끊깁니다.

Q. 인그레스 컨트롤러를 마스터 앞 LB로 쓸 수 있나요? #

없습니다. 인그레스 컨트롤러는 클러스터 안에서 Pod로 동작하므로, 클러스터가 뜨기 전·바깥에 있어야 하는 마스터 앞 LB 역할은 못 합니다. 그 자리엔 HAProxy·kube-vip 같은 외부 L4 LB가 필요합니다.

Q. 앱 요청이 느려지면 마스터(API 서버) 부하가 원인인가요? #

대부분 아닙니다. 일반 서비스 트래픽은 인그레스 → Service → Pod 경로로 흐르며 마스터를 거치지 않습니다. 마스터는 관리(컨트롤 플레인) 트래픽만 처리합니다.

Q. nginx, Contour, HAProxy 인그레스 컨트롤러를 동시에 써야 하나요? #

아닙니다. 같은 자리(앱 앞)를 놓고 경쟁하는 대안이라 하나만 고르면 됩니다.

📚 참고 #

[Kubernetes] ⚖️ L4 vs L7 로드밸런서와 gRPC 로드밸런싱의 함정

Tue, 02 Jun 2026 00:00:00 +0000

쿠버네티스에서 gRPC를 운영하다 보면 “L7 지원 되냐"는 질문을 반복해서 듣게 됩니다. 이 글에서는 L4와 L7 로드밸런서의 차이를 편지 비유로 정리하고, gRPC가 HTTP/2 연결 다중화 때문에 L4 로드밸런서에서 한 Pod로만 트래픽이 쏠리는 함정과 그래서 L7이 사실상 필수인 이유를 다룹니다. 또한 L4/L7이 버전도 하드웨어도 아닌 소프트웨어 동작 방식이라는 점도 짚습니다.

이 시리즈는 쿠버네티스에 gRPC를 올리다 막힌 삽질에서 출발해 HTTP/2·TLS·로드밸런서·Gateway API·인증서까지 풀어가는 기록입니다. 이번 3편은 L4 vs L7과 로드밸런서 편입니다. 앞선 1편(문제와 해결), 2편(h2 vs h2c)을 먼저 보면 이해가 빠릅니다.

✉️ L4 vs L7 — 편지를 여느냐, 안 여느냐 #

L4는 편지를 안 뜯고 겉봉의 주소(IP:포트)만 보고 전달하고, L7은 편지를 열어 내용까지 읽고 판단합니다. 2편의 편지 비유를 그대로 이어가면 깔끔합니다.

L4 = 편지를 안 뜯고, 겉봉의 주소(IP:포트)만 보고 전달합니다. 안에 뭐가 들었는지는 신경 쓰지 않습니다.
L7 = 편지를 열어서 내용까지 읽고 판단합니다. 경로·호스트·헤더·gRPC 메서드를 보고 라우팅하고, TLS를 풀고, 헤더를 고치기도 합니다.

용어로 풀면 L4는 전송 계층(TCP/포트), L7은 애플리케이션 계층(HTTP)입니다. 하지만 “겉봉만 보냐 / 내용까지 보냐"로 기억하는 게 훨씬 쓸모 있습니다.

이 구분은 1편과도 연결됩니다. 게이트웨이가 했던 일(TLS 풀기, :scheme 헤더 확인·수정, gRPC 라우팅)은 전부 “내용을 읽어야 가능한 일” = L7이었습니다. h2c 미스매치 같은 문제도 L7이라서 생긴 것입니다. 순수 L4였다면 내용을 안 읽으니 그런 문제 자체가 없습니다.

⚙️ 각각의 장단점 #

구분	장점	단점
L4 (전송 계층)	단순·고속, 프로토콜 무관(바이트로 전달), TLS 패스스루로 종단 암호화 쉬움	경로/호스트/gRPC 메서드별 라우팅·중앙 TLS 종료·헤더 조작 불가
L7 (애플리케이션 계층)	세밀한 라우팅, 중앙 TLS 종료, 헤더 조작, gRPC 요청 단위 분산	무겁고, 프로토콜을 이해해야 함(“h2c 지원하냐” 문제 발생)

L4는 프로토콜을 안 가리니(HTTP/1.1이든 HTTP/2든 그냥 바이트로 전달) 미스매치가 없습니다. 대신 똑똑한 처리는 못 합니다. L7은 그 똑똑한 걸 다 하는 대신, 1편에서 겪은 h2c 지원 같은 문제가 따라옵니다.

🪤 gRPC 로드밸런싱의 함정 (여기가 핵심) #

gRPC는 연결 하나에 요청 여러 개를 실어 보내기 때문에(HTTP/2 다중화), L4 로드밸런서로는 트래픽이 한 Pod로 쏠립니다. gRPC를 쓴다면 L4/L7 구분이 결정적으로 중요해지는 지점입니다.

L4 로드밸런서는 “연결 단위"로 분산한다 #

한 클라이언트가 연결 하나를 열면, 그 안의 모든 요청이 한 Pod에만 몰립니다.

1[L4 — 연결 단위]
2클라이언트 ──(연결 1개, 요청 100개)──▶ [LB] ──▶ Pod A (몰림 😵)
3 Pod B (놀고 있음)
4 Pod C (놀고 있음)

Pod를 3개로 늘려도 한 곳만 바쁘고 나머지는 놉니다. 스케일아웃이 무력화됩니다.

L7 로드밸런서는 “요청 단위"로 분산한다 #

같은 연결이라도 개별 RPC를 여러 Pod에 골고루 보냅니다.

1[L7 — 요청 단위]
2클라이언트 ──(연결 1개, 요청 100개)──▶ [LB] ──▶ Pod A (33개)
3 Pod B (33개)
4 Pod C (34개)

그래서 gRPC 로드밸런싱은 사실상 L7이 필요합니다.

💡 회의에서 듣던 “L7 지원 되냐"의 정체는 “이 장비가 편지를 열어 내용을 읽고, 특히 gRPC를 요청 단위로 똑똑하게 분산할 수 있냐"는 질문이었습니다. “L7 지원 안 되면 gRPC가 곤란하다"는 말이 나오면 십중팔구 이 분산 문제입니다.

🔀 로드밸런서는 “버전"이 아니라 “종류” #

L7은 L4의 신형 업그레이드가 아닙니다. 흔한 오해입니다.

L4/L7은 “어느 층에서 일하느냐에 따른 분류"일 뿐, 둘 다 현역이고 목적에 따라 고릅니다. L7이 항상 더 좋은 게 아니라 — 똑똑한 대신 무겁고 프로토콜을 가립니다. 단순·고속·프로토콜 무관이 필요하면 L4가 정답일 때도 많습니다.

🖥️ 전용 장비가 아니라 소프트웨어의 동작 방식 #

오늘날 L4/L7은 전용 하드웨어가 아니라 소프트웨어의 동작 방식입니다. 예전엔 로드밸런서가 물리 박스(어플라이언스)였던 탓에 전용 장비가 필요하다는 인상이 남아 있지만, 지금은 일반 머신에서 돌리는 소프트웨어 하나면 됩니다.

대표적으로 HAProxy는 설정 한 줄로 모드를 고릅니다.

# L4 — 편지 안 열고 그냥 전달
frontend grpc_l4
 bind *:8080
 mode tcp
 default_backend grpc_servers

# L7 — 편지 열어서 내용 보고 처리 (gRPC 요청 단위 분산)
frontend grpc_l7
 bind *:8443 ssl crt /etc/haproxy/certs/server.pem alpn h2
 mode http
 default_backend grpc_servers

mode tcp → L4 (편지 안 열고 그냥 전달)
mode http → L7 (편지 열어서 내용 보고 처리)

클라우드는 이름부터 층을 드러내기도 합니다.

클라우드 LB	계층	특징
AWS NLB (Network LB)	L4	초고속, 연결 단위
AWS ALB (Application LB)	L7	HTTP/gRPC 라우팅, 요청 단위

📝 한 줄 요약 #

L4는 겉봉(IP:포트)만 보고 빠르게 전달, L7은 편지를 열어 똑똑하게 처리합니다.
gRPC는 연결 하나에 요청을 몰아 보내기 때문에, 요청 단위로 분산하는 L7이 사실상 필수입니다.
L4/L7은 버전도 하드웨어도 아니라, 소프트웨어의 동작 방식(종류)입니다.

❓ 자주 묻는 질문 #

Q. gRPC를 L4 로드밸런서 뒤에 두면 왜 문제가 되나요? #

gRPC는 HTTP/2의 다중화로 연결 하나에 여러 요청을 싣습니다. L4는 연결 단위로 분산하므로, 한 클라이언트의 모든 요청이 한 Pod로만 가서 다른 Pod가 놀게 됩니다. 스케일아웃 효과가 사라집니다.

Q. 그럼 gRPC는 항상 L7을 써야 하나요? #

요청 단위 분산이 필요하면 L7(또는 클라이언트 사이드 LB, 서비스 메시)이 필요합니다. 다만 단일 백엔드이거나 클라이언트가 직접 분산하는 구조라면 L4도 가능합니다.

Q. L7이 L4보다 항상 좋은가요? #

아닙니다. L7은 똑똑한 대신 무겁고 프로토콜을 이해해야 합니다. 단순·고속·프로토콜 무관 처리가 필요하면 L4가 더 적합합니다. 둘은 버전 관계가 아니라 용도에 따른 선택입니다.

Q. HAProxy에서 L4와 L7은 어떻게 구분하나요? #

mode tcp는 L4(내용을 안 보고 전달), mode http는 L7(HTTP를 해석해 처리)입니다. gRPC를 요청 단위로 분산하려면 mode http가 필요합니다.

📚 참고 #

[Kubernetes] 🔐 HTTP/2는 TLS가 아니다: h2 vs h2c 완벽 정리

Mon, 01 Jun 2026 00:00:00 +0000

쿠버네티스에서 gRPC를 다루다 보면 “평문 HTTP/2(h2c)”, “scheme이 https인데 평문” 같은 모순처럼 들리는 말들과 마주칩니다. 이 글에서는 그 혼란의 근원인 “HTTP/2 = TLS"라는 오해를 봉투·엽서 비유로 깨고, h2와 h2c의 차이, ALPN 협상, TLS termination을 정리합니다. 이 개념만 잡으면 게이트웨이 뒤 gRPC 통신이 왜 그렇게 동작하는지 전부 설명됩니다.

이 시리즈는 쿠버네티스에 gRPC 서비스를 올리다 막힌 삽질에서 출발해 HTTP/2·TLS·로드밸런서·Gateway API·인증서까지 풀어가는 기록입니다. 이번 2편은 기초 개념(h2 vs h2c) 편입니다. 1편을 아직 안 읽었다면 .NET gRPC가 게이트웨이 뒤에서 안 됐던 문제와 해결을 먼저 보면 좋습니다.

🧱 모든 혼란의 근원: “HTTP/2 = TLS"라는 오해 #

HTTP/2와 TLS는 별개입니다. 가장 먼저 깨야 할 오해입니다. 둘은 서로 다른 축에 있습니다.

TLS = 암호화. 데이터를 봉투에 넣어 봉하느냐의 문제입니다.
HTTP/2 = 통신 프로토콜. 편지를 어떤 “언어"로 쓰느냐의 문제입니다(HTTP/1.1이냐 HTTP/2냐).

비유하면 이렇습니다.

암호화(TLS) = 봉투 / 평문 = 엽서
통신 방식(HTTP 버전) = 편지를 쓴 언어

편지를 HTTP/2라는 언어로 쓰되, 봉투에 담아 보낼 수도 있고(암호화), 엽서로 보낼 수도 있습니다(평문). 이 둘은 독립적입니다.

🔢 네 가지 조합 #

포장(암호화)과 언어(HTTP 버전)가 독립이라, 네 가지 조합이 모두 가능합니다.

	평문 (엽서)	TLS (봉투)
HTTP/1.1	그냥 HTTP (`http://`)	HTTPS (`https://`)
HTTP/2	h2c	h2

여기서 h2c의 c는 cleartext(평문), 즉 “암호화하지 않은 HTTP/2"입니다.

왜 “평문 HTTP/2"가 모순처럼 들릴까? #

브라우저 때문입니다. 브라우저는 보안상 HTTP/2를 TLS 위에서만(h2) 허용하고, 평문 HTTP/2(h2c)는 쓰지 않습니다. 그래서 일상에서 “HTTP/2 = HTTPS"처럼 느껴집니다. 하지만 그건 브라우저의 정책일 뿐, 프로토콜 자체의 규칙이 아닙니다. 서버끼리 통신할 땐 평문 HTTP/2(h2c)를 흔히 쓰며, 쿠버네티스 클러스터 내부가 대표적입니다.

🧠 흔한 오해: “HTTP/2면 당연히 https니까 인증서가 필요하겠지.” 실제로는 클러스터 내부 통신은 평문 HTTP/2(h2c)인 경우가 많고, 암호화는 별개 문제입니다.

📜 h2 / h2c는 누가 지어낸 말이 아니다 #

h2와 h2c는 특정 도구의 용어가 아니라 HTTP/2 표준(RFC 7540)에 정의되고 IANA에 등록된 공식 식별자입니다.

원래 h2는 TLS 핸드셰이크 때 “우리 HTTP/2로 말하자"를 짧게 주고받기 위한 ALPN 토큰입니다. 그래서 http2처럼 길게 쓰지 않고 h2라는 짧은 형태로 정했습니다. h2c는 평문 연결에서 HTTP/1.1 → HTTP/2 업그레이드를 요청할 때 쓰던 토큰이었습니다.

이게 중요한 이유는 도구가 바뀌어도 의미가 같기 때문입니다. Envoy·Kestrel·gRPC·Contour HTTPProxy 어디서 보든 h2c는 전부 “평문 HTTP/2"라는 같은 뜻입니다. 각 도구가 제멋대로 지은 게 아니라 같은 표준을 따르므로, 한 번 익히면 그대로 통합니다.

참고: 이후 HTTP/2 표준이 RFC 9113으로 정리되며 평문 업그레이드(Upgrade: h2c) 메커니즘 등 세부 규칙은 일부 바뀌었지만, h2=TLS HTTP/2, h2c=평문 HTTP/2라는 기본 의미는 그대로입니다.

🤝 ALPN — 봉투를 열기 전에 “언어"를 합의하는 과정 #

ALPN(Application-Layer Protocol Negotiation)은 TLS 핸드셰이크 단계에서 클라이언트와 서버가 어떤 프로토콜로 통신할지 미리 합의하는 과정입니다. 봉투(TLS)를 봉하기 전에 “우리 무슨 언어로 말할까?“를 정하는 셈이고, 여기서 h2로 합의되면 HTTP/2로 통신합니다.

핵심 포인트는 평문(엽서)에는 이 ALPN 단계가 없다는 것입니다.

그래서 1편에서 Kestrel을 Http1AndHttp2로 두면 안 됐던 것입니다. 평문 포트에는 “무슨 언어냐"를 협상할 ALPN이 없으니, Kestrel이 안전하게 HTTP/1.1로 떨어뜨립니다. 평문에서 HTTP/2를 받으려면 Http2 전용으로 못 박아야 합니다.

1// appsettings.json — 평문 포트에서 HTTP/2를 강제
2{
3 "Kestrel": {
4 "EndpointDefaults": {
5 "Protocols": "Http2"
6 }
7 }
8}

✂️ TLS termination — 봉투를 어디서 뜯느냐 #

TLS termination(TLS 종료)은 게이트웨이가 들어오는 암호화 연결의 봉투(TLS)를 뜯어 평문으로 바꾸는 지점입니다. 내용을 읽어 라우팅하려면 봉투를 먼저 열어야 하기 때문입니다. 그리고 클러스터 안쪽(게이트웨이 → Pod)으로는 다시 엽서(평문 h2c)로 전달합니다.

1클라이언트 ──(봉투, h2)──▶ 게이트웨이[봉투 뜯음] ──(엽서, h2c)──▶ Pod

여기서 1편의 원인 ②가 나옵니다. 게이트웨이는 봉투를 뜯어 엽서로 바꾸면서도, 편지에 붙은 :scheme 라벨은 원래대로 “https(봉투)“라고 남겨 둡니다. 그러니 엽서를 받은 Kestrel이 “라벨엔 봉투라는데 넌 엽서네?” 하고 거부한 것입니다. AllowAlternateSchemes는 “그 라벨은 무시하고 받아라"라는 허락이었습니다.

1builder.WebHost.ConfigureKestrel(options =>
2{
3 options.AllowAlternateSchemes = true; // :scheme=https + 평문 전송 허용
4});

🧩 정리: 세 가지만 구분하면 된다 #

1편의 모든 증상이 이 세 가지의 조합으로 설명됩니다.

구분	의미	예시
봉투 / 엽서	암호화 여부	TLS / 평문
언어	통신 방식	HTTP/1.1 / HTTP/2
라벨	요청 헤더	`:scheme`, `:authority` 등

외울 한 문장: 통신 방식(HTTP/1.1·HTTP/2)과 암호화(TLS를 쓰냐 마냐)는 완전히 별개다.

이 한 문장이 몸에 배면, “평문 HTTP/2"도 “scheme이 https인데 평문"도 더 이상 모순으로 들리지 않습니다.

❓ 자주 묻는 질문 #

Q. h2와 h2c의 차이는 무엇인가요? #

둘 다 HTTP/2입니다. h2는 TLS 위에서(암호화) 동작하는 HTTP/2, h2c는 평문(cleartext)에서 동작하는 HTTP/2입니다. c는 cleartext를 뜻합니다.

Q. HTTP/2를 쓰려면 반드시 인증서(TLS)가 필요한가요? #

아닙니다. 그건 브라우저의 정책일 뿐 프로토콜 규칙이 아닙니다. 서버 간 통신, 특히 쿠버네티스 클러스터 내부에서는 평문 HTTP/2(h2c)를 흔히 사용합니다.

Q. ALPN이 없으면 왜 HTTP/2로 통신할 수 없나요? #

평문 연결에는 TLS 핸드셰이크 자체가 없어 ALPN 협상 단계가 없습니다. 따라서 “HTTP/2로 말하자"를 합의할 방법이 없어, 서버는 안전하게 HTTP/1.1로 처리하거나 HTTP/2 전용으로 명시되어 있어야 합니다.

Q. TLS termination 이후 백엔드는 어떤 프로토콜을 받나요? #

게이트웨이가 TLS를 종료하면 백엔드(Pod)로는 평문이 전달됩니다. gRPC라면 이때 평문 HTTP/2, 즉 h2c로 전달되어야 합니다.

📚 참고 #

[Kubernetes] 🔌 gRPC가 .NET에서만 안 됐다: HTTP/2·TLS·scheme 문제 해결

Sat, 30 May 2026 00:00:00 +0000

쿠버네티스에 gRPC 서비스를 올렸는데 Python 서버는 붙고 .NET(Kestrel) 서버만 계속 끊기는 문제를 겪었습니다. 이 글에서는 그 원인이 ① 게이트웨이가 백엔드로 HTTP/1.1을 보내는 문제와 ② TLS 종료 후에도 :scheme=https 라벨이 남아 Kestrel이 거부하는 문제, 두 개의 서로 다른 계층에 있었음을 추적하고 h2c + AllowAlternateSchemes로 해결하는 과정을 단계별로 다룹니다.

이 시리즈는 쿠버네티스에 gRPC 서비스를 올리다 막힌 삽질에서 출발해, HTTP/2·TLS·로드밸런서·Gateway API·인증서까지 하나씩 풀어가는 기록입니다. 1편(이 글)은 문제와 해결입니다.

🚨 증상: 같은 gRPC인데 한쪽만 안 된다 #

쿠버네티스에 gRPC 서비스를 올렸습니다. 게이트웨이 설정은 동일한데 결과가 갈렸습니다.

백엔드	포트 80 (평문)	포트 443 (TLS)
Python gRPC 서버	✅ 정상	✅ 정상
.NET(Kestrel) gRPC 서버	✅ 정상	❌ 연결 끊김

Kestrel 로그에는 다음과 같은 에러가 찍혔습니다.

1The request :scheme header 'https' does not match the transport scheme 'http'.

처음 든 생각은 “HTTP/2가 문제니까 HTTP/2를 피해보자"였습니다. 결론부터 말하면 그건 불가능합니다. gRPC는 HTTP/2 위에서만 동작하기 때문입니다. HTTP/2를 빼는 순간 그건 더 이상 gRPC가 아닙니다.

그래서 방향을 바꿨습니다. “피하자"가 아니라 “어디서, 왜 깨지는지"를 정확히 찾자로요.

📌 핵심 전제 두 가지 #

본격적으로 들어가기 전에 두 가지만 깔고 갑니다. (자세한 개념은 다음 편에서 다룹니다.)

gRPC = HTTP/2. 처음부터 끝까지 HTTP/2를 요구합니다.
“통신 방식(HTTP 버전)“과 “암호화(TLS)“는 별개입니다. 이게 모든 혼란의 근원이었습니다.

특히 헷갈렸던 건 h2c라는 단어였습니다.

h2와 h2c는 무엇인가? #

h2는 TLS 위에서 동작하는 HTTP/2, h2c는 암호화 없이(평문) 동작하는 HTTP/2를 가리킵니다(c = cleartext). “HTTP/2인데 평문"이라는 말이 모순처럼 들리지만, HTTP/2와 TLS가 별개의 계층이라는 것을 알고 나면 자연스럽습니다.

표기	프로토콜	암호화	일반적인 포트
`h2`	HTTP/2	TLS 있음	443
`h2c`	HTTP/2	평문	80

🔍 원인 ① — 게이트웨이가 HTTP/1.1로 말을 걸고 있었다 #

첫 번째 원인은 게이트웨이가 백엔드로 HTTP/1.1을 보내고 있었던 것입니다. Kestrel을 HTTP/2 전용으로 설정해 두면 그 포트는 HTTP/2만 알아듣습니다. 그런데 게이트웨이는 별도 지정이 없으면 백엔드로 HTTP/1.1을 보냅니다. “언어"가 안 맞으니 Kestrel이 거부합니다.

해결 ①-a: 게이트웨이가 h2c로 보내게 한다 #

Service에 appProtocol을 명시하면, 게이트웨이가 백엔드로 평문 HTTP/2를 보내야 한다는 것을 알게 됩니다.

 1# Service
 2apiVersion: v1
 3kind: Service
 4metadata:
 5 name: my-grpc-svc
 6spec:
 7 ports:
 8 - name: grpc
 9 port: 8080
10 targetPort: 8080
11 appProtocol: kubernetes.io/h2c  # 평문 HTTP/2로 전달하라

Contour를 사용한다면 HTTPProxy에서 백엔드 프로토콜을 직접 지정할 수도 있습니다.

1# Contour HTTPProxy
2spec:
3 routes:
4 - services:
5 - name: my-grpc-svc
6 port: 8080
7 protocol: h2c

해결 ①-b: Kestrel을 HTTP/2 전용으로 둔다 #

평문 포트에는 프로토콜 자동 협상(ALPN)이 없어서, Http1AndHttp2로 두면 협상 단계 없이 HTTP/1.1로 떨어집니다. 따라서 평문 gRPC 포트는 Http2로 고정해야 합니다.

1// appsettings.json
2{
3 "Kestrel": {
4 "EndpointDefaults": {
5 "Protocols": "Http2"
6 }
7 }
8}

⚠️ Http1AndHttp2는 TLS(ALPN)가 있을 때만 HTTP/2로 협상됩니다. TLS 종료가 게이트웨이에서 일어나는 쿠버네티스 환경에서는 평문 포트이므로 Http2로 명시해야 합니다.

🔍 원인 ② — scheme 라벨 불일치 (.NET만 막혔던 진짜 이유) #

두 번째 원인이자 .NET만 막힌 진짜 이유는 :scheme 라벨과 실제 전송 방식의 불일치입니다. 게이트웨이가 TLS를 종료(복호화)해 평문으로 바꿔 보내면서도, 요청에 붙은 :scheme 값은 원래대로 https 로 남겨 둡니다. 그런데 Kestrel에 도착한 연결은 평문입니다. Kestrel은 “scheme은 https라는데 연결은 평문이네? 안 맞잖아"라며 거부합니다. 이게 로그에 찍힌 그 에러의 정체였습니다.

1The request :scheme header 'https' does not match the transport scheme 'http'.

Python gRPC 서버는 이 scheme 검증을 하지 않아서 그냥 통과했고, Kestrel만 엄격하게 검사했던 것입니다.

해결 ②: Kestrel에게 그 scheme을 허용하라고 알려준다 #

AllowAlternateSchemes 옵션을 켜면 Kestrel이 :scheme과 전송 방식이 달라도 허용합니다.

1builder.WebHost.ConfigureKestrel(options =>
2{
3 options.AllowAlternateSchemes = true;
4});

덤으로 이 옵션을 켜면 HttpRequest.Scheme이 원래 값(https)으로 잡혀, 앱이 리다이렉트·절대경로 URL을 만들 때도 올바르게 동작합니다.

Tip: AllowAlternateSchemes는 .NET 6 이상에서 사용할 수 있습니다. scheme 값 자체는 여전히 유효한 형식이어야 합니다.

🧩 두 설정은 “중복"이 아니라 “서로 다른 층” #

처음엔 “둘 다 h2c 관련 아닌가?” 싶었는데, 역할이 완전히 다릅니다.

설정	담당하는 계층	의미
Service의 `appProtocol: h2c`	통신 방식(언어)	“HTTP/2로 보내라”
Kestrel `AllowAlternateSchemes`	헤더(라벨) 검증	“https 라벨을 평문 위에서도 허용해라”

그래서 하나만 빼도, 둘 다 빼도 통신이 안 됩니다. 둘 다 맞춰야 합니다.

✅ 증상이 전부 설명된다 #

두 원인을 알고 나면 처음의 증상 표가 모두 설명됩니다.

왜 80은 되고 443은 안 됐나? 80(평문)으로 들어오면 게이트웨이가 scheme http로 전달 → 실제도 평문 → 일치 → OK. 443(TLS)은 scheme https를 평문 위로 전달 → 불일치 → 실패.
왜 Python은 되고 .NET은 안 됐나? Python 서버는 scheme 라벨을 검증하지 않았고, Kestrel만 엄격하게 검사했기 때문입니다.

📝 한 줄 요약 #

.NET gRPC가 게이트웨이 뒤에서 안 됐던 건 두 가지였습니다.

게이트웨이가 HTTP/1.1로 말을 걸어서 → Service appProtocol: h2c + Kestrel Protocols: Http2
TLS를 푼 뒤에도 :scheme=https 라벨이 남아 Kestrel이 거부해서 → AllowAlternateSchemes = true

둘은 다른 층의 문제라 둘 다 맞춰야 합니다.

❓ 자주 묻는 질문 #

Q. gRPC를 HTTP/1.1로 쓸 수는 없나요? #

없습니다. gRPC는 스트리밍과 멀티플렉싱을 위해 HTTP/2를 전제로 설계되어, HTTP/2를 빼면 더 이상 gRPC가 아닙니다.

Q. h2와 h2c의 차이는 무엇인가요? #

둘 다 HTTP/2입니다. h2는 TLS 위에서(암호화), h2c는 평문에서 동작합니다. 쿠버네티스에서 게이트웨이가 TLS를 종료하면 백엔드로는 h2c(평문 HTTP/2)가 전달됩니다.

Q. Kestrel을 `Http1AndHttp2`로 두면 안 되나요? #

평문 포트에서는 ALPN 협상이 없어 HTTP/1.1로 떨어집니다. TLS 종료가 게이트웨이에서 일어나는 환경에서는 평문 gRPC 포트를 Http2로 고정해야 합니다.

Q. `AllowAlternateSchemes`는 어떤 상황에서 필요한가요? #

게이트웨이/로드밸런서가 TLS를 종료한 뒤 :scheme을 원래 값(https)으로 유지한 채 평문으로 백엔드에 전달할 때 필요합니다. 이 옵션이 없으면 Kestrel이 scheme과 전송 방식 불일치로 연결을 거부합니다.

📚 참고 #

[Kubernetes] 🔐 kubeadm 인증서 자동 갱신: systemd 타이머로 만료 방지하기

Tue, 26 May 2026 00:00:00 +0000

kubeadm으로 설치한 Kubernetes 클러스터의 컨트롤 플레인 인증서는 기본 유효기간이 1년입니다. 운영 중인 클러스터에서 인증서가 만료되면 API 서버, 컨트롤러 매니저, 스케줄러가 통신을 멈추면서 클러스터 전체가 마비됩니다. 이 글에서는 systemd 타이머로 만료 30일 전에 자동으로 kubeadm certs renew all을 실행하여 인증서를 무중단으로 갱신하는 방법을 정리합니다.

🔑 kubeadm 인증서란? #

kubeadm은 클러스터 부트스트랩 시 컨트롤 플레인 구성요소가 사용하는 TLS 인증서를 자동으로 생성합니다. 모든 인증서는 /etc/kubernetes/pki/ 경로에 저장됩니다.

구분	인증서	용도
CA	`ca.crt`, `ca.key`	클러스터 루트 CA (유효기간 10년)
API Server	`apiserver.crt`	kube-apiserver HTTPS
API Server (kubelet)	`apiserver-kubelet-client.crt`	apiserver → kubelet 통신
Front Proxy	`front-proxy-*.crt`	Aggregation Layer
etcd	`etcd/*.crt`	etcd 멤버 간 + 클라이언트 통신
kubeconfig 내 인증서	`admin.conf`, `controller-manager.conf`, `scheduler.conf`	컨트롤 플레인 컴포넌트 인증

Tip: CA 인증서는 10년이지만 그 외 leaf 인증서는 모두 1년입니다. CA가 만료되면 클러스터 재설치 수준의 작업이 필요하니, leaf 인증서 갱신 시 CA 만료일도 함께 확인해야 합니다.

🔍 인증서 만료일 확인하기 #

kubeadm으로 확인 #

kubeadm certs check-expiration 명령으로 모든 인증서의 만료일을 한 번에 확인할 수 있습니다.

1sudo kubeadm certs check-expiration

출력 예시:

 1CERTIFICATE EXPIRES RESIDUAL TIME CERTIFICATE AUTHORITY EXTERNALLY MANAGED
 2admin.conf May 26, 2027 03:00 UTC 364d ca no
 3apiserver May 26, 2027 03:00 UTC 364d ca no
 4apiserver-kubelet-client May 26, 2027 03:00 UTC 364d ca no
 5controller-manager.conf May 26, 2027 03:00 UTC 364d ca no
 6etcd-server May 26, 2027 03:00 UTC 364d etcd-ca no
 7front-proxy-client May 26, 2027 03:00 UTC 364d front-proxy-ca no
 8scheduler.conf May 26, 2027 03:00 UTC 364d ca no
 9
10CERTIFICATE AUTHORITY EXPIRES RESIDUAL TIME
11ca May 24, 2036 03:00 UTC 9y
12etcd-ca May 24, 2036 03:00 UTC 9y
13front-proxy-ca May 24, 2036 03:00 UTC 9y

openssl로 개별 확인 #

특정 인증서만 빠르게 확인하고 싶다면 openssl을 사용합니다.

1sudo openssl x509 -in /etc/kubernetes/pki/apiserver.crt -noout -enddate
2# notAfter=May 26 03:00:00 2027 GMT

🛠️ 수동 갱신 방법 #

긴급 상황에서는 kubeadm certs renew all로 즉시 갱신할 수 있습니다.

 1# 1. 모든 인증서 갱신 (남은 기간과 무관하게 1년 연장)
 2sudo kubeadm certs renew all
 3
 4# 2. 컨트롤 플레인 Pod 재시작 (정적 Pod이므로 컨테이너만 재기동)
 5sudo crictl pods --namespace kube-system \
 6 --name 'kube-apiserver-*|kube-controller-manager-*|kube-scheduler-*|etcd-*' -q \
 7 | xargs sudo crictl rmp -f
 8
 9# 3. admin.conf 백업 후 .kube/config 갱신
10sudo cp /etc/kubernetes/admin.conf /root/.kube/config

⚠️ kubelet 인증서(/var/lib/kubelet/pki/kubelet-client-current.pem)는 별도로 자동 회전됩니다. kubelet.conf에 rotateCertificates: true가 설정되어 있는지 확인하세요.

⏰ systemd 타이머로 자동 갱신 구성하기 #

수동 갱신은 휴먼 에러로 누락되기 쉽습니다. 매주 월요일 새벽 3시에 만료일을 점검하고, 30일 미만이면 자동으로 갱신하는 systemd 타이머를 구성합니다.

동작 흐름 #

 1k8s-certs-renew.timer (매주 월 03:00)
 2 │ 트리거
 3 ▼
 4k8s-certs-renew.service (oneshot)
 5 │ ExecStart
 6 ▼
 7/usr/local/bin/kube-scripts/k8s-certs-renew.sh
 8 │
 9 ├─ kubeadm certs check-expiration
10 ├─ 만료까지 30일 미만이면:
11 │ ├─ kubeadm certs renew all
12 │ ├─ crictl로 컨트롤 플레인 Pod 재기동
13 │ └─ admin.conf → /root/.kube/config 복사
14 └─ apiserver 기동 대기 (6443 포트)

1️⃣ 갱신 스크립트 작성 #

/usr/local/bin/kube-scripts/k8s-certs-renew.sh 파일을 생성합니다.

 1sudo mkdir -p /usr/local/bin/kube-scripts
 2sudo tee /usr/local/bin/kube-scripts/k8s-certs-renew.sh > /dev/null <<'EOF'
 3#!/bin/bash
 4kubeadmCerts='/usr/local/bin/kubeadm certs'
 5
 6getCertValidDays() {
 7 local earliestExpireDate
 8 earliestExpireDate=$(${kubeadmCerts} check-expiration \
 9 | grep -o "[A-Za-z]\{3,4\}\s\w\w,\s[0-9]\{4,\}\s\w*:\w*\s\w*\s*" \
10 | xargs -I {} date -d {} +%s | sort | head -n 1)
11 local today
12 today="$(date +%s)"
13 echo -n $(( (earliestExpireDate - today) / (24 * 60 * 60) ))
14}
15
16echo "## Expiration before renewal ##"
17${kubeadmCerts} check-expiration
18
19if [ "$(getCertValidDays)" -lt 30 ]; then
20 echo "## Renewing certificates managed by kubeadm ##"
21 ${kubeadmCerts} renew all
22
23 echo "## Restarting control plane pods managed by kubeadm ##"
24 crictl pods --namespace kube-system \
25 --name 'kube-scheduler-*|kube-controller-manager-*|kube-apiserver-*|etcd-*' -q \
26 | xargs crictl rmp -f
27
28 echo "## Updating /root/.kube/config ##"
29 cp /etc/kubernetes/admin.conf /root/.kube/config
30fi
31
32echo "## Waiting for apiserver to be up again ##"
33until printf "" 2>>/dev/null >>/dev/tcp/127.0.0.1/6443; do sleep 1; done
34
35echo "## Expiration after renewal ##"
36${kubeadmCerts} check-expiration
37EOF
38
39sudo chmod +x /usr/local/bin/kube-scripts/k8s-certs-renew.sh

Tip: kubeadm 바이너리 경로는 환경마다 다릅니다. which kubeadm으로 확인 후 스크립트의 kubeadmCerts 변수를 조정하세요. (/usr/bin/kubeadm 또는 /usr/local/bin/kubeadm)

2️⃣ systemd 서비스 작성 #

/etc/systemd/system/k8s-certs-renew.service 파일을 생성합니다.

1sudo tee /etc/systemd/system/k8s-certs-renew.service > /dev/null <<EOF
2[Unit]
3Description=Renew K8S control plane certificates
4
5[Service]
6Type=oneshot
7ExecStart=/usr/local/bin/kube-scripts/k8s-certs-renew.sh
8EOF

3️⃣ systemd 타이머 작성 #

/etc/systemd/system/k8s-certs-renew.timer 파일을 생성합니다.

 1sudo tee /etc/systemd/system/k8s-certs-renew.timer > /dev/null <<EOF
 2[Unit]
 3Description=Timer to renew K8S control plane certificates
 4
 5[Timer]
 6OnCalendar=Mon *-*-* 03:00:00
 7Unit=k8s-certs-renew.service
 8
 9[Install]
10WantedBy=multi-user.target
11EOF

4️⃣ 타이머 활성화 #

1sudo systemctl daemon-reload
2sudo systemctl enable --now k8s-certs-renew.timer

5️⃣ 타이머 상태 확인 #

1# 다음 실행 시각 확인
2systemctl list-timers k8s-certs-renew.timer
3
4# 서비스 로그 확인
5journalctl -u k8s-certs-renew.service --no-pager

출력 예시:

1NEXT LEFT LAST PASSED UNIT ACTIVATES
2Mon 2026-06-01 03:00:00 UTC 5d 10h - - k8s-certs-renew.timer k8s-certs-renew.service

🧪 동작 테스트 #

실제 만료가 임박하지 않아도 수동으로 서비스를 실행해 동작을 검증할 수 있습니다.

1# 수동 실행 (renew 분기는 타지 않고 check-expiration만 출력됨)
2sudo systemctl start k8s-certs-renew.service
3
4# 결과 확인
5journalctl -u k8s-certs-renew.service -f

만료 30일 미만 조건을 강제로 만들고 싶다면 스크립트의 if [ "$(getCertValidDays)" -lt 30 ] 부분을 임시로 -lt 9999로 변경한 뒤 실행 → 동작 확인 후 원복합니다.

⚠️ 운영 시 주의사항 #

항목	내용
HA 클러스터	모든 컨트롤 플레인 노드에 동일한 타이머를 설치해야 합니다. 노드별로 인증서가 따로 발급되어 있습니다.
CA 만료	CA 인증서는 `kubeadm certs renew all`로 갱신되지 않습니다. 10년 만료가 가까워지면 별도 절차가 필요합니다.
kubeconfig 사용자	`/root/.kube/config`만 갱신됩니다. 다른 사용자가 사용하는 kubeconfig도 별도로 업데이트해야 합니다.
외부 관리 인증서	`EXTERNALLY MANAGED=yes`로 표시되는 인증서는 갱신되지 않습니다. (예: Vault, cert-manager 발급)
etcd 백업	갱신 작업 전 반드시 etcd 스냅샷을 확보합니다.

❓ 자주 묻는 질문 #

Q. kubeadm으로 설치하지 않은 클러스터에도 적용 가능한가요? #

아니요. 이 스크립트는 kubeadm certs renew 명령에 의존합니다. kubespray로 설치한 클러스터는 kubeadm 기반이라 적용 가능하지만, k3s나 RKE2처럼 자체 인증서 관리 메커니즘이 있는 배포판은 각 도구가 제공하는 회전 방식을 사용해야 합니다.

Q. 인증서 유효기간을 1년보다 길게 설정할 수 있나요? #

가능합니다. kubeadm init 시 --cert-validity-period 플래그(v1.31+)를 사용하거나 ClusterConfiguration에서 certificateValidityPeriod를 설정합니다. 다만 보안 모범 사례는 짧은 주기로 자주 갱신하는 것이라, 1년을 유지하고 자동화를 도입하는 편이 권장됩니다.

Q. 갱신 시 클러스터가 중단되나요? #

컨트롤 플레인 Pod 재기동 시 수 초간 API 응답이 지연될 수 있지만, 워크로드(Pod)에는 영향이 없습니다. HA 클러스터라면 노드별 타이머를 동일 시각으로 설정하지 말고 5~10분 간격으로 분산하는 것이 안전합니다.

Q. `kubelet` 인증서는 어떻게 갱신되나요? #

kubelet 인증서는 RotateKubeletClientCertificate 기능 게이트(기본 활성화)에 의해 자동 회전됩니다. kubeadm certs renew가 관여하지 않습니다. /var/lib/kubelet/pki/ 아래의 kubelet-client-current.pem 심볼릭 링크가 주기적으로 갱신됩니다.

Q. 갱신 후 `kubectl` 명령이 실패합니다. #

/etc/kubernetes/admin.conf의 인증서는 갱신됐지만 사용자 홈의 ~/.kube/config가 갱신되지 않은 경우입니다. 다음 명령으로 동기화합니다.

1sudo cp /etc/kubernetes/admin.conf $HOME/.kube/config
2sudo chown $(id -u):$(id -g) $HOME/.kube/config

📚 참고 #

[Linux] 🔐 OpenSSL로 PFX 인증서 변환 후 Kubernetes TLS Secret 만들기

Mon, 18 May 2026 00:00:00 +0000

이 글에서는 Windows IIS나 CA에서 발급한 PFX(PKCS#12) 인증서 파일을 OpenSSL 명령으로 개인키(.key)와 인증서 체인(.crt) PEM 파일로 분리하고, 이를 kubectl create secret tls로 Kubernetes TLS Secret 매니페스트로 변환하는 워크플로우를 단계별로 다룹니다. Ingress·Argo CD 등에서 사용할 TLS Secret을 만들 때 그대로 활용할 수 있습니다.

📦 PFX(PKCS#12) 파일이란? #

PFX는 PKCS#12 표준을 따르는 바이너리 형식의 인증서 컨테이너입니다. 하나의 파일 안에 개인키 + 인증서 + 중간 CA 체인이 모두 패스워드로 암호화되어 들어 있어, Windows 환경에서 인증서를 백업하거나 이관할 때 주로 사용됩니다.

반면 Linux 진영(Nginx, HAProxy, Kubernetes Ingress 등)은 일반적으로 PEM 형식의 별도 파일(.key, .crt)을 요구합니다. 따라서 PFX를 그대로 사용할 수 없고 OpenSSL로 변환해야 합니다.

항목	PFX (PKCS#12)	PEM
형식	바이너리	Base64 텍스트
확장자	`.pfx`, `.p12`	`.key`, `.crt`, `.pem`
구성	키 + 인증서 + 체인 통합	파일별 분리
암호화	항상 패스워드 보호	선택적 (키만 암호화 가능)
주 사용처	Windows, IIS	Linux, Nginx, Kubernetes

🛠️ 사전 준비 #

OpenSSL과 kubectl이 설치되어 있어야 합니다.

1openssl version
2# OpenSSL 3.0.x 이상 권장
3
4kubectl version --client

작업할 PFX 파일과 그 파일의 패스워드를 미리 준비해 둡니다. 이 글에서는 다음과 같은 변수로 진행한다고 가정하겠습니다.

1PFX_FILE="example.com.pfx"
2PFX_PASS="ChangeMeStrongPass" # PFX 원본 패스워드
3TMP_PASS="ChangeMeTempPass" # 중간 작업용 임시 패스워드
4KEY_OUT="tls.key"
5CRT_OUT="fullchain.crt"
6NAMESPACE="argocd"
7SECRET_NAME="tls-example-com"

⚠️ 실제 운영 환경에서는 패스워드를 셸 히스토리에 남기지 않도록 -passin file:... 또는 환경변수(-passin env:VAR)를 사용하는 것이 안전합니다.

1️⃣ PFX에서 개인키 추출하기 #

먼저 PFX에서 개인키만 분리합니다. 이 시점에서는 키가 여전히 임시 패스워드(TMP_PASS)로 암호화된 PEM 형식으로 출력됩니다.

1openssl pkcs12 \
2 -passin pass:${PFX_PASS} \
3 -passout pass:${TMP_PASS} \
4 -in ${PFX_FILE} \
5 -nocerts \
6 -out tmp.key

옵션	설명
`pkcs12`	PKCS#12 형식 처리 서브커맨드
`-passin pass:...`	입력 PFX 파일의 패스워드
`-passout pass:...`	출력 PEM 키에 적용할 패스워드
`-in`	입력 PFX 파일 경로
`-nocerts`	인증서는 제외하고 키만 추출
`-out`	출력 파일 경로

Tip: -passout을 빼면 OpenSSL이 대화형으로 패스워드를 물어봅니다. 자동화 스크립트에서는 명시적으로 지정하는 편이 안정적입니다.

2️⃣ 개인키 패스워드 제거 (복호화) #

Kubernetes TLS Secret과 대부분의 Ingress 컨트롤러는 패스워드가 없는 PEM 키를 요구합니다. 따라서 임시 패스워드로 암호화된 키를 평문 RSA 키로 변환합니다.

1openssl rsa \
2 -passin pass:${TMP_PASS} \
3 -in tmp.key \
4 -out ${KEY_OUT}

명령이 성공하면 다음과 같은 메시지가 출력됩니다.

1writing RSA key

생성된 ${KEY_OUT} 파일은 다음과 같이 시작합니다.

1-----BEGIN RSA PRIVATE KEY-----
2MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQ...
3-----END RSA PRIVATE KEY-----

⚠️ 평문 개인키는 노출 시 즉시 인증서 폐기 사유가 됩니다. 작업이 끝나면 임시 파일(tmp.key)은 반드시 삭제하세요.

3️⃣ 인증서 체인 추출하기 #

이번에는 키를 제외한 클라이언트 인증서와 중간 CA 인증서를 한 파일로 묶어 추출합니다.

1openssl pkcs12 \
2 -passin pass:${PFX_PASS} \
3 -in ${PFX_FILE} \
4 -clcerts \
5 -nokeys \
6 -out ${CRT_OUT}

옵션	설명
`-clcerts`	클라이언트(서버) 인증서만 출력
`-nokeys`	개인키는 제외

체인이 분리되어 있어 풀체인(fullchain)으로 묶고 싶다면 -clcerts 옵션을 빼고, 출력된 인증서 블록 중 필요한 것을 확인해 정렬합니다.

1openssl pkcs12 \
2 -passin pass:${PFX_PASS} \
3 -in ${PFX_FILE} \
4 -nokeys \
5 -out fullchain.crt

Tip: Ingress에서 SSL Labs A+ 등급을 받으려면 서버 인증서 + 중간 CA 순서로 정렬된 풀체인이 필요합니다.

4️⃣ 추출 결과 검증하기 #

변환이 정상적으로 끝났는지 반드시 확인합니다.

인증서 정보 확인

1openssl x509 -in ${CRT_OUT} -noout -subject -issuer -dates

1subject=CN=example.com
2issuer=CN=Internal Issuing CA
3notBefore=Jan 1 00:00:00 2026 GMT
4notAfter=Dec 31 23:59:59 2026 GMT

개인키와 인증서가 한 쌍인지 확인 (모듈러스 비교)

1diff \
2 <(openssl rsa -in ${KEY_OUT} -modulus -noout) \
3 <(openssl x509 -in ${CRT_OUT} -modulus -noout)

출력이 없으면 같은 쌍입니다. 다르면 잘못된 키/인증서 조합이므로 Secret을 만들어도 TLS 핸드셰이크가 실패합니다.

5️⃣ Kubernetes TLS Secret YAML 만들기 #

kubectl create secret tls에 --dry-run=client -o yaml을 붙이면 클러스터에 반영하지 않고 매니페스트만 생성할 수 있습니다.

1kubectl create secret tls ${SECRET_NAME} \
2 -n ${NAMESPACE} \
3 --key ${KEY_OUT} \
4 --cert ${CRT_OUT} \
5 --dry-run=client -o yaml > tls-example-com.yaml

생성된 매니페스트는 다음과 같은 형태입니다.

1apiVersion: v1
2kind: Secret
3metadata:
4 name: tls-example-com
5 namespace: argocd
6type: kubernetes.io/tls
7data:
8 tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUZ...
9 tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpN...

Tip: Git에 커밋한다면 평문 Secret 대신 Sealed Secrets나 External Secrets Operator로 암호화하는 것이 좋습니다.

6️⃣ 클러스터에 적용 및 Ingress 연결 #

생성한 매니페스트를 적용합니다.

1kubectl apply -f tls-example-com.yaml
2
3kubectl get secret ${SECRET_NAME} -n ${NAMESPACE}
4# NAME TYPE DATA AGE
5# tls-example-com kubernetes.io/tls 2 5s

이후 Ingress 리소스에서 tls.secretName으로 참조합니다.

 1apiVersion: networking.k8s.io/v1
 2kind: Ingress
 3metadata:
 4 name: argocd-server-ingress
 5 namespace: argocd
 6spec:
 7 ingressClassName: nginx
 8 tls:
 9 - hosts:
10 - example.com
11 secretName: tls-example-com
12 rules:
13 - host: example.com
14 http:
15 paths:
16 - path: /
17 pathType: Prefix
18 backend:
19 service:
20 name: argocd-server
21 port:
22 number: 443

🧹 마무리 정리 #

작업이 끝나면 민감 파일을 안전하게 정리합니다.

1shred -u tmp.key ${KEY_OUT} 2>/dev/null || rm -f tmp.key ${KEY_OUT}

⚠️ shred는 ext4 등 일부 파일시스템에서만 효과적입니다. SSD·복사본 캐시·tmpfs에서는 완전 삭제가 보장되지 않으므로 작업 디렉터리 자체를 안전한 위치(예: tmpfs 마운트)로 잡는 편이 좋습니다.

🚀 한 번에 처리하는 스크립트 #

위 단계를 자동화한 예시 스크립트입니다.

 1#!/usr/bin/env bash
 2set -euo pipefail
 3
 4PFX_FILE="${1:?usage: $0 <pfx> <pfx-pass> <namespace> <secret-name>}"
 5PFX_PASS="${2}"
 6NAMESPACE="${3}"
 7SECRET_NAME="${4}"
 8TMP_PASS="$(openssl rand -hex 8)"
 9
10WORKDIR="$(mktemp -d)"
11trap 'rm -rf "${WORKDIR}"' EXIT
12
13openssl pkcs12 -passin "pass:${PFX_PASS}" -passout "pass:${TMP_PASS}" \
14 -in "${PFX_FILE}" -nocerts -out "${WORKDIR}/tmp.key"
15
16openssl rsa -passin "pass:${TMP_PASS}" \
17 -in "${WORKDIR}/tmp.key" -out "${WORKDIR}/tls.key"
18
19openssl pkcs12 -passin "pass:${PFX_PASS}" \
20 -in "${PFX_FILE}" -nokeys -out "${WORKDIR}/tls.crt"
21
22kubectl create secret tls "${SECRET_NAME}" \
23 -n "${NAMESPACE}" \
24 --key "${WORKDIR}/tls.key" \
25 --cert "${WORKDIR}/tls.crt" \
26 --dry-run=client -o yaml

❓ 자주 묻는 질문 #

Q. `-nodes` 옵션을 한 번에 쓰면 되지 않나요? #

가능합니다. openssl pkcs12 -in file.pfx -nodes -out all.pem 한 줄로 키와 인증서를 평문으로 함께 추출할 수 있습니다. 다만 키/인증서를 한 파일에 섞으면 kubectl create secret tls처럼 두 파일을 요구하는 도구에서 다시 분리해야 하므로, 단계별로 추출하는 편이 자동화에 유리합니다.

Q. “Mac verify error: invalid password” 오류가 납니다. #

PFX 파일의 패스워드가 틀린 경우입니다. 일부 환경에서는 OpenSSL 3.x에서 구버전 PFX의 해시 알고리즘을 거부하기도 합니다. 이 경우 -legacy 옵션을 추가해 보세요.

1openssl pkcs12 -legacy -passin pass:... -in file.pfx -out out.pem

Q. 평문 RSA 키와 PKCS#8 키 중 어느 쪽을 써야 하나요? #

대부분의 Kubernetes Ingress 컨트롤러는 두 형식을 모두 지원합니다. 다만 일부 신규 도구(예: Envoy 일부 빌드)는 PKCS#8을 선호합니다. 변환은 다음과 같이 합니다.

1openssl pkcs8 -topk8 -nocrypt -in tls.key -out tls.pkcs8.key

Q. `--dry-run=client`와 `--dry-run=server`의 차이는? #

client는 클라이언트(kubectl) 측에서만 매니페스트를 생성하고 API 서버로 보내지 않습니다. server는 API 서버까지 가서 어드미션 검증을 수행하지만 실제로 저장하지 않습니다. Secret YAML을 만들 때는 client로 충분합니다.

Q. Secret을 만든 뒤 인증서가 갱신되면 어떻게 하나요? #

같은 이름으로 kubectl create secret tls ... --dry-run=client -o yaml | kubectl apply -f -를 다시 실행하면 됩니다. Ingress 컨트롤러는 Secret 변경을 감지해 자동으로 새 인증서를 로드합니다.

📚 참고 #

[macOS] 👻 Ghostty 터미널 완전 정복: 설치부터 커스터마이징까지

Sat, 25 Apr 2026 00:00:00 +0000

Ghostty는 GPU 가속을 통해 압도적인 속도를 제공하는 최신 터미널입니다. Apple Silicon의 성능을 100% 활용하기 위한 필수 도구로, 설치부터 커스터마이징까지 핵심만 정리했습니다.

🚀 설치 및 폰트 세팅 #

1brew install --cask ghostty

⚠️ 반드시 아이콘이 포함된 Nerd Font를 사용해야 이모지 깨짐 현상을 방지할 수 있습니다.

추천 폰트는 JetBrainsMono Nerd Font입니다. 내장된 수백 개의 테마 목록은 아래 명령어로 확인할 수 있습니다.

1ghostty +list-themes

🛠️ Node / npx 명령어를 찾을 수 없을 때 (PATH 해결법) #

가장 빈번하게 발생하는 command not found: node 오류는 환경 변수 설정과 물리적 파일 연결 문제입니다.

STEP 1: .zshrc 환경 변수 최적화 #

Apple Silicon 기반 맥은 Homebrew 경로가 이전과 다릅니다. ~/.zshrc 최상단에 아래 설정을 추가합니다.

1# Homebrew 및 주요 경로를 최우선으로 설정 (중복 경로 방지)
2export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:$HOME/bin:$HOME/.local/bin:/usr/local/bin:$PATH"
3
4# Homebrew 환경변수 즉시 로드
5eval "$(/opt/homebrew/bin/brew shellenv)"

STEP 2: 그래도 안 된다면? Node 재설치 #

경로 설정 후에도 문제가 해결되지 않는다면 설치 자체가 깨진 것입니다. 재설치가 가장 확실한 해결책입니다.

1brew uninstall --ignore-dependencies node
2brew install node
3brew link --overwrite node

Tip: 설정 후에는 단순히 창을 닫지 말고 Cmd + Q로 Ghostty를 완전히 종료한 뒤 다시 실행하세요.

⌨️ 단축키 및 설정 즉시 반영 #

Ghostty의 진가는 마우스 없이 모든 것을 제어하는 단축키에서 나옵니다.

단축키	기능
`Cmd + Shift + ,`	설정 파일 즉시 반영 (재시작 불필요)
`Cmd + D`	화면 세로 분할
`Cmd + Shift + D`	화면 가로 분할
`Cmd + W`	현재 분할 창 닫기
`Cmd + Option + 방향키`	분할 창 간 이동

Tip: 설정 파일을 수정한 뒤 Cmd + Shift + ,로 즉시 반영하는 습관을 들이면 생산성이 크게 향상됩니다.

🎨 Starship 및 디테일 커스터마이징 #

터미널 프롬프트의 가독성을 높이기 위한 세부 설정입니다.

Starship 개행(빈 줄) 제거 #

Starship은 기본적으로 명령어 사이에 여백을 둡니다. ~/.config/starship.toml에서 아래 옵션으로 제거할 수 있습니다.

1add_newline = false # 명령어 사이 빈 줄 제거
2
3[line_break]
4disabled = true # 명령어를 한 줄로 깔끔하게 유지

분할 화면 경계선 색상 #

경계선을 테마 컬러와 맞추면 훨씬 세련된 환경이 구축됩니다. ~/.config/ghostty/config에 추가합니다.

1window-divider-color = "#3d59a1" # 테마에 맞는 색상값
2window-divider-width = 1

❓ 자주 묻는 질문 및 트러블슈팅 #

Q1. Expo 실행 시 ‘Unable to run simctl’ (Code 72) 에러 #

Xcode 경로 설정이 꼬인 문제입니다. 아래 명령어로 Xcode 위치를 다시 설정하세요.

1sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Q2. 기본 터미널은 되는데 Ghostty에서만 설정이 안 먹는 이유 #

Ghostty는 성능 최적화를 위해 일부 환경 파일을 생략하고 시작하는 경우가 있습니다. 아래 두 가지 방법을 함께 사용하면 해결됩니다.

1source ~/.zshrc

설정 파일 수동 로드 후 Cmd + Shift + ,로 즉시 반영합니다.

✅ 요약 #

Ghostty 설치 후 Nerd Font를 반드시 적용합니다.
~/.zshrc 맨 위에 Homebrew 경로를 최우선으로 배치합니다.
그래도 안 되면 고민하지 말고 brew reinstall node를 실행합니다.
Cmd + Shift + , 단축키를 활용해 실시간으로 환경을 다듬습니다.

[AI] 🤖 바이브 코딩의 핵심: Claude Code 프로젝트 문서 관리 완전 가이드

Tue, 21 Apr 2026 00:00:00 +0000

AI와 함께 개발하는 시대, 코드보다 중요한 건 문서입니다.

Claude Code를 활용한 프로젝트에서 문서는 “사람이 읽기 위한 기록"이 아니라 **“AI가 매 세션마다 기억을 복원하기 위한 장치”**입니다. 이 글에서는 어떤 언어, 어떤 프로젝트에서든 통용되는 문서 관리 전략과 실전 프롬프트를 공유합니다.

1️⃣ 왜 문서 관리가 바이브 코딩의 핵심인가 #

AI는 매 세션마다 기억을 잃습니다 #

사람은 프로젝트를 며칠 놓아둬도 코드를 보면 “아 맞아, 이랬지” 하고 감을 되찾습니다. 하지만 AI는 매번 0부터 다시 시작합니다. 이전 세션에서 아무리 좋은 대화를 했어도, 새 세션이 열리면 모든 맥락이 사라집니다.

이때 문서가 AI의 장기 기억 역할을 합니다. 잘 정리된 문서가 있으면 AI는 몇 초 만에 프로젝트 맥락을 파악하고 작업에 들어갈 수 있습니다. 문서가 없으면 매번 처음부터 설명해야 하고, 그만큼 토큰을 낭비하게 됩니다.

문서가 곧 토큰입니다 #

Claude Code에서 토큰 비용은 이전 대화 길이에 비례합니다. 매 응답마다 이전 대화 전체를 다시 처리하기 때문입니다.

110턴 대화: 이전 10턴 + 새 요청 → 토큰 적음
2100턴 대화: 이전 100턴 + 새 요청 → 토큰 많음 (10배)

문서가 잘 분리되어 있으면 AI가 “이 작업은 PLAN.md만 보면 되겠다"고 판단해서 불필요한 파일을 읽지 않습니다. 문서 분리 = 토큰 절약입니다.

사람을 위한 문서 vs AI를 위한 문서 #

전통적인 문서화는 “나중에 다른 사람이 읽을 때"를 위한 것이었습니다. AI 시대의 문서화는 “5분 후 새 세션의 AI가 읽을 때"를 위한 것입니다.

관점	사람을 위한 문서	AI를 위한 문서
목적	이해와 커뮤니케이션	맥락 복원과 작업 지시
형식	자유롭고 서술적	구조화되고 명확
업데이트	가끔 (릴리즈 때)	매 세션마다
분리 기준	독자별	역할별 (질문별)

2️⃣ 프로젝트 문서 구조 #

각 문서의 역할 #

핵심은 각 문서가 하나의 질문에만 답하도록 설계하는 것입니다.

문서	답하는 질문	AI가 읽는 시점	업데이트 빈도
README.md	“이 프로젝트는 뭐지?”	새 세션 첫 진입	릴리즈 때
CLAUDE.md	“어떻게 작업해야 하지?”	모든 세션에서 항상	매 세션
PLAN.md	“무엇을 만들어야 하지?”	기능 구현 시	계획 변경 시
CHANGELOG.md	“언제 뭐가 바뀌었지?”	버그 추적 시	매 작업 완료
DECISIONS.md	“왜 이렇게 했지?”	구조 변경 고민 시	중요 결정 시
DESIGN.md	“UI를 어떻게 만들지?”	UI 작업 시	디자인 변경 시

Tip: 문서가 하나의 거대한 파일이면 AI가 매번 전체를 읽느라 토큰을 낭비합니다. 분리하면 필요한 부분만 읽고 빠르게 작업에 들어갈 수 있습니다.

3️⃣ 각 문서 작성 가이드 #

CLAUDE.md — AI의 “작업 매뉴얼” #

CLAUDE.md는 Claude Code가 모든 세션에서 자동으로 읽는 파일입니다. 프로젝트 루트에 있으면 Claude Code가 시작할 때 가장 먼저 참고합니다. AI의 첫 번째 기억이자 가장 중요한 문서입니다.

포함해야 할 내용:

 1# 프로젝트명
 2
 3## 프로젝트 개요
 4한 줄 설명
 5
 6## 📚 문서 인덱스
 7- PLAN.md: 전체 기능 설계 및 개발 일정
 8- DESIGN.md: 디자인 시스템 (프론트엔드인 경우)
 9- CHANGELOG.md: 버전별 변경 이력
10- DECISIONS.md: 중요한 기술적 결정 기록
11
12## 🎯 코딩 규칙
13(프로젝트 기술 스택에 맞는 규칙)
14
15## 📋 현재 진행 상황
16- Phase 1: ✅ 완료
17- Phase 2: 🔄 진행 중 (어디까지 했는지)
18- Phase 3: ⬜ 미시작
19
20## 🔄 작업 완료 시 자동 수행 규칙
211. CHANGELOG.md에 변경사항 추가
222. 이 파일의 진행 상황 업데이트
233. git commit 메시지 규칙: feat:, fix:, chore:, docs:
24
25## ⚠️ 알려진 이슈
26- (현재 해결 중이거나 인지하고 있는 문제들)

Tip: 짧고 가볍게 유지합니다 (200줄 이하 권장). 세부 내용은 다른 문서로 링크하고, “현재 진행 상황"은 매 세션마다 업데이트합니다.

PLAN.md — 프로젝트의 “설계도” #

무엇을 만들어야 하는지, 어떤 순서로 만들지를 담는 문서입니다. 기능 정의, 데이터 모델, 화면 구성, 개발 일정이 포함됩니다.

포함해야 할 내용:

프로젝트 개요 (목적, 기술 스택)
핵심 기능 정의
화면/API/모듈 설계
데이터 모델 (TypeScript interface, Python dataclass, DB 스키마 등)
폴더 구조
Phase별 개발 일정 (체크리스트 형태)

Tip: Phase를 체크리스트(- [ ])로 작성하면 진행 추적이 쉽습니다. 너무 길어지면 기능별로 분리(docs/features/)하는 것을 권장합니다.

CHANGELOG.md — 변경 이력 추적 #

Keep a Changelog 형식을 사용합니다. AI가 버그 추적 시 “최근에 뭐가 바뀌었지?“를 빠르게 파악할 수 있습니다.

 1# Changelog
 2
 3## [Unreleased]
 4### Added
 5- 새로 추가된 기능
 6
 7## [1.0.0] - 2026-04-25
 8### Added
 9- 초기 출시
10### Fixed
11- 수정한 버그

DECISIONS.md — 기술 결정 기록 #

“왜 이 라이브러리를 썼지?”, “왜 이 구조로 했지?“에 대한 답을 남깁니다. 3개월 후 리팩토링할 때 과거의 맥락을 복원하는 데 결정적인 역할을 합니다.

1# Architecture Decisions
2
3## 001: 데이터 저장 방식
4- 날짜: 2026-04-20
5- 상태: 승인됨
6- 결정: 서버 없이 로컬 저장
7- 이유: 서버 운영비 불필요, 개인정보 미수집
8- 결과: 기기 간 동기화 불가 (v2.0에서 고려)

DESIGN.md — 디자인 일관성 (프론트엔드) #

AI는 매번 미세하게 다른 스타일을 생성할 수 있습니다. DESIGN.md가 있으면 색상, 폰트, 간격, 컴포넌트 규칙을 일관되게 유지할 수 있습니다.

포함해야 할 내용:

컬러 팔레트 (정확한 hex 코드)
타이포그래피 (폰트, 사이즈 스케일)
간격 시스템 (4, 8, 12, 16, 24, 32…)
모서리 둥글기 스케일
컴포넌트별 규칙 (버튼, 카드, 입력 필드)
애니메이션 가이드
카피라이팅 톤

4️⃣ 언어별 초기화 프롬프트 #

공통 프롬프트 (모든 프로젝트) #

어떤 기술 스택이든 이 프롬프트로 문서 구조를 초기화할 수 있습니다.

 1아래 지시사항을 순서대로 실행해줘.
 2
 3## 사전 파악
 4먼저 프로젝트 루트의 모든 설정 파일을 읽고
 5기술 스택, 구조, 현재 상태를 파악해.
 6
 7## 생성할 파일
 8
 9### 1. README.md
10- 프로젝트 소개, 주요 기능, 기술 스택
11- 설치 및 실행 방법
12- 뱃지 포함 (기술 스택 기반 자동 감지)
13
14### 2. CLAUDE.md
15- 문서 인덱스
16- 코딩 규칙 (기술 스택에 맞게 자동 설정)
17- 현재 진행 상황
18- 작업 완료 시 자동 수행 규칙
19
20### 3. PLAN.md
21- 프로젝트 개요
22- 핵심 기능 정의
23- 데이터 모델
24- 폴더 구조
25- Phase별 개발 일정 (체크리스트)
26
27### 4. CHANGELOG.md
28- Keep a Changelog 형식
29- 현재까지 작업 내용 기반으로 초안
30
31### 5. DECISIONS.md
32- ADR 형식
33- 프로젝트에서 파악된 기술 결정 자동 추출
34
35## 완료 후
36각 파일 생성 결과를 체크리스트로 보고

React Native / TypeScript 프로젝트 (모바일 앱) #

 1아래 지시사항을 순서대로 실행해줘.
 2
 3## 사전 파악
 4package.json, tsconfig.json, app.json을 읽고
 5기술 스택과 현재 프로젝트 상태를 파악해.
 6
 7## 생성할 파일
 8
 9### 1. README.md
10- 앱 소개, 주요 기능, 기술 스택
11- 설치: npm install, npx expo start
12- 뱃지: React Native, Expo, TypeScript
13
14### 2. CLAUDE.md (아래 구조로)
15- 문서 인덱스 (README, PLAN, DESIGN, CHANGELOG, DECISIONS)
16- 코딩 규칙:
17 - TypeScript strict mode
18 - 함수형 컴포넌트 + hooks
19 - StyleSheet.create 사용 (인라인 최소화)
20 - camelCase (변수), PascalCase (컴포넌트/타입)
21- 현재 진행 상황 (Phase별 체크박스)
22- 작업 완료 시: CHANGELOG 업데이트, 진행 상황 갱신
23- 커밋 규칙: feat:, fix:, chore:, docs:, refactor:
24
25### 3. PLAN.md
26- 프로젝트 개요 (목적, 플랫폼, 기술 스택)
27- 화면 구성 (탭/스택 네비게이션 구조)
28- 핵심 기능 정의 (우선순위 P0/P1/P2)
29- TypeScript interface 정의
30- 폴더 구조 (app/, components/, stores/, services/)
31- Phase별 개발 일정 (체크리스트)
32- 배포 요건 (App Store, Google Play)
33
34### 4. DESIGN.md
35- 컬러 팔레트 (hex 코드)
36- 타이포그래피 (폰트, 사이즈 스케일)
37- 간격 시스템 (4/8/12/16/24/32)
38- 모서리 둥글기 스케일
39- 컴포넌트별 규칙 (버튼, 카드, 입력 필드)
40- 애니메이션 가이드
41- 다크 모드 대응
42
43### 5. CHANGELOG.md + DECISIONS.md
44- 현재까지 작업 기반으로 초안
45
46## 완료 후 체크리스트로 보고

Python 프로젝트 (백엔드 API / 데이터 / 자동화) #

 1아래 지시사항을 순서대로 실행해줘.
 2
 3## 사전 파악
 4requirements.txt (또는 pyproject.toml, Pipfile),
 5main 진입점, 기존 코드 구조를 읽고 파악해.
 6
 7## 생성할 파일
 8
 9### 1. README.md
10- 프로젝트 소개, 주요 기능
11- 설치: pip install -r requirements.txt
12- 실행: python main.py 또는 uvicorn/flask 명령어
13- 환경 변수 설명 (.env.example 포함)
14- 뱃지: Python 버전, 프레임워크
15
16### 2. CLAUDE.md (아래 구조로)
17- 문서 인덱스
18- 코딩 규칙:
19 - PEP 8 준수
20 - Type hints 필수
21 - docstring: Google style
22 - 함수는 단일 책임 원칙
23 - 테스트: pytest 사용
24- 현재 진행 상황
25- 작업 완료 시: CHANGELOG 업데이트, pytest 실행
26- 커밋 규칙: feat:, fix:, chore:
27
28### 3. PLAN.md
29- 프로젝트 개요 (목적, 기술 스택)
30- 핵심 기능/모듈 정의
31- API 엔드포인트 설계 (REST/GraphQL인 경우)
32- 데이터 모델 (SQLAlchemy/Pydantic/dataclass)
33- 폴더 구조 (app/, models/, services/, utils/, tests/)
34- Phase별 개발 일정 (체크리스트)
35
36### 4. CHANGELOG.md + DECISIONS.md
37- 현재까지 작업 기반으로 초안
38
39## 완료 후 체크리스트로 보고

Swift 프로젝트 (iOS 네이티브 앱) #

 1아래 지시사항을 순서대로 실행해줘.
 2
 3## 사전 파악
 4.xcodeproj 또는 Package.swift, Info.plist,
 5기존 Swift 파일 구조를 읽고 파악해.
 6
 7## 생성할 파일
 8
 9### 1. README.md
10- 앱 소개, 주요 기능, 스크린샷 섹션
11- 요구사항: Xcode 버전, iOS 최소 버전
12- 빌드: Xcode에서 열고 Run
13- 뱃지: Swift, iOS, Xcode
14
15### 2. CLAUDE.md (아래 구조로)
16- 문서 인덱스
17- 코딩 규칙:
18 - Swift API Design Guidelines 준수
19 - MVVM 또는 SwiftUI+Observable 아키텍처
20 - guard let 우선 사용 (if let보다)
21 - Protocol 기반 의존성 주입
22 - 네이밍: camelCase (프로퍼티), PascalCase (타입)
23- 현재 진행 상황
24- 작업 완료 시: CHANGELOG 업데이트, 빌드 확인
25- 커밋 규칙: feat:, fix:, chore:
26
27### 3. PLAN.md
28- 앱 개요 (목적, 타겟 iOS 버전)
29- 화면 구성 (NavigationStack/TabView 구조)
30- 핵심 기능 정의
31- 데이터 모델 (struct, Codable)
32- 폴더 구조 (Views/, Models/, ViewModels/, Services/)
33- Phase별 개발 일정
34
35### 4. DESIGN.md
36- Color Assets 정의
37- Typography 스케일
38- 컴포넌트별 규칙
39- 다크 모드 대응
40- SF Symbols 사용 가이드
41
42### 5. CHANGELOG.md + DECISIONS.md
43
44## 완료 후 체크리스트로 보고

Java / Kotlin 프로젝트 (Android / Spring Boot) #

 1아래 지시사항을 순서대로 실행해줘.
 2
 3## 사전 파악
 4build.gradle (또는 pom.xml), 기존 소스 구조,
 5application.properties를 읽고 파악해.
 6
 7## 생성할 파일
 8
 9### 1. README.md
10- 프로젝트 소개, 주요 기능
11- 요구사항: JDK 버전, Gradle/Maven
12- 빌드: ./gradlew build (또는 mvn package)
13- 실행: ./gradlew bootRun (Spring) 또는 Android Studio
14- 뱃지: Java/Kotlin, Spring Boot/Android
15
16### 2. CLAUDE.md (아래 구조로)
17- 문서 인덱스
18- 코딩 규칙:
19 - [Android] Kotlin 우선, Jetpack Compose UI
20 - [Spring] Java/Kotlin, 계층 구조 (Controller→Service→Repository)
21 - 네이밍: camelCase (메서드), PascalCase (클래스)
22 - 예외 처리: 커스텀 Exception 사용
23 - 테스트: JUnit 5 + Mockito
24- 현재 진행 상황
25- 작업 완료 시: CHANGELOG 업데이트, 빌드 확인
26- 커밋 규칙: feat:, fix:, chore:
27
28### 3. PLAN.md
29- 프로젝트 개요
30- [Android] 화면 구성 (Navigation Graph)
31- [Spring] API 엔드포인트 설계
32- 데이터 모델 (Entity, DTO)
33- 폴더 구조
34- Phase별 개발 일정
35
36### 4. CHANGELOG.md + DECISIONS.md
37
38## 완료 후 체크리스트로 보고

5️⃣ 보안 가이드: API Key와 환경 변수 #

AI가 저지르는 보안 실수 #

바이브 코딩에서 가장 흔한 보안 사고는 AI가 환경 변수를 잘못 다루는 것입니다.

1실제 사고 사례:
2 1. AI가 .env의 API Key를 코드에 하드코딩
3 2. AI가 CLAUDE.md에 실제 키 값을 기록
4 3. AI가 .env 파일을 git commit에 포함
5 4. AI가 디버깅 중 콘솔에 키를 출력하는 코드 생성
6 5. AI가 README에 "실행 시 이 키를 넣으세요"라며 실제 값 노출

⚠️ 한번 GitHub에 올라간 키는 몇 초 내에 봇이 수집합니다. 삭제해도 git 히스토리에 남아있어서 완전 제거가 어렵습니다.

CLAUDE.md에 넣어야 할 보안 규칙 #

 1## 🔒 보안 규칙 (절대 위반 금지)
 2
 3### 환경 변수
 4- .env, .env.local 파일의 실제 값을 절대 코드나 문서에 기록하지 말 것
 5- API Key, Secret, Token, Password를 절대 하드코딩하지 말 것
 6- 환경 변수는 반드시 process.env.VARIABLE_NAME으로 참조
 7- 디버깅 시에도 console.log로 환경 변수 값을 출력하지 말 것
 8- 커밋 전 반드시 .env가 .gitignore에 포함되어 있는지 확인
 9
10### 문서에 적을 때
11- 필요한 환경 변수의 "이름"만 기록 (값은 절대 기록 금지)
12- .env.example 파일에 빈 값으로 목록만 제공
13
14### 금지 패턴
15❌ const API_KEY = "sk-abc123..."
16❌ OPENWEATHER_API_KEY=abc123 (CLAUDE.md에 실제 값)
17❌ console.log("Key:", process.env.API_KEY)
18❌ fetch(`...?key=abc123...`)
19
20### 허용 패턴
21✅ const API_KEY = process.env.OPENWEATHER_API_KEY
22✅ OPENWEATHER_API_KEY=your_key_here (.env.example)
23✅ "환율 API Key가 필요합니다 (.env 참고)"

.env.example 파일 관리 #

프로젝트에 필요한 환경 변수를 .env.example에 기록합니다. 이 파일은 git에 포함해도 안전합니다 (실제 값이 없으므로).

1# .env.example (git에 포함 OK)
2OPENWEATHER_API_KEY=your_key_here
3EXCHANGE_RATE_API_KEY=your_key_here
4GOOGLE_MAPS_API_KEY=your_key_here
5ADMOB_ANDROID_APP_ID=ca-app-pub-xxx
6ADMOB_IOS_APP_ID=ca-app-pub-xxx

1# .env (git에 절대 포함 금지)
2OPENWEATHER_API_KEY=abc123실제키값
3EXCHANGE_RATE_API_KEY=xyz789실제키값

.gitignore 필수 항목 #

 1# .gitignore
 2.env
 3.env.local
 4.env.production
 5.env.*.local
 6*.keystore
 7*.jks
 8*.p12
 9google-services.json
10GoogleService-Info.plist

CLAUDE.md에 환경 변수 목록 기록 방법 #

 1## 🔑 필요한 환경 변수
 2
 3| 변수명 | 용도 | 발급처 |
 4|--------|------|--------|
 5| OPENWEATHER_API_KEY | 날씨 조회 | openweathermap.org |
 6| EXCHANGE_RATE_API_KEY | 환율 조회 | exchangerate-api.com |
 7| GOOGLE_MAPS_API_KEY | 지도 (Android) | Google Cloud Console |
 8
 9⚠️ 실제 값은 .env 파일에만 저장. 이 문서에 절대 기록 금지.
10⚠️ .env.example 참고하여 로컬에 .env 파일 생성할 것.

언어별 환경 변수 참조 방식 #

1# Python
2import os
3API_KEY = os.environ.get("OPENWEATHER_API_KEY")
4# 또는 python-dotenv 사용
5from dotenv import load_dotenv
6load_dotenv()

1// TypeScript / React Native
2const API_KEY = process.env.EXPO_PUBLIC_OPENWEATHER_API_KEY;
3// Expo에서는 EXPO_PUBLIC_ 접두사 필요

1// Swift (iOS)
2let apiKey = ProcessInfo.processInfo.environment["OPENWEATHER_API_KEY"]
3// 또는 xcconfig 파일 사용

1// Java / Kotlin (Android)
2String apiKey = BuildConfig.OPENWEATHER_API_KEY;
3// build.gradle에서 local.properties 참조

만약 키가 노출됐다면 #

11. 즉시 해당 서비스에서 키 재발급 (기존 키 비활성화)
22. git 히스토리에서 제거:
3 git filter-branch 또는 BFG Repo-Cleaner 사용
43. GitHub에서 "Secret scanning alert" 확인
54. .gitignore에 .env 추가 확인
65. 새 키로 .env 업데이트

6️⃣ 세션 관리 전략 #

세션의 원리 #

Claude Code의 토큰 비용은 세션 길이에 비례합니다. 한 세션에서 대화가 길어질수록 매 응답마다 이전 대화 전체를 다시 처리해야 하기 때문입니다.

1세션 A (짧은 세션 3개):
2 세션 1: 20턴 → 20턴분 토큰
3 세션 2: 15턴 → 15턴분 토큰
4 세션 3: 10턴 → 10턴분 토큰
5
6세션 B (긴 세션 1개):
7 45턴 → 1+2+3+...+45 = 누적 1,035턴분 토큰
8 (이전 대화가 매번 재처리되므로)

같은 작업이라도 짧은 세션 여러 개가 긴 세션 하나보다 토큰 효율이 좋습니다.

효율적인 세션 패턴 #

 1작업 단위로 세션 분리 (가장 중요):
 2 오전: "체크리스트 버그 수정" → exit
 3 오후: "지도 탭 구현" → exit (새 세션)
 4 저녁: "문서 정리" → exit (새 세션)
 5
 6긴 세션은 /compact로 압축:
 7 작업 중 대화가 20턴 넘어가면
 8 /compact 실행 → 이전 내용 요약 → 토큰 절약
 9
10/resume으로 이전 세션 이어하기:
11 claude --resume → 세션 목록에서 선택
12
13effort 레벨 조절:
14 /effort low → 오타 수정, 텍스트 변경
15 /effort medium → 일반 기능 구현 (기본값)
16 /effort high → 복잡한 로직, 멀티파일 작업
17 /effort max → 아키텍처 설계, 풀리지 않는 디버깅

세션 끊는 타이밍 #

1끊어야 할 때:
2 ✅ 하나의 작업/이슈가 완료됐을 때
3 ✅ 다른 주제로 넘어갈 때
4 ✅ 대화가 20~30턴 이상 길어졌을 때
5
6유지해야 할 때:
7 🔄 같은 파일을 연속 수정 중일 때
8 🔄 디버깅이 진행 중일 때
9 🔄 관련된 작업을 연속으로 할 때

7️⃣ Claude Code 자동화 설정 #

슬래시 커맨드 등록 #

~/.claude/commands/ 폴더에 마크다운 파일을 만들면 어떤 프로젝트에서든 /명령어로 실행할 수 있습니다.

1mkdir -p ~/.claude/commands

문서 초기화 커맨드 (~/.claude/commands/init-docs.md):

 1# 프로젝트 문서 초기화
 2
 3이 프로젝트에 다음 문서 구조를 생성해줘.
 4실행 전 설정 파일들을 읽고 기술 스택을 파악할 것.
 5
 6## 생성할 파일
 71. README.md (프로젝트 소개, 기술 스택, 설치 방법)
 82. CLAUDE.md (문서 인덱스, 코딩 규칙, 진행 상황, 자동 수행 규칙)
 93. PLAN.md (기능 설계, 데이터 모델, 폴더 구조, 개발 일정)
104. CHANGELOG.md (Keep a Changelog 형식)
115. DECISIONS.md (ADR 형식)
12
13## 규칙
14- 기술 스택은 설정 파일에서 자동 감지
15- 코딩 규칙은 기술 스택에 맞게 자동 설정
16- 기존 파일이 있으면 덮어쓰지 말고 병합 제안
17
18## 완료 후
19생성 결과를 체크리스트로 보고

사용법:

1cd any-project
2claude
3/init-docs

상태 점검 커맨드 (~/.claude/commands/check-status.md):

 1# 프로젝트 상태 점검
 2
 3현재 프로젝트 상태를 점검하고 보고해줘.
 4
 5## 점검 항목
 61. CLAUDE.md의 진행 상황이 실제 코드와 일치하는지
 72. CHANGELOG.md가 최신인지
 83. 알려진 버그나 TODO가 남아있는지
 94. 빌드/테스트가 정상적으로 통과하는지
105. 다음으로 해야 할 작업이 뭔지
11
12## 보고 형식
13- 현재 상태 요약
14- 불일치 항목 (있으면)
15- 다음 작업 추천

문서 정리 커맨드 (~/.claude/commands/clean-docs.md):

 1# 문서 정리
 2
 3프로젝트의 모든 문서를 점검하고 정리해줘.
 4
 5## 작업
 61. 중복된 내용 통합
 72. 오래되어 관련 없어진 내용 제거
 83. 각 문서의 역할이 명확한지 확인
 94. 문서 간 링크가 올바른지 확인
105. 필요하면 새 문서 분리 제안
11
12## 대상 파일
13README.md, CLAUDE.md, PLAN.md, CHANGELOG.md, DECISIONS.md

글로벌 CLAUDE.md 설정 #

~/.claude/CLAUDE.md에 모든 프로젝트 공통 규칙을 넣어두면 어떤 프로젝트에서든 자동으로 적용됩니다.

1touch ~/.claude/CLAUDE.md

 1# 글로벌 Claude Code 규칙
 2
 3## 모든 프로젝트 공통
 4
 5### 문서 규칙
 6- README.md, CLAUDE.md, CHANGELOG.md는 필수
 7- 작업 완료 시 CHANGELOG.md 업데이트
 8- 중요한 결정은 DECISIONS.md에 기록
 9
10### 커밋 메시지
11- feat: 새 기능
12- fix: 버그 수정
13- chore: 설정, 의존성
14- docs: 문서 변경
15- refactor: 리팩토링
16
17### 작업 스타일
18- 큰 작업은 작은 단계로 나눠서 진행
19- 각 단계 완료 후 git commit
20- 불확실한 부분은 먼저 질문하고 진행

8️⃣ 실전 팁 #

문서 길이 관리 #

1CLAUDE.md: 200줄 이하 (허브 역할, 짧게)
2PLAN.md: 500줄 이하 (넘으면 기능별 분리)
3DESIGN.md: 300줄 이하
4CHANGELOG: 제한 없음 (시간순 누적)
5DECISIONS: 제한 없음 (결정순 누적)

문서 간 링크 활용 #

1# PLAN.md
2상세 디자인은 [DESIGN.md](./DESIGN.md) 참고.
3AdMob 연기 결정은 [DECISIONS.md](./DECISIONS.md#003) 참고.

AI가 링크를 따라가면서 필요한 정보만 골라 읽을 수 있습니다.

AI에게 문서 업데이트 위임하기 #

매번 직접 수정하지 말고 AI에게 맡기면 됩니다.

1체크리스트 버그 수정 완료했어.
2CHANGELOG.md에 추가하고,
3CLAUDE.md 진행 상황도 업데이트해줘.

새 세션 시작 시 컨텍스트 최소화 #

1PLAN.md의 Phase 3 섹션만 읽고,
2예산 탭의 환율 변환 기능을 구현해줘.

Tip: “전체를 읽어줘"보다 “특정 섹션만 읽어줘"가 토큰을 절약합니다.

9️⃣ 정리 #

바이브 코딩에서 문서 관리는 선택이 아닌 필수입니다.

 1문서가 없는 AI 개발:
 2 매 세션마다 처음부터 설명
 3 → 토큰 낭비
 4 → 일관성 없는 코드
 5 → 매번 다른 스타일
 6
 7문서가 있는 AI 개발:
 8 새 세션에서도 즉시 맥락 파악
 9 → 토큰 절약
10 → 일관된 코드
11 → 누적되는 품질

시작은 간단합니다.

1cd my-project
2claude
3/init-docs

이 한 줄이면 됩니다. 나머지는 AI가 알아서 해줍니다. 그리고 그 AI가 잘 해주도록 만드는 게 바로 문서입니다.

“코드는 AI가 쓴다. 문서는 내가 설계한다.”

이것이 바이브 코딩 시대의 개발자 역할입니다.

[AI Assignment - Python] 🐍 제너레이터 실전 — batch, file reader, infinite ID

Sun, 19 Apr 2026 00:00:00 +0000

🎯 과제 개요 #

데이터 파이프라인에서 자주 쓰이는 제너레이터 3개를 구현해봤습니다.

batch_generator — 데이터를 배치 단위로 나누기
file_line_reader — 대용량 파일을 한 줄씩 읽기 (빈 줄 처리 옵션)
infinite_id_generator — 무한 고유 ID 생성기

요구사항: 모든 함수에 타입 힌트, Generator 또는 Iterator 사용, 파일이 없으면 FileNotFoundError 발생, next()와 for 두 방식 모두 테스트.

📌 제너레이터 기본 개념 #

제너레이터는 값을 한 번에 다 만들지 않고, 필요할 때 하나씩 만들어내는 함수입니다. return 대신 yield를 사용합니다.

 1# 일반 함수 — 리스트를 통째로 메모리에 올림
 2def get_numbers(n: int) -> list[int]:
 3 result = []
 4 for i in range(n):
 5 result.append(i ** 2)
 6 return result # 1억 개면 메모리 폭발
 7
 8# 제너레이터 — 하나씩 생성
 9def gen_numbers(n: int):
10 for i in range(n):
11 yield i ** 2 # 1억 개여도 메모리 1개분만 사용

1️⃣ batch_generator #

1차 시도 #

1def batch_generator(data: list, batch_size: int):
2 for i in range(len(data)):
3 if i * batch_size >= len(data):
4 return
5 yield data[i * batch_size:i * batch_size + batch_size]

동작은 맞지만 range(len(data))를 만들어놓고 대부분 버립니다. 10개 데이터면 range(10)이지만 실제로 필요한 건 4번 루프뿐입니다.

✅ 개선: `range`의 step 인자 활용 #

range(start, stop, step)의 세 번째 인자로 증가폭을 지정할 수 있습니다.

1def batch_generator(data: list, batch_size: int) -> Iterator[list]:
2 for i in range(0, len(data), batch_size): # 0, 3, 6, 9
3 yield data[i:i + batch_size]

슬라이싱이 범위를 초과해도 에러 없이 잘라주기 때문에(data[9:12] → [9]), 조건문도 return도 필요하지 않습니다.

2️⃣ file_line_reader #

여러 번 헤맸던 함수입니다. 시도별로 정리합니다.

1차 시도 — 두 가지 문제 #

1def file_line_reader(filepath: str, skip_empty: bool = True):
2 try:
3 with open(filepath, 'r', encoding='utf-8') as file:
4 for line in file:
5 yield line.strip()
6 except FileNotFoundError:
7 print("파일을 찾을 수 없습니다. 경로를 확인해주세요.")

① skip_empty를 구현하지 않음. 파라미터는 받아놓고 전혀 사용하지 않아 빈 줄이 그대로 출력됩니다.

② 에러를 print로 덮어버림. 요구사항은 “FileNotFoundError를 발생시킨다"였는데, try/except로 잡아서 조용히 처리하고 있었습니다.

1# 호출자 입장에서
2for line in file_line_reader("없는파일.csv"):
3 process(line)
4# → "파일을 찾을 수 없습니다" 출력 후 for 루프 0회 실행
5# → 버그가 조용히 숨어버림

⚠️ 에러를 print로 덮어버리면 호출자는 무엇이 잘못됐는지 알 수 없습니다. 에러는 숨기지 말고 발생시켜서 호출자가 처리하게 해야 합니다.

2차 시도 — `skip_empty` 의미를 잘못 이해 #

 1def file_line_reader(filepath: str, skip_empty: bool = True):
 2 if os.path.exists(filepath):
 3 with open(filepath, 'r', encoding='utf-8') as file:
 4 for line in file:
 5 if skip_empty:
 6 yield line.strip()
 7 else:
 8 yield line
 9 else:
10 print(f"'{filepath}' 파일을 찾을 수 없습니다.")

os.path.exists로 먼저 체크하도록 바꿨지만 여전히 없을 때 print만 하고 조용히 끝납니다. 그리고 skip_empty의 의미를 완전히 잘못 이해했습니다.

내가 구현한 의미	실제 의미
`True` → `strip()` 적용	`True` → 빈 줄 건너뛰기
`False` → `strip()` 미적용	`False` → 빈 줄도 yield

strip()은 skip_empty와 무관하게 항상 적용되어야 합니다. skip_empty는 strip 이후 빈 문자열이면 건너뛸지 결정하는 플래그입니다.

✅ 3차 시도 (완성) — EAFP 패턴 #

1def file_line_reader(filepath: str, skip_empty: bool = True) -> Iterator[str]:
2 with open(filepath, 'r', encoding='utf-8') as file:
3 for line in file:
4 stripped = line.strip()
5 if skip_empty and not stripped: # 빈 문자열은 falsy
6 continue
7 yield stripped

EAFP 패턴 적용. os.path.exists로 먼저 체크(LBYL)하지 않고, open()이 알아서 FileNotFoundError를 던지도록 둡니다. 이것이 파이썬 철학인 EAFP(Easier to Ask for Forgiveness than Permission) 입니다.

skip_empty 올바른 구현. strip()은 항상 적용하고, 빈 문자열이면 continue로 건너뜁니다. Python에서 빈 문자열은 falsy이므로 not stripped로 체크할 수 있습니다.

Tip: LBYL(“되는지 확인하고 해라”)보다 EAFP(“일단 해보고 안 되면 예외”)가 더 파이썬다운 방식입니다.

3️⃣ infinite_id_generator #

1def infinite_id_generator(prefix: str = "item") -> Iterator[str]:
2 count = 0
3 while True:
4 count += 1
5 yield f"{prefix}_{count:04d}"

while True + yield로 무한 생성합니다. f"{count:04d}"는 4자리 0패딩입니다. 제너레이터는 next() 호출 사이에 상태를 유지하므로 count가 자동으로 누적됩니다.

▶️ 실행 결과 #

=== batch_generator ===
[0, 1, 2]
[3, 4, 5]
[6, 7, 8]
[9]

=== file_line_reader(skip_empty=True) ===
'서울,15.2,45,32.1'
'부산,17.8,61,22.3'
'대구,19.3,38,41.5'
'인천,14.7,55,29.8'

=== file_line_reader(skip_empty=False) ===
'서울,15.2,45,32.1'
'부산,17.8,61,22.3'
''
'대구,19.3,38,41.5'
''
'인천,14.7,55,29.8'

=== 없는 파일 ===
FileNotFoundError: [Errno 2] No such file or directory: 'nonexistent.csv'

=== infinite_id_generator ===
user_0001
user_0002
user_0003

🏷️ 타입 힌트 — `Generator` vs `Iterator` #

Generator의 타입 파라미터는 3개입니다.

1Generator[YieldType, SendType, ReturnType]

YieldType — yield로 내보내는 값의 타입
SendType — .send()로 제너레이터에 값을 보낼 때의 타입
ReturnType — 제너레이터가 끝날 때 return하는 값의 타입

대부분은 YieldType만 신경쓰면 되므로 나머지는 None으로 두게 됩니다. 더 간결한 방법은 Iterator를 사용하는 것입니다.

1from collections.abc import Iterator
2
3def batch_generator(data: list, batch_size: int) -> Iterator[list]:
4 ...

Tip: .send()나 return 값을 사용할 일이 없다면 Generator[T, None, None] 대신 Iterator[T]가 훨씬 깔끔합니다.

💡 이번 과제에서 배운 것 #

yield의 기본 동작: 함수가 yield를 만나면 값을 내보내고 일시정지합니다. 다음 호출에서 그 자리부터 재개합니다.

range(start, stop, step): 증가폭을 직접 지정할 수 있습니다. range(0, len(data), batch_size) 같은 패턴은 파이썬 어디서든 활용됩니다.

EAFP 패턴: os.path.exists로 먼저 체크(LBYL)하는 대신, 일단 open()을 시도하고 예외가 발생하면 처리(EAFP)하는 것이 더 파이썬답습니다.

에러를 숨기지 말기: try/except로 잡아서 print로 덮는 것은 디버깅을 어렵게 만듭니다. 호출자가 예외를 받아서 처리할 수 있도록 자연스럽게 발생시켜야 합니다.

skip_empty 같은 파라미터의 의미: 이름만 보고 추측하지 말고 요구사항을 정확히 읽어야 합니다.

타입 힌트 간결하게: Generator[T, None, None] 대신 Iterator[T]를 사용합시다.

🔄 반복해서 나타난 패턴 #

세 과제를 진행하면서 반복적으로 마주친 두 가지 패턴이 있습니다.

① 하드코딩 의존: result == 'done', isinstance(arg, int), skip_empty 오해 — 전부 특정 값이나 상황에 의존하는 코드를 작성하는 습관입니다. 범용 함수를 만들 때는 의도적으로 추상화해야 합니다.

② 에러 숨김: 에러를 값으로 반환하거나 print 후 조용히 종료하면 호출자는 무엇이 잘못됐는지 알 수 없습니다. 예외는 적절한 레이어에서 처리되어야 합니다.

[AI Assignment - Python] 🎀 데코레이터 완전 정복 — timer, retry, validate_types 직접 구현

Tue, 14 Apr 2026 00:00:00 +0000

🎯 과제: 실무형 데코레이터 3개 구현 #

@timer — 함수 실행 시간 측정
@retry(max_attempts=3) — 실패 시 자동 재시도
@validate_types — 타입 힌트 기반 런타임 타입 검증

모든 데코레이터에 functools.wraps를 적용하는 것이 요구사항이었습니다.

📐 데코레이터 기본 구조 #

과제에 들어가기 전에 먼저 기본 구조를 정리했습니다.

 1def my_decorator(func):
 2 def wrapper(*args, **kwargs):
 3 # 함수 실행 전에 할 일
 4 result = func(*args, **kwargs)
 5 # 함수 실행 후에 할 일
 6 return result
 7 return wrapper
 8
 9# @my_decorator는 사실 이것과 같습니다:
10# say_hello = my_decorator(say_hello)

인자를 받는 데코레이터는 한 겹 더 감쌉니다:

1def repeat(n: int): # ← 데코레이터 팩토리
2 def decorator(func): # ← 실제 데코레이터
3 def wrapper(*args, **kwargs):
4 ...
5 return wrapper
6 return decorator

1️⃣ @timer #

1차 시도 #

 1def timer(func):
 2 def running_check(*args, **kwargs):
 3 start_time = time.time()
 4 result = func(*args, **kwargs)
 5 end_time = time.time()
 6 if result == 'done':
 7 text = f"출력: slow_function 실행 시간: {end_time - start_time:.2f}초"
 8 return text
 9 print(running_check().__repr__())
10 return running_check

지적받은 점 3가지 #

if result == 'done' 하드코딩: 데코레이터는 어떤 함수든 감쌀 수 있어야 합니다. 'done'을 반환하는 함수에서만 작동하면 범용성이 없습니다.

text를 반환하고 result를 소실: 원래 함수의 반환값을 돌려줘야 하는데, 출력 문자열을 반환하고 있었습니다. if를 타지 않으면 text가 미정의되어 NameError도 발생합니다.

데코레이터 안에서 직접 실행: print(running_check()) 이 줄 때문에 @timer가 붙는 순간 함수가 바로 실행됩니다. 데코레이터는 감싼 함수를 반환만 해야 합니다.

1# 실행 타이밍 이해
2@timer # ← 이 시점에 timer(slow_function) 실행
3def slow_function(): # → wrapper를 반환만 해야 함
4 ...
5
6slow_function() # ← 이 시점에 wrapper() 실행

2차 시도 (완성) #

1def timer(func):
2 @wraps(func)
3 def wrapper(*args, **kwargs):
4 start = time.time()
5 result = func(*args, **kwargs)
6 elapsed = time.time() - start
7 print(f"{func.__name__} 실행 시간: {elapsed:.2f}초")
8 return result
9 return wrapper

Tip: 핵심 패턴 — wrapper는 result를 반환, 데코레이터는 wrapper를 반환합니다.

2️⃣ @retry #

1차 시도 #

1def retry(max_attempts: int):
2 def decorator(func):
3 def wrapper(*args, **kwargs):
4 for _ in range(max_attempts):
5 result = func(*args, **kwargs)
6 return result
7 return wrapper
8 return decorator

재시도 로직을 데코레이터 안이 아니라 __main__에 따로 작성했습니다:

1# __main__에서 직접 재시도 — 데코레이터의 의미가 없어짐
2for i in range(max_attempts):
3 try:
4 check = unstable_api_call()
5 if check['status'] == 'ok':
6 break
7 except Exception as e:
8 print(f"시도 {i+1}/{max_attempts} 실패: {e}")

⚠️ 데코레이터의 가치는 호출하는 쪽이 재시도 로직을 몰라도 되게 만드는 것입니다. try/except + for 루프가 wrapper 안에 있어야 합니다.

2차 시도 — return vs raise 문제 #

 1def wrapper(*args, **kwargs):
 2 last_exception = None
 3 for i in range(max_attempts):
 4 try:
 5 result = func(*args, **kwargs)
 6 print(f"{func.__name__} 시도 {i+1}/{max_attempts} 성공")
 7 return result
 8 except Exception as e:
 9 last_exception = e
10 print(f"{func.__name__} 시도 {i+1}/{max_attempts} 실패: {e}")
11 return last_exception # ← 문제!

3번 다 실패하면:

result = 서버 응답 없음
type = <class 'ConnectionError'> ← 예외 객체가 정상 반환값처럼 돌아옴

return last_exception은 예외를 정상 반환값으로 돌려보냅니다. 호출하는 쪽에서 에러가 발생했는지 알 수가 없습니다.

3차 시도 — 바깥 try/except 추가 (역시 실패) #

 1def wrapper(*args, **kwargs):
 2 last_exception = None
 3 try:
 4 for i in range(max_attempts):
 5 try:
 6 result = func(*args, **kwargs)
 7 return result
 8 except Exception as e:
 9 last_exception = e
10 break
11 except Exception as e:
12 raise last_exception

안쪽 except가 이미 예외를 처리하기 때문에 바깥 except까지 예외가 전파되지 않았습니다. 결과적으로 None이 반환되었습니다.

4차 시도 (완성) #

 1def retry(max_attempts: int):
 2 def decorator(func):
 3 @wraps(func)
 4 def wrapper(*args, **kwargs):
 5 last_exception = None
 6 for i in range(max_attempts):
 7 try:
 8 result = func(*args, **kwargs)
 9 print(f"{func.__name__} 시도 {i+1}/{max_attempts} 성공")
10 return result
11 except Exception as e:
12 last_exception = e
13 print(f"{func.__name__} 시도 {i+1}/{max_attempts} 실패: {e}")
14 raise last_exception
15 return wrapper
16 return decorator

Tip: 성공하면 return으로 함수가 즉시 종료됩니다. for문이 끝까지 다 돌았다는 것 자체가 전부 실패를 의미하므로, for문 바로 뒤에 raise만 놓으면 됩니다.

3️⃣ @validate_types #

1차 시도 — int 하드코딩 #

1def validate_types(func):
2 @wraps(func)
3 def wrapper(*args, **kwargs):
4 for arg in args:
5 if not isinstance(arg, int):
6 raise TypeError(f"인자는 정수(int)여야 합니다. 받은 타입: {type(arg)}")
7 return func(*args, **kwargs)
8 return wrapper

동작은 하지만, 모든 인자가 int인지만 검사합니다. get_type_hints와 inspect를 import 해놓고도 안 쓰고 있었습니다. 이러면 greet(name: str, count: int) 같은 함수에서 str을 넣어도 에러가 납니다.

2차 시도 — 에러 메시지 문제 #

1for param_name, value in zip(params, args):
2 if not isinstance(value, hints[param_name]):
3 raise TypeError(f"인자는 정수(int)여야 합니다. 받은 타입: {type(param_name)}")

로직은 맞았지만 에러 메시지에 두 가지 문제가 있었습니다:

"정수(int)"가 하드코딩 — str이어야 하는 파라미터에도 “정수(int)여야 합니다"가 출력됨
type(param_name) — param_name은 "a" 같은 문자열이므로 항상 <class 'str'>이 나옴. type(value)를 써야 함

3차 시도 (완성) #

 1def validate_types(func):
 2 @wraps(func)
 3 def wrapper(*args, **kwargs):
 4 hints = get_type_hints(func)
 5 sig = inspect.signature(func)
 6 params = list(sig.parameters.keys())
 7
 8 for param_name, value in zip(params, args):
 9 if not isinstance(value, hints[param_name]):
10 raise TypeError(
11 f"'{param_name}'의 타입이 {hints[param_name].__name__}여야 하지만 "
12 f"{type(value).__name__}이 전달됨"
13 )
14 return func(*args, **kwargs)
15 return wrapper

✅ 실행 결과 #

=== timer ===
slow_function 실행 시간: 1.50초

=== retry ===
unstable_api_call 시도 1/3 실패: 서버 응답 없음
unstable_api_call 시도 2/3 성공

=== validate_types ===
add(1, 2) → 3
add("1", "2") → TypeError: 'a'의 타입이 int여야 하지만 str이 전달됨
greet(123, 3) → TypeError: 'name'의 타입이 str여야 하지만 int이 전달됨
greet("hello", 3) → hellohellohello

🔍 functools.wraps는 왜 필요한가 #

처음에는 @wraps 없이도 func.__name__이 잘 나와서 필요 없다고 생각했습니다. 하지만 그건 데코레이터 내부에서 func을 직접 참조하고 있기 때문이었습니다. 문제는 바깥에서 볼 때입니다:

 1@timer
 2def slow_function():
 3 """느린 함수입니다"""
 4 ...
 5
 6# @wraps 없이
 7print(slow_function.__name__) # → "wrapper" ← 원래 이름 소실
 8print(slow_function.__doc__) # → None ← docstring 소실
 9
10# @wraps 있으면
11print(slow_function.__name__) # → "slow_function"
12print(slow_function.__doc__) # → "느린 함수입니다"

⚠️ FastAPI 같은 프레임워크가 함수의 __name__과 __doc__을 읽어서 API 문서를 자동 생성하는데, @wraps가 없으면 모든 엔드포인트 이름이 “wrapper"로 표시됩니다.

💡 Python 타입 힌트는 런타임에 강제되지 않는다 #

과제 중에 “타입 힌트를 넣으면 add("1", 2)에서 바로 에러가 나지 않나요?“라는 의문이 생겼습니다. 답은 아닙니다.

1def add(a: int, b: int) -> int:
2 return a + b
3
4add("hello", "world") # → "helloworld" (에러 없음!)
5add(1.5, 2.3) # → 3.8 (int 아닌데 에러 없음!)

Python의 타입 힌트는 그냥 “메모"입니다. 실제로 타입을 강제하려면 mypy 같은 정적 분석 도구를 쓰거나, 이번 과제의 @validate_types처럼 런타임에 직접 체크해야 합니다. FastAPI가 내부적으로 이런 런타임 검증을 해주는 대표적인 예입니다.

🤔 데코레이터가 왜 필요한가 #

과제를 하면서 “굳이 데코레이터가 필요한가?“라는 의문이 들었습니다. 하지만 @retry 없이 API 호출 3개를 만든다고 가정하면 답이 나옵니다:

 1# 데코레이터 없이 — 재시도 로직이 매번 반복
 2def call_openai():
 3 for i in range(3):
 4 try: return openai.chat(...)
 5 except: ...
 6
 7def call_anthropic():
 8 for i in range(3): # ← 똑같은 코드
 9 try: return anthropic.messages(...)
10 except: ...

1# 데코레이터로 — 비즈니스 로직만 남음
2@retry(max_attempts=3)
3def call_openai():
4 return openai.chat(...)
5
6@retry(max_attempts=3)
7def call_anthropic():
8 return anthropic.messages(...)

데코레이터의 가치는 횡단 관심사의 분리입니다. 로깅, 인증, 재시도, 캐싱, 타입 검증 같은 건 비즈니스 로직이 아닌데 여기저기서 필요합니다. 이걸 함수마다 반복하는 대신 @ 한 줄로 붙이는 것입니다.

📝 이번 과제에서 배운 것 #

데코레이터 기본 패턴: wrapper는 result를 반환, 데코레이터는 wrapper를 반환합니다. 데코레이터 안에서 함수를 직접 실행하면 안 됩니다.

인자 있는 데코레이터: 팩토리 → 데코레이터 → wrapper의 3중 중첩 구조입니다. 키워드 인자로 호출할 때는 이름이 일치해야 하고, 위치 인자로 호출하면 상관없습니다.

return vs raise: 예외를 return하면 정상 반환값처럼 돌아갑니다. 예외는 반드시 raise로 발생시켜야 호출하는 쪽에서 인지할 수 있습니다.

@wraps의 역할: 원래 함수의 __name__, __doc__ 등 메타데이터를 보존합니다. FastAPI 같은 프레임워크의 자동 문서 생성에 영향을 줍니다.

타입 힌트는 메모일 뿐: Python은 런타임에 타입을 강제하지 않습니다. get_type_hints()와 inspect.signature()로 직접 읽어와야 합니다.

[AI Assignment - Python] 🐍 타입 힌트와 컴프리헨션 — WeatherAnalyzer 클래스 구현기

Tue, 07 Apr 2026 00:00:00 +0000

🎯 과제: WeatherAnalyzer 클래스 구현 #

첫 번째 과제는 타입 힌트와 컴프리헨션을 활용한 날씨 데이터 분석 클래스 만들기입니다.

입력 데이터 #

1weather_data = [
2 {"city": "서울", "date": "2026-04-01", "temp": 15.2, "humidity": 45, "pm25": 32.1},
3 {"city": "서울", "date": "2026-04-02", "temp": 18.5, "humidity": 52, "pm25": 28.7},
4 {"city": "부산", "date": "2026-04-01", "temp": 17.8, "humidity": 61, "pm25": 22.3},
5 {"city": "부산", "date": "2026-04-02", "temp": 20.1, "humidity": 58, "pm25": 19.5},
6]

요구사항 #

get_city_avg(city) — 특정 도시의 temp, humidity, pm25 각각의 평균을 딕셔너리로 반환
get_good_air_days(threshold) — pm25가 threshold 이하인 날만 필터링 (컴프리헨션 사용)
summary() — 모든 도시별 평균을 {"서울": {...}, "부산": {...}} 형태로 반환 (딕셔너리 컴프리헨션 사용)
모든 함수에 타입 힌트 적용

1️⃣ 1차 시도: 일단 기억나는 대로 작성 #

 1class WeatherAnalyzer:
 2 def __init__(self, list_input: list[dict[str]]):
 3 self._list_input = list_input
 4
 5 def get_city_avg(self, city: str) -> dict[str, float]:
 6 results = {
 7 item["city"]: (item["temp"] + item["humidity"] + item["pm25"]) / 3
 8 for item in self._list_input if item['city'] == city
 9 }
10 return results
11
12 def get_good_air_days(self, threshold: float = 30.0) -> list[dict]:
13 results = [item for item in self._list_input if item['pm25'] <= threshold]
14 return results
15
16 def summary(self) -> dict[str, dict[str, float]]:
17 results = [{
18 item["city"]: (item["temp"] + item["humidity"] + item["pm25"]) / 3
19 for item in self._list_input
20 }]
21 return results

리뷰에서 지적받은 점 #

타입 힌트 오류: dict[str]은 유효하지 않습니다. dict는 key와 value 타입을 둘 다 명시해야 합니다. 값이 str, float, int 등 여러 타입이 섞여 있으므로 dict[str, Any]로 써야 합니다.

get_city_avg 로직 오류: 가장 큰 실수였습니다. 온도, 습도, 미세먼지를 합산해서 3으로 나누는 의미 없는 계산을 하고 있었습니다. 요구사항은 각 항목의 도시별 평균이었습니다.

1# 내가 한 것 (틀림)
2(item["temp"] + item["humidity"] + item["pm25"]) / 3 # → 의미 없는 숫자
3
4# 기대한 것
5{"temp": 18.95, "humidity": 59.5, "pm25": 20.9} # → 각 항목별 평균

딕셔너리 키 중복 문제: 컴프리헨션에서 같은 키(“부산”)가 여러 번 나오면 마지막 값만 남습니다. 즉 부산 4/1 데이터가 사라집니다.

summary의 반환 타입 불일치: 리스트로 감싸서 list[dict]를 반환하고 있었는데, 요구사항은 dict[str, dict]이었습니다.

2️⃣ 2차 시도: 로직 수정 + dataclass 도전 #

 1from dataclasses import dataclass, field
 2from typing import Any
 3
 4@dataclass
 5class WeatherAnalyzer:
 6 city: str
 7 date: str
 8 temp: float
 9 humidity: int
10 pm25: float
11
12 def __init__(self, list_input: list[dict[str, Any]]):
13 self._list_input = list_input
14
15 def get_city_avg(self, city: str) -> dict[str, float]:
16 results = {
17 city: [
18 {'temp': sum(data['temp'] for data in self._list_input if data['city'] == city) /
19 len([data for data in self._list_input if data['city'] == city])},
20 {'humidity': sum(data['humidity'] for data in self._list_input if data['city'] == city) /
21 len([data for data in self._list_input if data['city'] == city])},
22 {'pm25': sum(data['pm25'] for data in self._list_input if data['city'] == city) /
23 len([data for data in self._list_input if data['city'] == city])},
24 ]
25 }
26 return results
27
28 def summary(self) -> dict[str, dict[str, float]]:
29 cities = set(d['city'] for d in self._list_input)
30 results = {item: self.get_city_avg(item) for item in cities}
31 return results

좋아진 점 #

항목별 평균을 따로 구하는 방향은 맞았습니다.
summary()에서 get_city_avg()를 재활용하는 설계도 좋았습니다.

여전히 남은 문제 #

@dataclass 오용: @dataclass는 __init__을 자동 생성해주는 데코레이터인데, 직접 __init__을 정의하면 자동생성이 무시됩니다. 위에 선언한 city, date 등의 필드도 실제로 사용되지 않았습니다.

반환 구조: dict 안에 list 안에 dict 3개라는 불필요하게 복잡한 구조가 만들어졌습니다.

1# 내 반환값 (너무 복잡)
2{"부산": [{"temp": 18.95}, {"humidity": 59.5}, {"pm25": 20.9}]}
3
4# 기대한 반환값 (심플)
5{"temp": 18.95, "humidity": 59.5, "pm25": 20.9}

같은 필터링이 6번 반복: data['city'] == city 필터링을 temp, humidity, pm25마다 sum과 len에서 각각 반복하고 있었습니다. 총 6번. 먼저 한 번 필터링하고 재사용하면 됩니다.

3️⃣ 3차 시도 (최종): 피드백 반영 #

 1from typing import Any
 2
 3class WeatherAnalyzer:
 4 def __init__(self, list_input: list[dict[str, Any]]):
 5 self._list_input = list_input
 6
 7 def get_city_avg(self, city: str) -> dict[str, float]:
 8 city_data = [d for d in self._list_input if d['city'] == city]
 9 n = len(city_data)
10 results = {
11 'temp': sum(d['temp'] for d in city_data) / n,
12 'humidity': sum(d['humidity'] for d in city_data) / n,
13 'pm25': sum(d['pm25'] for d in city_data) / n,
14 }
15 return results
16
17 def get_good_air_days(self, threshold: float = 30.0) -> list[dict]:
18 return [item for item in self._list_input if item['pm25'] <= threshold]
19
20 def summary(self) -> dict[str, dict[str, float]]:
21 cities = set(d['city'] for d in self._list_input)
22 return {city: self.get_city_avg(city) for city in cities}

실행 결과 #

get_city_avg('부산') → {'temp': 18.95, 'humidity': 59.5, 'pm25': 20.9}
get_good_air_days(20) → [{'city': '부산', 'date': '2026-04-02', 'temp': 20.1, 'humidity': 58, 'pm25': 19.5}]
summary() → {'부산': {'temp': 18.95, ...}, '서울': {'temp': 16.85, ...}}

🏆 모범답안과 비교 #

리뷰에서 받은 모범답안에는 몇 가지 추가 테크닉이 있었습니다.

필드 반복을 상수로 제거 #

1class WeatherAnalyzer:
2 FIELDS = ('temp', 'humidity', 'pm25')
3
4 def get_city_avg(self, city: str) -> dict[str, float]:
5 city_data = [d for d in self._data if d['city'] == city]
6 n = len(city_data)
7 return {f: round(sum(d[f] for d in city_data) / n, 2) for f in self.FIELDS}

FIELDS를 상수로 정의해두면 필드가 추가되어도 한 곳만 수정하면 됩니다. 딕셔너리 컴프리헨션으로 3줄이 1줄로 줄어듭니다.

방어 코드 #

1if not city_data:
2 raise ValueError(f"도시 '{city}'의 데이터가 없습니다")

⚠️ 존재하지 않는 도시를 넣으면 n = 0이 되어 ZeroDivisionError가 발생합니다. 실무에서는 이런 엣지 케이스를 항상 고려해야 합니다.

`repr` 구현 #

1def __repr__(self) -> str:
2 return f"WeatherAnalyzer({len(self._data)}건, 도시: {sorted({d['city'] for d in self._data})})"

print(analyzer) 했을 때 객체 정보를 한눈에 볼 수 있어 디버깅에 유용합니다.

📝 이번 과제에서 배운 것 #

타입 힌트: dict[str]이 아니라 dict[str, Any]처럼 key/value 타입을 모두 명시해야 합니다. 모던 Python에서 타입 힌트는 선택이 아닌 사실상 표준입니다.

컴프리헨션의 함정: 딕셔너리 컴프리헨션에서 같은 키가 여러 번 나오면 마지막 값만 남습니다. 데이터를 먼저 그룹핑하고 집계해야 합니다.

@dataclass의 용도: @dataclass는 데이터를 담는 클래스에 쓰는 것이지, 로직 중심의 분석 클래스에 억지로 끼워넣을 필요가 없습니다.

필터링 한 번, 재사용 여러 번: 같은 조건의 필터링을 반복하지 말고 변수에 담아서 재사용합니다. 가독성과 성능 모두 좋아집니다.

Tip: 메서드 안에 print를 넣지 않는 것이 좋은 습관입니다. 메서드는 값을 반환하고, 출력은 호출하는 쪽에서 결정해야 합니다.

[Kubernetes] 🧹 GitHub Actions Runner Pod 디스크 정리: kubectl exec + docker prune 일괄 실행

Fri, 27 Mar 2026 00:00:00 +0000

Kubernetes에 올린 GitHub Actions self-hosted runner는 CI 빌드를 반복하면서 Docker 이미지·빌드 캐시가 쌓여 노드 디스크를 가득 채우기 쉽습니다. 이 글에서는 kubectl get pods -l로 runner Pod를 골라 xargs로 묶어, 여러 Pod에 한 번에 docker system prune을 실행하는 한 줄 명령어를 분해하고, 안전한 옵션 선택과 CronJob 자동화까지 실무 관점으로 정리합니다.

🎯 핵심 명령어 한 줄 #

1kubectl get -n github-runner pods -l app=githubrunner-cs -o name \
2 | xargs -I {} kubectl exec -n github-runner {} -c githubrunner-cs -- docker system prune -f

이 한 줄은 github-runner 네임스페이스에서 app=githubrunner-cs 라벨이 붙은 모든 runner Pod를 찾아, 각 Pod의 githubrunner-cs 컨테이너 안에서 docker system prune -f를 실행합니다. 결과적으로 모든 runner의 Docker 찌꺼기를 한 번에 정리합니다.

🧐 왜 runner Pod에 찌꺼기가 쌓일까? #

self-hosted runner는 CI 빌드마다 Docker 이미지를 받고 빌드 캐시를 남기는데, 이게 정리되지 않고 누적되기 때문입니다. 특히 runner Pod 안에서 Docker 빌드를 돌리는 DinD(Docker-in-Docker) 구조에서는 다음이 쌓입니다.

빌드 중간 단계 이미지와 dangling 이미지(태그가 떨어진 <none> 이미지)
docker build 과정에서 생기는 빌드 캐시
종료된 컨테이너, 사용하지 않는 네트워크

GitHub Actions의 공식 호스티드 runner는 매번 깨끗한 VM에서 시작하지만, self-hosted runner는 환경이 유지되므로 직접 청소하지 않으면 계속 누적됩니다. 결국 노드의 디스크가 가득 차면 ImagePull 실패나 Pod Evicted로 이어집니다.

⚠️ 디스크가 이미 가득 찬 뒤에는 Pod가 Evicted되어 정리 명령조차 못 들어갈 수 있습니다. **주기적 정리(자동화)**가 핵심입니다.

🔬 명령어 한 줄 분해하기 #

명령어는 세 토막으로 나눠 보면 명확합니다.

1️⃣ 대상 Pod 고르기 — `kubectl get -l` #

1kubectl get -n github-runner pods -l app=githubrunner-cs -o name

-l app=githubrunner-cs는 label selector로 runner Pod만 선택합니다. -o name은 출력을 pod/이름 형식으로 단순화해 다음 단계에 넘기기 좋게 만듭니다.

1pod/githubrunner-cs-0
2pod/githubrunner-cs-1
3pod/githubrunner-cs-2

2️⃣ 각 Pod로 펼치기 — `xargs -I {}` #

1| xargs -I {} kubectl exec ... {} ...

xargs -I {}는 앞 단계에서 받은 줄(Pod 이름)을 하나씩 {} 자리에 끼워 넣어 명령을 Pod 개수만큼 반복합니다. Pod가 3개면 kubectl exec가 3번 실행됩니다.

3️⃣ 컨테이너 안에서 실행 — `kubectl exec -c ... -- docker ...` #

1kubectl exec -n github-runner pod/githubrunner-cs-0 -c githubrunner-cs -- docker system prune -f

-c githubrunner-cs: Pod에 컨테이너가 여러 개(예: runner + DinD 사이드카)일 때 어느 컨테이너에서 실행할지 지정합니다. 생략하면 첫 번째 컨테이너에서 실행됩니다.
-- 뒤가 컨테이너 안에서 실제로 돌릴 명령(docker system prune -f)입니다.

Tip: Docker 데몬이 별도 사이드카(예: dind)에 있다면 -c 값을 그 컨테이너 이름으로 맞춰야 합니다. kubectl get pod <name> -o jsonpath='{.spec.containers[*].name}'로 컨테이너 이름을 확인하세요.

🗑️ docker system prune은 정확히 무엇을 지우나 #

docker system prune은 기본적으로 멈춘 컨테이너·미사용 네트워크·dangling 이미지·미사용 빌드 캐시를 삭제하지만, 볼륨과 태그가 붙은 미사용 이미지는 건드리지 않습니다. 옵션에 따라 삭제 범위가 크게 달라지므로 표로 정리합니다.

명령	멈춘 컨테이너	dangling 이미지	태그된 미사용 이미지	빌드 캐시	볼륨
`docker system prune`	✅	✅	❌	✅(미사용)	❌
`docker system prune -a`	✅	✅	✅	✅(전체)	❌
`docker system prune -a --volumes`	✅	✅	✅	✅(전체)	✅

-f / --force: 확인 프롬프트를 건너뜁니다. 스크립트·일괄 실행에는 필수입니다.
-a / --all: dangling뿐 아니라 컨테이너가 참조하지 않는 모든 이미지를 삭제합니다. 디스크는 더 확보되지만, 다음 빌드에서 베이스 이미지를 다시 받아야 합니다(캐시 손실).
--volumes: 미사용 볼륨까지 삭제합니다. 데이터 유실 위험이 있으니 runner 캐시 볼륨 구조를 모르면 쓰지 마세요.

⚠️ runner에서는 보통 **docker system prune -f(기본)**가 안전한 균형점입니다. 디스크를 더 비워야 하면 -a까지 고려하되, --volumes는 무엇이 지워지는지 확인 후에만 사용하세요.

🔎 정리 전후 확인하기 #

정리 효과를 수치로 확인하려면 docker system df를 활용합니다.

1# 특정 runner Pod의 디스크 사용 현황
2kubectl exec -n github-runner pod/githubrunner-cs-0 -c githubrunner-cs -- docker system df

1TYPE TOTAL ACTIVE SIZE RECLAIMABLE
2Images 42 5 12.3GB 9.8GB (79%)
3Containers 8 2 1.2GB 0.9GB (75%)
4Local Volumes 15 3 4.1GB 3.0GB (73%)
5Build Cache 120 0 6.5GB 6.5GB (100%)

RECLAIMABLE 값이 prune으로 회수 가능한 용량입니다. 노드 디스크 자체는 다음으로 확인합니다.

1# 노드 파일시스템 사용률
2kubectl exec -n github-runner pod/githubrunner-cs-0 -c githubrunner-cs -- df -h /

⏰ CronJob으로 자동화하기 #

수동 실행은 까먹기 쉬우니, CronJob으로 주기적 정리를 거는 것이 실무에서 가장 깔끔합니다. 클러스터 안에서 kubectl을 실행하려면 해당 명령에 대한 권한(RBAC)이 필요합니다.

 1# ServiceAccount + RBAC (pods 조회 + exec 권한)
 2apiVersion: v1
 3kind: ServiceAccount
 4metadata:
 5 name: runner-pruner
 6 namespace: github-runner
 7---
 8apiVersion: rbac.authorization.k8s.io/v1
 9kind: Role
10metadata:
11 name: runner-pruner
12 namespace: github-runner
13rules:
14 - apiGroups: [""]
15 resources: ["pods"]
16 verbs: ["get", "list"]
17 - apiGroups: [""]
18 resources: ["pods/exec"]
19 verbs: ["create"]
20---
21apiVersion: rbac.authorization.k8s.io/v1
22kind: RoleBinding
23metadata:
24 name: runner-pruner
25 namespace: github-runner
26subjects:
27 - kind: ServiceAccount
28 name: runner-pruner
29 namespace: github-runner
30roleRef:
31 kind: Role
32 name: runner-pruner
33 apiGroup: rbac.authorization.k8s.io

 1# CronJob — 매일 새벽 4시에 모든 runner Pod 정리
 2apiVersion: batch/v1
 3kind: CronJob
 4metadata:
 5 name: runner-docker-prune
 6 namespace: github-runner
 7spec:
 8 schedule: "0 4 * * *" # 매일 04:00 (클러스터 타임존 기준)
 9 concurrencyPolicy: Forbid
10 jobTemplate:
11 spec:
12 template:
13 spec:
14 serviceAccountName: runner-pruner
15 restartPolicy: Never
16 containers:
17 - name: pruner
18 image: bitnami/kubectl:latest
19 command:
20 - /bin/sh
21 - -c
22 - >
23 kubectl get -n github-runner pods -l app=githubrunner-cs -o name
24 | xargs -I {} kubectl exec -n github-runner {} -c githubrunner-cs
25 -- docker system prune -f

Tip: schedule의 타임존은 기본적으로 kube-controller-manager 기준(UTC인 경우가 많음)입니다. KST 기준으로 돌리려면 spec.timeZone: "Asia/Seoul"(Kubernetes 1.27+ 안정화)을 추가하세요.

📝 한 줄 요약 #

self-hosted GitHub Actions runner는 환경이 유지되어 Docker 이미지·빌드 캐시가 누적되므로 주기적 정리가 필요합니다.
kubectl get -l ... -o name | xargs -I {} kubectl exec ... -- docker system prune -f로 여러 runner Pod를 한 번에 정리할 수 있습니다.
기본 prune -f가 안전하며, -a(전체 이미지)·--volumes(볼륨)는 영향 범위를 이해하고 써야 합니다.
운영에서는 RBAC + CronJob으로 자동화하는 것이 가장 확실합니다.

❓ 자주 묻는 질문 #

Q. `docker system prune -f`는 실행 중인 컨테이너도 지우나요? #

아닙니다. 멈춘(stopped) 컨테이너, dangling 이미지, 미사용 네트워크, 미사용 빌드 캐시만 삭제합니다. 실행 중인 컨테이너와 그것이 사용하는 이미지·볼륨은 보존됩니다.

Q. `-c` 옵션은 꼭 써야 하나요? #

Pod에 컨테이너가 하나면 생략해도 됩니다. runner + DinD 사이드카처럼 여러 컨테이너가 있으면 Docker 데몬이 있는 컨테이너를 -c로 지정해야 합니다. 생략 시 첫 번째 컨테이너에서 실행됩니다.

Q. Pod가 아주 많을 때 한 번에 돌려도 되나요? #

xargs는 기본적으로 순차 실행이라 안전합니다. 더 빠르게 병렬 실행하려면 xargs -P 4처럼 동시 실행 수를 지정할 수 있지만, API 서버·노드 부하를 고려해 적당히 제한하세요.

Q. 디스크를 더 확보하려면 `-a`를 써야 하나요? #

-a는 태그가 있어도 컨테이너가 참조하지 않는 모든 이미지를 지웁니다. 디스크는 더 비지만 다음 빌드에서 베이스 이미지를 다시 받아야 해 빌드가 느려집니다. 정기 정리는 기본 prune, 디스크 위기 시에만 -a를 권장합니다.

Q. ARC(Actions Runner Controller)를 쓰면 어떻게 하나요? #

ARC의 ephemeral runner는 잡마다 Pod가 새로 떠 비교적 깨끗하지만, DinD 캐시를 공유 볼륨에 두는 구성이면 여전히 누적될 수 있습니다. 이 경우 공유 캐시 볼륨에 대한 정리 정책을 별도로 두거나 위 CronJob 방식을 적용하세요.

📚 참고 #

[Python] 🚀 uv로 프로젝트 & 패키지 관리 완벽 가이드

Thu, 19 Mar 2026 00:00:00 +0000

🐍 uv로 Python 프로젝트 관리하기 #

uv는 Python 프로젝트에서 패키지 관리 + 가상환경 + Python 버전 관리를 한 번에 해결해주는 최신 도구입니다. Rust로 작성되어 기존 pip보다 10~100배 빠르며, pip, venv, pyenv를 대체할 수 있는 올인원 툴입니다 ⚡

이 글에서는 실무에서 바로 사용할 수 있도록 정확한 명령어 기준으로 깔끔하게 정리했습니다.

📥 설치하기 #

macOS / Linux #

1curl -LsSf https://astral.sh/uv/install.sh | sh

Windows #

1powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

pip으로 설치 #

1pip install uv

설치 후 버전 확인:

1uv --version

1️⃣ 프로젝트 생성 및 설정 #

📦 프로젝트 생성 #

 1# 현재 디렉토리에 새로운 파이썬 프로젝트 환경을 초기화하는 기본적인 파일과 폴더 구조가 자동으로 생성
 2uv init
 3
 4# 기본 프로젝트 생성
 5uv init my-project
 6
 7# 설정 파일만 필요하다면
 8uv init --bare
 9
10# 특정 Python 버전으로 생성
11uv init my-project --python 3.11
12
13# 가상환경 없이 생성
14uv init my-project --no-venv

⚠️ 만약 error: Failed to discover parent workspace; 가 발생했다면 --no-workspace 옵션을 넣어주어 프로젝트를 생성

📁 uv init 시 생성되는 파일 #

uv init 실행 후 프로젝트 디렉토리에 아래 파일들이 자동으로 생성됩니다.

1my-project/
2├── pyproject.toml # 프로젝트 메타데이터 및 의존성 정의
3├── .python-version # 사용할 Python 버전 고정
4├── uv.lock # 의존성 버전 잠금 파일 (자동 생성)
5├── .venv/ # 가상환경 디렉토리
6└── src/
7 └── main.py # 기본 진입점

Tip: uv.lock 파일은 git에 포함해야 팀원 전체가 동일한 의존성 환경을 보장받을 수 있습니다.

📚 의존성 관리 #

 1# 패키지 추가
 2uv add requests
 3
 4# 특정 버전 추가
 5uv add requests==2.31.0
 6
 7# 개발 의존성 추가
 8uv add --dev pytest
 9
10# 로컬 패키지 (editable 모드)
11uv add -e ./localpackage

❌ 의존성 제거 #

1uv remove requests
2uv remove --dev pytest

🔄 의존성 동기화 #

1uv sync # 전체 설치
2uv sync --dev # 개발 의존성 포함
3uv sync --no-dev # 개발 의존성 제외

🔒 의존성 잠금 #

1uv lock
2uv lock --dev
3uv lock --no-dev

2️⃣ 패키지 설치 (pip 스타일) #

📥 기본 설치 #

1uv pip install requests

🎯 특정 버전 설치 #

1uv pip install "requests==2.31.0"
2uv pip install "requests>=2.31.0"
3uv pip install "requests<3.0.0"

🧪 개발 도구 설치 #

1uv pip install --dev pytest
2uv pip install --dev black isort mypy

❌ 패키지 제거 #

1uv pip uninstall requests
2uv pip uninstall -y requests

⬆️ 패키지 업그레이드 #

1uv pip install --upgrade requests
2uv pip install --upgrade pip

🔍 패키지 조회 #

1uv pip search "data science"
2uv pip show requests
3uv pip list
4uv pip list outdated
5uv pip freeze # 현재 환경의 의존성 requirements 형식으로 출력

🤔 uv add vs uv pip install 차이 #

두 명령어 모두 패키지를 설치하지만 사용 목적이 다릅니다.

구분	`uv add`	`uv pip install`
용도	프로젝트 의존성으로 등록	즉시 설치 (pip 호환)
pyproject.toml	✅ 자동 업데이트	✗ 업데이트 안 함
uv.lock	✅ 자동 갱신	✗ 갱신 안 함
추천 상황	팀 프로젝트, 공유 환경	일회성 설치, 임시 테스트

Tip: 팀 프로젝트에서는 uv add를 사용해야 pyproject.toml과 uv.lock이 업데이트되어 팀원과 환경을 공유할 수 있습니다.

3️⃣ 가상환경 관리 #

🏗️ 가상환경 생성 #

1uv venv
2uv venv --python 3.11
3uv venv --name myenv
4uv venv --clear

▶️ 가상환경 활성화 #

macOS / Linux #

1source .venv/bin/activate
2source myenv/bin/activate

Windows #

1.venv\Scripts\activate
2myenv\Scripts\activate

⛔ 가상환경 비활성화 #

1deactivate

4️⃣ Python 버전 관리 #

📦 Python 설치 #

1uv python install 3.11
2uv python install 3.11.0
3uv python install 3.11 --force

🧰 버전 관리 #

1uv python list
2uv python remove 3.11
3uv python pin 3.11

▶️ 특정 버전 실행 #

1uv run --python 3.11 script.py
2uv run --python 3.11 -m pytest

5️⃣ 스크립트 실행 #

▶️ 기본 실행 #

1uv run script.py
2uv run -m module

📦 의존성과 함께 실행 #

1uv run --with-deps script.py
2uv run --no-deps script.py

🎛️ 인자 전달 #

1uv run script.py --arg1 value1 --arg2 value2
2uv run -m pytest tests/ --verbose

🌍 환경 변수 설정 #

1uv run --env VAR1=value1 --env VAR2=value2 script.py

⚡ uv가 빠른 이유 #

uv는 단순히 “빠르다"는 말로만 설명되지만, 그 이유는 다음 기술들의 조합입니다.

기술	설명
Rust 구현	컴파일 언어로 Python 대비 실행 속도 우월
병렬 처리	여러 패키지를 동시에 다운로드·설치
전역 캐시	한 번 다운로드한 패키지는 하드 링크로 재사용 (디스크 절약)
PubGrub 알고리즘	pip의 순차 탐색보다 효율적인 의존성 해결 알고리즘
HTTP/2 지원	연결 풀링으로 네트워크 요청 효율화

📊 pip + venv + pyenv vs uv 비교 #

항목	기존 방식	uv
프로젝트 초기화	수동 설정	`uv init`
가상환경 생성	`python -m venv .venv`	자동 생성
가상환경 활성화	매번 수동	`uv run` 시 자동
패키지 설치	`pip install`	`uv add` / `uv pip install`
의존성 잠금	`pip freeze > requirements.txt`	`uv lock` (자동)
Python 버전 관리	pyenv 별도 설치 필요	`uv python install` 통합
의존성 해결 방식	순차 처리	병렬 처리 (PubGrub)
캐시 방식	프로젝트별 개별 저장	전역 캐시 + 하드 링크
속도	기준 (1x)	10~100x 빠름

🏗️ 실전 프로젝트 예제 #

데이터 과학 프로젝트 #

1uv init data-science-project --python 3.11
2cd data-science-project
3uv add pandas numpy matplotlib scikit-learn
4uv add --dev jupyter notebook
5uv run jupyter notebook

FastAPI 웹 서버 #

1uv init web-api --python 3.11
2cd web-api
3uv add fastapi uvicorn sqlalchemy pydantic
4uv add --dev pytest black mypy
5uv run uvicorn src.main:app --reload

머신러닝 프로젝트 #

1uv init ml-project --python 3.11
2cd ml-project
3uv add torch torchvision transformers datasets
4uv add --dev jupyter wandb tensorboard
5uv run python src/train.py

💡 실무 팁 #

✅ uv sync 하나로 팀 환경 통일 가능
✅ uv lock으로 의존성 충돌 방지
✅ uv run으로 Python 버전까지 통제
✅ pip + venv + pyenv 대체 가능

🎯 이런 분들께 추천 #

⚡ 빠른 Python 환경을 원하시는 분
🧩 의존성 관리에 스트레스 받는 분
🐳 Docker / CI 환경에서 속도 개선이 필요한 분

🎉 마무리 #

uv는 단순한 패키지 매니저가 아니라 👉 Python 개발 환경 전체를 관리하는 차세대 도구입니다.

앞으로 Python 프로젝트는 이렇게 관리하는 것이 표준이 될 가능성이 높습니다 🚀

⚡ 빠른 패키지 설치
🧩 의존성 관리 통합
🐍 Python 버전 관리까지 한 번에

👉 기존 pip, venv, pyenv를 따로 쓰던 분들에게 강력 추천!

📚 참고 #

uv 공식 GitHub

[LLM] Mac Mini M4 환경에서 Ollama 설치 및 관리 가이드

Sat, 28 Feb 2026 00:00:00 +0000

Mac Mini M4(Apple Silicon) 환경에서 Ollama 설치 및 관리 가이드 #

📌 개요 #

본 가이드는 Apple Silicon 기반 Mac Mini M4 환경에서 로컬 LLM(Local Large Language Model) 도구인 Ollama를 설치하고 관리하는 방법을 설명합니다.
Homebrew를 활용하여 설치하고, 서비스 등록부터 모델 실행, 삭제 방법까지 전체 과정을 정리합니다.

🚀 1. Homebrew 준비 및 설치 #

1.1 Homebrew 설치 확인 #

먼저 Homebrew가 설치되어 있는지 확인합니다.

1brew --version

설치되어 있지 않다면 Homebrew 공식 사이트 안내에 따라 먼저 설치하세요.

1.2 Homebrew 업데이트 #

패키지 인덱스를 최신 상태로 유지합니다.

1brew update

🛠 2. Ollama 설치 #

Homebrew를 통해 Ollama를 설치합니다.

1brew install ollama

설치 완료 후 정상 설치 여부를 확인합니다.

1ollama --version

⚙️ 3. Ollama 실행 방식 #

3.1 백그라운드 서비스 실행 (권장) #

시스템 부팅 시 자동 실행되도록 설정:

1brew services start ollama

서비스 상태 확인:

1brew services list

3.2 포그라운드 실행 #

현재 터미널 세션에서만 실행하려면:

1ollama serve

터미널 세션이 종료되면 Ollama도 함께 종료됩니다.

🤖 4. 모델 다운로드 및 실행 #

모델을 다운로드하고 바로 실행할 수 있습니다.

1ollama run llama3.2

처음 실행 시 모델이 자동으로 다운로드됩니다.

설치된 모델 목록 확인:

1ollama list

현재 실행 중인 모델 확인:

1ollama ps

🌐 5. 외부 접속 허용 설정 #

기본적으로 Ollama는 127.0.0.1:11434에 바인딩됩니다.

외부 네트워크 접근을 허용하려면:

1export OLLAMA_HOST=0.0.0.0

영구 적용하려면 ~/.zshrc 또는 ~/.bashrc에 추가합니다.

1echo 'export OLLAMA_HOST=0.0.0.0' >> ~/.zshrc
2source ~/.zshrc

🧠 6. 리소스 관리 팁 (Apple Silicon) #

Apple Silicon은 Unified Memory 구조를 사용하므로, 대형 모델 실행 시 메모리 사용량을 반드시 확인하는 것이 좋습니다.

macOS에서 Activity Monitor를 통해 메모리 사용량을 모니터링하세요.

대형 모델 실행 시:

8GB RAM → 7B 이하 모델 권장
16GB RAM → 13B 모델 가능
32GB 이상 → 대형 모델 원활

❌ 7. Ollama 완전 삭제 (Uninstall) #

7.1 패키지 삭제 #

1brew uninstall ollama

7.2 데이터 디렉토리 삭제 #

1rm -rf ~/.ollama

⚠️ 해당 명령은 모든 모델 데이터를 완전히 삭제하므로 신중하게 실행하세요.

✅ 마무리 #

이 가이드를 통해 Mac Mini M4 환경에서:

Ollama 설치
서비스 등록
모델 실행
외부 접속 설정
완전 삭제

까지 전체 워크플로우를 정리했습니다.

로컬 LLM 환경을 구축하려는 Apple Silicon 사용자에게 기본 세팅 가이드로 활용할 수 있습니다.

[LangChain] 🔀 Ensemble Retriever로 RAG 검색 정확도 높이기: BM25 + Vector 하이브리드 검색

Sun, 01 Feb 2026 00:00:00 +0000

LangChain Ensemble Retriever는 BM25 키워드 검색과 Vector 의미 검색을 결합하여 단일 검색기보다 높은 정확도를 제공하는 하이브리드 검색 방식입니다. 두 검색기의 결과를 RRF(Reciprocal Rank Fusion) 알고리즘으로 재순위화하여 최적의 문서를 반환합니다. 이 글에서는 Ensemble Retriever의 동작 원리부터 BM25 + FAISS 조합 코드, weights 튜닝, 실무 적용 팁까지 정리합니다.

🤔 왜 단일 검색기로는 부족한가? #

RAG(Retrieval-Augmented Generation) 시스템에서 검색 품질은 LLM 답변의 품질을 직접 결정합니다. 그런데 현재 가장 많이 쓰이는 두 가지 검색 방식은 각각 뚜렷한 한계가 있습니다.

Dense Retrieval (의미 기반 — Vector Search) #

임베딩 벡터의 코사인 유사도로 의미적으로 유사한 문서를 찾습니다. 단어가 달라도 의미가 같으면 검색되는 것이 강점이지만, 정확한 용어·고유명사·코드 식별자 검색에는 취약합니다.

Sparse Retrieval (키워드 기반 — BM25) #

단어 빈도(TF-IDF 기반 BM25)로 문서를 검색합니다. “쿠버네티스”, “CVE-2024-1234” 같은 정확한 키워드 일치에 강하지만, 동의어·문맥 기반 질문에는 약합니다.

방식	강점	약점
Vector (Dense)	의미 유사성, 동의어, 맥락 이해	정확한 용어·고유명사·코드 검색
BM25 (Sparse)	키워드 정확 일치, 도메인 전문용어	오타, 동의어, 문맥 파악
Hybrid (Ensemble)	두 방식의 장점 결합	설정 복잡도 증가

Tip: 실무에서는 두 방식을 결합한 하이브리드 검색이 단일 방식보다 일관되게 더 나은 성능을 보입니다.

🔀 Ensemble Retriever란? #

Ensemble Retriever는 여러 검색기의 결과를 RRF(Reciprocal Rank Fusion) 알고리즘으로 병합하는 LangChain 컴포넌트입니다.

쿼리
 ├─ BM25Retriever → [문서A(1위), 문서C(2위), 문서E(3위), ...]
 └─ FAISSRetriever → [문서B(1위), 문서A(2위), 문서D(3위), ...]
 ↓
 RRF 재순위화 (weights 적용)
 ↓
 최종 결과: [문서A, 문서B, 문서C, ...]

RRF 알고리즘 #

RRF(Reciprocal Rank Fusion)는 각 검색기에서 반환된 문서의 순위를 기반으로 최종 점수를 계산합니다.

RRF 점수 = Σ (weight_i / (rank_i + c))

rank_i — 각 검색기에서의 순위 (1부터 시작)
weight_i — 해당 검색기의 가중치
c — 상수 (기본값 60, 높을수록 순위 차이 완화)

순위만 사용하기 때문에 서로 다른 점수 스케일을 가진 검색기를 직접 결합할 수 있다는 것이 핵심 장점입니다.

🚀 설치 #

1pip install langchain langchain-community langchain-openai faiss-cpu rank_bm25

패키지	용도
`langchain`	코어 프레임워크
`langchain-community`	BM25Retriever, FAISS 등 커뮤니티 컴포넌트
`langchain-openai`	OpenAI 임베딩
`faiss-cpu`	Facebook AI 유사도 검색 (GPU 버전: `faiss-gpu`)
`rank_bm25`	BM25 알고리즘 구현체

1️⃣ 기본 예제: BM25 + FAISS 결합 #

가장 일반적인 조합인 BM25와 FAISS를 사용한 Ensemble Retriever 구성입니다.

 1from langchain.retrievers import EnsembleRetriever
 2from langchain_community.retrievers import BM25Retriever
 3from langchain_community.vectorstores import FAISS
 4from langchain_openai import OpenAIEmbeddings
 5from langchain_core.documents import Document
 6
 7# 샘플 문서
 8docs = [
 9 Document(page_content="쿠버네티스(Kubernetes)는 컨테이너 오케스트레이션 플랫폼입니다."),
10 Document(page_content="Docker는 컨테이너 기반 가상화 기술로 애플리케이션을 패키징합니다."),
11 Document(page_content="Helm은 쿠버네티스 패키지 매니저로 차트를 통해 배포를 관리합니다."),
12 Document(page_content="Prometheus는 시계열 데이터베이스 기반의 모니터링 솔루션입니다."),
13 Document(page_content="Istio는 서비스 메시로 마이크로서비스 간 통신을 관리합니다."),
14]
15
16# BM25 리트리버 (키워드 기반)
17bm25_retriever = BM25Retriever.from_documents(docs)
18bm25_retriever.k = 3 # 반환할 문서 수
19
20# FAISS 리트리버 (의미 기반)
21embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
22vectorstore = FAISS.from_documents(docs, embeddings)
23faiss_retriever = vectorstore.as_retriever(search_kwargs={"k": 3})
24
25# Ensemble Retriever 구성
26ensemble_retriever = EnsembleRetriever(
27 retrievers=[bm25_retriever, faiss_retriever],
28 weights=[0.4, 0.6], # BM25 40%, FAISS 60%
29)
30
31# 검색 실행
32results = ensemble_retriever.invoke("쿠버네티스 패키지 관리 도구는?")
33for doc in results:
34 print(doc.page_content)

2️⃣ 실전 예제: RAG 파이프라인에 통합 #

문서 로딩부터 LLM 답변 생성까지 전체 RAG 파이프라인에 Ensemble Retriever를 통합합니다.

 1from langchain.text_splitter import RecursiveCharacterTextSplitter
 2from langchain_community.document_loaders import TextLoader
 3from langchain.chains import RetrievalQA
 4from langchain_openai import ChatOpenAI
 5
 6# 1. 문서 로딩 및 분할
 7loader = TextLoader("knowledge_base.txt", encoding="utf-8")
 8raw_docs = loader.load()
 9
10splitter = RecursiveCharacterTextSplitter(
11 chunk_size=500,
12 chunk_overlap=50,
13)
14docs = splitter.split_documents(raw_docs)
15
16# 2. BM25 리트리버
17bm25_retriever = BM25Retriever.from_documents(docs)
18bm25_retriever.k = 5
19
20# 3. FAISS 벡터스토어
21embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
22vectorstore = FAISS.from_documents(docs, embeddings)
23faiss_retriever = vectorstore.as_retriever(
24 search_type="mmr", # 다양성 확보 (Maximum Marginal Relevance)
25 search_kwargs={"k": 5, "fetch_k": 20, "lambda_mult": 0.7}
26)
27
28# 4. Ensemble Retriever
29ensemble_retriever = EnsembleRetriever(
30 retrievers=[bm25_retriever, faiss_retriever],
31 weights=[0.3, 0.7],
32)
33
34# 5. RAG 체인 구성
35llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
36qa_chain = RetrievalQA.from_chain_type(
37 llm=llm,
38 chain_type="stuff",
39 retriever=ensemble_retriever,
40 return_source_documents=True,
41)
42
43# 6. 질의
44response = qa_chain.invoke({"query": "서비스 메시의 역할은 무엇인가요?"})
45print(response["result"])
46print("\n--- 참조 문서 ---")
47for doc in response["source_documents"]:
48 print(f"- {doc.page_content[:100]}...")

3️⃣ ChromaDB + BM25 조합 #

FAISS 대신 ChromaDB를 사용하는 경우입니다. 영구 저장이 필요한 프로덕션 환경에 적합합니다.

 1from langchain_community.vectorstores import Chroma
 2from langchain_openai import OpenAIEmbeddings
 3
 4# ChromaDB 벡터스토어 생성
 5embeddings = OpenAIEmbeddings()
 6vectorstore = Chroma.from_documents(
 7 docs,
 8 embeddings,
 9 collection_name="my_collection",
10 persist_directory="./chroma_db", # 디스크 저장
11)
12chroma_retriever = vectorstore.as_retriever(search_kwargs={"k": 4})
13
14# Ensemble 구성
15ensemble_retriever = EnsembleRetriever(
16 retrievers=[bm25_retriever, chroma_retriever],
17 weights=[0.5, 0.5],
18)

⚖️ weights 설정 가이드 #

weights는 각 검색기가 최종 순위에 미치는 영향력을 조절합니다. 합계가 반드시 1.0일 필요는 없지만, 상대적 비율로 이해하면 됩니다.

상황	권장 weights (BM25 : Vector)
일반 QA (균형)	`[0.5, 0.5]`
기술 문서, 코드, 전문용어	`[0.6, 0.4]` — BM25 강화
고객 상담, 자연어 질문	`[0.3, 0.7]` — Vector 강화
뉴스·블로그 등 일반 문서	`[0.4, 0.6]` — Vector 약간 우세
법률·의료 전문 도메인	`[0.7, 0.3]` — 정확한 용어 우선

1# 세 개의 검색기를 결합할 수도 있습니다
2ensemble_retriever = EnsembleRetriever(
3 retrievers=[bm25_retriever, faiss_retriever, chroma_retriever],
4 weights=[0.3, 0.4, 0.3],
5)

Tip: weights는 도메인과 질의 패턴에 따라 다르므로, 평가 데이터셋으로 실험하여 최적값을 찾는 것이 좋습니다.

🔄 다른 다중 검색기 전략과 비교 #

Ensemble Retriever 외에도 LangChain이 제공하는 다중 검색기 전략들이 있습니다.

전략	설명	적합한 경우
EnsembleRetriever	여러 검색기 결과를 RRF로 병합	하이브리드 검색의 기본
MultiQueryRetriever	질문을 여러 변형으로 재생성 후 검색	모호한 질문, 다각도 검색
ContextualCompression	검색 결과를 LLM으로 압축·필터링	불필요한 정보 제거
ParentDocumentRetriever	작은 청크로 검색 후 원본 상위 문서 반환	문맥 손실 방지
SelfQueryRetriever	LLM이 메타데이터 필터를 자동 생성	구조화된 필터 조건 처리

MultiQueryRetriever와 Ensemble 조합 #

 1from langchain.retrievers.multi_query import MultiQueryRetriever
 2
 3# MultiQuery로 질문을 다각도로 확장
 4multi_query_retriever = MultiQueryRetriever.from_llm(
 5 retriever=faiss_retriever,
 6 llm=ChatOpenAI(temperature=0),
 7)
 8
 9# MultiQuery + BM25를 Ensemble로 결합
10ensemble_retriever = EnsembleRetriever(
11 retrievers=[bm25_retriever, multi_query_retriever],
12 weights=[0.4, 0.6],
13)

🏗️ 프로덕션 고려사항 #

성능 최적화 #

 1# FAISS 검색 타입별 특성
 2faiss_retriever = vectorstore.as_retriever(
 3 search_type="mmr", # 다양성 + 관련성 균형
 4 # search_type="similarity", # 순수 유사도 (기본값)
 5 # search_type="similarity_score_threshold", # 최소 점수 필터
 6 search_kwargs={
 7 "k": 5,
 8 "fetch_k": 20, # mmr에서 후보 풀 크기
 9 "lambda_mult": 0.5, # 0=다양성 최대, 1=유사도 최대
10 }
11)

대용량 문서 처리 #

1# BM25 리트리버를 파일에서 직접 로딩 (메모리 효율)
2from langchain_community.retrievers import BM25Retriever
3
4# 청크 크기를 고려한 k 설정
5bm25_retriever = BM25Retriever.from_documents(
6 docs,
7 bm25_params={"k1": 1.5, "b": 0.75} # BM25 하이퍼파라미터 조정
8)
9bm25_retriever.k = 10

검색 결과 평가 #

 1# 검색 결과 품질 간단 확인
 2def evaluate_retrieval(retriever, test_queries):
 3 for query, expected_keyword in test_queries:
 4 results = retriever.invoke(query)
 5 hit = any(expected_keyword in doc.page_content for doc in results)
 6 print(f"{'✅' if hit else '❌'} [{query}] → {len(results)}개 반환")
 7
 8test_cases = [
 9 ("쿠버네티스 설치 방법", "Kubernetes"),
10 ("컨테이너 패키징", "Docker"),
11]
12evaluate_retrieval(ensemble_retriever, test_cases)

💡 실무 적용 팁 #

BM25 토크나이저 커스터마이징 — 한국어 문서는 기본 토크나이저가 형태소를 고려하지 않아 성능이 떨어질 수 있습니다. konlpy 등의 한국어 형태소 분석기를 전처리 단계에 추가하는 것을 권장합니다.

청크 크기와 k의 균형 — 청크가 작을수록 더 많은 k가 필요합니다. 일반적으로 500~~1000자 청크에 k=4~~8이 적절합니다.

중복 문서 처리 — 두 검색기가 같은 문서를 반환하면 EnsembleRetriever가 자동으로 중복을 제거하고 점수를 합산합니다.

점진적 도입 — 기존 Vector 검색만 사용하던 시스템이라면, weights=[0.2, 0.8]처럼 BM25 비중을 낮게 시작하여 점진적으로 조정하세요.

❓ 자주 묻는 질문 #

Q. BM25Retriever와 EnsembleRetriever 중 무엇이 더 나은가요? #

단독으로는 우열을 가릴 수 없습니다. BM25는 키워드 일치에 강하고, Vector는 의미 이해에 강합니다. 대부분의 실무 RAG에서는 두 방식을 결합한 Ensemble이 단일 방식보다 일관되게 좋은 성능을 보입니다.

Q. weights 합이 반드시 1.0이어야 하나요? #

아닙니다. [0.4, 0.6]이든 [2, 3]이든 상대적 비율만 중요합니다. 내부적으로 정규화됩니다.

Q. `rank_bm25` 패키지 없이 BM25Retriever를 쓸 수 있나요? #

없습니다. BM25Retriever는 내부적으로 rank_bm25를 의존합니다. pip install rank_bm25가 필수입니다.

Q. RRF의 `c` 파라미터는 어떻게 조정하나요? #

현재 LangChain의 EnsembleRetriever는 c 파라미터를 직접 노출하지 않습니다. 기본값 60이 대부분의 경우 적합하며, 커스터마이징이 필요하다면 소스를 상속하여 오버라이드할 수 있습니다.

Q. 한국어 문서에서 BM25 성능이 낮습니다. #

한국어는 형태소 분석 없이 어절 단위로 분리되면 검색 정확도가 낮습니다. konlpy의 Okt나 Mecab으로 형태소 분석 후 토큰을 직접 BM25에 전달하면 성능이 향상됩니다.

📚 참고 #

LangChain 공식 문서 - Ensemble Retriever

[LLM] 🧠 프롬프트 엔지니어링 완전 가이드: Zero-shot, Few-shot, CoT부터 ReAct까지

Sun, 11 Jan 2026 00:00:00 +0000

프롬프트 엔지니어링은 LLM이 최적의 답변을 생성하도록 입력 텍스트의 형식, 맥락, 구조를 설계하는 기술입니다. 단어 하나의 차이가 결과를 크게 바꾸며, 예시 제공 방식에 따라 Zero-shot부터 Few-shot CoT까지 다양한 기법이 존재합니다. 이 글에서는 기본 기법의 개념과 차이부터 Chain-of-Thought, Tree-of-Thought, ReAct 같은 고급 기법까지 실제 프롬프트 예시와 함께 정리합니다.

🤔 프롬프트 엔지니어링이란? #

프롬프트 엔지니어링은 AI가 최상의 답변을 생성하도록 입력값(프롬프트)을 설계하고 최적화하는 과정입니다. 같은 질문이라도 어떻게 표현하느냐에 따라 LLM의 답변 품질이 극적으로 달라집니다.

# 나쁜 프롬프트
"요약해줘"

# 좋은 프롬프트
"다음 기술 문서를 비개발자도 이해할 수 있는 수준으로
 3문장 이내 한국어 글머리 목록으로 요약해줘."

프롬프트는 일반적으로 4가지 요소로 구성됩니다:

요소	설명	예시
Instruction	AI에게 수행할 작업 지시	“다음 텍스트를 감정 분류해줘”
Context	배경 정보, 제약 조건	“고객 리뷰 데이터입니다”
Input	실제 처리할 데이터	리뷰 텍스트
Output Indicator	원하는 출력 형식	“긍정/부정/중립 중 하나로만 답해줘”

1️⃣ Zero-Shot 프롬프팅 #

Zero-Shot은 예시(예제) 없이 지시만으로 AI에게 작업을 수행시키는 방식입니다. “영점(0개의 예시)“이라는 이름 그대로입니다.

AI의 사전학습 지식만으로 작업하기 때문에 빠르고 간편하지만, 복잡하거나 특수한 형식의 작업에서는 결과가 불안정할 수 있습니다.

# Zero-Shot 예시 — 감정 분류
"다음 문장의 감정을 긍정, 부정, 중립 중 하나로 분류하세요.

문장: 오늘 배송이 너무 늦어서 실망했어요."

# Zero-Shot 예시 — 번역
"다음 문장을 영어로 번역해줘.

문장: 인공지능은 미래를 바꿀 기술입니다."

적합한 상황: 일반적인 번역, 간단한 요약, 기본 질의응답처럼 명확하고 단순한 작업

2️⃣ One-Shot 프롬프팅 #

One-Shot은 하나의 입출력 예시를 제공한 후 같은 패턴으로 답변을 요청하는 방식입니다.

# One-Shot 예시 — 감정 분류
"다음 형식으로 감정을 분류해줘.

예시:
입력: 배송이 빠르고 포장이 깔끔해서 만족합니다.
출력: 긍정

입력: 제품 색상이 사진과 달라서 당황했어요.
출력:"

예시 하나만으로도 AI가 원하는 출력 형식을 파악하여 일관된 응답을 생성합니다.

3️⃣ Few-Shot 프롬프팅 #

Few-Shot은 2~5개의 예시를 제공하여 AI가 패턴을 학습하고 일관된 결과를 내도록 유도하는 방식입니다. Zero-Shot보다 훨씬 안정적인 결과를 얻을 수 있습니다.

# Few-Shot 예시 — 신조어 감정 분석
"다음 형식으로 리뷰의 감정을 분류해줘.

입력: 이 카페 분위기 레전드다
출력: 긍정

입력: 음식이 존맛탱이에요
출력: 긍정

입력: 서비스가 별로고 가성비도 구림
출력: 부정

입력: 인테리어는 갓벽한데 가격이 좀 세네요
출력:"

좋은 예시를 고르는 기준 #

다양성: 다양한 케이스를 포함해 AI가 패턴을 일반화하도록 유도
명확성: 각 입출력이 1:1로 명확하게 대응
일관성: 모든 예시가 동일한 형식을 따름
관련성: 실제 요청과 유사한 도메인의 예시 사용

Tip: Few-Shot에서 예시의 순서도 영향을 줍니다. 가장 관련성 높은 예시를 마지막에 배치하면 효과적입니다.

4️⃣ Chain-of-Thought (CoT) — 사고의 연쇄 #

Chain-of-Thought(CoT)는 AI가 최종 답을 바로 내놓는 대신 단계별 추론 과정을 거치도록 유도하는 기법입니다. 수학 계산, 논리 추론, 복잡한 판단 문제에서 정확도를 비약적으로 향상시킵니다.

Zero-Shot CoT #

“Let’s think step by step” 또는 “단계별로 생각해봐"라는 트리거 문장 하나만 추가해도 모델이 단계적 사고를 시작합니다.

# Zero-Shot CoT 예시
"철수는 사과를 5개 가지고 있었다. 영희에게 2개를 주고,
 마트에서 3개를 더 샀다. 철수에게 사과는 몇 개인가?

단계별로 생각하며 풀어줘."

# AI 응답 예시
1단계: 처음 사과 수 = 5개
2단계: 영희에게 준 후 = 5 - 2 = 3개
3단계: 마트에서 구매 후 = 3 + 3 = 6개
정답: 6개

Few-Shot CoT #

단계별 추론 과정을 포함한 예시를 제공하면 더 복잡한 추론도 정확하게 수행합니다.

# Few-Shot CoT 예시
"다음 문제를 단계별로 풀어줘.

Q: 버스에 승객이 10명 있었다. 정류장에서 3명이 내리고
 5명이 탔다. 버스에는 몇 명이 있는가?
A: 처음 10명에서 3명이 내리면 7명, 거기서 5명이 타면 12명.
 정답: 12명

Q: 상자에 공이 8개 있다. 4개를 꺼내고 2개를 넣었다.
 상자에는 몇 개가 남아있는가?
A:"

CoT가 효과적인 상황:

수학 계산 및 수식 풀기
논리 추론과 인과관계 분석
복잡한 다단계 의사결정
코드 디버깅 과정 추적

5️⃣ 기법 비교 한눈에 보기 #

기법	예시 수	장점	단점	적합한 작업
Zero-Shot	0개	빠르고 간편	복잡한 작업에서 불안정	번역, 요약, 단순 QA
One-Shot	1개	형식 가이드 가능	패턴 일반화 한계	형식이 명확한 작업
Few-Shot	2~5개	일관된 결과, 형식 제어	프롬프트 길이 증가	감정 분류, 데이터 변환
Zero-Shot CoT	0개 + 트리거	추론 품질 향상	단순 작업에는 과잉	수학, 논리, 분석
Few-Shot CoT	추론 과정 포함 예시	가장 높은 정확도	프롬프트 설계 복잡	복잡한 다단계 추론

🌳 고급 기법 1: Tree-of-Thought (ToT) #

Tree-of-Thought(ToT)는 CoT를 확장하여 여러 가능한 추론 경로를 동시에 탐색하는 기법입니다. 나무의 가지처럼 여러 방향으로 사고를 전개하고 최적의 경로를 선택합니다.

# Tree-of-Thought 프롬프트 예시
"다음 문제를 풀기 위한 3가지 접근법을 각각 제시하고,
 각 접근법의 장단점을 분석한 후 가장 효과적인 방법을 선택해줘.

문제: 스타트업의 초기 마케팅 예산 100만원을 어떻게 배분해야 할까?"

적합한 상황: 창의적 문제 해결, 전략 수립, 최적 방안 선택이 필요한 복잡한 의사결정

🔄 고급 기법 2: Self-Consistency (자기 일관성) #

Self-Consistency는 동일한 문제를 여러 번 풀게 한 후 가장 많이 나온 답을 선택하는 기법입니다. 여러 전문가의 의견을 다수결로 취합하는 앙상블 방식입니다.

# Self-Consistency 활용
"다음 코드의 버그를 3가지 다른 관점(성능, 보안, 가독성)에서
 각각 독립적으로 분석한 후, 공통으로 지적된 문제를 최우선으로 수정해줘."

CoT 결과의 신뢰도를 높이는 데 효과적이며, 중요한 판단이 필요할 때 활용합니다.

⚡ 고급 기법 3: ReAct (Reasoning + Acting) #

ReAct는 추론(Reasoning)과 행동(Acting)을 반복하는 기법으로, 외부 도구(검색, API, 코드 실행 등)와 연동하는 AI 에이전트에 사용됩니다.

Thought → Action → Observation → Thought → Action → ...

# ReAct 흐름 예시 (에이전트)
Thought: 현재 날씨를 알아야 추천이 가능하다.
Action: search("서울 오늘 날씨")
Observation: 서울 기온 12도, 비 예보

Thought: 비가 오므로 실내 활동을 추천해야 한다.
Action: search("서울 실내 주말 여행지")
Observation: 국립중앙박물관, CGV IMAX...

Final Answer: 오늘 비가 오니 국립중앙박물관 방문을 추천드립니다.

LangChain Agent, OpenAI Function Calling 같은 도구 연동 시스템이 이 방식을 기반으로 합니다.

🔗 고급 기법 4: Prompt Chaining (프롬프트 체이닝) #

복잡한 작업을 여러 단계의 프롬프트로 분해하여 앞 단계의 출력을 다음 단계의 입력으로 연결하는 방식입니다.

1# Prompt Chaining 예시 — 블로그 포스트 작성
2step1 = llm.invoke("다음 주제로 블로그 목차 5개를 작성해줘: {topic}")
3step2 = llm.invoke(f"다음 목차로 각 섹션의 핵심 내용 1문장씩 작성해줘:\n{step1}")
4step3 = llm.invoke(f"다음 개요를 바탕으로 전체 포스트를 작성해줘:\n{step2}")

한 번에 긴 작업을 시키면 품질이 떨어질 때, 단계별로 나눠서 각 단계의 품질을 보장합니다.

🛠️ 실무 프롬프트 설계 원칙 #

역할 부여 (Role Prompting) #

"너는 10년 경력의 시니어 백엔드 개발자야.
 다음 Python 코드를 프로덕션 레벨로 리뷰해줘."

출력 형식 명시 #

"다음 내용을 분석하고 아래 JSON 형식으로 반환해줘:
{
 "sentiment": "긍정|부정|중립",
 "confidence": 0.0~1.0,
 "key_phrases": ["키워드1", "키워드2"]
}"

제약 조건 설정 #

"다음 조건을 반드시 지켜서 답변해줘:
- 200자 이내로 작성
- 기술 용어 사용 금지
- 번호 목록 형식
- 한국어로만 답변"

부정형 대신 긍정형 지시 #

# ❌ 부정형 (AI가 헷갈릴 수 있음)
"전문 용어를 사용하지 말고, 너무 길게 쓰지 마세요."

# ✅ 긍정형 (명확한 지시)
"초등학생도 이해할 수 있는 쉬운 단어로, 3문장 이내로 설명해줘."

📊 기법 선택 가이드 #

작업이 단순하고 명확한가?
 └─ YES → Zero-Shot
 └─ NO ↓

원하는 출력 형식이 특수한가?
 └─ YES → Few-Shot (예시 2~5개 제공)
 └─ NO ↓

수학/논리/복잡한 추론이 필요한가?
 └─ YES → CoT (Zero-Shot CoT 또는 Few-Shot CoT)
 └─ NO ↓

여러 방안 중 최적을 찾아야 하는가?
 └─ YES → Tree-of-Thought
 └─ NO ↓

외부 도구(검색, API) 연동이 필요한가?
 └─ YES → ReAct
 └─ NO → Prompt Chaining으로 단계 분해

❓ 자주 묻는 질문 #

Q. Zero-Shot과 Few-Shot 중 무엇을 먼저 시도해야 하나요? #

항상 Zero-Shot부터 시작하세요. 원하는 결과가 나오지 않으면 예시를 1개(One-Shot), 그래도 부족하면 2~5개(Few-Shot)로 늘려가는 방식이 토큰 효율적입니다.

Q. CoT는 모든 LLM에서 효과가 있나요? #

GPT-4, Claude 3+, Gemini 1.5 같은 대형 모델에서 효과가 뚜렷합니다. 작은 모델(7B 이하)에서는 CoT의 효과가 제한적이거나 오히려 성능을 저하시킬 수 있습니다.

Q. Few-Shot 예시는 몇 개가 적당한가요? #

일반적으로 3~5개가 최적입니다. 예시가 너무 많으면 토큰을 낭비하고 프롬프트가 복잡해집니다. 5개를 넘으면 대부분의 경우 큰 성능 향상이 없습니다.

Q. “Let’s think step by step” 외에 CoT를 유도하는 문장이 있나요? #

다양한 트리거 문장이 효과적입니다:

“단계별로 생각해봐”
“풀이 과정을 보여줘”
“이유를 먼저 설명하고 결론을 내려줘”
“틀릴 수 있는 가능성을 먼저 검토하고 답해줘”

Q. 프롬프트 길이가 길수록 좋은가요? #

아닙니다. 불필요한 미사여구나 중복 설명은 오히려 LLM을 혼란시킬 수 있습니다. 간결하고 명확하게 핵심 지시만 포함하는 것이 원칙입니다.

[Backend] 🚀 Supabase란? Firebase·Appwrite와 차이점 완벽 비교

Sat, 01 Nov 2025 00:00:00 +0000

Supabase는 PostgreSQL 기반의 오픈소스 BaaS(Backend as a Service) 플랫폼으로, Firebase의 대안으로 설계되었습니다. 인증, 데이터베이스, 실시간 처리, 파일 스토리지, 서버리스 함수를 하나의 패키지로 제공하여 백엔드 인프라 구축 시간을 대폭 단축할 수 있습니다. 이 글에서는 Supabase의 핵심 개념과 Firebase, Appwrite와의 차이점을 실무 관점에서 비교합니다.

🧩 Supabase란? #

Supabase는 Google Firebase의 오픈소스 대안으로 2020년 등장한 BaaS(Backend as a Service) 플랫폼입니다. PostgreSQL을 핵심 데이터베이스로 사용하며, 인증·실시간 처리·파일 스토리지·서버리스 함수를 통합 제공합니다.

Firebase가 NoSQL(Firestore) 기반인 것과 달리, Supabase는 표준 SQL과 관계형 데이터 모델을 사용할 수 있다는 점이 가장 큰 차별점입니다. 오픈소스이기 때문에 클라우드 호스팅뿐만 아니라 자체 서버에서 셀프 호스팅도 가능합니다.

🔍 BaaS(Backend as a Service)란? #

BaaS는 “인증, 데이터베이스, 파일 스토리지 등 공통 백엔드 기능을 서비스로 제공하는 플랫폼"입니다. 개발자가 직접 서버를 구축하거나 API를 개발할 필요 없이, 프론트엔드 코드만으로 전체 애플리케이션을 만들 수 있게 해줍니다.

Tip: BaaS는 스타트업이나 소규모 팀이 빠른 시장 진입(MVP)이 필요할 때 특히 효과적입니다.

대표적인 BaaS 플랫폼으로는 Firebase, Supabase, Appwrite가 있으며, 각각 설계 철학이 다릅니다.

⚡ Firebase vs Supabase vs Appwrite 비교 #

항목	Firebase	Supabase	Appwrite
설계 방향	완제품 지향	통합 데이터 흐름	셀프 호스팅 자유도
데이터베이스	NoSQL (Firestore)	SQL (PostgreSQL)	SQL/NoSQL 선택
제공 방식	완전 관리형	관리형 + 로컬 개발	직접 운영
오픈소스	❌	✅	✅
벤더 락인	높음 (Google)	낮음	없음
권한 구조	기능별 분리	RLS 기반 통합	직접 구성
AI/벡터 지원	별도 솔루션 필요	pgvector 기본 지원	별도 설정 필요
적합 팀	MVP/모바일 팀	프론트 중심 소규모 팀	인프라 운영 가능 팀

Firebase가 적합한 경우 #

Firebase는 “모바일 앱 개발과 초고속 MVP 구현"에 최적화된 플랫폼입니다. Google 생태계와의 긴밀한 통합, 실시간 데이터 동기화, Firebase Analytics 등 모바일에 특화된 서비스가 강점입니다.

모바일(iOS/Android) 앱 개발 중심
Google 생태계 전반 활용이 필요한 경우
NoSQL 데이터 구조에 익숙한 팀

Supabase가 적합한 경우 #

Supabase는 “SQL에 익숙한 팀이 빠른 개발과 통제권을 동시에 원할 때” 최적입니다. 장기 운영을 고려하면서도 빠르게 제품을 출시해야 하는 팀에 어울립니다.

SQL 및 관계형 데이터베이스에 익숙한 팀
AI/ML 기능을 앱에 통합할 계획이 있는 경우
Firebase의 벤더 락인을 피하고 싶은 경우

Appwrite가 적합한 경우 #

Appwrite는 “인프라를 직접 운영할 수 있는 팀이 완전한 데이터 주권을 원할 때” 적합합니다. 셀프 호스팅을 통해 데이터를 완전히 통제할 수 있습니다.

데이터를 자체 서버에서 완전히 통제해야 하는 경우
인프라 운영 역량이 있는 팀
오픈소스 커스터마이징이 필요한 경우

🛠️ Supabase 핵심 기능 #

1️⃣ Database (PostgreSQL) #

Supabase의 데이터베이스는 완전한 PostgreSQL입니다. 복잡한 SQL 쿼리, 조인, 트랜잭션, 인덱스를 모두 활용할 수 있으며, Row Level Security(RLS)로 사용자별 데이터 접근 권한을 DB 레벨에서 제어합니다.

1-- RLS 정책 예시: 사용자가 자신의 데이터만 조회
2CREATE POLICY "users can view own data"
3ON profiles
4FOR SELECT
5USING (auth.uid() = user_id);

Tip: RLS를 활성화하면 API에서 별도 권한 체크 없이 DB 자체에서 보안이 처리됩니다.

2️⃣ Auth (인증) #

Supabase Auth는 이메일/패스워드, 소셜 로그인(Google, GitHub, Apple), OTP, 패스키를 대시보드에서 클릭 몇 번으로 설정할 수 있습니다. JWT 기반의 토큰과 세션 관리는 자동으로 처리됩니다.

 1import { createClient } from '@supabase/supabase-js'
 2
 3const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY)
 4
 5// 소셜 로그인 (GitHub)
 6const { data, error } = await supabase.auth.signInWithOAuth({
 7 provider: 'github'
 8})
 9
10// 이메일 로그인
11const { data, error } = await supabase.auth.signInWithPassword({
12 email: 'user@example.com',
13 password: 'password'
14})

3️⃣ Realtime (실시간 처리) #

Supabase Realtime은 PostgreSQL의 변경 사항을 웹소켓으로 클라이언트에 즉시 전달합니다. 별도 폴링 없이 채팅, 알림, 협업 도구를 구현할 수 있습니다.

 1// 실시간 메시지 구독
 2const channel = supabase
 3 .channel('messages')
 4 .on(
 5 'postgres_changes',
 6 { event: 'INSERT', schema: 'public', table: 'messages' },
 7 (payload) => {
 8 console.log('새 메시지:', payload.new)
 9 }
10 )
11 .subscribe()

4️⃣ Storage (파일 관리) #

이미지·동영상 업로드 시 자동 썸네일 변환, CDN 연동, RLS 기반 접근 제어가 기본 내장되어 있습니다.

1// 파일 업로드
2const { data, error } = await supabase.storage
3 .from('avatars')
4 .upload(`${userId}/avatar.png`, file)
5
6// 퍼블릭 URL 조회
7const { data } = supabase.storage
8 .from('avatars')
9 .getPublicUrl(`${userId}/avatar.png`)

5️⃣ Edge Functions (서버리스) #

Deno 기반의 서버리스 함수로 인증 체크, 웹훅 처리, 외부 API 호출, AI 연동 등 서버 로직을 빠르게 배포할 수 있습니다.

 1// Edge Function 예시: OpenAI 연동
 2import { serve } from 'https://deno.land/std@0.177.0/http/server.ts'
 3
 4serve(async (req) => {
 5 const { query } = await req.json()
 6
 7 const response = await fetch('https://api.openai.com/v1/chat/completions', {
 8 method: 'POST',
 9 headers: {
10 'Authorization': `Bearer ${Deno.env.get('OPENAI_API_KEY')}`,
11 'Content-Type': 'application/json'
12 },
13 body: JSON.stringify({
14 model: 'gpt-4o',
15 messages: [{ role: 'user', content: query }]
16 })
17 })
18
19 return new Response(await response.text(), {
20 headers: { 'Content-Type': 'application/json' }
21 })
22})

6️⃣ Vector DB (pgvector) #

Supabase는 pgvector 확장을 기본 지원하여 별도 벡터 데이터베이스 없이 PostgreSQL 안에서 AI 임베딩 저장과 유사도 검색을 처리할 수 있습니다.

 1-- pgvector 확장 활성화
 2CREATE EXTENSION IF NOT EXISTS vector;
 3
 4-- 임베딩 컬럼이 있는 테이블 생성
 5CREATE TABLE documents (
 6 id BIGSERIAL PRIMARY KEY,
 7 content TEXT,
 8 embedding VECTOR(1536)
 9);
10
11-- 코사인 유사도 검색
12SELECT content, 1 - (embedding <=> query_embedding) AS similarity
13FROM documents
14ORDER BY embedding <=> query_embedding
15LIMIT 5;

Tip: Supabase + pgvector 조합은 RAG(Retrieval-Augmented Generation) 시스템 구축에 매우 효과적입니다.

💰 요금제 비교 #

플랜	가격	DB 용량	스토리지	MAU	특이사항
Free	무료	500MB	1GB	10,000	1주 미사용 시 자동 중지, 2개 프로젝트 제한
Pro	$25/월	8GB	100GB	100,000	자동 백업, 커스텀 도메인
Team	$599/월	커스텀	커스텀	무제한	SOC2, HIPAA, SSO 지원
Enterprise	문의	커스텀	커스텀	무제한	전용 서버, SLA 보장

⚠️ Free 플랜은 7일 동안 활동이 없으면 프로젝트가 자동 일시정지됩니다. 개인 프로젝트나 테스트 환경에서 주의가 필요합니다.

✅ Supabase 장단점 요약 #

장점 #

SQL 표준 지원: 복잡한 관계형 쿼리, 조인, 트랜잭션 완전 지원
오픈소스: 벤더 락인 없이 자체 호스팅으로 전환 가능
AI 통합 용이: pgvector로 벡터 DB를 별도 서비스 없이 활용
통합 솔루션: 인증·DB·스토리지·실시간·함수가 하나의 패키지
비용 예측 가능: Firebase의 사용량 기반 과금과 달리 플랜 기반 정액제

단점 #

Free 플랜 제약: 1주 미사용 시 자동 일시정지, 2개 프로젝트 제한
Region 고정: 프로젝트 생성 후 리전 변경 불가
PostgreSQL 기본 지식 필요: SQL에 익숙하지 않으면 초기 설정이 어려울 수 있음
Firebase 마이그레이션 복잡도: NoSQL → 관계형 전환 시 데이터 재설계 필요

🚀 빠른 시작 가이드 #

Supabase CLI 설치 및 로컬 개발 환경 구성 #

 1# Supabase CLI 설치
 2npm install -g supabase
 3
 4# 로그인
 5supabase login
 6
 7# 새 프로젝트 초기화
 8supabase init
 9
10# 로컬 개발 서버 시작 (Docker 필요)
11supabase start

Next.js + Supabase 연동 #

1npm install @supabase/supabase-js @supabase/ssr

1// lib/supabase.ts
2import { createBrowserClient } from '@supabase/ssr'
3
4export const supabase = createBrowserClient(
5 process.env.NEXT_PUBLIC_SUPABASE_URL!,
6 process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
7)

1// 데이터 조회 예시
2const { data: posts, error } = await supabase
3 .from('posts')
4 .select('id, title, created_at')
5 .order('created_at', { ascending: false })
6 .limit(10)

❓ 자주 묻는 질문 #

Q. Supabase와 Firebase 중 무엇을 선택해야 하나요? #

SQL과 관계형 데이터에 익숙하거나 AI 기능 통합이 필요하다면 Supabase를 권장합니다. 모바일 앱 개발이 주목적이고 Google 생태계를 적극 활용한다면 Firebase가 더 적합합니다.

Q. Supabase는 셀프 호스팅이 가능한가요? #

네, 가능합니다. Supabase는 오픈소스이며 Docker Compose로 자체 서버에 배포할 수 있습니다. supabase/supabase GitHub 리포지토리에서 공식 셀프 호스팅 가이드를 확인할 수 있습니다.

Q. Free 플랜의 프로젝트 자동 중지를 방지할 수 있나요? #

무료 플랜에서는 7일 연속 미사용 시 자동 일시정지됩니다. 주기적으로 접속하거나, Pro 플랜($25/월)으로 업그레이드하면 이 제한이 사라집니다.

Q. pgvector를 활용한 AI 기능은 어떻게 사용하나요? #

Supabase 대시보드의 Database > Extensions 탭에서 vector 확장을 활성화합니다. 이후 VECTOR 타입 컬럼을 가진 테이블을 생성하고 OpenAI 등 임베딩 모델로 생성한 벡터를 저장하면 유사도 검색이 가능합니다.

Q. Free 플랜의 프로젝트 개수 제한은? #

Free 플랜에서는 최대 2개의 프로젝트를 생성할 수 있습니다. Pro 플랜부터는 제한이 없습니다.

[Python] 🔍 Pylint로 Python 코드 품질 관리하기: 설치부터 CI/CD 연동까지

Wed, 01 Oct 2025 00:00:00 +0000

Pylint는 Python 코드의 오류 검출, PEP 8 스타일 위반, 코드 복잡도 분석을 수행하는 정적 분석 도구입니다. 단순한 스타일 검사를 넘어 잠재적 버그까지 탐지하며, 10점 만점 품질 점수를 제공합니다. 이 글에서는 Pylint의 기본 사용법부터 .pylintrc 설정, VSCode 연동, pre-commit CI/CD 통합까지 실무에서 바로 활용할 수 있도록 정리합니다.

🔍 Pylint란? #

Pylint는 Python 코드를 실행하지 않고도 품질 문제를 탐지하는 정적 코드 분석(static analysis) 도구입니다. 단순한 스타일 검사기를 넘어, 런타임 이전에 발견하기 어려운 버그와 잠재적 오류까지 잡아냅니다.

주요 검사 항목은 다음과 같습니다:

문법 오류 및 잠재적 버그 — 정의되지 않은 변수, self 누락, 잘못된 import 등
PEP 8 코딩 표준 위반 — 명명 규칙(snake_case, PascalCase), 줄 길이, 공백 등
코드 복잡도 — 중복 코드, 너무 긴 함수, 지나치게 많은 인자 등
문서화 부재 — docstring 미작성 경고
10점 만점 품질 점수 — 코드 전체의 상태를 수치로 확인

Tip: Pylint의 경고가 절대적인 기준은 아닙니다. 의도된 코드가 경고를 받을 수 있으므로, 프로젝트 상황에 맞게 규칙을 조정하는 것이 중요합니다.

⚖️ Linter vs Formatter 차이 #

코드 품질 도구를 처음 접할 때 가장 혼란스러운 부분이 Linter와 Formatter의 차이입니다.

구분	Linter	Formatter
역할	코드의 논리 오류·잠재적 버그 탐지	코드 스타일·레이아웃 자동 정리
동작	문제를 보고하고 수정은 개발자가 직접	코드를 자동으로 수정
예시	미사용 변수, import 오류, 명명 규칙 위반	들여쓰기 정렬, 따옴표 통일, 줄 바꿈
대표 도구	Pylint, Flake8, Ruff	Black, YAPF, Ruff(format)

📊 Python 코드 품질 도구 비교 #

실무에서 자주 함께 언급되는 4가지 도구를 비교합니다.

도구	분류	특징	속도
Pylint	Linter	가장 엄격, 품질 점수 제공, 심층 분석	느림
Flake8	Linter	안정적, PEP 8 중심, 설정 간단	빠름
Black	Formatter	설정 없이 일관된 스타일 강제, 팀 협업 최적	빠름
Ruff	Linter + Formatter	Rust 기반, 매우 빠름, Flake8+isort+Black 통합	매우 빠름

Flake8 ─ 스타일 검사 → 오류 보고
Pylint ─ 심층 분석 → 오류 보고 + 개선 제안 + 품질 점수
Black ─ 자동 포맷팅 → 코드 직접 수정
Ruff ─ lint + format → 위 세 도구를 대부분 대체

Tip: 2026년 현재는 Ruff 단독 사용으로 lint·format·import 정리까지 처리하는 방식이 증가 중입니다. 하지만 Pylint는 Ruff가 탐지하지 못하는 심층 분석(코드 냄새, 복잡도, 품질 점수)에서 여전히 강점이 있습니다.

🚀 설치 및 기본 사용법 #

설치 #

1pip install pylint

가상 환경을 사용하는 경우 환경 활성화 후 설치합니다.

1python -m venv .venv
2source .venv/bin/activate # Windows: .venv\Scripts\activate
3pip install pylint

파일 분석 #

1# 단일 파일 분석
2pylint my_script.py
3
4# 모듈 전체 분석
5pylint my_package/
6
7# 여러 파일 동시 분석
8pylint src/main.py src/utils.py

출력 결과 예시 #

my_script.py:5:0: C0304: Final newline missing (missing-final-newline)
my_script.py:10:4: W0611: Unused import os (unused-import)
my_script.py:15:0: E1101: Module 'os' has no 'pathh' member (no-member)

-----------------------------------
Your code has been rated at 6.50/10

출력 형식은 파일명:줄번호:컬럼:메시지코드: 설명 (코드명) 입니다.

📋 메시지 유형과 코드 이해하기 #

Pylint 메시지는 알파벳 접두사로 심각도를 구분합니다.

접두사	유형	의미
C	Convention	PEP 8 등 코딩 규칙 위반
W	Warning	잠재적 문제, 개선 권장
E	Error	런타임 오류로 이어질 가능성이 높은 버그
R	Refactor	리팩토링이 필요한 코드 구조
F	Fatal	분석 자체를 막는 치명적 오류

자주 마주치는 메시지 코드 #

코드	이름	설명
`C0301`	line-too-long	줄 길이 초과 (기본 100자)
`C0114`	missing-module-docstring	모듈 docstring 없음
`C0116`	missing-function-docstring	함수 docstring 없음
`W0611`	unused-import	사용하지 않는 import
`W0612`	unused-variable	사용하지 않는 변수
`W1203`	logging-fstring	로깅에 f-string 사용 (lazy loading 불가)
`E0401`	import-error	모듈을 찾을 수 없음
`E1101`	no-member	존재하지 않는 속성/메서드 접근
`R0913`	too-many-arguments	함수 인자 수 초과 (기본 5개)
`R1705`	no-else-return	return 후 불필요한 else 블록

⚙️ .pylintrc 설정 파일 #

프로젝트 루트에 .pylintrc 파일을 두면 팀 전체에 일관된 규칙을 적용할 수 있습니다.

기본 템플릿 생성 #

1pylint --generate-rcfile > .pylintrc

주요 설정 항목 #

 1[MASTER]
 2# 가상환경, 외부 라이브러리 경로 추가
 3init-hook='import sys; sys.path.insert(0, "src")'
 4
 5# 병렬 처리 (0 = CPU 수에 맞게 자동)
 6jobs=0
 7
 8[MESSAGES CONTROL]
 9# 비활성화할 메시지 코드 (쉼표로 구분)
10disable=
11 C0114, # missing-module-docstring
12 C0115, # missing-class-docstring
13 C0116, # missing-function-docstring
14 W1203 # logging-fstring
15
16[FORMAT]
17# 한 줄 최대 길이 (PEP 8 기본값 79, 실무 100~120 권장)
18max-line-length=120
19
20# 들여쓰기 단위
21indent-string=' '
22
23[DESIGN]
24# 함수 최대 인자 수
25max-args=7
26
27# 함수 최대 줄 수
28max-statements=50
29
30[TYPECHECK]
31# 외부 라이브러리 타입 체크 오류 무시
32ignored-modules=numpy,pandas,pydantic

🔕 경고 비활성화 방법 #

프로젝트 전체가 아닌 특정 코드에만 규칙을 비활성화할 때 인라인 주석을 사용합니다.

1줄 비활성화 #

1import os # pylint: disable=unused-import

블록 단위 비활성화 #

1# pylint: disable=too-many-arguments
2def complex_function(a, b, c, d, e, f):
3 pass
4# pylint: enable=too-many-arguments

파일 전체 비활성화 #

파일 최상단에 추가합니다.

1# pylint: disable=missing-module-docstring,missing-function-docstring

⚠️ 인라인 비활성화를 남용하면 Pylint의 효과가 떨어집니다. 실제로 불필요한 경고만 선택적으로 끄고, 가능하면 .pylintrc에서 프로젝트 전체 기준을 설정하는 것이 바람직합니다.

🖥️ VSCode 연동 #

settings.json 설정 #

.vscode/settings.json에 다음을 추가합니다.

1{
2 "python.linting.enabled": true,
3 "python.linting.pylintEnabled": true,
4 "python.linting.pylintArgs": [
5 "--disable", "C0301",
6 "--max-line-length", "120"
7 ]
8}

저장 시 자동 검사 #

1{
2 "editor.formatOnSave": true,
3 "python.linting.lintOnSave": true
4}

Tip: VSCode의 Python 확장(ms-python.python)을 설치하면 편집 중 실시간으로 Pylint 오류가 표시됩니다.

🔗 pre-commit으로 CI/CD 통합 #

커밋 시점에 Pylint를 자동 실행하면, 오류가 있는 코드는 커밋 자체가 차단됩니다.

pre-commit 설치 #

1pip install pre-commit

.pre-commit-config.yaml 작성 #

 1repos:
 2 - repo: https://github.com/pycqa/pylint
 3 rev: v3.3.0
 4 hooks:
 5 - id: pylint
 6 args:
 7 - "--max-line-length=120"
 8 - "--disable=C0114,C0115,C0116"
 9 additional_dependencies:
10 - pydantic
11 - pyyaml
12 - requests

훅 설치 및 실행 #

1# 훅 설치 (최초 1회)
2pre-commit install
3
4# 전체 파일 수동 실행
5pre-commit run --all-files

이후 git commit 시 자동으로 Pylint가 실행되며, 오류가 있으면 커밋이 차단됩니다.

GitHub Actions 통합 #

 1name: Lint
 2
 3on: [push, pull_request]
 4
 5jobs:
 6 pylint:
 7 runs-on: ubuntu-latest
 8 steps:
 9 - uses: actions/checkout@v4
10 - uses: actions/setup-python@v5
11 with:
12 python-version: "3.12"
13 - run: pip install pylint
14 - run: pylint src/ --fail-under=8.0

--fail-under=8.0 옵션으로 품질 점수가 8점 미만이면 CI가 실패합니다.

💡 실무 적용 팁 #

점진적 도입 전략 #

기존 프로젝트에 Pylint를 도입할 때는 처음부터 모든 규칙을 강제하면 수백 개의 오류가 나올 수 있습니다. 아래 순서로 단계적으로 접근하는 것을 권장합니다.

E(Error) 먼저 — 런타임 오류로 이어지는 치명적 문제 우선 해결
W(Warning) 다음 — 잠재적 버그와 개선 권장 사항 처리
C/R 마지막 — 코딩 규칙과 리팩토링은 여유를 두고 개선

자주 발생하는 오류 해결 #

오류	원인	해결책
`E0401 import-error`	모듈을 찾을 수 없음	`.pylintrc`의 `init-hook`으로 경로 추가
`W1203 logging-fstring`	로깅에 f-string 사용	`logger.info("값: %s", value)` 형태로 변경
`R1705 no-else-return`	return 후 else 블록	else 제거 후 들여쓰기 감소
`C0301 line-too-long`	줄 길이 초과	max-line-length 조정 또는 줄 바꿈

Pyreverse로 UML 다이어그램 생성 #

Pylint 패키지에 포함된 pyreverse로 클래스 구조를 시각화할 수 있습니다. Graphviz 설치 후 실행합니다.

1pip install pylint
2brew install graphviz # macOS
3
4pyreverse -o png -p MyProject my_package/

classes_MyProject.png와 packages_MyProject.png 파일이 생성됩니다.

❓ 자주 묻는 질문 #

Q. Pylint와 Flake8 중 무엇을 써야 하나요? #

간단한 스타일 검사가 목적이라면 Flake8이 빠르고 설정이 쉽습니다. 잠재적 버그 탐지, 코드 복잡도 분석, 품질 점수까지 필요하다면 Pylint가 적합합니다. 실무에서는 두 도구를 함께 사용하거나, 최근에는 Ruff로 통합하는 경우가 많습니다.

Q. Pylint 점수 10점을 목표로 해야 하나요? #

아닙니다. 10점이 항상 좋은 코드를 의미하지는 않습니다. 팀의 기준(예: 8.0 이상)을 설정하고, 점수보다는 E·W 오류 0건을 목표로 삼는 것이 더 실용적입니다.

Q. 외부 라이브러리(numpy, pandas) 사용 시 E0401 오류가 계속 나옵니다. #

.pylintrc의 [TYPECHECK] 섹션에 해당 라이브러리를 추가합니다.

1[TYPECHECK]
2ignored-modules=numpy,pandas,torch,tensorflow

Q. pre-commit 사용 시 가상환경 패키지를 인식하지 못합니다. #

.pre-commit-config.yaml의 additional_dependencies에 프로젝트에서 사용하는 패키지를 명시해야 합니다.

1additional_dependencies:
2 - pydantic
3 - sqlalchemy
4 - fastapi

[Kubernetes] 🛡️ OPA Gatekeeper vs Kyverno: 쿠버네티스 정책 관리 완전 가이드

Fri, 26 Sep 2025 00:00:00 +0000

쿠버네티스 클러스터를 운영하다 보면 “모든 Pod에 리소스 제한을 설정해야 한다”, “승인된 레지스트리의 이미지만 사용해야 한다"처럼 조직 차원의 정책을 강제해야 하는 상황이 생깁니다. 이를 코드 리뷰에만 의존하면 누락이 발생하기 쉽습니다. OPA Gatekeeper와 Kyverno는 이런 정책을 클러스터 레벨에서 자동으로 강제하는 대표적인 도구입니다.

🔑 Kubernetes 정책 관리란? #

쿠버네티스는 리소스 생성·수정·삭제 요청이 API 서버에 도달했을 때 이를 검사하는 Admission Controller 플러그인을 제공합니다.

1kubectl apply
2 ↓
3API Server
4 ↓
5Authentication → Authorization → Admission Control → etcd 저장
6 ↑
7 Mutating / Validating Webhook
8 (Gatekeeper / Kyverno 가 여기서 동작)

두 도구 모두 Webhook 형태로 동작하며 요청을 가로채 정책 준수 여부를 검사합니다.

Tip: 쿠버네티스 1.25에서 Pod Security Policy(PSP)가 제거된 이후 OPA Gatekeeper와 Kyverno가 PSP의 실질적인 대안으로 자리잡았습니다.

🔵 OPA Gatekeeper #

개념 및 아키텍처 #

OPA(Open Policy Agent) 는 CNCF에서 관리하는 범용 정책 엔진입니다. Gatekeeper는 OPA를 쿠버네티스 Admission Webhook과 연결하는 브리지 역할을 합니다.

 1API Server
 2 │ AdmissionReview 요청
 3 ▼
 4Gatekeeper Webhook
 5 │ Rego 정책 평가
 6 ▼
 7OPA (정책 평가 엔진)
 8 │ allow / deny 반환
 9 ▼
10API Server (요청 허용 or 거부)

Gatekeeper v3.0부터는 OPA Constraint Framework를 기반으로 CRD(Custom Resource Definition)를 통해 정책을 선언적으로 관리합니다.

ConstraintTemplate — 정책 템플릿 정의 #

ConstraintTemplate은 정책의 로직(Rego)과 파라미터 스키마를 정의하는 청사진입니다. 한 번 정의하면 여러 클러스터, 여러 네임스페이스에 재사용할 수 있습니다.

 1apiVersion: templates.gatekeeper.sh/v1beta1
 2kind: ConstraintTemplate
 3metadata:
 4 name: k8srequiredlabels
 5spec:
 6 crd:
 7 spec:
 8 names:
 9 kind: K8sRequiredLabels
10 validation:
11 openAPIV3Schema:
12 properties:
13 labels:
14 type: array
15 items:
16 type: string
17 targets:
18 - target: admission.k8s.gatekeeper.sh
19 rego: |
20 package k8srequiredlabels
21
22 deny[{"msg": msg, "details": {"missing_labels": missing}}] {
23 provided := {label | input.review.object.metadata.labels[label]}
24 required := {label | label := input.parameters.labels[_]}
25 missing := required - provided
26 count(missing) > 0
27 msg := sprintf("필수 레이블이 누락되었습니다: %v", [missing])
28 }

Constraint — 정책 인스턴스 생성 #

ConstraintTemplate으로 만들어진 CRD를 인스턴스화하여 실제 정책을 적용합니다. match 필드로 적용 대상을 세밀하게 지정할 수 있습니다.

 1apiVersion: constraints.gatekeeper.sh/v1beta1
 2kind: K8sRequiredLabels
 3metadata:
 4 name: ns-must-have-owner
 5spec:
 6 match:
 7 kinds:
 8 - apiGroups: [""]
 9 kinds: ["Namespace"]
10 parameters:
11 labels: ["owner", "env"]

위 정책 적용 후 owner, env 레이블 없이 네임스페이스를 생성하면 아래처럼 거부됩니다.

1Error from server ([ns-must-have-owner] 필수 레이블이 누락되었습니다: {"env", "owner"})

설치 #

1# Helm으로 설치
2helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts
3helm install gatekeeper/gatekeeper \
4 --name-template=gatekeeper \
5 --namespace gatekeeper-system \
6 --create-namespace

1# 또는 manifest로 설치
2kubectl apply -f https://raw.githubusercontent.com/open-policy-agent/gatekeeper/master/deploy/gatekeeper.yaml

설치 후 gatekeeper-system 네임스페이스에 컨트롤러 파드가 생성됩니다.

1kubectl get pods -n gatekeeper-system
2# NAME READY STATUS
3# gatekeeper-audit-xxxxxxxxx 1/1 Running
4# gatekeeper-controller-manager-xxxxxxxxx 1/1 Running

Audit 기능 #

Gatekeeper는 Audit 기능을 통해 이미 배포된 리소스도 정책 위반 여부를 감사합니다. 정책 적용 시점 이전에 생성된 리소스까지 소급 검사할 수 있습니다.

1# 정책 위반 리소스 확인
2kubectl get k8srequiredlabels ns-must-have-owner -o yaml
3# status.violations 필드에 위반 리소스 목록이 표시됩니다

또한 클러스터 내 리소스를 Gatekeeper에 복제하여 정책 간 데이터 참조가 가능합니다.

 1apiVersion: config.gatekeeper.sh/v1alpha1
 2kind: Config
 3metadata:
 4 name: config
 5 namespace: gatekeeper-system
 6spec:
 7 sync:
 8 syncOnly:
 9 - group: ""
10 version: "v1"
11 kind: "Namespace"

🟢 Kyverno #

개념 및 아키텍처 #

Kyverno는 Kubernetes Native 정책 엔진입니다. 정책을 Rego 같은 별도 언어 없이 순수 YAML(CR)로 표현할 수 있어 학습 곡선이 낮습니다.

1API Server
2 │ AdmissionReview 요청
3 ▼
4Kyverno Webhook
5 │ ClusterPolicy / Policy 평가
6 ├── Mutate → 리소스 자동 수정 후 허용
7 ├── Validate → 검증 실패 시 거부
8 └── Generate → 새 리소스 자동 생성

Kyverno는 4개의 컨트롤러로 구성됩니다.

컨트롤러	역할
Webhook	AdmissionReview 요청 처리
Monitor	필수 설정(웹훅 등) 유지 관리
PolicyController	정책 CR 변경 감시
GenerateController	Generate 정책으로 생성된 리소스 관리

설치 #

1# Helm으로 설치 (권장)
2helm repo add kyverno https://kyverno.github.io/kyverno/
3helm repo update
4helm install kyverno kyverno/kyverno \
5 -n kyverno \
6 --create-namespace

1# 또는 manifest로 설치
2kubectl create -f https://raw.githubusercontent.com/kyverno/kyverno/main/config/install.yaml

⚠️ Kyverno는 Kubernetes 1.14 이상이 필요합니다. 고가용성 환경에서는 replicaCount=3으로 설정을 권장합니다.

정책 유형 #

Kyverno 정책은 ClusterPolicy(클러스터 전체) 또는 Policy(네임스페이스 범위) 두 가지 스코프로 생성합니다.

유형	설명	실행 시점
Validate	리소스가 정책을 준수하는지 검증	생성·수정 시
Mutate	리소스를 자동으로 수정	생성·수정 시 (Validate 전)
Generate	새로운 리소스를 자동 생성	트리거 리소스 생성 시
Cleanup	불필요한 리소스를 자동 삭제	주기적 실행

Validate 예제: 필수 레이블 강제 #

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4 name: require-app-label
 5spec:
 6 validationFailureAction: Enforce  # Audit으로 변경하면 감사 모드
 7 rules:
 8 - name: check-app-label
 9 match:
10 any:
11 - resources:
12 kinds:
13 - Pod
14 validate:
15 message: "레이블 'app.kubernetes.io/name' 이 필요합니다."
16 pattern:
17 metadata:
18 labels:
19 app.kubernetes.io/name: "?*"

정책 위반 시 아래 메시지와 함께 거부됩니다.

1Error from server: admission webhook "validate.kyverno.svc-fail" denied the request:
2resource Pod was blocked due to the following policies: require-app-label

Mutate 예제: 리소스 제한 자동 주입 #

레이블이나 리소스 제한이 없는 Pod에 기본값을 자동으로 삽입합니다.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4 name: add-default-resources
 5spec:
 6 rules:
 7 - name: add-resource-limits
 8 match:
 9 any:
10 - resources:
11 kinds:
12 - Pod
13 mutate:
14 patchStrategicMerge:
15 spec:
16 containers:
17 - (name): "*"
18 resources:
19 limits:
20 +(memory): "256Mi"
21 +(cpu): "500m"

Tip: +() 표기는 해당 필드가 없을 때만 값을 추가합니다. 기존 설정을 덮어쓰지 않습니다.

Generate 예제: 네임스페이스 생성 시 NetworkPolicy 자동 생성 #

새 네임스페이스가 생성될 때 기본 NetworkPolicy를 자동으로 생성합니다.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4 name: default-network-policy
 5spec:
 6 rules:
 7 - name: default-deny-ingress
 8 match:
 9 any:
10 - resources:
11 kinds:
12 - Namespace
13 generate:
14 apiVersion: networking.k8s.io/v1
15 kind: NetworkPolicy
16 name: default-deny-ingress
17 namespace: "{{request.object.metadata.name}}"
18 synchronize: true
19 data:
20 spec:
21 podSelector: {}
22 policyTypes:
23 - Ingress

⚖️ OPA Gatekeeper vs Kyverno 비교 #

항목	OPA Gatekeeper	Kyverno
정책 언어	Rego (전용 DSL)	YAML (Kubernetes 네이티브)
학습 곡선	높음 (Rego 학습 필요)	낮음
적용 범위	멀티 플랫폼 (쿠버네티스 외 지원)	쿠버네티스 전용
정책 유형	Validate, Audit	Validate, Mutate, Generate, Cleanup
Mutate 지원	제한적	강력한 기본 지원
Generate 지원	✗	✅
Audit	✅ (내장)	✅ (내장)
CLI 도구	OPA CLI	Kyverno CLI
CNCF 등급	Graduated	Incubating
커뮤니티 성숙도	높음	빠르게 성장 중

🎯 어떤 것을 선택할까? #

OPA Gatekeeper를 선택해야 할 때:

쿠버네티스 외 다른 시스템(Terraform, API 서버 등)에도 동일한 정책 엔진을 사용하고 싶은 경우
정책 로직이 복잡하여 Rego의 표현력이 필요한 경우
이미 OPA 생태계를 사용 중인 경우

Kyverno를 선택해야 할 때:

쿠버네티스 전용 정책 관리가 목적인 경우
Rego 학습 없이 빠르게 도입하고 싶은 경우
Mutate, Generate 등 다양한 정책 유형이 필요한 경우
GitOps 환경에서 YAML 기반으로 정책을 관리하고 싶은 경우

Tip: 두 도구를 함께 사용하는 것도 가능합니다. 예를 들어 복잡한 검증 정책은 OPA Gatekeeper로, 리소스 자동 변형·생성은 Kyverno로 역할을 분담할 수 있습니다.

[AI] 🤝 CrewAI: 멀티 에이전트 AI 협업 프레임워크 완벽 가이드

Thu, 21 Aug 2025 00:00:00 +0000

CrewAI는 여러 AI Agent가 인간 팀처럼 역할을 나누고 협력하여 복잡한 작업을 처리하는 멀티 에이전트 오케스트레이션 프레임워크입니다. 단일 LLM 호출로는 해결하기 어려운 리서치·작성·분석·코딩 등 다단계 작업을 Agent 팀이 분업하여 처리합니다. 이 글에서는 핵심 구성요소, 프로세스 유형, 메모리 시스템, Python 코드 예제를 실무 기준으로 정리합니다.

🤝 CrewAI란? #

CrewAI는 역할 기반 AI Agent 협업 플랫폼입니다. 각 Agent는 특정 전문 역할(리서처, 작가, 분석가 등)을 부여받고, 독립적으로 작업을 수행하거나 다른 Agent에게 위임하면서 팀 목표를 달성합니다.

1사용자 입력 (목표)
2 ↓
3 Crew 오케스트레이터
4 ┌────┴────┐
5Agent A Agent B Agent C
6(리서처) (작가) (검수자)
7 └────┬────┘
8 최종 결과물

항목	단일 LLM	CrewAI 멀티 에이전트
작업 복잡도	단순 단발성	다단계·복합 작업
전문화	범용	역할별 전문화
컨텍스트	단일 대화	에이전트 간 공유·누적
확장성	제한적	Agent 추가로 수평 확장

🧱 핵심 구성요소 #

Agent — 자율 작업 단위 #

Agent는 특정 역할과 목표를 가진 자율적 AI 소프트웨어입니다.

파라미터	설명
`role`	Agent의 기능/직책 정의
`goal`	개별 목표로 의사결정 방향 제시
`backstory`	배경 스토리로 역할 맥락 강화
`tools`	사용 가능한 도구 목록
`llm`	사용할 LLM (기본값: OpenAI GPT-4)
`verbose`	`True` 설정 시 실행 로그 출력
`allow_delegation`	`True`면 다른 Agent에게 작업 위임 가능
`memory`	`True`면 메모리 시스템 활성화
`max_iter`	최대 반복 횟수 (기본값: 15)

Task — 구체적 작업 단위 #

Agent가 수행할 명확한 과제를 정의합니다.

파라미터	설명
`description`	작업 내용과 수행 방법
`agent`	담당 Agent 지정
`expected_output`	기대 결과물 형식 설명
`tools`	해당 Task에만 사용되는 도구
`context`	이전 Task 출력을 컨텍스트로 전달
`output_file`	결과를 파일로 저장

Tool — Agent의 외부 능력 #

Agent가 실제 데이터를 수집하거나 외부 서비스와 상호작용하는 함수입니다.

1from crewai_tools import SerperDevTool, ScrapeWebsiteTool, WebsiteSearchTool
2
3search_tool = SerperDevTool() # Google 검색
4scrape_tool = ScrapeWebsiteTool() # 웹 페이지 스크래핑
5rag_tool = WebsiteSearchTool() # 웹 콘텐츠 RAG 검색

Process — 작업 흐름 조율 방식 #

프로세스	설명
`Process.sequential`	작업을 순서대로 실행, 앞 결과가 다음 컨텍스트가 됨
`Process.hierarchical`	매니저 Agent가 작업을 하위 Agent에게 위임·검수

Crew — 최상위 오케스트레이터 #

Agent와 Task를 모아서 실행 계획을 관리하는 최상위 구조입니다.

📦 설치 #

1pip install crewai
2pip install 'crewai[tools]' # 기본 도구 모음 포함

환경 변수 설정 (.env 파일):

1OPENAI_API_KEY=sk-...
2SERPER_API_KEY=... # SerperDevTool 사용 시 필요

🚀 빠른 시작: 블로그 글 자동 작성 에이전트 #

리서처 Agent가 주제를 조사하고, 에디터 Agent가 블로그 글을 작성하는 2인 팀 예제입니다.

 1import os
 2from dotenv import load_dotenv
 3from crewai import Agent, Task, Crew, Process
 4from crewai_tools import SerperDevTool, ScrapeWebsiteTool
 5
 6load_dotenv()
 7os.environ["OPENAI_MODEL_NAME"] = "gpt-4o"
 8
 9# ── Tools ────────────────────────────────────────
10search_tool = SerperDevTool()
11scrape_tool = ScrapeWebsiteTool()
12
13# ── Agents ───────────────────────────────────────
14researcher = Agent(
15 role="시니어 리서처",
16 goal="주어진 주제에 대해 웹에서 최신 정보를 수집하고 핵심 인사이트를 정리한다",
17 backstory="다양한 기술 문서와 블로그를 분석하여 최고의 리서치 결과를 만드는 전문가",
18 tools=[search_tool, scrape_tool],
19 allow_delegation=False,
20 verbose=True,
21)
22
23editor = Agent(
24 role="IT 블로거 / 에디터",
25 goal="리서치 결과를 바탕으로 읽기 쉽고 실용적인 블로그 글을 작성한다",
26 backstory="개발자 독자를 위해 명확하고 유익한 기술 콘텐츠를 작성하는 전문 블로거",
27 verbose=True,
28)
29
30# ── Tasks ────────────────────────────────────────
31research_task = Task(
32 description="""'{topic}'에 관한 최신 정보를 웹에서 검색하고 분석하세요.
33 핵심 개념, 주요 기능, 실제 활용 사례를 정리하세요.""",
34 agent=researcher,
35 expected_output="주제의 핵심 내용, 주요 기능, 활용 사례를 포함한 리서치 보고서",
36)
37
38writing_task = Task(
39 description="""리서치 결과를 바탕으로 '{topic}'에 대한 블로그 포스트를 작성하세요.
40 도입부, 주요 3개 섹션, 실용적 예시, 결론으로 구성하세요.""",
41 agent=editor,
42 expected_output="마크다운 형식의 블로그 포스트 (도입부, 3개 섹션, 결론 포함)",
43 context=[research_task], # 리서치 결과를 컨텍스트로 전달
44 output_file="output_blog.md",
45)
46
47# ── Crew ─────────────────────────────────────────
48crew = Crew(
49 agents=[researcher, editor],
50 tasks=[research_task, writing_task],
51 process=Process.sequential,
52 verbose=True,
53)
54
55result = crew.kickoff(inputs={"topic": "CrewAI 멀티 에이전트 프레임워크"})
56print(result.raw)

⚙️ 프로세스 유형 #

Sequential (순차 처리) #

작업 목록 순서대로 실행하며, 앞 Task의 출력이 다음 Task의 컨텍스트가 됩니다. 가장 단순하고 예측 가능한 흐름입니다.

1crew = Crew(
2 agents=[researcher, editor, reviewer],
3 tasks=[research_task, writing_task, review_task],
4 process=Process.sequential,
5)

1research_task → writing_task → review_task
2 (출력) → (컨텍스트) → (컨텍스트)

Hierarchical (계층 처리) #

매니저 Agent가 자동 생성되어 작업을 하위 Agent에게 위임하고 결과를 검수합니다. 복잡하고 동적인 워크플로에 적합합니다.

1from langchain_openai import ChatOpenAI
2
3crew = Crew(
4 agents=[researcher, editor, reviewer],
5 tasks=[complex_task],
6 process=Process.hierarchical,
7 manager_llm=ChatOpenAI(model="gpt-4o"), # 매니저 LLM 지정
8)

1Manager Agent (자동 생성)
2 ├── researcher 에게 조사 위임
3 ├── editor 에게 작성 위임
4 └── 결과 검수 후 최종 승인

🧠 메모리 시스템 #

CrewAI v1.10+ 에서는 통합 메모리 시스템을 제공합니다. Agent가 이전 실행 맥락을 기억하고 중복 작업을 줄일 수 있습니다.

메모리 유형	범위	설명
Short-term	현재 Crew 실행 내	대화 중 컨텍스트 유지
Long-term	실행 간 영속	벡터 스토어에 저장, 재실행 시 활용
Entity	현재 실행 내	언급된 인물·조직·개념 추적

 1researcher = Agent(
 2 role="리서처",
 3 goal="정보 수집",
 4 backstory="...",
 5 memory=True, # 메모리 활성화
 6)
 7
 8crew = Crew(
 9 agents=[researcher],
10 tasks=[task],
11 memory=True, # Crew 레벨 메모리 활성화
12)

🔧 커스텀 Tool 구현 #

@tool 데코레이터로 Python 함수를 Agent가 사용할 수 있는 도구로 등록합니다.

 1from crewai.tools import tool
 2
 3@tool('naver_news_search')
 4def search_naver_news(query: str) -> str:
 5 """네이버 뉴스 API에서 최신 기사 URL을 검색합니다."""
 6 import requests
 7 # 실제 API 호출 구현
 8 response = requests.get(
 9 "https://openapi.naver.com/v1/search/news.json",
10 params={"query": query, "display": 5},
11 headers={
12 "X-Naver-Client-Id": os.getenv("NAVER_CLIENT_ID"),
13 "X-Naver-Client-Secret": os.getenv("NAVER_CLIENT_SECRET"),
14 }
15 )
16 items = response.json().get("items", [])
17 return "\n".join(item["link"] for item in items)

Tip: docstring이 Tool의 설명으로 사용됩니다. Agent가 언제 이 Tool을 써야 하는지 명확히 작성하면 호출 정확도가 높아집니다.

📋 YAML 설정 방식 (대규모 프로젝트 권장) #

Agent와 Task 정의를 YAML 파일로 분리하면 코드와 설정을 분리하여 관리하기 쉽습니다.

config/agents.yaml:

1researcher:
2 role: 시니어 리서처
3 goal: 주어진 주제의 최신 정보를 수집하고 핵심 인사이트를 정리한다
4 backstory: 다양한 기술 문서를 분석하여 최고의 리서치 결과를 만드는 전문가
5
6editor:
7 role: IT 블로거 에디터
8 goal: 리서치 결과를 읽기 쉬운 블로그 글로 작성한다
9 backstory: 개발자 독자를 위해 명확한 기술 콘텐츠를 작성하는 전문 블로거

config/tasks.yaml:

 1research_task:
 2 description: "{topic}"에 관한 최신 정보를 수집하고 핵심 내용을 정리하세요.
 3 expected_output: 핵심 개념, 주요 기능, 활용 사례를 포함한 리서치 보고서
 4 agent: researcher
 5
 6writing_task:
 7 description: 리서치 결과를 바탕으로 "{topic}" 블로그 포스트를 작성하세요.
 8 expected_output: 마크다운 블로그 포스트
 9 agent: editor
10 context:
11 - research_task

crew.py:

 1from crewai import Agent, Task, Crew, Process
 2from crewai.project import CrewBase, agent, task, crew
 3
 4@CrewBase
 5class BlogCrew:
 6 agents_config = 'config/agents.yaml'
 7 tasks_config = 'config/tasks.yaml'
 8
 9 @agent
10 def researcher(self) -> Agent:
11 return Agent(config=self.agents_config['researcher'], tools=[search_tool])
12
13 @agent
14 def editor(self) -> Agent:
15 return Agent(config=self.agents_config['editor'])
16
17 @task
18 def research_task(self) -> Task:
19 return Task(config=self.tasks_config['research_task'])
20
21 @task
22 def writing_task(self) -> Task:
23 return Task(config=self.tasks_config['writing_task'])
24
25 @crew
26 def crew(self) -> Crew:
27 return Crew(
28 agents=self.agents,
29 tasks=self.tasks,
30 process=Process.sequential,
31 )

🏗️ 실전 예제: 뉴스 리서치 멀티 에이전트 #

검색 → 내용 추출 → 요약 응답을 3개 Agent가 분담하는 파이프라인입니다.

 1from crewai import Agent, Task, Crew, Process
 2from crewai.tools import tool
 3
 4@tool('fetch_article')
 5def fetch_article(url: str) -> str:
 6 """주어진 URL의 기사 본문을 추출합니다."""
 7 from newspaper import Article
 8 article = Article(url)
 9 article.download()
10 article.parse()
11 return article.text
12
13# Agents
14searcher = Agent(
15 role="뉴스 검색 전문가",
16 goal="사용자 질문에 맞는 최신 뉴스 URL을 수집한다",
17 backstory="다양한 뉴스 소스에서 정확한 기사를 찾는 리서치 전문가",
18 tools=[search_tool],
19)
20
21analyzer = Agent(
22 role="콘텐츠 분석가",
23 goal="기사 URL에서 본문을 추출하고 핵심 내용을 분석한다",
24 backstory="복잡한 기사를 빠르게 파악하고 핵심을 추출하는 분석가",
25 tools=[fetch_article],
26)
27
28answerman = Agent(
29 role="최종 응답 작성자",
30 goal="분석된 정보를 바탕으로 사용자에게 명확한 답변을 제공한다",
31 backstory="복잡한 정보를 쉽고 정확하게 전달하는 커뮤니케이션 전문가",
32)
33
34# Tasks
35search_task = Task(
36 description="'{query}'에 관한 최신 뉴스 기사 URL 5개를 수집하세요.",
37 agent=searcher,
38 expected_output="관련 뉴스 기사 URL 목록 (최소 5개)",
39)
40
41analysis_task = Task(
42 description="수집된 URL에서 기사 본문을 추출하고 핵심 내용을 정리하세요.",
43 agent=analyzer,
44 expected_output="각 기사의 핵심 내용 요약",
45 context=[search_task],
46)
47
48answer_task = Task(
49 description="분석 결과를 바탕으로 '{query}'에 대한 종합 답변을 작성하세요.",
50 agent=answerman,
51 expected_output="출처와 근거를 포함한 명확한 답변",
52 context=[analysis_task],
53)
54
55# Crew 실행
56crew = Crew(
57 agents=[searcher, analyzer, answerman],
58 tasks=[search_task, analysis_task, answer_task],
59 process=Process.sequential,
60)
61
62result = crew.kickoff(inputs={"query": "2026년 AI Agent 트렌드"})
63print(result.raw)

❓ 자주 묻는 질문 #

Q. CrewAI와 LangChain의 차이는? #

LangChain은 LLM 체이닝과 도구 통합을 위한 범용 라이브러리입니다. CrewAI는 멀티 에이전트 협업 오케스트레이션에 특화되어 있으며, LangChain 위에서 동작할 수 있습니다.

Q. OpenAI 외에 다른 LLM을 사용할 수 있나요? #

네, llm 파라미터로 Anthropic Claude, Google Gemini, Ollama(로컬 LLM) 등을 지정할 수 있습니다.

1from langchain_anthropic import ChatAnthropic
2
3agent = Agent(
4 role="분석가",
5 goal="...",
6 backstory="...",
7 llm=ChatAnthropic(model="claude-sonnet-4-6"),
8)

Q. Sequential과 Hierarchical 중 어떤 걸 써야 하나요? #

단계별 흐름이 명확하고 예측 가능하면 Sequential, 작업의 복잡도가 높고 동적 위임이 필요하면 Hierarchical을 선택하세요.

📚 참고 #

[Kubernetes] Containerd 기반 쿠버네티스 고가용성(HA) 클러스터 완벽 구축 가이드

Wed, 06 Aug 2025 00:00:00 +0000

1. 🏗️ 클러스터 아키텍처 및 환경 #

고가용성 클러스터는 마스터 노드(Control Plane)를 여러 대 두어, 특정 노드에 장애가 발생해도 서비스가 중단되지 않도록 설계합니다.

Container Runtime: Containerd (Docker 대체 표준)
Load Balancer: HAProxy + Keepalived (Virtual IP 사용)
Nodes: Master 3대, Worker N대 권장

2. ⚙️ 사전 준비 (모든 노드 공통) #

가장 먼저 모든 노드에서 쿠버네티스가 구동될 수 있는 기초 공사를 진행합니다.

2.1 Swap 비활성화 및 네트워크 설정 #

쿠버네티스는 메모리 관리를 위해 Swap 비활성화가 필수입니다. 🛑

 1# 1. Swap 끄기
 2sudo swapoff -a
 3sudo sed -i '/swap/s/^/#/' /etc/fstab
 4
 5# 2. 커널 모듈 로드 (Containerd 필수 모듈)
 6cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
 7overlay
 8br_netfilter
 9EOF
10
11sudo modprobe overlay
12sudo modprobe br_netfilter
13
14# 3. sysctl 파라미터 설정 (IP 포워딩 활성화)
15cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
16net.bridge.bridge-nf-call-iptables = 1
17net.bridge.bridge-nf-call-ip6tables = 1
18net.ipv4.ip_forward = 1
19EOF
20
21sudo sysctl --system

3. 📦 Containerd 설치 및 최적화 #

도커 없이 가볍고 빠른 Containerd를 직접 설치합니다.

1sudo apt-get update && sudo apt-get install -y containerd
2
3# 기본 설정 생성 및 SystemdCgroup 활성화 (중요!)
4sudo mkdir -p /etc/containerd
5containerd config default | sudo tee /etc/containerd/config.toml
6sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml
7
8sudo systemctl restart containerd

4. ⚖️ Load Balancer 구성 (LB 노드) #

마스터 노드들을 하나로 묶어줄 대표 주소인 **VIP(Virtual IP)**를 설정합니다. (예: 192.168.0.100)

HAProxy 설정 예시 (/etc/haproxy/haproxy.cfg):

frontend k8s-api
 bind *:6443
 mode tcp
 default_backend k8s-api-nodes

backend k8s-api-nodes
 mode tcp
 balance roundrobin
 server master1 192.168.0.11:6443 check
 server master2 192.168.0.12:6443 check
 server master3 192.168.0.13:6443 check

5. 🚩 클러스터 초기화 (Master 1) #

⚠️ [필독] VIP 설정을 빠뜨리면 안 되는 이유! #

kubeadm init 실행 시 --control-plane-endpoint 옵션을 빠뜨리는(빼는) 실수를 가장 많이 합니다.

만약 빠뜨린다면? 😱 클러스터가 로드밸런서가 아닌 **‘첫 번째 마스터의 IP’**를 대표 주소로 기억합니다. 나중에 마스터를 추가해도, 첫 번째 노드가 죽으면 클러스터 전체가 먹통이 되어 HA 구성의 의미가 사라집니다.

1# 로드밸런서 VIP를 엔드포인트로 지정하여 시작!
2sudo kubeadm init \
3 --control-plane-endpoint "192.168.0.100:6443" \
4 --upload-certs \
5 --pod-network-cidr=10.244.0.0/16 \
6 --cri-socket unix:///run/containerd/containerd.sock

6. 🤝 노드 조인 (Join) #

초기화 완료 후 출력되는 토큰을 사용하여 나머지 노드들을 연결합니다.

6.1 추가 마스터 노드 (Master 2, 3) 조인 #

1sudo kubeadm join 192.168.0.100:6443 --token <TOKEN> \
2 --discovery-token-ca-cert-hash sha256:<HASH> \
3 --control-plane --certificate-key <KEY>

6.2 워커 노드 (Worker) 조인 #

1sudo kubeadm join 192.168.0.100:6443 --token <TOKEN> \
2 --discovery-token-ca-cert-hash sha256:<HASH>

7. ✅ 설치 확인 및 마무리 #

모든 노드가 정상적으로 연결되었는지 확인해 볼까요?

1kubectl get nodes

STATUS가 모두 Ready라면 축하드립니다! 🎉 이제 어떤 마스터 노드 하나가 장애가 나더라도 끄떡없는 견고한 쿠버네티스 클러스터가 완성되었습니다.

💡 요약하자면: #

Swap 오프는 기본!
Containerd 설정 시 SystemdCgroup을 꼭 true로!
kubeadm init 시 LB VIP를 절대 빠뜨리지 말 것!

[Kubernetes] eBPF + Cilium로 클러스터 심층 모니터링

Wed, 02 Jul 2025 00:00:00 +0000

🔍 eBPF + Cilium: 개발자 관점에서 보는 심층 모니터링 #

쿠버네티스에서 애플리케이션 + 클러스터 호스트 수준 Observability를 확보하려면
OTel과 eBPF를 활용하는 것이 효과적입니다.
특히 eBPF 기반 네트워크 모니터링 도구인 Cilium을 활용하면 실전 환경에서 강력한 가시성을 제공합니다.

1️⃣ eBPF란? #

eBPF = extended Berkeley Packet Filter
리눅스 커널 내부에서 안전하게 코드 실행 가능
주요 활용:
- 커널 이벤트 트레이싱
- 네트워크 패킷 분석
- 성능 분석
- 보안 이벤트 감지
요약: 커널 레벨에서 실시간 데이터를 수집하고 분석하는 기술

2️⃣ Cilium이란? #

Cilium은 eBPF 기반 Kubernetes 네트워크 및 보안 솔루션
기능:
- Pod-to-Pod, Pod-to-Service 트래픽 관찰
- 네트워크 정책(enforcement) 적용
- L7 로깅, 트레이싱
- eBPF를 활용한 고성능 패킷 필터링과 모니터링
개발자 관점 핵심:
- 네트워크 수준 Observability와 보안을 동시에 제공
- OTel과 함께 사용하면 애플리케이션 + 네트워크 + 커널 이벤트 통합 가능

3️⃣ OTel과 eBPF (Cilium) 통합 아키텍처 #

Application / Container → OTel SDK → OTel Collector → Backend (Loki/Prometheus/Tempo)
Host Kernel → eBPF Agent (Cilium) → OTel Collector → Backend

OTel Collector가 애플리케이션 로그/트레이스와 eBPF 이벤트 모두 수집
Loki, Prometheus, Tempo 등 백엔드로 통합 전송
시각화/알람/분석을 한 곳에서 관리 가능

4️⃣ 개발자 관점 통합 전략 #

Cilium 설치
- DaemonSet 형태로 클러스터 전체 배포
- eBPF로 Pod-to-Pod 트래픽 관찰, L7 로깅 가능
OTel Collector 연계
- Collector OTLP Receiver로 Cilium에서 수집한 이벤트 전송
백엔드 설정
- Loki → 로그/이벤트 시각화
- Prometheus → 메트릭 수집
- Tempo/Jaeger → 트레이스 시각화
운영 체크
- Liveness/Readiness Probe
- eBPF 오버헤드 모니터링
- Cilium Hubble UI/CLI 확인

5️⃣ 실전 예시 (DaemonSet + Collector 연계) #

 1apiVersion: apps/v1
 2kind: DaemonSet
 3metadata:
 4 name: cilium
 5 namespace: kube-system
 6spec:
 7 selector:
 8 matchLabels:
 9 k8s-app: cilium
10 template:
11 metadata:
12 labels:
13 k8s-app: cilium
14 spec:
15 serviceAccountName: cilium
16 containers:
17 - name: cilium
18 image: cilium/cilium:v1.16
19 securityContext:
20 privileged: true
21 env:
22 - name: OTEL_COLLECTOR_ENDPOINT
23 value: "http://otel-collector.observability.svc.cluster.local:4317"

Cilium(eBPF Agent) → OTLP로 Collector 전송
Collector에서 앱 로그와 함께 백엔드 전송

6️⃣ 개발자 관점 팁 #

데이터 수집 레이어 명확화: 앱 로그 vs 네트워크/커널 이벤트
오버헤드 주의: eBPF 스크립트 과도하게 사용 시 CPU 증가
보안: eBPF Agent(Cilium)는 Host 권한 필요 → RBAC 최소화
통합 시각화: Loki/Prometheus/Tempo에서 모든 이벤트 연계 확인
Hubble 활용: Cilium의 시각화/CLI 도구로 네트워크 트래픽 추적

7️⃣ 요약 #

항목	내용
목적	앱 + 네트워크 + 호스트 통합 Observability
핵심 기술	OTel Collector, eBPF Agent (Cilium)
배포	OTel Collector (Deployment/DaemonSet), Cilium (DaemonSet)
장점	전체 클러스터 가시성, 실시간 모니터링, 트레이스/로그/메트릭 통합, 네트워크 보안 관측
운영 포인트	Liveness/Readiness, eBPF 오버헤드 관리, RBAC 최소화, 백엔드 연결 확인, Hubble 활용

💡 한 줄 기억:

OTel + Cilium = “앱·네트워크·커널 통합 Observability + 보안까지 확보하는 실전 도구”

[Kubernetes] Kubestr: 스토리지 성능과 상태 점검 도구

Thu, 05 Jun 2025 00:00:00 +0000

📦 Kubestr란? #

Kubestr는 쿠버네티스 클러스터에서 스토리지(Storage) 리소스의 성능과 상태를 점검하는 도구입니다.
Persistent Volume, StorageClass, PVC 등을 대상으로 벤치마크와 분석을 수행할 수 있습니다.

1️⃣ 주요 기능 #

스토리지 클래스 분석
- StorageClass, PVC, PV 구조 및 매칭 상태 확인
- 권장 구성 준수 여부 점검
성능 벤치마크
- IOPS, Throughput, Latency 측정
- 다양한 볼륨 타입(NFS, CSI, Local PV 등) 비교
보고서 제공
- CLI, YAML, JSON 형식 제공
- 성능 병목이나 문제점을 쉽게 확인 가능
쿠버네티스 친화적
- Helm chart 또는 kubectl로 배포 가능
- Pod 기반 벤치마크 → 클러스터 안전하게 실행

2️⃣ 설치 및 실행 예시 #

1# Helm으로 설치
2helm repo add kubestr https://kubestr.io/helm-charts
3helm install kubestr kubestr/kubestr
4
5# 스토리지 성능 벤치마크
6kubestr storageclass ls # 클러스터의 StorageClass 목록 확인
7kubestr benchmark sc my-sc # 특정 StorageClass 벤치마크

3️⃣ 사용 목적 #

스토리지 성능 비교 및 최적화
클러스터 스토리지 상태 점검
Persistent Volume 병목 또는 구성 문제 사전 탐지
DevOps/Platform 팀에서 클러스터 안정성 확보

4️⃣ 요약 #

항목	내용
이름	Kubestr
역할	쿠버네티스 클러스터 스토리지 점검 & 성능 벤치마크
대상	StorageClass, PersistentVolume, PVC 등
장점	클러스터 친화적, IOPS/Throughput/Latency 측정, 보고서 제공

💡 한 줄 기억:

Kubestr = 쿠버네티스 스토리지의 건강검진 + 성능 테스트 도구

[Kubernetes] Velero: 클러스터 백업, 복구, 마이그레이션 도구

Mon, 02 Jun 2025 00:00:00 +0000

🛡️ Velero란? #

Velero는 쿠버네티스 클러스터의 리소스와 데이터를 백업/복원하고, 클러스터 간 마이그레이션을 지원하는 도구입니다.
재해 복구(Disaster Recovery)와 테스트/스테이징 환경 관리에 유용합니다.

1️⃣ 주요 기능 #

백업 (Backup)
- 전체 클러스터 또는 특정 네임스페이스 단위 백업
- 리소스 + Persistent Volume 데이터 포함 가능
복원 (Restore)
- 특정 시점으로 클러스터 또는 네임스페이스 복원
- 선택적 리소스 복원 가능
마이그레이션 (Migration)
- 클러스터 간 애플리케이션 이전
- 테스트/스테이징 환경 배포 용이
클라우드 스토리지 연동
- AWS S3, GCP GCS, Azure Blob 등 외부 오브젝트 스토리지 활용

2️⃣ 설치 및 사용 예시 #

 1# Velero CLI 설치 (Mac 예시)
 2brew install velero
 3
 4# 클러스터에 Velero 설치
 5velero install \
 6 --provider aws \
 7 --bucket my-backup-bucket \
 8 --secret-file ./credentials-velero
 9
10# 백업 생성
11velero backup create my-backup --include-namespaces default
12
13# 백업 목록 확인
14velero backup get
15
16# 백업 복원
17velero restore create --from-backup my-backup

3️⃣ 사용 목적 #

쿠버네티스 클러스터 재해 복구 준비
선택적 Namespace/리소스 백업 및 복원
클러스터 간 데이터 및 리소스 마이그레이션
테스트 환경/스테이징 환경 구성 자동화

4️⃣ 요약 #

항목	내용
이름	Velero
역할	Kubernetes 리소스 & 데이터 백업, 복구, 마이그레이션
대상	Namespace, PV, CRD 등
장점	클라우드 연동, 선택적 백업, 재해 복구/마이그레이션 용이

💡 한 줄 기억:

Velero = 쿠버네티스 클러스터용 “백업 + 복구 + 마이그레이션 매니저”

[Kubernetes] Steady Load on Kubernetes Node Using Stress

Mon, 19 May 2025 00:00:00 +0000

stress 설치 #

1RUN apt-get update && apt-get install -y stress bc

ConfigMap 설정 #

 1apiVersion: v1
 2kind: ConfigMap
 3metadata:
 4 name: stress-script
 5 namespace: chip-analyzer
 6data:
 7 stress-control.sh: |
 8 #!/bin/bash
 9
10 TARGET_CPU_USAGE=$TARGET_CPU
11 echo "TARGET_CPU_USAGE = $TARGET_CPU_USAGE"
12
13 TARGET_MEMORY_USAGE=$TARGET_MEM
14 echo "TARGET_MEMORY_USAGE = $TARGET_MEMORY_USAGE"
15
16 TIMEOUT=$TIMEOUT
17 echo "TIMEOUT = $TIMEOUT"
18
19 while true; do
20 echo "##### CPU Check #####"
21 TOTAL_CORES=$(nproc)
22 echo "TOTAL_CORES = $TOTAL_CORES"
23
24 CURRENT_IDLE=$(top -bn1 | grep "Cpu(s)" | sed "s/.*, *\([0-9.]*\)%* id.*/\1/" | awk '{print $1}')
25 echo "CURRENT_IDLE = $CURRENT_IDLE"
26
27 CURRENT_CPU_USAGE=$(echo "100 - $CURRENT_IDLE" | bc -l)
28 echo "CURRENT_CPU_USAGE = $CURRENT_CPU_USAGE"
29
30 NEEDED_CPU_USAGE=$(echo "$TARGET_CPU_USAGE - $CURRENT_CPU_USAGE" | bc -l)
31 echo "NEEDED_CPU_USAGE = $NEEDED_CPU_USAGE"
32
33 TARGET_CPU_CORES=$(echo "$NEEDED_CPU_USAGE * $TOTAL_CORES / 100" | bc -l)
34 echo "TARGET_CPU_CORES = $TARGET_CPU_CORES"
35
36 TARGET_CPU_CORES_ROUNDED=$(echo "($TARGET_CPU_CORES+0.5)/1" | bc)
37 echo "TARGET_CPU_CORES_ROUNDED = $TARGET_CPU_CORES_ROUNDED"
38
39
40 echo "##### Memory Check #####"
41 TOTAL_MEMORY=$(grep MemTotal /proc/meminfo | awk '{print $2}')
42 echo "TOTAL_MEMORY = $TOTAL_MEMORY"
43
44 FREE_MEMORY=$(grep MemFree /proc/meminfo | awk '{print $2}')
45 echo "FREE_MEMORY = $FREE_MEMORY"
46
47 BUFFERS=$(grep Buffers /proc/meminfo | awk '{print $2}')
48 echo "BUFFERS = $BUFFERS"
49
50 CACHED=$(grep "^Cached" /proc/meminfo | awk '{print $2}')
51 echo "CACHED = $CACHED"
52
53 USED_MEMORY=$((TOTAL_MEMORY - FREE_MEMORY - BUFFERS - CACHED))
54 echo "USED_MEMORY = $USED_MEMORY"
55
56 TARGET_MEMORY=$(echo "$TOTAL_MEMORY * $TARGET_MEMORY_USAGE / 100" | bc)
57 echo "TARGET_MEMORY = $TARGET_MEMORY"
58
59 NEEDED_MEMORY=$((TARGET_MEMORY - USED_MEMORY))
60 echo "NEEDED_MEMORY = $NEEDED_MEMORY"
61
62 # MB로 계산하고 싶을 때(반올림 추가)
63 NEEDED_MEMORY_ROUNDED=$(echo "($NEEDED_MEMORY + 1023) / 1024" | bc)
64 echo "NEEDED_MEMORY_ROUNDED = $NEEDED_MEMORY_ROUNDED"
65
66 if (( $(echo "$TARGET_CPU_CORES_ROUNDED > 0" | bc -l) )) && (( NEEDED_MEMORY > 1023 )); then
67 echo "Adding Stress CPU: $TARGET_CPU_CORES_ROUNDED / Memory: $NEEDED_MEMORY KB."
68 stress --cpu $TARGET_CPU_CORES_ROUNDED --vm 1 --vm-bytes ${NEEDED_MEMORY}k --vm-hang 0 --verbose --timeout ${TIMEOUT}s
69 elif (( $(echo "$TARGET_CPU_CORES_ROUNDED > 0" | bc -l) )) && (( NEEDED_MEMORY <= 1023 )); then
70 echo "Adding Stress CPU: $TARGET_CPU_CORES_ROUNDED."
71 stress --cpu $TARGET_CPU_CORES_ROUNDED --vm-hang 0 --verbose --timeout ${TIMEOUT}s
72 elif (( $(echo "$TARGET_CPU_CORES_ROUNDED <= 0" | bc -l) )) && (( NEEDED_MEMORY > 1023 )); then
73 echo "Adding Stress Memory: $NEEDED_MEMORY KB."
74 stress --vm 1 --vm-bytes ${NEEDED_MEMORY}k --vm-hang 0 --verbose --timeout ${TIMEOUT}s
75 else
76 echo "No Stress Needed."
77 fi
78
79 wait
80
81 sleep 1
82
83 done

DaemonSet 설정 #

 1apiVersion: apps/v1
 2kind: DaemonSet
 3metadata:
 4 labels:
 5 app: chip-analyzer-master
 6 name: chip-analyzer-master
 7 namespace: chip-analyzer
 8spec:
 9 updateStrategy:
10 type: RollingUpdate
11 rollingUpdate:
12 maxUnavailable: 5
13 maxSurge: 0
14 selector:
15 matchLabels:
16 app: chip-analyzer-master
17 template:
18 metadata:
19 labels:
20 app: chip-analyzer-master
21 spec:
22 affinity:
23 nodeAffinity:
24 requiredDuringSchedulingIgnoredDuringExecution:
25 nodeSelectorTerms:
26 - matchExpressions:
27 - key: node-role.kubernetes.io/control-plane
28 operator: Exists
29 tolerations:
30 - key: node-role.kubernetes.io/control-plane
31 operator: Exists
32 effect: NoSchedule
33 - key: node-role.kubernetes.io/master
34 operator: Exists
35 effect: NoSchedule
36 containers:
37 - env:
38 - name: TARGET_CPU
39 value: '50'
40 - name: TARGET_MEM
41 value: '50'
42 - name: TIMEOUT
43 value: '300'
44 image: stress:v1.0
45 command: ["/bin/bash", "/scripts/stress-control.sh"]
46 volumeMounts:
47 - name: script-volume
48 mountPath: /scripts
49 imagePullPolicy: Always
50 name: chip-analyzer-master
51 restartPolicy: Always
52 volumes:
53 - name: script-volume
54 configMap:
55 name: stress-script
56 defaultMode: 0775

[Linux] Stress

Sat, 17 May 2025 00:00:00 +0000

stress 설치 #

stress는 다양한 스트레스 테스트를 지원하는 도구

1apt install -y stress

stress 옵션 #

 1Usage: stress [OPTION [ARG]] ...
 2 -?, --help show this help statement
 3 --version show version statement
 4 -v, --verbose be verbose
 5 -q, --quiet be quiet
 6 -n, --dry-run show what would have been done
 7 -t, --timeout N timeout after N seconds
 8 --backoff N wait factor of N microseconds before work starts
 9 -c, --cpu N spawn N workers spinning on sqrt()
10 -i, --io N spawn N workers spinning on sync()
11 -m, --vm N spawn N workers spinning on malloc()/free()
12 --vm-bytes B malloc B bytes per vm worker (default is 256MB)
13 --vm-stride B touch a byte every B bytes (default is 4096)
14 --vm-hang N sleep N secs before free (default none, 0 is inf)
15 --vm-keep redirty memory instead of freeing and reallocating
16 -d, --hdd N spawn N workers spinning on write()/unlink()
17 --hdd-bytes B write B bytes per hdd worker (default is 1GB)

Example #

1stress --cpu 8 --io 4 --vm 2 --vm-bytes 128M --timeout 10s

CPU 부하 #

1stress -c <Core 수>

Memory 부하 #

사용할 크기의 단위 : b(byte) ,k(killo byte) , m(mega byte) , g(giga byte)

1stress –vm <프로세스 수> –vm-bytes <사용할 크기>
2ex)stress -vm 2 –vm-bytes 2048m

HDD write 부하 #

1stress –hdd <write에 사용할 worker 수> –hdd-bytes <사용할 크기>
2ex) stress –hdd 3 -hdd-bytes 1024m

I/O 부하 #

1stress -i <sync를 사용하여 i/o 부하를 발생 시킬 worker의수>

[Kubernetes] Steady Load on Kubernetes Node Using Stress-ng

Mon, 12 May 2025 00:00:00 +0000

stress-ng 설치 #

stress-ng는 다양한 스트레스 테스트를 지원하는 도구

1apt install -y stress-ng

[Linux] Stress-ng

Sat, 10 May 2025 00:00:00 +0000

stress-ng 설치 #

stress-ng는 다양한 스트레스 테스트를 지원하는 도구

1apt install -y stress-ng

CPU 스트레스 테스트 실행 #

설치 후, 아래 명령어를 사용해 CPU 스트레스 테스트를 실행할 수 있다.

1stress-ng --cpu 1 --cpu-load 70 --timeout 10m --metrics --times --verify

--cpu 1: CPU 코어 1개를 사용해 스트레스 테스트를 수행
--cpu-load 70: CPU 사용률을 70%로 설정
--timeout 10m: 테스트를 10분 동안 실행
--metrics: 테스트 결과에 대한 성능 메트릭스를 표시
--times: 테스트 완료 후 실행 시간과 관련된 통계를 출력
--verify: 테스트 중 계산 결과가 정확한지 확인

실행 결과 예시 #

테스트를 실행하면 다음과 비슷한 결과를 볼 수 있다.

1stress-ng: info: [1234] Setting up 1 CPU worker(s) to run 70% load
2stress-ng: info: [1234] Successful run completed in 600.00s (10 mins)
3stress-ng: info: [1234] Metrics: bogo-ops: 1000000, real-time: 600.00s, user-time: 420.00s, system-time: 0.05s
4stress-ng: info: [1234] Verification passed: 100.0% correct

테스트 후 모니터링 #

다음 명령어를 사용해 CPU 사용량을 확인할 수 있다

▼ top 명령어:CPU, 메모리 사용률을 실시간으로 확인

1top

▼ htop (더 보기 편리한 대안):CPU 사용량과 프로세스를 시각적으로 확인

1htop

테스트 종료 #

테스트가 완료되면 자동으로 종료되지만, 수동으로 종료하려면 다음 명령을 사용할 수 있다.
pkill stress-ng: 실행 중인 stress-ng 프로세스를 종료합니다.

1pkill stress-ng

[Kubernetes] Upgrade Kubernetes(v1.32.x) using Kubekey(v3.1.9) Artifact

Fri, 02 May 2025 00:00:00 +0000

offline 설치 위한 artifact 참고

version 참고
- kubernetes와 관련된 image는 https://github.com/kubesphere/ks-installer/releases에서 주요 release에만 포함되는 image-list.txt파일을 참고
- kubekey의 버전별로 kubernetes, kubesphere의 최신 지원 버전이 있음
  - kubekey/version/components.json
  - kubekey/cmd/kk/pkg/version/kubesphere/version_enum.go
  - kubekey/cmd/kk/pkg/version/kubernetes/version_enum.go
- default 버전에 대한 설정은 kubekey/cmd/kk/apis/kubekey/v1alpha2/default.go 파일에 있다
https://github.com/kubesphere/kubekey/blob/v3.1.9/docs/manifest_and_artifact.md
https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/images-list.txt
https://kubesphere.io/docs/v3.4/installing-on-linux/introduction/air-gapped-installation
https://github.com/kubesphere/kubekey/blob/v3.1.9/docs/manifest-example.md {: .prompt-info }

script 다운로드 #

1curl -sfL https://get-kk.kubesphere.io | VERSION=v3.1.9 sh -

ubuntu-20.04-debs-amd64.iso 다운로드 #

1wget https://github.com/kubesphere/kubekey/releases/download/v3.1.9/ubuntu-20.04-debs-amd64.iso

artifact-3.1.9.yaml 작성 #

 1apiVersion: kubekey.kubesphere.io/v1alpha2
 2kind: Manifest
 3metadata:
 4 name: artifact-v3.1.9
 5spec:
 6 arches:
 7 - amd64
 8 operatingSystems:
 9 - arch: amd64
10 type: linux
11 id: ubuntu
12 version: "20.04"
13 osImage: Ubuntu 20.04.4 LTS
14 repository:
15 iso:
16 localPath: "/home/ubuntu/kk_install/ubuntu-20.04-debs-amd64.iso"
17 # url: "https://github.com/kubesphere/kubekey/releases/download/v3.1.1/ubuntu-20.04-debs-amd64.iso"
18 kubernetesDistributions:
19 - type: kubernetes
20 version: v1.32.4
21 components:
22 helm:
23 version: v3.14.3
24 cni:
25 version: v1.2.0
26 etcd:
27 version: v3.5.13
28 calicoctl:
29 version: v3.27.4
30 containerRuntimes:
31 - type: containerd
32 version: 1.7.13
33 crictl:
34 version: v1.29.0
35 harbor:
36 version: v2.10.1
37 docker-compose:
38 version: v2.26.1
39 images:
40 - docker.io/kubesphere/kube-apiserver:v1.30.12
41 - docker.io/kubesphere/kube-apiserver:v1.31.8
42 - docker.io/kubesphere/kube-apiserver:v1.32.4
43 - docker.io/kubesphere/kube-controller-manager:v1.30.12
44 - docker.io/kubesphere/kube-controller-manager:v1.31.8
45 - docker.io/kubesphere/kube-controller-manager:v1.32.4
46 - docker.io/kubesphere/kube-scheduler:v1.30.12
47 - docker.io/kubesphere/kube-scheduler:v1.31.8
48 - docker.io/kubesphere/kube-scheduler:v1.32.4
49 - docker.io/kubesphere/kube-proxy:v1.30.12
50 - docker.io/kubesphere/kube-proxy:v1.31.8
51 - docker.io/kubesphere/kube-proxy:v1.32.4
52 - docker.io/kubesphere/pause:3.9
53 - docker.io/coredns/coredns:1.9.3
54 - docker.io/calico/cni:v3.23.2
55 - docker.io/calico/cni:v3.27.3
56 - docker.io/calico/kube-controllers:v3.23.2
57 - docker.io/calico/kube-controllers:v3.27.4
58 - docker.io/calico/node:v3.23.2
59 - docker.io/calico/node:v3.27.4
60 - docker.io/calico/pod2daemon-flexvol:v3.23.2
61 - docker.io/calico/pod2daemon-flexvol:v3.27.4
62 - docker.io/calico/typha:v3.23.2
63 - docker.io/calico/typha:v3.27.4
64 - docker.io/kubesphere/flannel:v0.12.0
65 - docker.io/openebs/provisioner-localpv:3.3.0
66 - docker.io/openebs/linux-utils:3.3.0
67 - docker.io/library/haproxy:2.3
68 - docker.io/kubesphere/nfs-subdir-external-provisioner:v4.0.2
69 - docker.io/kubesphere/k8s-dns-node-cache:1.15.12
70 registry:
71 auths:
72 "docker.io":
73 username: "username"
74 password: "password"

components version 확인(지원하는 version이 없을 시 아래와 같이 Error) #

Failed to download docker binary: curl -L -o /home/ubuntu/kk_install/kubekey/artifact/docker/20.10.8/amd64/docker-20.10.8.tgz https://download.docker.com/linux/static/stable/x86_64/docker-20.10.8.tgz error: No SHA256 found for docker. 20.10.8 is not supported.
17:40:24 KST failed: [LocalHost]
error: Pipeline[ArtifactExportPipeline] execute failed: Module[ArtifactBinariesModule] exec failed:
failed: [LocalHost] [DownloadBinaries] exec failed after 1 retries: Failed to download docker binary: curl -L -o /home/ubuntu/kk_install/kubekey/artifact/docker/20.10.8/amd64/docker-20.10.8.tgz https://download.docker.com/linux/static/stable/x86_64/docker-20.10.8.tgz error: No SHA256 found for docker. 20.10.8 is not supported.

Components 참고

https://github.com/kubesphere/kubekey/blob/v3.1.9/version/components.json {: .prompt-info }

Export Artifact #

1sudo ./kk artifact export -m artifact-3.1.9.yaml -o artifact-3.1.9.tar.gz

Cluster 업그레이드를 위한 config 파일 생성 및 작성 #

1sudo ./kk create config --with-kubesphere v3.3.2 --with-kubernetes v1.32.4 -f config-v1.32.4.yaml

1vi config-v1.32.4.yaml

 1apiVersion: kubekey.kubesphere.io/v1alpha2
 2kind: Cluster
 3metadata:
 4 name: sample
 5spec:
 6 hosts:
 7 - {name: kk-repo, address: 192.168.0.100, internalAddress: 192.168.0.100, privateKeyPath: "/home/ubuntu/.ssh/id_rsa_multipass"}
 8 - {name: kk-master, address: 192.168.0.101, internalAddress: 192.168.0.101, privateKeyPath: "/home/ubuntu/.ssh/id_rsa_multipass"}
 9 - {name: kk-worker-1, address: 192.168.0.102, internalAddress: 192.168.0.102, privateKeyPath: "/home/ubuntu/.ssh/id_rsa_multipass"}
10 - {name: kk-worker-2, address: 192.168.0.103, internalAddress: 192.168.0.103, privateKeyPath: "/home/ubuntu/.ssh/id_rsa_multipass"}
11 roleGroups:
12 etcd:
13 - kk-master
14 control-plane:
15 - kk-master
16 worker:
17 - kk-worker-1
18 - kk-worker-2
19 registry:
20 - kk-repo
21 controlPlaneEndpoint:
22 ## Internal loadbalancer for apiservers
23 # internalLoadbalancer: haproxy
24
25 domain: lb.kubesphere.local
26 # domain: 192.168.0.101
27 address: "192.168.0.101"
28 port: 6443
29 kubernetes:
30 version: v1.29.3
31 imageRepo: kubesphere
32 clusterName: cluster.local
33 masqueradeAll: false
34 maxPods: 150
35 nodeCidrMaskSize: 24
36 proxyMode: ipvs
37 autoRenewCerts: true
38 containerManager: containerd
39 featureGates:
40 RotateKubeletServerCertificate: true
41 apiserverArgs:
42 - default-not-ready-toleration-seconds=30
43 - default-unreachable-toleration-seconds=30
44 controllerManagerArgs:
45 - node-monitor-period=2s
46 - node-monitor-grace-period=16s
47 kubeletConfiguration:
48 nodeStatusUpdateFrequency: 4s
49 # etcd:
50 # type: kubekey
51 network:
52 plugin: calico
53 calico:
54 ipipMode: Always
55 vxianMode: Never
56 vethMTU: 1440
57 kubePodsCIDR: 10.233.64.0/18
58 kubeServiceCIDR: 10.233.0.0/18
59 ## multus support. https://github.com/k8snetworkplumbingwg/multus-cni
60 multusCNI:
61 enabled: false
62 registry:
63 type: harbor
64 auths:
65 "cr.harbor.kubekey.com":
66 username: admin
67 password: Harbor12345
68 privateRegistry: "cr.harbor.kubekey.com"
69 namespaceOverride: "kubesphereio"
70 registryMirrors: []
71 insecureRegistries: ["cr.harbor.kubekey.com"]
72 addons: []

Upgrade #

1sudo ./kk upgrade cluster -f config-v1.32.4.yaml -a artifact-3.1.9.tar.gz

--skip-dependency-check를 추가하면 Kubernetes 및 KubeSphere 버전 의존성 검사를 생략할 수 있다.

1sudo ./kk upgrade cluster -f config-v1.32.4.yaml -a artifact-3.1.9.tar.gz --skip-dependency-check

{: .prompt-tip }

image 별도로 push 방법

1sudo ./kk artifact image push -f config-v1.32.4.yaml -a artifact-3.1.9.tar.gz

{: .prompt-tip }

[ERROR] Harbor에 image push 할 때 Unauthorized 에러 발생 때

다시 로그인

1docker login [your.host.com]:port -u username -p password
2sudo docker login https://cr.harbor.kubekey.com -u admin -p Harbor12345

{: .prompt-danger }

kubekey command 참고

https://github.com/kubesphere/kubekey/blob/master/docs/commands/kk-upgrade.md {: .prompt-info }

Upgrade log 확인 #

1kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system -l 'app in (ks-install, ks-installer)' -o jsonpath='{.items[0].metadata.name}') -f

[Kubernetes] Install Kubernetes(v1.29.x) using Kubekey(v3.1.1) Artifact on Multipass

Mon, 28 Apr 2025 00:00:00 +0000

offline 설치 위한 artifact 참고

version 참고
- kubernetes와 관련된 image는 https://github.com/kubesphere/ks-installer/releases에서 주요 release에만 포함되는 image-list.txt파일을 참고
- kubekey의 버전별로 kubernetes, kubesphere의 최신 지원 버전이 있음
  - kubekey/version/components.json
  - kubekey/cmd/kk/pkg/version/kubesphere/version_enum.go
  - kubekey/cmd/kk/pkg/version/kubernetes/version_enum.go
- default 버전에 대한 설정은 kubekey/cmd/kk/apis/kubekey/v1alpha2/default.go 파일에 있다
https://github.com/kubesphere/kubekey/blob/v3.1.1/docs/manifest_and_artifact.md
https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/images-list.txt
https://kubesphere.io/docs/v3.4/installing-on-linux/introduction/air-gapped-installation
https://github.com/kubesphere/kubekey/blob/v3.1.1/docs/manifest-example.md {: .prompt-info }

Multipass 접속을 위한 ssh key 생성 #

1ssh-keygen -t rsa -b 2048 -f ~/.ssh/id_rsa_multipass

cloud-init 구성 #

cloud-init 생성
```
1vi cloud-init.yaml
```

cloud-init 작성

 1users:
 2 - default
 3 - name: root
 4 sudo: ALL=(ALL) NOPASSWD:ALL
 5 ssh_authorized_keys:
 6 - <content of YOUR public key>
 7
 8 - name: ubuntu
 9 sudo: ALL=(ALL) NOPASSWD:ALL
10 ssh_authorized_keys:
11 - <content of YOUR public key>
12
13runcmd:
14 - sudo apt-get update
15 - sudo timedatectl set-timezone "Asia/Seoul"
16 - sudo swapoff -a
17 - sudo sed -i "/swap/d" /etc/fstab
18 - sudo apt-get install -y conntrack
19 - sudo apt-get install -y socat

cloud-init의 ssh_authorized_keys 설정을 하지 않았을 시 #

각 Node의 ~/.ssh 경로의 있는 authorized_keys에 id_rsa_multipass.pub 내용 붙여넣기
```
1cat $HOME/.ssh/id_rsa_multipass.pub
```

root 계정일 때

1# root 접속
2sudo -i
3
4# 수정 또는 .ssh 폴더 생성 후 authorized_keys 작성
5vi .ssh/authorized_keys

Multipass 생성 #

Repository 생성

1multipass launch focal --name kk-repo --memory 8G --disk 100G --cpus 4 --network name=multipass,mode=manual --cloud-init cloud-init.yaml

Master 생성

1multipass launch focal --name kk-master --memory 8G --disk 50G --cpus 4 --network name=multipass,mode=manual --cloud-init cloud-init.yaml

Worker-1 생성

1multipass launch focal --name kk-worker-1 --memory 8G --disk 50G --cpus 4 --network name=multipass,mode=manual --cloud-init cloud-init.yaml

Worker-2 생성

1multipass launch focal --name kk-worker-2 --memory 8G --disk 50G --cpus 4 --network name=multipass,mode=manual --cloud-init cloud-init.yaml

Multipass 접속 #

kk-repo

1ssh -i $HOME/.ssh/id_rsa_multipass ubuntu@192.168.0.100

1multipass shell kk-repo

kk-master

1ssh -i $HOME/.ssh/id_rsa_multipass ubuntu@192.168.0.101

1multipass shell kk-master

kk-worker-1

1ssh -i $HOME/.ssh/id_rsa_multipass ubuntu@192.168.0.102

1multipass shell kk-worker-1

kk-worker-2

1ssh -i $HOME/.ssh/id_rsa_multipass ubuntu@192.168.0.103

1multipass shell kk-worker-2

각 Node별로 Static IP 설정 #

1sudo vi /etc/netplan/50-cloud-init.yaml

kk-repo

 1network:
 2 ethernets:
 3 eth0:
 4 dhcp4: true
 5 dhcp6: true
 6 match:
 7 macaddress: 52:54:00:80:6b:21
 8 set-name: eth0
 9--- 추가
10 eth1:
11 addresses: [192.168.0.100/24]
12 gateway4: 192.168.0.1
13 dhcp4: no
14---
15 version: 2

kk-master

 1network:
 2 ethernets:
 3 eth0:
 4 dhcp4: true
 5 dhcp6: true
 6 match:
 7 macaddress: 52:54:00:80:6b:21
 8 set-name: eth0
 9--- 추가
10 eth1:
11 addresses: [192.168.0.101/24]
12 gateway4: 192.168.0.1
13 dhcp4: no
14---
15 version: 2

kk-worker-1

 1network:
 2 ethernets:
 3 eth0:
 4 dhcp4: true
 5 dhcp6: true
 6 match:
 7 macaddress: 52:54:00:80:6b:21
 8 set-name: eth0
 9--- 추가
10 eth1:
11 addresses: [192.168.0.102/24]
12 gateway4: 192.168.0.1
13 dhcp4: no
14---
15 version: 2

kk-worker-2

 1network:
 2 ethernets:
 3 eth0:
 4 dhcp4: true
 5 dhcp6: true
 6 match:
 7 macaddress: 52:54:00:80:6b:21
 8 set-name: eth0
 9--- 추가
10 eth1:
11 addresses: [192.168.0.103/24]
12 gateway4: 192.168.0.1
13 dhcp4: no
14---
15 version: 2

kubekey artifact 구성 및 설치 #

script 다운로드 #

1curl -sfL https://get-kk.kubesphere.io | VERSION=v3.1.1 sh -

ubuntu-20.04-debs-amd64.iso 다운로드 #

1wget https://github.com/kubesphere/kubekey/releases/download/v3.1.1/ubuntu-20.04-debs-amd64.iso

artifact-3.1.1.yaml 작성 #

 1apiVersion: kubekey.kubesphere.io/v1alpha2
 2kind: Manifest
 3metadata:
 4 name: artifact-v3.1.1
 5spec:
 6 arches:
 7 - amd64
 8 operatingSystems:
 9 - arch: amd64
 10 type: linux
 11 id: ubuntu
 12 version: "20.04"
 13 osImage: Ubuntu 20.04.4 LTS
 14 repository:
 15 iso:
 16 localPath: "/home/ubuntu/kk_install/ubuntu-20.04-debs-amd64.iso"
 17 # url: "https://github.com/kubesphere/kubekey/releases/download/v3.1.1/ubuntu-20.04-debs-amd64.iso"
 18 kubernetesDistributions:
 19 - type: kubernetes
 20 version: v1.29.3
 21 components:
 22 helm:
 23 version: v3.14.3
 24 cni:
 25 version: v1.2.0
 26 etcd:
 27 version: v3.5.13
 28 calicoctl:
 29 version: v3.27.3
 30 ## For now, if your cluster container runtime is containerd, KubeKey will add a docker 20.10.8 container runtime in the below list.
 31 ## The reason is KubeKey creates a cluster with containerd by installing a docker first and making kubelet connect the socket file of containerd which docker contained.
 32 containerRuntimes:
 33 - type: docker
 34 version: 24.0.9
 35 - type: containerd
 36 version: 1.7.13
 37 crictl:
 38 version: v1.29.0
 39 docker-registry:
 40 version: "2"
 41 harbor:
 42 version: v2.10.1
 43 docker-compose:
 44 version: v2.26.1
 45 images:
 46 - docker.io/kubesphere/kube-apiserver:v1.29.3
 47 - docker.io/kubesphere/kube-controller-manager:v1.29.3
 48 - docker.io/kubesphere/kube-scheduler:v1.29.3
 49 - docker.io/kubesphere/kube-proxy:v1.29.3
 50 - docker.io/kubesphere/pause:3.9
 51 - docker.io/coredns/coredns:1.9.3
 52 - docker.io/calico/cni:v3.23.2
 53 - docker.io/calico/cni:v3.27.3
 54 - docker.io/calico/kube-controllers:v3.23.2
 55 - docker.io/calico/kube-controllers:v3.27.3
 56 - docker.io/calico/node:v3.23.2
 57 - docker.io/calico/node:v3.27.3
 58 - docker.io/calico/pod2daemon-flexvol:v3.23.2
 59 - docker.io/calico/typha:v3.23.2
 60 - docker.io/kubesphere/flannel:v0.12.0
 61 - docker.io/openebs/provisioner-localpv:3.3.0
 62 - docker.io/openebs/linux-utils:3.3.0
 63 - docker.io/library/haproxy:2.3
 64 - docker.io/kubesphere/nfs-subdir-external-provisioner:v4.0.2
 65 - docker.io/kubesphere/k8s-dns-node-cache:1.22.20
 66 - docker.io/kubesphere/k8s-dns-node-cache:1.15.12
 67 # https://github.com/kubesphere/ks-installer/releases/download/v3.3.2/images-list.txt
 68 ##kubesphere-images
 69 - docker.io/kubesphere/ks-installer:v3.4.1
 70 - docker.io/kubesphere/ks-apiserver:v3.4.1
 71 - docker.io/kubesphere/ks-console:v3.4.1
 72 - docker.io/kubesphere/ks-controller-manager:v3.4.1
 73 - docker.io/kubesphere/kubectl:v1.22.0
 74 - docker.io/kubesphere/kubefed:v0.8.1
 75 - docker.io/kubesphere/tower:v0.2.1
 76 - docker.io/minio/minio:RELEASE.2019-08-07T01-59-21Z
 77 - docker.io/minio/mc:RELEASE.2019-08-07T23-14-43Z
 78 - docker.io/csiplugin/snapshot-controller:v4.0.0
 79 - docker.io/kubesphere/nginx-ingress-controller:v1.3.1
 80 - docker.io/mirrorgooglecontainers/defaultbackend-amd64:1.4
 81 - docker.io/kubesphere/metrics-server:v0.4.2
 82 - docker.io/library/redis:5.0.14-alpine
 83 - docker.io/library/haproxy:2.0.25-alpine
 84 - docker.io/library/alpine:3.14
 85 - docker.io/osixia/openldap:1.3.0
 86 - docker.io/kubesphere/netshoot:v1.0
 87 ##kubeedge-images
 88 - docker.io/kubeedge/cloudcore:v1.13.0
 89 - docker.io/kubesphere/iptables-manager:v1.13.0
 90 - docker.io/kubeedge/iptables-manager:v1.9.2
 91 - docker.io/kubesphere/edgeservice:v0.3.0
 92 - docker.io/kubesphere/edgeservice:v0.2.0
 93 ##gatekeeper-images
 94 - docker.io/openpolicyagent/gatekeeper:v3.5.2
 95 ##openpitrix-images
 96 - docker.io/kubesphere/openpitrix-jobs:v3.3.2
 97 ##kubesphere-devops-images
 98 - docker.io/kubesphere/devops-apiserver:ks-v3.4.1
 99 - docker.io/kubesphere/devops-controller:ks-v3.4.1
100 - docker.io/kubesphere/devops-tools:ks-v3.4.1
101 - docker.io/kubesphere/ks-jenkins:v3.4.0-2.319.3-1
102 - docker.io/jenkins/inbound-agent:4.10-2
103 - docker.io/kubesphere/builder-base:v3.2.2
104 - docker.io/kubesphere/builder-nodejs:v3.2.0
105 - docker.io/kubesphere/builder-maven:v3.2.1-jdk11
106 - docker.io/kubesphere/builder-maven:v3.2.0
107 - docker.io/kubesphere/builder-python:v3.2.0
108 - docker.io/kubesphere/builder-go:v3.2.2-1.18
109 - docker.io/kubesphere/builder-go:v3.2.2-1.17
110 - docker.io/kubesphere/builder-go:v3.2.2-1.16
111 - docker.io/kubesphere/builder-go:v3.2.0
112 - docker.io/kubesphere/builder-base:v3.2.2-podman
113 - docker.io/kubesphere/builder-nodejs:v3.2.0-podman
114 - docker.io/kubesphere/builder-maven:v3.2.1-jdk11-podman
115 - docker.io/kubesphere/builder-maven:v3.2.0-podman
116 - docker.io/kubesphere/builder-python:v3.2.0-podman
117 - docker.io/kubesphere/builder-go:v3.2.0-podman
118 - docker.io/kubesphere/builder-go:v3.2.2-1.18-podman
119 - docker.io/kubesphere/builder-go:v3.2.2-1.17-podman
120 - docker.io/kubesphere/builder-go:v3.2.2-1.16-podman
121 - docker.io/kubesphere/s2ioperator:v3.2.1
122 - docker.io/kubesphere/s2irun:v3.2.0
123 - docker.io/kubesphere/s2i-binary:v3.2.0
124 - docker.io/kubesphere/tomcat85-java11-centos7:v3.2.0
125 - docker.io/kubesphere/tomcat85-java11-runtime:v3.2.0
126 - docker.io/kubesphere/tomcat85-java8-centos7:v3.2.0
127 - docker.io/kubesphere/tomcat85-java8-runtime:v3.2.0
128 - docker.io/kubesphere/java-11-centos7:v3.2.0
129 - docker.io/kubesphere/java-11-runtime:v3.2.0
130 - docker.io/kubesphere/java-8-centos7:v3.2.0
131 - docker.io/kubesphere/java-8-runtime:v3.2.0
132 - docker.io/kubesphere/nodejs-8-centos7:v3.2.0
133 - docker.io/kubesphere/nodejs-6-centos7:v3.2.0
134 - docker.io/kubesphere/nodejs-4-centos7:v3.2.0
135 - docker.io/kubesphere/python-36-centos7:v3.2.0
136 - docker.io/kubesphere/python-35-centos7:v3.2.0
137 - docker.io/kubesphere/python-34-centos7:v3.2.0
138 - docker.io/kubesphere/python-27-centos7:v3.2.0
139 - quay.io/argoproj/argocd:v2.3.3
140 - quay.io/argoproj/argocd-applicationset:v0.4.1
141 - ghcr.io/dexidp/dex:v2.30.2
142 - docker.io/library/redis:6.2.6-alpine
143 ##kubesphere-monitoring-images
144 - docker.io/jimmidyson/configmap-reload:v0.7.1
145 - docker.io/prom/prometheus:v2.39.1
146 - docker.io/kubesphere/prometheus-config-reloader:v0.55.1
147 - docker.io/kubesphere/prometheus-operator:v0.55.1
148 - docker.io/kubesphere/kube-rbac-proxy:v0.11.0
149 - docker.io/kubesphere/kube-state-metrics:v2.6.0
150 - docker.io/prom/node-exporter:v1.3.1
151 - docker.io/prom/alertmanager:v0.23.0
152 - docker.io/thanosio/thanos:v0.31.0
153 - docker.io/grafana/grafana:8.3.3
154 - docker.io/kubesphere/kube-rbac-proxy:v0.11.0
155 - docker.io/kubesphere/notification-manager-operator:v2.3.0
156 - docker.io/kubesphere/notification-manager:v2.3.0
157 - docker.io/kubesphere/notification-tenant-sidecar:v3.2.0
158 ##kubesphere-logging-images
159 - docker.io/kubesphere/elasticsearch-curator:v5.7.6
160 - docker.io/kubesphere/opensearch-curator:v0.0.5
161 - docker.io/kubesphere/elasticsearch-oss:6.8.22
162 - docker.io/opensearchproject/opensearch:2.6.0
163 - docker.io/opensearchproject/opensearch-dashboards:2.6.0
164 - docker.io/kubesphere/fluentbit-operator:v0.14.0
165 - docker.io/library/docker:19.03
166 - docker.io/kubesphere/fluent-bit:v1.9.4
167 - docker.io/kubesphere/log-sidecar-injector:v1.2.0
168 - docker.io/elastic/filebeat:6.7.0
169 - docker.io/kubesphere/kube-events-operator:v0.6.0
170 - docker.io/kubesphere/kube-events-ruler:v0.6.0
171 - docker.io/kubesphere/kube-auditing-operator:v0.2.0
172 - docker.io/kubesphere/kube-auditing-webhook:v0.2.0
173 ##istio-images
174 - docker.io/istio/pilot:1.14.6
175 - docker.io/istio/proxyv2:1.14.6
176 - docker.io/jaegertracing/jaeger-operator:1.29
177 - docker.io/jaegertracing/jaeger-agent:1.29
178 - docker.io/jaegertracing/jaeger-collector:1.29
179 - docker.io/jaegertracing/jaeger-query:1.29
180 - docker.io/jaegertracing/jaeger-es-index-cleaner:1.29
181 - docker.io/kubesphere/kiali-operator:v1.50.1
182 - docker.io/kubesphere/kiali:v1.50
183 # ##example-images
184 # - docker.io/library/busybox:1.31.1
185 # - docker.io/library/nginx:1.14-alpine
186 # - docker.io/joosthofman/wget:1.0
187 # - docker.io/nginxdemos/hello:plain-text
188 # - docker.io/library/wordpress:4.8-apache
189 # - docker.io/mirrorgooglecontainers/hpa-example:latest
190 # - docker.io/fluent/fluentd:v1.4.2-2.0
191 # - docker.io/library/perl:latest
192 # - docker.io/kubesphere/examples-bookinfo-productpage-v1:1.16.2
193 # - docker.io/kubesphere/examples-bookinfo-reviews-v1:1.16.2
194 # - docker.io/kubesphere/examples-bookinfo-reviews-v2:1.16.2
195 # - docker.io/kubesphere/examples-bookinfo-details-v1:1.16.2
196 # - docker.io/kubesphere/examples-bookinfo-ratings-v1:1.16.3
197 # ##weave-scope-images
198 # - docker.io/weaveworks/scope:1.13.0
199 registry:
200 auths:
201 "docker.io":
202 username: "username"
203 password: "password"

components version 확인(지원하는 version이 없을 시 아래와 같이 Error) #

Failed to download docker binary: curl -L -o /home/ubuntu/kk_install/kubekey/artifact/docker/20.10.8/amd64/docker-20.10.8.tgz https://download.docker.com/linux/static/stable/x86_64/docker-20.10.8.tgz error: No SHA256 found for docker. 20.10.8 is not supported.
17:40:24 KST failed: [LocalHost]
error: Pipeline[ArtifactExportPipeline] execute failed: Module[ArtifactBinariesModule] exec failed:
failed: [LocalHost] [DownloadBinaries] exec failed after 1 retries: Failed to download docker binary: curl -L -o /home/ubuntu/kk_install/kubekey/artifact/docker/20.10.8/amd64/docker-20.10.8.tgz https://download.docker.com/linux/static/stable/x86_64/docker-20.10.8.tgz error: No SHA256 found for docker. 20.10.8 is not supported.

Components 참고

https://github.com/kubesphere/kubekey/blob/v3.1.1/version/components.json {: .prompt-info }

Export Artifact #

1sudo ./kk artifact export -m artifact-3.1.1.yaml -o artifact-3.1.1.tar.gz

Cluster 설치를 위한 config 파일 생성 및 작성 #

config 파일 생성

1sudo ./kk create config --with-kubesphere v3.3.2 --with-kubernetes v1.29.3 -f config-v1.29.3.yaml

config 파일 편집
```
1vi config-v1.29.3.yaml
```

config 파일 작성

 1apiVersion: kubekey.kubesphere.io/v1alpha2
 2kind: Cluster
 3metadata:
 4 name: sample
 5spec:
 6 hosts:
 7 - {name: kk-repo, address: 192.168.0.100, internalAddress: 192.168.0.100, privateKeyPath: "/home/ubuntu/.ssh/id_rsa_multipass"}
 8 - {name: kk-master, address: 192.168.0.101, internalAddress: 192.168.0.101, privateKeyPath: "/home/ubuntu/.ssh/id_rsa_multipass"}
 9 - {name: kk-worker-1, address: 192.168.0.102, internalAddress: 192.168.0.102, privateKeyPath: "/home/ubuntu/.ssh/id_rsa_multipass"}
 10 - {name: kk-worker-2, address: 192.168.0.103, internalAddress: 192.168.0.103, privateKeyPath: "/home/ubuntu/.ssh/id_rsa_multipass"}
 11 roleGroups:
 12 etcd:
 13 - kk-master
 14 control-plane:
 15 - kk-master
 16 worker:
 17 - kk-worker-1
 18 - kk-worker-2
 19 registry:
 20 - kk-repo
 21 controlPlaneEndpoint:
 22 ## Internal loadbalancer for apiservers
 23 # internalLoadbalancer: haproxy
 24
 25 domain: lb.kubesphere.local
 26 # domain: 192.168.0.101
 27 address: "192.168.0.101"
 28 port: 6443
 29 kubernetes:
 30 version: v1.29.3
 31 imageRepo: kubesphere
 32 clusterName: cluster.local
 33 masqueradeAll: false
 34 maxPods: 150
 35 nodeCidrMaskSize: 24
 36 proxyMode: ipvs
 37 autoRenewCerts: true
 38 containerManager: containerd
 39 featureGates:
 40 RotateKubeletServerCertificate: true
 41 apiserverArgs:
 42 - default-not-ready-toleration-seconds=30
 43 - default-unreachable-toleration-seconds=30
 44 controllerManagerArgs:
 45 - node-monitor-period=2s
 46 - node-monitor-grace-period=16s
 47 kubeletConfiguration:
 48 nodeStatusUpdateFrequency: 4s
 49 # etcd:
 50 # type: kubekey
 51 network:
 52 plugin: calico
 53 calico:
 54 ipipMode: Always
 55 vxianMode: Never
 56 vethMTU: 1440
 57 kubePodsCIDR: 10.233.64.0/18
 58 kubeServiceCIDR: 10.233.0.0/18
 59 ## multus support. https://github.com/k8snetworkplumbingwg/multus-cni
 60 multusCNI:
 61 enabled: false
 62 registry:
 63 type: harbor
 64 auths:
 65 "cr.harbor.kubekey.com":
 66 username: admin
 67 password: Harbor12345
 68 privateRegistry: "cr.harbor.kubekey.com"
 69 namespaceOverride: "kubesphereio"
 70 registryMirrors: []
 71 insecureRegistries: ["cr.harbor.kubekey.com"]
 72 addons: []
 73---
 74apiVersion: installer.kubesphere.io/v1alpha1
 75kind: ClusterConfiguration
 76metadata:
 77 name: ks-installer
 78 namespace: kubesphere-system
 79 labels:
 80 version: v3.4.1
 81spec:
 82 persistence:
 83 storageClass: ""
 84 authentication:
 85 jwtSecret: ""
 86 zone: ""
 87 local_registry: ""
 88 namespace_override: ""
 89 # dev_tag: ""
 90 etcd:
 91 monitoring: false
 92 endpointIps: localhost
 93 port: 2379
 94 tlsEnable: true
 95 common:
 96 core:
 97 console:
 98 enableMultiLogin: true
 99 port: 30880
100 type: NodePort
101 # apiserver:
102 # resources: {}
103 # controllerManager:
104 # resources: {}
105 redis:
106 enabled: false
107 volumeSize: 2Gi
108 openldap:
109 enabled: false
110 volumeSize: 2Gi
111 minio:
112 volumeSize: 20Gi
113 monitoring:
114 # type: external
115 endpoint: http://prometheus-operated.kubesphere-monitoring-system.svc:9090
116 GPUMonitoring:
117 enabled: false
118 gpu:
119 kinds:
120 - resourceName: "nvidia.com/gpu"
121 resourceType: "GPU"
122 default: true
123 es:
124 # master:
125 # volumeSize: 4Gi
126 # replicas: 1
127 # resources: {}
128 # data:
129 # volumeSize: 20Gi
130 # replicas: 1
131 # resources: {}
132 logMaxAge: 7
133 elkPrefix: logstash
134 basicAuth:
135 enabled: false
136 username: ""
137 password: ""
138 externalElasticsearchHost: ""
139 externalElasticsearchPort: ""
140 alerting:
141 enabled: false
142 # thanosruler:
143 # replicas: 1
144 # resources: {}
145 auditing:
146 enabled: false
147 # operator:
148 # resources: {}
149 # webhook:
150 # resources: {}
151 devops:
152 enabled: false
153 # resources: {}
154 jenkinsMemoryLim: 8Gi
155 jenkinsMemoryReq: 4Gi
156 jenkinsVolumeSize: 8Gi
157 events:
158 enabled: false
159 # operator:
160 # resources: {}
161 # exporter:
162 # resources: {}
163 # ruler:
164 # enabled: true
165 # replicas: 2
166 # resources: {}
167 logging:
168 enabled: false
169 logsidecar:
170 enabled: true
171 replicas: 2
172 # resources: {}
173 metrics_server:
174 enabled: false
175 monitoring:
176 storageClass: ""
177 node_exporter:
178 port: 9100
179 # resources: {}
180 # kube_rbac_proxy:
181 # resources: {}
182 # kube_state_metrics:
183 # resources: {}
184 # prometheus:
185 # replicas: 1
186 # volumeSize: 20Gi
187 # resources: {}
188 # operator:
189 # resources: {}
190 # alertmanager:
191 # replicas: 1
192 # resources: {}
193 # notification_manager:
194 # resources: {}
195 # operator:
196 # resources: {}
197 # proxy:
198 # resources: {}
199 gpu:
200 nvidia_dcgm_exporter:
201 enabled: false
202 # resources: {}
203 multicluster:
204 clusterRole: none
205 network:
206 networkpolicy:
207 enabled: false
208 ippool:
209 type: none
210 topology:
211 type: none
212 openpitrix:
213 store:
214 enabled: false
215 servicemesh:
216 enabled: false
217 istio:
218 components:
219 ingressGateways:
220 - name: istio-ingressgateway
221 enabled: false
222 cni:
223 enabled: false
224 edgeruntime:
225 enabled: false
226 kubeedge:
227 enabled: false
228 cloudCore:
229 cloudHub:
230 advertiseAddress:
231 - ""
232 service:
233 cloudhubNodePort: "30000"
234 cloudhubQuicNodePort: "30001"
235 cloudhubHttpsNodePort: "30002"
236 cloudstreamNodePort: "30003"
237 tunnelNodePort: "30004"
238 # resources: {}
239 # hostNetWork: false
240 iptables-manager:
241 enabled: true
242 mode: "external"
243 # resources: {}
244 # edgeService:
245 # resources: {}
246 terminal:
247 timeout: 600

Repo에서 각 Node 접속을 위해 `id_rsa_multipass` 파일 복사 #

1multipass copy-files $HOME/.ssh/id_rsa_multipass kk-repo:/home/ubuntu/.ssh/id_rsa_multipass

Registry 설치 #

1sudo ./kk init registry -f config-v1.29.3.yaml -a artifact-3.1.1.tar.gz

harbor 주소 : [harbor 설치한 ip]:80 {: .prompt-info }

[ERROR] ssh error

각 node 별로 ssh가 안될시 root passwd가 맞지 않아 발생함.
Multipass에서 vm이 생성되면 root 비번을 설정해줘야 하는 듯

1sudo passwd root

{: .prompt-danger }

Harbor 인증서 복사 및 업데이트 (`harbor curl: (60) SSL certificate problem: unable to get local issuer certificate`) #

인증서 업데이트를 하지 않았을 시, 아래와 같이 Error

[WARNING ImagePull]: failed to pull image cr.harbor.kubekey.com/kubesphereio/kube-apiserver:v1.29.3: output: E0501 22:53:12.616927 4525 remote_image.go:180] "PullImage from image service failed" err="rpc error: code = Unknown desc = failed to pull and unpack image \"cr.harbor.kubekey.com/kubesphereio/kube-apiserver:v1.29.3\": failed to resolve reference \"cr.harbor.kubekey.com/kubesphereio/kube-apiserver:v1.29.3\": failed to do request: Head \"https://cr.harbor.kubekey.com:443/v2/kubesphereio/kube-apiserver/manifests/v1.29.3\": tls: failed to verify certificate: x509: certificate signed by unknown authority" image="cr.harbor.kubekey.com/kubesphereio/kube-apiserver:v1.29.3"
time="2025-05-01T22:53:12+09:00" level=fatal msg="pulling image: failed to pull and unpack image \"cr.harbor.kubekey.com/kubesphereio/kube-apiserver:v1.29.3\": failed to resolve reference \"cr.harbor.kubekey.com/kubesphereio/kube-apiserver:v1.29.3\": failed to do request: Head \"https://cr.harbor.kubekey.com:443/v2/kubesphereio/kube-apiserver/manifests/v1.29.3\": tls: failed to verify certificate: x509: certificate signed by unknown authority"
, error: exit status 1

{: .prompt-danger }

Repo 및 각 Node의 인증서 복사 #

1sudo cp /etc/docker/certs.d/cr.harbor.kubekey.com/ca.crt /usr/local/share/ca-certificates/harbor-ca.crt
2sudo scp -i /home/ubuntu/.ssh/id_rsa_multipass /usr/local/share/ca-certificates/harbor-ca.crt root@192.168.0.101:/usr/local/share/ca-certificates/harbor-ca.crt
3sudo scp -i /home/ubuntu/.ssh/id_rsa_multipass /usr/local/share/ca-certificates/harbor-ca.crt root@192.168.0.102:/usr/local/share/ca-certificates/harbor-ca.crt
4sudo scp -i /home/ubuntu/.ssh/id_rsa_multipass /usr/local/share/ca-certificates/harbor-ca.crt root@192.168.0.103:/usr/local/share/ca-certificates/harbor-ca.crt

각 Node 별로 인증서 업데이트 #

1sudo update-ca-certificates

인증서 적용 확인 #

1ls -lrt /etc/ssl/certs

- harbor-ca.pem -> /usr/local/share/ca-certificates/harbor-ca.crt
- ca-certificates.crt

Container Restart #

1sudo systemctl restart containerd

Harbor Project 생성 #

Sample Bash 파일 다운로드 #

1curl -O https://raw.githubusercontent.com/kubesphere/ks-installer/master/scripts/create_project_harbor.sh

Harbor 프로젝트 수정 및 url 수정(https://dockerhub.kubekey.local) #

파일 편집
```
1vi create_project_harbor.sh
```

url 수정(https://dockerhub.kubekey.local)

 1#!/usr/bin/env bash
 2
 3# Copyright 2018 The KubeSphere Authors.
 4#
 5# Licensed under the Apache License, Version 2.0 (the "License");
 6# you may not use this file except in compliance with the License.
 7# You may obtain a copy of the License at
 8#
 9# http://www.apache.org/licenses/LICENSE-2.0
10#
11# Unless required by applicable law or agreed to in writing, software
12# distributed under the License is distributed on an "AS IS" BASIS,
13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14# See the License for the specific language governing permissions and
15# limitations under the License.
16
17url="https://cr.harbor.kubekey.com" #Change the value of url to https://cr.harbor.kubekey.com.
18user="admin"
19passwd="Harbor12345"
20
21harbor_projects=(library
22 kubesphereio
23 kubesphere
24 argoproj
25 calico
26 coredns
27 openebs
28 csiplugin
29 minio
30 mirrorgooglecontainers
31 osixia
32 prom
33 thanosio
34 jimmidyson
35 grafana
36 elastic
37 istio
38 jaegertracing
39 jenkins
40 weaveworks
41 openpitrix
42 joosthofman
43 nginxdemos
44 fluent
45 kubeedge
46 openpolicyagent
47)
48
49for project in "${harbor_projects[@]}"; do
50 echo "creating $project"
51 curl -u "${user}:${passwd}" -X POST -H "Content-Type: application/json" "${url}/api/v2.0/projects" -d "{ \"project_name\": \"${project}\", \"public\": true}" -k #Add -k at the end of the curl command.
52done

파일 권한 변경 #

1chmod +x create_project_harbor.sh

실행 #

1./create_project_harbor.sh

Cluster 설치 #

1sudo ./kk create cluster -f config-v1.29.3.yaml -a artifact-3.1.1.tar.gz

Install operating system packages

1sudo ./kk create cluster -f config-v1.29.3.yaml -a artifact-3.1.1.tar.gz --with-packages

{: .prompt-tip }

image 별도로 push 방법

1sudo ./kk artifact image push -f config-v1.29.3.yaml -a artifact-3.1.1.tar.gz

{: .prompt-tip }

--skip-push-images를 추가하면 harbor에 image를 push하는 과정으로 생략할 수 있다.

1sudo ./kk create cluster -f config-v1.29.3.yaml -a artifact-3.1.1.tar.gz --skip-push-images

{: .prompt-tip }

[ERROR] Harbor에 image push 할 때 Unauthorized 에러 발생 때

다시 로그인

1docker login [your.host.com]:port -u username -p password
2sudo docker login https://cr.harbor.kubekey.com -u admin -p Harbor12345

{: .prompt-danger }

kubekey command 참고

https://github.com/kubesphere/kubekey/blob/master/docs/commands/kk-upgrade.md {: .prompt-info }

Cluster 설치하면서 log 확인 #

1kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system -l 'app in (ks-install, ks-installer)' -o jsonpath='{.items[0].metadata.name}') -f

Kubernetes 일반 유저 일 때 #

1mkdir -p $HOME/.kube
2sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
3sudo chown $(id -u):$(id -g) $HOME/.kube/config

만약 일반 계정에서 아래와 sudo 명령어 없이 kubectl 명령어 사용시 아래와 같은 오류가 발생하면

[ERROR] error loading config file /etc/kubernetes/admin.conf: open /etc/kubernetes/admin.conf: permission denied
- 아래 명령어를 입력하면 sudo 없이 사용 가능하다.
```
1export KUBECONFIG=$HOME/.kube/config
```

{: .prompt-danger }

[ERROR] error making pod data directories: mkdir /var/lib/kubelet/pods/86cfe394-ba32-4a9f-ad65-1fb21f98a4ba: read-only file system

1chown -R kubelet:kubelet /var/lib/kubelet/pods
2chmod 750 /var/lib/kubelet/pods
3systemctl restart kubelet

{: .prompt-danger }

Cluster 설치 완료 #

 1#####################################################
 2### Welcome to KubeSphere! ###
 3#####################################################
 4
 5Console: http://192.168.0.101:30880
 6Account: admin
 7Password: P@88w0rd
 8NOTES：
 9 1. After you log into the console, please check the
10 monitoring status of service components in
11 "Cluster Management". If any service is not
12 ready, please wait patiently until all components
13 are up and running.
14 2. Please change the default password after login.
15
16#####################################################
17https://kubesphere.io 2025-05-01 22:32:53
18#####################################################
1922:32:54 KST success: [kk-master]
2022:32:54 KST Pipeline[CreateClusterPipeline] execute successfully
21Installation is complete.
22
23Please check the result using the command:
24
25 kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system -l 'app in (ks-install, ks-installer)' -o jsonpath='{.items[0].metadata.name}') -f

설치 후, 이상 증세 #

Cluster 재시작 이후, 연결이 되지 않을 때 #

1Unable to connect to the server: dial tcp: lookup lb.kubesphere.local on 127.0.0.53:53: server misbehaving

kk-master, kk-worker-1, kk-worker-2 각 Node의 /etc/hosts 수정
```
1sudo vi /etc/hosts
```

아래와 같이 추가

192.168.0.100 cr.harbor.kubekey.com

192.168.0.101 lb.kubesphere.local

# Your system has configured 'manage_etc_hosts' as True.
# As a result, if you wish for changes to this file to persist
# then you will need to either
# a.) make changes to the master file in /etc/cloud/templates/hosts.debian.tmpl
# b.) change or remove the value of 'manage_etc_hosts' in
# /etc/cloud/cloud.cfg or cloud-config from user-data
#
127.0.1.1 kk-worker-1 kk-worker-1
127.0.0.1 localhost

## 추가
192.168.0.100 cr.harbor.kubekey.com
192.168.0.101 lb.kubesphere.local
##

# The following lines are desirable for IPv6 capable hosts
::1 localhost ip6-localhost ip6-loopback
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

다만, 재시작하면 다시 초기화 됨 #

/etc/cloud/templates/hosts.debian.tmpl 해당 파일을 수정해야 다시 시작하더라도 변경됨
```
1sudo vi /etc/cloud/templates/hosts.debian.tmpl
```

아래와 같이 추가

192.168.0.100 cr.harbor.kubekey.com

192.168.0.101 lb.kubesphere.local

# Your system has configured 'manage_etc_hosts' as True.
# As a result, if you wish for changes to this file to persist
# then you will need to either
# a.) make changes to the master file in /etc/cloud/templates/hosts.debian.tmpl
# b.) change or remove the value of 'manage_etc_hosts' in
# /etc/cloud/cloud.cfg or cloud-config from user-data
#
127.0.1.1 kk-worker-1 kk-worker-1
127.0.0.1 localhost

## 추가
192.168.0.100 cr.harbor.kubekey.com
192.168.0.101 lb.kubesphere.local
##

# The following lines are desirable for IPv6 capable hosts
::1 localhost ip6-localhost ip6-loopback
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

아래와 같이 docker-compose 재시작

1sudo -i
2cd /opt/harbor
3docker-compose restart

[Kubernetes] CIS Benchmark와 kube-bench 소개

Wed, 09 Apr 2025 00:00:00 +0000

🔒 CIS Kubernetes Benchmark와 kube-bench란? #

쿠버네티스 클러스터의 보안 상태를 점검하고 규정을 준수하기 위한 도구와 기준입니다.

1️⃣ CIS란? #

CIS (Center for Internet Security)
- 전 세계적으로 보안 벤치마크와 가이드를 제공하는 기관
쿠버네티스용 CIS Kubernetes Benchmark
- 클러스터 설정이 보안 기준을 만족하는지 점검
- 점검 항목 예: 인증, RBAC, 네트워크 정책, etcd 암호화 등

2️⃣ kube-bench란? #

kube-bench = CIS Kubernetes Benchmark 체크 자동화 도구
제공: Aqua Security (aquasec/kube-bench)
역할:
- 쿠버네티스 클러스터 검사
- CIS 기준 준수 여부 확인
- 마스터/워커 노드, 컨트롤 플레인 구성 체크

3️⃣ 설치 및 실행 예시 #

1# Docker로 실행
2docker run --rm --net host --pid host --userns host \
3 -v /etc:/etc:ro -v /var:/var:ro -v /usr/bin:/usr/local/bin:ro \
4 aquasec/kube-bench:latest

검사 결과: PASS / WARN / FAIL
- PASS: 보안 기준 준수
- WARN: 권장하지만 필수 아님
- FAIL: 보안 위험 존재

4️⃣ 사용 목적 #

쿠버네티스 클러스터 보안 점검
CIS Benchmark 기준 규정 준수 확인
DevSecOps 환경에서 자동화된 감사

5️⃣ 요약 #

항목	내용
CIS	Center for Internet Security, 보안 벤치마크 제공 기관
kube-bench	CIS Kubernetes Benchmark 자동 검사 도구 (AquaSec)
용도	클러스터 보안 점검, 규정 준수 확인, DevSecOps
출력	PASS / WARN / FAIL

💡 한 줄 요약: kube-bench = 쿠버네티스 클러스터를 CIS 보안 기준으로 “건강검진” 해주는 도구

[Docker-Compose] Install Docker-Compose(2.33.1)

Wed, 12 Mar 2025 00:00:00 +0000

도커 (Docker) 설치 #

시스템 업데이트 #

1sudo apt-get update -y
2sudo apt-get upgrade -y

의존성 패키지 설치 #

1sudo apt install apt-transport-https ca-certificates curl software-properties-common -y

도커 GPG 키 추가 #

1curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

도커 레포지토리 설정 #

1echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

도커 설치 #

1sudo apt update
2sudo apt install docker-ce docker-ce-cli containerd.io

도커 시작 및 활성화 #

1sudo systemctl start docker
2sudo systemctl enable docker

도커 상태 확인 #

1sudo systemctl status docker

도커 컴포즈 (Docker-Compose) 설치 #

도커 컴포즈 다운로드 및 설치 #

1sudo curl -L "https://github.com/docker/compose/releases/download/v2.33.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

도커 컴포즈 실행 권한 부여 #

1sudo chmod +x /usr/local/bin/docker-compose

도커 컴포즈 설치 확인 #

1docker-compose --version

도커 컴포즈 CURL 오류 발생 시 #

우분투 22.04 서버에서 도커 컴포즈 CURL 설치 시 아래와 같은 오류가 발생하는 경우가 있다.

오류 코드를 살펴보면 아래와 같다. #

1Failed to create the file /usr/local/bin/docker-compose: No such file or directory
2curl: (23) Failure writing output to destination 오류 발생

위 오류는 설치하려는 대상 디렉토리인 /usr/local/bin 폴더가 없어서 나는 오류이므로 폴더를 만들어주면 간단히 해결된다.

`/usr/local/bin` 폴더 생성 #

1sudo mkdir -p /usr/local/bin

이후 다시 CURL 명령어를 실행하면 잘 설치가 된다.

도커 권한 부여 #

도커를 sudo 없이 실행시키려면 아래 명령어를 통해 모든 유저가 도커에 접근할 수 있도록 해주면 된다.
```
1sudo chmod 666 /var/run/docker.sock
```
위 명령어를 실행하면 super user가 아니더라도 sudo 없이 실행할 수 있다.

[Kubernetes] Kafbat - Kafka UI(1.1.0)

Sat, 08 Mar 2025 00:00:00 +0000

Helm 설치 및 설명 참고 {: .prompt-info }

Add Repo the Helm charts #

1helm repo add kafbat-ui https://kafbat.github.io/helm-charts

values 수정 - kafka 연결 세팅 #

 1...✂...
 2
 3yamlApplicationConfig:
 4 kafka:
 5 clusters:
 6 - name: yaml
 7 bootstrapServers: kafka-cluster-broker-endpoints:9092
 8 auth:
 9 type: disabled
10 management:
11 health:
12 ldap:
13 enabled: false
14
15...✂...

values 수정 - NodePort 설정 #

 1...✂...
 2
 3yamlApplicationConfig:
 4 kafka:
 5 clusters:
 6 - name: yaml
 7 bootstrapServers: my-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092
 8 auth:
 9 type: disabled
10 management:
11 health:
12 ldap:
13 enabled: false
14service:
15 ## @param service.type Kafka-UI service type
16 type: NodePort
17 ## @param service.port Kafka-UI pod port number
18 port: 80
19 # In case of service type LoadBalancer, you can specify reserved static IP
20 # loadBalancerIP: 10.11.12.13
21 # if you want to force a specific nodePort. Must be use with service.type=NodePort
22 nodePort: 30092
23
24...✂...

Install kafka UI #

1helm install -n [NAMESPACE] kafbat-ui kafbat-ui/kafka-ui -f values.yaml

kafbat helm 참고 - https://github.com/kafbat/helm-charts

1helm install -n [NAMESPACE] kafka-ui charts/kafka-ui -f charts/kafka-ui/values.yaml

{: .prompt-info }

[Kubernetes] Strimzi Operator(0.45.0)

Sat, 08 Mar 2025 00:00:00 +0000

Helm 설치 및 설명 참고 {: .prompt-info }

설치 방법 #

Operator Yaml (strimzi-cluster-operator-0.45.0.yaml)
Helm (strimzi-kafka-operator-helm-3-chart-0.45.0.tgz)
- https://github.com/strimzi/strimzi-kafka-operator/tree/main/helm-charts/helm3/strimzi-kafka-operator
cluster-operator Yaml 파일 (https://github.com/strimzi/strimzi-kafka-operator/tree/main/install/cluster-operator)

Strimzi Release 참고 - https://github.com/strimzi/strimzi-kafka-operator/releases {: .prompt-info }

Operator Yaml로 설치 #

Namespace kafka에 설치 #

1kubectl create -f 'https://strimzi.io/install/latest?namespace=kafka' -n kafka

특정 Namespace 또는 여러 Namespace 관리 #

watchNamespaces
- 특정 Namespace에서만 Resource를 감시(watch)하도록 지정하는 기능
watchAnyNamespace
- Kafka 및 관련 Resource를 관리할 때, 여러 Namespace에서 발생하는 변경 사항을 감시(watch)할 수 있도록 설정하는 옵션
- 여러 Namespace에서 Kafka 관련 Resource의 생성, 삭제, 업데이트 등을 실시간으로 추적할 수 있다.

1# If you set `watchNamespaces` to the same value as ``.Release.Namespace` (e.g. `helm ... --namespace $NAMESPACE`),
2# the chart will fail because duplicate RoleBindings will be attempted to be created in the same namespace
3watchNamespaces: []
4watchAnyNamespace: false

values yaml 참고 - https://github.com/strimzi/strimzi-kafka-operator/blob/main/helm-charts/helm3/strimzi-kafka-operator/values.yaml {: .prompt-info }

확인 #

1kubectl get pod -n kafka --watch

Log 확인 #

1kubectl logs deployment/strimzi-cluster-operator -n kafka -f

Storage Class 세팅 (Storage Class 및 PersistentVolume 세팅이 되어 있지 않다면) #

1kind: StorageClass
2apiVersion: storage.k8s.io/v1
3metadata:
4 name: local-storage
5provisioner: kubernetes.io/no-provisioner
6volumeBindingMode: WaitForFirstConsumer

Patch Storage Class #

1kubectl patch storageclass local-storage -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

확인 #

1kubectl get sc
2
3NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE
4local-storage (default) kubernetes.io/no-provisioner Delete WaitForFirstConsumer false 3h16m

PersistentVolume 세팅 #

 1apiVersion: v1
 2kind: PersistentVolume
 3metadata:
 4 name: kafka-pv-volume
 5 labels:
 6 type: local
 7spec:
 8 storageClassName: local-storage
 9 capacity:
10 storage: 10Gi
11 accessModes:
12 - ReadWriteOnce
13 hostPath:
14 path: "/mnt/data"
15---
16apiVersion: v1
17kind: PersistentVolume
18metadata:
19 name: kafka-pv-volume-2
20 labels:
21 type: local
22spec:
23 storageClassName: local-storage
24 capacity:
25 storage: 10Gi
26 accessModes:
27 - ReadWriteOnce
28 hostPath:
29 path: "/mnt/data"
30---
31apiVersion: v1
32kind: PersistentVolume
33metadata:
34 name: kafka-pv-volume-3
35 labels:
36 type: local
37spec:
38 storageClassName: local-storage
39 capacity:
40 storage: 10Gi
41 accessModes:
42 - ReadWriteOnce
43 hostPath:
44 path: "/mnt/data"

Kafka Single Node - kraft 모드 #

Kafka Single Node Yaml 파일 수정 및 참고 - kraft 모드 #

 1apiVersion: kafka.strimzi.io/v1beta2
 2kind: KafkaNodePool
 3metadata:
 4 name: dual-role
 5 labels:
 6 strimzi.io/cluster: my-cluster
 7spec:
 8 replicas: 1
 9 roles:
10 - controller
11 - broker
12 storage:
13 type: jbod
14 volumes:
15 - id: 0
16 type: persistent-claim
17 class: local-storage
18 size: 10Gi
19 deleteClaim: false
20 kraftMetadata: shared
21---
22
23apiVersion: kafka.strimzi.io/v1beta2
24kind: Kafka
25metadata:
26 name: my-cluster
27 annotations:
28 strimzi.io/node-pools: enabled
29 strimzi.io/kraft: enabled
30spec:
31 kafka:
32 version: 3.9.0
33 metadataVersion: 3.9-IV0
34 listeners:
35 - name: plain
36 port: 9092
37 type: internal
38 tls: false
39 - name: tls
40 port: 9093
41 type: internal
42 tls: true
43 template:
44 pod:
45 securityContext:
46 runAsUser: 0
47 config:
48 offsets.topic.replication.factor: 1
49 transaction.state.log.replication.factor: 1
50 transaction.state.log.min.isr: 1
51 default.replication.factor: 1
52 min.insync.replicas: 1
53 entityOperator:
54 topicOperator: {}
55 userOperator: {}

참고 - https://github.com/strimzi/strimzi-kafka-operator/tree/main/examples/kafka/kraft {: .prompt-info }

Kafka Single Node 설치 - kraft 모드 #

1kubectl apply -f https://strimzi.io/examples/latest/kafka/kraft/kafka-single-node.yaml -n kafka

준비될 때까지 기다리기 #

1kubectl wait kafka/my-cluster --for=condition=Ready --timeout=300s -n kafka

Kafka - kraft 모드 #

Kafka Yaml 파일 수정 및 참고 - kraft 모드 #

 1apiVersion: kafka.strimzi.io/v1beta2
 2kind: KafkaNodePool
 3metadata:
 4 name: controller
 5 labels:
 6 strimzi.io/cluster: my-cluster
 7spec:
 8 replicas: 3
 9 roles:
10 - controller
11 storage:
12 type: jbod
13 volumes:
14 - id: 0
15 type: persistent-claim
16 size: 100Gi
17 kraftMetadata: shared
18 deleteClaim: false
19---
20
21apiVersion: kafka.strimzi.io/v1beta2
22kind: KafkaNodePool
23metadata:
24 name: broker
25 labels:
26 strimzi.io/cluster: my-cluster
27spec:
28 replicas: 3
29 roles:
30 - broker
31 storage:
32 type: jbod
33 volumes:
34 - id: 0
35 type: persistent-claim
36 size: 100Gi
37 kraftMetadata: shared
38 deleteClaim: false
39---
40
41apiVersion: kafka.strimzi.io/v1beta2
42kind: Kafka
43metadata:
44 name: my-cluster
45 annotations:
46 strimzi.io/node-pools: enabled
47 strimzi.io/kraft: enabled
48spec:
49 kafka:
50 version: 3.9.0
51 metadataVersion: 3.9-IV0
52 listeners:
53 - name: plain
54 port: 9092
55 type: internal
56 tls: false
57 - name: tls
58 port: 9093
59 type: internal
60 tls: true
61 config:
62 offsets.topic.replication.factor: 3
63 transaction.state.log.replication.factor: 3
64 transaction.state.log.min.isr: 2
65 default.replication.factor: 3
66 min.insync.replicas: 2
67 entityOperator:
68 topicOperator: {}
69 userOperator: {}

참고 - https://github.com/strimzi/strimzi-kafka-operator/tree/main/examples/kafka/kraft {: .prompt-info }

Kafka 설치 - kraft 모드 #

1kubectl apply -f https://strimzi.io/examples/latest/kafka/kraft/kafka.yaml -n kafka

준비될 때까지 기다리기 #

1kubectl wait kafka/my-cluster --for=condition=Ready --timeout=300s -n kafka

[Kubernetes] Install Alloy(v1.7.1) Using Helm Chart

Thu, 06 Mar 2025 00:00:00 +0000

Helm 설치 및 설명 참고 {: .prompt-info }

Install the Helm charts #

namespace 생성

1kubectl create namespace [NAMESPACE NAME]

Alloy 배포

1helm repo add grafana https://grafana.github.io/helm-charts
2helm repo update
3helm install --namespace <NAMESPACE> <RELEASE_NAME> grafana/alloy

Alloy - Helm 설치 참고

https://grafana.com/docs/alloy/latest/set-up/install/kubernetes/ {: .prompt-info }

Customize Default Configuration #

values.yaml 수정

최상위 values.yaml을 수정하면 하위 폴더 values.yaml을 override 한다. {: .prompt-info }
- Release file (.tgz)
  - https://github.com/grafana/helm-charts/releases

kafka 연결 #

 1...✂...
 2
 3alloy:
 4 configMap:
 5 # -- Create a new ConfigMap for the config file.
 6 create: true
 7 # -- Content to assign to the new ConfigMap. This is passed into `tpl` allowing for templating from values.
 8 content: |
 9 loki.source.kafka "raw" {
10 brokers = ["kafka:9092"]
11 topics = ["loki"]
12 forward_to = [loki.write.http.receiver]
13 relabel_rules = loki.relabel.kafka.rules
14 version = "2.0.0"
15 labels = {service_name = "raw_kafka"}
16 }
17
18 loki.relabel "kafka" {
19 forward_to = [loki.write.http.receiver]
20 rule {
21 source_labels = ["__meta_kafka_topic"]
22 target_label = "topic"
23 }
24 }
25
26 loki.write "http" {
27 endpoint {
28 url = "http://loki:3100/loki/api/v1/push"
29 }
30 }
31
32 # -- Name of existing ConfigMap to use. Used when create is false.
33 name: null
34 # -- Key in ConfigMap to get config from.
35 key: null
36
37...✂...

참고 - https://grafana.com/docs/loki/latest/send-data/alloy/examples/alloy-kafka-logs/ {: .prompt-info }

Kafka를 통해 OpenTelemetry logs 수집 #

 1...✂...
 2
 3alloy:
 4 configMap:
 5 # -- Create a new ConfigMap for the config file.
 6 create: true
 7 # -- Content to assign to the new ConfigMap. This is passed into `tpl` allowing for templating from values.
 8 content: |
 9 loki.source.kafka "raw" {
10 brokers = ["kafka:9092"]
11 topics = ["loki"]
12 forward_to = [loki.write.http.receiver]
13 relabel_rules = loki.relabel.kafka.rules
14 version = "2.0.0"
15 labels = {service_name = "raw_kafka"}
16 }
17
18 loki.relabel "kafka" {
19 forward_to = [loki.write.http.receiver]
20 rule {
21 source_labels = ["__meta_kafka_topic"]
22 target_label = "topic"
23 }
24 }
25
26 loki.write "http" {
27 endpoint {
28 url = "http://loki:3100/loki/api/v1/push"
29 }
30 }
31
32
33 otelcol.receiver.kafka "default" {
34 brokers = ["kafka:9092"]
35 protocol_version = "2.0.0"
36 topic = "otlp"
37 encoding = "otlp_proto"
38
39 output {
40 logs = [otelcol.processor.batch.default.input]
41 }
42 }
43
44 otelcol.processor.batch "default" {
45 output {
46 logs = [otelcol.exporter.otlphttp.default.input]
47 }
48 }
49
50 otelcol.exporter.otlphttp "default" {
51 client {
52 endpoint = "http://loki:3100/otlp"
53 }
54 }
55
56 # -- Name of existing ConfigMap to use. Used when create is false.
57 name: null
58 # -- Key in ConfigMap to get config from.
59 key: null
60
61...✂...

참고 - https://grafana.com/docs/loki/latest/send-data/alloy/examples/alloy-kafka-logs/ {: .prompt-info }

Kubernetes Pods logs 연결 #

 1...✂...
 2
 3alloy:
 4 configMap:
 5 # -- Create a new ConfigMap for the config file.
 6 create: true
 7 # -- Content to assign to the new ConfigMap. This is passed into `tpl` allowing for templating from values.
 8 content: |
 9 loki.write "http" {
 10 endpoint {
 11 url = "http://loki:3100/loki/api/v1/push"
 12 }
 13 }
 14
 15 // discovery.kubernetes allows you to find scrape targets from Kubernetes resources.
 16 // It watches cluster state and ensures targets are continually synced with what is currently running in your cluster.
 17 discovery.kubernetes "pod" {
 18 role = "pod"
 19 }
 20
 21 // discovery.relabel rewrites the label set of the input targets by applying one or more relabeling rules.
 22 // If no rules are defined, then the input targets are exported as-is.
 23 discovery.relabel "pod_logs" {
 24 targets = discovery.kubernetes.pod.targets
 25
 26 // Label creation - "namespace" field from "__meta_kubernetes_namespace"
 27 rule {
 28 source_labels = ["__meta_kubernetes_namespace"]
 29 action = "replace"
 30 target_label = "namespace"
 31 }
 32
 33 // Label creation - "pod" field from "__meta_kubernetes_pod_name"
 34 rule {
 35 source_labels = ["__meta_kubernetes_pod_name"]
 36 action = "replace"
 37 target_label = "pod"
 38 }
 39
 40 // Label creation - "container" field from "__meta_kubernetes_pod_container_name"
 41 rule {
 42 source_labels = ["__meta_kubernetes_pod_container_name"]
 43 action = "replace"
 44 target_label = "container"
 45 }
 46
 47 // Label creation - "app" field from "__meta_kubernetes_pod_label_app_kubernetes_io_name"
 48 rule {
 49 source_labels = ["__meta_kubernetes_pod_label_app_kubernetes_io_name"]
 50 action = "replace"
 51 target_label = "app"
 52 }
 53
 54 // Label creation - "job" field from "__meta_kubernetes_namespace" and "__meta_kubernetes_pod_container_name"
 55 // Concatenate values __meta_kubernetes_namespace/__meta_kubernetes_pod_container_name
 56 rule {
 57 source_labels = ["__meta_kubernetes_namespace", "__meta_kubernetes_pod_container_name"]
 58 action = "replace"
 59 target_label = "job"
 60 separator = "/"
 61 replacement = "$1"
 62 }
 63
 64 // Label creation - "container" field from "__meta_kubernetes_pod_uid" and "__meta_kubernetes_pod_container_name"
 65 // Concatenate values __meta_kubernetes_pod_uid/__meta_kubernetes_pod_container_name.log
 66 rule {
 67 source_labels = ["__meta_kubernetes_pod_uid", "__meta_kubernetes_pod_container_name"]
 68 action = "replace"
 69 target_label = "__path__"
 70 separator = "/"
 71 replacement = "/var/log/pods/*$1/*.log"
 72 }
 73
 74 // Label creation - "container_runtime" field from "__meta_kubernetes_pod_container_id"
 75 rule {
 76 source_labels = ["__meta_kubernetes_pod_container_id"]
 77 action = "replace"
 78 target_label = "container_runtime"
 79 regex = "^(\\S+):\\/\\/.+$"
 80 replacement = "$1"
 81 }
 82 }
 83
 84 // loki.source.kubernetes tails logs from Kubernetes containers using the Kubernetes API.
 85 loki.source.kubernetes "pod_logs" {
 86 targets = discovery.relabel.pod_logs.output
 87 forward_to = [loki.process.pod_logs.receiver]
 88 }
 89
 90 // loki.process receives log entries from other Loki components, applies one or more processing stages,
 91 // and forwards the results to the list of receivers in the component's arguments.
 92 loki.process "pod_logs" {
 93 stage.static_labels {
 94 values = {
 95 cluster = "<CLUSTER_NAME>",
 96 }
 97 }
 98
 99 forward_to = [loki.write.<WRITE_COMPONENT_NAME>.receiver]
100 }
101
102 # -- Name of existing ConfigMap to use. Used when create is false.
103 name: null
104 # -- Key in ConfigMap to get config from.
105 key: null
106
107...✂...

참고 - https://grafana.com/docs/alloy/latest/collect/logs-in-kubernetes/#pods-logs {: .prompt-info }

외부 접속을 위한 NodePort 설정 #

 1...✂...
 2
 3service:
 4 # -- Creates a Service for the controller's pods.
 5 enabled: true
 6 # -- Service type
 7 type: NodePort
 8 # -- NodePort port. Only takes effect when `service.type: NodePort`
 9 nodePort: 31128
10 # -- Cluster IP, can be set to None, empty "" or an IP address
11 clusterIP: ''
12 # -- Value for internal traffic policy. 'Cluster' or 'Local'
13 internalTrafficPolicy: Cluster
14 annotations: {}
15 # cloud.google.com/load-balancer-type: Internal
16
17...✂...

외부 접속을 위한 Ingress 설정 #

 1...✂...
 2
 3ingress:
 4 # -- Enables ingress for Alloy (Faro port)
 5 enabled: true
 6 # For Kubernetes >= 1.18 you should specify the ingress-controller via the field ingressClassName
 7 # See https://kubernetes.io/blog/2020/04/02/improvements-to-the-ingress-api-in-kubernetes-1.18/#specifying-the-class-of-an-ingress
 8 # ingressClassName: nginx
 9 # Values can be templated
10 annotations:
11 {}
12 # kubernetes.io/ingress.class: nginx
13 # kubernetes.io/tls-acme: "true"
14 labels: {}
15 path: /
16 faroPort: 12345
17
18 # pathType is only for k8s >= 1.1=
19 pathType: Prefix
20
21 hosts:
22 - chart-example.local
23 ## Extra paths to prepend to every host configuration. This is useful when working with annotation based services.
24 extraPaths: []
25 # - path: /*
26 # backend:
27 # serviceName: ssl-redirect
28 # servicePort: use-annotation
29 ## Or for k8s > 1.19
30 # - path: /*
31 # pathType: Prefix
32 # backend:
33 # service:
34 # name: ssl-redirect
35 # port:
36 # name: use-annotation
37
38 tls: []
39 # - secretName: chart-example-tls
40 # hosts:
41 # - chart-example.local
42
43...✂...

Install Customize Default Configuration #

1helm install -n <NAMESPACE> [RELEASE NAME] [Chart.yaml 경로] -f [YAML 파일 또는 URL에 값 지정 (여러 개를 지정가능)]

1helm install --namespace <NAMESPACE> [RELEASE NAME] grafana/alloy -f override-values.yaml

Uninstall the Chart #

1helm uninstall [RELEASE NAME] -n [NAMESPACE NAME]

[Gitlab] Back up & Restore

Wed, 19 Feb 2025 00:00:00 +0000

Back up #

1gitlab-backup create

위 명령어를 실행하면 .tar 백업파일이 생성된다.
생성된 백업파일은
- /var/opt/gitlab/backups 경로에 저장된다.

만약 백업파일의 경로를 변경하려면 #

1vi /etc/gitlab/gitlab.rb

아래내용 수정 #

gitlab_rails['backup_path'] = "/var/opt/gitlab/backups"

Restore #

만약 다른 서버에 gitlab을 설치하고 복원하기를 원한다면 위에서 백업한 gitlab과 동일한 버전으로 설치하여야 한다.
백업파일을 새로 gitlab을 설치한 서버의 동일한 경로에 옮긴다.

백업파일의 소유자 변경 #

1cd /var/opt/gitlab/backups/
2chown git:git 1707880170_2024_02_14_16.8.1_gitlab_backup.tar

gitlab 서비스 중단 #

1sudo gitlab-ctl stop puma
2sudo gitlab-ctl stop sidekiq
3# Verify
4sudo gitlab-ctl status

복원 #

1sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

재시작 #

1sudo gitlab-ctl restart
2sudo gitlab-rake gitlab:check SANITIZE=true

자동 백업구성 #

시간대 확인
- 현재 서버의 시간대를 확인해서 원하는 시간에 실행되도록 한다.
```
1# Asia/Seoul 시간대로 설정
2timedatectl set-timezone Asia/Seoul
```
reboot
```
1reboot
```

crontab 설정

1crontab -e

# 아래 내용 추가
# 매주 수요일 00시 30분에 백업실행
30 0 * * 3 sh /opt/gitlab/bin/gitlab-backup create

Gitlab Container Back up & Restore #

Back up #

1docker exec -t <container name> gitlab-backup create

Backup options #

대부분의 경우에는 정상적으로 작동하지만, 데이터가 빠르게 변경될 때 문제가 발생할 수 있다.
tar이 데이터를 읽는 도중 데이터가 변경되면 오류 file changed as we read it가 발생하여 백업 프로세스가 실패할 수 있다.
- 이 경우, copy라는 백업 전략을 사용할 수 있다. 이 전략은 tar와 gzip를 호출하기 전에 데이터 파일을 임시 위치로 복사하여 오류를 피한다.
  - 기본 스트리밍 전략 대신 copy 전략을 사용하려면 Rake 작업 명령에 STRATEGY=copy를 지정하면 된다.
```
1docker exec -t <container name> gitlab-backup create STRATEGY=copy
```

Back up 파일 확인 #

/var/opt/gitlab/backups 경로
- [Timestamp of backup creation]_[Date (YYYY_MM_DD)]_[GitLab version]_[GitLab edition]_gitlab_backup.tar와 같은 형태로 백업파일이 생성

참고

gitlab 공식 문서 : https://docs.gitlab.com/administration/backup_restore/backup_archive_process {: .prompt-info }

Resotre #

데이터베이스에 연결된 프로세스를 중지 및 확인

1# Stop the processes that are connected to the database
2docker exec -it <name of container> gitlab-ctl stop puma
3docker exec -it <name of container> gitlab-ctl stop sidekiq
4
5# Verify that the processes are all down before continuing
6docker exec -it <name of container> gitlab-ctl status

BACKUP 변수에 복원 대상이 되는 파일명을 기준
- 예를들어 1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar 이 파일 이름이라면 _gitlab_backup.tar 의 앞부분까지의 문자열인 1493107454_2018_04_25_10.6.4-ce 까지를 입력해주면 된다.
```
1# Run the restore. NOTE: "_gitlab_backup.tar" is omitted from the name
2docker exec -it <name of container> gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce
```
작업이 완료된 이후 Container를 재시작

Restart #

1# Restart the GitLab container
2docker restart <name of container>

1# Check GitLab
2docker exec -it <name of container> gitlab-rake gitlab:check SANITIZE=true

참고

Gitlab Back up : https://docs.gitlab.com/administration/backup_restore
Gitlab Archive Process : https://docs.gitlab.com/administration/backup_restore/backup_archive_process
Gitlab Restore : https://docs.gitlab.com/administration/backup_restore/restore_gitlab {: .prompt-info }

[Redis] Save

Mon, 17 Feb 2025 00:00:00 +0000

Redis는 기본적으로 메모리 기반 저장소이지만, 데이터를 디스크에 저장하기 위해 RDB 또는 AOF 모드를 사용할 수 있다.
이를 설정 파일에서 조정하거나, redis-cli 명령어를 통해 실시간으로 변경할 수 있다.

Redis 접속 #

1kubectl get pods -l app=redis # redis라는 label을 가진 Pod 확인

Redis Pod에 접속

1kubectl exec -it <redis-pod-name> -- redis-cli

Redis 저장 방식 변경 #

Redis는 기본적으로 두 가지 방식으로 데이터를 디스크에 저장할 수 있다: RDB (Redis Database) snapshotting과 AOF (Append-Only File).

RDB (Redis Database snapshotting) 방식 변경 #

RDB는 특정 시간 간격으로 데이터를 디스크에 덤프하여 저장하는 방식이다. Redis 설정에서 save 옵션을 사용하여 RDB 덤프 간격을 설정할 수 있다.
현재 save 설정을 확인하려면 redis-cli에서 다음 명령을 입력한다.

1CONFIG GET save

RDB 설정을 변경하려면 CONFIG SET 명령어를 사용하여 덤프 주기를 설정할 수 있다. 예를 들어, 60초마다 1000개의 키가 변경되면 덤프를 생성하도록 설정하려면 아래와 같이 실행한다.

1CONFIG SET save "60 1000"

이 설정은 60초 동안 1000개의 키가 변경되면 RDB 파일을 덤프하도록 지정한다. 이 설정은 Redis가 동작하는 동안 지속되지 않으므로, 영구적인 변경을 원한다면 redis.conf 파일에서 이 값을 설정해야 한다.

AOF (Append-Only File) 방식 변경 #

AOF는 모든 쓰기 명령을 로그 파일에 순차적으로 기록하여 데이터 손실을 방지하는 방식이다. appendonly 옵션을 사용하여 AOF를 활성화하거나 비활성화할 수 있다.
현재 AOF 설정을 확인하려면 redis-cli에서 다음 명령을 입력한다.

1CONFIG GET appendonly

AOF를 활성화하려면 다음 명령을 입력한다.

1CONFIG SET appendonly yes

AOF의 동작 방식을 조정하려면 appendfsync 설정을 사용할 수 있다. 예를 들어, AOF 동기화를 always로 설정하면, Redis는 각 쓰기 연산 후에 즉시 파일을 디스크에 동기화한다.

1CONFIG SET appendfsync always

AOF는 성능에 영향을 미칠 수 있으므로, 이를 사용하되 주기적인 백업과 모니터링이 필요하다.

변경 사항 확인 #

저장 방식을 변경한 후, 설정이 적용되었는지 다시 확인할 수 있다.

1CONFIG GET save
2CONFIG GET appendonly

영구적인 설정 변경 #

CONFIG SET 명령어는 Redis가 종료되고 재시작되면 설정이 초기화된다. 따라서 영구적인 변경을 원한다면 Redis 설정 파일인 redis.conf에서 해당 값을 수정해야 한다.
Redis의 설정 파일 (redis.conf)을 Kubernetes 설정에 맞게 수정한 후, 해당 파일을 Pod에 반영하거나, Redis가 사용하는 ConfigMap을 업데이트해야 한다.

1kubectl edit configmap redis-config

위 명령을 사용하여 ConfigMap을 수정하고, 그에 맞는 변경을 Redis Pod에 적용한다. Pod가 재시작되면 새로운 설정이 반영된다.

변경 후 Redis 재시작 #

변경 사항을 적용하려면 Redis Pod를 재시작해야 할 수 있다. Redis Pod를 재시작하려면 다음 명령어를 사용할 수 있다.

1kubectl rollout restart deployment redis

[Kubernetes] Deploy Redis Insight(2.64.1)

Fri, 14 Feb 2025 00:00:00 +0000

Redis Insight 배포 #

 1apiVersion: apps/v1
 2kind: Deployment
 3metadata:
 4 name: redisinsight #deployment name
 5 labels:
 6 app: redisinsight #deployment label
 7spec:
 8 replicas: 1 #a single replica pod
 9 selector:
10 matchLabels:
11 app: redisinsight #which pods is the deployment managing, as defined by the pod template
12 template: #pod template
13 metadata:
14 labels:
15 app: redisinsight #label for pod/s
16 spec:
17 containers:
18 - name: redisinsight #Container name (DNS_LABEL, unique)
19 image: redis/redisinsight:latest #repo/image
20 imagePullPolicy: IfNotPresent #Installs the latest Redis Insight version
21 volumeMounts:
22 - name: redisinsight #Pod volumes to mount into the container's filesystem. Cannot be updated.
23 mountPath: /data
24 ports:
25 - containerPort: 5540 #exposed container port and protocol
26 protocol: TCP
27 volumes:
28 - name: redisinsight
29 emptyDir: {} # node-ephemeral volume https://kubernetes.io/docs/concepts/storage/volumes/#emptydir

Redis Insight 설치 참고

https://redis.io/docs/latest/operate/redisinsight/install/install-on-k8s {: .prompt-info }

Redis Insight Configuration Settings 참고

https://redis.io/docs/latest/operate/redisinsight/configuration {: .prompt-info }

[Kubernetes] Deploy P3X Redis UI(v2025.4.101)

Thu, 13 Feb 2025 00:00:00 +0000

P3X Redis UI 배포 #

 1apiVersion: apps/v1
 2kind: Deployment
 3metadata:
 4 name: p3x-redis-ui
 5 namespace: p3x-redis-ui
 6spec:
 7 replicas: 1
 8 selector:
 9 matchLabels:
10 app.kubernetes.io/name: p3x-redis-ui
11 template:
12 metadata:
13 labels:
14 app.kubernetes.io/name: p3x-redis-ui
15 spec:
16 containers:
17 - name: p3x-redis-ui
18 image: patrikx3/p3x-redis-ui
19 ports:
20 - name: p3x-redis-ui
21 containerPort: 7843
22 volumeMounts:
23 - name: p3x-redis-ui-settings
24 mountPath: /settings/.p3xrs-conns.json
25 subPath: .p3xrs-conns.json
26 volumes:
27 - name: p3x-redis-ui-settings
28 configMap:
29 name: p3x-redis-ui-settings

ConfigMap 설정 #

 1apiVersion: v1
 2kind: ConfigMap
 3metadata:
 4 name: p3x-redis-ui-settings
 5 namespace: p3x-redis-ui
 6data:
 7 .p3xrs-conns.json: |
 8 {
 9 "list": [
10 {
11 "name": "cluster",
12 "host": "YOUR_REDIS_HOST",
13 "port": 6379,
14 "password": "YOUR_REDIS_PASSWORD_OR_EMPTY",
15 "id": "unique"
16 }
17 ],
18 "license": ""
19 }

[Kubernetes] Deploy Redis(7.4.2)

Wed, 12 Feb 2025 00:00:00 +0000

Command를 통해 Redis ACL 설정하여 배포 + PVC 설정 #

 1apiVersion: apps/v1
 2kind: Deployment
 3metadata:
 4 name: redis
 5 namespace: redis-namespace
 6spec:
 7 replicas: 1
 8 selector:
 9 matchLabels:
10 app: redis
11 template:
12 metadata:
13 labels:
14 app: redis
15 spec:
16 containers:
17 - name: redis
18 image: redis:latest
19 ports:
20 - containerPort: 6379
21 command:
22 - sh
23 - '-c'
24 args:
25 - "nohup sh -c 'sleep 15 && redis-cli -a $REDIS_PASSWORD ACL SETUSER $REDIS_USERNAME on +@all ~* \\>$REDIS_PASSWORD' & redis-server --requirepass $REDIS_PASSWORD"
26 env:
27 - name: REDIS_USERNAME
28 valueFrom:
29 secretKeyRef:
30 name: redis-credentials
31 key: REDIS_USERNAME
32 - name: REDIS_PASSWORD
33 valueFrom:
34 secretKeyRef:
35 name: redis-credentials
36 key: REDIS_PASSWORD
37 volumeMounts:
38 - name: redis-data
39 mountPath: /data
40 volumes:
41 - name: redis-data
42 persistentVolumeClaim:
43 claimName: redis-pvc

데이터 보존을 위한 PVC 생성 #

Persistent Volume 생성 #

 1apiVersion: v1
 2kind: PersistentVolume
 3metadata:
 4 name: redis-pv
 5spec:
 6 capacity:
 7 storage: 5Gi
 8 accessModes:
 9 - ReadWriteOnce
10 persistentVolumeReclaimPolicy: Retain
11 hostPath:
12 path: /mnt/data/redis

Persistent Volume Claim 생성 #

 1apiVersion: v1
 2kind: PersistentVolumeClaim
 3metadata:
 4 name: redis-pvc
 5spec:
 6 accessModes:
 7 - ReadWriteOnce
 8 resources:
 9 requests:
10 storage: 5Gi

Secret 설정 #

 1apiVersion: v1
 2kind: Secret
 3metadata:
 4 name: redis-credentials
 5 namespace: redis-namespace
 6type: Opaque
 7data:
 8 # base64 인코딩된 값 (user와 password 값)
 9 REDIS_USERNAME: YWRtaW4=  # admin을 base64로 인코딩한 값
10 REDIS_PASSWORD: MTIzNQ==  # 1235를 base64로 인코딩한 값

Redis ACL 설정을 ConfigMap을 통해 Redis 배포 #

 1apiVersion: apps/v1
 2kind: Deployment
 3metadata:
 4 name: redis
 5 namespace: redis-namespace
 6spec:
 7 replicas: 1
 8 selector:
 9 matchLabels:
10 app: redis
11 template:
12 metadata:
13 labels:
14 app: redis
15 spec:
16 containers:
17 - name: redis
18 image: redis:latest
19 ports:
20 - containerPort: 6379
21 command:
22 - "redis-server"
23 - "--aclfile"
24 - "/etc/redis/redis.acl" # ACL 파일 경로 지정
25 volumeMounts:
26 - name: redis-acl-config
27 mountPath: /etc/redis
28 subPath: redis.acl
29 volumes:
30 - name: redis-acl-config
31 configMap:
32 name: redis-acl-config

ConfigMap 설정 #

 1apiVersion: v1
 2kind: ConfigMap
 3metadata:
 4 name: redis-acl-config
 5 namespace: redis-namespace
 6data:
 7 redis.acl: |
 8 # default 계정 No Password
 9 user default on nopass ~* +@all
10
11 # admin 계정 Password 설정
12 user admin on >password ~* +@all
13
14 또는
15
16 # 모든 key 읽기 권한만 부여
17 user default on >password allkeys +@read
18
19 또는
20
21 # 관리자 계정
22 user default on +@all
23
24 # 사용자 계정 (readonly 권한)
25 user myuser on >password +@read
26
27 # 관리자 권한을 가진 사용자
28 user admin on >adminpassword +@all

ACL, Redis 설정 관련 ConfigMap을 통해 Command로 배포 #

 1apiVersion: apps/v1
 2kind: Deployment
 3metadata:
 4 name: redis
 5 namespace: redis-namespace
 6spec:
 7 replicas: 1
 8 selector:
 9 matchLabels:
10 app: redis
11 template:
12 metadata:
13 labels:
14 app: redis
15 spec:
16 containers:
17 - name: redis
18 image: redis:latest
19 ports:
20 - containerPort: 6379
21 command:
22 - sh
23 - '-c'
24 args:
25 - "nohup sh -c 'sleep 15 && redis-cli -a $REDIS_PASSWORD ACL SETUSER $REDIS_USERNAME on +@all ~* \\>$REDIS_PASSWORD' & redis-server /etc/redis/redis.conf --aclfile /etc/redis/redis.acl --requirepass $REDIS_PASSWORD"
26 env:
27 - name: REDIS_USERNAME
28 valueFrom:
29 secretKeyRef:
30 name: redis-credentials
31 key: REDIS_USERNAME
32 - name: REDIS_PASSWORD
33 valueFrom:
34 secretKeyRef:
35 name: redis-credentials
36 key: REDIS_PASSWORD
37 volumeMounts:
38 - name: redis-data
39 mountPath: /data
40 - name: redis-acl-config
41 mountPath: /etc/redis
42 subPath: redis.acl
43 - name: redis-config
44 mountPath: /etc/redis
45 subPath: redis.conf
46 volumes:
47 - name: redis-data
48 persistentVolumeClaim:
49 claimName: redis-pvc
50 - name: redis-acl-config
51 configMap:
52 name: redis-acl-config
53 - name: redis-config
54 configMap:
55 name: redis-config

Redis ConfigMap 설정 #

 1apiVersion: v1
 2kind: ConfigMap
 3metadata:
 4 name: redis-config
 5 namespace: redis-namespace
 6data:
 7 redis.conf: |
 8 # Redis의 기본 설정 예시
 9 save 900 1
10 save 300 10
11 save 60 10000
12
13 appendonly yes
14 appendfsync everysec
15
16 # 아래와 같이 ACL 파일 경로 설정하지 않는다면 command에서 실행
17 aclfile /etc/redis/redis.acl

Redis ACL ConfigMap 설정 #

 1apiVersion: v1
 2kind: ConfigMap
 3metadata:
 4 name: redis-acl-config
 5 namespace: redis-namespace
 6data:
 7 redis.acl: |
 8 # default 계정 No Password
 9 user default on nopass ~* +@all
10
11 # admin 계정 Password 설정
12 user admin on >password ~* +@all
13
14 또는
15
16 # 모든 key 읽기 권한만 부여
17 user default on >password allkeys +@read
18
19 또는
20
21 # 관리자 계정
22 user default on +@all
23
24 # 사용자 계정 (readonly 권한)
25 user myuser on >password +@read
26
27 # 관리자 권한을 가진 사용자
28 user admin on >adminpassword +@all

[Redis] ACL

Wed, 05 Feb 2025 00:00:00 +0000

Redis ACL #

Redis 6 Version 부터 ACL(Access Control List)로 User라는 개념이 도입
- 이 User를 통해 실행 가능 Command와 접근 가능 키를 제한할 수 있다.
ACL : Access Control List. 접근 제어
사용자를 생성하고 암호 지정, 사용 가능한 Command와 키 지정 가능
ACL 사용을 통해 보안성과 안전성 구현 가능
- KEYS/FLUSHALL 호출 방지, 사용자에게 필요한 권한만 부여 등

사용자 조회 #

사용자 정보 리스트 조회 #

1127.0.0.1:6379> ACL LIST
21) "user default on nopass ~* +@all"

초기 Redis 서버에는 default user가 등록되어 있음
사용자명 default
- 활성 상태
- 비밀번호 없음
- 모든 키 접근 가능
- 모든 Command 수행 가능

사용자 목록 조회 #

1127.0.0.1:6379> ACL USERS

사용자 조회 #

1127.0.0.1:6379> ACL GETUSER user

본인 확인 #

1127.0.0.1:6379> ACL WHOAMI

로그인 AUTH #

1127.0.0.1:6379> AUTH user password

user명 생략 시 default user로 로그인

사용자 등록 ACL SETUSER #

1127.0.0.1:6379> ACL SETUSER user on|off >password keys commands

user : user id 설정
on|off : 활성화 여부 설정. 사용자를 등록하지만 일단 사용하지 못하게 할 때 off 사용
- 새로 로그인(auth) 할 수는 없지만, 이미 로그인한 사용자의 사용을 막을 수는 없음
>password : 비밀번호는 > 구분자 다음에 지정
- nopass : 비밀번호 없이 사용하려는 경우 지정. 로그인 시 아무 문자열이나 입력해도 됨
- 비밀번호 저장 시 내부적으로 SHA-256 암호화 알고리즘 사용
keys : 사용가능한 키 지정
- 모든 키 허용 : allkeys 또는 ~*
- 특정 패턴 지정 : ~user* 로 지정 시 user로 시작하는 키만 사용 가능
- ~* 상태에서 특정 패턴을 지정하려면 resetkeys 사용 ex) ACL SETUSER user resetkeys ~user*
commands : 사용 가능한 Command 지정
- 모든 Command 허용 : allcommands 또는 +@all
- 모든 Command 비허용 : nocommands 또는 -@all
- Command 지정 : +command로 추가, -command로 빼기
- Command 그룹 지정 : +@group으로 추가, -@group으로 빼기
ACL SETUSER Command는 비밀번호가 포함되므로 로그에 남지 않음

관리자 user 설정

1127.0.0.1:6379> ACL SETUSER admin on >password allkeys allcommands

조회 user 설정

1127.0.0.1:6379> ACL SETUSER reader on >password allkeys +@read

Read/Write 가능한 일반 사용자 설정

1127.0.0.1:6379> ACL SETUSER writer on >password allkeys allcommands -@dangerous

read-only:로 시작하는 key만 접근 가능
```
1127.0.0.1:6379> ACL SETUSER reader on >abcd ~read-only:* +@all -@set &*
```
- reader라는 User의 비밀번호를 abcd로 설정
- key는 read-only:로 시작하는 key만 접근 가능
- +@all은 모든 Command 사용 가능
- -@set은 set Command는 사용 불가능
- &*는 모든 pub/sub채널에 대해 접근 가능

Command 그룹 #

Command 그룹 목록 조회 #

 1127.0.0.1:6379> ACL CAT
 2 1) "keyspace"
 3 2) "read"
 4 3) "write"
 5 4) "set"
 6 5) "sortedset"
 7 6) "list"
 8 7) "hash"
 9 8) "string"
10 9) "bitmap"
1110) "hyperloglog"
1211) "geo"
1312) "stream"
1413) "pubsub"
1514) "admin"
1615) "fast"
1716) "slow"
1817) "blocking"
1918) "dangerous"
2019) "connection"
2120) "transaction"
2221) "scripting"

keyspace : del, expire, flushdb, keys, ttl, scan 등
read : get, lrange, smembers, zrange, hget, xrange 등
write : set, lpush, sadd, zadd, hset, xadd 등
set : sadd, scard, srem, spop 등
sortedset : zadd, zcard, srem, zpopmin 등
list : lpush, llen, lrem, lpop 등
hash : hset, hlen, ldel, hget 등
string : set, get, incr 등
bitmap : setbit, bitop, getbit 등
hyperloglog : pfadd, pfmerge, pfcount, pfselftest
geo : geoadd, geodist, georadius 등
stream : xadd, xlen, xrange, xdel 등
pubsub : publish, subscribe, pubsub 등
admin : bgsave, config, debug, shutdown 등
- admin 명령은 dangerous 그룹에 포함됨
fast : get, lpush, hget 등
slow : lrem, mset, save 등
blocking : blpop, brpop, brpoplpush, bzpopmin, bzpopmax, xread, xreadgroup
dangerous : flushall, keys, shutdown, failover, cluster, client, module 등
connection : hello, client, auth, echo, ping, command
transaction : watch, multi, unwatch, discard, exec
scripting : evalsha, eval, script

Dangerous 그룹 #

보안 위험, 성능 저하 위험이 있는 Command들이 포함됨
flushall : Redis 서버의 모든 데이터(key, value) 삭제
flushdb : 현재 사용중인 DB의 모든 데이터(key, value) 삭제
swapdb : 두 DB를 swap
keys : 패턴에 일치하는 모든 key 반환 ➡️ scan 사용으로 대체
shutdown : Redis 종료
monitor : 서버에서 실행되는 모든 Command 관찰/감시. monitor 수행 시 서버 성능 50% 하락
role : 자신의 역할(master/slave/sentinel)과 부가 정보 조회
sync : 내부 Command replication
psync : 내부 Command partial replication
replconf : 내부 명령 cluster
pfselftest : 내부 명령 HyperLogLog
sort : list 데이터를 정렬
sort_ro : sort와 동일하지만 결과를 저장하지 않음
migrate : data를 다른 redis server로 옮기기. 내부적으로 dump, restore, del 명령이 실행됨
restore, restore-asking : serialized value를 deserialize하여 저장
failover : master와 replica 변경
info : Redis 서버 정보와 통계값 조회
debug, pfdebug : redis 개발/테스트 용도. 여러 관리 명령 실행 가능
save : RDB 파일 저장 (foreground 수행). 수행 완료까지 서버가 다른 일 수행 불가
bgsave : RDB 파일 저장 (background 수행). 하위 프로세스를 생성하여 수행
bgrewriteaof : AOF 파일 저장(background 수행). 하위 프로세스를 생성하여 수행
lastsave : RDB 마지막 저장 일시를 timestamp 형식으로 출력
slaveof : 슬레이브 설정 변경
replicaof : 복제노드 설정 변경
config : 서버 설정 변경
client : 클라이언트 관리 (조회, 제거, 이름 변경 등)
cluster : 클러스터 설정 변경
module : 모듈 관리
slowlog : 명령 성능 측정/기록. 성능 저하 발생
latency : 서버 성능 분석. 성능 저하 발생
acl : 사용자 관리

그룹의 Command 목록 조회 #

1127.0.0.1:6379> ACL CAT group

Command가 어느 그룹에 속하는지 확인
```
1127.0.0.1:6379> COMMAND INFO <Command명>
```

사용자 삭제 DELUSER #

1127.0.0.1:6379> ACL DELUSER user

Default user 삭제 불가

ACL file #

사용자 정보 저장
```
1127.0.0.1:6379> ACL SAVE
```
- 사용자 정보를 redis.conf에 설정된 옵션에 따라 acl file에 저장
- 저장하는 사용자 정보는 ACL LIST의 결과와 같음
사용자 정보 로드
```
1127.0.0.1:6379> ACL LOAD
```
- redis 서버 시작 시 acl file에서 사용자 정보 로드

ACL(Auth) 로그 #

1127.0.0.1:6379> ACL LOG [<count> | RESET]

실패한 로그인 정보 조회

ACL 참고

https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl {: .prompt-info }

[Kubernetes] Install CloudNativePG Using Helm Chart

Thu, 16 Jan 2025 00:00:00 +0000

참고 Helm 설치 및 설명 참고

PostgreSQL Helm Repo 추가 #

1helm repo add cnpg https://cloudnative-pg.github.io/charts

1helm repo update

자신의 환경에 맞게 values.yaml 파일 수정 #

 1replicaCount: 1
 2
 3image:
 4 repository: ghcr.io/cloudnative-pg/cloudnative-pg
 5 pullPolicy: IfNotPresent
 6 # -- Overrides the image tag whose default is the chart appVersion.
 7 tag: ""
 8
 9imagePullSecrets: []
10nameOverride: ""
11fullnameOverride: ""
12namespaceOverride: ""
13
14hostNetwork: false
15
16...✂...
17
18# -- Nodeselector for the operator to be installed.
19nodeSelector: {}
20
21# -- Tolerations for the operator to be installed.
22tolerations: []
23
24# -- Affinity for the operator to be installed.
25affinity: {}
26
27...✂...

Values 참고

https://github.com/cloudnative-pg/charts/blob/main/charts/cloudnative-pg/values.yaml
참고

Helm으로 Operator 설치 #

1helm install cnpg cnpg/cloudnative-pg --namespace [NAMESPACE NAME] -f values.yaml

postgresql 배포 #

 1apiVersion: postgresql.cnpg.io/v1
 2kind: Cluster
 3metadata:
 4 name: mycluster
 5spec:
 6 imageName: postgres:17.3
 7 instances: 3 # 3대 파드 (Primary 1대, Standby 2대가 기본)
 8 storage: 
 9 size: 3Gi 
10 postgresql:
11 parameters:
12 max_worker_processes: "40"
13 timezone: "Asia/Seoul"
14 ssl_min_protocol_version: TLSv1.2
15 pg_hba:
16 - host all postgres all trust
17 primaryUpdateStrategy: unsupervised
18 enableSuperuserAccess: true
19 bootstrap:
20 initdb:
21 database: app
22 encoding: UTF8
23 localeCType: C
24 localeCollate: C
25 owner: app

Cluster Sample Yaml 참고

https://github.com/cloudnative-pg/cloudnative-pg/blob/main/docs/src/samples/cluster-example-full.yaml
참고

Cluster Sample Init DB Yaml 참고

https://github.com/cloudnative-pg/cloudnative-pg/blob/main/docs/src/samples/cluster-example-initdb.yaml
참고

Cluster Sample Init DB SQL Refs Yaml 참고

https://github.com/cloudnative-pg/cloudnative-pg/blob/main/docs/src/samples/cluster-example-initdb-sql-refs.yaml
참고

[Blog] Chirpy

Wed, 15 Jan 2025 00:00:00 +0000

Linux 환경에서 작업 (아래 중에 하나 선택)

WSL(Windows Subsystem for Linux)
Docker
Mac OS {: .prompt-info }

bundle 실행 전 반드시 ruby Version이 최소 3 Version 이상인지 확인해야 한다.

Ruby 2.x Version인 bundle을 통해 모듈을 설치할 경우
- Chirpy에서 사용하는 모듈과 호환되지 않아 정상적으로 동작하지 않는다.
  - 블로그 기능(Dark Mode, 검색, 이미지 표시, Mobile 환경 비정상 동작 등)
Node.js Version 20 이상 추천한다.
- Node.js Version이 낮을 경우, 몇몇 npm module이 설치가 되지 않을 때가 있다. {: .prompt-tip }

Ruby 설치 #

아래와 같이 설치하면 2.x version이 설치된다.
```
1sudo apt-get install ruby-full
```
```
1ruby -v
```

Ruby 3.x Version 설치 #

1gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

1\curl -sSL https://get.rvm.io | bash -s stable

1rvm install 3.4.1

1ruby -v

Node.js 설치 #

1curl -fsSL https://deb.nodesource.com/setup_23.x -o nodesource_setup.sh

node.js 모듈을 설치하지 않으면 assets/js/dist/*.min.js Not Found 에러 발생과 함께 블로그 기능이 정상적으로 동작하지 않는다. {: .prompt-info }

필요 패키지 설치 #

1gem install bundler

1bundle install

초기화 전에 `git commit` #

1git add .

1git commit -m "chore(release): prepare for version 1.2.3"

Chirpy 초기화 #

1sudo bash tools/init.sh

1git push

[Kubernetes] PostgreSQL SSL Mode 설정

Wed, 08 Jan 2025 00:00:00 +0000

Kubernetes에서 PostgreSQL의 pg_hba.conf 파일에서 SSL 모드를 활성화하려면 다음 단계에 따라 설정할 수 있다.

SSL 인증서 준비 #

SSL 모드를 활성화하려면 PostgreSQL 서버와 클라이언트가 인증서와 개인 키를 설정해야 한다. 보통 다음 파일들이 필요하다:
server.crt: 서버 인증서
server.key: 서버의 개인 키
root.crt: 클라이언트가 신뢰하는 CA 인증서 (optional, 클라이언트 검증용)
인증서 파일을 Kubernetes 비밀(Secret)로 관리하는 것이 일반적이다.

PostgreSQL Docker 이미지에서 SSL 설정 #

PostgreSQL의 Docker 이미지를 사용하고 있다면, postgresql.conf 파일과 pg_hba.conf 파일을 수정하여 SSL을 활성화할 수 있다.
postgresql.conf에서 SSL 활성화:
ssl = on
ssl_cert_file = '/path/to/server.crt'
ssl_key_file = '/path/to/server.key'
ssl_ca_file = '/path/to/root.crt' (옵션)

pg_hba.conf 파일에서 SSL 모드 설정 #

pg_hba.conf 파일에서 SSL 모드를 활성화하려면, hostssl 키워드를 사용하여 SSL 연결만 허용하도록 설정할 수 있다.

1# TYPE DATABASE USER ADDRESS METHOD
2hostssl all all 0.0.0.0/0 md5
3hostssl all all ::/0 md5

이 설정은 모든 IP에서 SSL 연결만 허용하고, md5 인증 방법을 사용하도록 설정한다.

Kubernetes에서 설정 적용하기 #

Kubernetes에서 PostgreSQL Pod의 설정을 수정하려면, ConfigMap 또는 Secret을 사용하여 pg_hba.conf와 SSL 인증서 파일을 제공해야 한다.

ConfigMap 또는 Secret을 사용하여 `pg_hba.conf` 수정 #

Kubernetes ConfigMap 또는 Secret을 생성하여 pg_hba.conf와 postgresql.conf를 제공할 수 있다.

 1apiVersion: v1
 2kind: ConfigMap
 3metadata:
 4 name: postgresql-config
 5data:
 6 pg_hba.conf: |
 7 # TYPE DATABASE USER ADDRESS METHOD
 8 hostssl all all 0.0.0.0/0 md5
 9 hostssl all all ::/0 md5
10 postgresql.conf: |
11 ssl = on
12 ssl_cert_file = '/etc/ssl/certs/server.crt'
13 ssl_key_file = '/etc/ssl/private/server.key'
14 ssl_ca_file = '/etc/ssl/certs/root.crt'

Pod에 SSL 인증서 및 키 파일을 추가 #

server.crt, server.key, root.crt 파일을 Kubernetes Secret으로 생성한다.

1apiVersion: v1
2kind: Secret
3metadata:
4 name: postgresql-ssl-secret
5data:
6 server.crt: <base64-encoded-certificate>
7 server.key: <base64-encoded-private-key>
8 root.crt: <base64-encoded-ca-certificate>

그런 다음 PostgreSQL Pod의 볼륨으로 Secret을 마운트하여 postgresql.conf 및 pg_hba.conf와 함께 사용할 수 있다.

PostgreSQL Pod에 적용 #

pg_hba.conf와 SSL 관련 파일들을 수정한 후, 해당 파일들을 컨테이너 내부에 마운트해야 한다. PostgreSQL 컨테이너의 postgresql.conf 파일과 pg_hba.conf 파일을 수정한 후, 컨테이너를 재시작하여 변경 사항을 적용한다.

 1apiVersion: apps/v1
 2kind: Deployment
 3metadata:
 4 name: postgresql
 5spec:
 6 replicas: 1
 7 template:
 8 metadata:
 9 labels:
10 app: postgresql
11 spec:
12 containers:
13 - name: postgresql
14 image: postgres:latest
15 volumeMounts:
16 - name: postgresql-config-volume
17 mountPath: /etc/postgresql/postgresql.conf
18 subPath: postgresql.conf
19 - name: postgresql-ssl-secret
20 mountPath: /etc/ssl/certs
21 - name: postgresql-config-volume
22 mountPath: /etc/pgsql/pg_hba.conf
23 subPath: pg_hba.conf
24 volumes:
25 - name: postgresql-config-volume
26 configMap:
27 name: postgresql-config
28 - name: postgresql-ssl-secret
29 secret:
30 secretName: postgresql-ssl-secret

Pod 재시작 #

위 설정을 완료한 후, PostgreSQL Pod를 재시작하여 SSL 및 pg_hba.conf 설정이 적용되도록 한다.

1kubectl rollout restart deployment postgresql

이 과정을 통해 Kubernetes에서 PostgreSQL에 SSL을 활성화하고, pg_hba.conf 파일에 hostssl 설정을 추가하여 SSL 연결을 강제할 수 있다.

[Blog] Jekyll Liquid Tag Template

Sun, 29 Dec 2024 00:00:00 +0000

jekyll를 이용해서 만든 github blog에 Markdown 문법을 이용해서 글을 쓴다.
글을 쓰다 보면 예시를 작성하기 위해 {{ }} 과 {% %}를 사용하는 일이 생긴다.
하지만 그대로 작성하면 문제가 생긴다. 그럴 경우에는 다음과 같이 liquid 문법의 raw tag를 사용한다.

작성 방법 #

raw tag를 이용해서 앞뒤로 감싸주면 다음과 같이 Markdown 문법에서 {{ }}, {% %}이 예외 처리가 되어 실행되지 않는다.
```
{% raw %} {{ example }} {% endraw %}
{% raw %} {% example %} {% endraw %}
```

결과 #

{{ example }}
{% example %}

다른 방법 #

Jekyll은 코드 블록 안에서도 Liquid 필터를 처리한다.
코드 앞 뒤를 {% raw %} 와 {% endraw %} Tag로 감싸야 할 것입니다.

Jekyll 4.0 부터, 머리말에 render_with_liquid: false 를 추가해 문서 전체의 Liquid 를 비활성화할 수 있다.

1---
2title: "[Blog] Jekyll Liquid Tag Template"
3date: 2024-12-29
4categories: [Blog, Jekyll]
5tags: [blog, jekyll, liquid, tag, template]
6render_with_liquid: false
7---

Jekyll Liquid 참고

https://jekyllrb-ko.github.io/docs/liquid/tags/ {: .prompt-info }

[DevOps] GitLab Kubernetes Runner: Service Account 권한 에러 해결

Sun, 01 Dec 2024 00:00:00 +0000

🔎 문제 상황 #

Helm 기반으로 GitLab Runner를 설치하면 다음 리소스가 생성됩니다.

Pod, Role, RoleBinding, ServiceAccount
Runner 서비스 어카운트(sa)가 namespace에 생성

예시: gitlab-runner 네임스페이스에 설치된 리소스

kubectl get pod,role,rolebinding,sa -n gitlab-runner

보면 default와 gitlab-runner라는 두 ServiceAccount가 생성됩니다.

🚨 실제 에러 #

CI 파이프라인에서 아래와 같이 kubectl 명령을 실행하면 다음과 같은 에러가 발생합니다.

Error from server (Forbidden): pods "nginx-test" is forbidden:
User "system:serviceaccount:gitlab-runner:default"
cannot get resource "pods" in API group "" in the namespace "gitlab-runner"

즉, Runner가 잘 설치됐지만 잘못된 ServiceAccount를 사용하여 권한이 없어 작업을 수행할 수 없는 상황입니다.

❓ 원인 분석 #

Kubernetes에서 GitLab Runner는 기본적으로 default ServiceAccount를 사용하는데, 이 경우 Runner가 파이프라인에서 필요한 리소스(예: Pod, Secrets)에 대한 권한을 가지지 못합니다.

특히 다음과 같은 CI/CD 작업에서 kubectl apply나 리소스 조회를 할 때 이 문제가 발생합니다.

✅ 해결 방법 #

1) Runner Helm values 파일 설정 #

Helm 설치 시 values.yaml에서 다음 값을 반드시 override해야 합니다.

 1gitlabUrl: "<GITLAB_URL>"
 2runnerToken: "<RUNNER_TOKEN>"
 3rbac:
 4 create: true
 5 rules:
 6 - resources: ["configmaps","events","pods","pods/attach","pods/exec","secrets","services"]
 7 verbs: ["get","list","watch","create","patch","update","delete"]
 8 - apiGroups: [""]
 9 resources: ["pods/exec"]
10 verbs: ["create","patch","delete"]
11 - apiGroups: [""]
12 resources: ["pods/log"]
13 verbs: ["get"]

위 설정으로 Runner가 처리할 리소스에 대한 RBAC 권한을 충분히 부여합니다.

2) ServiceAccount 지정 #

Runner가 사용할 ServiceAccount 이름을 직접 지정해야 합니다.

1runners:
2 config: |
3 [[runners]]
4 [runners.kubernetes]
5 namespace = "{{ .Release.Namespace }}"
6 image = "alpine"
7 privileged = true
8 service_account = "<GITLAB_RUNNER_SA_NAME>"

이렇게 함으로써 Runner가 실제로 생성된 ServiceAccount를 명시적으로 사용하도록 설정합니다.

🧪 실행 예시 #

Helm으로 Runner를 설치할 때 아래처럼 실행합니다.

1helm install --namespace gitlab-runner gitlab-runner \
2 -f values.yaml \
3 gitlab/gitlab-runner

설치 후 파이프라인을 다시 실행하면, Runner가 올바른 ServiceAccount를 이용해 Kubernetes 리소스에 접근합니다.

📌 요약 #

GitLab Runner를 Kubernetes에 설치하면 default ServiceAccount가 기본적으로 선택됩니다.
이 경우 필요한 권한이 없어 kubectl 명령이 실패할 수 있습니다.
해결 방법은:
- RBAC rules로 리소스 권한을 명시적으로 추가
- Runner가 사용할 ServiceAccount를 지정

이 설정이 적용되면 CI 파이프라인에서 kubectl 작업이 정상적으로 실행됩니다.

[Kubernetes] Install Kong Ingress Controller - Gateway API

Sat, 30 Nov 2024 00:00:00 +0000

Helm 설치 및 설명 참고 {: .prompt-info }

Kong Ingress Controller 참고

https://docs.konghq.com/kubernetes-ingress-controller/latest/ {: .prompt-info }

Install the experimental Gateway API CRDs #

1kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/experimental-install.yaml

Install GatewayClass #

1apiVersion: gateway.networking.k8s.io/v1
2kind: GatewayClass
3metadata:
4 name: kong
5 annotations:
6 konghq.com/gatewayclass-unmanaged: 'true'
7
8spec:
9 controllerName: konghq.com/kic-gateway-controller

Install Gateway #

 1apiVersion: gateway.networking.k8s.io/v1
 2kind: Gateway
 3metadata:
 4 name: kong
 5spec:
 6 gatewayClassName: kong
 7 listeners:
 8 - name: proxy
 9 port: 80
10 protocol: HTTP
11 allowedRoutes:
12 namespaces:
13 from: All
14 - name: proxy-ssl
15 port: 443
16 protocol: HTTPS
17 hostname: kong.example.com
18 tls:
19 mode: Terminate
20 certificateRefs:
21 - kind: Secret
22 name: kong-example-com-cert
23 - name: proxy-tcp-9901
24 port: 9901
25 protocol: TCP
26 - name: proxy-udp-9902
27 port: 9902
28 protocol: UDP
29 - name: proxy-tls-9903
30 port: 9903
31 protocol: TLS

Add Kong Helm Chart #

1helm repo add kong https://charts.konghq.com
2helm repo update

Modify Values.yaml #

 1...✂...
 2
 3ingressController:
 4 enabled: true
 5 env:
 6 anonymous_reports: false
 7
 8...✂...
 9
10postgresql:
11 enabled: true
12
13...✂...

Install Kong #

1helm install kong kong/kong -n kong --create-namespace

Enable the Gateway API Alpha feature gate #

1kubectl set env -n kong deployment/kong-controller CONTROLLER_FEATURE_GATES="GatewayAlpha=true" -c ingress-controller

TCP Service #

포트 기반 라우팅: Kong Gateway는 특정 포트에서 수신한 모든 트래픽을 Kubernetes 서비스로 단순히 프록시한다. TCP 연결은 서비스의 모든 사용 가능한 Pods에 걸쳐 로드 밸런싱된다.
SNI 기반 라우팅: Kong Gateway는 지정된 포트에서 TLS 암호화된 스트림을 수락하고, TLS 핸드쉐이크에서 제공되는 SNI를 기준으로 트래픽을 다른 서비스로 라우팅할 수 있다. 또한 Kong Gateway는 TLS 핸드쉐이크를 종료하고 TCP 스트림을 Kubernetes 서비스로 전달한한다.

Patch Deployment kong-gateway #

 1kubectl patch deploy -n kong kong-gateway --patch '{
 2 "spec": {
 3 "template": {
 4 "spec": {
 5 "containers": [
 6 {
 7 "name": "proxy",
 8 "env": [
 9 {
10 "name": "KONG_STREAM_LISTEN",
11 "value": "0.0.0.0:9000, 0.0.0.0:9443 ssl"
12 }
13 ],
14 "ports": [
15 {
16 "containerPort": 9000,
17 "name": "stream9000",
18 "protocol": "TCP"
19 },
20 {
21 "containerPort": 9443,
22 "name": "stream9443",
23 "protocol": "TCP"
24 }
25 ]
26 }
27 ]
28 }
29 }
30 }
31 }'

Patch Service kong kong-gateway-proxy #

 1kubectl patch service -n kong kong-gateway-proxy --patch '{
 2 "spec": {
 3 "ports": [
 4 {
 5 "name": "stream9000",
 6 "port": 9000,
 7 "protocol": "TCP",
 8 "targetPort": 9000
 9 },
10 {
11 "name": "stream9443",
12 "port": 9443,
13 "protocol": "TCP",
14 "targetPort": 9443
15 }
16 ]
17 }
18}'

Create TCP Ingress #

 1echo "apiVersion: configuration.konghq.com/v1beta1
 2kind: TCPIngress
 3metadata:
 4 name: echo-tls
 5 annotations:
 6 kubernetes.io/ingress.class: kong
 7spec:
 8 tls:
 9 - secretName: tls9443.kong.example
10 hosts:
11 - tls9443.kong.example
12 rules:
13 - host: tls9443.kong.example
14 port: 9443
15 backend:
16 serviceName: echo
17 servicePort: 1025

[Kubernetes] Dashboard 설치

Thu, 21 Nov 2024 00:00:00 +0000

📌 1. Kubernetes Dashboard란? #

Kubernetes Dashboard는 클러스터 리소스를 웹 UI로 시각화하고 관리할 수 있는 공식 웹 인터페이스입니다.

주요 기능:

Pod / Deployment / Service 조회
로그 확인
리소스 생성 및 삭제
네임스페이스 관리
RBAC 기반 인증

📦 2. Dashboard 설치 #

공식 manifest를 이용해 설치합니다.

1kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml

🔎 생성되는 주요 리소스 #

Namespace: kubernetes-dashboard
Deployment: kubernetes-dashboard
Deployment: dashboard-metrics-scraper
Service
ServiceAccount
Role / RoleBinding

설치 확인:

1kubectl get all -n kubernetes-dashboard

🌐 3. Dashboard 외부 접속 (NodePort 방식) #

기본적으로 Service 타입은 ClusterIP이므로 외부에서 접근할 수 없습니다.

1️⃣ Service 타입 변경 #

1kubectl edit svc kubernetes-dashboard -n kubernetes-dashboard

아래 부분을 수정합니다.

1spec:
2 type: NodePort
3 ports:
4 - port: 443
5 targetPort: 8443
6 nodePort: 31000

저장 후 확인:

1kubectl get svc -n kubernetes-dashboard

예시 출력:

kubernetes-dashboard NodePort 10.97.112.43 443:31000/TCP

2️⃣ 브라우저 접속 #

https://<NodeIP>:31000

⚠️ Self-signed 인증서이므로 브라우저에서 보안 경고가 발생할 수 있습니다.

🔐 4. 관리자 계정 및 토큰 생성 #

Dashboard는 기본적으로 Token 인증 방식을 사용합니다.

1️⃣ ServiceAccount 생성 #

1apiVersion: v1
2kind: ServiceAccount
3metadata:
4 name: admin-user
5 namespace: kubernetes-dashboard

1kubectl apply -f admin-user.yaml

2️⃣ ClusterRoleBinding 생성 #

 1apiVersion: rbac.authorization.k8s.io/v1
 2kind: ClusterRoleBinding
 3metadata:
 4 name: admin-user
 5roleRef:
 6 apiGroup: rbac.authorization.k8s.io
 7 kind: ClusterRole
 8 name: cluster-admin
 9subjects:
10 - kind: ServiceAccount
11 name: admin-user
12 namespace: kubernetes-dashboard

1kubectl apply -f cluster-role-binding.yaml

3️⃣ 토큰 생성 #

1kubectl -n kubernetes-dashboard create token admin-user

출력된 토큰을 복사하여 Dashboard 로그인 화면에 붙여넣습니다.

⚠️ 5. 자주 발생하는 이슈 #

🔸 1. NET::ERR_CERT_INVALID #

Self-signed 인증서로 인한 브라우저 경고
실서비스 환경에서는 Ingress + TLS 구성 권장

🔸 2. 권한 관련 에러 #

Forbidden 오류 발생 시 RBAC 확인
실 운영 환경에서는 cluster-admin 대신 최소 권한 Role 사용 권장

🔐 보안 관점에서의 주의사항 #

운영 환경에서 반드시 고려해야 할 사항:

❌ NodePort 직접 오픈은 지양
✅ Ingress + 인증서(TLS) 적용
✅ OIDC / SSO 연동 고려
✅ 최소 권한 RBAC 구성

🧠 개발자 관점 정리 #

항목	Dev 환경	운영 환경
Service 타입	NodePort	Ingress
인증	Admin Token	OIDC / SSO
권한	cluster-admin	최소 권한
인증서	Self-signed	공인 TLS

🏁 마무리 #

Kubernetes Dashboard는:

빠르게 클러스터를 시각적으로 확인할 수 있고
리소스 디버깅에 매우 유용하지만
보안 설정 없이 운영 환경에 노출하는 것은 위험합니다.

Dev/Test 환경에서는 빠른 실습용으로, 운영 환경에서는 보안 구성을 충분히 고려하여 사용하세요.

[Python] Python Setup Package

Sat, 19 Oct 2024 00:00:00 +0000

Package Directory 구조 만들기 #

package로 만들기 위해 Directory 구조를 만든다.
프로젝트는 기본적으로 아래와 같은 형태로 구성한다.

1project/
2├── package/
3│ ├── __init__.py
4│ └── module.py
5├── README.md
6└── setup.py

Name	Description
project	프로젝트 root Directory
package	프로젝트의 핵심 Directory. 일반적으로 Package의 이름과 동일하게 지정한다.
init.py	Package를 모듈로 인식하게 만드는 파일. Package가 import될 때 실행된다.
module.py	Package에서 제공하는 기능들이 정의된 Python 모듈 파일. 여러 개의 모듈로 구성할 수도 있으며, 기능별로 파일을 나눌 수 있다.
README.md	프로젝트의 설명 파일
setup.py	PIP 배포를 위한 설정 파일

Package 배포를 위한 의존성 설치 #

손수 만든 Python 프로젝트를 배포하기 위한 몇가지 의존성 Package가 존재한다.
이후 손쉽게 배포하기 위해, 먼저 의존성을 설치해 준다.

1pip install setuptools
2pip install wheel
3pip install twine

Package 설치를 위한 설정 파일 작성 #

Package를 설치 가능하게 만들기 위해 setup.py 파일을 작성한다.

 1from setuptools import setup
 2
 3# README.md 파일을 불러오는 기능
 4with open('README.md', encoding='utf-8') as f:
 5 long_description = f.read()
 6
 7setup(
 8 name='project', # 등록할 Package 이름 (PyPI에 등록되는 이름)
 9 version='0.0.1', # Package 버전
10 description='This is my Python Package.', # Package의 짧은 설명
11 long_description=long_description, # Package의 상세 설명
12 long_description_content_type = 'text/markdown', # long_description의 형식
13 author='author name', # Package 작성자 이름
14 author_email='author email', # Package 작성자 이메일
15 url='https://example.com', # 프로젝트의 공식 URL
16 license='MIT', # Package의 라이선스 정보
17 python_requires='>=3.7', # Package가 지원하는 Python 버전
18 install_requires=[], # Package가 의존하는 외부 라이브러리 목록
19 packages=['package'], # 포함할 Python Package 목록
20 package_data={}, # Package에 포함할 추가 데이터 목록
21 keywords=[], # Package 검색 키워드
22 classifiers=[
23 'Development Status :: 4 - Beta',
24 'Intended Audience :: Developers',
25 'Programming Language :: Python :: 3',
26 'Operating System :: OS Independent',
27 'License :: OSI Approved :: MIT License',
28 ] # Package 분류
29)

Package 배포 #

1python setup.py bdist_wheel

명령어를 실행하면 Package 파일들이 생성된다.

아래 명령어를 통해 PyPI로 배포

1python -m twine upload dist/{배포할 Package 파일}

명령어를 실행하면 아래와 같이 API 토큰을 입력하라고 한다.
API 토큰은 PyPI 사이트에 로그인한 후, Account settings에서 발급받을 수 있다.
```
1Uploading distributions to https://upload.pypi.org/legacy/
2Enter your API token: 
```
이후 올바른 API 토큰을 입력하면 배포가 시작되고, 패키지가 등록된다.

Package 설치 #

Package 설치하려면 Terminal을 열고 Package Directory로 이동한 후 다음 명령어를 실행한다.
```
1pip install .
```
이 명령어를 실행하면 Package가 Local 환경에 설치된다.

Package 사용 #

설치된 Package를 다른 Python Script에서 사용할 수 있다.
```
1from my_package import my_utils
```

[Kubernetes] eBPF로 실시간 커널 레벨 모니터링하기

Thu, 17 Oct 2024 00:00:00 +0000

🔍 eBPF: 개발자 관점에서 보는 커널 레벨 모니터링 #

쿠버네티스 환경에서 성능 분석, 네트워크 모니터링, 보안 트레이싱을 위해 eBPF가 점점 주목받고 있습니다.
개발자 입장에서 이해하면 애플리케이션과 커널 단위를 어떻게 실시간으로 관측하는지 명확해집니다.

1️⃣ eBPF란? #

eBPF = extended Berkeley Packet Filter
리눅스 커널 내부에서 안전하게 코드 실행 가능
원래 패킷 필터링 용도로 시작했지만, 지금은:
- 커널/시스템 이벤트 트레이싱
- 성능 분석
- 네트워크 패킷 모니터링
- 보안 이벤트 감지
즉, 커널 레벨에서 실시간 데이터를 수집하고 분석하는 기술입니다.

2️⃣ 개발자 관점에서 특징 #

커널 레벨 후킹
- Tracepoints, kprobes, uprobes를 사용하여 커널 이벤트나 특정 함수 호출 추적 가능
실시간 분석
- 거의 지연 없이 syscall, 네트워크 패킷, 컨테이너 활동 감지
낮은 오버헤드
- 커널 내부에서 직접 실행되므로, 고성능 모니터링 가능
다양한 활용
- 성능 최적화, 보안 모니터링, 네트워크 분석 등

3️⃣ 활용 사례 #

분야	예시
네트워크	Cilium: Kubernetes 네트워크 정책 + 모니터링
성능 분석	bpftrace: syscall 트레이싱, latency 분석
보안	Falco: 실시간 보안 이벤트 감지
Observability 연계	eBPF → OTel Collector → Grafana/Loki 시각화

eBPF 자체가 데이터 수집/분석용 엔진이고, OTel 같은 Observability 플랫폼과 결합하면 심층 + 통합 관측이 가능합니다.

4️⃣ 설치 & 사용 예시 (간단) #

1# bcc 설치 (Ubuntu)
2sudo apt install bpfcc-tools linux-headers-$(uname -r)
3
4# 간단한 syscall 트레이싱
5sudo execsnoop

bcc/bpftrace 도구를 이용하면 커널 이벤트를 쉽게 추적 가능
Kubernetes에서는 DaemonSet 형태로 eBPF agent 배포 가능 (Cilium, Pixie 등)

5️⃣ 개발자 관점 핵심 포인트 #

데이터 수집 레이어
- 애플리케이션 단위 관측과 달리, 커널/호스트 수준에서 직접 수집
사용 난이도
- 커널 지식이 필요하고, 추적 스크립트 작성이 필요
보완적 사용
- eBPF로 syscall/네트워크 이벤트 수집 → OTel로 통합 시각화 가능
성능 고려
- 실시간 후킹이지만, 너무 과도하게 사용하면 CPU/메모리 오버헤드 발생 가능

6️⃣ 요약 #

항목	내용
이름	eBPF (extended Berkeley Packet Filter)
역할	커널 레벨 실시간 트레이싱, 성능/보안/네트워크 모니터링
배포	Host Agent, Kubernetes DaemonSet 형태 가능
장점	거의 실시간, 커널 레벨 데이터, 오버헤드 낮음
개발자 포인트	심층 분석용, Observability 플랫폼과 결합 시 최적 활용 가능

💡 한 줄 기억:

eBPF = “커널/호스트 단위 실시간 모니터링·트레이싱 엔진”

eBPF는 네트워크 패킷 필터링에서 시작하여, 보안, 성능 모니터링, 트레이싱 등 다양한 영역에 걸쳐 커널과 사용자 공간 사이의 경계를 허물며 중요한 역할을 하고 있다.
이를 통해 시스템 관리자와 개발자들은 커널의 복잡한 부분을 안전하고 효율적으로 제어할 수 있으며, 다양한 문제를 실시간으로 해결할 수 있다.

[Kubernetes] Install Kubernetes(v1.29.x) on Multipass

Tue, 15 Oct 2024 00:00:00 +0000

Multipass 설명 참고 {: .prompt-info }

cloud-init yaml 구성 #

master.yaml #

 1package_update: true
 2package_upgrade: true
 3packages:
 4 - docker.io
 5 - apt-transport-https
 6 - ca-certificates
 7 - curl
 8 - ntpdate
 9
10runcmd:
11 - sudo swapoff -a
12 - sudo ntpdate ntp.ubuntu.com
13 - sudo systemctl enable containerd
14 - sudo systemctl start containerd
15 - sudo mkdir -p /etc/apt/keyrings
16 - curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
17 - echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list
18 - sudo apt update
19 - sudo apt install -y kubelet kubeadm kubectl
20 - sudo apt-mark hold kubelet kubeadm kubectl
21 - sudo systemctl enable kubelet
22 - sudo kubeadm init
23 - mkdir -p /home/ubuntu/.kube
24 - sudo cp -i /etc/kubernetes/admin.conf /home/ubuntu/.kube/config
25 - sudo chown -R ubuntu:ubuntu /home/ubuntu/.kube
26 - sudo kubeadm token create --print-join-command > /home/ubuntu/kubeadm_join_cmd.sh
27 - sudo chown ubuntu:ubuntu /home/ubuntu/kubeadm_join_cmd.sh
28 - chmod +x /home/ubuntu/kubeadm_join_cmd.sh
29 - |
30 sudo bash -c 'cat <<EOF > /home/ubuntu/k8s-post-init.sh
31 #!/bin/bash
32 export KUBECONFIG=/home/ubuntu/.kube/config
33 sleep 60
34 kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
35 kubectl taint nodes --all node-role.kubernetes.io/control-plane-
36 EOF'
37 - sudo chown ubuntu:ubuntu /home/ubuntu/k8s-post-init.sh
38 - sudo chmod +x /home/ubuntu/k8s-post-init.sh
39 - sudo -u ubuntu /home/ubuntu/k8s-post-init.sh

kubeadm 세부 설정 참고 #

pod 네트워크 CIDR 설정
- Calico 기반 구축
  - pod-network-cidr=192.168.0.0/16
- Flannel 기반 구축
  - pod-network-cidr=10.244.0.0/16
- Cilium 기반 구축
  - pod-network-cidr=10.0.0.0/8

1sudo kubeadm init --pod-network-cidr=10.244.0.0/12 --apiserver-advertise-address=192.168.0.55

--pod-network-cidr : pod 간 통신할 IP 주소를 지정
--apiserver-advertise-address : Control-plane의 api-server가 사용할 IP 주소. 지정하지 않으면 default network interface 주소를 사용
--service-cidr : Cluster 내에서 Application 간 통신을 위해 사용되며, 고유한 IP 주소를 가지게 된다. 기본값으로 10.96.0.0/12을 가진다.
--pod-network-cidr 과 --service-cidr 주소를 겹치지 않게 설정. 겹칠 경우 Kubernetes가 중복되지 않게 배치함

worker.yaml #

 1package_update: true
 2package_upgrade: true
 3packages:
 4 - docker.io
 5 - apt-transport-https
 6 - ca-certificates
 7 - curl
 8 - ntpdate
 9
10runcmd:
11 - sudo swapoff -a
12 - sudo ntpdate ntp.ubuntu.com
13 - sudo systemctl enable containerd
14 - sudo systemctl start containerd
15 - sudo mkdir -p /etc/apt/keyrings
16 - curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
17 - echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list
18 - sudo apt update
19 - sudo apt install -y kubelet kubeadm kubectl
20 - sudo systemctl enable kubelet

Instance 생성 #

1multipass launch focal --name mp-master --memory 4G --disk 50G --cpus 2 --cloud-init mp-master.yaml
2multipass launch focal --name mp-master --memory 4G --disk 50G --cpus 2 --network name=multipass,mode=manual
3
4multipass launch focal --name mp-worker-1 --memory 4G --disk 50G --cpus 2 --cloud-init mp-worker.yaml
5multipass launch focal --name mp-worker-1 --memory 4G --disk 50G --cpus 2 --network name=multipass,mode=manual
6
7multipass launch focal --name mp-worker-2 --memory 4G --disk 50G --cpus 2 --cloud-init mp-worker.yaml
8multipass launch focal --name mp-worker-2 --memory 4G --disk 50G --cpus 2 --network name=multipass,mode=manual

Network - Static IP #

Network for Windows #

관리자 권한 파워쉘에서 실행.

1# 고정된 Switch와 인터넷 통신을 위한 NAT 를 생성한다. 172.16.0.1/16
2New-VMSwitch -SwitchName "MySwitch" -SwitchType Internal
3New-NetIPAddress -IPAddress 172.16.0.1 -PrefixLength 16 -InterfaceAlias "vEthernet (MySwitch)"
4New-NetNat -Name "NATNetwork" -InternalIPInterfaceAddressPrefix "172.16.0.1/16"
5
6# mutipass launch 시 network 를 추가한다.
7multipass launch -n mp-master -c 2 -m 2G -d 20G --network name=MySwitch focal

생성한 VM 접속하여 아래와 같이 설정 및 추가

1sudo vi /etc/netplan/50-cloud-init.yaml

 1network:
 2 ethernets:
 3 eth0:
 4 dhcp4: true
 5 match:
 6 macaddress: 52:54:00:f1:f0:e8
 7 set-name: eth0
 8--- 추가
 9 eth1:
10 addresses: [192.168.0.55/24]
11 routes:
12 - to: default
13 via: 192.168.0.1
14 nameservers:
15 addresses: [8.8.8.8, 1.1.1.1]
16---
17 version: 2

--network name=multipass,mode=manual

 1network:
 2 ethernets:
 3 eth0:
 4 dhcp4: true
 5 dhcp6: true
 6 match:
 7 macaddress: 52:54:00:80:6b:21
 8 set-name: eth0
 9--- 추가
10 eth1:
11 addresses: [192.168.0.55/24]
12 gateway4: 192.168.0.1
13 dhcp4: no
14---
15 version: 2

--network name=multipass

 1network:
 2 ethernets:
 3 default:
 4 dhcp4: true
 5 match:
 6 macaddress: 52:54:00:25:1d:ab
 7 extra0:
 8 dhcp4: true
 9 dhcp4-overrides:
10 route-metric: 200
11 match:
12 macaddress: 52:54:00:09:13:61
13 optional: true
14
15--- 추가
16 eth1:
17 addresses: [192.168.0.55/24]
18 gateway4: 192.168.0.1
19 dhcp4: no
20---
21 version: 2

worker Node에도 추가

 1network:
 2 ethernets:
 3 eth0:
 4 dhcp4: true
 5 dhcp6: true
 6 match:
 7 macaddress: 52:54:00:80:6b:21
 8 set-name: eth0
 9--- 추가
10 eth1:
11 addresses: [192.168.0.56/24]
12 gateway4: 192.168.0.1
13 dhcp4: no
14---
15 version: 2

Restart Network #

아래와 같이 network 적용 또는 instance를 재시작
```
1sudo netplan apply
```

Network for MacOS #

Mac Terminal에서 아래와 같이 설정 및 추가

 1sudo vi /var/db/dhcpd_leases
 2
 3{
 4 name=mp-master
 5 ip_address=192.168.64.55
 6 hw_address=ff,f1:f5:dd:7f:0:2:0:0:ab:11:fa:4c:c0:e7:17:a6:ae:9a
 7 identifier=ff,f1:f5:dd:7f:0:2:0:0:ab:11:fa:4c:c0:e7:17:a6:ae:9a
 8 lease=0x671d9fc1
 9}
10{
11 name=mp-worker-1
12 ip_address=192.168.64.56
13 hw_address=ff,f1:f5:dd:7f:0:2:0:0:ab:11:50:ed:1b:91:59:3e:45:b4
14 identifier=ff,f1:f5:dd:7f:0:2:0:0:ab:11:50:ed:1b:91:59:3e:45:b4
15 lease=0x671daf7a
16}

Restart Instance #

1multipass restart mp-master
2multipass restart mp-worker-1

Add Cluster Node : Join #

kubeadm_join_cmd.sh 파일 받아서 worker로 전송

1multipass transfer mp-master:/home/ubuntu/kubeadm_join_cmd.sh ./
2multipass transfer kubeadm_join_cmd.sh mp-worker-1:/home/ubuntu
3multipass transfer kubeadm_join_cmd.sh mp-worker-2:/home/ubuntu

각 worker 접속하여 join
```
1sudo ./kubeadm_join_cmd.sh
```

[Flutter] RootTab

Sun, 15 Sep 2024 00:00:00 +0000

RootTab #

정의: 일반적으로 “RootTab"은 여러 개의 탭을 상단에 배치하여 사용자가 여러 화면을 쉽게 전환할 수 있게 하는 UI 구성 요소를 의미한다.
구성: 각 탭은 사용자가 선택할 수 있는 특정 항목을 나타낸다. 이 탭은 일반적으로 TabBar 위젯을 통해 생성된다.

TabBarView #

정의: TabBarView는 TabBar와 함께 사용되는 위젯으로, 각 탭에 해당하는 내용을 표시한다.
구성: TabBarView는 여러 개의 자식 위젯을 받아서 각 탭이 선택될 때 보여줄 내용을 정의한다. 각 탭에 대해 해당하는 콘텐츠를 작성할 수 있다.

설명 참고 {: .prompt-info }

Flutter 프로젝트 생성 #

1코드 복사
2flutter create my_app
3cd my_app

필요한 패키지 추가 #

기본적으로 material.dart만 있으면 충분하다.
추가적인 패키지는 필요하지 않다.

기본 UI 구성 #

lib/main.dart 파일을 열고 아래의 코드를 작성한다.

 1import 'package:flutter/material.dart';
 2
 3void main() {
 4 runApp(MyApp());
 5}
 6
 7class MyApp extends StatelessWidget {
 8 @override
 9 Widget build(BuildContext context) {
10 return MaterialApp(
11 title: 'Flutter Tab Example',
12 home: HomeScreen(),
13 );
14 }
15}
16
17class HomeScreen extends StatelessWidget {
18 @override
19 Widget build(BuildContext context) {
20 return DefaultTabController(
21 length: 3, // 탭의 개수
22 child: Scaffold(
23 appBar: AppBar(
24 title: Text('Root Tab Example'),
25 bottom: TabBar(
26 tabs: [
27 Tab(text: 'Tab 1'),
28 Tab(text: 'Tab 2'),
29 Tab(text: 'Tab 3'),
30 ],
31 ),
32 ),
33 body: TabBarView(
34 children: [
35 Center(child: Text('Content for Tab 1')),
36 Center(child: Text('Content for Tab 2')),
37 Center(child: Text('Content for Tab 3')),
38 ],
39 ),
40 ),
41 );
42 }
43}

코드 설명 #

기본 구조 #

main() 함수: 애플리케이션의 진입점이다. runApp(MyApp())를 통해 Flutter 앱을 실행한다.
MyApp 클래스: MaterialApp 위젯으로 앱의 기본적인 스타일을 제공한다.

HomeScreen 클래스 #

DefaultTabController: 탭을 관리하는 컨트롤러로, 탭의 개수를 length 속성으로 지정한다.
Scaffold: 앱의 기본 레이아웃을 제공하는 위젯이다.
AppBar: 상단에 위치하며, 앱의 제목과 TabBar를 포함한다. TabBar는 각각의 탭을 정의한다.
TabBar: 각 탭을 표시하는 위젯으로, Tab 위젯을 리스트로 포함한다. 여기서는 3개의 탭을 정의했다.
TabBarView: 각 탭에 대한 내용을 표시하는 위젯이다. children 속성에는 각 탭에 맞는 위젯을 포함한다. 여기서는 각 탭에 대한 간단한 텍스트를 사용했다.

실행하기 #

1flutter run

탭 사용하기 #

앱이 실행되면 상단에 3개의 탭이 표시된다.
각 탭을 클릭하면 해당하는 내용이 아래에 표시된다.
이로써 기본적인 Root Tab 구성이 완료되었다.

추가 기능 #

탭 아이콘 추가: 각 탭에 아이콘을 추가할 수 있다.
```
1Tab(icon: Icon(Icons.home), text: 'Tab 1'),
```
탭 간 전환 애니메이션: 기본적으로 Flutter에서 제공하는 전환 애니메이션을 사용하여 사용자 경험을 향상시킬 수 있다.
상태 관리: 탭 간의 상태를 유지하기 위해 상태 관리 라이브러리(예: Provider, Riverpod)를 사용할 수 있다.

[Flutter] TabBarView

Thu, 12 Sep 2024 00:00:00 +0000

RootTab #

정의: 일반적으로 “RootTab"은 여러 개의 탭을 상단에 배치하여 사용자가 여러 화면을 쉽게 전환할 수 있게 하는 UI 구성 요소를 의미한다.
구성: 각 탭은 사용자가 선택할 수 있는 특정 항목을 나타낸다. 이 탭은 일반적으로 TabBar 위젯을 통해 생성된다.

설명 참고 {: .prompt-info }

TabBarView #

정의: TabBarView는 TabBar와 함께 사용되는 위젯으로, 각 탭에 해당하는 내용을 표시한다.
구성: TabBarView는 여러 개의 자식 위젯을 받아서 각 탭이 선택될 때 보여줄 내용을 정의한다. 각 탭에 대해 해당하는 콘텐츠를 작성할 수 있다.

TabBarView 정의 #

TabBarView는 여러 개의 자식 위젯을 받아서 각 탭이 선택될 때 보여줄 내용을 정의한다.
이 위젯은 TabBar와 함께 사용되어 탭 인터페이스를 구성한다.

기본 구조 #

TabBarView의 기본적인 구조는 다음과 같다.

1TabBarView(
2 children: [
3 // 각 탭에 해당하는 위젯
4 Center(child: Text('Content for Tab 1')),
5 Center(child: Text('Content for Tab 2')),
6 Center(child: Text('Content for Tab 3')),
7 ],
8)

주요 속성 #

children: TabBarView에서 표시할 위젯들의 리스트이다. 각 탭에 해당하는 콘텐츠를 포함한다.

사용 예시 #

아래는 TabBar와 TabBarView를 함께 사용한 기본적인 예시이다.

 1import 'package:flutter/material.dart';
 2
 3void main() {
 4 runApp(MyApp());
 5}
 6
 7class MyApp extends StatelessWidget {
 8 @override
 9 Widget build(BuildContext context) {
10 return MaterialApp(
11 title: 'TabBarView Example',
12 home: DefaultTabController(
13 length: 3, // 탭의 개수
14 child: Scaffold(
15 appBar: AppBar(
16 title: Text('TabBarView Example'),
17 bottom: TabBar(
18 tabs: [
19 Tab(text: 'Tab 1'),
20 Tab(text: 'Tab 2'),
21 Tab(text: 'Tab 3'),
22 ],
23 ),
24 ),
25 body: TabBarView(
26 children: [
27 Center(child: Text('Content for Tab 1')),
28 Center(child: Text('Content for Tab 2')),
29 Center(child: Text('Content for Tab 3')),
30 ],
31 ),
32 ),
33 ),
34 );
35 }
36}

코드 설명 #

DefaultTabController: TabBar와 TabBarView의 상태를 관리한다. length 속성은 탭의 개수를 설정한다.
TabBar: 상단에 표시되는 탭으로, 사용자가 선택할 수 있는 각 항목을 나타낸다.
TabBarView: children 리스트에 포함된 각 위젯이 탭 선택에 따라 표시된다. 각 탭에 대한 콘텐츠를 정의할 수 있다.

탭 전환 애니메이션 #

TabBarView는 기본적으로 탭 간 전환 애니메이션을 제공한다.
사용자가 탭을 클릭할 때마다 애니메이션 효과가 자동으로 적용되어 부드러운 전환을 경험할 수 있다.

상태 관리 #

탭 간의 상태를 유지하고 싶다면, 각 탭에서 상태를 관리하는 방식
- 예: StatefulWidget, Provider, Riverpod 등을 사용할 수 있다.
- 예를 들어, 각 탭에 대한 상태를 관리하는 별도의 StatefulWidget을 만들 수도 있다.

스크롤 가능한 TabBarView #

대량의 콘텐츠를 다룰 경우 TabBarView를 스크롤 가능하도록 설정할 수 있다.
- 예를 들어, SingleChildScrollView와 함께 사용할 수 있다.

[Flutter] Drawer

Tue, 10 Sep 2024 00:00:00 +0000

기본 Flutter 프로젝트 설정 #

Flutter 프로젝트를 생성하고 필요한 패키지를 추가
```
1flutter create my_app
2cd my_app
```

Drawer 추가 #

lib/main.dart 파일 수정

이제 lib/main.dart 파일을 열어 기본적인 UI를 구성한다. 아래의 코드를 추가

 1import 'package:flutter/material.dart';
 2
 3void main() {
 4 runApp(MyApp());
 5}
 6
 7class MyApp extends StatelessWidget {
 8 @override
 9 Widget build(BuildContext context) {
10 return MaterialApp(
11 title: 'Flutter Drawer Demo',
12 home: HomeScreen(),
13 );
14 }
15}

main() 함수: Flutter 애플리케이션의 진입점이다. runApp() 함수를 호출하여 위젯 트리를 시작한다.
MyApp 클래스: 애플리케이션의 루트 위젯을 정의한다. MaterialApp 위젯을 사용하여 기본적인 Material Design 스타일을 제공한다.

HomeScreen 클래스 추가 #

다음으로, HomeScreen 클래스를 추가하여 Drawer를 포함한 화면을 정의

 1class HomeScreen extends StatelessWidget {
 2 @override
 3 Widget build(BuildContext context) {
 4 return Scaffold(
 5 appBar: AppBar(
 6 title: Text('Drawer Example'),
 7 ),
 8 drawer: Drawer(
 9 child: ListView(
10 padding: EdgeInsets.zero,
11 children: <Widget>[
12 DrawerHeader(
13 child: Text(
14 'Drawer Header',
15 style: TextStyle(
16 color: Colors.white,
17 fontSize: 24,
18 ),
19 ),
20 decoration: BoxDecoration(
21 color: Colors.blue,
22 ),
23 ),
24 ListTile(
25 leading: Icon(Icons.home),
26 title: Text('Home'),
27 onTap: () {
28 Navigator.pop(context); // Drawer 닫기
29 },
30 ),
31 ListTile(
32 leading: Icon(Icons.settings),
33 title: Text('Settings'),
34 onTap: () {
35 Navigator.pop(context); // Drawer 닫기
36 },
37 ),
38 ListTile(
39 leading: Icon(Icons.info),
40 title: Text('About'),
41 onTap: () {
42 Navigator.pop(context); // Drawer 닫기
43 },
44 ),
45 ],
46 ),
47 ),
48 body: Center(
49 child: Text('Home Screen'),
50 ),
51 );
52 }
53}

Scaffold 구성 요소 설명 #

Scaffold: Flutter에서 기본적인 레이아웃 구조를 제공하는 위젯이다. appBar, drawer, body 등의 속성을 사용하여 앱의 구조를 설정한다.
AppBar: 화면 상단에 위치하며, 앱의 제목이나 액션 버튼을 포함할 수 있다. 여기서는 “Drawer Example"이라는 제목을 표시한다.
Drawer: 왼쪽에서 슬라이드 방식으로 열리는 사이드 메뉴이다. 이 안에 여러 개의 ListTile을 배치하여 메뉴 항목을 나열한다.
ListView: 스크롤 가능한 리스트를 생성한다. padding: EdgeInsets.zero를 통해 기본 패딩을 제거한다.
DrawerHeader: 드로어의 헤더 부분으로, 주로 사용자 프로필이나 앱 이름 등을 표시한다. 배경색과 텍스트 스타일을 설정할 수 있다.
ListTile: 각 메뉴 항목을 구성하는 위젯이다. leading 속성을 사용하여 아이콘을 추가하고, title 속성으로 텍스트를 설정한다. onTap 속성에는 해당 항목을 클릭했을 때 실행될 동작을 정의한다. 여기서는 Drawer를 닫기 위해 Navigator.pop(context)를 사용한다.

실행 #

1코드 복사
2flutter run

Drawer 열기 #

앱이 실행되면, 화면의 왼쪽 상단에 있는 아이콘을 클릭하면 Drawer가 열린다.
Drawer 안에는 Home, Settings, About라는 항목이 표시된다.
각 항목을 클릭하면 Navigator.pop(context)에 의해 Drawer가 닫힌다.

추가 기능 #

항목 클릭 시 페이지 전환: 각 ListTile의 onTap에서 페이지를 전환하도록 추가적인 코드를 작성할 수 있다.
- 예를 들어, 새로운 화면으로 이동할 수 있다.
상태 관리: 복잡한 앱에서는 Drawer의 상태를 관리하기 위해 상태 관리 라이브러리를 사용할 수 있다.

[Android] SDK Manager

Sat, 07 Sep 2024 00:00:00 +0000

SDK Manager #

Android 개발에 필요한 소프트웨어 개발 키트(Software Development Kit) 및 관련 도구, 플랫폼 및 시스템 이미지를 설치하고 관리하는 도구

주요 기능 #

SDK 및 도구 설치

Android SDK Manager를 통해 Android 버전에 맞는 SDK 플랫폼, 빌드 도구, 플랫폼 도구, 시스템 이미지 등을 다운로드하고 설치할 수 있다.

라이브러리 및 추가 컴포넌트 관리

필요한 라이브러리, 추가 도구, 시스템 이미지 등을 SDK Manager를 통해 쉽게 관리할 수 있다.

SDK 버전 및 플랫폼 업데이트

새로운 Android 버전이나 플랫폼 도구가 출시되면 SDK Manager를 통해 업데이트를 받고 새로운 기능 및 개선 사항을 활용할 수 있다.

가상 디바이스 생성 및 관리

SDK Manager를 사용하여 가상 디바이스에 사용할 수 있는 다양한 시스템 이미지를 설치하고 관리할 수 있다.

라이선스 관리

Android SDK Manager를 통해 필요한 라이선스를 수락하고 관리할 수 있다. 명령행 도구로도 사용 가능하며, 명령행에서는 sdkmanager를 사용한다.

안드로이드 스튜디오와의 통합

Android SDK Manager는 주로 안드로이드 스튜디오(Android Studio)와 함께 사용되며, 스튜디오에서도 SDK 관리 기능이 일부 내장되어 있다.

Android SDK 설치 #

Andriod Studio 실행
More Actions ➡️ SDK Manager
Edit
SDK Components Setup
Andriod SDK
Android SDK Platform
Android API 34(Version)

cmdline tools 설치 #

Andriod Studio 실행
More Actions ➡️ SDK Manager
SDK Tools
Android SDK Command-line Tools

이 도구가 있어야 CLI (명령어)로 설정을 할 수 있다. {: .prompt-warning }

1flutter doctor --android-licenses

[Flutter] Google Login

Thu, 29 Aug 2024 00:00:00 +0000

Flutter 프로젝트 설정 #

1flutter create my_project
2cd my_project

Firebase 설정 #

Firebase Console에 가서 새 프로젝트를 생성한다.
안드로이드 앱을 추가한다.
패키지 이름을 입력합니다. - 예: com.example.my_project
google-services.json 파일을 다운로드한다.
다운로드한 google-services.json 파일을 android/app Directory에 추가한다.

Dependencies 추가 #

pubspec.yaml 파일을 열고 google_sign_in과 firebase_auth 패키지를 추가한다.

1dependencies:
2 flutter:
3 sdk: flutter
4 google_sign_in: ^6.1.0
5 firebase_auth: ^4.5.0
6 firebase_core: ^2.16.0

그런 다음, 패키지를 설치한다.
```
1flutter pub get
```

Android 설정 #

android/build.gradle 파일을 열고 classpath에 Google 서비스 플러그인을 추가한다.

1buildscript {
2 dependencies {
3 ...✂...
4 classpath 'com.google.gms:google-services:4.3.15' // 최신 버전 확인
5 }
6}

그 다음 android/app/build.gradle 파일을 열고 아래를 추가한다.

1apply plugin: 'com.google.gms.google-services'
2
3android {
4 ...✂...
5 defaultConfig {
6 ...✂...
7 minSdkVersion 21
8 }
9}

Firebase 초기화 #

lib/main.dart 파일을 열고 Firebase를 초기화한다.

 1import 'package:flutter/material.dart';
 2import 'package:firebase_core/firebase_core.dart';
 3import 'package:google_sign_in/google_sign_in.dart';
 4import 'package:firebase_auth/firebase_auth.dart';
 5
 6void main() async {
 7 WidgetsFlutterBinding.ensureInitialized();
 8 await Firebase.initializeApp();
 9 runApp(MyApp());
10}
11
12class MyApp extends StatelessWidget {
13 @override
14 Widget build(BuildContext context) {
15 return MaterialApp(
16 home: SignInScreen(),
17 );
18 }
19}

Google 로그인 기능 구현 #

SignInScreen 클래스를 추가하여 Google 로그인 기능을 구현한다.

 1class SignInScreen extends StatelessWidget {
 2 final GoogleSignIn googleSignIn = GoogleSignIn();
 3 final FirebaseAuth firebaseAuth = FirebaseAuth.instance;
 4
 5 Future<User?> _signInWithGoogle() async {
 6 final GoogleSignInAccount? googleUser = await googleSignIn.signIn();
 7 final GoogleSignInAuthentication? googleAuth = await googleUser?.authentication;
 8
 9 final AuthCredential credential = GoogleAuthProvider.credential(
10 accessToken: googleAuth?.accessToken,
11 idToken: googleAuth?.idToken,
12 );
13
14 UserCredential userCredential = await firebaseAuth.signInWithCredential(credential);
15 return userCredential.user;
16 }
17
18 @override
19 Widget build(BuildContext context) {
20 return Scaffold(
21 appBar: AppBar(title: Text("Google Sign In")),
22 body: Center(
23 child: ElevatedButton(
24 onPressed: () async {
25 User? user = await _signInWithGoogle();
26 if (user != null) {
27 print("로그인 성공: ${user.displayName}");
28 }
29 },
30 child: Text("Google로 로그인"),
31 ),
32 ),
33 );
34 }
35}

권한 설정 #

AndroidManifest.xml 파일에 인터넷 권한을 추가한다.

1<uses-permission android:name="android.permission.INTERNET"/>

[Kubernetes] Deploy MinIO

Mon, 26 Aug 2024 00:00:00 +0000

Create MinIO Object #

1curl https://raw.githubusercontent.com/minio/docs/master/source/extra/examples/minio-dev.yaml -O

 1# Deploys a new Namespace for the MinIO Pod
 2apiVersion: v1
 3kind: Namespace
 4metadata:
 5 name: minio-dev # Change this value if you want a different namespace name
 6 labels:
 7 name: minio-dev # Change this value to match metadata.name
 8---
 9# Deploys a new MinIO Pod into the metadata.namespace Kubernetes namespace
10#
11# The `spec.containers[0].args` contains the command run on the pod
12# The `/data` directory corresponds to the `spec.containers[0].volumeMounts[0].mountPath`
13# That mount path corresponds to a Kubernetes HostPath which binds `/data` to a local drive or volume on the worker node where the pod runs
14# 
15apiVersion: v1
16kind: Pod
17metadata:
18 labels:
19 app: minio
20 name: minio
21 namespace: minio-dev # Change this value to match the namespace metadata.name
22spec:
23 containers:
24 - name: minio
25 image: quay.io/minio/minio:latest
26 command:
27 - /bin/bash
28 - -c
29 args: 
30 - minio server /data --console-address :9001
31 volumeMounts:
32 - mountPath: /data
33 name: localvolume # Corresponds to the `spec.volumes` Persistent Volume
34 nodeSelector:
35 kubernetes.io/hostname: kubealpha.local # Specify a node label associated to the Worker Node on which you want to deploy the pod.
36 volumes:
37 - name: localvolume
38 hostPath: # MinIO generally recommends using locally-attached volumes
39 path: /mnt/disk1/data # Specify a path to a local drive or volume on the Kubernetes worker node
40 type: DirectoryOrCreate # The path to the last directory must exist

minio 설치 참고

https://min.io/docs/minio/kubernetes/upstream/index.html {: .prompt-info }

Apply the MinIO Object Definition #

The following command applies the minio-dev.yaml configuration and deploys the objects to Kubernetes:

1kubectl apply -f minio-dev.yaml

The command output should resemble the following:

namespace/minio-dev created
pod/minio created

You can verify the state of the pod by running kubectl get pods:

kubectl get pods -n minio-dev

The output should resemble the following:

NAME READY STATUS RESTARTS AGE
minio 1/1 Running 0 77s

You can also use the following commands to retrieve detailed information on the pod status:

kubectl describe pod/minio -n minio-dev

kubectl logs pod/minio -n minio-dev

Temporarily Access the MinIO S3 API and Console #

Use the kubectl port-forward command to temporarily forward traffic from the MinIO pod to the local machine:

kubectl port-forward pod/minio 9000 9090 -n minio-dev

The command forwards the pod ports 9000 and 9090 to the matching port on the local machine while active in the shell. The kubectl port-forward command only functions while active in the shell session. Terminating the session closes the ports on the local machine.

Note The following steps of this procedure assume an active kubectl port-forward command. To configure long term access to the pod, configure Ingress or similar network control components within Kubernetes to route traffic to and from the pod. Configuring Ingress is out of the scope for this documentation.

Connect your Browser to the MinIO Server #

Access the MinIO Console by opening a browser on the local machine and navigating to http://127.0.0.1:9001.

[Flutter] SDK

Sat, 24 Aug 2024 00:00:00 +0000

Google에서 개발한 오픈 소스 프레임워크로, 모바일 앱뿐만 아니라 웹 및 데스크톱 앱까지 다양한 플랫폼에서 동작하는 크로스 플랫폼 앱을 개발하는 도구

SDK (Software Development Kit) : 소프트웨어 개발 키트 #

특정한 소프트웨어를 개발하기 위해 필요한 도구, 라이브러리, 문서, 샘플 코드 등이 포함된 패키지이다.

Flutter SDK 특징 #

Dart 언어:

플러터 앱을 개발하기 위한 주 언어는 Dart. Dart는 간결하고 생산적인 언어로, 플러터 앱의 비즈니스 로직과 UI를 함께 다룰 수 있다.

위젯:

플러터는 위젯을 기반으로 하는 UI 개발을 지원한다. 위젯은 화면에 표시되는 모든 것을 나타내며, 텍스트, 버튼, 이미지 등 다양한 형태의 위젯을 조합하여 UI를 구성할 수 있다.

호환성:

플러터는 iOS와 Android뿐만 아니라 웹 및 데스크톱 플랫폼에도 빌드할 수 있는 크로스 플랫폼 개발을 지원한다. 이는 개발자가 하나의 코드베이스로 여러 플랫폼에서 동일한 앱을 실행할 수 있도록 해준다.

빠른 개발:

플러터는 Hot Reload 기능을 제공하여 앱의 변경 사항을 실시간으로 반영하고 테스트할 수 있다. 이는 빠른 개발 주기를 지원하여 생산성을 향상시킨다.

Material Design 및 Cupertino 스타일:

플러터는 Material Design(Android) 및 Cupertino(iOS)와 호환되는 미리 디자인된 스타일과 위젯을 제공하여 각 플랫폼의 네이티브한 룩앤필을 쉽게 구현할 수 있다.

다양한 패키지 및 플러그인:

플러터는 다양한 패키지와 플러그인을 제공하여 네트워크 통신, 데이터베이스 연동, 상태 관리 등 다양한 기능을 쉽게 추가할 수 있다.

Install Flutter

https://docs.flutter.dev/get-started/install {: .prompt-info }

flutter 시스템 환경 변수 설정 #

시스템 환경 변수 편집
[환경 변수]
시스템 변수
Path
[편집]
[새로 만들기]
~/설치경로/flutter/bin (입력)
[확인]

flutter doctor 실행하기 #

flutter doctor? #

개발 환경의 설정 및 필수 구성 요소를 검사하고 문제를 해결하는 데 도움을 주는 명령어

📂~/설치경로/flutter/bin #

cd ~/설치경로/flutter/bin

1flutter doctor

 1Doctor summary (to see all details, run flutter doctor -v):
 2[√] Flutter (Channel stable, 3.24.0, on Microsoft Windows [Version 10.0.22631.4169], locale ko-KR)
 3[√] Windows Version (Installed version of Windows is version 10 or higher)
 4[!] Android toolchain - develop for Android devices (Android SDK version 35.0.0)
 5 ! Some Android licenses not accepted. To resolve this, run: flutter doctor --android-licenses
 6[√] Chrome - develop for the web
 7[X] Visual Studio - develop Windows apps
 8 X Visual Studio not installed; this is necessary to develop Windows apps.
 9 Download at https://visualstudio.microsoft.com/downloads/.
10 Please install the "Desktop development with C++" workload, including all of its default components
11[!] Android Studio (version 2022.2)
12 X Unable to find bundled Java version.
13[√] Android Studio (version 2024.1)
14[√] VS Code (version 1.92.2)
15[√] Connected device (3 available)
16[√] Network resources
17
18! Doctor found issues in 3 categories.

❌ 표시로 나오는 부분은 추가로 설치할 항목이 필요하거나 설정이 필요한 내용 #

❌ cmdline-tools component is missing.
- ➡️cmdline-tools 라는 플러그인 설치가 필요합니다.
❌ Anroid license status unknown.
- ➡️안드로이드 관련 라이센스 동의가 필요합니다.
  
  명령어를 입력하여 라이센스 동의를 하라고 알려주고 있는데, 먼저 명령어를 사용하기 위해서는 cmdline-tools 라는 플러그인이 설치되어야 명령어를 사용할 수 있다. {: .prompt-info }
❌ Visual Studio not installed: this is necessary to develop Windows apps
- ➡️Visual Studio 개발 앱이 설치되어 있지 않다. (Visual Studio를 사용하지 않는다면, 무시해도 좋다. cf. VS Code 와 다르다.)

Andriod 라이센스 승인 #

1flutter doctor --andriod-licenses

Android sdkmanager not found. Update to the latest Android SDK and ensure that the cmdline-tools are installed to resolve this. {: .prompt-danger }

해결방법: SDK Manager 에서 cmdline-tools 설치 #

SDK Manager 설치 참고 {: .prompt-info }

Andriod Studio 실행
More Actions SDK Manager
SDK Tools
Android SDK Command-line Tools

이 도구가 있어야 CLI (명령어)로 설정을 할 수 있다.

1flutter doctor --android-licenses

[Git] .gitignore 파일이 바로 적용이 안될 때 해결방법 : git 캐시 삭제

Thu, 22 Aug 2024 00:00:00 +0000

문제점 #

.gitignore 파일에 추가를 하고 확인해 보았지만 바로 적용이 되지 않은 문제점을 확인

해결방법 #

해당 명령어는 Git에서 Local 저장소에서 파일을 제거하지만 실제 파일은 유지되며 Commit을 수행하는 과정을 통해 반영되지 않은 .gitignore를 수행

실제 파일은 삭제되지 않는다. {: .prompt-info }

 1# 인덱스/스테이징 영역에 있는 영역에서만 Local 파일을 삭제하고 실제 파일은 남겨둔다.
 2git rm -r --cached .
 3
 4# Local 저장소의 내용을 스테이징 영역으로 올린다.
 5git add .
 6
 7# 변경 사항을 커밋한다.
 8git commit -m "커밋 내용"
 9
10# 변경 사항을 원격 저장소로 올린다.
11git push

해결 방법 : 1단계 #

Git 인덱스 또는 스테이징 영역에서 모든 파일과 디렉터리를 삭제하지만 Local 파일 시스템에서는 삭제하지 않고 남겨둘 때 사용된다.

실제 파일은 삭제되지 않는다 {: .prompt-info }
git : Git의 명령 줄 인터페이스
rm : 파일 또는 Directory를 삭제하는 명령
-r : Directory를 재귀적으로 삭제하는 옵션
–cached : 이 옵션은 파일을 인덱스/스테이징 영역에서만 삭제하고 Local 파일 시스템에서는 삭제하지 않도록 Git에 지시
. : 현재 디렉터리를 지정

해결방법 : 2단계 #

Local 저장소의 변경 사항을 스테이징 영역으로 모두 추가
```
1git add .
```

해결 방법 : 3단계 #

Local 저장소에 있는 내용들을 Commit하고 Push
```
1git commit -m "Commit 내용"
```
```
1git push
```

[Error] Python PATH Problem

Tue, 20 Aug 2024 00:00:00 +0000

Command 상에서 python 파일명.py를 써서 실행하면 Python이라는 응답이 나오는 것을 볼 수 있다.

문제점 #

윈도우10 시스템 변수에 경로(PATH)로 추가하지 않았기 때문에 발생한다.

1PS F:\Development\python_prj\BoardAPI> python -m venv venv
2Python
3PS F:\Development\python_prj\BoardAPI> python -v
4Python
5PS F:\Development\python_prj\BoardAPI> python3 -v
6Python
7PS F:\Development\python_prj\BoardAPI>

해결 방법 #

윈도우10 시스템 변수에 경로(PATH)로 추가한다면 이 문제는 해결된다.
또는 다시 설치해서 Add Path 해준다.

[Kubernetes] Install CSI Driver SMB(v1.15.0) for Kubernetes Using Helm Chart

Mon, 12 Aug 2024 00:00:00 +0000

Helm 설치 및 설명 참고 {: .prompt-info }

Install CSI Driver SMB #

1helm repo add csi-driver-smb https://raw.githubusercontent.com/kubernetes-csi/csi-driver-smb/master/charts
2helm repo update
3helm install csi-driver-smb csi-driver-smb/csi-driver-smb --version 1.15.0

CSI Driver SMB - Helm 설치 참고

https://github.com/kubernetes-csi/csi-driver-smb {: .prompt-info }

Customize Default Configuration #

values.yaml 수정

최상위 values.yaml을 수정하면 하위 폴더 values.yaml을 override 한다. {: .prompt-info }
- Chart
  - https://github.com/kubernetes-csi/csi-driver-smb/tree/master/charts
- Release file (.tgz)
  - https://github.com/kubernetes-csi/csi-driver-smb/releases

Install Customize Default Configuration #

1helm install [RELEASE NAME] [Chart.yaml 경로] -f [YAML 파일 또는 URL에 값 지정 (여러 개를 지정가능)] -n [NAMESPACE NAME]

1helm install csi-driver-smb csi-driver-smb/csi-driver-smb -f override-values.yaml -n [NAMESPACE NAME]

Test #

1. Namespace 생성 #

1kubectl create ns smb-test

2. Secret 생성 #

1kubectl -n smb-test create secret generic smb-creds \
2--from-literal username=testuser \
3--from-literal domain=12.123.123.123 \
4--from-literal password=testpw

3. PersistentVolume or StorageClass 생성 #

PersistentVolume #

 1apiVersion: v1
 2kind: PersistentVolume
 3metadata:
 4 name: pv-smb
 5 namespace: smb-test
 6spec:
 7 storageClassName: ''
 8 capacity:
 9 storage: 50Gi
10 accessModes:
11 - ReadWriteMany
12 persistentVolumeReclaimPolicy: Retain
13 mountOptions:
14 - dir_mode=0777
15 - file_mode=0777
16 - vers=3.0
17 csi:
18 driver: smb.csi.k8s.io
19 readOnly: false
20 volumeHandle: $VOLUMEID  # make sure it's a unique id in the cluster
21 volumeAttributes:
22 source: //12.123.123.123/testuser
23 nodeStageSecretRef:
24 name: smb-creds
25 namespace: smb-test

StorageClass #

 1apiVersion: storage.k8s.io/v1
 2kind: StorageClass
 3metadata:
 4 name: smb
 5 namespace: smb-test
 6provisioner: smb.csi.k8s.io
 7parameters:
 8 # On Windows, "*.default.svc.cluster.local" could not be recognized by csi-proxy
 9 source: //smb-server.default.svc.cluster.local/share
10 # if csi.storage.k8s.io/provisioner-secret is provided, will create a sub directory
11 # with PV name under source
12 # csi.storage.k8s.io/provisioner-secret-name: smbcreds
13 # csi.storage.k8s.io/provisioner-secret-namespace: [NAMESPACE NAME]
14 csi.storage.k8s.io/node-stage-secret-name: smbcreds
15 csi.storage.k8s.io/node-stage-secret-namespace: smb-test
16volumeBindingMode: Immediate
17mountOptions:
18 - dir_mode=0777
19 - file_mode=0777
20 - uid=1001
21 - gid=1001
22 - noperm
23 - mfsymlinks
24 - cache=strict
25 - noserverino  # required to prevent data corruption

Storage Class 참고

https://github.com/kubernetes-csi/csi-driver-smb/blob/master/deploy/example/storageclass-smb.yaml {: .prompt-info }

4. PersistentVolumeClaim 생성 #

 1kind: PersistentVolumeClaim
 2apiVersion: v1
 3metadata:
 4 name: pvc-smb
 5 namespace: smb-test
 6spec:
 7 accessModes:
 8 - ReadWriteMany
 9 resources:
10 requests:
11 storage: 10Gi
12 volumeName: pv-smb  # pv를 설정했을 때
13 storageClassName: smb  # sc를 설정했을 때

5. Deployment 생성 #

 1apiVersion: apps/v1
 2kind: Deployment
 3metadata:
 4 labels:
 5 app: nginx
 6 name: deploy-smb-pod
 7 namespace: smb-test
 8spec:
 9 replicas: 1
10 selector:
11 matchLabels:
12 app: nginx
13 template:
14 metadata:
15 labels:
16 app: nginx
17 name: deploy-smb-pod
18 spec:
19 containers:
20 - name: deploy-smb-pod
21 image: nginx:1.19.5
22 command:
23 - "/bin/bash"
24 - "-c"
25 - set -euo pipefail; while true; do echo $(date) >> /mnt/smb/outfile; sleep 1; done
26 volumeMounts:
27 - name: smb
28 mountPath: "/mnt/smb"
29 readOnly: false
30 volumes:
31 - name: smb
32 persistentVolumeClaim:
33 claimName: pvc-smb

6. 확인 #

1kubectl -n smb-test exec -it deploy-smb-pod-8569fdd89c-dmlzh -- ls -rtl /mnt/smb
2
3total 28
4-rwxrwxrwx 1 root root 26280 Sep 25 17:53 outfile

7. test.txt 파일 생성 #

1kubectl -n smb-test exec -it deploy-smb-pod-8569fdd89c-dmlzh -- touch /mnt/smb/test.txt

8. 확인2 #

1kubectl -n smb-test exec -it deploy-smb-pod-8569fdd89c-dmlzh -- ls -la /mnt/smb
2
3total 48
4drwxrwxrwx 2 root root 0 Sep 25 18:02 .
5drwxr-xr-x 1 root root 4096 Sep 25 17:51 ..
6-rwxrwxrwx 1 root root 43800 Sep 25 18:03 outfile
7-rwxrwxrwx 1 root root 0 Sep 25 18:15 test.txt

[SRE] SLO, SLI 및 SLA란?

Sun, 11 Aug 2024 00:00:00 +0000

SLO, SLI 및 SLA란? #

서비스 레벨은 일정 기간 내에 사용자에게 제공되는 서비스를 측정 가능한 용어
- 서비스 레벨 목표(Service-level objectives, SLO)는 시스템에서 기대되는 가용성을 설정한 목표이다.
- 서비스 레벨 지표(Service-level indicators, SLI)는 시스템의 가용성을 파악하기 위한 핵심 측정치와 지표이다.
- 서비스 레벨 계약(Service-level agreements, SLA)은 시스템이 SLO를 충족하지 못할 경우 발생하는 상황과 합의된 내용을 설명하는 법적 계약이다.

예를 들어,\ 웹 애플리케이션의 SLO가 1주일 중 99%에 해당하는 시간 동안 2초 이내에 비디오 재생을 시작하는 것이라고 가정한다면,\ SLI는 웹사이트에서 2초 이내에 재생을 시작한 비디오의 비율을 측정한다. SLA에는 이러한 SLO와 고객과 서비스 공급업체가 합의한 기타 SLO와 적용되는 서비스 범위, 그리고 성능을 측정하는 데 사용되는 메트릭인 SLI가 모두 포함된다.

서비스의 성능과 안정성을 측정하는 방법에 초점을 맞추는 사이트 안정성 엔지니어링(Site Reliability Engineering, SRE)으로 인해,\ 분산 시스템의 업타임과 안정성을 유지하기 위한 모범 사례들이 보편화되었다.\ 2016년 3월, Google은 서비스 레벨 목표부터 시작해 메트릭을 모델링, 선택 및 분석하는 프레임워크에 대해 설명하는 ‘사이트 안정성 엔지니어링: Google이 프로덕션 시스템 운영하는 방법(Site Reliability Engineering: How Google Runs Production Systems)‘을 발표했다.

SLO란? #

SLO(서비스 레벨 목표)는 시스템에서 기대하는 가용성을 설정한 목표로, 일정 기간 동안의 백분율로 표시된다.

서비스 레벨 목표는 ‘가용성’과 ‘업타임’이라는 공통된 의미를 기반으로 팀들이 협업하는 데 도움이 된다.\ SLO를 안정성과 가용성을 측정하는 표준으로 사용할 수 있다.\ 이전 예시에서 설명한 것처럼, SLO는 1주일 중 99%의 시간 동안 웹 애플리케이션의 비디오가 2초 이내에 재생되어야 한다는 것이다.

SLI란? #

SLI(서비스 레벨 지표)는 사용자가 시스템의 가용성을 경험하는 방식을 정량적으로 측정한 것이다.
서비스 레벨의 성공 비율을 백분율로 나타낸다.

서비스 레벨 지표는 SLO와 관련해 설명이 되지만, SLI는 시스템 안정성에 대한 실시간 신호를 제공한다.\ SLI는 임계치보다 빠른 요청의 비율 또는 파이프라인으로 들어오는 기록의 비율을 측정하여 정확한 값을 산출할 수 있다.\ 앞의 예시의 경우, SLI는 웹사이트에서 2초 이내에 재생을 시작한 비디오의 비율을 측정한다.\ 이를 통해 SLO와 얼마나 차이가 나는지 알 수 있다.\ SLI는 임계치보다 빠른 요청의 비율 또는 파이프라인으로 들어오는 기록의 비율을 측정하여 정확한 값을 산출할 수 있다.\ 앞의 예시의 경우, SLI는 웹사이트에서 2초 이내에 재생을 시작한 비디오의 비율을 측정한다.\ 이를 통해 SLO와 얼마나 차이가 나는지 알 수 있다.

SLA란? #

SLA(서비스 레벨 계약 또는 협약)는 고객이 서비스를 사용할 때 기대하는 서비스 레벨을 정의한다.

서비스 레벨 계약은 서비스 제공업체와 고객 간의 계약으로, 공급업체가 제공할 서비스를 문서화하고 공급업체가 충족해야 하는 서비스 표준을 정의한다.\ SLA에는 SLO를 위반할 경우 어떤 구제책이나 페널티가 있는지를 설명한다.

앞의 예시의 경우, SLA에는 웹 애플리케이션에 대한 모든 SLO는 물론 포함될 서비스 범위, SLO에 대한 성능 측정에 사용되는 모든 SLI가 포함된다.\ 계약에는 또한 서비스 제공업체와 고객의 책임도 포함된다.

서비스 레벨, SLO, SLI 및 SLA는 누가 사용할까? #

SRE 팀, 안정성 엔지니어 및 교차 기능 팀은 서비스의 ‘안정성’을 정의하고 측정하는 데 어려움을 겪는 경우가 많다.\ 교차 기능 팀은 서비스나 시스템의 모든 측면에서 중요한 메트릭에 대한 포괄적인 뷰를 생성하여 업타임과 성능을 쉽게 측정할 수 있어야 한다.

서비스 레벨은 SRE 팀과 안정성 엔지니어가 애플리케이션과 인프라에서 주요 구성 요소를 식별하는 데 도움이 된다.\ 이들은 하나 이상의 구성 요소가 외부 고객들에게 기능을 노출시키는 경우 알아야 하기 때문이다. 이러한 교차점을 시스템 경계라고 한다.\ 시스템 경계는 사이트 안정성 엔지니어가 시스템의 성능 및 안정성의 실제 상황을 설명하기 위해 서비스 레벨 지표와 목표를 측정 지표에 적용하는 지점이다.

서비스 범위를 설정하고 어떤 메트릭이 SLI이 되어야 하고, SLO 준수 요구 사항이 무엇인지를 결정하려면 많은 노력이 필요하다.\ 복잡하기 때문에 아예 시도하지 않고 포기하는 경우도 많다.\ 안정성 엔지니어와 SRE 팀은 모든 팀을 위해 전체 스택에서 가용성 및 업타임에 대한 기준을 신속하게 설정할 수 있도록, 시스템의 성능 이력을 기반으로 맞춤화된 정확한 SLI 및 SLO가 필요하다.

SRE 팀이 항상 서비스 레벨 관리에 대한 책임을 지는 것은 아니지만, 서비스 레벨이 책임 범위에 포함되는 경우가 많다. SLI를 추적하고 SLO에 연결하면, 시스템 성능에 대한 목표를 설정할 수 있다.\ Google의 SRE 지침은 레이턴시, 트래픽, 오류 및 포화를 서비스 레벨의 4가지 황금 신호로 정의하고 있다.\ 예를 들어,\ API 호출을 확인하고 고객이 좋은 경험을 하기 위해 성공해야 하는 일반적인 요청의 비율(예: SLO 95%)을 기준으로 성공/실패 요청 수(SLI)를 추적할 수 있다.

SRE 팀은 고객에게 어느 정도 레벨의 SLA를 보장해 줘야 할지 보다 잘 이해하기 위해, 애플리케이션과 서비스 내의 핵심 구성 요소에 대해 엄격한 SLO를 설정한다.\ 이를 기준으로 팀은 SLO를 준수하려면 얼마나 신속하게 문제를 해결해야 하는지 이해하기 위한 방법으로 오류 예산을 적용할 수 있다.\ 서비스 레벨은 팀이 메트릭을 집계하고 전체 조직에서 업타임, 성능 및 안정성을 투명하게 파악할 수 있도록 해준다.\ 비즈니스 리더들은 서비스 레벨을 사용해 여러 팀, 애플리케이션, 서비스 등의 규정 준수 여부를 한눈에 모니터링하고 시스템 상태를 포괄적으로 파악할 수 있다.

서비스 레벨 관리란? #

서비스 레벨 관리는 고객에게 제공되는 서비스 레벨에 대한 모든 프로세스와 운영 계약이 적절한지 확인하는 것을 의미한다.\ 여기에는 서비스 레벨에 대한 모니터링 및 보고, SLO 설정 및 조정, SLI 결정, SLA 준수 확인, 고객 리뷰 유지 등이 포함된다.

중요한 점은 SLO의 경우 팀 간에 ‘가용성’의 의미를 공유해야 한다는 것이며, 이는 SLA를 통해 파악할 수도 있다.\ 이러한 서비스 레벨 계약을 충족하거나 초과 충족하려면, 교차 기능 팀이 내부 SLO를 관리하는 것이 중요하다.

서비스 레벨 관리의 혜택 #

팀 전체에 SLO 모범 사례를 구현하는 것은 쉽지 않은 일이다.\ 팀 간에 공유되는 용어를 정확히 정의하려면 올바른 데이터가 필요하다.

안정성 엔지니어는 전체 스택과 팀 전체의 가용성 및 업타임에 대한 기준을 신속하게 설정해야 한다.\ 서비스 경계를 결정하고 서비스 안정성을 투명하게 파악할 수 있는 SLO와 SLI가 있어야, 고객과의 약속인 SLA를 보다 효과적으로 준수할 수 있다.\ 환경 전반을 개선하려면 안정성, SLO 준수 메트릭 및 오류 예산을 보고할 수 있어야 한다.

[K6] K6 Load Testing Tool

Sat, 10 Aug 2024 00:00:00 +0000

Smoke Test, Load Test, Stress Test 등 다양한 테스트 지원
예를 들어, Kubernetes에 애플리케이션 Pod를 배포한다고 가정했을 때
- Pod의 resources를 지정해줘야 하는데 어느 정도 값을 줘야 하는 지 모를 때가 있다.
- 이때 k6 의 Load Test 를 진행하면 보다 수월하게 값을 지정할 수 있다.

Load Test Type

https://grafana.com/docs/k6/latest/testing-guides/test-types/ {: .prompt-info }

주요 성능 지표 #

퍼포먼스 테스트의 결과를 분석 할때, 반드시 알아야 할 주요 성능 지표가 있다.
- Latency(지연시간)
- Throughput(처리량)
- Iterations(반복)

Latency(지연시간) #

고객이 배달 앱을 통해 식당에 음식을 주문하고 문 앞까지 도착하는 시간에 비유할 수 있다.
주문하는데 1분이 걸렸고, 요리하는데 10분, 배달 오는데 10분 총 21 분이 소요되었다. 이때는 21 분의 지연시간이 걸렸다고 할 수 있다.
인터넷에서 요청을 보내고 응답을 받기 전까지를 측정한 지표

Throuput(처리량) #

이번엔 한 식당에 100 명의 고객이 웨이팅하고 있다고 가정
Throuput은 식당이 1시간 동안 100 명의 고객에게 음식을 대접할 수 있는지에 비유할 수 있다.
식당이 높은 Throuput을 가졌다면, 1시간 동안 100 명의 고객에게 모두 음식을 대접할 수 있을 것이고, 낮은 Throuput을 가졌다면 고객들은 더 많은 시간을 기다려야 할 것이다.

Iterations(반복) #

“A 고객이 음식을 주문하고, 식당은 음식을 조리하고, 고객에게 음식을 제공합니다.”
“B 고객이 음식을 주문하고, 식당은 음식을 조리하고, 고객에게 음식을 제공합니다.”
“C 고객이 음식을 주문하고, 식당은 음식을 조리하고, 고객에게 음식을 제공합니다.”
이렇듯 같은 행위를 얼마만큼 안정적으로 반복할 수 있는지를 테스트하는 지표

k6의 Lifecycle은 크게 네가지 #

 1// 1. 초기화 - init code
 2
 3// 2. 전처리 - setup code
 4export function setup() {
 5	//　로그인 토큰취득 등 API실행전에 필요한 처리 구현
 6}
 7
 8// 3. API실행(시나리오 실행) - VU code
 9export default function (data) {
10	/// API를 실행할 시나리오를 구현
11}
12
13// 4. API 실행후 처리 - teardown code
14export function teardown(data) {
15	// API 실행후에 필요한 처리가 있다면 구현
16}

init은 스크립트를 초기화
- 모듈 임포트
- 로컬 파일 시스템에서 파일 로드
- 모든 옵션에 대한 설정 테스트
- 함수 정의 (default에서 수행 혹은 setup, teardown에서 수행)
(선택사항) setup코드는 환경을 준비하고, 데이터를 생성
- setup은 init 다음에 수행되며 오직 한번만 수행
VU코드는 default 함수에서 수행. 실제로 테스트 요청을 보내는 코드가 작성된다. 옵션에 정의한 만큼 반복 동작한다.
- default 함수에서 실제 테스트를 수행
- 혹은 옵션에서 특정 시나리오가 정의한 함수를 수행
- VU코드는 테스트가 수행되는 기간동안 지속적으로 반복 수행
- VU코드는 테스트를 위한 http코드를 생성하고, 메트릭의 생성, 테스트를 위한 모든 작업을 수행
- job 함수를 제외하고 모든 작업이 수행되며, job은 init함수에서 수행
  - VU코드는 로컬 파일을 읽을 수 없다.
  - VU코드는 어떠한 모듈도 로드할 수 없다.
(선택사항) teardown 함수는 테스트의 환경을 정리하고, 자원을 릴리즈한다.
- teardown은 테스트 끝날때 한번만 수행되며 VU 코드가 종료되고 난뒤 바로 수행

setup, teardown 스킵 #

--no-setup 옵션을 이용하여 셋업을 스킵한다.
--no-teardown 옵션을 이용하여 teardown 을 스킵한다.

1k6 run --no-setup --no-teardown ...

setup에서 정의한 데이터를 전달 #

setup에서 정의한 데이터를 default function과 teardown 으로 전달

 1export function setup() {
 2 return { v: 1 };
 3}
 4
 5export default function (data) {
 6 console.log(JSON.stringify(data));
 7}
 8
 9export function teardown(data) {
10 if (data.v != 1) {
11 throw new Error('incorrect data: ' + JSON.stringify(data));
12 }
13}

setup에서 데이터를 return을 하게 되면 이 return 된 객체가 전달이 되는 방식이다.
이후 defult, teardown에서 data를 파라미터로 전달 받을 수 있다.
- 데이터는 오직 json 데이터만 전달가능하며, 함수는 전달불가이다.
- 데이터가 너무 크면 더 많은 메모리가 사용된다.
- default() 에서 데이터를 변경할 수 없다.

Test Life Cycle

https://grafana.com/docs/k6/latest/using-k6/test-lifecycle/ {: .prompt-info }

Test Code 작성 방법 #

k6는 가상 유저를 만들어 애플리케이션에 원하는 요청을 반복적으로 보내게 된다.

 1import http from "k6/http"		// http test
 2import { sleep } from "k6"		// sleep 기능 사용 시 추가 (sleep(n) → 지정한 n 기간 동한 VU 실행을 일시 중지)
 3
 4export let options = {
 5	vus: 10, // 가상의 유저 수
 6	duration: '1m' // 테스트 진행 시간
 7};
 8
 9const BASE_URL = 'http://test.k6.io';		// 테스트 URL
10
11export default function () {
12	let getUrl = BASE_URL
13	http.get(getUrl);
14	sleep(1);
15}

10명의 가상 유저가 10s 동안 https://test.k6.io 을 호출

K6 Web Page Test : https://test.k6.io

K6 API Test : https://test-api.k6.io {: .prompt-info }

1명의 가상 유저가 한번만 default function을 호출하는 것이 아닌, 60초 동안 해당 함수를 계속 호출한다.

즉, default function을 1명씩 1번 호출해서 총 10번 호출하는 것이 아닌, 1명의 가상유저가 5~10번 정도 호출한다. {: .prompt-info }

Production 환경이 아닌 Dev 또는 Staging 환경에서 진행

성능을 분석할 때, 절대 평균값으로 판단하지 않기
클라우드 환경을 이용한다면, k6를 테스트할 때 Scale Up, Out에 주의 {: .prompt-warning }

Test Code 작성 예시 #

 1import http from "k6/http";
 2import { sleep, check } from "k6";
 3import { Trend } from "k6/metrics";
 4
 5const trends = {
 6 scenario1: new Trend("scenario1_response_time", true),
 7 scenario2: new Trend("scenario2_response time", true),
 8};
 9
10const VUS = 1;
11const DURATION = "10s";
12
13export const options = {
14 scenarios: {
15 scenario1: {
16 executor: "constant-vus",
17 exec: "scenarioFunc",
18 vus: VUS,
19 duration: DURATION,
20 env: {
21 SCENARIO_ID: "1",
22 },
23 },
24 scenario2: {
25 executor: "constant-vus",
26 exec: "scenarioFunc",
27 vus: VUS,
28 duration: DURATION,
29 env: {
30 SCENARIO_ID: "2",
31 },
32 },
33 },
34};
35
36export function setup() {
37 const url = "";		// token취득
38 const params = {
39 headers: {
40 Authorization: "Bearer XXX",
41 },
42 };
43 const res = http.get(url, params);
44 const token = JSON.parse(res.body).account.token;
45
46 return token;
47 return { data: res.json() };
48}
49
50export function teardown(data) {
51 console.log("Function teardown : " + JSON.stringify(data));
52}
53
54export function scenarioFunc(token, data) {
55 const scenarioUrl = "";		// 실행할 API
56 const scenario = http.get(scenarioUrl, {
57 headers: {
58 Authorization: `Bearer ${token}`,
59 },
60 });
61 __ENV.SCENARIO_ID === "1"
62 ? trends.scenario1.add(scenario.timings.duration)
63 : trends.scenario2.add(scenario.timings.duration);
64
65 console.log("Function default : " + JSON.stringify(data));
66
67 check(scenario, {
68 "scenario status is 200": (res) => res.status === 200,
69 });
70
71 sleep(1);
72}

Option 관련 #

 1export const options = {
 2 scenarios: {
 3 scenario1: {
 4 executor: "constant-vus",
 5 exec: "scenarioFunc",
 6 vus: VUS,
 7 duration: DURATION,
 8 env: {
 9 SCENARIO_ID: "1",
10 },
11 },
12 },
13};

executor : k6의 실행 엔진을 나타낸다.
- 여기에서 VU(Virtual user)나 스크립트 실행 패턴을 지정할 수 있다.
- 자세한 내용은 k6의 executors를 참조
exec : 실행하고자 하는 시나리오를 지정
vus : Virtual Users API를 실행할 가상 유저. 필요한 만큼의 병렬 실행 수를 여기에 설정
duration : VUS가 반복 시나리오를 실행하는 시간을 설정
env : 공통으로 사용되는 변수를 설정

참고

https://grafana.com/docs/k6/latest/using-k6/k6-options/reference/ {: .prompt-info }

Trend 관련 #

1const trends = {
2 scenario1: new Trend("scenario1_response_time", true),
3 scenario2: new Trend("scenario2_response_time", true),
4};

Trend는 실행 결과에 포함할 User 지정 Metric
시나리오별 응답 시간을 통해 실행 결과에 포함시키기 위해 추가
Trend를 추가하면 아래와 같이 실행 결과에서 볼 수 있다.

scenario1_response_time.......: avg=1.29s min=1.26s med=1.29s max=1.35s p(90)=1.34s p(95)=1.34s
scenario2_response_time.......: avg=1.29s min=1.25s med=1.29s max=1.36s p(90)=1.32s p(95)=1.34s

Setup 관련 #

 1export function setup() {
 2 const url = "";
 3 const params = {
 4 headers: {
 5 Authorization: "Bearer XXX",
 6 },
 7 };
 8 const res = http.get(url, params);
 9 const token = JSON.parse(res.body).account.token;
10
11 return token;
12}

여기에서 토큰 취득 등 시나리오를 실행하기 전에 실행되어야할 처리를 설정하는 곳
로그인이 필요한 서비스를 가정하여 토큰을 취득

scenario 관련 #

 1export function scenarioFunc(token) {
 2 const scenarioUrl = "";
 3 const scenario = http.get(scenarioUrl, {
 4 headers: {
 5 Authorization: `Bearer ${token}`,
 6 },
 7 });
 8 __ENV.SCENARIO_ID === "1"
 9 ? trends.scenario1.add(scenario.timings.duration)
10 : trends.scenario2.add(scenario.timings.duration);
11
12 check(scenario, {
13 "scenario status is 200": (res) => res.status === 200,
14 });
15
16 sleep(1);
17}

여기서 실행하고 싶은 시나리오를 작성
같은 API를 실행하는 시나리오가 2개이기 때문에 그에 따라 Trend를 실행 시나리오 아이디로 분리
check메서드는 값에 대해 true/false를 반환
여기에서 API실행이 성공했는지 실패했는지 확인하고 결과에 기록
실패해도 중간에 멈추지 않고 실행하기 때문에 유연하게 대응할 수 있다.

K6 HTTP Module

https://grafana.com/docs/k6/latest/javascript-api/k6-http/ {: .prompt-info }

K6 JavaScript API

https://grafana.com/docs/k6/latest/javascript-api/ {: .prompt-info }

Result #

 /\ |‾‾| /‾‾/ /‾‾/
 /\ / \ | |/ / / /
 / \/ \ | ( / ‾‾\
 / \ | |\ \ | (‾) |
 / __________ \ |__| \__\ \_____/ .io

 execution: local
 script: scripts.js
 output: -

 scenarios: (100.00%) 2 scenario, 200 max VUs, 40s max duration (incl. graceful stop):
 * scenario1: 1 looping VUS for 10s (exec: scenarioFunc, gracefulStop: 30s)
 * scenario2: 1 looping VUS for 10s (exec: scenarioFunc, gracefulStop: 30s)


running (11.9s), 0/2 VUS, 16 complete and interrupted iterations
scenario1 ✓ [======================================] 1 VUS 10s
scenario2 ✓ [======================================] 1 VUS 10s

 ✓ scenario status is 200
	 
 ▮ setup

 checks.........................: 100.00% ✓ 2893 ✗ 0
 data_received..................: 3.5 MB 58 kB/s
 data_sent......................: 416 kB 6.9 kB/s
 http_req_blocked...............: avg=49.33ms min=1µs med=3µs max=3.45s p(90)=16µs p(95)=377.18ms
 http_req_connecting............: avg=13.09ms min=0s med=0s max=199.77ms p(90)=0s p(95)=186.36ms
 http_req_duration..............: avg=2.14s min=190.5ms med=1.32s max=5.79s p(90)=5.39s p(95)=5.57s
 { expected_response:true }...: avg=2.14s min=190.5ms med=1.32s max=5.79s p(90)=5.39s p(95)=5.57s
 http_req_failed................: 0.00% ✓ 0 ✗ 2893
 http_req_receiving.............: avg=81.97µs min=19µs med=61µs max=2.43ms p(90)=141.8µs p(95)=205.4µs
 http_req_sending...............: avg=22.37µs min=5µs med=16µs max=687µs p(90)=38µs p(95)=57µs
 http_req_tls_handshaking.......: avg=36.2ms min=0s med=0s max=3.2s p(90)=0s p(95)=190.18ms
 http_req_waiting...............: avg=2.14s min=190.38ms med=1.32s max=5.79s p(90)=5.39s p(95)=5.57s
 http_reqs......................: 2893 48.176768/s
 iteration_duration.............: avg=2.19s min=190.7ms med=1.39s max=6.05s p(90)=5.4s p(95)=5.58s
 iterations.....................: 2893 48.176768/s
 scenario1) Response time.......: avg=1.29s min=1.26s med=1.29s max=1.36s p(90)=1.32s p(95)=1.34s
 scenario2) Response time.......: avg=1.29s min=1.25s med=1.29s max=1.36s p(90)=1.32s p(95)=1.34s
 vus............................: 2 min=0 max=2
 vus_max........................: 2 min=2 max=2

checks
- 결과 : 100.00% ✓ 2893 ✗ 0
- 의미 : 요청이 성공한 비율(%)
data_received
- 결과 : 3.5 MB 58 kB/s
- 의미 : 응답한 데이터 양 (Total, /s)
data_sent
- 결과 : 416 kB 6.9 kB/s
- 의미 : 요청한 데이터 양 (Total, /s)
http_req_blocked
- 결과 : avg=49.33ms min=1µs med=3µs max=3.45s p(90)=16µs p(95)=377.18ms
- 의미 : TCP 접속 대기시간(avg, min, med, max, p(90), p(95)
http_req_connecting
- 결과 : avg=13.09ms min=0s med=0s max=199.77ms p(90)=0s p(95)=186.36ms
- 의미 : TCP 접속에 걸린시간(avg, min, med, max, p(90), p(95)
http_req_duration
- 결과 : avg=2.14s min=190.5ms med=1.32s max=5.79s p(90)=5.39s p(95)=5.57s
- 의미 : 요청 → 응답 까지 얼마나 걸렸는지를 나타내는 지표. http_req_sending + http_req_waiting + http_req_receiveing(avg, min, med, max, p(90), p(95)
{ expected_response:true }
- 결과 : avg=2.14s min=190.5ms med=1.32s max=5.79s p(90)=5.39s p(95)=5.57s
- 의미 : 정상응답만 http_req_duration(avg, min, med, max, p(90), p(95) 정상응답이 없을 경우 이 항목은 표시되지 않음
http_req_failed
- 결과 : 0.00% ✓ 0 ✗ 2893
- 의미 : 요청이 실패한 비율(%)
http_req_receiving
- 결과 : avg=81.97µs min=19µs med=61µs max=2.43ms p(90)=141.8µs p(95)=205.4µs
- 의미 : 응답의 1바이트가 도달하고 나서 마지막 바이트를 수신할 때까지의 시간(avg, min, med, max, p(90), p(95)
http_req_sending
- 결과 : avg=22.37µs min=5µs med=16µs max=687µs p(90)=38µs p(95)=57µs
- 의미 : 요청을 전송하는데 걸린시간(avg, min, med, max, p(90), p(95)
http_req_tls_handshaking
- 결과 : avg=36.2ms min=0s med=0s max=3.2s p(90)=0s p(95)=190.18ms
- 의미 : TLS 세션의 핸드쉐이크에 걸린 시간(avg, min, med, max, p(90), p(95) http에서는 0
http_req_waiting
- 결과 : avg=2.14s min=190.38ms med=1.32s max=5.79s p(90)=5.39s p(95)=5.57s
- 의미 : 요청이 전송 완료된 후 응답이 시작될 때까지의 시간(avg, min, med, max, p(90), p(95) TTFB(Time To First Byte)
http_reqs
- 결과 : 2893 48.176768/s
- 의미 : 총 리퀘스트수 (Total, /s)
iteration_duration
- 결과 : avg=2.19s min=190.7ms med=1.39s max=6.05s p(90)=5.4s p(95)=5.58s
- 의미 : 시나리오 1회 반복에 걸린 시간(avg, min, med, max, p(90), p(95)
iterations
- 결과 : 2893 48.176768/s
- 의미 : 시나리오 반복 횟수(Total, /s)
vus
- 결과 : 2 min=0 max=2
- 의미 : Virtual Users, 시나리오 실행시 유저수(병렬)
vus_max
- 결과 : 2 min=0 max=2
- 의미 : 최대 Virtual Users, 시나리오의 최대 실행유저수(병렬)

p(90)과 p(95)의 의미 #

p는 percentile을 의미하고 뒤에 90, 95는 각각 90%, 95%를 의미
- p(90)은 “90%의 요청이 주어진 지연보다 빠르거나 동일한 시간 안에 완료된다는 것을 의미”
- p(95)는 “95%의 요청이 주어진 지연보다 빠르거나 동일한 시간 안에 완료된다는 것을 의미”

500명의 고객들이 햄버거를 주문했다고 가정 #

80%인 400명은 20초 안에 햄버거를 받았고, 20%인 100명은 햄버거를 받기까지 10분 이상이 걸렸다.
이때 평균적으로 한 고객이 햄버거를 받기까지 약 4분이 소요
대부분의 사람들이 20초 내에 햄버거를 받았음에도 불구하고 평균 시간은 4분으로 측정되기 때문에 햄버거를 받기까지의 시간이 오래 걸린다고 생각할 수 있다.

이렇듯 평균은 실제로 전체 성능을 말해주기엔 함정이 있다.
따라서 퍼포먼스 측정을 진행 할 때는 평균을 보는 것에 주의를 주어야 하며, 평균보다는 p(90)과 p(95)가 더 중요하다.

100만 건의 요청을 보냈을 때, 모든 요청은 1초 내에 이루어져야 하는데, 딱 하나의 요청만이 1분이 걸렸다고 가정 #

일반적인 관점에서는 실패로 볼 수 있지만, Service Level Objective(SLO) 관점에서 바라보면 성공. 왜냐하면 SLO에서 100%는 있을 수 없기 때문이다.
AWS S3 서비스만 봐도 99.999999999%의 내구성과 99.99%의 가용성을 제공한다고 합니다.

Test 표준 측정 항목 #

Metric Name	Type	Description
vus	Gauge	현재 활성화 된 사용자 유저
vus_max	Gauge	가능한 최대 가상 사용자 수(로드 레벨을 확장할 때 성능에 영향을 미치지 않도록 VU 리소스가 미리 할당됨)
iterations	Counter	테스트에서 Vu가 JS 스크립트를 실행한 총 횟수
iteration_duration	Trend	default/main function의 전체 반복을 한 번 완료하는데 소요된 시간
dropped_iterations	Counter	k6 v0.27.0에 도입된 VU lack 또는 lack of time으로 인해 시작할 수 없는 반복 회수
data_received	Counter	데이터를 전달받은 양
data_sent	Counter	데이터를 전달한 양
checks	Rate	성공적으로 체크된 Rate

HTTP 측정 항목 #

Metric Name	Type	Description
http_reqs	Counter	총 얼마나 많은 HTTP requests를 k6에서 생성했는지 횟수
http_req_blocked	Trend	요청을 시작하기 전에 차단된 시간(TCP connection slot 을 기다리는) 단위: float
http_req_connecting	Trend	원격 호스트에 대한 TCP 연결을 설정하는데 소요된 시간. 단위: float
http_req_tls_handshaking	Trend	원격 호스트와의 핸드셰이킹 TLS 세션에 소요된 시간
http_req_sending	Trend	원격 호스트에 데이터를 보내는데 소요된 시간. 단위: float
http_req_waiting	Trend	원격 호스트로부터의 응답을 대기하는 데 소요된 시간 (a.k.a. “time to first byte”, or “TTFB”). 단위: float
http_req_receiving	Trend	원격 호스트로부터 응답 데이터를 수신하는 데 소요된 시간. 단위: float
http_req_duration	Trend	요청의 총 시간. It’s equal to http_req_sending + http_req_waiting + http_req_receiving (즉, 초기 DNS 조회/연결 시간 없이 원격 서버가 요청을 처리하고 응답하는 데 소요된 시간s). 단위: float
http_req_failed	Rate	setResponseCallback 에 따른 요칭 실패 비율.

출력 가능한 옵션

https://grafana.com/docs/k6/latest/results-output/real-time/ {: .prompt-info }

Swagger API 관련

https://k6.io/blog/load-testing-your-api-with-swagger-openapi-and-k6/ {: .prompt-info }

Postman 관련

https://grafana.com/blog/2020/04/19/load-testing-your-api-with-postman/ {: .prompt-info }

k6-learn

https://github.com/grafana/k6-learn {: .prompt-info }

[Kubernetes] Install K6-operator Using Helm Chart

Mon, 29 Jul 2024 00:00:00 +0000

Helm 설치 및 설명 참고 {: .prompt-info }

Install k6-operator #

1helm repo add grafana https://grafana.github.io/helm-charts
2helm repo update
3helm install k6-operator grafana/k6-operator

K6-operator 설치 참고

https://grafana.com/docs/k6/latest/set-up/set-up-distributed-k6/install-k6-operator/ {: .prompt-info }

Customize Default Configuration #

values.yaml 수정

최상위 values.yaml을 수정하면 하위 폴더 values.yaml을 override 한다. {: .prompt-info }
- Chart
  - https://github.com/grafana/k6-operator/tree/main/charts/k6-operator
- Release file (.tgz)
  - https://github.com/grafana/k6-operator/releases

Install Customize Default Configuration #

1helm install [RELEASE NAME] [Chart.yaml 경로] -f [YAML 파일 또는 URL에 값 지정 (여러 개를 지정가능)] -n [NAMESPACE NAME]

1helm install k6-operator grafana/k6-operator -f override-values.yaml -n [NAMESPACE NAME]

k6 resource 설정 관련 #

Resource yaml 작성

 1apiVersion: k6.io/v1alpha1
 2kind: TestRun
 3metadata:
 4 name: k6-sample
 5spec:
 6 parallelism: 4
 7 arguments: --out influxdb=http://influxdb:8086/k6
 8 arguments: -o xk6-influxdb=http://localhost:8086
 9 arguments: -o xk6-prometheus-rw --tag testid=test
10 arguments: -o experimental-prometheus-rw # prometheus : --enable-feature=remote-write-receiver
11 cleanup: 'post' # configure the automatic deletion of all resources
12 script:
13 configMap:
14 name: k6-test
15 file: test.js
16 separate: false
17 runner:
18 image: <custom-image>
19 metadata:
20 labels:
21 cool-label: foo
22 annotations:
23 cool-annotation: bar
24 securityContext:
25 runAsUser: 1000
26 runAsGroup: 1000
27 runAsNonRoot: true
28 resources:
29 limits:
30 cpu: 200m
31 memory: 1000Mi
32 requests:
33 cpu: 100m
34 memory: 500Mi
35 starter:
36 image: <custom-image>
37 metadata:
38 labels:
39 cool-label: foo
40 annotations:
41 cool-annotation: bar
42 securityContext:
43 runAsUser: 2000
44 runAsGroup: 2000
45 runAsNonRoot: true

적용

1kubectl apply -f /path/to/your/k6-resource.yml

삭제

1kubectl delete -f /path/to/your/k6-resource.yml

Run k6 사용법

https://grafana.com/docs/k6/latest/set-up/set-up-distributed-k6/usage/ {: .prompt-info }

Stream real-time

https://grafana.com/docs/k6/latest/results-output/real-time/ {: .prompt-info }

InfluxDB 설치 참고 {: .prompt-info }

Dockerfile Build with xk6-output-influxdb #

 1# Build the k6 binary with the extension
 2FROM golang:1.20 as builder
 3
 4RUN go install go.k6.io/xk6/cmd/xk6@latest
 5# For our example, we'll add support for output of test metrics to InfluxDB v2.
 6# Feel free to add other extensions using the '--with ...'.
 7RUN xk6 build \
 8 --with github.com/grafana/xk6-output-influxdb@latest \
 9 --output /k6
10
11# Use the operator's base image and override the k6 binary
12FROM grafana/k6:latest
13COPY --from=builder /k6 /usr/bin/k6

Dockerfile Build with xk6-output-prometheus-remote #

1# Build the k6 binary with the extension
2FROM golang:1.18.1 as builder
3
4RUN go install go.k6.io/xk6/cmd/xk6@latest
5RUN xk6 build --output /k6 --with github.com/grafana/xk6-output-prometheus-remote@latest
6
7# Use the operator's base image and override the k6 binary
8FROM grafana/k6:latest
9COPY --from=builder /k6 /usr/bin/k6

k6 resource 예시 #

 1apiVersion: k6.io/v1alpha1
 2kind: K6
 3metadata:
 4 name: k6-sample
 5spec:
 6 arguments: -o xk6-prometheus-rw --tag testid=test
 7 parallelism: 1
 8 runner:
 9 image: <custom-image>
10 env:
11 - name: K6_PROMETHEUS_RW_SERVER_URL
12 value: http://kube-prometheus-stack-prometheus.monitoring:9090/api/v1/write
13 - name: K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM
14 value: "true"
15 image: k6-prometheus:v1
16 starter:
17 image: <custom-image>
18 script:
19 configMap:
20 file: scritps.js
21 name: test-script

테스트 JavaScript #

Ex 1. #

 1import http from 'k6/http';
 2import { sleep } from 'k6';
 3
 4export const options = {
 5 stages: [
 6 { duration: '10s', target: 10 },
 7 { duration: '10s', target: 20 },
 8 { duration: '10s', target: 30 },
 9 { duration: '10s', target: 0 },
10 ],
11};
12
13export default function () {
14 http.get('http://test.k6.io');
15 sleep(1);
16}

Ex 2. #

 1import http from 'k6/http';
 2import { check } from 'k6';
 3
 4export const options = {
 5 insecureSkipTLSVerify: true,
 6 stages: [
 7 { target: 200, duration: '30s' },
 8 { target: 0, duration: '30s' },
 9 ],
10};
11
12export default function () {
13 const result = http.get('https://test-api.k6.io/public/crocodiles/');
14 check(result, {
15 'http response status code is 200': result.status === 200,
16 });
17}

테스트 JavaScript 적용 #

1kubectl -n [NAMESPACE NAME] create configmap test-script --from-file /home/documents/k6/scritps.js

K6 Load Test 참고 {: .prompt-info }

Uninstall the Chart #

1helm uninstall [RELEASE NAME] -n [NAMESPACE NAME]

[Kubernetes] Install InfluxDB Using Helm Chart

Sun, 28 Jul 2024 00:00:00 +0000

참고 Helm 설치 및 설명 참고

Install InfluxDB #

1helm repo add influxdata https://helm.influxdata.com/
2helm repo update
3helm install influxdb influxdata/influxdb

InfluxDB - Helm 설치 참고

https://github.com/influxdata/helm-charts
참고

Customize Default Configuration #

values.yaml 수정

최상위 values.yaml을 수정하면 하위 폴더 values.yaml을 override 한다. {: .prompt-info }
- Chart
  - https://github.com/influxdata/helm-charts/tree/master/charts/influxdb
- Release file (.tgz)
  - https://github.com/influxdata/helm-charts/releases

팁 InfluxDB 설정 및 사용법 참고

Setting config #

 1...✂...
 2
 3config:
 4 reporting_disabled: false
 5 rpc:
 6 bind-address: ":8088"
 7 meta: {}
 8 data: {}
 9 coordinator: {}
10 retention: {}
11 shard_precreation: {}
12 monitor: {}
13 http:
14 enabled: true
15 bind-address: ":8086"
16 flux-enabled: true
17 logging: {}
18 subscriber: {}
19 graphite: {}
20 collectd: {}
21 opentsdb: {}
22 udp: {}
23 continuous_queries: {}
24 tls: {}
25
26...✂...

Setting create database #

1...✂...
2
3initScripts:
4 enabled: false
5 scripts:
6 init.iql: |+
7 CREATE DATABASE "telegraf" WITH DURATION 30d REPLICATION 1 NAME "rp_30d"
8
9...✂...

API Create Database

1curl -XPOST 'http://[influxdb-svc].[influxdb-namespace].svc:8086/query' --data-urlencode 'q=CREATE DATABASE mydb'

참고

Install Customize Default Configuration #

1helm install [RELEASE NAME] [Chart.yaml 경로] -f [YAML 파일 또는 URL에 값 지정 (여러 개를 지정가능)] -n [NAMESPACE NAME]

1helm install influxdb influxdata/influxdb -f override-values.yaml -n [NAMESPACE NAME]

[Kubernetes] Install Loki(v3.1.1) Distributed Using Helm Chart

Wed, 19 Jun 2024 00:00:00 +0000

Helm 설치 및 설명 참고 {: .prompt-info }

Install the Loki Distributed Helm charts #

1helm repo add grafana https://grafana.github.io/helm-charts
2helm repo update
3helm install loki-distributed grafana/loki-distributed --namespace [NAMESPACE NAME] --version [VERSION]

Loki Distributed - Helm 설치 참고

https://grafana.com/docs/loki/latest/setup/install/helm/ {: .prompt-info }

Customize Default Configuration #

values.yaml 수정

최상위 values.yaml을 수정하면 하위 폴더 values.yaml을 override 한다. {: .prompt-info }
- Chart
  - https://github.com/grafana/helm-charts/tree/main/charts/loki-distributed
- Release file (.tgz)
  - https://github.com/grafana/helm-charts/releases

Loki Configurations #

Loki 설정 값 문서

https://grafana.com/docs/loki/latest/configuration/ {: .prompt-info }
Grafana Loki 모범 사례
- 레이블은 Loki에서 Log를 검색할 때 필터링이 되는 기준이 되는데 여기선 정적 레이블을 가급적이면 사용하라고 가이드하고 있다.
  - 레이블은 클라이언트에서 설정한 다음에 Loki에게 Push하면 된다.
- chunk_target_size를 사용하라고 한다.
  - 기본 1.5MB 사이즈로 모든 청크 크기를 채우도록 하는게 좋다고 한다.
- chunk_encoding은 기본값이 gzip인데 snappy를 권고한다고 한다.
  - 이게 훨씬 더 압축을 푸는데도 빠르고 쿼리 속도도 더 빠르다고 한다.
- max_chunk_age는 2h을 권고한다고 한다.
- chunk_idle_period은 1h ~ 2h을 권고한다고 한다.
- RF(Replication factor)를 항상 설정할 것을 권고한다.
  - 데이티의 손실 가능성을 완화하기 위해 Ingester의 복제 요소를 일반적으로 3개로 설정할 것을 권고하고 있다.
  - 복제 요소가 데이터 손실을 방지하는 유일한 요소는 아니며, 주요 목적은 롤아웃 및 재시작 중에 쓰기가 중단되지 않도록 하는 것이다.

참고

https://grafana.com/docs/loki/latest/best-practices/
https://grafana.com/blog/2021/02/16/the-essential-config-settings-you-should-use-so-you-wont-drop-logs-in-loki/ {: .prompt-info }
Request Validation, Rate-Limit 에러
- 아래의 값으로 설정하면 필히 쓰로틀링이 걸리게 된다. 하여 적절한 값으로 조정이 필요하다.
- ingestion_rate_mb는 기본값 4이며 ingestion_burst_size_mb는 기본값 6이다.
  - ingestion_rate_mb: 20
  - ingestion_burst_size_mb: 40

참고

https://grafana.com/docs/loki/latest/operations/request-validation-rate-limits/
https://grafana.com/docs/loki/latest/configuration/#limits_config {: .prompt-info }
Loki Grafana 모니터링
- Loki는 기본적으로 /metrics 엔드포인트로부터 각 Components들의 Metric들을 확인할 수 있다.
- 모든 컴포넌트들의 Service annotation에 아래의 문구를 추가해준다.
  - 이렇게 하면 Prometheus가 자동으로 /metrics 엔드포인트로 메트릭들을 scrape 해간다.
```
1prometheus.io/scrape: "true"
2prometheus.io/path: "/metrics"
3prometheus.io/port: "3100"
```

Loki에 대한 모니터링 참고

https://grafana.com/docs/loki/latest/operations/observability/ {: .prompt-info }

analytics false #

1analytics:
2 reporting_enabled: false

Compactor와 Table Manager #

Grafana Loki의 로그 보존(Retention)은 Compactor 혹은 Table Manager에 의해 수행된다.
현재 Table Manager를 통한 Retention은 TTL을 통해 달성되며 boltdb-shipper, chunk/index store 모두 작동한다.
Compactor를 통한 Retention은 boltdb-shipper 저장소에서만 지원된다.
만약 Compactor로 Retention을 적용한다면 Table Manager는 필요로 하지 않게 될 수 있다.

Compactor 설정 예시

1compactor:
2 retention_delete_delay: 2h
3 delete_request_store: s3
4 working_directory: "/var/loki/compactor"
5 retention_enabled: true
6 retention_delete_worker_count: 150
7 apply_retention_interval: 1h
8 compaction_interval: 5m

Compactor의 Retention은 limits_config에 설정해주면 된다.

Retention 설정 참고
- https://grafana.com/docs/loki/latest/operations/storage/retention/#configuring-the-retention-period {: .prompt-info }

storage #

 1schema_config:
 2 configs:
 3 - from: "2024-06-19"
 4 index:
 5 period: 24h
 6 prefix: tsdb_index_
 7 object_store: s3
 8 schema: v13
 9 store: tsdb
10
11storage_config:
12 aws:
13 s3: http://access_key:secret_key@endpoint:port
14 bucketnames: loki-logs
15 s3forcepathstyle: true
16 tsdb_shipper:
17 active_index_directory: /var/loki/tsdb-index
18 cache_location: /var/loki/tsdb-cache
19 index_gateway_client:
20 # only applicable if using microservices where index-gateways are independently deployed.
21 # This example is using kubernetes-style naming.
22 server_address: dns:///index-gateway.<namespace>.svc.cluster.local:9095

minio 설치 참고 {: .prompt-info }

Install Customize Default Configuration #

1helm install [RELEASE NAME] [Chart.yaml 경로] -f [YAML 파일 또는 URL에 값 지정 (여러 개를 지정가능)] -n [NAMESPACE NAME]

1helm install loki-distributed grafana/loki-distributed -f override-values.yaml -n [NAMESPACE NAME]

Uninstall the Chart #

1helm uninstall [RELEASE NAME] -n [NAMESPACE NAME]

[Kubernetes] OTel(OpenTelemetry) Collector - Logging

Mon, 10 Jun 2024 00:00:00 +0000

🔀 OTEL 예시 흐름: #

graph TD
 A[Application] --> B[OTel SDK]
 B --> C[OTel Collector]
 C --> D[Logs]
 C --> E[Metrics]
 C --> F[Traces]
 D --> G[Loki]
 E --> H[Prometheus]
 F --> I[Tempo/Jaeger]

Opentelemetry Collector #

아키텍쳐는 OTel Collector와 기존의 로그 수집 도구를 혼합해 구성한 Plan A와 OTel Collector만으로 구성한 Plan B로 나눌 수 있다.

OpenTelemetry Collector 배포 및 구성 #

vi /etc/rsyslog.conf에 아래의 Code 추가

*.* action(type="omfwd" target="0.0.0.0" port="54527" protocol="tcp" action.resumeRetryCount="10" queue.type="linkedList" queue.size="10000")

syslog 및 container log

 1apiVersion: opentelemetry.io/v1beta1
 2kind: OpenTelemetryCollector
 3metadata:
 4 name: otel-log
 5spec:
 6 mode: daemonset
 7 hostNetwork: true
 8 podSecurityContext:
 9 runAsUser: 0
 10 runAsGroup: 0
 11 tolerations:
 12 - operator: Exists
 13 volumes:
 14 # Typically the collector will want access to pod logs and container logs
 15 - name: varlogpods
 16 hostPath:
 17 path: /var/log/pods
 18 - name: varlibdockercontainers
 19 hostPath:
 20 path: /var/lib/docker/containers
 21 - name: applogs
 22 hostPath:
 23 path: /appdata/applog
 24 volumeMounts:
 25 # Mount the volumes to the collector container
 26 - name: varlogpods
 27 mountPath: /var/log/pods
 28 readOnly: true
 29 - name: varlibdockercontainers
 30 mountPath: /var/lib/docker/containers
 31 readOnly: true
 32 - name: applogs
 33 mountPath: /appdata/applog
 34 readOnly: true
 35 config:
 36 # This is a new configuration file - do not merge this with your metrics configuration!
 37 receivers:
 38 syslog:
 39 tcp:
 40 listen_address: '0.0.0.0:54527'
 41 protocol: rfc3164
 42 location: UTC or Asia/Seoul # specify server timezone here
 43 operators:
 44 - type: move
 45 from: attributes.message
 46 to: body
 47 - type: move
 48 from: attributes.hostname
 49 to: resource["hostname"]
 50 - type: move
 51 from: attributes.appname
 52 to: resource["daemon"]
 53
 54 filelog/applog:
 55 include:
 56 - /appdata/applog/*/*/*.log
 57 operators:
 58 # Extract metadata from file path
 59 - type: regex_parser
 60 id: extract_metadata_from_filepath
 61 # Pod UID is not always 36 characters long
 62 regex: '^.*\/(?P<namespace>\S+)\/(?P<pod_name>\S+)\/(?P<log_file_name>\S+)\.log$'
 63 parse_from: attributes["log.file.path"]
 64 cache:
 65 size: 128 # default maximum amount of Pods per Node is 110
 66 # Rename attributes
 67 - type: move
 68 from: attributes["log.file.path"]
 69 to: resource["filename"]
 70 - type: move
 71 from: attributes.namespace
 72 to: resource["namespace"]
 73 - type: move
 74 from: attributes.pod_name
 75 to: resource["pod"]
 76 - type: add
 77 field: resource["cluster"]
 78 value: 'your-cluster-name'
 79
 80 filelog:
 81 include:
 82 - /var/log/pods/*/*/*.log
 83 exclude:
 84 # Exclude logs from all containers named otel-collector
 85 - /var/log/pods/*/otel-collector/*.log
 86 start_at: beginning
 87 include_file_path: true
 88 include_file_name: false
 89 operators:
 90 # Find out which format is used by kubernetes
 91 - type: router
 92 id: get-format
 93 routes:
 94 - output: parser-docker
 95 expr: 'body matches "^\\{"'
 96 - output: parser-crio
 97 expr: 'body matches "^[^ Z]+ "'
 98 - output: parser-containerd
 99 expr: 'body matches "^[^ Z]+Z"'
100 # Parse CRI-O format
101 - type: regex_parser
102 id: parser-crio
103 regex: '^(?P<time>[^ Z]+) (?P<stream>stdout|stderr) (?P<logtag>[^ ]*) ?(?P<log>.*)$'
104 output: extract_metadata_from_filepath
105 timestamp:
106 parse_from: attributes.time
107 layout_type: gotime
108 layout: '2006-01-02T15:04:05.999999999Z07:00'
109 # Parse CRI-Containerd format
110 - type: regex_parser
111 id: parser-containerd
112 regex: '^(?P<time>[^ ^Z]+Z) (?P<stream>stdout|stderr) (?P<logtag>[^ ]*) ?(?P<log>.*)$'
113 output: extract_metadata_from_filepath
114 timestamp:
115 parse_from: attributes.time
116 layout: '%Y-%m-%dT%H:%M:%S.%LZ'
117 # Parse Docker format
118 - type: json_parser
119 id: parser-docker
120 output: extract_metadata_from_filepath
121 timestamp:
122 parse_from: attributes.time
123 layout: '%Y-%m-%dT%H:%M:%S.%LZ'
124 # Extract metadata from file path
125 - type: regex_parser
126 id: extract_metadata_from_filepath
127 # Pod UID is not always 36 characters long
128 regex: '^.*\/(?P<namespace>[^_]+)_(?P<pod_name>[^_]+)_(?P<uid>[a-f0-9\-]{16,36})\/(?P<container_name>[^\._]+)\/(?P<restart_count>\d+)\.log$'
129 parse_from: attributes["log.file.path"]
130 cache:
131 size: 128 # default maximum amount of Pods per Node is 110
132 # Rename attributes
133 - type: move
134 from: attributes["log.file.path"]
135 to: resource["filename"]
136 - type: move
137 from: attributes.container_name
138 to: resource["container"]
139 - type: move
140 from: attributes.namespace
141 to: resource["namespace"]
142 - type: move
143 from: attributes.pod_name
144 to: resource["pod"]
145 - type: add
146 field: resource["cluster"]
147 value: 'your-cluster-name' # Set your cluster name here
148 - type: move
149 from: attributes.log
150 to: body
151
152 processors:
153 attributes:
154 actions:
155 - action: insert
156 key: loki.resource.labels
157 value: hostname, daemon
158 resource:
159 attributes:
160 - action: insert
161 key: loki.format
162 value: raw
163 - action: insert
164 key: loki.resource.labels
165 value: pod, namespace, container, cluster, filename
166
167 exporters:
168 loki:
169 endpoint: https://LOKI_USERNAME:ACCESS_POLICY_TOKEN@LOKI_URL/loki/api/v1/push or http://<Loki-svc>.<Loki-Namespace>.svc/loki/api/v1/push
170
171 service:
172 pipelines:
173 logs:
174 receivers: [syslog, filelog/applog, filelog]
175 processors: [attributes, resource]
176 exporters: [loki]

변경될 Container Log 수집 방법

 1apiVersion: opentelemetry.io/v1beta1
 2kind: OpenTelemetryCollector
 3metadata:
 4 name: otel-log
 5spec:
 6 mode: daemonset
 7 hostNetwork: true
 8 volumes:
 9 # Typically the collector will want access to pod logs and container logs
10 - name: varlogpods
11 hostPath:
12 path: /var/log/pods
13 - name: varlibdockercontainers
14 hostPath:
15 path: /var/lib/docker/containers
16 volumeMounts:
17 # Mount the volumes to the collector container
18 - name: varlogpods
19 mountPath: /var/log/pods
20 readOnly: true
21 - name: varlibdockercontainers
22 mountPath: /var/lib/docker/containers
23 readOnly: true
24 config:
25 # This is a new configuration file - do not merge this with your metrics configuration!
26 receivers:
27 filelog:
28 include_file_path: true
29 include:
30 - /var/log/pods/*/*/*.log
31 operators:
32 - id: container-parser
33 type: container
34
35 processors:
36 resource:
37 attributes:
38 - action: insert
39 key: loki.format
40 value: raw
41 - action: insert
42 key: loki.resource.labels
43 value: pod, namespace, container, cluster, filename
44
45 exporters:
46 loki:
47 endpoint: https://LOKI_USERNAME:ACCESS_POLICY_TOKEN@LOKI_URL/loki/api/v1/push or http://<Loki-svc>.<Loki-Namespace>.svc/loki/api/v1/push
48
49 service:
50 pipelines:
51 logs:
52 receivers: [filelog]
53 processors: [resource]
54 exporters: [loki]

참고 : https://opentelemetry.io/blog/2024/otel-collector-container-log-parser/ {: .prompt-info }

Receiver Configuration - Plan A #

Receiver는 Promtail 및 EventExporter로부터 Log 데이터를 받는 진입점을 위한 loki receiver를 사용한다.
loki receiver를 사용하면 Otel Collector에 기존의 Loki가 노출하는 endpoint를 동일하게 노출시켜 기존의 Log 수집 컴포넌트들이 동일한 방법으로 OTel Collector에 Log를 보낼 수 있도록 구성할 수 있다.

Receiver Configuration - Plan B #

Receiver는 Container Log 수집을 위한 filelog, System Log 수집을 위한 filelog, Kubernetes Event Log 수집을 위한 k8s_event 3개를 사용한다.
Container Log는 filelog receiver로 /var/log/pods/*/*/*.log 경로에서 수집하고, 수집한 파일들을 기반으로 Path 및 Body를 분석해 Container명, Pod명, Namespace명 등의 정보를 추출한다.
System Log는 별도의 filelog receiver로 /var/log 경로에서 수집한 dmesg, messages, secure 파일들에서 syslog_parser로 정보를 추출해 수집한다.
Kubernetes Event Log는 k8s_event receiver를 이용해 Kubernetes API로부터 수집한다.

Processor Configuration #

Processor는 Log에 Kubernetes Attribute를 부착하기 위한 k8sattributes, Loki Label을 구성하기 위한 resource, OOM 방지를 위한 memory_limiter, Log를 batch성으로 전송하기 위한 batch 4개를 사용한다.
k8sattributes Processor는 filelog로부터 수집한 Container log를 기반으로 이와 일치하는 Pod, Deployment, Cluster 등의 정보를 데이터에 부착한다.
resource Processor는 위에서 부착한 정보를 Loki의 indexing에 필요한 Label로 변환하는 작업을 수행한다.
batch와 memory_limiter Processor는 가공한 Log 데이터를 Export하는 방법을 제공한다.

Exporter Configuration #

Exporter는 Log를 Loki로 전송하기 위한 loki exporter를 사용한다.
loki의 endpoint Attribute에 loki 주소의 /loki/api/v1/push Path를 붙여 로그 진입점을 값으로 넣어 수집한 Log를 Loki로 전송한다.

Pipeline Configuration #

마지막으로 위에서 정의한 Receiver, Processor, Exporter를 순서에 맞게 조합하는 Pipeline을 정의한다.
특히 Processor 요소들의 배치 순서에 따라 Log를 가공하는 순서가 달라지기 때문에, 위의 순서를 준수하는 것이 중요하다.
Loki Receiver에서 Log 데이터를 수집해 k8sattributes, resource, memory_limiter, batch 순으로 가공한 뒤, Loki Exporter를 사용해 Loki backend로 전송한다.

Pipeline Configuration - Plan B #

filelog, k8s_events Receiver에서 Log 데이터를 수집해 k8sattributes, resource, memory_limiter, batch순으로 가공한 뒤, Loki Exporter를 사용해 Loki backend로 전송한다.

Node Collector(Daemonset) #

File Logs
Host metrics
Kubelet state metrics
공식 문서에서 DaemonSet을 권장하는 receiver가 모인 collector이다.

Log | Filelog #

수집 대상은 stdout/stderr로 생성된 Kubernetes, app log으로,\ 사실상 Fluentbit를 대체한다.\ 이를 위해 log scraping 및 전달 뿐 아니라 Processors 에서 언급한 다양한 processor 사용을 고려해야 한다.

Receiver: Filelog Receiver
Exporter: Loki exporter

Metric | Kubelet Stats #

node, pod, container, volume, filesystem network I/O and error metrics 등 CPU, memory 등 infra resource에 관한 metric을 다루어,\ 각 노드의 kubelet이 노출하는 API에서 추출한다. 사실 상 cAdvisor의 대체이다.

Receiver: Kubelet Stats Receiver
Exporter: OTLP/HTTP Exporter

Metric | Host Metrics #

수집 대상은 node (cpu, disk, CPU load, filesystem, memory, network, paging, process..)의 metric으로,\ 사실 상 Prometheus Node Exporter를 대체한다.\ Kubelet Stats Receiver와 일부 항목이 겹치므로 동시 운용 시 중복 처리가 필요하다.

Receiver: Host Metrics Receiver
Exporter: OTLP/HTTP Exporter

 1# otel-node-collector service accounts are created automatically
 2---
 3apiVersion: rbac.authorization.k8s.io/v1
 4kind: ClusterRole
 5metadata:
 6 name: otel-node-collector
 7rules:
 8 - apiGroups: [""]
 9 resources: ["nodes/stats", "nodes/proxy"]
 10 verbs: ["get", "watch", "list"]
 11---
 12apiVersion: rbac.authorization.k8s.io/v1
 13kind: ClusterRoleBinding
 14metadata:
 15 name: otel-node-collector
 16roleRef:
 17 apiGroup: rbac.authorization.k8s.io
 18 kind: ClusterRole
 19 name: otel-node-collector
 20subjects:
 21 - kind: ServiceAccount
 22 name: otel-node-collector
 23 namespace: cluster
 24---
 25apiVersion: opentelemetry.io/v1beta1
 26kind: OpenTelemetryCollector
 27metadata:
 28 name: otel-node
 29 namespace: cluster
 30 labels:
 31 app: otel-node-collector
 32spec:
 33 mode: daemonset
 34 resources:
 35 # requests:
 36 # cpu: 10m
 37 # memory: 10Mi
 38 limits:
 39 cpu: 500m
 40 memory: 1000Mi
 41 podAnnotations:
 42 prometheus.io/scrape: "true"
 43 prometheus.io/port: "8888"
 44 env:
 45 - name: NODE_NAME
 46 valueFrom:
 47 fieldRef:
 48 fieldPath: spec.nodeName
 49 # volumes:
 50 # - name: hostfs
 51 # hostPath:
 52 # path: /
 53 # volumeMounts:
 54 # - name: hostfs
 55 # mountPath: /hostfs
 56 # readOnly: true
 57 # mountPropagation: HostToContainer
 58 config:
 59 extensions:
 60 health_check: # for k8s liveness and readiness probes
 61 endpoint: 0.0.0.0:13133 # default
 62
 63 processors:
 64 batch: # buffer up to 10000 spans, metric data points, log records for up to 5 seconds
 65 send_batch_size: 10000
 66 timeout: 5s
 67 memory_limiter:
 68 check_interval: 1s # recommended by official README
 69 limit_percentage: 80 # in 1Gi memory environment, hard limit is 800Mi
 70 spike_limit_percentage: 25 # in 1Gi memory environment, soft limit is 500Mi (800 - 250 = 550Mi)
 71
 72 service:
 73 extensions:
 74 - health_check
 75
 76 telemetry:
 77 logs:
 78 level: INFO
 79 metrics:
 80 address: 0.0.0.0:8888
 81
 82 pipelines:
 83 metrics:
 84 receivers:
 85 - kubeletstats
 86 # - hostmetrics
 87 processors:
 88 - memory_limiter
 89 - batch
 90 exporters:
 91 - otlphttp/prometheus
 92
 93 receivers:
 94 kubeletstats:
 95 auth_type: serviceAccount
 96 endpoint: https://${env:NODE_NAME}:10250
 97 collection_interval: 10s
 98 insecure_skip_verify: true
 99 extra_metadata_labels:
100 - k8s.volume.type
101 k8s_api_config:
102 auth_type: serviceAccount
103 metric_groups:
104 - node
105 - pod
106 - container
107 - volume
108
109 # hostmetrics:
110 # collection_interval: 10s
111 # root_path: /hostfs
112 # scrapers:
113 # cpu: # CPU utilization metrics
114 # load: # CPU load metrics
115 # memory: # Memory utilization
116 # disk: # Disk I/O metrics
117 # filesystem: # File System utilization metrics
118 # network: # Network interface I/O metrics & TCP connection metrics
119 # paging: # Paging/Swap space utilization and I/O metrics
120 # processes: # Process count metrics
121 # process: # Per process CPU, Memory, and Disk I/O metrics
122 # # The following settings can be used to handle the error to work hostmetrics: 2024-05-12T01:06:30.683Z error scraperhelper/scrapercontroller.go:197 Error scraping metrics {"kind": "receiver", "name": "hostmetrics", "data_type": "metrics", "error": "error reading process executable for pid 1: readlink /hostfs/proc/1/exe: permission denied; error reading username for process \"systemd\" (pid 1): open /etc/passwd: no such file or directory;
123 # # refer: https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/28661
124 # mute_process_name_error: true
125 # mute_process_exe_error: true
126 # mute_process_io_error: true
127 # mute_process_user_error: true
128 # mute_process_cgroup_error: true
129
130 exporters:
131 debug:
132 verbosity: basic # detailed, basic
133
134 otlphttp/prometheus:
135 metrics_endpoint: http://prometheus-server.cluster.svc.cluster.local:80/api/v1/otlp/v1/metrics
136 tls:
137 insecure: true

Cluster Collector(Single Pod) #

k8s events(log)
k8s objects(metrics)

단일 replica 사용 권장인 receivers 대상으로,\ 이들 receiver는 2개 이상의 instance 사용 시 중복이 발생 가능하기 때문이라고 공식 문서에서 논한다.\ 두 receiver 모두 cluster 관점에서 추출하기 때문이라고. 이에 따라 deployment type에 1개의 replica로 설정한다.

Log | Kubernetes Objects #

주로 Kubernetes event 수집용으로 Kubernetes API server 출처의 objects(전체 목록은 kubectl api-resources 로 확인) 수집에도 사용한다.

Receiver: Kubernetes Objects Receiver
Exporter: Loki exporter

Metric | Kubernetes Cluster #

사실 상 Kube State Metrics의 대체로 Kubernetes API server에서 cluster level의 metric과 entity events를 추출한다.

Receiver: Kubernetes Cluster Receiver
Exporter: OTLP/HTTP Exporter

 1apiVersion: v1
 2kind: ServiceAccount
 3metadata:
 4 name: otel-collector-opentelemetry-collector
 5---
 6apiVersion: rbac.authorization.k8s.io/v1
 7kind: ClusterRole
 8metadata:
 9 name: otel-collector-opentelemetry-collector
 10rules:
 11 - apiGroups:
 12 - ''
 13 resources:
 14 - events
 15 - namespaces
 16 - namespaces/status
 17 - nodes
 18 - nodes/spec
 19 - pods
 20 - pods/status
 21 - replicationcontrollers
 22 - replicationcontrollers/status
 23 - resourcequotas
 24 - services
 25 verbs:
 26 - get
 27 - list
 28 - watch
 29 - apiGroups:
 30 - apps
 31 resources:
 32 - daemonsets
 33 - deployments
 34 - replicasets
 35 - statefulsets
 36 verbs:
 37 - get
 38 - list
 39 - watch
 40 - apiGroups:
 41 - extensions
 42 resources:
 43 - daemonsets
 44 - deployments
 45 - replicasets
 46 verbs:
 47 - get
 48 - list
 49 - watch
 50 - apiGroups:
 51 - batch
 52 resources:
 53 - jobs
 54 - cronjobs
 55 verbs:
 56 - get
 57 - list
 58 - watch
 59 - apiGroups:
 60 - autoscaling
 61 resources:
 62 - horizontalpodautoscalers
 63 verbs:
 64 - get
 65 - list
 66 - watch
 67---
 68apiVersion: rbac.authorization.k8s.io/v1
 69kind: ClusterRoleBinding
 70metadata:
 71 name: otel-collector-opentelemetry-collector
 72roleRef:
 73 apiGroup: rbac.authorization.k8s.io
 74 kind: ClusterRole
 75 name: otel-collector-opentelemetry-collector
 76subjects:
 77 - kind: ServiceAccount
 78 name: otel-collector-opentelemetry-collector
 79 namespace: default
 80---
 81# otel-cluster-collector service accounts are created automatically
 82apiVersion: opentelemetry.io/v1beta1
 83kind: OpenTelemetryCollector
 84metadata:
 85 name: otel-cluster
 86 namespace: cluster
 87 labels:
 88 app: otel-cluster-collector
 89spec:
 90 mode: deployment
 91 replicas: 1
 92 podAnnotations:
 93 prometheus.io/scrape: "true"
 94 prometheus.io/port: "8888"
 95 config:
 96 extensions:
 97 health_check: # for k8s liveness and readiness probes
 98 endpoint: 0.0.0.0:13133 # default
 99
100 processors:
101 batch: # buffer up to 10000 spans, metric data points, log records for up to 5 seconds
102 send_batch_size: 10000
103 timeout: 5s
104 memory_limiter:
105 check_interval: 1s # recommended by official README
106 limit_percentage: 80 # in 1Gi memory environment, hard limit is 800Mi
107 spike_limit_percentage: 25 # in 1Gi memory environment, soft limit is 500Mi (800 - 250 = 550Mi)
108 attributes:
109 actions:
110 key: elasticsearch.index.prefix
111 value: otel-k8sobject
112 action: insert
113 service:
114 extensions:
115 - health_check
116
117 telemetry:
118 logs:
119 level: DEBUG
120 metrics:
121 address: 0.0.0.0:8888
122
123 pipelines:
124 logs:
125 receivers:
126 - k8sobjects
127 processors:
128 - memory_limiter
129 - batch
130 - attributes
131 exporters:
132 - debug
133 - elasticsearch
134
135 metrics:
136 receivers:
137 - k8s_cluster
138 processors:
139 - memory_limiter
140 - batch
141 exporters:
142 - otlphttp/prometheus
143
144 receivers:
145 k8sobjects:
146 objects:
147 - name: pods
148 mode: pull
149 - name: events
150 mode: watch
151 k8s_cluster:
152 collection_interval: 10s
153 node_conditions_to_report:
154 - Ready
155 - MemoryPressure
156 allocatable_types_to_report:
157 - cpu
158 - memory
159 - ephemeral-storage
160 - storage
161
162 exporters:
163 debug:
164 verbosity: detailed # default is basic
165
166 otlphttp/prometheus:
167 metrics_endpoint: http://prometheus-server.cluster.svc.cluster.local:80/api/v1/otlp/v1/metrics
168 tls:
169 insecure: true
170
171 elasticsearch:
172 endpoints:
173 - http://elasticsearch-es-http.cluster.svc.cluster.local:9200
174 logs_index: ""
175 logs_dynamic_index:
176 enabled: true
177 logstash_format:
178 enabled: true
179 user: anyflow
180 password: mycluster

 1apiVersion: opentelemetry.io/v1beta1
 2kind: OpenTelemetryCollector
 3metadata:
 4 name: otel-cluster-k8s-events
 5 namespace: cluster
 6 labels:
 7 app: otel-cluster-collector
 8spec:
 9 mode: deployment
10 replicas: 1
11 config:
12 receivers:
13 k8s_events:
14 auth_type: serviceAccount
15
16 processors:
17 batch:
18
19 exporters:
20 loki:
21 endpoint: https://LOKI_USERNAME:ACCESS_POLICY_TOKEN@LOKI_URL/loki/api/v1/push or http://<Loki-svc>.<Loki-Namespace>.svc/loki/api/v1/push
22 service:
23 pipelines:
24 logs:
25 receivers: [k8s_events]
26 processors: [batch]
27 exporters: [loki]

prometheus Collector(statefulset) #

prometheus metrics

OTLP Collector(Deployment) #

Traces(OTEL)
Generic OTEL Logs
Generic OTEL metrics

공용 receiver, exporter 공통적으로 otlp 프로토콜을 사용하고 replica 개수 제약이 없는 signal 대상 collector로서,\ 제약이 없을 경우 가장 운용에 유리한 배포 패턴인 Deployment 를 사용한다. MLT 모두를 대상으로 한다.

Trace | Generic OTEL trace #

Jaeger 및 Grafana Tempo는 OTLP Receiver를 자체적으로 지원한다.

Receiver: OTLP Receiver
Exporter: OTLP Exporter (gRPC)

Metric | Generic OTEL metric #

앞서 논한 metric 이외의 app level metrics 등의 여타 metric 수집을 위한 endpoint이다.

Receiver: OTLP Receiver
Exporter: OTLP/HTTP Exporter

Log | Generic OTEL log #

Istio의 OTel access log를 포함한 여타 log 수집을 위한 endpoint이다.

Receiver: OTLP Receiver
Exporter: Loki exporter

 1# otel-otlp-collector service accounts are created automatically
 2apiVersion: opentelemetry.io/v1beta1
 3kind: OpenTelemetryCollector
 4metadata:
 5 name: otel-otlp
 6 namespace: cluster
 7 labels:
 8 app: otel-otlp-collector
 9spec:
 10 mode: deployment
 11 # replicas: 1
 12 autoscaler:
 13 minReplicas: 1
 14 maxReplicas: 2
 15 resources:
 16 # requests:
 17 # cpu: 10m
 18 # memory: 10Mi
 19 limits:
 20 cpu: 500m
 21 memory: 1000Mi
 22 podAnnotations:
 23 prometheus.io/scrape: "true"
 24 prometheus.io/port: "8888"
 25 config:
 26 extensions:
 27 health_check: # for k8s liveness and readiness probes
 28 endpoint: 0.0.0.0:13133 # default
 29
 30 processors:
 31 batch: # buffer up to 10000 spans, metric data points, log records for up to 5 seconds
 32 send_batch_size: 10000
 33 timeout: 5s
 34 memory_limiter:
 35 check_interval: 1s # recommended by official README
 36 limit_percentage: 80 # in 1Gi memory environment, hard limit is 800Mi
 37 spike_limit_percentage: 25 # in 1Gi memory environment, soft limit is 500Mi (800 - 250 = 550Mi)
 38
 39 service:
 40 extensions:
 41 - health_check
 42
 43 telemetry:
 44 logs:
 45 level: INFO
 46 metrics:
 47 address: 0.0.0.0:8888
 48
 49 pipelines:
 50 traces:
 51 receivers:
 52 - otlp
 53 processors:
 54 - memory_limiter
 55 - batch
 56 exporters:
 57 - debug
 58 - otlp/jaeger
 59
 60 logs:
 61 receivers:
 62 - otlp
 63 processors:
 64 - memory_limiter
 65 - batch
 66 exporters:
 67 - debug
 68 - elasticsearch
 69
 70 metrics:
 71 receivers:
 72 - otlp
 73 processors:
 74 - memory_limiter
 75 - batch
 76 exporters:
 77 - debug
 78 - otlphttp/prometheus
 79
 80 receivers:
 81 otlp:
 82 protocols:
 83 grpc:
 84 endpoint: 0.0.0.0:4317
 85 http:
 86 endpoint: 0.0.0.0:4318
 87
 88 exporters:
 89 debug:
 90 verbosity: basic # detailed, basic
 91
 92 otlp/jaeger:
 93 endpoint: jaeger-collector.istio-system.svc.cluster.local:4317
 94 tls:
 95 insecure: true
 96
 97 otlphttp/prometheus:
 98 metrics_endpoint: http://prometheus-server.cluster.svc.cluster.local:80/api/v1/otlp/v1/metrics
 99 tls:
100 insecure: true
101
102 elasticsearch:
103 endpoints:
104 - http://elasticsearch-es-http.cluster.svc.cluster.local:9200
105 logs_index: "istio-access-log"
106 logs_dynamic_index:
107 enabled: true
108 logstash_format:
109 enabled: true
110 user: anyflow
111 password: mycluster

[Kubernetes] Install OTel(OpenTelemetry) Operator Using Helm Chart

Sun, 09 Jun 2024 00:00:00 +0000

Helm 설치 및 설명 참고 {: .prompt-info }

🔀 OTEL 예시 흐름: #

graph TD
 A[Application] --> B[OTel SDK]
 B --> C[OTel Collector]
 C --> D[Logs]
 C --> E[Metrics]
 C --> F[Traces]
 D --> G[Loki]
 E --> H[Prometheus]
 F --> I[Tempo/Jaeger]

Install Cert-manager #

1kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

OTel(OpenTelemetry) 설치 시 Cert-manager가 필요한 이유 #

HTTPS 통신 보안 OTel(OpenTelemetry) Collector는 기본적으로 HTTP를 통해 데이터를 수집하고 전송하지만,\ HTTPS를 사용하여 보안을 강화하는 것이 좋다.\ Cert-manager는 인증서 발급 및 관리를 자동화하여 OTel(OpenTelemetry) Collector가 안전하게 HTTPS를 사용하도록 설정하는 데 도움을 준다.
인증서 자동 갱신 HTTPS 인증서는 만료 기간이 있으며, 만료되면 OTel(OpenTelemetry) Collector가 작동하지 않게 된다.\ Cert-manager는 인증서가 만료되기 전에 자동으로 갱신하여 서비스 중단을 방지한다.
사용 편의성 향상 Cert-manager를 사용하면 수동으로 인증서를 발급하고 관리하는 번거로움 없이 OpenTelemetry Collector를 안전하게 배포하고 운영할 수 있다.

OTel(OpenTelemetry) 설치 시 반드시 Cert-manager가 필요한 것은 아니지만, HTTPS를 사용하여 보안을 강화하려는 경우 필수. Cert-manager는 Kubernetes 환경에서만 사용 가능. {: .prompt-warning }

Install OpenTelemetry Operator #

Install OpenTelemetry Operator

1kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

OpenTelemetry Operator - 설치 참고 {: .prompt-info }

Install Helm Chart - OpenTelemetry Operator

1helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
2helm repo update
3helm install opentelemetry-operator open-telemetry/opentelemetry-operator --set "manager.collectorImage.repository=otel/opentelemetry-collector-k8s"

OpenTelemetry Operator - Helm 설치 참고 {: .prompt-info }

Opentelemetry Operator가 관리하는 기능 두가지 #

Opentelemetry Collector
auto-instrumentation of the workloads using OpenTelemetry instrumentation libraries

프로젝트가 다수일 경우 매번 Opentelemetry Collector와 auto-instrumentation agent를 같이 띄울 필요 없이 Operator를 활용하여, 프로젝트별로 Collector를 설치할 수 있고 각 서버마다 agent를 명세할 필요 없이 annotation을 통하여 Operator가 해당 Pod에 sidecar 형태로 추가해준다.

OpenTelemetry Operator 사용하여 OpenTelemetry Collector 배포 할 수 있다. #

OpenTelemetry Collector #

collector에 대한 배포판은 3가지
- opentelemetry-collector : 핵심 기능을 제공
- opentelemetry-collector-contrib : Contrib은 opentelemetry-collector 확장하여 다양한 환경에서 사용될 수 있도록 제작
- opentelemetry-collector-k8s : opentelemetry-collector와 contrib의 구성요소 중 k8s cluster와 구성요소를 모니터링할 수 있도록 특별히 제작

Node Collector(Daemonset) #

File Logs
Host metrics
Kubelet state metrics
공식 문서에서 DaemonSet을 권장하는 receiver가 모인 collector이다.

Log | Filelog #

Receiver: Filelog Receiver
Exporter: Loki exporter

Metric | Kubelet Stats #

Receiver: Kubelet Stats Receiver
Exporter: OTLP/HTTP Exporter

Metric | Host Metrics #

Receiver: Host Metrics Receiver
Exporter: OTLP/HTTP Exporter

 1# otel-node-collector service accounts are created automatically
 2---
 3apiVersion: rbac.authorization.k8s.io/v1
 4kind: ClusterRole
 5metadata:
 6 name: otel-node-collector
 7rules:
 8 - apiGroups: [""]
 9 resources: ["nodes/stats", "nodes/proxy"]
 10 verbs: ["get", "watch", "list"]
 11---
 12apiVersion: rbac.authorization.k8s.io/v1
 13kind: ClusterRoleBinding
 14metadata:
 15 name: otel-node-collector
 16roleRef:
 17 apiGroup: rbac.authorization.k8s.io
 18 kind: ClusterRole
 19 name: otel-node-collector
 20subjects:
 21 - kind: ServiceAccount
 22 name: otel-node-collector
 23 namespace: cluster
 24---
 25apiVersion: opentelemetry.io/v1beta1
 26kind: OpenTelemetryCollector
 27metadata:
 28 name: otel-node
 29 namespace: cluster
 30 labels:
 31 app: otel-node-collector
 32spec:
 33 mode: daemonset
 34 resources:
 35 # requests:
 36 # cpu: 10m
 37 # memory: 10Mi
 38 limits:
 39 cpu: 500m
 40 memory: 1000Mi
 41 podAnnotations:
 42 prometheus.io/scrape: "true"
 43 prometheus.io/port: "8888"
 44 env:
 45 - name: NODE_NAME
 46 valueFrom:
 47 fieldRef:
 48 fieldPath: spec.nodeName
 49 # volumes:
 50 # - name: hostfs
 51 # hostPath:
 52 # path: /
 53 # volumeMounts:
 54 # - name: hostfs
 55 # mountPath: /hostfs
 56 # readOnly: true
 57 # mountPropagation: HostToContainer
 58 config:
 59 extensions:
 60 health_check: # for k8s liveness and readiness probes
 61 endpoint: 0.0.0.0:13133 # default
 62
 63 processors:
 64 batch: # buffer up to 10000 spans, metric data points, log records for up to 5 seconds
 65 send_batch_size: 10000
 66 timeout: 5s
 67 memory_limiter:
 68 check_interval: 1s # recommended by official README
 69 limit_percentage: 80 # in 1Gi memory environment, hard limit is 800Mi
 70 spike_limit_percentage: 25 # in 1Gi memory environment, soft limit is 500Mi (800 - 250 = 550Mi)
 71
 72 service:
 73 extensions:
 74 - health_check
 75
 76 telemetry:
 77 logs:
 78 level: INFO
 79 metrics:
 80 address: 0.0.0.0:8888
 81
 82 pipelines:
 83 metrics:
 84 receivers:
 85 - kubeletstats
 86 # - hostmetrics
 87 processors:
 88 - memory_limiter
 89 - batch
 90 exporters:
 91 - otlphttp/prometheus
 92
 93 receivers:
 94 kubeletstats:
 95 auth_type: serviceAccount
 96 endpoint: https://${env:NODE_NAME}:10250
 97 collection_interval: 10s
 98 insecure_skip_verify: true
 99 extra_metadata_labels:
100 - k8s.volume.type
101 k8s_api_config:
102 auth_type: serviceAccount
103 metric_groups:
104 - node
105 - pod
106 - container
107 - volume
108
109 # hostmetrics:
110 # collection_interval: 10s
111 # root_path: /hostfs
112 # scrapers:
113 # cpu: # CPU utilization metrics
114 # load: # CPU load metrics
115 # memory: # Memory utilization
116 # disk: # Disk I/O metrics
117 # filesystem: # File System utilization metrics
118 # network: # Network interface I/O metrics & TCP connection metrics
119 # paging: # Paging/Swap space utilization and I/O metrics
120 # processes: # Process count metrics
121 # process: # Per process CPU, Memory, and Disk I/O metrics
122 # # The following settings can be used to handle the error to work hostmetrics: 2024-05-12T01:06:30.683Z error scraperhelper/scrapercontroller.go:197 Error scraping metrics {"kind": "receiver", "name": "hostmetrics", "data_type": "metrics", "error": "error reading process executable for pid 1: readlink /hostfs/proc/1/exe: permission denied; error reading username for process \"systemd\" (pid 1): open /etc/passwd: no such file or directory;
123 # # refer: https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/28661
124 # mute_process_name_error: true
125 # mute_process_exe_error: true
126 # mute_process_io_error: true
127 # mute_process_user_error: true
128 # mute_process_cgroup_error: true
129
130 exporters:
131 debug:
132 verbosity: basic # detailed, basic
133
134 otlphttp/prometheus:
135 metrics_endpoint: http://prometheus-server.cluster.svc.cluster.local:80/api/v1/otlp/v1/metrics
136 tls:
137 insecure: true

Cluster Collector(Single Pod) #

k8s events(log)
k8s objects(metrics)

Log | Kubernetes Objects #

주로 Kubernetes event 수집용으로 Kubernetes API server 출처의 objects(전체 목록은 kubectl api-resources 로 확인) 수집에도 사용한다.

Receiver: Kubernetes Objects Receiver
Exporter: Loki exporter

Metric | Kubernetes Cluster #

사실 상 Kube State Metrics의 대체로 Kubernetes API server에서 cluster level의 metric과 entity events를 추출한다.

Receiver: Kubernetes Cluster Receiver
Exporter: OTLP/HTTP Exporter

 1apiVersion: v1
 2kind: ServiceAccount
 3metadata:
 4 name: otel-collector-opentelemetry-collector
 5---
 6apiVersion: rbac.authorization.k8s.io/v1
 7kind: ClusterRole
 8metadata:
 9 name: otel-collector-opentelemetry-collector
 10rules:
 11 - apiGroups:
 12 - ''
 13 resources:
 14 - events
 15 - namespaces
 16 - namespaces/status
 17 - nodes
 18 - nodes/spec
 19 - pods
 20 - pods/status
 21 - replicationcontrollers
 22 - replicationcontrollers/status
 23 - resourcequotas
 24 - services
 25 verbs:
 26 - get
 27 - list
 28 - watch
 29 - apiGroups:
 30 - apps
 31 resources:
 32 - daemonsets
 33 - deployments
 34 - replicasets
 35 - statefulsets
 36 verbs:
 37 - get
 38 - list
 39 - watch
 40 - apiGroups:
 41 - extensions
 42 resources:
 43 - daemonsets
 44 - deployments
 45 - replicasets
 46 verbs:
 47 - get
 48 - list
 49 - watch
 50 - apiGroups:
 51 - batch
 52 resources:
 53 - jobs
 54 - cronjobs
 55 verbs:
 56 - get
 57 - list
 58 - watch
 59 - apiGroups:
 60 - autoscaling
 61 resources:
 62 - horizontalpodautoscalers
 63 verbs:
 64 - get
 65 - list
 66 - watch
 67---
 68apiVersion: rbac.authorization.k8s.io/v1
 69kind: ClusterRoleBinding
 70metadata:
 71 name: otel-collector-opentelemetry-collector
 72roleRef:
 73 apiGroup: rbac.authorization.k8s.io
 74 kind: ClusterRole
 75 name: otel-collector-opentelemetry-collector
 76subjects:
 77 - kind: ServiceAccount
 78 name: otel-collector-opentelemetry-collector
 79 namespace: default
 80---
 81# otel-cluster-collector service accounts are created automatically
 82apiVersion: opentelemetry.io/v1beta1
 83kind: OpenTelemetryCollector
 84metadata:
 85 name: otel-cluster
 86 namespace: cluster
 87 labels:
 88 app: otel-cluster-collector
 89spec:
 90 mode: deployment
 91 replicas: 1
 92 podAnnotations:
 93 prometheus.io/scrape: "true"
 94 prometheus.io/port: "8888"
 95 config:
 96 extensions:
 97 health_check: # for k8s liveness and readiness probes
 98 endpoint: 0.0.0.0:13133 # default
 99
100 processors:
101 batch: # buffer up to 10000 spans, metric data points, log records for up to 5 seconds
102 send_batch_size: 10000
103 timeout: 5s
104 memory_limiter:
105 check_interval: 1s # recommended by official README
106 limit_percentage: 80 # in 1Gi memory environment, hard limit is 800Mi
107 spike_limit_percentage: 25 # in 1Gi memory environment, soft limit is 500Mi (800 - 250 = 550Mi)
108 attributes:
109 actions:
110 key: elasticsearch.index.prefix
111 value: otel-k8sobject
112 action: insert
113 service:
114 extensions:
115 - health_check
116
117 telemetry:
118 logs:
119 level: DEBUG
120 metrics:
121 address: 0.0.0.0:8888
122
123 pipelines:
124 logs:
125 receivers:
126 - k8sobjects
127 processors:
128 - memory_limiter
129 - batch
130 - attributes
131 exporters:
132 - debug
133 - elasticsearch
134
135 metrics:
136 receivers:
137 - k8s_cluster
138 processors:
139 - memory_limiter
140 - batch
141 exporters:
142 - otlphttp/prometheus
143
144 receivers:
145 k8sobjects:
146 objects:
147 - name: pods
148 mode: pull
149 - name: events
150 mode: watch
151 k8s_cluster:
152 collection_interval: 10s
153 node_conditions_to_report:
154 - Ready
155 - MemoryPressure
156 allocatable_types_to_report:
157 - cpu
158 - memory
159 - ephemeral-storage
160 - storage
161
162 exporters:
163 debug:
164 verbosity: detailed # default is basic
165
166 otlphttp/prometheus:
167 metrics_endpoint: http://prometheus-server.cluster.svc.cluster.local:80/api/v1/otlp/v1/metrics
168 tls:
169 insecure: true
170
171 elasticsearch:
172 endpoints:
173 - http://elasticsearch-es-http.cluster.svc.cluster.local:9200
174 logs_index: ""
175 logs_dynamic_index:
176 enabled: true
177 logstash_format:
178 enabled: true
179 user: anyflow
180 password: mycluster

 1apiVersion: opentelemetry.io/v1beta1
 2kind: OpenTelemetryCollector
 3metadata:
 4 name: otel-cluster-k8s-events
 5 namespace: cluster
 6 labels:
 7 app: otel-cluster-collector
 8spec:
 9 mode: deployment
10 replicas: 1
11 config:
12 receivers:
13 k8s_events:
14 auth_type: serviceAccount
15
16 processors:
17 batch:
18
19 exporters:
20 loki:
21 endpoint: https://LOKI_USERNAME:ACCESS_POLICY_TOKEN@LOKI_URL/loki/api/v1/push or http://<Loki-svc>.<Loki-Namespace>.svc/loki/api/v1/push
22 service:
23 pipelines:
24 logs:
25 receivers: [k8s_events]
26 processors: [batch]
27 exporters: [loki]

prometheus Collector(statefulset) #

prometheus metrics

OTLP Collector(Deployment) #

Traces(OTEL)
Generic OTEL Logs
Generic OTEL metrics

Trace | Generic OTEL trace #

Jaeger 및 Grafana Tempo는 OTLP Receiver를 자체적으로 지원한다.

Receiver: OTLP Receiver
Exporter: OTLP Exporter (gRPC)

Metric | Generic OTEL metric #

앞서 논한 metric 이외의 app level metrics 등의 여타 metric 수집을 위한 endpoint이다.

Receiver: OTLP Receiver
Exporter: OTLP/HTTP Exporter

Log | Generic OTEL log #

Istio의 OTel access log를 포함한 여타 log 수집을 위한 endpoint이다.

Receiver: OTLP Receiver
Exporter: Loki exporter

 1# otel-otlp-collector service accounts are created automatically
 2apiVersion: opentelemetry.io/v1beta1
 3kind: OpenTelemetryCollector
 4metadata:
 5 name: otel-otlp
 6 namespace: cluster
 7 labels:
 8 app: otel-otlp-collector
 9spec:
 10 mode: deployment
 11 # replicas: 1
 12 autoscaler:
 13 minReplicas: 1
 14 maxReplicas: 2
 15 resources:
 16 # requests:
 17 # cpu: 10m
 18 # memory: 10Mi
 19 limits:
 20 cpu: 500m
 21 memory: 1000Mi
 22 podAnnotations:
 23 prometheus.io/scrape: "true"
 24 prometheus.io/port: "8888"
 25 config:
 26 extensions:
 27 health_check: # for k8s liveness and readiness probes
 28 endpoint: 0.0.0.0:13133 # default
 29
 30 processors:
 31 batch: # buffer up to 10000 spans, metric data points, log records for up to 5 seconds
 32 send_batch_size: 10000
 33 timeout: 5s
 34 memory_limiter:
 35 check_interval: 1s # recommended by official README
 36 limit_percentage: 80 # in 1Gi memory environment, hard limit is 800Mi
 37 spike_limit_percentage: 25 # in 1Gi memory environment, soft limit is 500Mi (800 - 250 = 550Mi)
 38
 39 service:
 40 extensions:
 41 - health_check
 42
 43 telemetry:
 44 logs:
 45 level: INFO
 46 metrics:
 47 address: 0.0.0.0:8888
 48
 49 pipelines:
 50 traces:
 51 receivers:
 52 - otlp
 53 processors:
 54 - memory_limiter
 55 - batch
 56 exporters:
 57 - debug
 58 - otlp/jaeger
 59
 60 logs:
 61 receivers:
 62 - otlp
 63 processors:
 64 - memory_limiter
 65 - batch
 66 exporters:
 67 - debug
 68 - elasticsearch
 69
 70 metrics:
 71 receivers:
 72 - otlp
 73 processors:
 74 - memory_limiter
 75 - batch
 76 exporters:
 77 - debug
 78 - otlphttp/prometheus
 79
 80 receivers:
 81 otlp:
 82 protocols:
 83 grpc:
 84 endpoint: 0.0.0.0:4317
 85 http:
 86 endpoint: 0.0.0.0:4318
 87
 88 exporters:
 89 debug:
 90 verbosity: basic # detailed, basic
 91
 92 otlp/jaeger:
 93 endpoint: jaeger-collector.istio-system.svc.cluster.local:4317
 94 tls:
 95 insecure: true
 96
 97 otlphttp/prometheus:
 98 metrics_endpoint: http://prometheus-server.cluster.svc.cluster.local:80/api/v1/otlp/v1/metrics
 99 tls:
100 insecure: true
101
102 elasticsearch:
103 endpoints:
104 - http://elasticsearch-es-http.cluster.svc.cluster.local:9200
105 logs_index: "istio-access-log"
106 logs_dynamic_index:
107 enabled: true
108 logstash_format:
109 enabled: true
110 user: anyflow
111 password: mycluster

[Kubernetes] Install Grafana(v9.5.21) Using Helm Chart

Sat, 08 Jun 2024 00:00:00 +0000

Helm 설치 및 설명 참고 {: .prompt-info }

Install the Grafana Helm charts #

namespace 생성

1kubectl create namespace [NAMESPACE NAME]

Grafana 배포

1helm repo add grafana https://grafana.github.io/helm-charts
2helm repo update
3helm install grafana grafana/grafana --namespace [NAMESPACE NAME] --set adminPassword=<your_password>

Grafana - Helm 설치 참고

https://grafana.com/docs/grafana/latest/setup-grafana/installation/helm {: .prompt-info }

Password 설정하지 않았을 때, 아래와 같이 찾아보기

1kubectl get secret --namespace [NAMESPACE NAME] grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo

port-forward로 연결하기

1kubectl --namespace [NAMESPACE NAME] port-forward $POD_NAME 3000

1kubectl port-forward svc/grafana 3000:80 -n [NAMESPACE NAME]

Customize Default Configuration #

values.yaml 수정

최상위 values.yaml을 수정하면 하위 폴더 values.yaml을 override 한다. {: .prompt-info }
- Chart
  - https://github.com/grafana/helm-charts/tree/main/charts/grafana
- Release file (.tgz)
  - https://github.com/grafana/helm-charts/releases

Setting Admin #

1...✂...
2
3# Administrator credentials when not using an existing secret (see below)
4adminUser: admin
5adminPassword: <your_password>
6
7...✂...

Enable persistent storage (recommended) #

 1...✂...
 2
 3persistence:
 4 type: pvc
 5 enabled: true
 6 # storageClassName: default
 7 accessModes:
 8 - ReadWriteOnce
 9 size: 10Gi
10 # annotations: {}
11 finalizers:
12 - kubernetes.io/pvc-protection
13 # selectorLabels: {}
14 ## Sub-directory of the PV to mount. Can be templated.
15 # subPath: ""
16 ## Name of an existing PVC. Can be templated.
17 # existingClaim:
18 ## Extra labels to apply to a PVC.
19 extraPvcLabels: {}
20
21...✂...

외부 접속을 위한 NodePort 설정 #

 1...✂...
 2
 3## Expose the grafana service to be accessed from outside the cluster (LoadBalancer service).
 4## or access it from within the cluster (ClusterIP service). Set the service type and the port to serve it.
 5## ref: http://kubernetes.io/docs/user-guide/services/
 6##
 7service:
 8 enabled: true
 9 type: NodePort
10 loadBalancerIP: ""
11 loadBalancerClass: ""
12 loadBalancerSourceRanges: []
13 port: 80
14 targetPort: 3000
15 # targetPort: 4181 To be used with a proxy extraContainer
16 ## Service annotations. Can be templated.
17 annotations: {}
18 labels: {}
19 portName: service
20 # Adds the appProtocol field to the service. This allows to work with istio protocol selection. Ex: "http" or "tcp"
21 appProtocol: ""
22
23...✂...

Install Customize Default Configuration #

1helm install [RELEASE NAME] [Chart.yaml 경로] -f [YAML 파일 또는 URL에 값 지정 (여러 개를 지정가능)] -n [NAMESPACE NAME]

1helm install grafana grafana/grafana -f override-values.yaml -n [NAMESPACE NAME]

Uninstall the Chart #

1helm uninstall [RELEASE NAME] -n [NAMESPACE NAME]

[Error] K3S Install Helm

Thu, 06 Jun 2024 00:00:00 +0000

K3S에서 Helm 설치시 아래와 같이 ERROR 발생 #

1Error: INSTALLATION FAILED: Kubernetes cluster unreachable: Get "http://localhost:8080/version": dial tcp [::1]:8080: connect: connection refused

아래와 같이 설정 #

검색을 해보면 KUBECONFIG를 /etc/rancher/k3s/k3s.yaml 파일로 잡으라는 설명이 나온다.
```
1echo 'export KUBECONFIG=/etc/rancher/k3s/k3s.yaml' >> ~/.bashrc
2source ~/.bashrc
```

[Kubernetes] Install Kubernetes using Kubespray(v2.22.2) on VirtualBox

Sat, 01 Jun 2024 00:00:00 +0000

Kubespray? #

Kubespray는 Ansible 플레이북, 인벤토리, 프로비저닝 도구와 일반적인 운영체제, 쿠버네티스 클러스터의 설정 관리 작업에 대한 도메인 지식의 결합으로 만들어졌다. Kubespray는 아래와 같은 기능을 제공한다.
Kubespray 지원 사항
- 고가용성을 지닌 클러스터
- 구성 가능 (인스턴스를 위한 네트워크 플러그인 선택)
- 대부분의 인기있는 리눅스 배포판들에 대한 지원
  - Flatcar Container Linux by Kinvolk
  - Debian Bullseye, Buster, Jessie, Stretch
  - Ubuntu 16.04, 18.04, 20.04, 22.04
  - CentOS/RHEL 7, 8, 9
  - Fedora 35, 36
  - Fedora CoreOS
  - openSUSE Leap 15.x/Tumbleweed
  - Oracle Linux 7, 8, 9
  - Alma Linux 8, 9
  - Rocky Linux 8, 9
  - Kylin Linux Advanced Server V10
  - Amazon Linux 2
- 지속적인 통합 (CI) 테스트

Vagrant 설정 및 실행 #

Vagrant 설정 #

vagrant init

Vagrantfile 작성 #

require "yaml" 

CONFIG = YAML.load_file(File.join(File.dirname(__FILE__), "config.yaml"))

Vagrant.configure("2") do |config|
 # Use the same SSH key for all machines
 config.ssh.insert_key = false

 # masters
 CONFIG["masters"].each do |master|
 config.vm.define master["name"] do |cfg|
 cfg.vm.box = master["box"]
 cfg.vm.network "private_network", ip: master["ip"], virtualbox_intnet: true
 cfg.vm.hostname = master["hostname"]

 cfg.vm.provider "virtualbox" do |v|
 v.memory = master["memory"]
 v.cpus = master["cpu"]
 v.name = master["name"]
 v.customize ['modifyvm', :id, '--graphicscontroller', 'vmsvga']
 v.customize ['modifyvm', :id, '--hwvirtex', 'on']
 end
 cfg.vm.provision "shell", inline: <<-SCRIPT
 sed -i -e "s/PasswordAuthentication no/PasswordAuthentication yes/g" /etc/ssh/sshd _config
 systemctl restart sshd
 SCRIPT

 # set timezone & disable swap memory, ufw & enable ip forwarding
 cfg.vm.provision "shell", inline: <<-SCRIPT
 sudo apt-get update
 sudo timedatectl set-timezone "Asia/Seoul"
 sudo swapoff -a
 sudo sed -i "/swap/d" /etc/fstab
 sudo systemctl stop ufw
 sudo systemctl disable ufw
 sudo sed -i "s/#net.ipv4.ip_forward=1/net.ipv4.ip_forward=1/" /etc/sysctl.conf
 sudo sysctl -p
 SCRIPT

 # install python
 cfg.vm.provision "shell", inline: <<-SCRIPT
 sudo apt install python3-pip python3-setuptools virtualenv -y
 SCRIPT
 end
 end
 
 # worker nodes
 CONFIG["workers"].each do |worker|
 config.vm.define worker["name"] do |cfg|
 cfg.vm.box = worker["box"]
 cfg.vm.network "private_network", ip: worker["ip"], virtualbox_intnet: true
 cfg.vm.hostname = worker["hostname"]
 
 cfg.vm.provider "virtualbox" do |v|
 v.memory = worker["memory"]
 v.cpus = worker["cpu"]
 v.name = worker["name"]
 v.customize ['modifyvm', :id, '--graphicscontroller', 'vmsvga']
 v.customize ['modifyvm', :id, '--hwvirtex', 'on']
 end
 cfg.vm.provision "shell", inline: <<-SCRIPT
 sed -i -e "s/PasswordAuthentication no/PasswordAuthentication yes/g" /etc/ssh/sshd_config
 systemctl restart sshd
 SCRIPT

 # set timezone & disable swap memory & ufw & enable ip forwarding
 cfg.vm.provision "shell", inline: <<-SCRIPT
 sudo apt-get update
 sudo timedatectl set-timezone "Asia/Seoul"
 sudo swapoff -a
 sudo sed -i "/swap/d" /etc/fstab
 sudo systemctl stop ufw
 sudo systemctl disable ufw
 sudo sed -i "s/#net.ipv4.ip_forward=1/net.ipv4.ip_forward=1/" /etc/sysctl.conf
 sudo sysctl -p
 SCRIPT
 end
 end
end

config.yaml 작성 #

 1masters:
 2 - name: ks-master
 3 box: generic/ubuntu2004
 4 hostname: ks-master
 5 ip: 192.168.10.100
 6 memory: 4096
 7 cpu: 4
 8
 9workers:
10 - name: ks-worker-1
11 box: generic/ubuntu2004
12 hostname: ks-worker-1
13 ip: 192.168.10.210
14 memory: 4096
15 cpu: 4
16
17 - name: ks-worker-2
18 box: generic/ubuntu2004
19 hostname: ks-worker-2
20 ip: 192.168.10.220
21 memory: 4096
22 cpu: 4

Vagrant 실행 #

vagrant up

SSH 생성 및 설정 #

vagrant ssh ks-master

ssh-keygen -t rsa

ls -al .ssh/
cat .ssh/id_rsa.pub

ssh-copy-id vagrant@192.168.10.100
ssh-copy-id vagrant@192.168.10.210
ssh-copy-id vagrant@192.168.10.220

virtualenv --python=python3 venv

. venv/bin/activate

git clone https://github.com/kubernetes-sigs/kubespray
cd kubespray
git checkout v2.22.2

pip install -r requirements.txt

ansible --version

cp -rfp inventory/sample inventory/mycluster

declare -a IPS=(192.168.10.100 192.168.10.210 192.168.10.220)
CONFIG_FILE=inventory/mycluster/hosts.yaml python3 contrib/inventory_builder/inventory.py ${IPS[@]}

ansible all -m ping -i inventory/mycluster/hosts.yaml

vi inventory/mycluster/group_vars/k8s_cluster/addons.yml

ansible-playbook -i inventory/mycluster/hosts.yaml --become --become-user=root cluster.yml

deactivate

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

kubectl get nodes
kubectl get componentstatus
kubectl get --raw='/readyz?verbose'

vi inventory/mycluster/hosts.yaml #

 1all:
 2 hosts:
 3 ks-master:
 4 ansible_host: 192.168.10.100
 5 ip: 192.168.10.100
 6 access_ip: 192.168.10.100
 7 ks-worker-1:
 8 ansible_host: 192.168.10.210
 9 ip: 192.168.10.210
10 access_ip: 192.168.10.210
11 ks-worker-2:
12 ansible_host: 192.168.10.220
13 ip: 192.168.10.220
14 access_ip: 192.168.10.220
15 children:
16 kube_control_plane:
17 hosts:
18 ks-master:
19 kube_node:
20 hosts:
21 ks-worker-1:
22 ks-worker-2:
23 etcd:
24 hosts:
25 ks-master:
26 k8s_cluster:
27 children:
28 kube_control_plane:
29 kube_node:
30 calico_rr:
31 hosts: {}

[Kubernetes] Install K3S(v1.29.5+k3s1) on Multipass

Mon, 20 May 2024 00:00:00 +0000

VM deployments used multipass on mac #

master node 생성

1multipass launch --name k3s-master --cpus 2 --memory 4G --disk 50G focal

worker1 node 생성

1multipass launch --name k3s-worker1 --cpus 2 --memory 4G --disk 50G focal

worker2 node 생성

1multipass launch --name k3s-worker2 --cpus 2 --memory 4G --disk 50G focal

registry node 생성

1multipass launch --name registry --cpus 2 --memory 4G --disk 100G focal

ubuntu 구동 확인 #

1multipass list

1multipass ls

1multipass info --all

ubuntu swapoff #

master node swapoff

1multipass exec k3s-master -- /bin/bash -c "sudo swapoff -a"

worker1 node swapoff

1multipass exec k3s-worker1 -- /bin/bash -c "sudo swapoff -a"

worker2 node swapoff

1multipass exec k3s-worker2 -- /bin/bash -c "sudo swapoff -a"

registry node swapoff

1multipass exec registry -- /bin/bash -c "sudo swapoff -a"

ubuntu 메모리 사용량 확인 #

master node 메모리 사용량 확인

1multipass exec k3s-master -- /bin/bash -c "free -m"

worker1 node 메모리 사용량 확인

1multipass exec k3s-worker1 -- /bin/bash -c "free -m"

worker2 node 메모리 사용량 확인

1multipass exec k3s-worker2 -- /bin/bash -c "free -m"

registry node 메모리 사용량 확인

1multipass exec registry -- /bin/bash -c "free -m"

k3s master 설치 #

1multipass exec k3s-master -- /bin/bash -c "curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -"

k3s master Token 정보 조회 #

1multipass exec k3s-master -- /bin/bash -c "sudo cat /var/lib/rancher/k3s/server/node-token"

k3s worker Node 설치 #

1multipass exec k3s-node1 -- /bin/bash -c "curl -sfL https://get.k3s.io | K3S_TOKEN=\"<토큰 정보>\" K3S_URL=https://<마스터 노드 IP>:6443 sh -"

1K3S_NODEIP_MASTER="https://$(multipass info k3s-master | grep "IPv4" | awk -F' ' '{print $2}'):6443"
2K3S_TOKEN="$(multipass exec k3s-master -- /bin/bash -c "sudo cat /var/lib/rancher/k3s/server/node-token")"
3multipass exec k3s-worker1 -- /bin/bash -c "curl -sfL https://get.k3s.io | K3S_TOKEN=${K3S_TOKEN} K3S_URL=${K3S_NODEIP_MASTER} sh -"
4multipass exec k3s-worker2 -- /bin/bash -c "curl -sfL https://get.k3s.io | K3S_TOKEN=${K3S_TOKEN} K3S_URL=${K3S_NODEIP_MASTER} sh -"

k3s 노드 정보를 확인 한다. #

1multipass exec k3s-master kubectl get nodes

Copy multipass vm kubectl config locally #

계속 multipass cli를 사용하기는 귀찮으므로 k3s master node에서 k3s.yaml 파일을 로컬 Mac으로 가져온다.
kubectl은 미리 Mac에 설치 되어 있었고, 없다면 설치 해야 한다.

1multipass copy-files k3s-master:/etc/rancher/k3s/k3s.yaml ${HOME}/.kube/k3s.yaml
2sed -ie s,https://127.0.0.1:6443,${K3S_NODEIP_MASTER},g ${HOME}/.kube/k3s.yaml
3kubectl --kubeconfig=${HOME}/.kube/k3s.yaml get nodes

Configure cluster node roles and taint #

1NAME STATUS ROLES AGE VERSION
2k3s-master Ready control-plane,master 36m v1.29.5+k3s1
3k3s-worker1 Ready <none> 29m v1.29.5+k3s1
4k3s-worker2 Ready <none> 29m v1.29.5+k3s1

1kubectl --kubeconfig=${HOME}/.kube/k3s.yaml label node k3s-master node-role.kubernetes.io/master=""
2kubectl --kubeconfig=${HOME}/.kube/k3s.yaml label node k3s-worker1 node-role.kubernetes.io/node=""
3kubectl --kubeconfig=${HOME}/.kube/k3s.yaml label node k3s-worker2 node-role.kubernetes.io/node=""
4kubectl --kubeconfig=${HOME}/.kube/k3s.yaml taint node k3s-master node-role.kubernetes.io/master=effect:NoSchedule
5kubectl --kubeconfig=${HOME}/.kube/k3s.yaml get nodes -o wide

1NAME STATUS ROLES AGE VERSION
2k3s-worker1 Ready node 33m v1.29.5+k3s1
3k3s-worker2 Ready node 32m v1.29.5+k3s1
4k3s-master Ready control-plane,master 39m v1.29.5+k3s1

[Multipass] Setting Ubuntu

Sun, 19 May 2024 00:00:00 +0000

Multipass 설치 #

1brew install --cask multipass

공식 홈페이지 #

https://multipass.run 공식 홈페이지에서 직접 pkg를 받아 다운로드받을 수도 있다. 맥 OS 말고도 리눅스와 윈도우도 지원한다.

Multipass 사용 #

Instance 생성 #

현재 multipass를 통해 생성할 수 있는 Instance의 모든 Image 목록이 표시된다.
```
1multipass find
```
Instance 생성
```
1multipass launch
```
사용할 버전을 명시해줄 수도 있다.
```
1multipass launch 20.04
```

위와 같은 옵션 값을 통해 Instance의 스펙을 조절해줄 수 있다.

1multipass launch --cpus <cpus> --disk <disk> --memory <mem> --name <name> --cloud-init cloud-init.yaml

1-c, --cpus <cpus>
2할당할 CPU의 개수
3최소값 : 1, 기본값 : 1

1-d, --disk <disk>
2할당할 저장공간
3기본적으로 byte 단위이며, K, M, G 접미사를 붙여서 단위를 지정할 수 있다.

1-m, --memory <mem>
2할당할 메모리
3기본적으로 byte 단위이며, K, M, G 접미사를 붙여서 단위를 지정할 수 있다.

1-n, --name <name>
2Instance의 이름을 지정해준다.

1--cloud-init <file> | <url>
2Cloud 초기화 파일을 사용하여 가상 Instance를 설정한다. Cloud 초기화 파일은 yaml 형식의 설정 파일로, Instance 시작 시 다양한 초기 설정을 자동으로 수행할 수 있다.

Instance 목록 조회 #

list 명령어로 존재하는 Instance들을 확인할 수 있다. ls로 줄여쓸 수도 있다.
```
1multipass list
```

Instance Resource 변경 #

local.을 통해서 Resource를 변경할 수 있다.

1multipass stop some-instance
2multipass set local.some-instance.cpus=4
3multipass set local.some-instance.disk=40G
4multipass set local.some-instance.memory=8G

Instance의 Disk 크기를 늘릴 때 Partition이 자동으로 확장되지 않아 새로운 사용 가능한 공간을 사용하지 못할 수 있다.

이는 일반적으로 Disk 크기를 늘리려고 할 때 Partition이 이미 꽉 찬 경우에 발생한다. {: .prompt-warning }

다음과 같이 파티션을 수동으로 확장해야 한다. #

some-instance Shell에 접속

1$ multipass shell some-instance
2ubuntu@some-instance$ sudo parted /dev/sda resizepart 1 100%
3Warning: Not all of the space available to /dev/sda appears to be used, you can fix the GPT to use all of the space (an extra 4194304 blocks) or continue with the current setting?
4Fix/Ignore? fix
5Partition number? 1
6Warning: Partition /dev/sda1 is being used. Are you sure you want to continue?
7Yes/No? yes
8ubuntu@some-instance$ sudo resize2fs /dev/sda1

Instance Shell 접속 #

shell 명령어를 통해 해당 Instance의 쉘에 접근할 수 있다.
```
1multipass shell <instance name>
```

Instance 명령 실행 #

어느 Instance가 특정한 명령을 수행하길 원한다면, exec 명령어를 사용하면 된다. -- 하이픈 두개 뒤에 수행할 명령어를 기입해준다.
```
1multipass exec <instance name> -- <명령어>
```

Instance 정지 #

stop 명령어를 통해 Instance를 정지시킬 수 있다. 정지된 Instance는 State가 Stopped가 된다.
```
1multipass stop <instance name>
```

Instance 시작 #

start 명령어를 통해 정지되어 있던(Stopped 상태) Instance를 실행시킬 수 있다.
```
1multipass start <instance name>
```

Instance 삭제 #

delete 명령어를 통해 Instance를 삭제할 수 있다. 해당 명령어를 통해 Instance를 삭제할 경우, 완전히 없어지는 것이 아니다.
ls 명령을 통해 Instance 목록을 조회할 시, State가 deleted인 상태로 남아있다.
```
1multipass delete <instance name>
```

Instance 복구 #

recover 명령어를 통해 deleted 상태인 Instance를 복구할 수 있다. 복구된 Instance는 Stopped 상태가 된다.
```
1multipass recover <instance name>
```

Instance 영구 삭제 #

purge 명령어를 통해 deleted 상태인 Instance를 영구 삭제한다.
```
1multipass purge
```
delete와 purge를 한 번에 실행할 수 있다.
```
1multipass delete --purge <instance-name>
```

Multipass ssh 접속 #

가상 Instance에 일반적인 ssh 명령으로 Shell에 접속 시도하게 되면 permission denied로 접속이 되지 않는다.
이를 해결하기 위해서 다음 단계를 수행한다.
- ssh 키 생성
- Instance 생성시 적용될 yaml 파일 작성
- --cloud-init 옵션을 지정하여 Instance 생성

ssh key 생성 #

명령을 수행하면 $HOME/.ssh 경로에 id_rsa_multipass (개인키), id_rsa_multipass.pub (공개키) 파일이 생성된다.
```
1ssh-keygen -t rsa -b 2048 -f ~/.ssh/id_rsa_multipass
```

cloud-init 옵션에 적용할 yaml 파일 작성 #

ssh_authorized_keys 설정 항목에 id_rsa_multipass.pub 파일의 내용을 그대로 복사하여 설정하면 Instance 생성 시 지정된 공개키가 Instance에 적용된다.

Instance의 $HOME/.ssh/authorized_keys 파일에 공개키가 저장된다.

1users:
2 - default
3 - name: ubuntu
4 sudo: ALL=(ALL) NOPASSWD:ALL
5 ssh_authorized_keys:
6 - <id_rsa_multipass.pub 파일 내용>

Instance 생성 #

yaml 파일을 $HOME/multipass/cloud-init/cloud-init-ssh.yaml 경로에 저장한 경우 위와 같이 실행한다.
```
1multipass launch focal --name some-instance --cloud-init ~/multipass/cloud-init/cloud-init-ssh.yaml
```

ssh 접속

1ssh -i $HOME/.ssh/id_rsa_multipass ubuntu@192.168.64.2

-i 옵션과 함께 개인키 경로를 매번 지정하기 귀찮다면 $HOME/.ssh/config 파일에 다음과 같이 설정한다.
```
Host multipass-some-instance
 User ubuntu
 Hostname 192.168.64.2
 IdentityFile ~/.ssh/id_rsa_multipass
```
ssh 간편하게 접속
```
1ssh multipass-some-instance
```

Multipass Snapshot #

Snapshot 생성 #

1multipass snapshot <instance name> -n, --name <snapshot name> --comment, -c, -m <comment>
2multipass snapshot kk-repo -n kk-repo-snap-test -c test

Snapshot 이름 없이 생성 했을 시, snapshot(1,2,3…)으로 자동 저장된다. {: .prompt-tip }

Snapshot 조회 #

1multipass list --snapshots
2
3Instance Snapshot Parent Comment
4kk-repo kk-repo-snap-test -- test

Snapshot 복원 #

1multipass restore <instance name>.<snapshot name>
2multipass restore kk-repo.kk-repo-snap-test
3
4Do you want to take a snapshot of kk-repo before discarding its current state? (Yes/no): yes
5Snapshot taken: kk-repo.snapshot2
6Snapshot restored: kk-repo.kk-repo-snap-test

Snapshot 삭제 #

1multipass delete [options] <instance>[.snapshot] [<instance>[.snapshot] ...]
2multipass delete kk-repo.snapshot2
3
4Snapshots can only be purged (after deletion, they cannot be recovered). Are you sure you want to continue? (Yes/no): yes

Multipass Alias #

특정 Instance에서 명령을 실행하는 alias(별칭)을 만들어 사용할 수 있다.

Alias 등록 #

1multipass alias <instance-name>:<command> <alias-name>

Alias 목록 #

1multipass aliases

Alias 삭제 #

1multipass unalias <alias-name> ... <alias-name>
2multipass unalias --all

Alias 실행 #

1multipass <alias-name> -- <argument>

Shell 설정파일 (.bashrc, .zshrc, ..) 에 PATH 환경 변수에 아래 경로를 등록하면 multipass prefix는 생략 가능하다.

각 OS 마다 경로는 다음과 같지만 환경마다 다를 수 있다.
macOS의 경우 alias 등록 시 PATH 환경 변수에 추가할 경로가 안내된다. {: .prompt-tip }

1#MacOS m1 silicon
2$HOME/Library/Application Support/multipass/bin
3
4#Linux
5$HOME/snap/multipass/common/bin
6
7#Windows
8https://multipass.run/docs/using-aliases#heading--windows 참조

PATH 환경 변수에 경로가 추가되면 다음과 같이 multipass prefix 없이 사용 가능하다.
```
1<alias-name> --help
2<alias-name>
```

Multipass Mount #

multipass mount 명령을 사용하여 Host와 Instance 간의 데이터를 공유할 수 있다.

1# Instance 생성시 Mount
2multipass launch --mount <host-path>:<instance-path>
3# 이미 존재하는 Mount에 대해서 Mount 설정
4multipass mount <host-path> <instance-name>:<instance-path>

Multipass 복사 및 전송 #

복사 명령어 #

1multipass copy-files [복사할 파일 path] [설정한 multipass 이름]:[복사할 path]
2multipass copy-files C:\ProgramData\Multipass\data\ssh-keys\id_rsa primary:/home/ubuntu/.ssh/id_rsa

전송 명령어 #

1multipass transfer [options] <source> [<source> ...] <destination>

Instance ➡ Host로 파일 전송 #

1# some-instance의 /home/ubuntu/transfer_file을 Host의 $HOME/multipass_shared 경로에 전송한다.
2$ multipass transfer some-instance:/home/ubuntu/transfer_file $HOME/multipass_shared
3
4# some-instance의 /home/ubuntu/transfer_file 내용을 Host의 stdout 으로 출력한다.
5$ multipass transfer some-instance:/home/ubuntu/transfer_file -
6테스트용 전송 데이터
7테스트용 전송 데이터

Host ➡ Instance로 파일 전송 #

 1# Host의 $HOME/multipass_shared/directory1 Directory 전체를 
 2# some-instance의 /home/ubuntu/directory1 으로 전송한다.
 3$ multipass transfer -r $HOME/multipass_shared/directory1 some-instance:/home/ubuntu/
 4
 5# Host의 stdin (사용자 입력) 데이터를 some-instance의 /home/ubuntu/console_output 파일에 저장한다.
 6# 참고로 stdin 입력 종료는 Ctrl + D 로 종료한다.
 7$ multipass transfer - some-instance:/home/ubuntu/console_output
 8this is test message1
 9this is test message2
10this is test message3
11Ctrl + D
12
13# some-instance의 /home/ubuntu/console_outpout 파일 확인
14$ multipass exec some-instance -- cat /home/ubuntu/console_output
15this is test message1
16this is test message2
17this is test message3

cloud init examples

https://cloudinit.readthedocs.io/en/latest/reference/examples.html {: .prompt-info }

[Kubernetes] Install Tempo(v2.4.1) Using Helm Chart

Thu, 09 May 2024 00:00:00 +0000

Tempo #

트레이스(Trace)는 시스템, 소프트웨어 응용 프로그램 또는 사용자의 이벤트 또는 활동이 시간 순서대로 기록된 정보를 나타낸다.
Application이 단일 데이터베이스가 있는 모놀리식이든 여러 서비스가 있는 분산 시스템이든 관계없이 Application에서 요청이 취하는 전체 “경로"를 이해하려면 트레이스가 필수적이다.
메트릭(Metric)과 로그(Log)은 특정 시스템 내부에서의 동작을 볼 수 있지만, 분산 시스템에서의 문제 해결에는 부족하다.
이러한 이유로 트레이스가 필요하며, 이는 디버깅, 성능 분석 및 다양한 시나리오에서의 Application 동작 이해와 같은 다양한 목적으로 사용될 수 있다.
Tempo는 Grafana Labs에서 개발한 오픈 소스 분산 추적 백엔드(distributed tracing backend)
- 이는 매우 효율적이고 확장 가능한 방식으로 트레이스 데이터를 저장, 인덱싱 및 검색하기 위해 설계되었다.
- Tempo는 Grafana 옵저버빌리티(Observability) 스택의 일부이며, Grafana, Prometheus 및 Loki와 긴밀하게 통합된다.
- 비용 효율적이며 작동하는 데 오브젝트 스토리지만 필요하다.
- Jaeger, Zipkin 또는 OpenTelemetry를 포함한 오픈 소스 추적 프로토콜과 함께 Tempo를 사용할 수 있다.
- Tempo는 LogQL과 PromQL에서 영감을 얻은 추적 우선 쿼리 언어인 TraceQL을 구현한다.
  - 이 쿼리 언어를 사용하면 사용자는 매우 정확하고 쉽게 스팬(Span)을 선택하고 지정된 조건을 충족하는 스팬으로 바로 이동할 수 있다.

Helm 설치 및 설명 참고 {: .prompt-info }

Install the Tempo Helm charts #

1helm repo add grafana https://grafana.github.io/helm-charts
2helm repo update
3helm install tempo grafana/tempo --namespace [NAMESPACE NAME]

Tempo - Helm 설치 참고

https://grafana.com/docs/tempo/latest/setup/helm-chart/ {: .prompt-info }

Customize Default Configuration #

values.yaml 수정

최상위 values.yaml을 수정하면 하위 폴더 values.yaml을 override 한다. {: .prompt-info }
- Chart
  - https://github.com/grafana/helm-charts/tree/main/charts/tempo
- Release file (.tgz)
  - https://github.com/grafana/helm-charts/releases

Setting Config #

Install Customize Default Configuration #

1helm install [RELEASE NAME] [Chart.yaml 경로] -f [YAML 파일 또는 URL에 값 지정 (여러 개를 지정가능)] -n [NAMESPACE NAME]

1helm install tempo grafana/tempo -f override-values.yaml -n [NAMESPACE NAME]

Uninstall the Chart #

1helm uninstall [RELEASE NAME] -n [NAMESPACE NAME]

[Kubernetes] Install Loki(v2.9.4) Stack Using Helm Chart

Fri, 19 Apr 2024 00:00:00 +0000

Helm 설치 및 설명 참고 {: .prompt-info }

Install the Loki Stack Helm charts #

1helm repo add grafana https://grafana.github.io/helm-charts
2helm repo update
3helm install loki-stack grafana/loki-stack --namespace [NAMESPACE NAME] --version [VERSION]

Loki Stack - Helm 설치 참고

https://grafana.com/docs/loki/latest/setup/install/helm/ {: .prompt-info }

Customize Default Configuration #

values.yaml 수정

최상위 values.yaml을 수정하면 하위 폴더 values.yaml을 override 한다. {: .prompt-info }
- Chart
  - https://github.com/grafana/helm-charts/tree/main/charts/loki-stack
- Release file (.tgz)
  - https://github.com/grafana/helm-charts/releases

Setting Promtail #

1promtail:
2 enabled: true
3 config:
4 logLevel: info
5 serverPort: 3101
6 clients:
7 - url: http://{{ .Release.Name }}:3100/loki/api/v1/push

Promtail 설치 및 설정 관련 참고 {: .prompt-info }

Setting Loki #

 1loki:
 2 enabled: true
 3 isDefault: true
 4 url: http://{{(include "loki.serviceName" .)}}:{{ .Values.loki.service.port }}
 5 readinessProbe:
 6 httpGet:
 7 path: /ready
 8 port: http-metrics
 9 initialDelaySeconds: 45
10 livenessProbe:
11 httpGet:
12 path: /ready
13 port: http-metrics
14 initialDelaySeconds: 45
15 datasource:
16 jsonData: "{}"
17 uid: ""

Loki 관련 참고 {: .prompt-info }

Setting Grafana #

 1grafana:
 2 enabled: false
 3 sidecar:
 4 datasources:
 5 label: ""
 6 labelValue: ""
 7 enabled: true
 8 maxLines: 1000
 9 image:
10 tag: 10.3.3

Grafana 설치 및 설정 관련 참고 {: .prompt-info }

Install Customize Default Configuration #

1helm install [RELEASE NAME] [Chart.yaml 경로] -f [YAML 파일 또는 URL에 값 지정 (여러 개를 지정가능)] -n [NAMESPACE NAME]

1helm install loki-stack grafana/loki-stack -f override-values.yaml -n [NAMESPACE NAME]

Uninstall the Chart #

1helm uninstall [RELEASE NAME] -n [NAMESPACE NAME]

[Kubernetes] Loki(v2.9.4)

Sun, 07 Apr 2024 00:00:00 +0000

Loki #

Loki는 로그 전체 TEXT가 아닌 metadata만 인덱싱하는 방식을 취한다.
이런 최소 인덱싱 접근 방식은 다른 솔루션보다 적은 저장 공간이 필요함을 의미한다.
Loki를 위해 만들어진 로그 수집 도구인 Promtail 또는 OpenTelemetry를 통해 로그를 가져와 로그를 저장한다.
이후 Grafana에서 LogQL이라는 쿼리 언어를 통해 로그를 검색하게 된다.
또한 경고 규칙을 설정하여 Prometheus Alertmanager로 경고를 보낼 수 있다.

Loki 참고

https://github.com/grafana/loki {: .prompt-info }
“Like Prometheus, but for logs”
Prometheus가 metric을 시계열 데이터로 저장하기 위해 사용된다면 Loki는 log 데이터를 저장하기 위해 사용된다.
Loki는 log data를 효율적으로 보관하기 위해 최적화된 데이터 저장소이다.
다른 logging system과 다르게 Loki index는 label에서 작성되며 원래 log message는 색인화되지 않는다.
Prometheus가 저장과 polling을 담당한 것과 달리 Loki는 저장을 담당하고 application에서 push를 해주는 역할을 해주는 agent가 필요하다.
Promtail agent는 Loki를 위해 설계되었지만 그 외에 다른 많은 agent(FluentD, LogStash 혹은 기타 서비스 애플리케이션)가 Loki와 원활하게 통합된다.
Loki는 stream을 indexing 한다.
각 steam은 고유한 label set과 연결된 log 집합을 식별한다.
label의 quality set은 간결하고 효율적인 query 실행을 허용하는 index 생성의 핵심이다.
LogQL은 Loki의 query language이다.

Loki 특징 #

log indexing을 위한 효율적인 memory 사용
multi-tenancy
LogQL - Prometheus의 Query Language인 PromQL과 유사하며, log data에서 metric을 생성하는 것이 용이함.
Scalability - 단일 바이너리로 사용할 수도 있으나 component 별 microservice로 실행될 수도 있음
Flexibility - 많은 agent가 플러그인을 지원
Grafana 통합

Loki 저장소 #

Manage storage 참고

https://grafana.com/docs/loki/latest/operations/storage/ {: .prompt-info }
Loki는 chunk와 index라는 두 가지 유형의 데이터를 저장해야 한다.
Loki는 별도의 stream으로 log를 수신하며 각 steam은 tenant ID와 label set으로 고유하게 식별된다.
stream의 log 항목이 도착하면 chunk로 압축되어 chunk 저장소에 저장된다.
index는 각 steam의 label set를 저장하고 개별 chunk에 연결한다.
index에 대해 다음 저장소가 지원
- Single Store (boltdb-shipper)
- Amazon DynamoDB
- Google Bigtable
- Apache Cassandra
- BoltDB
chunk에 대해 다음 저장소가 지원
- Amazon DynamoDB
- Google Bigtable
- Apache Cassandra
- Amazon S3
- Google Cloud Storage
- FlieSystem
- Baidu Object Storage
기본 설정은 storage가 filesystem이며 Amazon S3의 경우 로컬에서 개발 시 minio를 사용할 수도 있다.

minio 참고
- https://blog.min.io/how-to-grafana-loki-minio/ {: .prompt-info }

Loki 설정 #

설정 파일에 대한 자세한 내용

https://grafana.com/docs/loki/latest/configuration/
common 아래에 설정을 하면 전체가 공통으로 사용할 설정을 하게 된다. {: .prompt-info }
Loki는 component별 microservice로 구성할 수 있다.

Component 참고
- https://grafana.com/docs/loki/latest/fundamentals/architecture/components/ {: .prompt-info }
Loki의 component는 대략 아래와 같이 있다.
- Distributor : client가 수신하는 stream을 처리하는 역할, steam의 유효성을 확인하고 여러 ingester로 병렬로 전송을 적절하게 제어
- Ingester : storage에 log data를 저장하고 write path 및 read path의 memory 내 쿼리에 대한 log data를 반환
- Query frontend : query 발송의 API endpoint를 제공하는 선택적 서비스
- Querier : LogQL을 사용하여 query를 처리하고 ingester와 storage에서 log를 가져옴

Loki Helm Charts #

grafana/loki 관련된 Helm chart들을 살펴보면 대략 5가지 정도가 존재
- grafana/loki : 현재 Grafana Loki에서 중점적으로 관리 및 업데이트하고 있는 Helm chart
- grafana/loki-distributed : Microservice 형태로 Loki를 관리할 수 있도록 해주는 Helm chart
  - Ingester, Querier, Index Gateway, Distributor, Query-Frontend, Ruler 등으로 구분되어 있음
- grafana/loki-simple-scalable : 현재 Deprecated 되었지만 Loki를 아주 간단하게 관리할 수 있도록 도와주는 Helm chart
  - Write와 Read, Nginx gateway로만 구분되어 있다.
- grafana/loki-stack : 올인원 모놀리식 형태로 사용할 수 있는 Loki Helm chart

1. loki-stack #

“loki-stack” Helm 차트는 Loki를 단일 노드로 구성하여 배포하는 방법을 제공한다.
이는 기본적인 Loki 설치를 위해 사용되며, 로그 수집, 저장 및 검색을 단일 노드에서 처리한다.
이 단일 노드는 다수의 컨테이너로 구성되어 Loki 서버, Prometheus, Grafana 및 Prometheus 메트릭 저장소를 모두 단일 클러스터에 배포한다.
이 단순한 배포 방식은 개발 및 테스트 용도로 적합할 수 있다.

loki-stack 설치 참고 {: .prompt-info }

2. loki-distributed #

“loki-distributed” Helm 차트는 Loki를 분산 환경에서 배포하기 위해 설계되었다.
이 차트는 Loki의 구성 요소들을 다수의 노드로 분산시키고, 데이터를 보다 효율적으로 처리하고 처리 능력을 확장할 수 있도록 도와준다.
분산된 Loki를 사용하면 대량의 로그를 처리하는 데 더 적합하며, 고가용성과 확장성을 갖추기 위해 다양한 구성을 가능하게 한다.

loki-distributed 설치 참고 {: .prompt-info }

Architecture #

핵심 개념
- Read Path와 Write Path : Loki는 로그 데이터 처리를 위한 읽기 경로(Read Path)와 쓰기 경로(Write Path)를 구분한다. 이러한 분리는 데이터 처리의 효율성을 극대화하며, 각 경로는 특정 작업에 최적화된 컴포넌트로 구성된다.
- Consistent Hash Rings : 클러스터 내에서 데이터를 균등하게 분배하고 고가용성을 보장하는 메커니즘이다. 이는 클러스터의 스케일링을 용이하게 하며, 데이터 샤딩과 복제를 통한 안정성을 제공한다.
- Multi-tenancy : Loki는 다중 테넌시를 지원하여, 하나의 Loki 인스턴스를 여러 사용자나 팀이 공유할 수 있게 한다. 이는 리소스의 효율적인 사용과 데이터 분리를 가능하게 한다.

Write Path: Distributor, Ingester #

Distributor #

클라이언트로부터 수신한 로그 데이터를 검증 후 Ingester에게 전달하는 역할을 담당한다. 여기서 클라이언트는 Promtail이 될 수도 있고 FluentD, LogStash 혹은 기타 서비스 애플리케이션 쪽 로그 라이브러리가 될 수도 있다.
Distributor의 주요 기능 및 특징
- 유효성 검사(Validation) : Distributor는 수신된 스트림이 Grafana LGTM 사양에 부합하는지 첫 번째로 확인한다. 이는 데이터가 올바르게 처리될 수 있는지를 보장하기 위한 필수적인 과정이다.
- 전처리(Preprocessing) : 스트림의 레이블을 정렬하는 과정으로, 이를 통해 Loki는 데이터를 효율적으로 캐시하고 해시할 수 있다.
- 속도 제한(Rate limiting) : 테넌트별 최대 전송률을 설정하여, 들어오는 로그의 전송률을 제어할 수 있다. 이는 시스템의 안정성을 유지하는 데 중요한 역할을 한다.
- 전달(Forwarding) : 모든 유효성 검사와 전처리 작업을 마친 후, 데이터는 Ingester로 전달된다. Ingester는 최종적으로 데이터의 쓰기를 승인하며, 이 과정에서 replication_factor를 참고하여 데이터 손실 위험을 최소화하기 위한 복제본을 생성한다.
- replication_factor가 3이라면 Ingester 내에 3개의 복제본을 생성하도록 3개의 스트림을 전달한다.
- 해싱(Hashing) : Distributor는 일관된 해싱을 사용해 특정 스트림이 전달될 Ingester 인스턴스를 결정한다. 이는 데이터가 올바른 대상에게 전달되도록 한다.
- 쿼럼 일관성(Quorum consistency) : Distributor는 최소 절반 이상의 Ingester로부터 응답을 받기 전까지는 클라이언트에게 응답을 보류한다. 이는 Dynamo 스타일의 쿼럼 일관성을 통해 데이터의 신뢰성을 높인다.
이러한 과정과 특징들은 Distributor가 Grafana Loki에서 매우 중요한 역할을 수행하게 한다.
특히, stateless한 성격 덕분에, 작업을 Ingester로 쉽게 확장하고 오프로드할 수 있으며, DDos 공격으로부터 시스템을 보호할 수 있다.
또한 distributor는 내부에서 링 component를 사용하여 peers 사이에서 자신을 등록하고 총 active distributors를 얻는다. 이는 ingesters가 링에서 사용하는 것과는 다른 “키"이며 distributor의 자체 링 구성에서 비롯된다. 이는 Distributor의 효율성과 안정성을 더욱 높인다.

Ingester #

Distributor로부터 받은 로그 데이터를 메모리에 압축하여 chunks 단위로 저장하고 일정 시간 후 장기 저장소 백엔드(DynamoDB, S3, Cassandra 등)에 기록하는 역할을 담당한다.
Ingester는 로그 데이터를 장기 저장소 백엔드(예: DynamoDB, S3, Cassandra 등)에 저장하고, 필요 시 인메모리 쿼리를 통해 이 데이터를 빠르게 검색하는 역할을 한다.
Ingester의 주요 기능 및 특징
- 수명 주기 관리 : Ingester 내에는 lifecycler라고 불리는 컴포넌트가 포함되어 있어, 해시 링을 통해 각 Ingester의 생명 주기를 관리한다. Ingester의 상태는 PENDING, JOINING, ACTIVE, LEAVING, 또는 UNHEALTHY 중 하나이다.
- chunk 처리 : 로그 스트림은 메모리 내에서 여러 ‘chunk’ 집합으로 관리되며, 설정 가능한 주기에 따라 장기 저장소 백엔드로 플러시된다. chunk는 용량에 도달하거나, 업데이트 없이 일정 시간이 지나거나, 플러시가 발생할 때 압축되고 읽기 전용으로 전환된다.
- 데이터 복제 : 갑작스러운 프로세스 종료나 충돌로 인해 아직 플러시되지 않은 데이터 손실을 방지하기 위해, Loki는 로그 데이터를 여러 Ingester에 복제한다(일반적으로 3개,replication_factor). 이는 데이터의 안정성과 가용성을 높인다.
- Timestamp Ordering : Loki는 설정을 통해 시간 순서가 뒤섞인 데이터 쓰기를 허용할 수 있다. 이러한 설정 없이는 Ingester가 순서대로 입력되는 로그 라인을 확인하고, 순서가 맞지 않는 경우 오류를 반환한다.
- 파일 시스템 지원 : Ingester는 BoltDB를 통해 파일 시스템에 쓰기를 지원하지만, queriers가 동일한 백엔드 저장소에 액세스해야 하고 BoltDB는 주어진 시간에 하나의 프로세스만 DB에 대한 잠금을 가질 수 있도록 허용하기 때문에 단일 프로세스 모드에서만 작동한다.
작동 방식
- 플러시 : 장기 저장소로의 플러시 과정에서, chunk는 테넌트, 레이블, 콘텐츠를 기반으로 해시되어 중복된 데이터의 백업 저장소 쓰기를 방지한다. 그러나 복제본 중 하나에 쓰기가 실패하면 여러 개의 서로 다른 chunk 객체가 생성될 수 있다.
이러한 기능과 특징들은 Ingester가 Grafana LGTM 아키텍처에서 중요한 역할을 수행하게 한다. 데이터의 안정적인 저장과 효율적인 검색을 보장하는 동시에, 시스템의 전반적인 신뢰성과 성능을 높이는 데 기여한다.

Write : 로그 스트림이 chunk에 저장되는 과정 #

distributor는 스트림(로그)에 대한 데이터를 저장하기 위한 HTTP/1 요청을 받는다.
각 스트림은 해시 링을 사용하여 해시된다.
distributor는 해시된 데이터를 각 스트림을 적절한 ingesters에 해당 복제본으로 보낸다.
각 ingesters는 스트림 데이터에 대해 chunk를 생성하거나 기존 chunk에 추가한다.
distributor는 HTTP/1 연결을 통해 성공 코드로 응답한다.

Read Path: Query frontend, Querier #

Query Frontend와 Querier의 조합은 Grafana Loki에서 데이터 검색과 분석을 위한 효율적이고 강력한 읽기 경로를 제공한다.
이러한 구조는 대규모 데이터 세트에 대한 쿼리 처리 시간을 줄이고, 시스템의 전반적인 성능과 확장성을 향상시키는 데 중요한 역할을 한다.
특히, 캐싱과 쿼리 분할 같은 기능은 쿼리 응답 시간을 단축시키고 사용자 경험을 개선하는 데 크게 기여한다.

Query-Frontend(optional service) #

실제 쿼리 실행에 필요한 Querier의 역할을 보조하며 읽기 경로를 가속화한다.
Query frontend는 내부적으로 쿼리를 조정하고 큐에 보관한다.
Query Frontend는 실제 쿼리를 실행하는 Querier를 보조하여 읽기 경로의 성능을 향상시키는 서비스이다.
이 서비스는 쿼리 실행을 더 효율적으로 만들기 위해 다음과 같은 주요 기능을 수행한다.
- 큐잉(Queueing) : 큰 쿼리로 인한 메모리 부족 문제를 방지하고, 공정한 스케줄링을 가능하게 한다. 이는 더 작은 쿼리의 병렬 실행을 통해 전체 소유 비용(TCO)을 줄이는 데 기여한다.
- 분할(Splitting) : 큰 쿼리를 여러 작은 쿼리로 분할하여 Querier의 메모리 부족 문제를 예방하고, 쿼리 결과를 더 빠르게 도출할 수 있도록 한다.
- 캐싱(Caching) : 쿼리 결과를 캐시하여 후속 쿼리에서 재사용합니다. 이는 쿼리 수행 시간을 단축시키고 전반적인 시스템 성능을 향상시키는 데 도움이 된다.
Query Frontend는 상태를 유지하지 않는 서비스로, 일반적으로 두 개의 복제본으로 운영되며, 이는 가용성을 높이면서도 리소스 사용을 최적화한다.

Querier #

Ingester의 in-memory 데이터를 쿼리 후 장기 저장소에서 Query Log를 가져와 Query-Frontend에게 데이터를 반환한다.
Ingester에서 복제 데이터를 가져올 수 있기 때문에 내부적으로 중복을 제거한다.
Querier는 LogQL 쿼리 언어를 사용하여 로그 데이터에 대한 쿼리를 처리한다.
- 인메모리 데이터 및 장기 저장소 쿼리 : 모든 Ingester에서 현재 메모리에 있는 데이터를 쿼리한 다음, 같은 쿼리를 장기 저장소에 대해서도 실행한다. 이는 실시간 데이터와 과거 데이터 모두에 대한 쿼리를 가능하게 한다.
- 중복 제거 : 복제로 인해 중복된 데이터를 수신할 수 있는데, Querier는 동일한 나노초(㎱) 타임스탬프, 레이블 세트 및 로그 메시지를 가진 데이터를 중복 제거하여 최종 쿼리 결과의 정확성을 보장한다.
Read Path에서 로그 스트림이 읽어지는 과정
1. querier는 데이터에 대한 HTTP/1 요청을 받는다.
2. querier는 인메모리 데이터에 대한 쿼리를 모든 ingesters에 전달한다.
3. ingesters는 읽기 요청을 수신하고 쿼리와 일치하는 데이터가 있는 경우 반환한다.
4. querier는 데이터를 반환한 ingesters가 없는 경우 백업 저장소에서 데이터를 느리게 로드하고 이에 대해 쿼리를 실행한다.
5. querier는 수신된 모든 데이터를 반복하고 중복을 제거하여 HTTP/1 연결을 통해 최종 데이터 세트를 반환한다.

Read #

Read 요청 시 querier에서 해당 요청을 수신한다.
querier는 ingester의 in-memory를 조회한다.
ingester에 캐시 된 데이터가 있는 경우 querier에게 반환하고, 데이터가 없는 경우 백업 저장소(S3)에서 데이터를 조회한다.
querier는 수신된 데이터가 중복 됐는지 확인 후 중복제거 진행하여 log를 제공한다.

Consistent Hash Rings #

로그 라인의 샤딩, 고가용성 구현, 그리고 클러스터의 수평적 확장성(scaling)을 용이하게 하는 데 사용된다.
해시 링은 Loki의 다양한 컴포넌트 간의 효율적인 데이터 분배와 관리를 가능하게 한다.
각각의 노드는 Loki 시스템 내의 특정 컴포넌트 인스턴스를 대표하며, 키-값 저장소에는 해당 인스턴스의 통신 정보가 저장된다.

일관된 해시 링의 주요 특징 및 용도 #

Distributor Ring : Distributor의 수를 계산하는 데 사용된다. 이는 로그 데이터가 어떻게 분산되어야 할지 결정하는 데 중요한 역할을 한다.
Ingester Ring : 로그 라인을 어느 Ingester에 전달할지 결정하는 데 사용된다. 이는 데이터의 안정적인 저장과 검색을 위한 효율적인 데이터 분배 메커니즘을 제공한다.
Query Scheduler Ring : 서비스 탐색에 사용된다. 쿼리 요청을 효율적으로 처리할 Querier를 결정하는 데 도움을 준다.
Compactor Ring : 로그 데이터의 압축을 담당할 인스턴스를 식별하는 데 사용된다. 이는 저장 공간의 효율적 사용과 데이터 처리 성능 향상에 기여한다.
Ruler Ring : 어떤 규칙 그룹을 평가할지 결정하는 데 사용된다. 이는 경고 및 메트릭 규칙을 효율적으로 관리하고 실행하는 데 중요하다.
Index Gateway Ring(선택적) : 어떤 게이트웨이가 특정 테넌트의 인덱스를 담당할지 결정하는 데 사용된다. 이는 인덱스 데이터의 관리와 접근성을 향상시킨다.

중요성 및 이점 #

일관된 해시 링은 Grafana Loki의 분산 시스템에서 데이터를 균등하게 분배하고, 컴포넌트 간의 효율적인 통신을 가능하게 하는 핵심 메커니즘이다.
이는 시스템의 확장성, 고가용성, 그리고 관리 용이성을 보장한다.
또한, 클러스터의 동적인 스케일 업과 스케일 다운을 지원하여, 변화하는 워크로드에 빠르게 대응할 수 있게 한다.
일관된 해시 링을 통한 데이터의 효율적인 분배는 리소스 사용 최적화와 시스템의 전반적인 성능 향상을 이끌어내며, Grafana Loki를 대규모 로그 데이터를 처리하는 강력한 도구로 만든다.

Multi-tenancy #

Grafana Loki는 멀티테넌트 모드를 지원하여, 여러 사용자 또는 팀이 동일한 Loki 인스턴스를 공유할 수 있도록 한다.
이 모드에서는 메모리와 장기 저장소에 있는 모든 데이터가 HTTP 요청의 X-Scope-OrgID 헤더에서 가져온 테넌트 ID에 따라 파티셔닝된다.
멀티테넌트 모드가 아닐 경우, 테넌트 ID는 “fake"로 설정되며, 이는 모든 사용자의 데이터가 동일한 인덱스와 저장된 chunk에 표시됨을 의미한다.
이 기능은 데이터의 격리와 보안을 강화하며, 리소스 사용의 효율성을 높인다.

Storage #

TSDB
- Loki 버전 2.8부터는 TSDB(Time Series Database)를 사용하여 인덱스 저장소로서 NoSQL 저장소에 의존하지 않고도 Loki를 실행할 수 있게 되었다.
- 이전 버전까지는 **Single Store(boltdb-shipper)**가 이 역할을 담당했다.
- TSDB를 사용하면 모든 데이터(chunk와 인덱스)를 단일 오브젝트 스토리지 백엔드에 저장할 수 있으며, 이는 운영의 단순화, 비용 절감, 그리고 성능 향상을 가능하게 한다.
- TSDB 어댑터를 통한 인덱스 저장은 chunk 저장 방식과 유사하게 진행되어, Loki의 데이터 관리 방식을 더욱 통합하고 효율적으로 만든다.
이러한 요소들은 Grafana Loki를 효과적으로 운영하기 위한 핵심적인 부분이며, 대규모 로그 데이터 관리 시스템의 설계와 구현에 중요한 기여를 한다.
Loki의 멀티테넌시 지원과 TSDB를 활용한 스토리지 관리는 사용자가 대규모 로그 데이터를 보다 유연하고 효율적으로 처리할 수 있게 돕는다.

Deployment modes #

Monolithic mode
- 하루에 최대 약 100GB의 읽기/쓰기 볼륨에 유용하다.
- Shared object store를 사용하여 라운드 로빈 방식 라우팅의 수평적 확장 구성 가능하다.
Simple scalable deployment mode
- 하루에 수백 GB를 초과하거나 읽기 및 쓰기 문제를 분리하려는 경우에 유용하다.
- 이 배포 모드는 하루에 몇 TB 이상의 로그로 확장할 수 있다.
Microservices mode
- components를 개별 마이크로서비스로 실행하면 마이크로서비스의 양을 늘려 확장할 수 있다.
- 마이크로서비스 모드는 규모가 매우 큰 Loki 클러스터 또는 확장 및 클러스터 작업을 더 많이 제어해야 하는 클러스터에 권장된다.

Compactor #

chunk 보관주기를 관리하고(retention), 테이블을 단일 인덱스 파일로 압축한다.
Compactor를 통한 보존은 boltdb-shipper 또는 tsdb store에서만 지원된다.
- Loki 2.8부터는 TSDB Store 사용이 권장이다. 이전에 사용하던 boltdb-shipper보다 효율적이고 빠르며 확장성이 뛰어나다.
  
  Loki Storage 참고
  - https://grafana.com/docs/loki/latest/storage/ {: .prompt-info }

Ruler #

사용자가 정의한 경고 규칙 기반으로 경고를 발생시키는 등 로그 데이터에 대한 경고를 관리한다.

WAL(Write Ahead Log) #

Loki에서는 WAL(Write Ahead Log)이라는 걸 사용하는데, 아래와 같은 예기치 않은 장애 상황을 방지해 준다.
1. 데이터(chunk)가 Ingesters로 들어오면, 먼저 이 데이터를 메모리 적재 및 WAL에 기록한다. WAL은 로컬 파일 시스템에 저장된다.
2. 예기치 않은 장애로 프로세스가 갑자기 중단되거나 다운되면, 메모리에 있는 데이터가 손실된다.
3. 장애가 복구되어 프로세스가 다시 시작되면 WAL에 저장된 데이터를 읽어와 메모리에 적재하여 장애 전의 상태로 복구된다.

Chunk Store #

Loki의 로그를 장기 저장하기 위한 저장소이다.

Index Gateway #

Querier, Ruler에게 Index 쿼리를 제공하기 위해 Object Storage 및 BoltDB 인덱스를 다운로드하고 동기화한다.
- 이렇게 하면 Grafana로부터 로그 검색 요청이 들어왔을 때 Querier나 Ruler가 불필요하게 일하지 않아도 된다.

Compactor와 Table Manager #

Grafana Loki의 로그 보존(Retention)은 Compactor 혹은 Table Manager에 의해 수행된다.
현재 Table Manager를 통한 Retention은 TTL을 통해 달성되며 boltdb-shipper, chunk/index store 모두 작동한다.
Compactor를 통한 Retention은 boltdb-shipper 저장소에서만 지원된다.
만약 Compactor로 Retention을 적용한다면 Table Manager는 필요로 하지 않게 될 수 있다.
현재 Grafana Loki에서는 Compactor를 중점적으로 개발중인 것 같다.

다음은 Compactor 설정 예시이다.

compactor:
 shared_store: s3
 retention_delete_delay: 2h
 retention_enabled: true

Compactor의 Retention은 limits_config에 설정해주면 된다.

Retention 설정 참고
- https://grafana.com/docs/loki/latest/operations/storage/retention/#configuring-the-retention-period {: .prompt-info }

API #

특정 데이터를 지우기 (Query 작성)
- 시간은 RFC3339, RFC3339Nano format만 지원한다.
- post: /loki/api/v1/delete?query={namespace="testns", app="testapp"}&start=1721166554&end=17263647383
- Compactor 설정한 시간 후에 삭제된다.
삭제 요청한 id를 삭제
- del: /loki/api/v1/delete?request_id=7148cf15
삭제 요청한 id 모두 삭제
- del: /loki/api/v1/delete
삭제 요청한 id 조회
- get: /loki/api/v1/delete

API 참고

https://grafana.com/docs/loki/latest/reference/loki-http-api/ {: .prompt-info }

[Kubernetes] Install Promtail(v2.9.4) Using Helm Chart

Tue, 02 Apr 2024 00:00:00 +0000

Promtail #

Loki가 로그를 저장하는 역할을 하면 Promtail은 application에서 로그를 전달하는 agent의 역할을 한다.
Promtail 이외에도 Bit, Fluentd, LogStash 등을 사용할 수 있다.
kubernetes는 node 별로 /var/log/pods 아래에 모든 Pod의 로그가 기록된다.
daemonset으로 설정하고 node별로 로그를 수집하도록 처리를 하면 된다.
설치 방식은 sidecar, daemonset 방식이 있는데 daemonset 방식을 추천한다고 한다.
- daemonset : 각 Node마다 promtail Pod가 실행되어 해당 Node 장비에서 실행 중인 Pod의 로그를 추적
- sidecar : 각 Pod에 container로 추가되어 실행, 해당 Pod 내부에서 로그 파일을 읽어서 Loki로 전송
Pod마다 agent 형태로 설정하는 것보다 daemonset을 하나 띄워 해당 node의 Pod들을 찾아 로그를 수집하는 것이 훨씬 편한 것 같다.
Prometheus가 저장소와 polling 역할을 같이 담당하는 반면 Promtail은 저장소의 역할은 하지 않고 로그를 찾아 저장소로 push 하는 역할을 한다.
하지만 설정 방식이나 문법은 크게 차이가 없다.

Helm 설치 및 설명 참고 {: .prompt-info }

Install the Promtail Helm charts #

1helm repo add grafana https://grafana.github.io/helm-charts
2helm repo update
3helm install promtail grafana/promtail --namespace [NAMESPACE NAME]

Promtail 설치 참고

https://grafana.com/docs/loki/latest/clients/promtail/installation/ {: .prompt-info }

Customize Default Configuration #

values.yaml 수정

최상위 values.yaml을 수정하면 하위 폴더 values.yaml을 override 한다. {: .prompt-info }
- Chart
  - https://github.com/grafana/helm-charts/tree/main/charts/promtail
- Release file (.tgz)
  - https://github.com/grafana/helm-charts/releases

Setting Volumes #

 1# -- Default volumes that are mounted into pods. In most cases, these should not be changed.
 2# Use `extraVolumes`/`extraVolumeMounts` for additional custom volumes.
 3# @default -- See `values.yaml`
 4defaultVolumes:
 5 - name: run
 6 hostPath:
 7 path: /run/promtail
 8 - name: containers
 9 hostPath:
10 path: /var/lib/docker/containers
11 - name: pods
12 hostPath:
13 path: /var/log/pods
14 - name: syslogs
15 hostPath:
16 path: /var/log
17
18# -- Default volume mounts. Corresponds to `volumes`.
19# @default -- See `values.yaml`
20defaultVolumeMounts:
21 - name: run
22 mountPath: /run/promtail
23 - name: containers
24 mountPath: /var/lib/docker/containers
25 readOnly: true
26 - name: pods
27 mountPath: /var/log/pods
28 readOnly: true
29 - name: syslogs
30 mountPath: /var/log
31 readOnly: true

Setting Config #

 1config:
 2 # -- Enable Promtail config from Helm chart
 3 # Set `configmap.enabled: true` and this to `false` to manage your own Promtail config
 4 # See default config in `values.yaml`
 5 enabled: true
 6 # -- The log level of the Promtail server
 7 # Must be reference in `config.file` to configure `server.log_level`
 8 # See default config in `values.yaml`
 9 logLevel: info
 10 # -- The log format of the Promtail server
 11 # Must be reference in `config.file` to configure `server.log_format`
 12 # Valid formats: `logfmt, json`
 13 # See default config in `values.yaml`
 14 logFormat: logfmt
 15 # -- The port of the Promtail server
 16 # Must be reference in `config.file` to configure `server.http_listen_port`
 17 # See default config in `values.yaml`
 18 serverPort: 3101
 19 # -- The config of clients of the Promtail server
 20 # Must be reference in `config.file` to configure `clients`
 21 # @default -- See `values.yaml`
 22 clients:
 23 - url: http://loki-gateway/loki/api/v1/push
 24 - basic_auth:
 25 password: ${LOKI_BASIC_AUTH_PW}
 26 username: ${LOKI_BASIC_AUTH_USER}
 27 external_labels:
 28 cluster: ${CLUSTER}
 29 url: ${LOKI_URL}
 30 # -- Configures where Promtail will save it's positions file, to resume reading after restarts.
 31 # Must be referenced in `config.file` to configure `positions`
 32
 33...✂...
 34
 35 snippets:
 36 pipelineStages:
 37 - cri: {}
 38 common:
 39 - action: replace
 40 source_labels:
 41 - __meta_kubernetes_pod_node_name
 42 target_label: node_name
 43 - action: replace
 44 source_labels:
 45 - __meta_kubernetes_namespace
 46 target_label: namespace
 47 - action: replace
 48 replacement: $1
 49 separator: /
 50 source_labels:
 51 - namespace
 52 - app
 53 target_label: job
 54 - action: replace
 55 source_labels:
 56 - __meta_kubernetes_pod_name
 57 target_label: pod
 58 - action: replace
 59 source_labels:
 60 - __meta_kubernetes_pod_container_name
 61 target_label: container
 62 - action: replace
 63 replacement: /var/log/pods/*$1/*.log
 64 separator: /
 65 source_labels:
 66 - __meta_kubernetes_pod_uid
 67 - __meta_kubernetes_pod_container_name
 68 target_label: __path__
 69 - action: replace
 70 replacement: /var/log/pods/*$1/*.log
 71 regex: true/(.*)
 72 separator: /
 73 source_labels:
 74 - __meta_kubernetes_pod_annotationpresent_kubernetes_io_config_hash
 75 - __meta_kubernetes_pod_annotation_kubernetes_io_config_hash
 76 - __meta_kubernetes_pod_container_name
 77 target_label: __path__
 78
 79...✂...
 80
 81 scrapeConfigs: |
 82 - job_name: syslog
 83 static_configs:
 84 - targets:
 85 - localhost
 86 labels:
 87 job: syslog
 88 __path__: /var/log/syslog
 89 pipeline_stages:
 90 - regex:
 91 expression: '^(?P<time>[^ ]* {1,2}[^ ]* [^ ]*) (?P<hostname>[^ ]*) (?P<daemon>[^ :\[]*)(?:\[(?P<pid>[0-9]+)\])?(?:[^\:]*\:)? *(?P<message>.*)$'
 92 - labels:
 93 time:
 94 hostname:
 95 daemon:
 96 pid:
 97 message:
 98 - match:
 99 selector: '{daemon=~"kubelet|kernel"}'
100 stages:
101 - regex:
102 expression: '^(?P<time>[^ ]* {1,2}[^ ]* [^ ]*) (?P<hostname>[^ ]*) (?P<daemon>[^ :\[]*)(?:\[(?P<pid>[0-9]+)\])?(?:[^\:]*\:)? *(?P<message>.*)$'
103 - labels:
104 time:
105 hostname:
106 daemon:
107 pid:
108 message:
109 - timestamp:
110 source: time
111 format: %b %d %H:%M:%S
112 - job_name: custom-log
113 static_configs:
114 - targets:
115 - localhost
116 labels:
117 job: custom-log
118 __path__: /appdata/applog
119 pipeline_stages:
120 - regex:
121 expression: '^(?P<log_type>[^ ]*) '
122 - labels:
123 log_type:
124 - match:
125 selector: '{log_type="type1"}'
126 stages:
127 - regex:
128 expression: '^(?P<log_type>[^ ]*) (?P<log_level>[^ ]*) ~'
129 - template:
130 source: log_level
131 template: 'warning'
132 - labels:
133 log_type:
134 - match:
135 selector: '{log_type="type2"}'
136 stages:
137 - regex:
138 expression: '^(?P<log_type>[^ ]*) (?P<log_level>[^ ]*) (?P<message>.*) ~'
139 - template:
140 source: log_type
141 template: 'API'
142 - labels:
143 log_type:
144 log_level:
145 message:
146 - match:
147 selector: '{log_level="I"}'
148 stages:
149 - regex:
150 expression: '^(?P<log_type>[^ ]*) (?P<log_level>[^ ]*) (?P<message>.*) ~'
151 - template:
152 source: log_level
153 template: 'INFO'
154 - labels:
155 log_type:
156 log_level:
157 message:
158 - match:
159 selector: '{log_level=~"W|E"}'
160 stages:
161 - regex:
162 expression: '^(?P<log_type>[^ ]*) (?P<log_level>[^ ]*) (?P<message>.*) ~'
163 - template:
164 source: log_level
165 template: '{{ if eq .Value "W" }}{{ Replace .Value "W" "WARNING" -1 }}{{ else if eq .Value "E" }}{{ Replace .Value "E" "ERROR" -1 }}{{ else }}{{ .Value }}{{ end }}'
166 - labels:
167 log_type:
168 log_level:
169 message:
170
171 # See also https://github.com/grafana/loki/blob/master/production/ksonnet/promtail/scrape_config.libsonnet for reference
172 - job_name: kubernetes-pods
173 pipeline_stages:
174 {{- toYaml .Values.config.snippets.pipelineStages | nindent 4 }}
175 kubernetes_sd_configs:
176 - role: pod
177 namespaces:
178 names:
179 - kube-system
180 - ...✂...
181 - ...✂...
182 relabel_configs:
183 - source_labels:
184 - __meta_kubernetes_pod_controller_name
185 regex: ([0-9a-z-.]+?)(-[0-9a-f]{8,10})?
186 action: replace
187 target_label: __tmp_controller_name
188 - source_labels:
189 - __meta_kubernetes_pod_label_app_kubernetes_io_name
190 - __meta_kubernetes_pod_label_app
191 - __tmp_controller_name
192 - __meta_kubernetes_pod_name
193 regex: ^;*([^;]+)(;.*)?$
194 action: replace
195 target_label: app
196 - source_labels:
197 - __meta_kubernetes_pod_label_app_kubernetes_io_instance
198 - __meta_kubernetes_pod_label_instance
199 regex: ^;*([^;]+)(;.*)?$
200 action: replace
201 target_label: instance
202 - source_labels:
203 - __meta_kubernetes_pod_label_app_kubernetes_io_component
204 - __meta_kubernetes_pod_label_component
205 regex: ^;*([^;]+)(;.*)?$
206 action: replace
207 target_label: component
208 {{- if .Values.config.snippets.addScrapeJobLabel }}
209 - replacement: kubernetes-pods
210 target_label: scrape_job
211 {{- end }}
212 {{- toYaml .Values.config.snippets.common | nindent 4 }}
213 {{- with .Values.config.snippets.extraRelabelConfigs }}
214 {{- toYaml . | nindent 4 }}
215 {{- end }}
216
217 # -- Config file contents for Promtail.
218 # Must be configured as string.
219 # It is templated so it can be assembled from reusable snippets in order to avoid redundancy.
220 # @default -- See `values.yaml`
221 file: |
222 server:
223 log_level: {{ .Values.config.logLevel }}
224 log_format: {{ .Values.config.logFormat }}
225 http_listen_port: {{ .Values.config.serverPort }}
226 {{- with .Values.httpPathPrefix }}
227 http_path_prefix: {{ . }}
228 {{- end }}
229 {{- tpl .Values.config.snippets.extraServerConfigs . | nindent 2 }}
230
231 clients:
232 {{- tpl (toYaml .Values.config.clients) . | nindent 2 }}
233
234 positions:
235 {{- tpl (toYaml .Values.config.positions) . | nindent 2 }}
236
237 scrape_configs:
238 {{- tpl .Values.config.snippets.scrapeConfigs . | nindent 2 }}
239 {{- tpl .Values.config.snippets.extraScrapeConfigs . | nindent 2 }}
240
241 limits_config:
242 {{- tpl .Values.config.snippets.extraLimitsConfig . | nindent 2 }}
243
244 tracing:
245 enabled: {{ .Values.config.enableTracing }}

syslog regex #

^(?P<time>[^ ]* {1,2}[^ ]* [^ ]*) (?P<hostname>[^ ]*) (?P<daemon>[^ :\[]*)(?:\[(?P<pid>[0-9]+)\])?(?:[^\:]*\:)? *(?P<message>.*)$

Install Customize Default Configuration #

1helm install [RELEASE NAME] [Chart.yaml 경로] -f [YAML 파일 또는 URL에 값 지정 (여러 개를 지정가능)] -n [NAMESPACE NAME]

1helm install promtail grafana/promtail -f override-values.yaml -n [NAMESPACE NAME]

Uninstall the Chart #

1helm uninstall [RELEASE NAME] -n [NAMESPACE NAME]

KyungRyeol Yoon

[Kubernetes] 🔒 Gateway API로 HTTP→HTTPS 리다이렉트 (HTTPRoute RequestRedirect)

🎯 핵심: RequestRedirect 필터 #

지원하는 상태 코드는? #

🧱 기본 구성: 리스너 2개 + 라우트 2개 #

1️⃣ Gateway — HTTP·HTTPS 리스너 둘 다 #

2️⃣ HTTPRoute ① — 80 리스너에 붙여 리다이렉트 #

3️⃣ HTTPRoute ② — 443 리스너에 붙여 백엔드로 전달 #

❓ 왜 라우트가 꼭 2개여야 하나? #

리다이렉트 라우트는 게이트웨이당 1개로 충분합니다 #

sectionName: https만 박으면 404, 리다이렉트가 아닙니다 #

🛡️ allowedRoutes로 평문 노출 원천 차단 #

🔧 트러블슈팅: 구성했는데 http가 계속 될 때 #

❓ 자주 묻는 질문 #

Q. Ingress의 ssl-redirect annotation과 무엇이 다른가요? #

Q. 301과 302 중 무엇을 써야 하나요? #

Q. 리다이렉트 라우트를 빼고 443 라우트만 두면 안 되나요? #

Q. POST 요청도 리다이렉트되나요? #

📚 참고 #

[Kubernetes] 🔏 인증서와 cert-manager: 두 갈래 PKI와 TLS 자동화

🪪 용어 4개 — 경쟁 관계가 아니라 한 시스템의 역할들 #

🍴 헷갈림의 핵심: 같은 기술을 쓰는 별개의 두 체계 #

① 클러스터 내부 PKI (kubeadm certs) — 컴포넌트끼리 인증용 #

② 앱/인그레스 TLS (Gateway·Ingress + cert-manager) — 외부 클라이언트용 #

🏢 Gateway에서 TLS를 중앙화하기 #

🤖 cert-manager — “받은 인증서를 넣는” 게 아니라 “받는 행위를 자동화” #

자동화 흐름 #

📝 한 줄 요약 #

❓ 자주 묻는 질문 #

Q. kubeadm 인증서와 Ingress TLS 인증서는 같은 건가요? #

Q. cert-manager에 회사에서 받은 .pfx를 넣으면 관리해주나요? #

Q. Let’s Encrypt 인증서 유효기간은 얼마인가요? #

Q. HTTP-01과 DNS-01 챌린지의 차이는? #

Q. Gateway API에서 다른 네임스페이스의 인증서 Secret을 참조하려면? #

📚 참고 #

[Kubernetes] 🌐 Ingress에서 Gateway API로: HTTPProxy vs HTTPRoute 비교

🧩 먼저: API(설정)와 엔진(Envoy)은 다른 층이다 #

🧬 진화의 흐름 #

1세대: Ingress (원조, 빌트인) #

2세대: 벤더별 CRD #

3세대: Gateway API (표준) #

⚔️ HTTPProxy vs HTTPRoute #

🤝 역할 분리 — Gateway API의 핵심 장점 #

🕸️ 왜 Istio 문서랑 비슷하게 느껴질까 #

📅 2026년 현재 상태 #

🎯 실무 권장 #

📝 한 줄 요약 #

❓ 자주 묻는 질문 #

Q. HTTPProxy와 HTTPRoute 중 무엇을 써야 하나요? #

Q. Ingress는 이제 안 쓰나요? #

Q. Gateway API와 서비스 메시(Istio)는 무엇이 다른가요? #

Q. Envoy와 Gateway API의 관계는? #

📚 참고 #

[Kubernetes] 🚦 쿠버네티스 트래픽 구조: 로드밸런서는 어디에 들어갈까

📍 로드밸런서가 들어갈 두 자리 #

🚪 자리 ②: 인그레스 — nginx·Contour·HAProxy는 서로 대안 #

🧭 자리 ①: 마스터 앞 LB — 흔한 오해 #

🔄 그럼 마스터들끼리 “알아서” 하는 건 뭘까 #

🧠 컨트롤 플레인 vs 데이터 플레인 — 앱 요청은 마스터를 안 거친다 #

건물 관리실 비유 #

↔️ 덤: Ingress와 Egress #

📝 한 줄 요약 #

❓ 자주 묻는 질문 #

Q. 마스터가 3대면 로드밸런서 없이도 HA가 되나요? #

Q. 인그레스 컨트롤러를 마스터 앞 LB로 쓸 수 있나요? #

Q. 앱 요청이 느려지면 마스터(API 서버) 부하가 원인인가요? #

Q. nginx, Contour, HAProxy 인그레스 컨트롤러를 동시에 써야 하나요? #

📚 참고 #

[Kubernetes] ⚖️ L4 vs L7 로드밸런서와 gRPC 로드밸런싱의 함정

✉️ L4 vs L7 — 편지를 여느냐, 안 여느냐 #

⚙️ 각각의 장단점 #

🪤 gRPC 로드밸런싱의 함정 (여기가 핵심) #

L4 로드밸런서는 “연결 단위"로 분산한다 #

L7 로드밸런서는 “요청 단위"로 분산한다 #

🔀 로드밸런서는 “버전"이 아니라 “종류” #

🖥️ 전용 장비가 아니라 소프트웨어의 동작 방식 #

📝 한 줄 요약 #

❓ 자주 묻는 질문 #

Q. gRPC를 L4 로드밸런서 뒤에 두면 왜 문제가 되나요? #

Q. 그럼 gRPC는 항상 L7을 써야 하나요? #

`sectionName: https`만 박으면 404, 리다이렉트가 아닙니다 #

Q. Ingress의 `ssl-redirect` annotation과 무엇이 다른가요? #

Q. Kestrel을 `Http1AndHttp2`로 두면 안 되나요? #

Q. `AllowAlternateSchemes`는 어떤 상황에서 필요한가요? #

Q. `kubelet` 인증서는 어떻게 갱신되나요? #

Q. 갱신 후 `kubectl` 명령이 실패합니다. #

Q. `-nodes` 옵션을 한 번에 쓰면 되지 않나요? #