Kubernetes on Joonlog

깃허브 코드로 배포한 Pokerogue 앱에서 구글/디스코드 외부 로그인이 실패하는 이슈

Wed, 22 Oct 2025 09:00:00 +0900

공식 rogueserver 코드의 쿠키 설정 버그로 인해 구글 OAuth 로그인이 작동하지 않는 이슈

환경

Vite 기반 React 프론트엔드와 Go 기반 백엔드 그리고 Mariadb로 구성
K8S + HAProxy를 통한 외부 접근

문제 상황

일반 계정 로그인은 정상 작동
구글/디스코드 계정 연결 시도 시 에러:
1. 일반 로그인 후 설정 메뉴에서 구글 연결 클릭
2. 구글 OAuth 인증 완료
3. 메인 화면으로 리다이렉트되지만 설정이 저장되지 않고 새로고침만 됨
4. 로그아웃 후 구글로 직접 로그인 시도 시 로그인 실패

에러 분석

1. 백엔드 로그 분석

1

kubectl logs -n pokerogue pokerogue-server

1
2
3


2025/10/14 23:02:24 [DEBUG] Google token response status: 200
2025/10/14 23:02:24 [DEBUG] Successfully extracted userId: 102118711772610730702
2025/10/14 23:02:47 /account/info: missing token

구글 OAuth 토큰 교환은 성공 (userId 추출 완료)
DB에 googleId도 정상 저장됨 확인
하지만 세션 토큰이 누락되어 로그인 상태 유지 실패

2. 브라우저 네트워크 탭 분석

1
2
3
4


Request: GET /api/auth/google/callback
Response: 303 See Other
Set-Cookie: pokerogue_sessionId=...; SameSite=Strict; Domain=pokerogue.net
Sec-Fetch-Site: cross-site

문제점 발견:

Domain=pokerogue.net
- 공식 pokerogue URL로 하드코딩 되어 있어 현재 도메인과 불일치
SameSite=Strict
- 구글에서 돌아오는 요청이 cross-site이므로 쿠키가 전송되지 않음

OAuth 리다이렉트 흐름:
- pokerogue.<도메인> → accounts.google.com → pokerogue.<도메인>/callback
  - SameSite=Strict는 같은 사이트 내부 요청에만 쿠키 전송
  - 구글에서 돌아오는 것은 cross-site 요청으로 간주되어 쿠키 차단

해결 방법

api/endpoints.go 파일의 쿠키 설정 수정:

1
2
3
4
5
6
7
8
9


http.SetCookie(w, &http.Cookie{
 Name: "pokerogue_sessionId",
 Value: sessionToken,
 Path: "/",
 Secure: true,
 SameSite: http.SameSiteLaxMode, // Strict → Lax 변경
 Domain: "", // "pokerogue.net" → "" 변경
 Expires: time.Now().Add(time.Hour * 24 * 30 * 3),
})

변경 사항
1. Domain: ""
  - 빈 문자열로 설정하여 현재 도메인 자동 적용
2. SameSite: http.SameSiteLaxMode
  - Strict → Lax
  - Lax는 안전한 cross-site GET 요청(OAuth 콜백 포함)에서 쿠키 전송 허용
  - OAuth 표준에서 권장하는 설정
  - 여전히 CSRF 공격 방어 가능 (위험한 POST 요청은 차단)

결과

일반 로그인 → 구글 계정 연결 → 로그아웃 → 구글 직접 로그인 모두 정상 작동
세션 쿠키가 올바르게 설정되어 로그인 상태 유지
브라우저 네트워크 탭에서 Set-Cookie: ...; SameSite=Lax 확인

참고

OAuth를 사용하는 많은 프로젝트에서 동일한 이슈가 발생했으며, 모두 SameSite=Lax로 해결

Kubernetes에서 Pokerogue 게임 배포하기

Mon, 20 Oct 2025 09:00:00 +0900

매니지드 K8S가 아닌 자체 관리형 K8S에서의 Pokerogue구축 방법

UI 접근을 위한 외부 통신으로 MetalLB+HAproxy+Nginx Controller가 구성 되었다는 전제 하에 구축

CSP 환경이라면 Ingress 설정에서 AWS ALB Controller와 같은 로드밸런서를 사용해 훨씬 간편하게 구축 가능

Pokerogue 공식문서: https://github.com/pagefaultgames/pokerogue https://github.com/pagefaultgames/rogueserver

아키텍쳐

인프라 구조: Pokerogue WEB(Frontend) - Pokerogue Rogueserver(Backend) - MariaDB(DB)
WEB과 API 통신 경로를 분리
- 분리 이유
  - SPA 특성상 Frontend가 / 경로로 모든 요청을 받아야 함
  - Backend는 /api/* 경로를 /*로 rewrite된 상태로 요청을 받아야 함
  - Ingress는 같은 Host(도메인)에 대해 두 개의 서로 다른 규칙 적용 불가
    - 따라서 HAproxy 설정에서 Frontend는 Ingress, Backend는 LoadBalancer타입 Service로 라우팅되도록 구성
- WEB 통신 구조:
  - Client(HTTPS) → HAproxy(SSL Termination) → Nginx Ingress Controller → Ingress → Service(pokerogue-web ClusterIP) → Workload(pokerogue-web)
- API 통신 구조:
  - Client JS(HTTPS/api/account/info) → HAproxy(SSL Termination + 경로 rewrite ⇒ HTTP /account/info) → Service(pokerogue-server LoadBalancer) → Workloads(pokerogue-server) → Service(pokerogue-db ClusterIP) → Workload(MariaDB)
구글 Oauth 로그인 흐름
- Client가 설정에서 Link Google → pokerogue-web에서 /api/auth/google?mode=link 요청 → rogueserver에서 Google OAuth URL 생성 → 브라우저에서 구글 로그인 → 구글에서 도메인/api/auth/google/callback?code=...&state=... 로 라우팅 → HAproxy(rogueserver-service)로 라우팅 → rogueserver에서 /auth/google/callback로 수신한 code로 구글 ID 조회 + 로그인한 사용자 ID 조회 → DB에서 해당 사용자에 구글 ID값 추가 → 도메인으로 리다이렉트
  - 디스코드 OAuth 로그인도 동일한 흐름

Pokerogue 구축

Pokerogue 네임스페이스 생성

1
2


kubectl create ns pokerogue
kubectl label namespace teleport-cluster 'pod-security.kubernetes.io/enforce=baseline'

mariadb-pvc 생성

mariadb-pvc.yaml
- longhorn pv 사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: pokerogue-db-pvc
 namespace: pokerogue
spec:
 accessModes:
 - ReadWriteOnce
 storageClassName: longhorn
 resources:
 requests:
 storage: 10Gi

mariadb-secret 생성
- DB 인증정보 secret
  - MYSQL_ROOT_PASSWORD
  - MYSQL_DATABASE
  - MYSQL_USER
  - MYSQL_PASSWORD

mariadb 배포

mariadb-deployment.yaml
- mariadb secret 참조
- mysqladmin ping 명령어로 헬스 체크

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82


apiVersion: apps/v1
kind: Deployment
metadata:
 name: pokerogue-db
 namespace: pokerogue
 labels:
 app: pokerogue-db
spec:
 replicas: 1
 selector:
 matchLabels:
 app: pokerogue-db
 template:
 metadata:
 labels:
 app: pokerogue-db
 spec:
 containers:
 - name: mariadb
 image: mariadb:11.2
 ports:
 - containerPort: 3306
 name: mysql
 env:
 - name: MYSQL_ROOT_PASSWORD
 valueFrom:
 secretKeyRef:
 name: pokerogue-db-secret
 key: MYSQL_ROOT_PASSWORD
 - name: MYSQL_DATABASE
 valueFrom:
 secretKeyRef:
 name: pokerogue-db-secret
 key: MYSQL_DATABASE
 - name: MYSQL_USER
 valueFrom:
 secretKeyRef:
 name: pokerogue-db-secret
 key: MYSQL_USER
 - name: MYSQL_PASSWORD
 valueFrom:
 secretKeyRef:
 name: pokerogue-db-secret
 key: MYSQL_PASSWORD
 volumeMounts:
 - name: db-data
 mountPath: /var/lib/mysql
 resources:
 requests:
 memory: "512Mi"
 cpu: "250m"
 limits:
 memory: "1Gi"
 cpu: "500m"
 livenessProbe:
 exec:
 command:
 - /usr/bin/mariadb-admin
 - ping
 - -h
 - localhost
 - -u
 - root
 - -p${MYSQL_ROOT_PASSWORD}
 initialDelaySeconds: 30
 periodSeconds: 10
 readinessProbe:
 exec:
 command:
 - /usr/bin/mariadb-admin
 - ping
 - -h
 - localhost
 - -u
 - root
 - -p${MYSQL_ROOT_PASSWORD}
 initialDelaySeconds: 5
 periodSeconds: 5
 volumes:
 - name: db-data
 persistentVolumeClaim:
 claimName: pokerogue-db-pvc

mariadb-service 생성

mariadb-service.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: v1
kind: Service
metadata:
 name: pokerogue-db
 namespace: pokerogue
spec:
 selector:
 app: pokerogue-db
 ports:
 - protocol: TCP
 port: 3306
 targetPort: 3306
 type: ClusterIP

OAuth-secret 생성
- rogueserver oauth 로그인을 위한 secret
  - GOOGLE_CLIENT_ID
  - GOOGLE_SECRET_ID
  - DISCORD_CLIENT_ID
  - DISCORD_CLIENT_SECRET

rogueserver 배포

rogueserver-deployment.yaml
- initcontainer로 DB가 준비될 때까지 대기
- DB secret 참조
- OAuth secret 참조

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80


apiVersion: apps/v1
kind: Deployment
metadata:
 name: pokerogue-server
 namespace: pokerogue
 labels:
 app: pokerogue-server
spec:
 replicas: 1
 selector:
 matchLabels:
 app: pokerogue-server
 template:
 metadata:
 labels:
 app: pokerogue-server
 spec:
 # DB가 준비될 때까지 대기
 initContainers:
 - name: wait-for-db
 image: busybox:1.36
 command: ['sh', '-c', 'until nc -z pokerogue-db 3306; do echo waiting for db; sleep 2; done;']
 containers:
 - name: rogueserver
 image: <registry명>/rogueserver:latest
 imagePullPolicy: Always
 ports:
 - containerPort: 8001
 name: api
 env:
 - name: debug
 value: "true"
 - name: dbaddr
 value: "pokerogue-db:3306"
 - name: dbuser
 valueFrom:
 secretKeyRef:
 name: pokerogue-db-secret
 key: MYSQL_USER
 - name: dbpass
 valueFrom:
 secretKeyRef:
 name: pokerogue-db-secret
 key: MYSQL_PASSWORD
 - name: dbname
 valueFrom:
 secretKeyRef:
 name: pokerogue-db-secret
 key: MYSQL_DATABASE
 - name: gameurl
 value: "https://pokerogue.<도메인>:48443"
 - name: callbackurl
 value: "https://pokerogue.<도메인>:48443/api"
 - name: googleclientid
 valueFrom:
 secretKeyRef:
 name: pokerogue-oauth-secret
 key: GOOGLE_CLIENT_ID
 - name: googlesecretid
 valueFrom:
 secretKeyRef:
 name: pokerogue-oauth-secret
 key: GOOGLE_SECRET_ID
 - name: discordclientid
 valueFrom:
 secretKeyRef:
 name: pokerogue-oauth-secret
 key: DISCORD_CLIENT_ID
 - name: discordsecretid
 valueFrom:
 secretKeyRef:
 name: pokerogue-oauth-secret
 key: DISCORD_CLIENT_SECRET
 resources:
 requests:
 memory: "512Mi"
 cpu: "250m"
 limits:
 memory: "1Gi"
 cpu: "1000m"

rogueserver-service생성

rogueserver-service.yaml
- type을 LoadBalancer로 만들어서 pokerogue-web용 ingrss에 할당할 IP와 다른 IP를 MetalLB로부터 할당
- /api로의 통신은 haproxy에서 rogueserver Service(LB)로 직접 라우팅

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: v1
kind: Service
metadata:
 name: pokerogue-server
 namespace: pokerogue
spec:
 selector:
 app: pokerogue-server
 ports:
 - protocol: TCP
 port: 8001
 targetPort: 8001
 type: LoadBalancer

web 배포

web-deployment.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


apiVersion: apps/v1
kind: Deployment
metadata:
 name: pokerogue-web
 namespace: pokerogue
 labels:
 app: pokerogue-web
spec:
 replicas: 1
 selector:
 matchLabels:
 app: pokerogue-web
 template:
 metadata:
 labels:
 app: pokerogue-web
 spec:
 containers:
 - name: web
 image: <registry명>/pokerogue-web:latest
 imagePullPolicy: Always
 ports:
 - containerPort: 80
 name: http
 resources:
 requests:
 memory: "512Mi"
 cpu: "500m"
 limits:
 memory: "1Gi"
 cpu: "1000m"

web-service생성

web-service.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: v1
kind: Service
metadata:
 name: pokerogue-web
 namespace: pokerogue
spec:
 selector:
 app: pokerogue-web
 ports:
 - protocol: TCP
 port: 80
 targetPort: 80
 type: ClusterIP

web-ingress 생성

pokerogue-web-ingress.yaml
- Frontend 라우팅만 처리
  - nginx.ingress.kubernetes.io/ssl-redirect
  - nginx.ingress.kubernetes.io/force-ssl-redirect
    - SSL Redirect 비활성화
      - HAproxy에서 SSL Termination 처리하기 때문
      - Ingress는 HTTP 트래픽만 수신
- Host 기반 라우팅
  - pokerogue.<도메인>으로 들어오는 요청만 처리
  - HAproxy가 Host 헤더 기반으로 이 Ingress로 라우팅

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: pokerogue-unified-ingress
 namespace: pokerogue
 annotations:
 nginx.ingress.kubernetes.io/ssl-redirect: "false"
 nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
spec:
 ingressClassName: nginx
 # TLS is handled by HAProxy, not by Ingress
 # This allows HAProxy to terminate SSL and forward HTTP to Ingress
 rules:
 - host: pokerogue.<도메인>
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: pokerogue-web
 port:
 number: 80

SSL 인증서 적용

인증서 발급
- /etc/letsencrypt/live/pokerogue.<도메인>/fullchain.pem
- /etc/letsencrypt/live/pokerogue.<도메인>/privkey.pem

1
2
3


certbot certonly --manual --preferred-challenges dns \
 -d pokerogue.<도메인> \
 --key-type ecdsa

haproxy용 인증서 생성

1
2
3


 cat /etc/letsencrypt/live/pokerogue.<도메인>/fullchain.pem \
 /etc/letsencrypt/live/pokerogue.<도메인>/privkey.pem \
 > /etc/haproxy/pokerogue.pem

HAproxy 설정

ingress, service를 조회하여 MetalLB로부터 부여받은 IP 확인

web: 172.27.1.100
backend: 172.27.1.104

1
2
3
4
5
6


# kubectl get ingress -n pokerogue 
NAME CLASS HOSTS ADDRESS PORTS AGE
pokerogue-unified-ingress nginx pokerogue.<도메인> 172.27.1.100 80 6d21h
# kubectl get svc -n pokerogue 
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
pokerogue-server LoadBalancer 10.233.16.211 172.27.1.104 8001:30946/TCP 9d

확인한 IP를 HAproxy 설정에 추가
HTTPS 트래픽 처리
- SSL Termination
  - SSL인증서와 개인키 파일을 결합한 pokerogue.pem파일 사용
- X-Forwarded-Port
  - 구글/디스코드 같은 외부 로그인을 위한 Backend OAuth callback URL 생성 시
- 경로 기반 라우팅
  - /api/* 요청 시 rogueserver-service로 직접 라우팅
  - 나머지 모든 요청은 pokerogue-ingress로 라우팅

API 서버(rogueserver-service)로의 라우팅을 위해 /api/* 요청을 /* 요청으로 재작성하는 설정 적용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


frontend pokerogue_frontend
 bind *:443 ssl crt /etc/haproxy/pokerogue.pem
 mode http
 option forwardfor

 # Set X-Forwarded headers for HTTPS
 http-request set-header X-Forwarded-Host %[req.hdr(host)]
 http-request set-header X-Forwarded-Proto https
 http-request set-header X-Forwarded-Port 48443

 # Path-based routing: /api -> Backend API, others -> Frontend
 use_backend pokerogue_api_backend if { path_beg /api }
 default_backend metallb_backend_pokerogue

backend metallb_backend_pokerogue
 # Frontend only (no rewrite)
 server pokerogue 172.27.1.100:80

backend pokerogue_api_backend
 # Backend API: direct to LoadBalancer Service (MetalLB managed)
 # Path rewrite: /api/* -> /*
 http-request set-path %[path,regsub(^/api,)]
 server pokerogue-server-lb 172.27.1.104:8001

haproxy 적용

1
2


haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl reload haproxy

접근 성공!

K8S에 구축된 Jenkins-GitLab CI Jenkinsfile - 애플리케이션 빌드 필요 없는 경우

Fri, 17 Oct 2025 09:00:00 +0900

Kubernetes 환경에서 Jenkins 파이프라인으로 CI를 수행하도록 구성한 Jenkinsfile 정리

Jenkins와 GitLab이 같은 K8S에 있는 환경인 가정하에 유효

Python, PHP처럼 애플리케이션 빌드 과정이 필요 없는 인터프리터 언어 기반인 경우에 유효

1. Kubernetes Pod 템플릿

Jenkins 에이전트를 파드 단위로 생성하는 파드 템플릿 정의
docker, dind 컨테이너로 구성
- docker-daemon 컨테이너는 Docker in Docker(DIND)를 사용해서 도커 데몬 실행
workspace-volume와 docker-socket 볼륨 공유

hostNetwork: true 설정으로 파드의 컨테이너가 호스트 노드(현재 워커 노드)의 네트워크 네임스페이스를 사용할 수 있도록 설정

hostAliases 설정으로 사설 IP로 GitLab 서버에 접근할 수 있도록 설정

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


 agent {
 kubernetes {
 yaml """
 apiVersion: v1
 kind: Pod
 spec:
 serviceAccountName: jenkins
 hostNetwork: true
 hostAliases:
 - ip: "<마스터 서버 사설 IP>"
 hostnames:
 - "registry.<도메인>"
 - "gitlab.<도메인>"
 containers:
 - name: docker
 image: docker
 command:
 - sleep
 args:
 - 99d
 tty: true
 volumeMounts:
 - name: workspace-volume
 mountPath: /home/jenkins/agent
 - name: docker-socket
 mountPath: /var/run
 - name: docker-daemon
 image: docker:dind
 securityContext:
 privileged: true
 env:
 - name: DOCKER_TLS_CERTDIR
 value: ""
 args:
 - --insecure-registry=registry.<도메인>:8080
 volumeMounts:
 - name: docker-socket
 mountPath: /var/run
 volumes:
 - name: workspace-volume
 emptyDir: {}
 - name: docker-socket
 emptyDir: {}
 """
 }
 }

2. Environment

Jenkinsfile에서 사용될 전역 환경 변수 정의

GITLAB_REGISTRY: GitLab Registry 주소
GITLAB_TOKEN: Jenkins Credentials에 저장된 GitLab 토큰

1
2
3
4
5
6
7
8


 environment {
 APP_NAME = "<앱 이름>"
 RELEASE = "1.0.0"
 GITLAB_REGISTRY = "registry.<도메인>:8080"
 GITLAB_TOKEN = credentials('<credentials 이름>')
 IMAGE_NAME = "${GITLAB_REGISTRY}/root/${APP_NAME}"
 IMAGE_TAG = "${RELEASE}-${BUILD_NUMBER}"
 }

3. Stages

Stage 1

SCM에서 소스코드 체크아웃
SCM의 url은 K8S Service의 FQDN으로 사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


 stage("Checkout from SCM") {
 steps {
 script {
 sh 'pwd'
 sh 'ls -al'
 git credentialsId: '<credentials 이름>',
 url: 'http://gitlab-webservice-default.gitlab.svc.cluster.local:8181/root/<리포지토리명>.git',
 branch: 'main'
 sh 'ls -al'
 }
 }
 }

Stage 2

Docker 이미지 빌드
- DinD 컨테이너에서 이미지 빌드 및 태그 추가

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


 stage('Build Docker Image') {
 steps {
 container('docker') {
 script {
 sh 'pwd'
 sh 'ls -al'
 sh 'docker build --no-cache -t ${IMAGE_NAME}:${IMAGE_TAG} .'
 sh 'docker tag ${IMAGE_NAME}:${IMAGE_TAG} ${IMAGE_NAME}:latest'
 }
 }
 }
 }

Stage 3

GitLab Registry 이미지 푸시
- GitLab Container Registry에 로그인 후 이미지 푸시
- GITLAB_TOKEN 환경변수에서 주입받은 credential로 GITLAB_TOKEN_PSW, GITLAB_TOKEN_USR 변수 사용 가능

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


stage('Push to GitLab Registry') {
 steps {
 container('docker') {
 script {
 sh 'echo $GITLAB_TOKEN_PSW | docker login ${GITLAB_REGISTRY} -u $GITLAB_TOKEN_USR --password-stdin'
 sh 'docker push ${IMAGE_NAME}:${IMAGE_TAG}' // Docker 이미지 푸시
 sh 'docker push ${IMAGE_NAME}:latest' // Docker 이미지 푸시(latest 태그)
 }
 }
 }
 }

4. 정리

파이프라인 종료 전 도커 리소스 정리 및 로그아웃

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


 post {
 always {
 // 작업 완료 후 정리
 container('docker') {
 script {
 sh 'docker logout ${GITLAB_REGISTRY} || true'
 sh 'docker system prune -f || true'
 }
 }
 }
 success {
 echo "Pipeline succeeded! Image ${IMAGE_NAME}:${IMAGE_TAG} pushed to GitLab Registry"
 }
 failure {
 echo "Pipeline failed!"
 }
 }

전체 Jenkinsfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115


pipeline {
 agent {
 kubernetes {
 yaml """
 apiVersion: v1
 kind: Pod
 spec:
 serviceAccountName: jenkins
 hostNetwork: true
 hostAliases:
 - ip: "<마스터 서버 사설 IP>"
 hostnames:
 - "registry.<도메인>"
 - "gitlab.<도메인>"
 containers:
 - name: docker
 image: docker
 command:
 - sleep
 args:
 - 99d
 tty: true
 volumeMounts:
 - name: workspace-volume
 mountPath: /home/jenkins/agent
 - name: docker-socket
 mountPath: /var/run
 - name: docker-daemon
 image: docker:dind
 securityContext:
 privileged: true
 env:
 - name: DOCKER_TLS_CERTDIR
 value: ""
 args:
 - --insecure-registry=registry.<도메인>:8080
 volumeMounts:
 - name: docker-socket
 mountPath: /var/run
 volumes:
 - name: workspace-volume
 emptyDir: {}
 - name: docker-socket
 emptyDir: {}
 """
 }
 }

 environment {
 APP_NAME = "<앱 이름>"
 RELEASE = "1.0.0" // 릴리즈 버전
 GITLAB_REGISTRY = "registry.<도메인>:8080" // GitLab Registry 주소
 GITLAB_TOKEN = credentials('<credentials 이름>') // Jenkins Credentials에 저장된 GitLab 토큰
 IMAGE_NAME = "${GITLAB_REGISTRY}/root/${APP_NAME}" // 이미지 이름
 IMAGE_TAG = "${RELEASE}-${BUILD_NUMBER}" // 이미지 태그
 }

 stages {
 stage("Checkout from SCM") { // 소스 코드 관리(SCM)에서 체크아웃 단계
 steps {
 script {
 sh 'pwd'
 sh 'ls -al'
 git credentialsId: '<credentials 이름>', // GitLab 자격증명 사용
 url: 'http://gitlab-webservice-default.gitlab.svc.cluster.local:8181/root/<리포지토리명>.git', // GitLab 리포지토리 URL
 branch: 'main' // 브랜치 이름
 sh 'ls -al'
 }
 }
 }

 stage('Build Docker Image') { // Docker 이미지 빌드 단계
 steps {
 container('docker') {
 script {
 sh 'pwd'
 sh 'ls -al'
 sh 'docker build --no-cache -t ${IMAGE_NAME}:${IMAGE_TAG} .' // Docker 이미지 빌드
 sh 'docker tag ${IMAGE_NAME}:${IMAGE_TAG} ${IMAGE_NAME}:latest' // latest 태그 추가
 }
 }
 }
 }

 stage('Push to GitLab Registry') { // GitLab Registry에 이미지 푸시 단계
 steps {
 container('docker') {
 script {
 sh 'echo $GITLAB_TOKEN_PSW | docker login ${GITLAB_REGISTRY} -u $GITLAB_TOKEN_USR --password-stdin' // GitLab Registry 로그인
 sh 'docker push ${IMAGE_NAME}:${IMAGE_TAG}' // Docker 이미지 푸시
 sh 'docker push ${IMAGE_NAME}:latest' // Docker 이미지 푸시(latest 태그)
 }
 }
 }
 }
 }

 post {
 always {
 // 작업 완료 후 정리
 container('docker') {
 script {
 sh 'docker logout ${GITLAB_REGISTRY} || true'
 sh 'docker system prune -f || true'
 }
 }
 }
 success {
 echo "Pipeline succeeded! Image ${IMAGE_NAME}:${IMAGE_TAG} pushed to GitLab Registry"
 }
 failure {
 echo "Pipeline failed!"
 }
 }
}

K8S에 구축된 Jenkins-GitLab 파이프라인 설정

Thu, 16 Oct 2025 09:00:00 +0900

파이프라인 설정

Definition: Pipeline script from SCM
- SCM: Git
  - Jenkinsfile을 Git으로 읽도록 설정
git repository url: http://gitlab-webservice-default.gitlab.svc.cluster.local:8181/root/test.git
- Jenkins 서버와 GitLab 서버가 모두 같은 k8s 클러스터에 있으므로, 외부 서버에서 url 설정하던 것처럼 하긴 어려움
- GitLab UI Service의 FQDN인 gitlab-webservice-default.gitlab.svc.cluster.local 을 사용
Credentials: GitLab PAT
- GitLab의 사용자/리포지토리에서 발급한 PAT를 Jenkins Credentials에 등록해서 사용
Branches to build: */main
- 빌드할 브랜치 선택

Kubernetes환경 Teleport에서 사용자 관리하기

Sat, 11 Oct 2025 09:00:00 +0900

Teleport 사용자 생성

member Role 생성

member.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


kind: role
version: v7
metadata:
 name: member
spec:
 allow:
 kubernetes_groups: ["system:masters"]
 kubernetes_labels:
 '*': '*'
 kubernetes_resources:
 - kind: '*'
 namespace: '*'
 name: '*'
 verbs: ['*']

1

kubectl exec -i deployment/teleport-auth -n teleport-cluster -- tctl create -f < member.yaml

myuser 사용자 생성

출력된 링크를 브라우저에서 접속

1

kubectl exec -it deployment/teleport-auth -n teleport-cluster -- tctl users add myuser --roles=member,access,editor

로그인 성공!

tsh 로그인

tsh login

1

tsh login --proxy=teleport.<도메인>:8443 --user=myuser

사용자에 할당된 사용 가능한 k8s cluster 목록

1
2
3
4


# tsh kube ls
Kube Cluster Name Labels Selected
---------------------- ------ --------
teleport.<domain> *

k8s cluster login
1

tsh kube login teleport.<domain>

kubectl 성공!

1
2
3
4
5
6
7


# kubectl get nodes
NAME STATUS ROLES AGE VERSION
master1 Ready control-plane 51d v1.31.4
master2 Ready control-plane 51d v1.31.4
master3 Ready control-plane 51d v1.31.4
node1 Ready <none> 51d v1.31.4
node2 Ready <none> 51d v1.31.4

자체 관리형 Kubernetes에서의 Teleport 구축

Fri, 10 Oct 2025 09:00:00 +0900

매니지드 K8S가 아닌 자체 관리형 K8S에서의 Teleport구축 방법

UI 접근을 위한 외부 통신으로 MetalLB+HAproxy+Nginx Controller가 구성 되었다는 전제 하에 구축

CSP 환경이라면 Ingress 설정에서 AWS ALB Controller와 같은 로드밸런서를 사용해 훨씬 간편하게 구축 가능

Teleport 공식문서: https://goteleport.com/docs/ https://goteleport.com/docs/zero-trust-access/deploy-a-cluster/helm-deployments/kubernetes-cluster/

Teleport 설치

Helm 리포지토리 추가

1
2


helm repo add teleport https://charts.releases.teleport.dev
helm repo update

teleport-cluster 네임스페이스 생성

네임스페이스에 baseline 보안 수준 적용

1
2


kubectl create ns teleport-cluster
kubectl label namespace teleport-cluster 'pod-security.kubernetes.io/enforce=baseline'

pvc 생성

teleportpvc.yaml
- kubectl apply -f teleportpvc.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: teleport-pvc
 namespace: teleport-cluster
spec:
 accessModes: ["ReadWriteOnce"]
 storageClassName: longhorn
 resources:
 requests:
 storage: 10Gi

SSL 인증서 Secret 등록

인증서 발급
- /etc/letsencrypt/live/teleport.<도메인>/fullchain.pem
- /etc/letsencrypt/live/teleport.<도메인>/privkey.pem

1
2
3


certbot certonly --manual --preferred-challenges dns \
 -d teleport.<도메인> \
 --key-type ecdsa

secret 생성

1
2
3


kubectl -n teleport-cluster create secret tls teleport-tls \
 --cert=/etc/letsencrypt/live/teleport.<도메인>/fullchain.pem \
 --key=/etc/letsencrypt/live/teleport.<도메인>/privkey.pem

teleport 설치

https://goteleport.com/docs/reference/helm-reference/

values.yaml 수정

helm으로 설치

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


helm show values teleport/teleport-cluster > values.yaml
vim values.yaml

helm install teleport teleport/teleport-cluster \
 -f values.yaml \
 -n teleport-cluster

helm upgrade --install teleport teleport/teleport-cluster \
 -f values.yaml \
 -n teleport-cluster

클러스터 이름 기입
1

clusterName: teleport.<도메인>

외부 접근 주소

1
2


publicAddr: ['teleport.<도메인>:8443']
tunnelPublicAddr: ['teleport.<도메인>:8443']

프록시가 443 포트 하나에서 ALPN으로 Web UI/SSH 리버스 터널/Kubernetes 프록시를 다 처리
- 기본값이 seprate인데 이렇게 되면 3024/3025/3026 등등 각각 포트 사용해야함
- 외부 주소는 publicAddr로 노출됨
1

proxyListenerMode: "multiplex"

Proxy Service

1
2
3
4
5


service:
 type: LoadBalancer
 spec:
 # MetalLB에서 고정 IP를 쓰고 싶을 때만 지정
 # loadBalancerIP: 172.27.1.103

ACME 비활성화
1

acme: false
TLS 인증서 Secret 지정
- cert-manager가 발급한 Secret 이름으로 설정
1 2

tls: existingSecretName: teleport-tls

Auth 스토리지 PV 설정

pv는 longhorn이 자동으로 프로비저닝

1
2
3
4


persistence:
 enabled: true
 existingClaimName: "teleport-pvc"
 volumeSize: 10Gi

HA replica 설정
- HA 안쓰면 1
1 2

highAvailability: replicaCount: 1

Teleport UI 접근

Teleport는 443포트에서 HTTPS/SSH 리버스 터널/K8S Access Proxy 등을 ALPN으로 동시에 처리하기 때문에, 다른 애플리케이션처럼 ingress로 프록시하면 안됨
- ingress가 처리하면 ALPN 정보가 사라져서 Teleport Proxy는 트래픽의 소스를 알 수 없게 됨
  - web ui는 접근 되더라도 tsh login, tctl, kubectl 등은 모두 실패할 것
- Teleport의 Proxy 서비스를 Load Balancer 타입 서비스로 생성해야 함
마찬가지 이유로 haproxy 설정에서도 L7 프록시 말고 L4 프록시가 필요

HAproxy 설정

values로 생성한 load balancer를 조회하여 MetalLB로부터 부여받은 IP 확인

현재는 172.27.1.103

1
2
3


# kubectl get svc -n teleport-cluster 
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
teleport LoadBalancer 10.233.62.211 172.27.1.103 443:30523/TCP,3023:31718/TCP,3026:31539/TCP,3024:31393/TCP,3036:30139/TCP 56s

확인한 IP를 HAproxy 설정에 추가

HAproxy 서버 공인 IP로 접근 시 teleport의 LB Service로 통신되도록 설정

1
2
3


vim /etc/haproxy/haproxy.cfg
haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl reload haproxy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


frontend unified_frontend_8443
 bind *:8443
 mode tcp
 option tcplog
 tcp-request inspect-delay 5s
 tcp-request content accept if { req_ssl_hello_type 1 }
 use_backend metallb_backend_teleport if { req.ssl_sni -i teleport.<도메인> }
 default_backend metallb_backend_teleport

backend metallb_backend_teleport
 mode tcp
 server teleport 172.27.1.103:443

접근 성공!

Kubernetes QoS Overview

Tue, 30 Sep 2025 09:00:00 +0900

kubernetes는 노드에 리소스가 부족할 때, Pod의 QoS 클래스에 따라 어떤 Pod를 우선적으로 Eviction(퇴출)할지를 결정

QoS 클래스 종류

Guaranteed
- Pod 내 모든 컨테이너의 CPU/Memory Request와 Limit 값이 동일한 경우
- 가장 높은 우선순위를 가짐 (Eviction 대상에서 가장 안전함)
Burstable
- Guaranteed와 BestEffort에 속하지 않는 모든 경우
- 예: Request < Limit 인 경우
- 우선순위는 중간
BestEffort
- 리소스 Request와 Limit을 전혀 지정하지 않은 경우
- 가장 낮은 우선순위 (Eviction 1순위)

Eviction 동작 원리

노드에 리소스가 부족해지면, kubelet은 다음과 같은 순서로 Pod를 Eviction

우선순위: Guaranteed > Burstable > BestEffort
BestEffort
- 항상 Eviction 대상에 포함됨
Burstable
- CPU/Memory Request보다 실제 사용량이 큰 경우 Eviction 대상
Guaranteed
- Eviction 대상에서 가장 안전

주의: Request와 Limit 차이를 너무 크게 잡으면 Burstable로 분류되어 Eviction 대상

따라서 Request와 Limit은 가급적 동일하게 잡는 것이 안정적

CPU vs Memory

CPU → 압축 가능한(compressible) 리소스
- Request보다 더 쓰더라도 kubelet이 throttle(스로틀링) 해서 CPU 사용량을 줄일 수 있음
- 즉, CPU 경합이 발생해도 프로세스가 죽지는 않음
Memory, Storage → 압축 불가능한(incompressible) 리소스
- Memory 사용이 Request를 초과하면, kubelet은 해당 Pod를 Eviction시켜야 함
- Storage도 마찬가지로 강제 종료가 필요할 수 있음

EX) Guaranteed Pod

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


apiVersion: v1
kind: Pod
metadata:
 name: guaranteed-pod
spec:
 containers:
 - name: nginx
 image: nginx
 resources:
 requests:
 memory: "512Mi"
 cpu: "500m"
 limits:
 memory: "512Mi"
 cpu: "500m"

Request = Limit 이므로 QoS = Guaranteed

EX) Burstable Pod

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


apiVersion: v1
kind: Pod
metadata:
 name: burstable-pod
spec:
 containers:
 - name: nginx
 image: nginx
 resources:
 requests:
 memory: "256Mi"
 cpu: "250m"
 limits:
 memory: "512Mi"
 cpu: "500m"

Request < Limit 이므로 QoS = Burstable

EX) BestEffort Pod

1
2
3
4
5
6
7
8


apiVersion: v1
kind: Pod
metadata:
 name: besteffort-pod
spec:
 containers:
 - name: nginx
 image: nginx

Request/Limit 미지정 → QoS = BestEffort

Pod QoS Class 확인 방법

1

kubectl get pod {POD_NAME} -o jsonpath='{ .status.qosClass}{"\n"}'

정리

QoS 클래스는 Pod의 리소스 보장 수준
Eviction 순서: Guaranteed > Burstable > BestEffort
CPU는 throttle 가능(죽지 않음), Memory/Storage는 Eviction 발생
안정적인 서비스 운영을 위해 Request와 Limit을 동일하게 설정하는 것이 가장 안전

참고 자료

K8S에 구축한 GitLab Registry에 Container Image 푸시 시 blob upload unknown 에러 TroubleShooting

Sat, 27 Sep 2025 09:00:00 +0900

GitLab을 Helm Chart로 구축 + 브라우저에서 GitLab 접근 시 80 포트가 아닌 다른 포트로 접근해야 할 경우 발생하는 이슈 GitLab Helm Chart의 포트 설정이 80/443으로 고정되어 있기 때문에 발생

환경

자체 관리형 kubernetes이기에 외부용 L7 로드밸런서로 haproxy를 사용 중인 경우
helm chart로 GitLab 서버를 구축한 경우
외부에서 브라우저로 GitLab UI 접근 시 80포트가 아닌 8080과 같은 별도의 포트로만 접근해야하는 제약사항이 있는 경우

문제 상황

helm chart로 GitLab 서버 구축 후 <도메인>:<포트>로 접근 시 포트가 제거된 후 도메인으로만 강제 리다이렉션 되는 현상 발생
- 404 에러
브라우저 → HAProxy(8080) → GitLab(80) → 리다이렉트 응답

해결 방법

HAproxy 설정을 통해 포트를 포함해서 리다이렉트 하도록 설정

http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1

정규식 분석:
- ^http://gitlab.<도메인>/(.*)$ - 매칭 패턴
- http://gitlab.<도메인>:8080/\1 - 치환 결과
- \1 = 첫 번째 그룹 (.*) 내용 (URL 경로)
- 변환 예시:
  - 원본: Location: http://gitlab.<도메인>/users/sign_in
  - 변환: Location: http://gitlab.<도메인>/users/sign_in
외부 브라우저에서 GitLab 접근 시 포트를 붙여서 접근해야 될 경우 반드시 설정
설정하지 않으면 접근 시 자동으로 포트가 제거된 상태로 리다이렉션되어 404 에러

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 # Host 기반 라우팅
 ...
 use_backend metallb_backend_gitlab if { hdr(host) -i gitlab.<도메인> }
 ...

backend metallb_backend_gitlab
 http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1
 server gitlab 172.27.1.102:80

결과

브라우저가 8080포트를 포함해서 리다이렉트
HAProxy를 통한 접속 유지

K8S에 구축한 Jenkins CI 파이프라인의 Dind 네트워크 에러 TroubleShooting

Sat, 27 Sep 2025 09:00:00 +0900

K8S 환경의 Jenkins에서 docker build가 Jenkins 파이프라인 파드의 dind 컨테이너에서 실행되기 때문에 발생한 이슈

환경

Jenkins 서버를 K8S에서 구축하고, 파이프라인을 K8S 파드에서 동작하도록 설정한 환경
- Jenkinsfile에서 K8S 파드 템플릿으로 파이프라인 실행하게 명시

문제 상황

Jenkinsfile의 docker build 단계에서 파이프라인 빌드 실패
- Dockerfile의 composer install 레이어에서 Could not fetch https://api.github.com/repos/ 에러 발생
- 외부에서 데이터를 받아오는 명령어에서 전부 timeout 에러 발생

에러 분석

Jenkins 파이프라인이 K8S 파드의 docker 컨테이너에서 실행되고, docker build 작업은 dind 컨테이너에서 실행됨
- dind 컨테이너 입장에서 네트워크가 격리되어 있어 GitHub API 서버로의 아웃바운드 연결 불가
따라서 composer install 와 같은 명령어 실행 시 연결 실패 에러 발생

해결 방법

Jenkinsfile의 k8s 파드 템플릿에 hostNetwork: true를 설정해서 파드의 컨테이너가 호스트 노드(현재 워커 노드)의 네트워크 네임스페이스를 사용할 수 있도록 설정
- 파드 템플릿이 아닌 docker build --network=host로 명령어 마다 옵션을 명시해서 해결도 가능하지만, 파드 레벨에서 해결하는게 관리에 용이

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


kubernetes {
 yaml """
 apiVersion: v1
 kind: Pod
 spec:
 serviceAccountName: jenkins
 hostNetwork: true
 hostAliases:
 - ip: "172.27.1.9"
 hostnames:
 - "registry.<도메인>"
 - "gitlab.<도메인>"
 containers:
 - name: docker
 image: docker
 command:
 - sleep
 args:
 - 99d
 tty: true
 volumeMounts:
 - name: workspace-volume
 mountPath: /home/jenkins/agent
 - name: docker-socket
 mountPath: /var/run
 - name: docker-daemon
 image: docker:dind
 securityContext:
 privileged: true
 env:
 - name: DOCKER_TLS_CERTDIR
 value: ""
 args:
 - --insecure-registry=registry.<도메인>:8080
 volumeMounts:
 - name: docker-socket
 mountPath: /var/run
 volumes:
 - name: workspace-volume
 emptyDir: {}
 - name: docker-socket
 emptyDir: {}
 """
 }

K8S에 구축한 GitLab UI 접근 시 접근 포트가 제거된 상태로 강제 리다이렉션 TroubleShooting

Thu, 25 Sep 2025 09:00:00 +0900

GitLab을 Helm Chart로 구축 + 브라우저에서 GitLab 접근 시 80 포트가 아닌 다른 포트로 접근해야 할 경우 발생하는 이슈 GitLab Helm Chart의 포트 설정이 80/443으로 고정되어 있기 때문에 발생

환경

자체 관리형 kubernetes이기에 외부용 L7 로드밸런서로 haproxy를 사용 중인 경우
helm chart로 GitLab 서버를 구축한 경우
외부에서 브라우저로 GitLab UI 접근 시 80포트가 아닌 8080과 같은 별도의 포트로만 접근해야하는 제약사항이 있는 경우

문제 상황

helm chart로 GitLab 서버 구축 후 <도메인>:<포트>로 접근 시 포트가 제거된 후 도메인으로만 강제 리다이렉션 되는 현상 발생
- 404 에러
브라우저 → HAProxy(8080) → GitLab(80) → 리다이렉트 응답

해결 방법

HAproxy 설정을 통해 포트를 포함해서 리다이렉트 하도록 설정

http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1

정규식 분석:
- ^http://gitlab.<도메인>/(.*)$ - 매칭 패턴
- http://gitlab.<도메인>:8080/\1 - 치환 결과
- \1 = 첫 번째 그룹 (.*) 내용 (URL 경로)
- 변환 예시:
  - 원본: Location: http://gitlab.<도메인>/users/sign_in
  - 변환: Location: http://gitlab.<도메인>/users/sign_in
외부 브라우저에서 GitLab 접근 시 포트를 붙여서 접근해야 될 경우 반드시 설정
설정하지 않으면 접근 시 자동으로 포트가 제거된 상태로 리다이렉션되어 404 에러

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 # Host 기반 라우팅
 ...
 use_backend metallb_backend_gitlab if { hdr(host) -i gitlab.<도메인> }
 ...

backend metallb_backend_gitlab
 http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1
 server gitlab 172.27.1.102:80

결과

브라우저가 8080포트를 포함해서 리다이렉트
HAProxy를 통한 접속 유지

자체 관리형 Kubernetes에서의 GitLab 구축

Wed, 24 Sep 2025 09:00:00 +0900

매니지드 K8S가 아닌 자체 관리형 K8S에서의 GitLab 구축 방법

UI 접근을 위한 외부 통신으로 MetalLB+HAproxy+Nginx Controller가 구성 되었다는 전제 하에 구축

CSP 환경이라면 Ingress 설정에서 AWS ALB Controller와 같은 로드밸런서를 사용해 훨씬 간편하게 구축 가능

GitLab 공식문서: ****https://docs.gitlab.com/install/install_methods/#helm-chart
GitLab Artifacthub 문서: https://artifacthub.io/packages/helm/gitlab/gitlab

GitLab 설치

Helm 리포지토리 추가

1
2


helm repo add gitlab https://charts.gitlab.io/
helm repo update

gitlab 네임스페이스 생성
1

kubectl create ns gitlab

gitlab-pv 생성(StorageClass 없을 시에만 진행)

기존에 사용하던 Ceph, Longhorn, EBS Driver, Harbor 같은 StorageClass가 없을 경우에 로컬 경로를 사용한 PV 할당 방법
- StorageClass가 있다면 PVC 생성 시 자동으로 PV가 할당되기 때문에 이 과정은 불필요

1
2


vim gitlab-01-volume.yaml
kubectl apply -f gitlab-01-volume.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


apiVersion: v1
kind: PersistentVolume
metadata:
 name: gitlab-pv
spec:
 storageClassName: gitlab-pv
 accessModes:
 - ReadWriteOnce
 capacity:
 storage: 20Gi
 persistentVolumeReclaimPolicy: Retain
 hostPath:
 path: /data/gitlab-volume/

---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
 name: gitlab-pv
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer

gitlab 설치

values.yaml 수정
- helm으로 설치

1
2
3
4


helm show values gitlab/gitlab > values.yaml
vim values.yaml

helm install gitlab -n gitlab -f values.yaml gitlab/gitlab

소스코드 리포지토리 설정

1
2
3
4
5
6


# GitLab Gitaly (Git 저장소)
gitlab:
 gitaly:
 persistence:
 storageClass: "longhorn"
 size: 20Gi

postgresql, redis 설정
- postgresql: gitlab 전체의 메타데이터 저장
  - redis: 사용자 세션, 백그라운드 작업, 캐시, 알림 등에 사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# PostgreSQL
postgresql:
 primary:
 persistence:
 storageClass: "longhorn"
 size: 8Gi

# Redis 
redis:
 master:
 persistence:
 storageClass: "longhorn"
 size: 2Gi

minio설정
- https://docs.gitlab.com/charts/charts/globals#configure-minio-settings
- S3와 호환되는 오브젝트 스토리지

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


global:

 # minio 서비스 활성화
 minio:
 enabled: true

 # 바이너리 파일들이 오브젝트 스토리지를 사용할 수 있도록 설정
 appConfig:
 object_store
 enabled: true

 # Container Registry가 minio의 registry 버킷을 사용
 registry:
 bucket: registry

# minio가 Longhorn을 통한 PV 사용
minio:
 persistence:
 enabled: true
 size: 10Gi
 storageClass: longhorn

불필요한 기능 비활성화

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


global:
 lfs:
 enabled: false
 uploads:
 enabled: false
 toolbox:
 enabled: false

# GitLab KAS 비활성화 (Kubernetes Agent)
global:
 kas:
 enabled: false

# CI/CD 관련 비활성화
global:
 appConfig:
 artifacts:
 enabled: false
 packages:
 enabled: false

# 모니터링 비활성화
prometheus:
 install: false

# GitLab Runner 비활성화
gitlab-runner:
 install: false

도메인, 에디션(CE/EE)

1
2
3
4


global:
 edition: ce
 hosts:
 domain: <도메인>

http 접근을 위한 설정

1
2
3
4
5
6
7
8


global:
 hosts:
 https: false
 ingress:
 configureCertmanager: false
 tls:
 enabled: false
installCertmanager: false

GitLab UI

GitLab Helm Chart를 통해 ingress는 생성 완료!

values.yaml 내에 ingress 생성을 위한 nginx 설정이 포함되어 있음

HAproxy 설정

ingress를 조회하여 MetalLB로부터 부여받은 IP 확인

현재는 172.27.1.102

1
2
3
4


# kubectl get ingress -n gitlab
NAME CLASS HOSTS ADDRESS PORTS AGE
gitlab-registry gitlab-nginx registry.<도메인> 172.27.1.102 80 61m
gitlab-webservice-default gitlab-nginx gitlab.<도메인> 172.27.1.102 80 61m

확인한 IP를 HAproxy 설정에 추가

HAproxy 서버 공인 IP로 접근 시 gitlab의 Ingress로 통신되도록 설정
http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:<포트>/\\1
두 조건을 만족할 경우 설정 필요
- 외부 브라우저에서 GitLab 접근 시 포트를 붙여서 접근해야 될 경우
- 애플리케이션 내부적으로 url로 응답이 나오도록 설정되어 있을 경우
  - EX) GitLab 로그인 시 GitLab에 설정된 url 응답
설정하지 않으면 접근 시 자동으로 포트가 제거된 상태로 리다이렉션되어 404 에러

1
2
3


vim /etc/haproxy/haproxy.cfg
haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl reload haproxy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 http-request set-header X-Forwarded-Host %[req.hdr(host)]
 http-request set-header X-Forwarded-Proto http
 http-request set-header X-Forwarded-Port %[dst_port]

 # Host 기반 라우팅
 use_backend metallb_backend_gitlab if { hdr(host) -m sub gitlab }
 # GitLab Container Registry를 위한 경로
 use_backend metallb_backend_gitlab if { hdr(host) -m sub registry }

backend metallb_backend_gitlab
 http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:<포트>/\\1
 server gitlab 172.27.1.100:80

접근 성공!

gitlab 관리자(root) 비밀번호 확인

1

kubectl get secret gitlab-gitlab-initial-root-password -n gitlab -o jsonpath="{.data.password}" | base64 --decode

Kubernetes 인증 / 권한 관리 Overview

Tue, 23 Sep 2025 09:00:00 +0900

kubernetes에서 kubectl 같이 클라이언트나 파드 내부에서 API 서버에 접근할 때는 인증과 권한이 필요

접근 제어

User/Group → 인증

인증서는 클라이언트 신원을 확인하는 데 사용
- ex) kubectl get nodes 실행 시 사용자 인증 필요
인증서(certificate)를 kubeconfig에 등록하여 사용

ServiceAccount → 권한

파드 내부에서 쿠버네티스 API를 호출할 때 사용
- Pod 실행 시 자동으로 토큰이 /var/run/secrets/kubernetes.io/serviceaccount/token 에 마운트
파드 내부에서 자동으로 마운트되거나 Secret을 통해 주입

사용자 생성 절차

개인키 생성
CSR 생성

CSR 요청 및 승인

1
2


kubectl apply -f csr.yaml
kubectl certificate approve myuser-csr

Role/RoleBinding 생성

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
 namespace: default
 name: pod-reader
rules:
- apiGroups: [""]
 resources: ["pods"]
 verbs: ["get", "list"]
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
 name: read-pods
 namespace: default
subjects:
- kind: User
 name: myuser
roleRef:
 kind: Role
 name: pod-reader
 apiGroup: rbac.authorization.k8s.io

kubeconfig에 사용자 추가

1

kubectl config set-credentials myuser --client-certificate=user.crt --client-key=user.key

context 변경

1
2


kubectl config set-context myuser-context --cluster=mycluster --namespace=default --user=myuser
kubectl config use-context myuser-context

서비스 어카운트 생성 절차

서비스 어카운트 생성

1

kubectl create serviceaccount mysa -n default

Rolebinding 생성

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
 name: sa-read-pods
 namespace: default
subjects:
- kind: ServiceAccount
 name: mysa
 namespace: default
roleRef:
 kind: Role
 name: pod-reader
 apiGroup: rbac.authorization.k8s.io

pod 실행시 서비스 어카운트 지정

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


apiVersion: v1
kind: Pod
metadata:
 name: test-pod
spec:
 serviceAccountName: mysa
 containers:
 - name: curl
 image: curlimages/curl
 command: ["sleep", "3600"]

권한 관리(RBAC)

Role
- 네임스페이스 단위 권한
  - ex) default namespace에서 pod 읽기
RoleBinding
- Role을 특정 User/Group/ServiceAccount에 바인딩
ClusterRole
- 클러스터 전체 권한
  - ex) 모든 namespace에서 pod 읽기
ClusterRoleBinding
- ClusterRole을 User/Group/ServiceAccount에 바인딩

자체 관리형 Kubernetes에서 Metrics Server를 통한 매트릭 자원 확인

Mon, 22 Sep 2025 09:00:00 +0900

kubectl top node node1과 같이 즉각적인 매트릭 자원 확인이 가능하도록 설정

GitHub: https://github.com/kubernetes-sigs/metrics-server?tab=readme-ov-file
Artifacthub: https://artifacthub.io/packages/helm/metrics-server/metrics-server
helm 리포지토리 추가

1
2


helm repo add metrics-server https://kubernetes-sigs.github.io/metrics-server/
helm upgrade

values.yaml 수정

1
2


helm show values metrics-server/metrics-server > metrics-server-values.yaml
vim metrics-server-values.yaml

metrics server가 tls 인증서를 검증하지 않도록 설정

1
2


args:
 - --kubelet-insecure-tls

metrics server 설치

1

helm upgrade --install metrics-server metrics-server/metrics-server -f metrics-server-values.yaml

Kubernetes Pod Scheduling Overview

Fri, 19 Sep 2025 09:00:00 +0900

k8s scheduler가 어떤 기준으로 파드를 노드에 배치하는지에 대한 정리

Node Affinity

지정된 조건에 맞는 노드에 파드를 배포

disktype=ssd label이 있는 노드에만 스케줄링

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


apiVersion: v1
kind: Pod
metadata:
 name: web-pod
spec:
 affinity:
 nodeAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 nodeSelectorTerms:
 - matchExpressions:
 - key: disktype
 operator: In
 values:
 - ssd
 containers:
 - name: web
 image: nginx

Pod Affinity

pod를 가까이 배치(ex: 같은 노드에 배치)

app=db label이 붙은 파드와 같은 노드에 배치
- 반대로 podAntiAffinity를 쓰면 다른 노드에 배치 가능

1
2
3
4
5
6
7
8
9


podAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - labelSelector:
 matchExpressions:
 - key: app
 operator: In
 values:
 - db
 topologyKey: "kubernetes.io/hostname"

Taint & Toleration

nodeselector: 노드레이블이 지정된 노드에 파드를 배포할 때 사용
node taint: 노드에 파드를 배포되지 않도록 할 때 사용
- node taint 추가 명령어
1

kubectl taint nodes node1 key=value:NoSchedule
pod toleration: node taint가 설정된 노드에 배포하고 싶을 때 사용
- pod 매니페스트 내 toleration 설정
  - 이 파드는 위 node1에 배치 가능
1 2 3 4 5

tolerations: - key: "key" operator: "Equal" value: "value" effect: "NoSchedule"

Cordon/Uncordon & Drain

cordon: 지정된 노드에 파드 배포 금지
1

kubectl cordon node1
uncordon: 지정된 노드에 파드 배포 금지 해제
1

kubectl uncordon node1
drain: 지정된 노드에 모든 파드 삭제
1

kubectl drain node1 --ignore-daemonsets

Jenkins 파이프라인을 K8S Pod로 사용하기 위한 설정

Wed, 17 Sep 2025 09:00:00 +0900

Jenkins 파이프라인이 K8S pod로 사용되도록 설정

Helm으로 설치 시에는 하기 설정들이 자동으로 세팅되어 있으니 설정 불필요

Jenkins에 Kubernetes 플러그인 설치 확인
- Jenkins가 K8S API와 통신해서 pod(파이프라인 에이전트)를 생성/삭제 가능하도록 설정
Built-In-Node excutor 설정
- 파이프라인 에이전트를 k8s pod에서 동적으로 실행할거라 built-in-node(jenkins 서버 pod)의 Number of executors을 0으로 설정
K8S Configure
- Manage Jenkins > Clouds > New Cloud / Configure
- K8S URL로 Test Connection 확인
- Jenkins URL/Tunnel
  - Jenkins URL: http://jenkins.jenkins.svc.cluster.local:8080
  - Jenkins tunnel: jenkins-agent.jenkins.svc.cluster.local:50000
    - jenkins tunnel은 jnlp(파이프라인 에이전트 관리 pod)로 연결되는 FQDN 입력
    - jnlp 포트가 50000
  - url, tunnel에 도메인을 넣으면 IP가 바뀌더라도 연결 가능
    - K8S FQDN: 클러스터 DNS 규칙에 의해 만들어짐
      - FQDN 룰: <Service명>.<Namespace명>.svc.
      - cluster domain 기본값은 cluster.local
    - FQDN 예시
      - jenkins FQDN: jenkins.jenkins.svc.cluster.local
      - jenkins-agent FQDN: jenkins-agent.jenkins.svc.cluster.local
      1 2 3 4
      
      # kubectl get svc -n jenkins NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE jenkins ClusterIP 10.233.54.119 <none> 8080/TCP 11d jenkins-agent ClusterIP 10.233.57.212 <none> 50000/TCP 11d
Pod Template

파이프라인 에이전트가 K8S에서 Pod로 관리될 때의 Pod 설정을 정의

Kubernetes 환경에서 Prometheus를 많이 사용하는 이유

Fri, 12 Sep 2025 09:00:00 +0900

흔히 Kubernetes 환경에서 매트릭 모니터링으로 Prometheus를 많이 사용한다는데, 왜 많이 쓰는지, 정확한 이유를 알아보고자 작성한 글입니다.

K8S에서 Prometheus를 쓰는 이유

Prometheus 구축을 kube-prometheus-stack Helm Chart로만 구축해봤다 보니 처음에는 Helm에 그 이유가 있을 줄 알았는데, 알고 보니 Prometheus 자체가 K8S와의 호환성이 좋았다. Helm은 Prometheus를 구축하기 편하게 Chart 형태로만 패키징 해놓은 것. 이 Helm Chart의 베이스 엔진인 Prometheus-Operator도 이유 중 하나로, CRD(podmonitor, servicemonitor)로 promtheus를 관리할 수 있다.

결론적으로, 크게 아래 두 이유 때문에 K8S에서 Prometheus를 사용한다고 볼 수 있다.

K8S 환경에서의 호환성
K8S 환경에서의 관리 용이성

K8S 환경에서의 Prometheus 호환성

Prometheus는 K8S 서비스 디스커버리를 지원

내장된 서비스 디스커버리로 인해 K8S API(서비스/파드/노드/인그레스 등)가 스케일인/아웃, 신규 네임스페이스 추가되는 등등의 상황에서도 동적으로 탐색 가능
- 서비스 디스커버리: 엔드포인트를 미리 하드코딩하지 않고, 런타임에 자동으로 찾아 쓰는 패턴

K8S에서는 kubelet 프로세스가 cAdvisor를 통해서 지표를 수집하는데, 이 데이터를 Prometheus 서버가 읽어서 신규 서비스/파드 추가 시 모니터링 대상으로 자동으로 편입 가능

prometheus.yml에서 kubelet의 엔트포인트인 /metrics, /metrics/cadvisor를 스크랩하도록 설정할 경우에 Prometheus가 자동으로 읽음
바닐라 prometheus를 사용할 경우의 prometheus.yml 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


scrape_configs:
 - job_name: kubelet
 scheme: https
 metrics_path: /metrics
 kubernetes_sd_configs:
 - role: node
 bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
 tls_config:
 ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
 relabel_configs:
 - source_labels: [__meta_kubernetes_node_address_InternalIP]
 target_label: __address__
 replacement: $1:10250

 - job_name: kubelet-cadvisor
 scheme: https
 metrics_path: /metrics/cadvisor
 kubernetes_sd_configs:
 - role: node
 bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
 tls_config:
 ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
 relabel_configs:
 - source_labels: [__meta_kubernetes_node_address_InternalIP]
 target_label: __address__
 replacement: $1:10250

K8S 환경에서의 Prometheus 관리 용이성

Prometheus Operator: https://github.com/prometheus-operator/prometheus-operator
Prometheus Operator는 Prometheus를 K8S에서 사용하기 편하게 패키징한 툴
- CRD 기반의 선언형으로 Prometheus 관리 가능
  - CRD 예: ServiceMonitor, PodMonitor, PrometheusRule 등의 커스텀 리소스
  - CRD에서의 Label Selector, Namespace Selector 설정으로 신규 파드 추가 시 자동 모니터링 편입
  - kubelet을 ServiceMonitor로 생성할 경우 kubelet의 cadvisor가 수집한 지표를 이 kubelet CRD로 인해 Prometheus 서버가 읽고, 신규 서비스/파드 추가 시 모니터링 대상으로 자동으로 편입 가능
  - Prometheus CRD로 Alerting 룰 분리

kube-prometheus-stack

prometheus operator부터 grafana까지 모니터링에 필요한 올인원 Helm 패키지

구조

1
2
3
4
5
6
7
8


kube-prometheus-stack
├── Prometheus Operator (핵심 엔진)
├── Prometheus 인스턴스
├── Grafana (시각화 대시보드)
├── AlertManager (알람 관리)
├── Node Exporter (Node 매트릭 수집)
├── kube-state-metrics (K8S 리소스 매트릭 수집)
└── 기본 ServiceMonitors/PrometheusRules (정책)

기본 생성 servicemonitor 목록

아래 리스트가 전부 생성되므로 사실상 kube-prometheus-stack을 설치하는 것만으로 기본 매트릭 모니터링은 끝

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


prometheus-grafana
prometheus-kube-prometheus-alertmanager
prometheus-kube-prometheus-apiserver
prometheus-kube-prometheus-coredns
prometheus-kube-prometheus-kube-controller-manager
prometheus-kube-prometheus-kube-etcd
prometheus-kube-prometheus-kube-proxy
prometheus-kube-prometheus-kube-scheduler
prometheus-kube-prometheus-kubelet
prometheus-kube-prometheus-operator
prometheus-kube-prometheus-prometheus
prometheus-kube-state-metrics
prometheus-prometheus-node-exporter

자체 관리형 Kubernetes에서의 Prometheus와 Grafana 구축

Fri, 12 Sep 2025 09:00:00 +0900

매니지드 K8S가 아닌 자체 관리형 K8S에서의 Prometheus + Grafana 구축 방법

UI 접근을 위한 외부 통신으로 MetalLB+HAproxy+Nginx Controller가 구성 되었다는 전제 하에 구축

CSP 환경이라면 Ingress 설정에서 AWS ALB Controller와 같은 로드밸런서를 사용해 훨씬 간편하게 구축 가능

Prometheus 공식문서: https://prometheus.io/docs/prometheus/latest/installation/
Grafana 공식문서: https://grafana.com/docs/grafana/latest/setup-grafana/installation/

개요

kube-prometheus-stack helm chart 구조

1
2
3
4
5
6
7
8


kube-prometheus-stack
├── Prometheus Operator (핵심 엔진)
├── Prometheus 인스턴스
├── Grafana (시각화 대시보드)
├── AlertManager (알람 관리)
├── Node Exporter (Node 매트릭 수집)
├── kube-state-metrics (K8S 리소스 매트릭 수집)
└── 기본 ServiceMonitors/PrometheusRules (정책)

Prometheus Operator란

CRD 기반 Prometheus 관리 도구
Prometheus, ServiceMonitor, PrometheusRule 등의 Custom Resource 제공
선언적 방식으로 Prometheus 설정 관리

Prometheus + Grafana 설치

깃허브: https://github.com/prometheus-community/helm-charts

helm 리포지토리 추가

1
2
3


helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

kube-prometheus-stack 설치

prometheus + grafana 합쳐진 패키지
values.yaml 수정

1

helm show values prometheus-community/kube-prometheus-stack > values.yaml

grafana pvc 설정

1
2
3
4
5
6
7


 persistence:
 enabled: true
 type: sts
 storageClassName: "longhorn"
 accessModes:
 - ReadWriteOnce
 size: 5Gi

prometheus pvc 설정
- selector: {} 삭제
  - longhorn은 selector 지원하지 않음

1
2
3
4
5
6
7
8


 storageSpec:
 volumeClaimTemplate:
 spec:
 storageClassName: longhorn
 accessModes: ["ReadWriteOnce"]
 resources:
 requests:
 storage: 40Gi

alertmanager pvc 설정
- selector: {} 삭제
  - longhorn은 selector 지원하지 않음

1
2
3
4
5
6
7
8


 storage:
 volumeClaimTemplate:
 spec:
 storageClassName: longhorn
 accessModes: ["ReadWriteOnce"]
 resources:
 requests:
 storage: 2Gi

kube-prometheus-stack 설치

1

helm install prometheus prometheus-community/kube-prometheus-stack -f values.yaml --namespace monitoring --create-namespace

Grafana UI 접근

ingress 생성

8082포트를 사용하는 grafana service로 연결

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


cat <<EOF > grafana-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: grafana-ingress
 namespace: monitoring
 annotations:
 nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
 nginx.ingress.kubernetes.io/proxy-body-size: "50m"
spec:
 ingressClassName: nginx
 rules:
 - host: "grafana.<도메인>"
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: prometheus-grafana
 port:
 number: 80
EOF

kubectl -n monitoring apply -f grafana-ingress.yaml

HAproxy 설정

ingress를 조회하여 MetalLB로부터 부여받은 IP 확인

현재는 172.27.1.100

1
2
3
4


# kubectl get ingress -n monitoring 
# kubectl get ingress -n monitoring 
NAME CLASS HOSTS ADDRESS PORTS AGE
grafana-ingress nginx grafana.<도메인> 172.27.1.100 80 9s

확인한 IP를 HAproxy 설정에 추가

HAproxy 서버 공인 IP로 접근 시 grafana의 Ingress로 통신되도록 설정

1
2
3


vim /etc/haproxy/haproxy.cfg
haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl reload haproxy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 http-request set-header X-Forwarded-Host %[req.hdr(host)]
 http-request set-header X-Forwarded-Proto http
 http-request set-header X-Forwarded-Port %[dst_port]

 # Host 기반 라우팅
 use_backend metallb_backend_grafana if { hdr(host) -m sub grafana }

backend metallb_backend_grafana
 server grafana 172.27.1.100:80

접근 성공!

Grafana 관리자 비밀번호 확인

1

kubectl --namespace monitoring get secrets prometheus-grafana -o jsonpath="{.data.admin-password}" | base64 -d ; echo

대시보드 그래프 origin not allowed 에러 발생 시

IP주소로의 직접 접근을 Grafana의 CSRF 정책이 요청 차단

도메인을 통해 접근해서 CSRF 정책 통과

ingrass, haproxy에 설정되어있던 grafana.local을 새로 설정한 도메인으로 변경
values.yaml 수정

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


 grafana:
 ...
 adminPassword: <GRAFANA_PASSWORD>
 grafana.ini:
 server:
 domain: <도메인>:48082
 root_url: http://<도메인>:48082
 security:
 csrf_trusted_origins: "<도메인>:48082"
 csrf_cookies_secure: false
 cookie_secure: false
 cookie_samesite: lax
 ...

설정 반영

1
2
3
4



helm uninstall prometheus --namespace monitoring
kubectl --namespace monitoring delete pvc --all
helm install prometheus prometheus-community/kube-prometheus-stack -f values.yaml --namespace monitoring

Prometheus UI 접근

ingress 생성

8080포트를 사용하는 prometheus service로 연결

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


cat <<EOF > prometheus-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: prometheus-ingress
 namespace: monitoring
 annotations:
 nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
 nginx.ingress.kubernetes.io/proxy-body-size: "50m"
spec:
 ingressClassName: nginx
 rules:
 - host: "prometheus.local"
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: prometheus-kube-prometheus-prometheus
 port:
 number: 9090
EOF

kubectl -n monitoring apply -f prometheus-ingress.yaml

HAproxy 설정

ingress를 조회하여 MetalLB로부터 부여받은 IP 확인

현재는 172.27.1.100

1
2
3


# kubectl get ingress -n monitoring 
NAME CLASS HOSTS ADDRESS PORTS AGE
prometheus-ingress nginx prometheus.<도메인> 172.27.1.100 80 9s

확인한 IP를 HAproxy 설정에 추가

HAproxy 서버 공인 IP로 접근 시 prometheus의 Ingress로 통신되도록 설정

1
2
3


vim /etc/haproxy/haproxy.cfg
haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl reload haproxy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 http-request set-header X-Forwarded-Host %[req.hdr(host)]
 http-request set-header X-Forwarded-Proto http
 http-request set-header X-Forwarded-Port %[dst_port]

 # Host 기반 라우팅
 use_backend metallb_backend_prometheus if { hdr(host) -m sub prometheus }

backend metallb_backend_prometheus
 server prometheus 172.27.1.100:80

접근 성공!

자체 관리형 Kubernetes에서의 분산 스토리지 Longhorn 구축

Sun, 07 Sep 2025 09:00:00 +0900

매니지드 K8S가 아닌 자체 관리형 K8S에서의 Longhorn 구축 방법

UI 접근을 위한 외부 통신으로 MetalLB+HAproxy+Nginx Controller가 구성 되었다는 전제 하에 구축

CSP 환경이라면 Ingress 설정에서 AWS ALB Controller와 같은 로드밸런서를 사용해 훨씬 간편하게 구축 가능

개요

자체 관리형 K8S에서 애플리케이션의 데이터를 고가용성으로 운영하려면 Ceph, Longhorn 같은 분산 블록 스토리지 툴이 필요
- 노드마다 데이터를 복제해서 저장하는 분산 블록 스토리지
- Ceph, Longhorn 같은 툴이 없다면 파드는 워커노드의 로컬 경로에만 데이터를 저장해야 하는데, 이러면 워커노드 장애가 발생할 경우 데이터 가용성 보장이 안됨
  - NFS를 StorageClass로 사용할 수 도 있지만, NFS는 단일 서버, 단일 네트워크 I/O에 의존하기 때문에, 성능과 장애 내구성이 떨어져 PV 데이터 저장 용도로는 부적합
- Ceph 퍼포먼스가 더 뛰어나지만 리소스 자원을 꽤 점유하는 툴이므로, 현재 환경에서는 Longhorn을 사용
  - 워커 노드가 5대 이상, 8vCPU 16GB 이상인 스펙이어도 Longhorn으로 충분히 운영 가능

Longhorn을 쓰면 PVC를 생성하는 것 만으로도 PV가 자동으로 프로비저닝됨!!!

AWS라면 EBS같은 스토리지를 통해 고가용성 확보 가능
- ALB Controller와 마찬가지로 CSP 관리형 K8S를 쓰는 또하나의 이유

구조

PVC가 생성되면 Longhorn Volume을 관리하는 Engine Pod가 생성되고, 하위에 Replica Pod들이 각 노드에 생성됨
- Replica Pod는 해당 노드의 특정 경로에 전체 데이터 replica를 저장
- 쓰기 I/O는 Engine Pod가 받아서 모든 Replica Pod에 동기 복제한 뒤 성공을 리턴
Pod가 노드1에서 노드2로 옮겨지면 Longhorn이 볼륨을 노드1에서 detatch 했다가 노드2로 attatch
- 이때 노드2에 Replica가 있으면 그대로 사용, 없으면 다른 Replica에서 동기받아서 새 Replica 생성

Longhorn 설치

helm 리포지토리 추가s

1
2


helm repo add longhorn https://charts.longhorn.io
helm repo update

values.yaml 수정

1
2
3


helm pull longhorn/longhorn --untar
cd longhorn
vim values.yaml

1
2
3
4
5
6
7
8


persistence:
 ...
 defaultClassReplicaCount: 2

defaultSettings:
 ...
 defaultDataPath: /data
 defaultReplicaCount: 2

helm 설치

1
2
3
4
5


helm install longhorn longhorn/longhorn \
 --namespace longhorn-system \
 --create-namespace \
 --values values.yaml
kubectl -n longhorn-system get pod

Longhorn UI 접속

https://longhorn.io/docs/1.9.1/deploy/accessing-the-ui/

auth 파일 생성

반드시 auth라는 이름으로 생성 필요

1

USER=<USERNAME_HERE>; PASSWORD=<PASSWORD_HERE>; echo "${USER}:$(openssl passwd -stdin -apr1 <<< ${PASSWORD})" >> auth

secret 생성

1

kubectl -n longhorn-system create secret generic basic-auth --from-file=auth

ingress 생성

80포트를 사용하는 longhorn service로 연결

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


cat <<EOF > longhorn-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: longhorn-ingress
 namespace: longhorn-system
 annotations:
 # type of authentication
 nginx.ingress.kubernetes.io/auth-type: basic
 # prevent the controller from redirecting (308) to HTTPS
 nginx.ingress.kubernetes.io/ssl-redirect: 'false'
 # name of the secret that contains the user/password definitions
 nginx.ingress.kubernetes.io/auth-secret: basic-auth
 # message to display with an appropriate context why the authentication is required
 nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required '
 # custom max body size for file uploading like backing image uploading
 nginx.ingress.kubernetes.io/proxy-body-size: 10000m
spec:
 ingressClassName: nginx
 rules:
 - host: "longhorn.local"
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: longhorn-frontend
 port:
 number: 80
EOF

kubectl -n longhorn-system apply -f longhorn-ingress.yaml

HAproxy 설정

ingress를 조회하여 MetalLB로부터 부여받은 IP 확인

현재는 172.27.1.100

1
2
3


# kubectl get ingress -n longhorn-system 
NAME CLASS HOSTS ADDRESS PORTS AGE
longhorn-ingress nginx longhorn.local 172.27.1.100 80 8s

확인한 IP를 HAproxy 설정에 추가

HAproxy 서버 공인 IP로 접근 시 Longhorn의 Ingress로 통신되도록 설정

1
2
3


vim /etc/haproxy/haproxy.cfg
haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl reload haproxy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 http-request set-header X-Forwarded-Host %[req.hdr(host)]
 http-request set-header X-Forwarded-Proto http
 http-request set-header X-Forwarded-Port %[dst_port]

 # Host 기반 라우팅
 use_backend metallb_backend_longhorn if { hdr(host) -m sub longhorn }

backend metallb_backend_longhorn
 server longhorn 172.27.1.100:80

접근 성공!

자체 관리형 Kubernetes에서의 Jenkins 구축

Fri, 29 Aug 2025 09:00:00 +0900

매니지드 K8S가 아닌 자체 관리형 K8S에서의 Jenkins 구축 방법

UI 접근을 위한 외부 통신으로 MetalLB+HAproxy+Nginx Controller가 구성 되었다는 전제 하에 구축

CSP 환경이라면 Ingress 설정에서 AWS ALB Controller와 같은 로드밸런서를 사용해 훨씬 간편하게 구축 가능

Jenkins 공식문서: ****https://www.jenkins.io/doc/book/installing/kubernetes/

Jenkins 설치

Helm 리포지토리 추가

1
2


helm repo add jenkinsci https://charts.jenkins.io
helm repo update

jenkins-ci 네임스페이스 생성
1

kubectl create ns jenkins

jenkins-pv 생성(기존 StorageClass 없을 시에만 진행)

기존에 사용하던 Ceph, Longhorn, EBS Driver, Harbor 같은 StorageClass가 없을 경우에 로컬 경로를 사용한 PV 할당 방법
- StorageClass가 있다면 PVC 생성 시 자동으로 PV가 할당되기 때문에 이 과정은 불필요

1
2


vim jenkins-01-volume.yaml
kubectl apply -f jenkins-01-volume.yaml

https://raw.githubusercontent.com/jenkins-infra/jenkins.io/master/content/doc/tutorials/kubernetes/installing-jenkins-on-kubernetes/jenkins-01-volume.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


apiVersion: v1
kind: PersistentVolume
metadata:
 name: jenkins-pv
spec:
 storageClassName: jenkins-pv
 accessModes:
 - ReadWriteOnce
 capacity:
 storage: 20Gi
 persistentVolumeReclaimPolicy: Retain
 hostPath:
 path: /data/jenkins-volume/

---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
 name: jenkins-pv
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer

ServiceAccount 생성

1
2


vim jenkins-02-sa.yaml
kubectl apply -f jenkins-02-sa.yaml

https://raw.githubusercontent.com/jenkins-infra/jenkins.io/master/content/doc/tutorials/kubernetes/installing-jenkins-on-kubernetes/jenkins-02-sa.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76


---
apiVersion: v1
kind: ServiceAccount
metadata:
 name: jenkins
 namespace: jenkins
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
 annotations:
 rbac.authorization.kubernetes.io/autoupdate: "true"
 labels:
 kubernetes.io/bootstrapping: rbac-defaults
 name: jenkins
rules:
- apiGroups:
 - '*'
 resources:
 - statefulsets
 - services
 - replicationcontrollers
 - replicasets
 - podtemplates
 - podsecuritypolicies
 - pods
 - pods/log
 - pods/exec
 - podpreset
 - poddisruptionbudget
 - persistentvolumes
 - persistentvolumeclaims
 - jobs
 - endpoints
 - deployments
 - deployments/scale
 - daemonsets
 - cronjobs
 - configmaps
 - namespaces
 - events
 - secrets
 verbs:
 - create
 - get
 - watch
 - delete
 - list
 - patch
 - update
- apiGroups:
 - ""
 resources:
 - nodes
 verbs:
 - get
 - list
 - watch
 - update
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
 annotations:
 rbac.authorization.kubernetes.io/autoupdate: "true"
 labels:
 kubernetes.io/bootstrapping: rbac-defaults
 name: jenkins
roleRef:
 apiGroup: rbac.authorization.k8s.io
 kind: ClusterRole
 name: jenkins
subjects:
- apiGroup: rbac.authorization.k8s.io
 kind: Group
 name: system:serviceaccounts:jenkins

jenkins 설치

https://github.com/jenkinsci/helm-charts/tree/main/charts/jenkins

helm으로 설치
values.yaml 수정

1
2
3
4


wget https://raw.githubusercontent.com/jenkinsci/helm-charts/main/charts/jenkins/values.yaml
vim values.yaml

helm install jenkins -n jenkins -f values.yaml jenkinsci/jenkins

helm을 통해 pvc 자동 생성

pv는 longhorn이 자동으로 프로비저닝
SA는 2번에서 생성한 리소스 사용

1
2
3
4
5
6
7


persistence:
 storageClass: longhorn
 size: "20Gi"

serviceAccount:
 create: false
 name: jenkins

Jenkins UI 접근

ingress 생성

8080포트를 사용하는 jenkins service로 연결

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


cat <<EOF > jenkins-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: jenkins-ingress
 namespace: jenkins
 annotations:
 nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
 nginx.ingress.kubernetes.io/proxy-body-size: "50m"
spec:
 ingressClassName: nginx
 rules:
 - host: "jenkins.<도메인>"
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: jenkins
 port:
 number: 8080
EOF

kubectl -n jenkins apply -f jenkins-ingress.yaml

HAproxy 설정

ingress를 조회하여 MetalLB로부터 부여받은 IP 확인

현재는 172.27.1.100

1
2
3


# kubectl get ingress -n jenkins
NAME CLASS HOSTS ADDRESS PORTS AGE
jenkins-ingress nginx jenkins.<도메인> 172.27.1.100 80 26h

확인한 IP를 HAproxy 설정에 추가

HAproxy 서버 공인 IP로 접근 시 jenkins의 Ingress로 통신되도록 설정
http-response replace-value Location ^http://jenkins\.<도메인>/(.*)$ http://jenkins.<도메인>:<포트>/\\1
두 조건을 만족할 경우 설정 필요
- 외부 브라우저에서 Jenkins 접근 시 포트를 붙여서 접근해야 될 경우
- 애플리케이션 내부적으로 url로 응답이 나오도록 설정되어 있을 경우
  - EX) Jenkins 파이프라인 빌드 시 파라미터를 기입해야 할 경우 Jenkins 설정된 url 응답
설정하지 않으면 접근 시 자동으로 포트가 제거된 상태로 리다이렉션되어 404 에러

1
2
3


vim /etc/haproxy/haproxy.cfg
haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl reload haproxy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 http-request set-header X-Forwarded-Host %[req.hdr(host)]
 http-request set-header X-Forwarded-Proto http
 http-request set-header X-Forwarded-Port %[dst_port]

 # Host 기반 라우팅
 use_backend metallb_backend_jenkins if { hdr(host) -m sub jenkins }

backend metallb_backend_jenkins
 http-response replace-value Location ^http://jenkins\.<도메인>/(.*)$ http://jenkins.<도메인>:<포트>/\\1
 server jenkins 172.27.1.100:80

접근 성공!

Jenkins 관리자 비밀번호 확인

1
2
3


jsonpath="{.data.jenkins-admin-password}"
secret=$(kubectl get secret -n jenkins jenkins -o jsonpath=$jsonpath)
echo $(echo $secret | base64 --decode)

외부에서 자체 관리형 Kubernetes 접근을 위한 MetalLB/HAproxy 설정과 통신 구조

Sun, 24 Aug 2025 09:00:00 +0900

외부에서의 로컬 K8S 클러스터 접근을 위해 MetalLB와 HAproxy를 사용
K8S 클러스터 내부의 로드밸런서로는 nginx controller를 사용 중인 상태
- AWS라면, ALB Controller 하나만으로 MetalLB+HAproxy+nginxcontroller 기능을 커버 가능
- 사실상의 CSP의 K8S를 쓰는 이유??

MetalLB

https://metallb.universe.tf/installation/

클러스터 내부용 로드밸런서
- 오픈소스
- CSP의 LB를 사용하지 못하는 경우(내/외부 양쪽에서 사용가능한 LB)에, 내부용 L4 로드밸런서로 사용하기 위해 주로 MetalLB를 사용

사전 준비

kube-proxy의 configmap에서 strictARP 활성화

1
2
3
4
5
6
7


kubectl edit configmap -n kube-system kube-proxy

apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
mode: "ipvs"
ipvs:
 strictARP: true

MetalLB 설치

helm으로 설치

1
2


helm repo add metallb https://metallb.github.io/metallb
helm install metallb metallb/metallb

MetalLB 설정

IP Pool 설정

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
 name: default-pool
 namespace: default
spec:
 addresses:
 - 172.27.1.100-172.27.1.110
EOF

L2Advertisement 설정

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
 name: default
 namespace: default
spec:
 ipAddressPools:
 - default-pool
EOF

HAproxy

haproxy 설치

1
2


yum install -y haproxy
systemctl enable --now haproxy

haproxy 설정
- Jenkins를 예시로 구성
  1 2 3
  
  # kubectl get ingress -n jenkins NAME CLASS HOSTS ADDRESS PORTS AGE jenkins-ingress nginx jenkins.local 172.27.1.100 80 26h
  - 파드가 MetalLB로부터 부여받은 IP가 172.27.1.100일 경우 하기와 같이 설정
    - 백엔드 헬스체크는 MetalLB에서 하고 있으니 HAproxy에선 설정하지 않음
  - http-request set-header Host
    - 클라이언트에서 오는 모든 HTTP 요청의 Host 헤더를 jenkins.local로 변경
  - http-request del-header X-Forwarded-Host
    - 이전 프록시에서 설정한 Host 헤더 제거
  - http-request del-header X-Forwarded-Proto
    - 이전 프록시에서 설정한 프로토콜 정보 제거
  1 2 3 4 5 6 7 8
  
  tee /etc/haproxy/haproxy.cfg > /dev/null <<EOF frontend jenkins_frontend bind *:8080 default_backend metallb_backend backend metallb_backend server metallb 172.27.1.100:80 EOF

통신 구조

jenkins 파드가 하기와 같이 구성되어 있다 가정할 때 통신 구조
- 현재 외부에서의 접근 시 80/443 포트를 사용하지 못하고 별도의 포트를 사용해야 하는 환경이기 때문에 8080포트를 사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# kubectl get ingress -n jenkins
NAME CLASS HOSTS ADDRESS PORTS AGE
jenkins-ingress nginx jenkins.local 172.27.1.100 80 26h
# kubectl get all -n jenkins 
NAME READY STATUS RESTARTS AGE
pod/jenkins-0 2/2 Running 0 9d

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/jenkins ClusterIP 10.233.5.87 <none> 8080/TCP 9d
service/jenkins-agent ClusterIP 10.233.28.70 <none> 50000/TCP 9d

NAME READY AGE
statefulset.apps/jenkins 1/1 9d

브라우저에서 <도메인>:8080으로 접속
DNS 해석되어 공인IP:8080으로 라우팅
- 공인IP:8080는 HAproxy 서버
HAproxy frontend 설정으로 8080포트로 들어오는 요청을 HAproxy backend로 라우팅
- HAproxy backend는 172.27.1.100:80
172.27.1.100 IP는 MetalLB의 IP 풀에서부터 할당받은 Nginx Controller의 IP
- Nginx Ingress Controller는 LoadBalancer 타입 Service
Nginx Ingress Controller는 HAproxy backend로부터 받은 트래픽의 Host 헤더가 Jenkins Ingress에 정의된 Host인 jenkins.local인지 확인
Jenkins Ingress에 정의된 규칙에 따라 Jenkins Service로 라우팅
Jenkins Service에서 Jenkins Pod로 라우팅

Kubernetes Autoscaling Overview

Fri, 22 Aug 2025 09:00:00 +0900

오토스케일링 종류

클러스터 레벨 오토스케일링
- 노드 풀의 VM 개수를 오토스케일링
- 클라우드 프로바이더와 같은 환경에서만 가능(EKS, GKE, AKS 등)
파드 레벨 오토스케일링
- 파드의 개수를 오토스케일링

수평적 파드 오토스케일링(HPA)

metrics-server 애드온이 필요
- 각 노드/파드가 사용하는 매트릭(CPU/MEM) 모니터링하고 데이터 수집하는 역할

동작원리

HPA 컨트롤러가 metrics-server에서 Pod 매트릭을 주기적으로 수집하고, 사전에 설정한 임계치 조건을 만족하면 파드의 개수를 자동으로 조정

HPA 동작 조건

기본값 30초 간격으로 Pod 사용량을 점검
임계값을 초과하면 Pod scale out
확장된 이후 3분 대기, scale in은 확장 이후 5분 대기

예시

myapp Deployment가 CPU 사용 평균 50%를 넘기면 Pod 개수가 늘어남
만약 CPU 사용률이 낮아지면, 5분 이후 Pod 개수를 줄임
Pod 개수는 최소 2개, 최대 10개 사이에서 조정됨

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
 name: myapp-hpa
spec:
 scaleTargetRef:
 apiVersion: apps/v1
 kind: Deployment
 name: myapp
 minReplicas: 2
 maxReplicas: 10
 metrics:
 - type: Resource
 resource:
 name: cpu
 target:
 type: Utilization
 averageUtilization: 50

애플리케이션 지표 기반 오토스케일링도 가능하지만, prometheus와 같은 툴과 연동 필요

Kubernetes Storage Overview

Thu, 21 Aug 2025 09:00:00 +0900

Pod에서 볼륨 선언 → 마운트가 기본 패턴
- spec.volumes에서 볼륨 선언 후 spec.containers.volumeMounts 에서 마운트

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


apiVersion: v1
kind: Pod
metadata:
 name: demo-pod
spec:
 containers:
 - name: app
 image: nginx:1.25
 volumeMounts:
 - name: html
 mountPath: /usr/share/nginx/html
 volumes:
 - name: html
 hostPath:
 path: /home/
 type: DirectoryOrCreate

볼륨 유형

타입	사용 용도	비고
emptyDir	Pod 수명=데이터 수명. 임시 공간	Pod 종료 시 데이터 없어짐
hostPath	노드 로컬 경로를 Pod에 마운트	데이터가 특정 워커노드에 종속됨
configMap / secret	변수를 파일로 주입	주로 읽기 전용으로 마운트
nfs	NAS 마운트	멀티 Pod 간 데이터 공유에 사용
CSI 기반 블록 / 파일	AWS EDB, GCE PD 등	대부분 CSI 드라이버로 제공
동적 프로비저닝 가능

예시: emptyDir / configMap / secret

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# emptyDir
volumes:
 - name: work
 emptyDir: {}

# configMap
volumes:
 - name: app-config
 configMap:
 name: my-config

# secret
volumes:
 - name: app-secret
 secret:
 secretName: db-cred

PV & PVC

PV(PersistentVolume): 클러스터에 영구 스토리지 리소스를 생성
PVC(PersistentVolumeClaim): 생성한 PV에서 자원 할당 요청

접근 모드

ReadWriteOnce(RWO): 한 노드에서 읽기/쓰기
ReadOnlyMany(ROX): 여러 노드에서 읽기 전용
ReadWriteMany(RWX): 여러 노드에서 읽기/쓰기
- ex) NFS, EFS
pv/pvc 예시
- persistentVolumeReclaimPolicy 기본값은 동적 프로비저닝이면 Delete인 경우가 많고, 중요한 데이터면 Retain 고려

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


# 1) PV: NFS 예시
apiVersion: v1
kind: PersistentVolume
metadata:
 name: pv-nfs
spec:
 capacity:
 storage: 20Gi
 accessModes: [ReadWriteMany]
 persistentVolumeReclaimPolicy: Retain
 nfs:
 path: /export/apps
 server: 10.0.0.10

---
# 2) PVC: 위 PV에 바인딩될 요청
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: pvc-nfs
spec:
 accessModes: [ReadWriteMany]
 resources:
 requests:
 storage: 20Gi

StorageClass

디스크 타입, 복제/백업 정책, 토폴로지 등의 프로비저닝에 필요한 파라미터를 묶어서 제공
사용자는 PVC에서 StorageClassName에만 지정하면 볼륨이 동적 프로비저닝됨
사용을 위해선 NFS Provisioner, EBS Driver와 같은 툴 설치 필요

kube-proxy 모드(iptables vs IPVS)

Tue, 19 Aug 2025 09:00:00 +0900

Kubernetes kube-proxy: iptables vs IPVS

K8S에서 Service를 만들면, 클러스터 내부 Pod는 ClusterIP를 통해 접근 가능
- 이때 트래픽을 실제 Pod로 보내주는 역할을 하는 게 kube-proxy
kube-proxy는 iptables 모드와 IPVS 모드 두가지 모드 중 하나로 동작 가능

iptables 모드

K8S 초창기부터 기본으로 사용된 방식

동작 원리
- service/endpoint 정보를 iptables 규칙에 직접 기록
- 커널이 NAT 체인을 따라가면서 Pod로 트래픽을 전송
장점
- 별도 모듈 설치 없이 바로 사용 가능
- 오래 쓰여온 만큼 안정적이고, 문제 생겼을 때 iptables -t nat -L -n 으로 바로 확인 가능
단점
- 엔드포인트 수가 많아지면 규칙도 폭발적으로 늘어나 성능 저하가 생길 수 있음
- 규칙을 갱신할 때 전체 체인을 다시 써야 해서 순간 부하 발생

IPVS 모드

리눅스 커널의 IPVS 기능을 사용

동작 원리
- ip_vs 모듈을 이용해 L4 로드밸런서처럼 동작
- kube-proxy는 service/endpoint를 커널에 등록만 해두고, 실제 트래픽 처리는 커널이 빠르게 처리
장점
- 수천~수만 엔드포인트까지 안정적으로 처리 가능
- 엔드포인트 변경 시 필요한 부분만 업데이트 → 부하 적음
- 라운드로빈, 세션 해시 등 다양한 로드밸런싱 알고리즘 지원
단점
- 커널 모듈(ip_vs)과 유틸리티(ipvsadm, ipset) 설치 필요
- iptables에 비해 디버깅이 낯설 수 있음 (ipvsadm -Ln 확인 필요)

선택 기준

iptables 모드
- 수십~수백 노드, 수천 개 엔드포인트 수준
- 운영 단순성, 문제 대응 속도 중시
IPVS 모드
- 수천 노드 이상, 서비스 엔드포인트 수가 수만 단위
- 대규모 SaaS 환경, 트래픽이 매우 많은 서비스
- 고급 로드밸런싱(세션 어피니티 등) 필요한 경우

kubespray는 기본적으로 IPVS로 동작

Kubernetes ConfigMap과 Secret

Sun, 17 Aug 2025 09:00:00 +0900

Kubernetes에서 애플리케이션을 배포할 때 환경변수나 설정 등을 관리하는 방법
- Pod yaml에 직접 값을 적을수도 있지만 재사용/보안을 위해 ConfigMap/Secret을 사용

Configmap

key-value 쌍으로 정의
DB 호스트, 포트, 로그 레벨 등의 민감하지 않은 설정 값을 저장할 때 사용

예시 - 환경변수

ConfigMap

1
2
3
4
5
6
7
8


apiVersion: v1
kind: ConfigMap
metadata:
 name: app-config
 namespace: demo
data:
 APP_MODE: "production"
 LOG_LEVEL: "debug"

Pod

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: v1
kind: Pod
metadata:
 name: sample-pod
 namespace: demo
spec:
 containers:
 - name: sample-app
 image: nginx
 envFrom:
 - configMapRef:
 name: app-config

예시 - 파일 형태로 마운트

ConfigMap

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


apiVersion: v1
kind: ConfigMap
metadata:
 name: nginx-config
data:
 nginx.conf: |
 events {}
 http {
 server {
 listen 80;
 location / {
 return 200 'Hello ConfigMap!';
 }
 }
 }

Pod

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


volumes:
 - name: config-volume
 configMap:
 name: nginx-config
containers:
 - name: nginx
 image: nginx
 volumeMounts:
 - mountPath: /etc/nginx/nginx.conf
 subPath: nginx.conf
 name: config-volume

Secret

key-value 쌍으로 정의
Base64로 인코딩하여 저장
비밀번호, 인증 토큰, TLS 키 등 민감한 데이터를 저장할 때 사용
AWS Secrets Manager, Vault와 같은 Secret CSI Driver을 연동해서 사용 가능

예시 - 환경변수

ConfigMap

1
2
3
4
5
6
7
8


apiVersion: v1
kind: Secret
metadata:
 name: db-secret
type: Opaque
data:
 username: ZGJ1c2Vy # "dbuser" → base64 인코딩
 password: c2VjcmV0MTIz # "secret123"

Pod

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


containers:
 - name: db-client
 image: postgres
 env:
 - name: DB_USER
 valueFrom:
 secretKeyRef:
 name: db-secret
 key: username
 - name: DB_PASS
 valueFrom:
 secretKeyRef:
 name: db-secret
 key: password

예시 - 도커 레지스트리 인증 정보

Secret

1
2
3
4
5
6
7


apiVersion: v1
kind: Secret
metadata:
 name: regcred
type: kubernetes.io/dockerconfigjson
data:
 .dockerconfigjson: <Base64-encoded-json>

Kubernetes Label과 Annotation

Sun, 17 Aug 2025 09:00:00 +0900

LoadBalancer

L4 - NLB + Service의 LoadBalancer

웹서버가 아닌 백엔드 서비스(API, DB 프록시 등)에 대한 부하 분산에 적합

TCP/UDP 레벨에서 패킷을 라우팅
L7 - ALB + Ingress

웹 애플리케이션 HTTP/HTTPS 트래픽 부하 분산에 적합

URL 경로, 호스트명 등 애플리케이션 계층의 규칙 기반 라우팅 가능

Ingress

트래픽 부하 분산 (HTTP/HTTPS)
경로 기반 라우팅

예: /, /home, /pay, /login
도메인 기반 라우팅

예: www.example.com, www.test.com
SSL/TLS 인증서 처리

HTTPS 통신을 위한 인증서 설치 및 자동 갱신(Let’s Encrypt 등과 연계 가능)

경로 기반 라우팅 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: path-based-ingress
spec:
 ingressClassName: nginx
 rules:
 - host: shop.example.com
 http:
 paths:
 - path: /products
 pathType: Prefix
 backend:
 service:
 name: product-service
 port:
 number: 80
 - path: /orders
 pathType: Prefix
 backend:
 service:
 name: order-service
 port:
 number: 80

호스트 기반 라우팅 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: host-based-ingress
spec:
 ingressClassName: nginx
 rules:
 - host: api.example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: api-service
 port:
 number: 80
 - host: admin.example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: admin-service
 port:
 number: 80

Ingress Architecture

Client(HTTP/HTTPS) → Ingress Controller(Ingress Rules 라우팅) → Service(ClusterIP) → Pod

Ingress Controller
- Ingress 리소스에 정의된 Ingress Rules를 읽고 동작
  - Input:
  - Output: :80
- 실제 트래픽은 Service(ClusterIP)를 통해 Pod로 전달
Service (ClusterIP)
- Input: :80
- Output: <pod’s label>:80
Deployment(ReplicaSet, Pod)
- 여러 Pod를 레플리카로 생성해 무중단 운영 가능

Ingress Controller 종류

로컬(Kubernetes On-Prem, Minikube 등) → NGINX Ingress Controller 사용
AWS EKS → AWS Load Balancer Controller(ALB 기반) 사용
- ALB와 연동해 L7 라우팅 처리
- ACM(AWS Certificate Manager)로 TLS 인증서 관리 가능

Kubernetes Ingress Overview

Wed, 13 Aug 2025 09:00:00 +0900

LoadBalancer

L4 - NLB + Service의 LoadBalancer

웹서버가 아닌 백엔드 서비스(API, DB 프록시 등)에 대한 부하 분산에 적합

TCP/UDP 레벨에서 패킷을 라우팅
L7 - ALB + Ingress

웹 애플리케이션 HTTP/HTTPS 트래픽 부하 분산에 적합

URL 경로, 호스트명 등 애플리케이션 계층의 규칙 기반 라우팅 가능

Ingress

트래픽 부하 분산 (HTTP/HTTPS)
경로 기반 라우팅

예: /, /home, /pay, /login
도메인 기반 라우팅

예: www.example.com, www.test.com
SSL/TLS 인증서 처리

HTTPS 통신을 위한 인증서 설치 및 자동 갱신(Let’s Encrypt 등과 연계 가능)

경로 기반 라우팅 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: path-based-ingress
spec:
 ingressClassName: nginx
 rules:
 - host: shop.example.com
 http:
 paths:
 - path: /products
 pathType: Prefix
 backend:
 service:
 name: product-service
 port:
 number: 80
 - path: /orders
 pathType: Prefix
 backend:
 service:
 name: order-service
 port:
 number: 80

호스트 기반 라우팅 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: host-based-ingress
spec:
 ingressClassName: nginx
 rules:
 - host: api.example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: api-service
 port:
 number: 80
 - host: admin.example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: admin-service
 port:
 number: 80

Ingress Architecture

Client(HTTP/HTTPS) → Ingress Controller(Ingress Rules 라우팅) → Service(ClusterIP) → Pod

Ingress Controller
- Ingress 리소스에 정의된 Ingress Rules를 읽고 동작
  - Input:
  - Output: :80
- 실제 트래픽은 Service(ClusterIP)를 통해 Pod로 전달
Service (ClusterIP)
- Input: :80
- Output: <pod’s label>:80
Deployment(ReplicaSet, Pod)
- 여러 Pod를 레플리카로 생성해 무중단 운영 가능

Ingress Controller 종류

로컬(Kubernetes On-Prem, Minikube 등) → NGINX Ingress Controller 사용
AWS EKS → AWS Load Balancer Controller(ALB 기반) 사용
- ALB와 연동해 L7 라우팅 처리
- ACM(AWS Certificate Manager)로 TLS 인증서 관리 가능

Kubernetes Service Overview

Tue, 12 Aug 2025 09:00:00 +0900

Pod 그룹에 대해 단일 진입점(VIP) 제공
외부에서 클러스터 내에 파드 그룹에 접근할 수 있도록 기능 제공

서비스 종류

ClusterIP ⇒ (외부 → 내부) VIP
NodePort ⇒ (외부 → 내부) VIP + NodePort
LoadBalancer ⇒ (외부 → 내부) VIP + NodePort + LB IP
ExternalName ⇒ (내부 → 외부) 도메인 매핑

ClusterIP

Pod그룹에 대해 단일 진입점(VIP)을 제공
VIP는 사설 IP로 제공됨

~/root/kubespray/inventory/mycluster/group_vars/k8s_cluster

1
2


kube_service_addresses: 10.233.0.0/18
kube_pods_subnet: 10.233.64.0/

예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


apiVersion: v1
kind: Service
metadata:
 name: my-clusterip-service
spec:
 selector:
 app: myapp
 ports:
 - port: 80
 targetPort: 8080
 type: ClusterIP

NodePort

Pod그룹에 대해 단일 진입점(VIP)을 제공
노드의 IP:Port(30000 ~ 32727)로 요청하면 Pod 그룹(같은 Label)에 대한 부하 분산을 제공

예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: v1
kind: Service
metadata:
 name: my-nodeport-service
spec:
 selector:
 app: myapp
 ports:
 - port: 80
 targetPort: 8080
 nodePort: 30080
 type: NodePort

LoadBalancer

Pod그룹에 대해 단일 진입점(VIP)을 제공
노드의 IP:Port(30000 ~ 32727)로 요청하면 Pod 그룹(같은 Label)에 대한 부하 분산을 제공
클라우드 환경(AWS ELB, GCP LB, Azure LB) 또는 MetalLB/HAProxy 등의 On-premise LB 사용

예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


apiVersion: v1
kind: Service
metadata:
 name: my-lb-service
spec:
 selector:
 app: myapp
 ports:
 - port: 80
 targetPort: 8080
 type: LoadBalancer

ExternalName - DNS CNAME 역할

(내부 → 외부/내부) DNS CNAME 등록 작업(서비스 이름 ← 매핑 → DNS 이름) (pod 예) .default.pod.cluster.local ← 매핑 → google.com (service 예) .default.svc.cluster.local ← 매핑 → google.com

예시

1
2
3
4
5
6
7


apiVersion: v1
kind: Service
metadata:
 name: my-external-service
spec:
 type: ExternalName
 externalName: google.com

헤드리스 서비스

단일 진입점이 필요 없는 경우에 사용 (clusterIP: None)
각 Pod의 IP가 DNS A 레코드로 직접 등록됨
주로 StatefulSet(DB, Kafka 등)에서 사용

예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


apiVersion: v1
kind: Service
metadata:
 name: my-headless-service
spec:
 clusterIP: None
 selector:
 app: myapp
 ports:
 - port: 80
 targetPort: 8080

네트워크

kube-proxy
- worker node안에 pod에 연결할 때 사용하는 네트워크를 담당
- Masquerading (IP 변환)
- Load Balancing (포트포워딩)
kube-proxy 모드
- iptables 모드 ⇒ iptables CMD
- ipvs 모드 ⇒ ipvsadm CMD

Kubernetes Workload Overview

Mon, 11 Aug 2025 09:00:00 +0900

ReplicaSet

동일한 스펙의 Pod를 지정된 개수만큼 유지
집합 기반 셀렉터(Set-based selector)
rolling update 지원
직접 쓰기보다는 Deployment 내부에서 주로 사용됨

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


apiVersion: apps/v1
kind: ReplicaSet
metadata:
 name: my-replicaset
spec:
 replicas: 3
 selector:
 matchExpressions:
 - key: app
 operator: In
 values: ["web", "api"]
 template:
 metadata:
 labels:
 app: web
 spec:
 containers:
 - name: nginx
 image: nginx:1.27

Deployment

ReplicaSet을 관리하며 Pod의 개수를 보장
Pod에 대한 rolling update/rollback 기능 지원
무중단 파드 배포를 위해 사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


apiVersion: apps/v1
kind: Deployment
metadata:
 name: my-deployment
spec:
 replicas: 3
 selector:
 matchLabels:
 app: web
 strategy:
 type: RollingUpdate
 rollingUpdate:
 maxUnavailable: 1
 maxSurge: 1
 template:
 metadata:
 labels:
 app: web
 spec:
 containers:
 - name: nginx
 image: nginx:1.27

DaemonSet

하나의 노드당 1개의 Pod 실행(controlplane 제외)
Rolling Update / Rollback 기능 지원
데몬셋 용도: (관리) ex) 모니터링 Pod 실행

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


apiVersion: apps/v1
kind: DaemonSet
metadata:
 name: node-monitor
spec:
 selector:
 matchLabels:
 app: node-monitor
 template:
 metadata:
 labels:
 app: node-monitor
 spec:
 containers:
 - name: node-exporter
 image: prom/node-exporter:latest

StatefulSet

State가 필요한 워크로드에 사용(Pod 이름, 스토리지 고정)
고유 네트워크 ID, 안정적인 스토리지, 순차 배포/종료 보장
주로 DB, 메시지 큐, Zookeeper, Kafka 등에 사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


apiVersion: apps/v1
kind: StatefulSet
metadata:
 name: web-stateful
spec:
 serviceName: "web"
 replicas: 3
 selector:
 matchLabels:
 app: web
 template:
 metadata:
 labels:
 app: web
 spec:
 containers:
 - name: nginx
 image: nginx:1.27
 volumeClaimTemplates:
 - metadata:
 name: www
 spec:
 accessModes: ["ReadWriteOnce"]
 resources:
 requests:
 storage: 1Gi

Job

트랜잭션의 단위
잡이 성공적으로 종료 될 때 까지 지속적으로 파드 실행
잡이 성공하면 completed
잡은 실패하면 종료 후 다시 실행

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: batch/v1
kind: Job
metadata:
 name: data-migration
spec:
 backoffLimit: 3
 template:
 spec:
 containers:
 - name: migrate
 image: busybox
 command: ["sh", "-c", "echo Running migration... && sleep 10"]
 restartPolicy: OnFailure

CronJob

Job 컨트롤러를 사용하여 애플리케이션 파드를 주기적으로 반복해서 실행
Job이 종료되면 스케쥴링에 의해 주기적으로 실행
Job이 비정상 종료되면 다시 실행

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


apiVersion: batch/v1
kind: CronJob
metadata:
 name: db-backup
spec:
 schedule: "0 2 * * *" # 매일 새벽 2시
 jobTemplate:
 spec:
 template:
 spec:
 containers:
 - name: backup
 image: busybox
 command: ["sh", "-c", "echo Backing up DB... && sleep 5"]
 restartPolicy: OnFailure

Kubernetes Pod Overview

Wed, 06 Aug 2025 09:00:00 +0900

Pod

컨테이너를 추상화 시켜 놓은 단위
k8s에서 배포하는 최소 단위
하나의 Pod에는 여러 Container가 들어 갈 수 있다
Pod는 하나의 IP를 갖는다

Multi-Container Pod

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


Liveness Probe
- httpGet
 - livenessProbe:
 httpGet:
 path: /
 port: 80
- tcpSocket
 - livenessProbe:
 tcpSocket:
 port: 22
- exec:
 - livenessProbe:
 exec:
 command:
 - ls
 - /tmp/datafile

Liveness Probe Parameter
- initialDelaySeconds: 0
- periodSeconds: 5
- timeoutSeconds: 1
- successThreshold: 1
- failureThreshold: 2

initcontainer

앱 컨테이너가 동작하기 위한 전초 작업을 위한 컨테이너

(WEB-DB) 환경의 WEB 컨테이너에서 DB 컨테이너가 기동되었는지를 위한 작업
(Network) 네트워크 인프라 점검을 위한 전초 작업

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


spec:
 containers:
 - name: myapp-container
 image: busybox:1.28
 command: ['sh', '-c', 'echo The app is running! && sleep 3600']
 initContainers:
 - name: init-myservice
 image: busybox:1.28
 command: ['sh', '-c', "until nslookup myservice.$(cat /var/run/secrets/kubernetes.io/serviceaccount/namespace).svc.cluster.local; do echo waiting for myservice; sleep 2; done"]
 - name: init-mydb
 image: busybox:1.28
 command: ['sh', '-c', "until nslookup mydb.$(cat /var/run/secrets/kubernetes.io/serviceaccount/namespace).svc.cluster.local; do echo waiting for mydb; sleep 2; done"]

Infra/pause container

앱컨테이너의 인프라를 생성 및 삭제를 담당하는 컨테이너

Static Pod

/var/lib/kubelet/config.yaml
- staticPodPath: /etc/kubernetes/manifests

Pod 자원 할당

자원 할당

cpu(단위: 1core/1vCPU = 1000m)
mem(단위: 500Mi, 1Gi, ..)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


apiVersion: v1
kind: Pod
metadata:
 name: nginx-pod-resources
spec:
 containers:
 - name: nginx-container
 image: nginx:1.14
 ports:
 - containerPort: 80
 protocol: TCP
 resources:
 requests:
 cpu: 200m
 memory: 250Mi
 limits:
 cpu: 1
 memory: 1Gi

Pod 환경 변수

환경 변수 설정

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


kind: Pod
apiVersion: v1
metadata:
 name: mysql-env-pod
spec:
 containers:
 - name: mysql-container
 image: mysql
 ports:
 - containerPort: 3306
 protocol: TCP
 env:
 - name: MYSQL_ROOT_PASSWORD
 value: "password"

디자인 패턴

사이드카 - 협업
어댑터 - 입력 표준화
앰버서더 - 출력 표준화

Kubernetes 아키텍쳐

Tue, 05 Aug 2025 09:00:00 +0900

Nginx Ingress Controller

k8s 외부에서 들어오는 http/https 트래픽을 1차적으로 처리하는 Entry Point

Ingress Controller가 없다면 NodePort Service 만으로 Pod를 열어야한다.
Ingress 리소스를 통해 내부 서비스로 라우팅
TLS Termination, 리버스 프록시, 로드 밸린싱 등 수행 가능

https://docs.nginx.com/nginx-ingress-controller/installation/installing-nic/installation-with-helm/

helm을 통한 설치

1

helm install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version 2.2.1

helm을 통한 설치 시 옵션 수정이 필요한 경우
- 하기 명령어로 pull한 helm chart의 values.yaml에서 옵션 수정

1

helm pull oci://ghcr.io/nginx/charts/nginx-ingress --untar --version 2.2.1

수정한 옵션 적용하여 설치

1

helm install my-release .

Kubernetes 아키텍쳐

Mon, 04 Aug 2025 09:00:00 +0900

Master Node

kube-apiserver

Kubernetes 클러스터의 프론트엔드입니다.
REST API를 통해 클러스터 상태를 읽고 조작하는 모든 요청을 처리합니다.

kubectl

kubectl은 kube-apiserver에 요청을 보냅니다. (예: kubectl get nodes)
또는, kubectl을 사용하지 않고도 직접 kube-apiserver에 요청을 보낼 수 있습니다.

controller-manager

클러스터의 상태를 지속적으로 모니터링하고, 원하는 상태를 유지합니다.
다양한 컨트롤러들(잡, 노드, 서비스 계정, 엔드포인트)을 관리하여 리소스의 상태를 조정합니다.

kube-scheduler

스케줄러는 새로 생성된 Pod를 워커 노드에 배치하는 역할을 합니다.
Pod의 리소스 요구사항과 각 노드의 리소스 가용성을 고려해 최적의 노드에 배치합니다.

ETCD

Kubernetes의 클러스터 데이터를 저장하는 분산 key-value 데이터베이스입니다.
클러스터의 현재 상태, 구성 정보, 시크릿, ConfigMap 등을 저장하는 데 사용됩니다.

Worker Node

kubelet

각 워커 노드에서 실행되며, API 서버와 통신하면서 Pod의 라이프사이클을 관리합니다.
kube-scheduler가 할당한 작업을 워커 노드에서 실행합니다.

kube-proxy

네트워크 트래픽을 라우팅하고 로드밸런싱하는 데 사용되는 기본 네트워크 프록시입니다.
Pod과 서비스 간의 통신 규칙을 설정합니다.

container runtime

실제 컨테이너를 실행하는 소프트웨어입니다.
Containerd, CRI-O 등이 Kubernetes에서 사용될 수 있으며, 컨테이너 이미지를 다운로드하고 실행, 관리하는 역할을 합니다.

Addons

CoreDNS

클러스터 내에서 서비스 디스커버리와 DNS 네임 리졸버를 제공합니다
이를 통해 서비스 이름을 클러스터 내부의 IP로 변환할 수 있습니다.

CNI

네트워크를 관리하기 위한 표준 인터페이스입니다.
각 Pod에 IP 주소를 할당해서, 다른 Pod와의 통신을 가능하게 만듭니다.
대표적인 플러그인으로는 Calico, Flannel 등이 있습니다.

Kubernetes Helm 설치

Sun, 03 Aug 2025 09:00:00 +0900

Kubernetes에서 사용하는 여러 플러그인 및 툴의 yaml 파일들을 패키징하여 쉽게 설치할 수 있는 툴
- values.yaml을 통해 툴들의 옵션 조정 가능

1
2
3
4


cd
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh --version v3.17.4

3.18.5 버전에서 helm 설치 시에 values.schema.json이 원격 $ref(HTTPS)로 참조하는 JSON Schema를 불러오면 검증 단계에서 실패하는 이슈가 있어서 3.17.4 버전 명시

https://github.com/helm/helm/issues/31136?utm_source=chatgpt.com

1
2
3
4
5
6


[root@master1 ~]# helm install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version 2.2.1
Pulled: ghcr.io/nginx/charts/nginx-ingress:2.2.1
Digest: sha256:00f7a7017799eafc7f109cca10204a9dc2bc2d2f0feafb8eff328d13e2cedd12
Error: INSTALLATION FAILED: values don't meet the specifications of the schema(s) in the following chart(s):
nginx-ingress:
failing loading "https://raw.githubusercontent.com/nginxinc/kubernetes-json-schema/master/v1.33.1/_definitions.json": invalid file url: https://raw.githubusercontent.com/nginxinc/kubernetes-json-schema/master/v1.33.1/_definitions.json

자체 관리형 Kubernetes에서 NFS를 통한 StorageClass 사용

Thu, 31 Jul 2025 09:00:00 +0900

AWS의 경우 EBS Driver를 통해 pvc를 위한 StorageClass를 사용 가능
- 로컬 Kubernetes에서도 StorageClass를 사용하기 위해 NFS 서버를 구축해서 사용
NFS 서버 구축

1
2
3
4
5
6
7
8
9


dnf install -y nfs-utils

systemctl enable --now nfs-server

mkdir -p /exports/k8s-pv
chown -R nobody:nobody /exports/k8s-pv
chmod 777 /exports/k8s-pv
echo "/exports/k8s-pv *(rw,sync,no_subtree_check,no_root_squash)" | sudo tee -a /etc/exports
exportfs -rav

Helm을 통한 NFS Provisioner 설치

1
2
3
4


helm repo add nfs-subdir-external-provisioner https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner/
helm repo update

helm install nfs-provisioner nfs-subdir-external-provisioner/nfs-subdir-external-provisioner --set nfs.server=172.27.1.9 --set nfs.path=/exports/k8s-pv --set storageClass.name=nfs-sc --set storageClass.defaultClass=true

pvc 생성

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: test-pvc
spec:
 accessModes:
 - ReadWriteMany
 resources:
 requests:
 storage: 1Gi
 storageClassName: nfs-sc

pod 생성

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: test-pvc
spec:
 accessModes:
 - ReadWriteMany
 resources:
 requests:
 storage: 1Gi
 storageClassName: nfs-sc

Kubespray를 사용한 Kubernetes 클러스터 배포 (자체 관리형 Kubernetes)

Fri, 25 Jul 2025 09:00:00 +0900

https://github.com/kubernetes-sigs/kubespray

Kubespray를 사용해 설치
- kubespray 2.27 버전을 사용하여 Kubernetes 1.31버전 클러스터 구성
최소 4대가 필요
- 배포 서버 1EA
  - 도커로 Kubespray를 배포하고, Kubernetes CRI로 containerd를 사용할 거기 때문에 Master Node에서 배포 불가해서 별도의 배포 서버 필요
- Master Node 1EA
- Worker Node 2EA

사전작업

모든 Master, Worker Node에 작업

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


# vim 설정
cat << EOF >> ~/.bashrc
alias vi='/usr/bin/vim'
EOF

cat << EOF >> ~/.vimrc
syntax on
autocmd FileType yaml setlocal ai nu ts=2 sw=2 et
autocmd Filetype python setlocal ai nu ts=2 sw=2 et
EOF

. ~/.bashrc

# DNS 서버가 없으므로 /etc/hosts 파일 사용
cat << EOF >> /etc/hosts
172.27.1.9 master.k8s.com master
172.27.0.182 node1.k8s.com node1
172.27.1.35 node2.k8s.com node2
EOF

# cri 전부 제거
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo dnf remove $pkg -y; done

CKA 후기

Sat, 04 Jan 2025 09:00:00 +0900

자격증들은 보통 깊은 기술을 요구하기 보단 넓고 얕게 아는 걸 요구하기 때문에 자격증 취득은 그 기술에 대해 어느 정도 알아보는 데 도움이 된다고 생각한다. 관련해서 쿠버네티스도 CKA 자격증 취득을 쿠버네티스 공부의 첫 목표로 잡았다.

CKA는 시험에 불합격 하더라도 retake 기회를 1회 제공하고, 자격증 유효 기간은 내가 합격 했을 땐 3년이었지만 지금은 2년으로 알고 있다.

할인 코드

Linux Foundation은 40% 할인 쿠폰을 1년에 두세번 정도 배포한다. 40%가 아니더라도 30%정도는 상시 할인하는 느낌이니 쿠폰은 반드시 적용해야 한다.

공부 방법 및 기간

CKA를 공부했다면 모두가 아는 mumshad 선생님의 udemy 강의(https://www.udemy.com/course/certified-kubernetes-administrator-with-practice-tests/?couponCode=KEEPLEARNING)를 통해 기초를 잡았다. 외에도 따배쿠 유튜브도 많이 보는 것 같다.

CKA를 신청하면 Linux Foundation에서 killer.sh 문제를 풀어 볼 수 있게 제공했던 걸로 기억하는데, 다른 블로그에서 하나같이 시험 난이도에 비해 killer.sh가 훨씬 어렵다고 해서 한번도 풀어보지 않았다. 대신 https://www.itexams.com/exam/CKA 여기 있는 문제들과 다른 블로그들을 참고해서 연습용 문제들을 골랐다.

공부 기간은 3주동안 매일 4시간 정도였는데, 그때는 리눅스를 약간 다룰 수 있는 정도였고 K8S는 하나도 몰랐으니 K8S를 다뤄 봤다면 더 짧아질 수 있을 것이다.

연습 환경

문제 풀이 실습들은 https://killercoda.com/cka에서 하는 걸 적극 추천한다. CKA는 쿠버네티스 구축에 대한 역량은 고려하지 않기 때문에 VM같은 걸로 K8S 구축하는데 에너지를 쏟기 보다 killercoda를 사용하는 게 좋다.

이 사이트는 K8S를 테스트 하는데 최적화되어 있는데, 무료는 1개 세션에서 클러스터 1개와 노드 1개를 1시간 동안 사용할 수 있지만 이정도면 충분하다. 1시간이 지나더라도 그 세션만 초기화 되고 다시 사용할 수 있기 때문에 한문제 풀고 초기화하고 또 풀면 된다.

시험 환경

CKA는 정해진 시험장이 없기 때문에 보통 노트북을 가지고 시험을 본다. 노트북은 캠과 오디오가 동작해야 한다. 시험 신청을 하면 안내 메일이 오는데, 여기에 시험 환경을 테스트 할 수 있는 링크가 있다. 그 링크에서 캠/오디오 등등을 체크 해야 시험 당일에 곤란하지 않을 것이다. 또 감독관 쪽에서 내 노트북을 원격으로 감시해야 하는데, 혹시 몰라서 윈도우 방화벽도 내렸다.

시험 시작 30분 전부터 시험 환경인 PSI 브라우저를 설치할 수 있다. 접속하면 감독관이 본인 확인과 방 안 검사를 요구하는데, 이 시간 안에 감독관한테 ok가 나와야 이후 시험에 지장이 가지 않는다. 본인 확인은 여권을 지참해야 한다.

정해진 시험장이 없는 만큼 주위 환경도 깨끗해야 한다. 노트북을 제외한 어떤 것도 시험장에 있으면 안되고, 벽에 안내문 같은 종이 붙어 있다면 어떻게든 가려야 한다. 나는 집에서는 이 환경을 구성하기가 어려울 것 같아, 공유 오피스에서 최대한 조용한 구석으로 자리를 잡았다.

시험 팁

모든 문제는 그 문제만의 k8s context가 명시되어 있다. 따라서 문제 풀기 전에 반드시 context 체크부터 해야 한다.
PSI 브라우저에서 https://kubernetes.io/docs/home/ 공식 문서에 접근이 가능하다. 즉 오픈북 시험이란 것. 대부분의 문제에 대한 구축 과정을 공식 문서에서 확인이 가능하니 그 문서를 빨리 찾을 수 있게 연습하는 것도 좋을 것이다. 특히 K8S Upgrade나 ETCD Backup 문제 같은 경우 공식 문서를 참조하는 걸 추천한다.

시험 변경점

문제들은 처음 나왔을 때부터 지금까지 변경이 거의 없는 것으로 알고 있는데, 올해 1월 15부터 변경이 있다고 한다.

https://www.youtube.com/watch?v=fvvgM3QmKGo

https://www.inflearn.com/notices/1375488

실무에서 사용하는 기술들을 많이 반영한 것 같은데, 대표적으로

Helm 차트
Kustomize
CRD

등등이 추가되고 기존 문제도 강화된다고 한다.