Subin's Blog

번외 — 컨테이너 메모리와 런타임 메모리

hsb_02 — Mon, 17 Aug 2026 15:00:02 +0900

1. 막힌 자리

번외 — 노드 메모리와 쿠버네티스 메모리를 진행할 때는 노드 한 대를 밖에서 봤다. 메모리 숫자를 내는 자리를 층으로 갈랐다.

리눅스 층 — 커널이 센다. /proc/meminfo의 MemTotal·MemAvailable, 지표로는 node-exporter의 node_memory_*. 도로 가져갈 수 있는 것(페이지 캐시)과 없는 것(익명 메모리)으로 갈린다
cgroup 층 — 커널이 센다. cgroup 파일의 memory.current·memory.stat, 지표로는 cAdvisor의 container_memory_working_set_bytes. 프로세스 묶음별로 세고, 그 묶음에 상한을 건다
쿠버네티스 층 — kubelet이 계산해 적는다. memory.max는 cgroup 파일에 쓰고 allocatable·requests는 apiserver에 보고한다. 지표로는 kube-state-metrics의 kube_*. 노드를 나눈 선을 cgroup 파일로 옮기는 층이다

그 구분으로 인프라 대시보드 행1 — 노드 한 대의 메모리를 선언(스케줄러가 보는 값)과 실사용(커널이 보는 값)으로 갈라 놓은 표 — 의 뺄셈을 고쳤다.

다음 작업이 스펙 재산정, 파드 스펙에 적어 둔 requests·limit을 실측으로 다시 정하는 일이었다. 둘은 하는 일이 다르다.

requests — 쿠버네티스만 아는 선언. 스케줄러가 자리를 잡을 때 쓰고, 노드가 빡빡해지면 어느 파드를 먼저 내보낼지도 정한다
limit — cgroup 상한. 회수 불가한 사용이 넘으면 커널이 OOMKill 한다

컨테이너 전수의 requests·실사용·limit을 한 표로 놓으니 어긋난 모양이 셋이었다.

모양	크기	무엇이 문제인가
requests 과대 (requests > 사용)	4,859 MiB	자리를 잡아 두고 안 쓴다
requests 과소 (사용 > requests)	1,018 MiB	압박이 오면 이 파드부터 나간다
limit 임박 (peak 가 limit 의 76-90%)	컨테이너 9개	조금 더 쓰면 OOMKill 이다

과대·과소·임박 셋은 독립이 아니다. requests를 넘겨 쓰는데 limit에 여유가 많으면 선언이 작은 것이고, requests는 맞는데 limit만 좁으면 상한이 작은 것이다. requests·실사용·limit을 같이 놓아야 어느 쪽을 고칠지가 갈린다.

AI가 낸 컴포넌트 표

세 모양을 잡으려면 컨테이너마다 값을 다시 정해야 한다. 나는 AI에게 클러스터 전수 분석을 맡겼고, AI가 지금 문제가 된다고 판단한 자리를 이렇게 냈다.

컴포넌트	지금 상태	낸 조치
Tempo	차트 기본값 밸러스트 1,024 MiB · GOMEMLIMIT 800 MiB · GC 12.58 회/초 · CPU 120 m. `go_memstats_heap_alloc` 1,039 MiB 인데 `process_resident_memory` 109 MiB	밸러스트를 0 으로 끈다
Kafka 브로커 ×3	`-Xmx` 없음 · MaxRAMPercentage 60 → 힙 상한 921 Mi · 사용 621-643 Mi	`-Xmx 512m` 명시 후 재측정
Argo controller	`go_memstats_heap_alloc` 127 Mi · `process_resident_memory` 359-487 Mi	`GOGC=50` · `GOMEMLIMIT=384MiB`
Strimzi operator	`-Xmx` 없음 · 실사용 281 Mi · request 256 Mi · limit 384 Mi	힙을 고정한다
Mimir ingester ×3	request 768 Mi · limit 2 Gi	실측 RSS 로 재산정

그 밖에 Alloy request 상향 · Loki 내장 캐시 상한 재배분 · Redis maxmemory 설정이 같이 나왔다.

"지금 상태" 열이 읽히지 않았다

Tempo 행만 봐도 그렇다. GOMEMLIMIT 800 MiB가 무엇을 거는 값인지, GC 12.58 회/초가 많은 것인지 적은 것인지, 1,039 MiB와 109 MiB가 나란히 있는 것이 정상인지. 판단이 서는 항목이 하나도 없었다.

훑어 보니 같은 낱말이 행마다 반복되고 있었고, 그 낱말들을 나는 정확히 모른다.

낱말	모르는 것
힙 · 스택	둘이 어떻게 다른지 나올 때마다 헷갈린다
런타임	말은 자주 보는데 무엇을 가리키는지 흐릿하다
RSS	지표 이름은 읽히는데 무엇을 잰 값인지 모른다
GC · GOGC	언제 왜 도는지 모른다
-Xms · -Xmx · MaxRAMPercentage · GOMEMLIMIT	자바 쪽에서 힙 크기를 정한 적이 있고 여기서도 같은 종류가 나오는데, 서로 어떻게 다른지 모른다
비힙	힙 밖에도 뭔가 있다는 것만 안다

낱말들이 서로 이어져 있다는 것은 안다. 한 덩어리라는 감은 있다. 그런데 이어져 있다는 것까지가 아는 전부고, 어디가 어디에 어떻게 붙는지는 모른다. 값을 왜 그렇게 정하느냐 이전에, 무엇이 문제라는 것인지조차 이해가 안 됐다.

모르는 낱말은 AI가 낸 표 밖에도 있다

같은 낱말을 나는 클러스터를 세우는 동안 이미 여러 번 적어 뒀다. AI가 낸 컴포넌트 표에 없는 것만 꼽아도 이렇다.

적어 둔 자리	적어 둔 것
booking values	`JAVA_OPTS: -XX:MaxRAMPercentage=75`
topicOperator	`-Xms: 64m` · `-Xmx: 128m`
booking 대시보드 패널 설명	"limit 1Gi 의 75%인 768Mi가 힙이고, 나머지는 클래스 정보와 컴파일해 둔 기계어가 쓴다. 힙이 상한 가까이 붙어 있으면 GC가 잦아진다"

나는 적을 때 설계를 AI 에 맡기고 이해는 뒤로 미뤘다.

그래서 나는 스펙 재산정을 여기서 멈추고 이 편을 쓴다. 이해를 먼저 쌓고, 내가 설계한 것을 되짚는다.

절 배치

컨테이너 밖은 리눅스 층·cgroup 층·쿠버네티스 층으로 갈랐고, 그 끝에서 나온 것이 컨테이너에 걸리는 상한 memory.max다. 이 편은 그 상한의 안쪽이다.

절	세우는 것	다음 절에 넘기는 것
2	힙 · 스택 · 스레드당 스택	힙 크기는 코드만 봐선 모른다
3	런타임 · 힙 지표	힙에 얼마나 있는지는 런타임만 안다
4	VSZ · RSS	힙 지표와 RSS 가 벌어져 있다
5	GC · GOGC · 손잡이	GC 페이스는 상한을 안 정한다
6	두 상한 · `working_set` · 비힙 · 사용자 수준 스레드 · 앱이 거는 상한	낱말이 다 선다

안을 파헤치다 보면 밖에서 정리해 둔 것과 다시 만난다.

밖에서 정리한 것	안에서 다시 만나는 자리
익명 메모리(회수 불가) / 페이지 캐시(회수 가능)	4절 — RSS 안이 같은 기준으로 갈린다
익명 메모리의 예로 든 Kafka 브로커의 607 Mi	6절 — 그 익명이 힙과 비힙으로 갈린다
`memory.max` — 커널이 강제하는 상한	6절 — 런타임이 스스로 지키는 상한과 마주 세운다

memory.max가 걸린 묶음 안에서 프로세스 하나가 무엇을 받는지부터 본다.

2. 힙과 스택

프로세스가 커널에게서 받는 것은 메모리 자체가 아니라 쓸 수 있는 주소의 범위다. 이것을 주소 공간이라 한다.

높은 주소
┌──────────────────┐
│  스택             │   함수 호출마다 쌓이고, 함수가 끝나면 사라진다
├──────────────────┤
│     (빈 공간)     │
├──────────────────┤
│  힙               │   실행 중에 "달라"고 요청해서 받는다.  위로 자란다
├──────────────────┤
│  data · bss      │   전역 변수
├──────────────────┤
│  text            │   기계어 코드.  읽기 전용
└──────────────────┘
낮은 주소

그림은 자리만 보여 준다. 조각마다 무엇이 들어가고 크기가 언제 정해지는지가 다르다.

조각	여기 들어가는 것	언제 정해지나	분류
text	함수 본체를 기계어로 번역한 것	컴파일할 때. 실행 내내 안 변한다	정적
data	초기값이 있는 전역 변수 — `var limit = 300000`	컴파일할 때. 값까지 실행 파일 안에 들어 있다	정적
bss	초기값이 없는 전역 변수 — `var total int64`	컴파일할 때 자리만. 값은 시작할 때 0으로 채운다	정적
스택	지금 실행 중인 함수의 지역 변수·매개변수, 그 함수가 끝나면 돌아갈 자리	함수에 들어가면 잡히고 나오면 풀린다	자동
힙	프로그램이 "이만큼 달라"고 해서 받아 낸 자리. 요청 하나마다 만드는 객체, 네트워크나 디스크에서 읽어 들인 바이트, 나중에 쓰려고 들고 있는 캐시 — 셋 다 몇 개가 생길지를 들어오는 일감이 정한다	실행 중에 요청한 만큼. 언제 버릴지도 실행 중에 정해진다	동적

앞의 셋은 실행 파일에서 크기가 읽힌다. 남는 것이 스택과 힙인데, 스택은 스레드 수에 스택 크기를 곱하면 나오고 힙은 돌려 보기 전에는 모른다. 그 둘을 차례로 본다.

스택은 스레드마다 하나씩, 늘리면 값이 붙는다

text·data·bss·스택·힙으로 나뉜다는 것은 프로세스가 실행 흐름 하나일 때의 그림이다. 스레드를 여럿 돌리면 갈린다.

프로세스 하나
├─ text · data · bss        하나.  스레드 전부가 공유
├─ 힙                       하나.  스레드 전부가 공유
│                             요청마다 만든 객체, 읽어 온 응답 바이트, 쌓아 둔 캐시
├─ 스레드 A ─ 스택 A       스레드 하나 몫으로 따로 예약
│               ├ main()    프레임
│               ├ handle()  프레임
│               └ parse()   프레임   ← 지금 실행 중. 반환하면 이 칸만 풀린다
└─ 스레드 B ─ 스택 B
                └ ...

함수마다 생기는 것은 스택이 아니라 그 안의 프레임 한 칸이다. 스택은 스레드가 만들어질 때 한 번 잡히고, 함수를 부를 때마다 지역 변수·매개변수·돌아갈 주소를 담은 프레임이 그 안에 쌓인다. 반환하면 그 칸만 풀린다.

스택은 스레드마다 붙으니 동시 실행을 늘리면 개수도 그만큼 는다. 커널이 만들고 커널이 굴리는 이 스레드를 OS 스레드라 한다. 여기에 값이 둘 붙는다.

스택 크기 — 리눅스는 OS 스레드 하나에 기본 8 MiB를 예약한다. 다만 프로그램이 스레드를 만들 때 이 값을 직접 넘길 수 있고, JVM은 그렇게 한다(리눅스 x64 기본 -Xss 1 MiB)
문맥 교환 — CPU 하나가 여러 스레드를 번갈아 돌리려면 돌던 것의 실행 상태를 저장하고 다음 것을 복원해야 한다. 스레드는 이 일을 커널이 한다

그래서 스레드 개수가 늘면 커널 자원과 문맥 교환 비용이 같이 는다.

힙은 무엇이 어떻게 올라가고, 누가 버리나

먼저 올라가는 쪽이다. 소스 어디에도 "이건 힙에 둬라"라고 적지 않는다. 이 클러스터의 두 언어가 그것을 서로 다르게 정한다.

Go — 컴파일러가 가른다.

func newTicket() *Ticket {
    t := Ticket{seat: "A12"}   // 함수 안에서 만든 값
    return &t                  // 그 값이 있는 자리의 주소를 밖으로 넘긴다
}

함수가 끝나면 프레임은 풀리는데 부른 쪽은 그 주소를 들고 계속 쓴다. 스택에 뒀다면 이미 없어진 자리를 가리키게 된다. 그래서 컴파일러가 코드를 훑어 함수 밖으로 새어 나가는 값만 골라 힙으로 보낸다. 같은 모양의 코드라도 밖으로 안 넘기면 스택에 남는다.

Java — new 를 쓰면 힙이다.

Ticket t = new Ticket("A12");

스택 프레임            힙
┌───────────┐      ┌─────────────────┐
│ t = 0x7f… │ ───► │  Ticket("A12")  │
└───────────┘      └─────────────────┘

변수 t 는 스택 프레임 안에 있지만 그 안에 든 것은 객체가 아니라 힙에 있는 객체의 주소다. 가르는 판단이 없으니 new 를 부른 횟수가 곧 힙에 쌓인 개수가 된다.

정하는 주체는 컴파일러와 new 로 다른데, 둘 다 프로그래머가 "힙"이라고 쓰지 않고 얼마나 쌓일지는 실행 중에 들어오는 일감이 정한다. 그래서 힙이 얼마나 커질지는 코드만 읽어서 알 수 없다.

이제 버리는 쪽이다. 올라간 자리는 다 쓰고 나면 버려야 한다. 그리고 버리는 문제가 남는 것은 힙뿐이다 — text와 data는 프로세스가 죽을 때까지 그대로 있고, 스택은 함수가 끝나면 저절로 풀린다. 힙만 함수 경계와 수명이 안 묶여 있어서 자동으로 풀릴 자리가 없다. 안 버리면 계속 쌓이고(누수), 아직 쓰는 것을 버리면 프로그램이 깨진다.

그런데 버리는 문장이 어느 코드에도 없다. Go에도 Java에도 "이제 이 자리를 반납한다"고 적는 자리가 없다. 그런데도 힙이 끝없이 부풀지 않고 쓰던 객체가 사라지지도 않으니, 코드 밖에서 그 일을 하는 무엇이 있다는 뜻이다. 그것이 다음 절이다.

3. 런타임

앞 절이 질문 하나를 남겼다. 힙을 버린다고 적은 문장이 코드에 없는데, 그럼 누가 버리나.

그 "코드 밖의 무엇"의 이름이 런타임이다.

일반적으로 런타임 시스템은 스택과 힙을 구축하고 관리하는 책임이 일부 있으며 쓰레기 수집, 스레드, 그 밖에 해당 언어로 빌드되는 동적 기능들과 같은 기능들을 포함할 수 있다.
— 위키백과 · 런타임 시스템

정의에 스택·힙 관리와 쓰레기 수집이 그대로 들어 있다. 이 글에서 쓰는 말로 줄이면, 내가 짠 코드와 같은 프로세스 안에서 함께 도는 코드인데 내가 짜지 않았고 실행할 때 이미 들어와 있다.

하는 일이 셋이다.

힙을 잡아 준다 — 앱이 "객체 하나 만들자"고 하면 힙에서 자리를 떼어 준다. 무엇이 올라갈지는 컴파일러와 new 가 정했고, 그 자리를 실제로 떼어 주는 쪽이 이것이다
다 쓴 것을 치운다 — 아무도 안 쓰게 된 자리를 되쓸 수 있게 만든다. 코드에 없던 그 문장이 여기 있다
실행 단위를 스케줄링한다 — 어느 코드를 어느 스레드 위에서 돌릴지 정한다. 셋 중 여기서 처음 나오는 것이다

어느 언어에 있고, 어디서 오나

모든 언어에 런타임이 있는 것은 아니다.

언어	컴파일 결과	런타임	이 클러스터의 파드
C · C++	기계어	없다 — `free`·`delete` 를 직접 부른다	Redis · MySQL
Go	기계어	실행 파일 안에 함께 묶여 나온다	Tempo · Loki · Mimir · Alloy · Argo · queue
Java	바이트코드 (JVM 이 읽는 중간 형식)	그것을 읽어 돌리는 JVM 본체 `libjvm.so`	Kafka 브로커 · booking · Strimzi

C 와 Go 는 둘 다 기계어로 컴파일되는데 런타임 유무가 갈린다. 컴파일 방식이 정하는 것이 아니고, 그래서 힙을 버린다고 적는 문장(free)이 C 에만 있다.

Go 와 Java 는 둘 다 런타임이 있으니 하는 일 셋을 둘 다 한다. 다만 하는 방식이 갈리고, 셋 중 아직 안 본 것이 하나 남았다.

실행 단위는 런타임이 굴린다

여기까지가 힙이다 — 런타임이 잡아 주고 런타임이 치운다. 그런데 런타임이 손대는 것이 힙만은 아니다.

스택은 스레드마다 붙는다. 그리고 CPU 하나가 여러 스레드를 번갈아 돌리려면 매번 실행 상태를 저장하고 복원해야 한다(문맥 교환). 둘 다 커널 몫이라, 스레드를 하나 늘릴 때마다 스택이 하나 더 잡히고 커널이 할 일도 그만큼 는다.

Go 와 Java 의 런타임이 같은 우회로를 냈다. 커널이 아니라 런타임 자신이 스케줄링하는 실행 단위를 만들고, 그 위에서 코드를 돌린다.

그러면 스택도 커널이 안 잡아 준다. 런타임이 그 몫을 스스로 마련해야 하고, 어디서 마련하느냐가 갈린다.

	누가 만들고 굴리나	스택 크기	스택이 잡히는 자리
OS 스레드	커널	리눅스 기본 8 MiB 예약. JVM 은 `-Xss` 1 MiB	힙 밖
고루틴 (Go)	Go 런타임	2 KiB 로 시작해 필요하면 늘린다	힙 밖
가상 스레드 (Java 21)	JVM	필요한 만큼 자란다	힙 안

셋이 세 축에서 갈린다.

커널이 굴리나, 런타임이 굴리나 — 고루틴과 가상 스레드는 런타임이 굴린다. 이 둘을 묶어 사용자 수준 스레드라 한다. OS 스레드를 안 쓴다는 뜻은 아니고 그 위에 얹혀서 도는 것이며, 커널이 아는 것은 OS 스레드까지다
런타임이 스택을 어디에 마련하나 — Go 런타임은 힙과 따로 셈하는 자리에 두고, JVM 은 가상 스레드의 스택을 힙 안에 객체로 둔다
그래서 그 몫을 덮는 값이 갈린다 — OS 스레드는 -Xss × 스레드 수로 힙 밖에서, 고루틴은 GOMEMLIMIT 안에서, 가상 스레드는 -Xmx 안에서 센다

이름만 짚고 넘어간다. 셋이 각각 무엇을 정하는 값이고 그 값을 넘으면 어떻게 되는지는 6절이다 — 셋이 같은 종류가 아니다. 하는 일 셋 중 셋째가 여기까지다.

힙에 얼마나 있는지는 런타임만 안다

힙을 잡아 주는 것도 치우는 것도 실행 단위를 굴리는 것도 런타임이다. 그러니 힙에 무엇이 얼마나 있는지도 런타임만 안다. 힙이 얼마나 커질지는 코드만 읽어서 알 수 없다고 했는데, 런타임이 세어 내주는 지표를 읽으면 나온다.

그 지표를 보기 전에 힙이 어디에 있는 것인지부터 놓고 본다. 힙은 커널이 프로세스에 준 주소 공간의 한 조각이었고, 그 주소 공간은 메모리 자체가 아니라 쓸 수 있는 번지 범위였다.

파드
 └ 컨테이너
     └ 프로세스 ─ 주소 공간 ─ text · data · bss · 스택 · 힙   ← 런타임이 아는 칸

컨테이너 하나에 프로세스 하나가 보통이다. 파드에 컨테이너가 더 있거나 앱이 자식 프로세스를 띄우면 이 줄기가 옆으로 늘어나는데, 늘어난 몫은 어차피 이 숫자 밖이다.

그 안쪽 한 칸을 세는 숫자가 이것이다.

Go    go_memstats_heap_alloc_bytes          할당돼 아직 해제되지 않은 힙 객체의 합
JVM   jvm_memory_used_bytes{area="heap"}    힙 영역에 들어 있는 양

둘 다 지금 그 프로세스의 힙에 객체가 얼마나 들어앉아 있는지를 센다. 주소 공간이 프로세스마다 하나씩이니 힙도 프로세스마다 하나씩이고, 이 숫자는 계측된 그 프로세스 하나의 것이다.

파드가 쓰는 메모리로 읽기에는 너무 좁다. 힙 한 칸만 세니, 같은 프로세스의 스택과 실행 파일 코드가 이미 이 숫자 밖이고 컨테이너나 프로세스가 더 있으면 그것들도 밖이다.

그래서 이 숫자로는 파드가 메모리를 얼마나 쓰는지 말할 수 없다.

힙 밖까지 세는 지표는 따로 있다. 프로세스에 물리 메모리가 얼마나 붙었는지는 OS 가 알고 있고, 그것을 내주는 것이 process_resident_memory_bytes 다. 줄여서 RSS 라 부른다.

여기까지가 이 절이 답한 것이다. 힙을 버리는 것은 런타임이고, 힙에 얼마가 들어 있는지는 런타임이 내주는 지표에 나온다. 그 숫자가 힙 한 칸짜리라는 것까지 왔다. 다음 절은 그 바깥을 세는 RSS 를 판다.

4. RSS

힙 지표는 "힙에 객체가 얼마나 들어앉았나"에 답했다. RSS 가 답하는 질문은 다르다 — "이 프로세스가 물리 메모리를 얼마나 차지하고 있나"다. 세는 쪽도 런타임이 아니라 커널이다.

이 값을 읽으려면 "물리 메모리를 차지한다"가 무슨 일인지부터 있어야 한다.

주소를 받는 것과 메모리가 붙는 것

프로세스가 커널에게서 받는 것은 메모리 자체가 아니라 쓸 수 있는 주소의 범위였다. 그 "메모리 자체"가 물리 메모리 — RAM 칩의 실제 자리다.

커널은 RAM 을 통으로 다루지 않고 4 KiB 조각으로 잘라 나눠 주며, 그 조각 하나를 물리 페이지라 한다. 어느 번지가 어느 페이지를 가리키는지는 커널이 프로세스마다 표를 하나씩 들고 관리한다.

그 표가 언제 채워지느냐가 이 절의 전부다.

프로세스가 커널에게 주소 범위를 달라고 하면 커널이 정해 주는 것은 범위뿐이다. "이 범위는 네 것"이라는 약속이고 표는 비어 있다. 물리 메모리는 한 장도 안 붙는다.

붙는 순간은 따로 있다. 그 주소에 처음 값을 써 넣을 때 커널이 그제서야 페이지 한 장을 떼어 표에 적는다. 쓰지 않은 자리는 표가 끝까지 비어 있다.

힙만 그런 것이 아니다. 힙이 모자라 런타임이 더 받아 오는 것도, 스레드를 만들 때 스택 몫을 잡는 것도, 실행 파일 코드가 올라오는 것도 전부 이 규칙을 따른다. 스택을 리눅스 기본 8 MiB 로 예약한다고 했던 것이 이 얘기다 — 주소만 잡아 둔 것이고, 함수가 깊이 안 들어가면 붙는 페이지는 몇 장뿐이다.

그래서 한 프로세스를 두고 숫자가 둘 나온다.

값	세는 것	지표 이름
가상 크기 (VSZ)	약속받은 주소의 합. 1 GiB 를 잡으면 바로 1 GiB 가 는다	`process_virtual_memory_bytes`
RSS	물리 페이지가 붙은 합. 값을 써 넣은 만큼만 는다	`process_resident_memory_bytes`

RSS 는 Resident Set Size — 물리 메모리에 상주(resident)하는 집합의 크기라는 이름이다.

1 GiB를 잡아 놓고 한 번도 안 건드리면, VSZ 는 1 GiB 늘고 RSS 는 그대로다.

RSS 안에 무엇이 들어 있나

이 프로세스에서 값이 써진 것 전부다. 리눅스가 메모리를 가르는 기준 그대로 두 몫이다.

RSS 안	무엇이 들어 있나
익명 메모리	값을 써 넣은 힙 페이지 · 스택 · 전역. 디스크에 원본이 없어 버리면 잃는다
페이지 캐시 중 이 프로세스에 매핑된 것	실행 파일 코드 · 공유 라이브러리. 디스크 사본이라 버려도 다시 읽으면 된다

그래서 RSS 는 "이 프로세스가 노드 메모리를 실제로 얼마나 점유하나"에 답한다. 컨테이너에 프로세스가 하나면 사실상 그 컨테이너의 점유량이다.

같은 프로세스를 세는 놈이 둘이다

힙 지표와 RSS, 같은 프로세스에 숫자가 둘이 됐다. 숫자만이 아니라 세는 놈까지 봐야 뜻이 정해진다.

지표	누가 세나	무엇을 보나	답하는 질문
힙 지표 `go_memstats_heap_alloc`	Go 런타임	힙에 객체가 들어앉았나	힙의 내역
RSS `process_resident_memory`	OS	물리 페이지가 붙었나	프로세스의 점유량

서로가 서로를 대신하지 못한다. RSS 는 물리 페이지가 붙었다는 사실만 알지 그것이 힙인지 스택인지, 산 객체의 자리인지 죽은 객체가 쓰던 자리인지 모른다. 힙 지표는 객체를 알지만, 배정은 적어 두는 일일 뿐이라 물리 페이지가 붙었는지 모른다.

VSZ 까지 셋을 층으로 놓으면 이렇다.

커널이 힙으로 준 주소 범위                     VSZ (다른 구역들과 함께)
 └ 그중 런타임이 객체에 배정한 만큼             힙 지표 (heap_alloc)
    └ 그중 값이 써져 물리 페이지가 붙은 만큼     RSS 의 힙 몫 (스택·코드와 함께)

힙 지표와 RSS 의 폭 — 죽은 객체의 자리

AI 가 낸 표의 Argo controller 행이다.

힙 지표    127 Mi
RSS        359-487 Mi

RSS 가 힙 밖까지 세니 더 큰 방향은 맞다.

그런데 힙 밖 몫(스택·실행 파일 코드)은 수십 Mi 수준이라 세 배라는 폭이 안 나온다. 폭의 정체는 힙 페이지 하나의 일생을 따라가면 보인다.

① 배정       객체가 자리에 앉는다              힙 지표 +
② 값 써짐    물리 페이지가 붙는다              RSS +
③ 객체 죽음  아무도 안 가리키게 된다           둘 다 그대로
④ 치움       런타임이 자리를 회수한다           힙 지표 −
⑤ 반납       물리 페이지를 커널에 돌려준다       RSS −

④ 치움의 이름이 GC(Garbage Collection) 다. 죽은 객체를 찾아 그 자리를 다음 객체를 앉혀도 되는 빈자리로 되돌리는 일이다. 물리 페이지를 건드리는 일이 아니라 런타임이 제 기록의 표시를 바꾸는 일이라, 이 순간 RSS 는 안 움직인다.

⑤ 반납을 런타임은 서두르지 않는다. 그 빈자리는 곧 다음 객체가 앉을 자리고, 커널에 돌려줬다가 다시 받으면 그 요청이 한 번 더 든다. 그래서 런타임은 페이지를 쥔 채 되쓴다. 새 객체가 앉으면 힙 지표만 다시 늘고 RSS 는 그대로다 — 자리는 비었다 찼다 돌지만, 페이지는 한 번 붙으면 오래 붙어 있는다.

그래서 어느 순간에 재든 힙 안에는 치워져서 다음 객체를 기다리는 페이지가 깔려 있다. 힙 지표에는 없고 RSS 에는 있는 몫 — Argo 폭의 대부분이 이것이다.

남는 질문은 시점이다. GC 가 언제 도는지가 이 폭을 정한다 — 늦게 돌수록 죽은 객체와 빈 페이지가 더 쌓인다. 그 시점의 규칙과, 사람이 그것을 만지는 값이 다음 절이다.

5. GC와 GOGC

앱이 도는 동안 힙에는 이런 일이 반복된다. 함수가 요청을 처리하며 힙에 객체를 만들고, 반환하면 프레임이 풀리면서 그 객체를 가리키던 참조도 같이 사라진다. 객체는 힙에 남았는데 가리키는 놈이 없다. 프로그램이 그 객체에 다시 닿을 길은 없고, 요청마다 이런 고아가 몇 개씩 생긴다.

GC 가 치우는 것이 정확히 이것이다 — 참조가 하나도 안 남은 객체. 닿을 수 없으면 다시 쓸 수도 없으니 쓰레기로 판정해도 안전하다. 기준은 참조 유무 하나고, 물리 페이지가 붙었는지는 판정에 안 들어간다.

찾아 치우는 데는 CPU 가 든다. 그래서 GC 는 맞바꾸기다 — 자주 돌리면 CPU 를 계속 쓰고, 미루면 죽은 객체가 물리 페이지를 깔고 앉은 채 쌓인다. 어느 쪽으로 기울일지 정하는 자리가 이 절의 손잡이다.

Go 는 살아있는 양의 두 배에서 돈다

Go 런타임에 "언제 돌라"를 정해 주는 값이 GOGC 다. 이 글에서 손잡이는 이렇게 배포 설정에 사람이 값을 넣어 런타임 동작을 바꾸는 자리를 가리킨다.

규칙은 한 줄인데, 읽으려면 힙 지표의 성질 하나가 먼저 필요하다. 죽은 객체는 치워지기 전까지 그대로 잡히므로 힙 지표 = 살아있는 객체 + 아직 안 치운 죽은 객체다. GC 가 돌면 죽은 몫이 빠져 살아있는 양까지 떨어졌다가, 일감이 들어오는 만큼 다시 쌓인다.

GOGC 기본값 100 — 힙 지표가, 직전 GC 가 끝났을 때 살아있던 양의 두 배에 닿으면 돈다.

살아있는 양이 100 Mi 로 일정하다고 치고 heap_alloc 을 시간축으로 그리면 이 모양이 나온다.

힙 지표   100 ↗↗ 200 ·GC↘ 100 ↗↗ 200 ·GC↘ 100 …      차오르다 GC 에 수직으로 떨어지기를 반복
RSS       ──────────── 200 언저리에서 거의 수평 ────────────

위 줄이 톱니(sawtooth) 라 부르는 그래프다. 바닥이 살아있는 양(100), 꼭대기가 두 배 선(200)이고, 그 사이를 채우며 올라가는 것은 대부분 죽은 채 쌓이는 객체다.

핵심은 아래 줄이다. 힙 지표는 GC 마다 바닥까지 떨어지는데 RSS 는 같이 안 떨어진다. 꼭대기까지 차오르는 동안 그 자리마다 값이 써져 물리 페이지가 붙었고, 커널로 돌려주는 반납은 별개 단계라 늦게 오기 때문이다.

그래서 살아있는 것은 100 인데 RSS 는 200 언저리다. 이 100 의 차이에 이름을 붙이면 둘이다.

헤드룸 — 두 배 선까지 차게 두는 규칙의 몫. 살아있는 양만큼이 위에 얹힌다
반납 지연 — 그 꼭대기가 안 내려오는 이유

이제 Argo controller 를 대 본다.

힙 지표   127 Mi
RSS       359-487 Mi      두 배로 쳐도 254 — 그보다 크다

숫자가 그림 그대로 떨어지지는 않는데, 안 떨어지는 이유가 전부 안 잰 것들이다.

127 이 톱니의 바닥인지 중간인지 — 한 순간의 값으로는 모른다
RSS 가 기억하는 것은 지금 톱니가 아니라 역대 가장 높았던 꼭대기다
힙 밖 몫(고루틴 스택·런타임 메타데이터·실행 파일 코드)은 안 쟀다 — go_memstats_heap_sys·heap_idle·stack_sys 를 떠야 갈린다

그래서 이 그림에서 가져갈 것은 숫자가 아니라 방향이다. 살아있는 양보다 몇 배 큰 RSS 는 바빠서 생기는 것이 아니라 이 구조가 만든다.

GOGC 를 낮추는 것은 두 배 선을 끌어내리는 것이다. GOGC=50 이면 살아있는 양의 1.5배 — 위 예에서 150 — 에서 돌아 톱니 꼭대기가 낮아지고, RSS 가 따라 내려온다. 대신 같은 쓰레기를 더 자주 치우니 CPU 를 더 쓴다. 메모리를 줄이는 대신 CPU 를 내는 손잡이고, Argo 의 폭이 정말 이 구조였는지는 이 값을 걸고 RSS 가 내려오는지로 확인된다.

JVM 은 Eden 이 차면 돈다

JVM 도 고르는 기준은 같다 — 참조가 없어진 객체. 갈리는 것은 도는 시점을 재는 방식이다. Go 가 힙 지표가 선에 닿는 것을 신호로 쓴다면, JVM 은 힙을 방 셋으로 나눠 두고 그중 한 방이 차는 것을 신호로 쓴다.

방	무엇이 들어가나
Eden	새로 만든 객체는 전부 여기부터
Survivor	GC 에서 한 번 살아남은 객체가 잠깐 머문다
Tenured	오래 살아남은 객체가 옮겨 가서 산다

새 객체는 Eden 에 쌓이고, Eden 이 차면 GC 가 돈다. 살아남은 것은 다음 방으로 옮기고 Eden 을 비운다.

그럼 Eden 의 크기는 누가 정하나. 힙 전체 크기에서 비율로 나뉜다. JVM 은 힙 전체의 상한을 -Xmx 라는 값으로 받는데(이 값이 어떻게 정해지는지는 다음 절), booking 의 -Xmx 768 Mi 는 실측으로 이렇게 갈라져 있다.

Tenured    512.0 MiB        768 의 3분의 2
Eden       204.8 MiB        남은 3분의 1 을 8 : 1 : 1 로
Survivor    25.6 MiB × 2

그래서 -Xmx 를 절반으로 내리면 Eden 도 절반이 되어, 같은 일감에서 GC 가 두 배 자주 돈다. 상한이 시점을 직접 정하지는 않지만 방 크기를 거쳐 빈도에 걸린다. Tenured 쪽 회수는 시점 규칙이 또 다르고, 이 편에서는 안 다룬다.

"언제 도나"는 알았고 "어디까지 자라나"가 남았다

여기까지 온 길을 한 줄씩 놓으면 이렇다.

2절  힙 · 스택     힙의 객체만 수명이 함수에 안 묶인다.  참조가 사라져 죽은 뒤에도
                  누가 치우기 전까지 힙에 남고, 얼마나 커질지는 코드만 봐서는 모른다

3절  런타임        그 죽은 객체를 치우는 것이 런타임이고,
                  힙에 얼마가 들었는지도 런타임이 힙 지표로 내준다

4절  RSS           그런데 파드가 실제로 차지한 메모리는 OS 가 RSS 로 따로 세고,
                  힙 지표보다 몇 배 크다 — 죽은 객체가 쓰던 페이지를 치운 뒤에도
                  커널에 바로 안 돌려주기 때문이다

5절  GC · GOGC     그 치움이 GC 고, 그래서 폭은 GC 가 언제 도는지가 정한다.
                  Go 는 힙 지표가 두 배 선에 닿을 때 돌고, JVM 은 Eden 이 찰 때 돈다

이 절이 정한 것은 거기까지 — GC 가 도는 시점이다. 힙이 어디까지 자라도 되는지는 안 정해졌고, 두 언어가 여기서 갈린다.

Go 에는 자람을 막는 선이 없다. GOGC 가 정하는 것은 다음 GC 지점이 직전 살아남은 양의 몇 배냐일 뿐이라, 살아있는 양이 늘면 그 지점도 같이 올라간다. 일감이 늘어 살아있는 양이 두 배가 되면 GC 가 도는 힙 크기도 두 배가 된다. 위에서 100·200 으로 그린 톱니가 통째로 올라가는 것이고, 그것을 잡아 두는 값은 GOGC 에 없다.

JVM 에는 선이 있다. Eden 이 차면 돈다는 규칙 자체가 방 크기에 매여 있고, 그 방들이 -Xmx 를 나눈 값이기 때문이다. 다만 -Xmx 가 어디서 오는지는 아직 안 봤다 — booking 은 그 값을 직접 적지 않았는데도 768 Mi 로 서 있다.

그래서 1절에 적어 둔 모르는 낱말 중 셋이 남는데, 셋 다 방금 세운 그림의 빈자리에 하나씩 꽂힌다.

GOMEMLIMIT — Go 의 없는 선 자리에 사람이 넣는 값. Tempo 에 800 MiB 로 걸려 있던 그것이다
-Xms · -Xmx · MaxRAMPercentage — JVM 선의 출처. booking 이 -Xmx 없이도 768 Mi 로 서 있는 이유가 이 안에 있다
비힙 — 선 바깥에 남는 몫. booking 은 힙 사용이 74 Mi 인데 컨테이너는 420 MiB 를 쓴다 — 힙만으로는 설명이 안 되는 나머지다

이 셋은 전부 컨테이너 안쪽의 값이다. 그런데 이 편을 시작하게 만든 문제 — 예약이 과대·과소로 어긋나고 peak 가 limit 의 76-90% 에 붙은 컨테이너가 아홉이던 그 상태 — 에서 파드를 실제로 죽이고 살리는 선은 컨테이너 바깥에서 커널이 긋는 limit 이다.

안쪽과 바깥은 서로를 아는가. limit 을 바꾸면 안쪽 선이 따라 움직이는가, 안쪽 선을 다 정하면 limit 이 지켜지는가. 다음 절이 그 둘을 마주 세운다.

6. 두 상한

앞 절 끝의 질문을 그대로 들고 간다 — limit 을 바꾸면 안쪽 선이 따라 움직이는가. 안쪽 선을 다 정하면 limit 이 지켜지는가. 답하려면 두 선을 한자리에 놓아야 한다.

	실체	누가 지키나	넘으면
바깥 선 `limit`	cgroup 의 `memory.max`	커널	OOMKill — 예고 없이 밖에서 죽는다
안쪽 선	런타임 설정 — JVM 의 힙 상한 · Go 의 `GOMEMLIMIT`	런타임이 스스로	언어마다 다르다. 아래에서 가른다

기본값 상태에서 둘은 서로를 참조하지 않는다. 커널은 런타임의 힙 지표를 읽지 않고, 런타임이 limit 을 아는지는 언어가 갈린다 — JVM 은 읽어 오고, Go 는 모른다.

바깥 선부터 확정하고, 안쪽 선을 언어별로 세운 다음, 끝에서 질문에 답을 모은다.

바깥 선 — 커널은 working_set 으로 판정한다

limit 은 values 에 적는 쿠버네티스 값이지만, kubelet 이 cgroup 파일 memory.max 에 써 넣는 순간부터 지키는 쪽은 커널이다. 그리고 커널이 판정에 쓰는 숫자는 힙 지표도 RSS 도 아니다 — cgroup 이 직접 세는 세 번째 숫자다.

지표	누가 세나	세는 범위	빼는 것
RSS	OS	프로세스 하나	없다. 매핑된 파일 페이지도 넣는다
`container_memory_working_set_bytes`	커널 (cgroup)	cgroup 이 묶은 것 전부	안 쓰는(inactive) 파일 캐시를 뺀다. 계속 읽고 쓰는 활성 캐시는 남는다

범위는 working_set 쪽을 키우고 뺄셈은 깎으니, 어느 쪽이 클지는 그때그때 다르다. Strimzi operator 는 뺄셈이 이겼다.

VmRSS                          312 MiB      프로세스 하나인데 더 크다
container working_set          296 MiB      cgroup 전체인데 더 작다

층이 다른 값끼리 빼면 안 된다는 뜻이다. 노드 실사용에서 파드 몫을 빼 시스템 몫을 구하는 식의 계산이 여기서 걸린다.

working_set 이 limit 을 넘으면 커널은 그 cgroup 의 프로세스에 SIGKILL 을 보낸다. 힙인지 비힙인지, 산 객체의 자리인지 죽은 객체가 쓰던 자리인지 — 안쪽 사정은 하나도 안 보고 총량 하나로 자른다. 바깥 선은 여기까지다. 이제 안쪽을 언어별로 본다.

JVM — limit 을 읽어 와서 선을 긋는다

5절이 남긴 수수께끼부터 푼다. booking 은 -Xmx 를 안 적었는데 힙 상한이 768 Mi 로 서 있었다. 768 = limit 1 Gi 의 75% 고, values 에 적어 둔 것은 MaxRAMPercentage=75 하나였다.

경로는 이렇다. JVM 의 힙 상한 기본 규칙은 컨테이너 이전 시대의 "물리 RAM 의 4분의 1"이다. 컨테이너 안에서 그대로 두면 노드 8 GiB 의 4분의 1 인 2 GiB 를 잡으려 들고, limit 512 MiB 컨테이너라면 커널이 먼저 죽인다.

그래서 JDK 10 부터 JVM 이 cgroup 파일을 직접 읽어 "물리 RAM" 자리에 컨테이너 limit 을 놓는다(UseContainerSupport, 기본 켜짐). 그 위에 손잡이 셋이 얹힌다.

손잡이	무엇을 정하나
`-Xmx`	힙 상한을 절대값으로 명시. 있으면 아래 비율은 무시된다
`MaxRAMPercentage`	`limit` 의 몇 % 를 힙 상한으로. 기본값 25
`-Xms`	시작할 때 잡아 두는 힙 크기. `-Xmx` 와 같게 두면 늘었다 줄었다 하는 요동이 없어진다

topicOperator 에 -Xms 64m·-Xmx 128m 을 함께 적어 둔 것이 이 짝이다. 시작은 64 에서 하고 상한은 128 이라 그 사이에서만 오르내리고, 그렇게 실제로 확보해 둔 양을 커밋이라 한다 — 커밋은 사용과 상한 사이에 있다.

나는 values 에서 비율 쪽을 두 군데 명시해 뒀다.

Kafka 브로커   limit 1,536 Mi × 60%  =  921.6 Mi   실측 MaxHeapSize 922.0 MiB
booking       limit 1 Gi × 75%      =  768 Mi

-Xmx 가 없으면 비율이 선을 긋고, 비율은 limit 에서 파생된다. 5절 끝 질문의 반쪽이 여기서 답이 된다 — JVM 쪽은 limit 을 바꾸면 안쪽 선이 따라 움직인다.

이 선에 닿으면 나는 일도 바깥 선과 다르다. 힙이 상한에 닿으면 JVM 은 GC 를 몰아 돌리고, 그래도 자리가 안 나면 OutOfMemoryError 를 던진다 — OOMKill 처럼 밖에서 죽임당하는 것이 아니라 앱 안에서 나는 실패다.

비힙 — 선을 그어도 limit 은 안 나온다

5절 끝 질문의 남은 반쪽 — 안쪽 선을 다 정하면 limit 이 지켜지나. 아니다. 커널이 재는 working_set 은 컨테이너 전부를 세는데 힙 상한은 힙 한 칸에만 그은 선이라, 선 바깥 몫이 limit 안에서 같이 산다. 이 몫을 비힙이라 한다.

비힙	무엇	무엇이 늘리나	상한 손잡이
메타스페이스	클래스 정보	로드한 클래스 수	`MaxMetaspaceSize` (기본 무제한)
코드캐시	바이트코드를 기계어로 번역해 둔 것 (JIT)	자주 도는 메서드 수	`ReservedCodeCacheSize`
스레드 스택	스레드마다 하나씩	스레드 수	`-Xss` × 스레드 수
다이렉트 버퍼	네트워크·디스크 I/O 용 버퍼	I/O 량	`MaxDirectMemorySize`
GC 관리 구조	회수에 쓰는 자료구조	힙 크기에 비례	—

스레드 스택 행은 OS 스레드에만 해당한다. booking 처럼 가상 스레드를 쓰면 그 스택은 힙 안에 놓여 -Xmx 안에서 세므로 이 행에 안 들어간다.

메타스페이스·코드캐시·스레드 스택·다이렉트 버퍼·GC 관리 구조는 모두 익명 메모리다. 힙과 같은 성질인데 -Xmx 밖에 있다. JVM 셋을 떠 보면 이 몫이 작지 않다.

	`limit`	힙 상한 (limit 대비)	힙 사용	비힙 (잰 것만)	`working_set`
Strimzi operator	384 Mi	58 Mi (15%)	52 Mi	메타스페이스 86 Mi	296 Mi
booking	1,024 Mi	768 Mi (75%)	74 Mi	합 181 Mi	420 Mi
Kafka 브로커	1,536 Mi	922 Mi (60%)	325 Mi (커밋 389)	메타스페이스 68 Mi	621-643 Mi

비힙 열이 고르지 않은 것은 잴 수 있는 것이 파드마다 달라서다. booking 은 앱이 JVM 지표를 내보내 다섯 조각의 합이 나오고, Strimzi·Kafka 는 jcmd 로 메타스페이스 한 조각만 떴다.

이 표에서 대 볼 것은 힙 사용과 working_set 사이의 거리다.

Strimzi — 힙은 52 를 쓰는데 컨테이너는 296 을 쓴다. 메타스페이스(86) 하나가 힙 상한(58)보다 크다
booking — 힙은 74, 컨테이너는 420. 힙 상한 768 은 이 420 의 대부분과 상관없는 선이다
Kafka — 힙 커밋 389 에 메타스페이스 68 을 더해도 164-186 이 빈다(621-643 의 양 끝). working_set 은 안 쓰는 파일 캐시만 빼므로 계속 읽고 쓰는 로그 세그먼트의 활성 캐시가 여기 남아 있고, JVM 네이티브 몫과 가르려면 -XX:NativeMemoryTracking 을 켜야 한다

limit 을 향해 차오르는 것은 working_set 전체인데, 안쪽 선이 다스리는 것은 그중 힙 한 칸뿐이다. 안쪽 선을 다 정해도 limit 이 지켜지지 않는 이유가 이 거리다.

그래서 내가 익명 메모리의 예로 든 Kafka 브로커의 607 Mi도 힙 단독이 아니다. 나는 그 값에 "JVM 힙"이라는 이름을 붙였는데, 익명 메모리를 잰 값이라 힙과 비힙이 함께 들어 있다.

Go — limit 을 아예 모른다

Go 런타임에는 cgroup 을 읽는 단계 자체가 없다. 힙 상한 기본값은 int64 최대 — 사실상 무한이다. 두 배 선은 살아있는 양을 따라 올라가는 선이라, limit 1 GiB 컨테이너 안에서 다음 GC 지점이 2 GiB 로 잡혀도 런타임은 이상한 줄 모른다. Go 파드가 죽는 선은 언제나 바깥의 OOMKill 이다.

그 빈자리에 사람이 넣는 값이 GOMEMLIMIT(Go 1.19부터)이다. JVM 처럼 런타임이 읽어 오는 것이 아니라 limit 을 보고 사람이 옮겨 적는 값이고, -Xmx 와 두 가지가 더 다르다.

덮는 범위 — 힙만이 아니라 힙 + 고루틴 스택 + 런타임 메타데이터를 한 값으로 묶는다
성격 — 상한이 아니라 목표다. 넘어도 실패하지 않는다. 살아있는 양이 목표를 넘으면, 런타임이 목표를 맞추려고 GC 를 계속 세게 돌릴 뿐이다

범위에 고루틴 스택이 들어 있는데, 고루틴이 무엇인지는 아직 이름뿐이다. 두 선이 다 선 지금이 그것을 놓을 자리다.

사용자 수준 스레드 — 그 스택은 어느 선이 세나

출발은 OS 스레드에 붙는 값이다. 스레드는 커널이 만들고 커널이 굴리며, 하나마다 스택이 예약되고(JVM 은 -Xss 1 MiB) 번갈아 돌릴 때마다 문맥 교환이 든다. 동시 요청 수백 개를 스레드 수백 개로 받으면 그 값이 그대로 쌓인다.

Go 와 Java 의 런타임은 같은 우회로를 냈다. 커널이 아니라 런타임 자신이 만들고 굴리는 실행 단위를 두고, OS 스레드 위에 얹어 돌린다. 이런 실행 단위를 사용자 수준 스레드라 하고, 이 클러스터에는 둘 다 있다.

	누가 만들고 굴리나	스택
고루틴 (Go)	Go 런타임	힙 밖. 2 KiB 로 시작해 필요하면 늘린다
가상 스레드 (Java 21)	JVM	힙 안. 객체로 놓여 필요한 만큼 자란다

동작의 핵심은 기다릴 때 비켜 주는 것이다. 고루틴이나 가상 스레드가 DB 응답 같은 것을 기다리게 되면, 런타임이 그것을 OS 스레드에서 떼어 내고 다른 것을 그 자리에 얹는다. 커널은 이 교체를 모른다. 그래서 OS 스레드는 CPU 코어 수 언저리면 되고, 실행 단위는 수만 개를 띄워도 스레드만큼 값이 안 든다.

이 클러스터의 두 앱이 그 위에 서 있다.

queue — 대기열 순번을 들고 폴링을 받는 Go 서비스. 연결마다 고루틴 하나를 붙인다
booking — spring.threads.virtual.enabled=true. 요청마다 가상 스레드 하나를 쓴다

사용자 수준 스레드가 이 절의 두 선과 만나는 자리는 스택이다. 커널이 안 만드는 실행 단위라 스택도 커널이 안 잡아 주고, 런타임이 마련한 그 스택이 어느 값 안에서 세어지는지가 갈린다.

OS 스레드 스택      -Xss × 스레드 수     힙 밖 — 비힙으로 limit 안에 든다
가상 스레드 스택     -Xmx 안             JVM 이 스택을 힙 안에 객체로 두므로
고루틴 스택         GOMEMLIMIT 안        힙 밖이지만 목표가 같이 묶어 센다

1절에서 서로 어떻게 다른지 몰랐던 -Xmx 와 GOMEMLIMIT 이 힙만 정하는 값이 아니라는 뜻이다. booking 이 동시 요청을 늘리면 그 스택 몫은 비힙이 아니라 -Xmx 안에서 늘고, queue 가 연결을 늘리면 GOMEMLIMIT 이 그 몫을 같이 센다.

런타임이 없는 언어는 앱이 직접 건다

C·C++에는 "언제 회수하나"를 정하는 런타임이 없다. 그래서 상한도 앱이 자기 자료구조에 직접 건다.

Redis — maxmemory가 그 자리다. 안 걸면 무한이라 데이터가 쌓이는 만큼 자라다 컨테이너 limit에서 끝난다. 걸어 두면 그 선에서 오래된 키를 버리거나 쓰기를 거절하고, 기본은 거절이다
MySQL — InnoDB 버퍼 풀이 JVM의 힙에 해당하는 자리인데 기본값이 128 MiB로 고정돼 있다. 미설정의 문제가 무한이 아니라 부족이다

앱이 직접 거는 상한은 런타임이 있는 쪽에도 있다. Loki는 Go 프로그램이지만 조회를 빠르게 하려고 프로세스 안에 캐시를 여러 개 두고, 그 캐시마다 크기 상한이 따로 있다. 그 상한들의 합은 컨테이너 limit과 무관하게 정해진다. 런타임 손잡이와 앱 설정은 다른 축이다.

총정리 — 질문의 답과, 다 선 낱말들

이 절 첫머리의 질문 둘에 답이 모였다.

limit 을 바꾸면 안쪽 선이 따라 움직이는가 — JVM 만 그렇다. JVM 은 cgroup 을 읽어 limit × 비율로 선을 긋기 때문이다(booking 75% → 768 Mi). -Xmx 로 절대값을 적으면 그 연결도 끊긴다. Go 는 처음부터 limit 을 모르니, limit 을 바꾸면 GOMEMLIMIT 도 사람이 다시 옮겨 적어야 한다.

안쪽 선을 다 정하면 limit 이 지켜지는가 — 아니다. JVM 은 비힙이 선 밖에서 limit 안을 채우고, Go 의 선은 목표라 강제가 아니고, 앱이 거는 상한은 아예 다른 축이다. limit 을 지킬 책임은 어느 런타임에도 없고, 그래서 마지막 선은 언제나 커널의 OOMKill 이다.

두 언어가 갈린 자리를 세로로 세우면 이렇다.

	Go	JVM
힙에 무엇이 올라가나	컴파일러가 정한다 (새어 나가면 힙)	객체 본체는 힙, 참조는 스택
실행 단위	고루틴. 런타임이 굴리고 스택 2 KiB 시작	OS 스레드(커널, `-Xss` 1 MiB) 또는 가상 스레드(JVM, 스택은 힙 안)
힙을 통으로 쓰나	통으로 쓴다	Eden · Survivor · Tenured 로 나눈다
GC 가 도는 시점	힙 지표가 살아있는 양의 두 배에 닿을 때 (`GOGC`)	Eden 이 찰 때. Eden 크기는 `-Xmx` 에서 파생된다
힙 상한 기본값	없다 (int64 최대)	`limit` 의 25%
cgroup 을 읽나	안 읽는다	읽는다 (`UseContainerSupport`)
잇는 손잡이	`GOMEMLIMIT` — 사람이 옮겨 적는 목표	`-Xmx`·`MaxRAMPercentage` — 상한
손잡이가 덮는 범위	힙 + 고루틴 스택 + 런타임 메타	힙만 (가상 스레드 스택 포함). 비힙은 밖
안쪽 선을 넘으면	실패 없음 — GC 만 세게 돈다	`OutOfMemoryError` — 앱 안에서 실패
바깥 선을 넘으면	OOMKill	OOMKill

그리고 1절 표 앞에서 판단이 안 서던 낱말들이 전부 섰다.

1절의 낱말	지금
힙 · 스택	주소 공간의 조각. 스택은 스레드마다 하나에 프레임이 쌓였다 풀리고, 힙만 수명이 함수에 안 묶여 치우는 문제가 남는다
런타임	내가 안 짰는데 같은 프로세스에서 함께 도는 코드. 힙을 잡아 주고, 치우고, 실행 단위를 굴린다
RSS	프로세스에 물리 페이지가 붙은 양. 힙 지표와의 폭은 죽은 객체가 쓰던 페이지와 반납 지연이 만든다
GC · GOGC	참조가 안 남은 객체를 치우는 일 · 그 시점(두 배 선)의 배율. 낮추면 메모리가 줄고 CPU 를 더 쓴다
-Xms · -Xmx · MaxRAMPercentage	JVM 안쪽 선의 세 손잡이 — 시작 크기 · 절대값 상한 · `limit` 파생 비율
GOMEMLIMIT	Go 안쪽 선. 사람이 옮겨 적는 목표 — 힙과 고루틴 스택과 런타임 메타를 묶는다
비힙	`-Xmx` 밖에서 `limit` 안을 채우는 몫 — 메타스페이스 · 코드캐시 · OS 스레드 스택 · 버퍼 · GC 구조

남은 일은 이 낱말로 AI 가 낸 표를 내 눈으로 다시 읽고 컨테이너마다 값을 정하는 것이다. 멈춰 뒀던 스펙 재산정으로 돌아간 후 클러스터 안정화 작업을 마친 뒤 부하테스인 12부를 진행한다.

번외 — 노드 메모리와 쿠버네티스 메모리

hsb_02 — Sat, 15 Aug 2026 14:42:09 +0900

1. 막힌 자리

11부에서 앱이 제대로 도는지 검증했고, 12부에서는 대시보드를 보면서 파드 스펙을 실측한다. queue와 booking에 메모리와 CPU를 얼마나 줘야 하는지를 부하로 재서 정하는 것이 목표다.

그런데 앱 쪽을 재기 전에 앞이 막혔다. 노트북 한 대에 노드 3대를 올린 클러스터라 자원이 정해져 있다. 지금 파드들에 걸린 requests와 limits가 그 안에서 어떻게 나뉘어 있는지를 모르는 상태였다.

그것을 모른 채 부하를 걸면 앱이 느린 것인지 자리가 없는 것인지 갈리지 않는다.

그래서 12부의 순서가 인프라 대시보드 → 앱 대시보드가 됐다. 이 글은 그중 앞쪽, 인프라 대시보드에서 노드 메모리를 분석하다 막힌 것을 정리한 기록이다.

노드 한 대가 이렇게 나뉘어 있다

k3s 노드는 3대이고 셋 다 물리 메모리가 같다. 한 대를 그리면 이렇다. (단위 MiB는 1,048,576 바이트다. 1000 단위인 MB와 다르고, 파드 스펙에 적는 Mi와 같다.)

k3s-1   물리 7,941 MiB
┌───────────────────────────────────────────────────────────────┐
│  파드가 도는 자리                              상한 5,381 MiB   │
│    지금 차 있는 양                                  3,671 MiB   │
│    스케줄러가 보고 판단하는 선                       5,081 MiB   │
├───────────────────────────────────────────────────────────────┤
│  시스템 몫 (파드에게 안 주고 남긴 것)            예약 2,560 MiB   │
│    지금 쓰는 양                                     2,235 MiB   │
└───────────────────────────────────────────────────────────────┘

여기 나오는 다음의 셋은 이 글에서 차례로 다룬다. 지금은 이렇게만 잡아 둔다.

파드가 도는 자리   커널이 파드를 한 칸에 가둔다.  그 칸이 cgroup 이다   → 3절
                 파드는 이 칸 밖으로 못 나간다

시스템 예약       kubelet · containerd · sshd 몫을 미리 뗀 것         → 4절
                 상한 5,381 과 선 5,081 이 다른 이유도 거기서

지금 차 있는 양    이 숫자를 재는 것이 cAdvisor 다                     → 3절

대시보드로 보면서 던지게 되는 질문

이 노드에 파드를 더 앉힐 수 있나
지금 쓰고 있는 것 중 어디까지가 파드 몫이고 어디부터가 시스템 몫인가
노드마다 떼어 둔 예약 2,560 MiB 를 줄일 수 있나

셋 다 숫자로 답해야 한다. 그런데 어떤 숫자를 어디서 가져올지가 안 정해진다. 클러스터에서 메모리 숫자를 내는 곳이 넷인데, 넷이 서로 다른 값을 낸다.

node_*        prometheus-node-exporter
container_*   cAdvisor            kubelet 안에 있다
kubelet_*     kubelet 자신
kube_*        kube-state-metrics

같은 노드의 같은 시각을 재는데 값이 다르다. 어느 것이 맞는지가 아니라 각자 무엇을 재려고 만들어졌는지를 모르면 어느 것을 쓸지 고를 수 없다.

순서는 층을 따라간다. 리눅스가 메모리를 다루는 방식, 그 위에 cgroup이 얹은 것, 다시 그 위에 쿠버네티스가 얹은 것. 층마다 그 층을 재는 곳이 하나씩 나온다.

2. 리눅스 층 — 커널이 도로 가져갈 수 있는 것과 없는 것

메모리를 나눠 주는 주체는 커널이다. 프로그램이 직접 가져가는 것이 아니라 커널에게 요청하고 커널이 배정한다.

그래서 메모리가 다 찼을 때 판단하는 것도 커널이다. 커널은 새 요청을 거절하거나, 이미 배정한 것을 도로 가져와 그 자리를 내준다. 뒤쪽을 회수(reclaim) 라 부르고, 이 글에서 계속 나오는 말이다.

회수할 수 있는지는 그 메모리가 어디서 왔느냐로 갈린다

프로그램이 커널에게 하는 요청이 두 가지이고, 결과가 각각 다른 종류로 남는다.

① 메모리를 달라고 한다
   → 커널이 빈 자리를 준다
   → 프로그램이 거기에 계산 결과를 넣는다              = 익명 메모리
      그 값은 이 프로그램이 만든 것이라 디스크 어디에도 없다
      커널이 가져오면 없어진다                       
      
      → 회수 못 한다

② 파일을 읽어 달라고 한다
   → 커널이 디스크에서 읽어 메모리에 복사한다
   → 프로그램이 그 사본을 읽는다
   → 다 읽은 뒤에도 커널이 사본을 안 지운다            = 페이지 캐시
      원본이 디스크에 그대로 있다
      커널이 가져와도 다시 읽으면 된다                 
      
      → 회수할 수 있다

②에서 복사 단계가 빠질 수 없는 이유는 CPU가 디스크를 직접 못 읽기 때문이다. 커널이 먼저 메모리로 올려야 프로그램이 그 내용을 쓴다.

이 클러스터에서 각각이 무엇인지 보면 갈린다.

익명 메모리   Kafka 브로커 JVM 힙 607 · MySQL InnoDB 버퍼 풀 433
             Mimir 가 들고 있는 최근 시리즈 401 · k3s.service 1,708

페이지 캐시   Mimir 가 디스크에 쓴 블록 파일 358 · Alloy 195
             카프카 로그 세그먼트 159 · 컨테이너 이미지 레이어 · journald 로그

같은 파드가 양쪽에 다 나온다. mimir-ingester-0은 최근 데이터를 메모리에 들고 있고(익명 401), 자기가 디스크에 쓴 블록 파일을 읽으면 그 사본이 남는다(캐시 358).

한 파드의 메모리가 두 종류로 갈려 있고, 커널이 가져갈 수 있는 것은 뒤쪽뿐이다.

커널은 캐시를 안 지우고 쌓아 둔다

② 페이지 캐시는 다 읽은 뒤에도 사본을 안 지우는 것이 목적이다. 같은 파일을 또 읽을 때 복사 단계를 건너뛴다.

그래서 캐시가 크다는 것은 메모리가 모자라다는 신호가 아니다. 커널은 빈 자리를 비워 두느니 사본으로 채운다. 모자라지면 이것부터 줄인다.

커널이 이 상태를 파일 하나에 적어 둔다 — /proc/meminfo

지금까지 나온 값들을 커널이 /proc/meminfo에 적어 둔다. 디스크에 있는 파일이 아니라 읽을 때마다 커널이 만들어 주는 것이고, 리눅스에서 메모리를 보는 명령은 전부 이 파일을 읽는다.

여기 적힌 항목 이름이 그대로 메트릭 이름이 된다. k3s-1에서 읽으면 50줄쯤 나오는데, 이 글에 걸리는 것만 뽑으면 이렇다.

$ cat /proc/meminfo

MemTotal:        8131780 kB      7,941 MiB   물리 전체
MemFree:          241060 kB        235       아무것도 안 담기지 않은 자리
MemAvailable:    3265556 kB      3,189       커널이 계산한 여유
AnonPages:       4365980 kB      4,264       익명 메모리      회수 못 한다
Cached:          3019452 kB      2,949       페이지 캐시      회수할 수 있다
Buffers:          201788 kB        197       블록 장치 메타데이터
SReclaimable:      78256 kB         76       커널 자료구조 중 회수 가능분

단위가 kB라 1024로 나눠야 MiB가 된다. 나눈 값을 오른쪽에 적어 뒀고, 이 글의 숫자는 전부 MiB다.

물리 전체를 항목으로 채우면 이렇게 맞는다.

AnonPages 4,264 + Cached 2,949 + Buffers 197 + MemFree 235 = 7,645
MemTotal 7,941 − 7,645 = 296   커널 자신이 쓰는 자료구조
                               Slab 178 · PageTables 26 · KernelStack 15 …

커널은 회수할 차례를 미리 정해 둔다 — Active 와 Inactive

같은 출력에 Active와 Inactive가 있고 그 아래 (anon)·(file)로 또 갈린다. 메모리가 모자란 순간에 무엇을 가져갈지 뒤지면 늦으니, 평소에 목록을 만들어 두고 회수할 때 앞에서부터 집는다.

Active     최근에 쓰였다.     나중에 가져간다
Inactive   한동안 안 쓰였다.  먼저 가져간다

처음 읽으면 Inactive → 다시 읽히면 Active → 안 읽히면 되돌아온다

회수 후보가 될 수 있는 것은 종류와 상관없이 전부 이 목록에 들어간다. 그래서 2×2가 된다.

                       Active      Inactive
익명 메모리 (anon)        3,928         323
페이지 캐시 (file)        1,649       1,482
                        ─────       ─────
                        5,577       1,805   출력의 Active · Inactive 와 맞는다

다만 목록에 올랐다고 다 회수되는 것은 아니다. 캐시는 원본이 디스크에 있어 버리면 되지만, 익명은 버리면 값이 사라져 내보낼 자리가 따로 있어야 한다. 이 노드에는 그 자리가 없다.

그래서 커널이 실제로 가져갈 수 있는 것은 페이지 캐시, Active(file) 1,649와 Inactive(file) 1,482뿐이다.

익명 메모리는 Inactive(anon) 323은 목록에 올라 있어도 못 가져간다.

커널이 계산해 주는 여유 — MemAvailable

"지금 새 프로그램을 띄우면 얼마까지 받을 수 있나"에 답하려면 비어 있는 자리와 회수할 수 있는 것을 더해야 한다.

MemAvailable = MemFree + 페이지 캐시(Active+InActive) + ~~ = 회수 가능한 사용 가능한 값

이 계산을 사람이 하지 않도록 커널이 직접 해서 같은 파일에 적어 둔다. 그 항목이 MemAvailable이고 값이 3,189다.

커널이 무엇을 더하는지 항목으로 맞춰 보면 이렇다.

MemFree            235     지금 비어 있는 자리
파일 캐시         3,131     Active(file) 1,649 + Inactive(file) 1,482
SReclaimable        76     커널 자료구조 중 버릴 수 있는 것
                 ─────
                 3,442     다 긁어모으면
MemAvailable     3,189     커널이 내놓은 답
                 ─────
                   253     안전분으로 남겨 둔 몫

Active(file)와 Inactive(file)가 똑같이 더해진다. 버리는 순서만 다를 뿐 커널은 둘 다 "버려도 되는 것"으로 센다. 이 구분이 갈리는 자리는 3절이다.

안전분 253을 빼는 이유는 여기까지 내려가면 커널이 메모리 만드는 일에 매달려 시스템이 느려지기 때문이다.

이것이 node-exporter 가 내는 값이다

node-exporter는 리눅스 서버 한 대를 감시할 때 쓰는 표준 도구다. 쿠버네티스와 무관하게 서버가 있으면 붙여서 CPU·메모리·디스크·네트워크·파일시스템을 본다. 커널이 /proc과 /sys에 적어 두는 값을 읽어 내보내는 것이 전부다.

지금까지 나온 값도 전부 커널이 /proc/meminfo에 적어 둔 것이고, 그 파일을 읽어 Mimir로 보내는 것이 node-exporter다.

node-exporter는 컨테이너 안에서 도는데 호스트 파일을 읽는다. 또한 DaemonSet으로 노드마다 파드가 하나씩 뜨고, 그 파드에 호스트가 통째로 붙어 있다.

hostPID: true       호스트의 프로세스 이름공간을 그대로 쓴다
proc  -> /proc      호스트의 /proc 를 컨테이너 안에 붙였다
sys   -> /sys
root  -> /

컨테이너는 보통 자기 안쪽만 본다. node-exporter는 호스트 파일을 붙여서 노드 전체를 본다. 파드로 떠 있으면서도 노드 값을 내는 것이 그래서다. 이 클러스터에서 observability-host 네임스페이스에 따로 있는 것도 이 권한을 요구하기 때문이다.

하는 일은 읽어서 형식만 바꾸는 것이다. 세는 것도 계산도 커널이 한다. 항목 이름 앞에 node_memory_가 붙고 뒤에 _bytes가 붙어서, MemAvailable은 node_memory_MemAvailable_bytes가 된다.

이 값이 필요한 이유는 노드 전체 상태를 아는 곳이 커널뿐이기 때문이다. 한계는 컨테이너를 모른다는 것이다

/proc/meminfo에 컨테이너별 항목이 없으니 낼 수도 없다.

답할 수 있다   이 노드에 지금 얼마까지 더 줄 수 있나        MemAvailable 3,189
답 못 한다     이 파드가 얼마 쓰나
              queue 가 자기 상한 256Mi 를 넘었나

그런데 노드 한 대에 파드가 여럿 산다

k3s-1에는 queue·booking·MySQL·Kafka·Mimir가 같이 앉아 있다. 그중 하나가 메모리를 계속 먹으면 노드가 꽉 차고, 그 상태로 두면 커널이 프로세스를 골라 죽인다. 원인을 만든 파드가 아니라 멀쩡한 파드가 죽을 수 있다.

그래서 쿠버네티스는 파드마다 "여기까지"를 정해 두고 넘은 파드만 멈춘다. 그러려면 둘이 있어야 한다.

파드별로 얼마 쓰는지 센다      누가 넘었는지 알아야 고른다
그 파드만 멈춘다             나머지는 살려야 한다

node-exporter로는 둘 다 안 된다. 노드 전체 합만 내므로 MemAvailable이 줄어드는 것은 보이지만 누가 먹는지 모르고, 안다 해도 그 파드만 멈추게 할 수단이 없다.

그런데 리눅스에는 이 둘을 다 하는 기능이 이미 있다. 쿠버네티스가 그것을 가져다 쓴다.

3. cgroup 층 — 프로세스 묶음별로 세고 상한을 건다

위에서 말한 파드를 다루는 리눅스에서의 기능이 cgroup(control group) 이다.

다만 cgroup은 리눅스 기능이라 파드를 모른다. 아는 것은 프로세스뿐이다.

프로세스를 묶는다
그 묶음이 쓴 양을 따로 센다
상한을 걸고, 넘으면 그 안의 프로세스를 죽인다

파드를 이 위에 얹을 수 있는 이유는 "파드도 결국 프로세스 묶음"이기 때문이다. 컨테이너가 프로세스이고 파드는 그 컨테이너들을 묶은 것이라, cgroup이 원래 하던 일에 그대로 들어맞는다.

컨테이너가 곧 cgroup 이다

컨테이너는 특별한 실행 방식이 아니라 그냥 리눅스 프로세스다. 그 프로세스에 상한을 걸고 시야를 가려 둔 것을 컨테이너라 부른다.

cgroup      얼마나 쓸 수 있나
              메모리 · CPU · 디스크 I/O

namespace   무엇이 보이나.  종류별로 따로 있다
              pid   다른 프로세스가 안 보인다.  ps 를 쳐도 자기 것만 나온다
              net   자기 IP · 포트 · 라우팅을 갖는다
              mnt   자기 파일시스템만 보인다.  호스트의 / 가 안 보인다
              uts   호스트명을 따로 갖는다

여기 쓰는 namespace는 리눅스 커널 기능이고, 쿠버네티스의 Namespace(app·data·observability)와는 이름만 같고 관계가 없다.

파드를 띄우는 순서로 보면 이렇다.

kubelet 이 파드 하나를 띄우기로 한다
  → containerd 에게 그 안의 컨테이너를 만들라고 한다
  → containerd 가 cgroup 을 만들고 상한을 적는다      queue 컨테이너는 256Mi
  → namespace 를 만들어 시야를 가린다                 pid · net · mnt …
  → 그 안에서 프로세스를 실행한다
  → 그 프로세스가 곧 컨테이너다

이 중 network namespace 는 컨테이너마다가 아니라 파드에 하나다. 왜 그런지가 바로 아래 pause에서 나온다.

쿠버네티스가 새로 만든 격리 장치가 있는 게 아니라 리눅스가 원래 갖고 있던 것을 쓴다. 파드 스펙에 적는 limits 가 cgroup 상한으로 그대로 옮겨진다.

cgroup 은 계층이고, 층마다 상한이 걸린다

cgroup은 프로세스마다 생기는 폴더가 아니라, 개별 프로세스들을 묶어서 관리하는 계층형 폴더 구조이다.

개별 프로세스에 256Mi씩 상한을 건다면 파드가 30개로 늘면 전체 합이 노드 용량을 넘길 수 있기에, 개별 상한만으로는 전체 합을 정할 수 없다.

그래서 cgroup은 '묶음 위에 다시 상위 묶음'을 두는 계층 구조로 되어 있다. 노드에는 '파드 전체 묶음 폴더(kubepods)'가 맨 위에 있고 그 아래에 개별 파드 폴더들이 들어간다.

정리하면 리눅스 cgroup의 계층형 폴더 구조를 활용하여, 노드 위 파드들의 자원 사용량을 그룹 단위로 제한한 것.

/                            루트.  노드의 모든 프로세스
├─ /kubepods.slice           파드 전부
│   ├─ memory.stat             내역.  anon · file · active · inactive
│   ├─ memory.current          지금 쓰는 총량
│   ├─ memory.max              넘을 수 없는 선.  파드에게 내주는 총량
│   └─ 파드 하나               상한 = 그 안 limits 합
│       ├─ pause 컨테이너
│       └─ 앱 컨테이너          상한 = limits.  queue 는 256Mi
└─ /system.slice             systemd 서비스.  상한 없음
    ├─ k3s.service             apiserver · etcd · kubelet · containerd
    │                            → kube-reserved 2,048 로 떼어 둔 몫
    └─ sshd.service 등          그 외 OS 서비스
                                 → system-reserved 512 로 떼어 둔 몫

쿠버네티스 클러스터 생성 시에 작성한 config.yaml에 적은 예약 두 줄이 겨냥하는 대상이 바로 이 system.slice 가지다. 다만 예약이 여기 상한으로 직접 걸리는 것은 아니다.

*쿠버네티스 config.yaml : "이 클러스터는 어떤 규칙과 자원 배정으로 운영하겠다"라고 작성하는 기반 설정 파일

이 자원 제어의 핵심은 모든 계층이 동일한 도구를 쓴다는 점이다. 세 파일(memory~)은 /kubepods.slice(파드를 다루는 층)에만 있는 것이 아니라 모든 층에 똑같이 들어 있다. 최상위 루트 폴더부터 파드 디렉터리, 컨테이너 디렉터리에 이르기까지 전부 존재하며 감시하는 범위만 다르다.

이 구조 덕분에 바깥 층이 안쪽 층의 합을 막을 수 있게 된다. 개별 컨테이너 하나하나가 아무리 얌전하게 자원을 써도, 상위 묶음인 /kubepods.slice의 상한에서 전체가 걸리기 때문이다. 그 상한선 값이 얼마이고 누가 이 파일에 값을 적는지는 이 절 뒤에서 이어진다.

이 /kubepods.slice 아래의 파드 디렉터리를 보면 pause라는 컨테이너가 파드마다 자동으로 붙어 있다.

파드 안 컨테이너들은 network namespace를 공유해 같은 IP를 쓰고 localhost로 서로를 부른다. 이때 앱 컨테이너가 죽었다 떠도 파드의 IP가 유지되려면 누군가 그 namespace를 끊임없이 붙들고 있어야 한다. 그 일만 전담하는 것이 pause 컨테이너이며, 이 역시 하나의 프로세스라 메모리도 몇 MiB 차지한다. 이 미세한 몫이 계산에 미치는 영향은 다시 나온다.

여기서 파드 몫과 시스템 몫이 갈린다

/kubepods.slice가 파드 전부를 담는 층이므로, 그 안과 밖이 곧 파드 몫과 시스템 몫이다.

파드 몫    /kubepods.slice
시스템 몫   루트 전체 − /kubepods.slice

cgroup이 메모리를 새로 분류하는 것은 아니다. 익명이냐 캐시냐는 그대로 두고, 거기에 누가 쓰느냐는 축을 하나 더한다. 그래서 두 축이 교차한다.

                 노드 전체     파드      시스템
익명 메모리         4,264     2,503     1,761
페이지 캐시         3,146     2,046     1,100

세로   익명이냐 페이지 캐시냐       커널이 가른다.  회수 가능 여부가 갈린다
가로   파드가 쓰는 것이냐 아니냐     /kubepods.slice 안이냐 밖이냐

여기 페이지 캐시 3,146은 2절에서 본 Cached 2,949에 Buffers 197을 더한 값이다. cgroup은 둘을 file 하나로 센다.

k3s.service가 시스템 쪽에 있는 이유도 여기 있다. 파드가 아니라 노드에서 직접 도는 프로세스라 /kubepods.slice 밖이다. 시스템 익명 메모리 1,761 중 대부분이 이 프로세스 하나다.

cgroup 이 세는 값 — 분류는 노드 층과 같다

cgroup 하나가 디렉터리 하나다. 위의 트리는 개념도가 아니라 /sys/fs/cgroup 아래에 실제로 있는 디렉터리 구조이고, 트리에 적은 세 파일도 실물이다.

/proc/meminfo가 노드 전체를 익명과 캐시로 나눴듯, cgroup도 자기 범위를 같은 항목(익명 / 캐시)으로 나눈다.

그 내역이 memory.stat에 있다.

$ cat /sys/fs/cgroup/kubepods.slice/memory.stat

anon      2624626688      파드 전부의 익명 메모리      2,503 MiB
file      2145509376      파드 전부의 페이지 캐시      2,046
kernel      76140544      커널 자료구조                  73
...                       inactive_file · active_file 이 이어진다

AnonPages·Cached가 anon·file로 이름만 바뀌었고 범위가 파드 전부로 좁혀진 것이다. 이 파일이 층마다 있어서, 컨테이너 cgroup에서 읽으면 그 컨테이너 하나의 익명과 캐시가 나온다.

컨테이너가 읽은 파일의 캐시는 그 컨테이너 몫으로 잡히므로, 로그를 많이 쓰는 컨테이너는 file이 그만큼 크다.

노드 층에 없는 것 — 상한

memory.stat이 내역이라면, 총량과 상한은 파일이 따로 있다. 성격이 다르다 — 하나는 측정이고 하나는 선언이다.

memory.current   파드 전부가 지금 쓰는 총량      4,622 MiB
                 측정.  커널이 센다.  계속 움직인다
                 = stat 의 합.  anon 2,503 + file 2,046 + kernel 73

memory.max       파드 전부가 넘을 수 없는 선     5,381 MiB
                 선언.  kubelet 이 적는다.  고정
                 = 물리 7,941 − 예약 2,560

memory.max의 뺄셈에 들어가는 예약 2,560이 노드 config.yaml에 직접 적은 그 값(= /system.slice)이다.

config.yaml       kube-reserved=memory=2Gi · system-reserved=memory=512Mi
  → kubelet 이 부팅하며 읽고 계산한다        7,941 − 2,048 − 512 = 5,381
  → /sys/fs/cgroup/kubepods.slice/memory.max 에 쓴다
  → 커널이 그 선을 강제한다

YAML에 적은 숫자가 커널 파일까지 내려간 것이다.

memory.max가 노드 층과 갈리는 지점이기도 하다. 노드에는 "여기까지"라는 파일이 없다. 물리 메모리가 곧 한계이고, 다 차면 커널이 알아서 회수하거나 죽인다. cgroup에는 그 선이 파일로 적혀 있고, 넘는 순간 그 cgroup 안에서만 커널이 개입한다.

컨테이너 cgroup의 memory.max도 같은 방식이고 적는 쪽만 다르다. /kubepods.slice는 kubelet이, 컨테이너 것은 containerd가 적는다.

그런데 커널은 이 둘을 그대로 비교하지 않는다

memory.current 4,622를 memory.max 5,381과 그대로 견주면 파드 전부가 상한의 86%까지 찬 것이 된다. 남은 자리가 759 MiB니 꽤나 용량이 부족한 것처럼 보인다.

그런데 그 파드 현재 총 사용량(current, 4,622) 안에는 파드들의 페이지 캐시(file, 2,046)가 들어 있다. 커널이 언제든 가져갈 수 있는 몫이다.(노드에서처럼)

memory.current 가 memory.max 5,381 에 닿는다
  → 커널이 그 cgroup 의 페이지 캐시부터 회수한다      2,046 이 줄어든다
  → 자리가 생기면 파드는 그대로 계속 돈다
  → 회수해도 안 줄어들 때만 죽인다                   익명 메모리는 못 줄이니까

"캐시부터 회수한다"는 것은 그 cgroup의 file(페이지 캐시)2,046을 가져간다는 뜻이고,

제일 중요한 건 그 안에서도 순서가 있다. 노드 전체를 Active·Inactive로 갈라 두었듯 cgroup 안에서도 같은 구분이 있으며, inactive_file 즉, 한동안 안 읽힌 페이지 캐시를 커널이 먼저 가져간다.

memory.stat 의 file 2,046      페이지 캐시
  ├─ inactive_file   한동안 안 읽힌 것.  커널이 먼저 가져간다
  └─ active_file     최근에 읽힌 것.    그래도 모자랄 때 가져간다

memory.stat 의 anon 2,503      익명 메모리
  ├─ inactive_anon   같은 구분이 여기도 있다
  └─ active_anon     그런데 이 노드에서는 둘 다 못 가져간다
                     버리면 값이 사라지고, 내보낼 자리가 없다

죽고 사는 것을 가르는 값은 memory.current가 아니다. 그 안에 커널이 가져갈 몫(페이지 캐시의 inactive_file 우선)이 섞여 있는 한, 상한에 닿아도 회수로 넘어간다. "지금 얼마나 위험한가"를 알려면 사라질 것을 미리 뺀 값이 필요하다.

그 값이 working_set 이다

memory.current에서 커널이 첫 번째로 가져갈 몫(페이지 캐시 - inactive_file)만 뺀다.

working_set = memory.current − inactive_file
            = 익명 메모리 anon
            + 페이지 캐시 중 active_file
            + 커널 자료 kernel

빼고 남기는 기준은 회수 가능 여부가 아니라, 회수했을 때 이 파드가 손해를 보느냐다.

항목	커널이 회수하면	working_set 에서
`inactive_file`	아무 일 없다. 곧 없어질 몫이다	뺀다
`active_file`	그 파드가 디스크를 다시 읽는다	남긴다
`anon`	값이 사라진다. 회수 자체가 안 된다	남긴다

그래서 working_set은 이 파드가 손해 없이는 못 놓는 양이다. 이 기준으로 파드 전부를 다시 재면 3,671이고, 같은 순간의 세 값이 이렇게 벌어진다.

memory.current  4,622  ████████████████████     86%   캐시까지 센 값
working_set     3,671  ██████████████           68%   판정에 쓰는 값
memory.max      5,381  └───────────────────┘          넘을 수 없는 선

여유를 구할 때도 어느 값에서 빼느냐로 답이 달라진다.

memory.max − memory.current    5,381 − 4,622 =   759
memory.max − working_set       5,381 − 3,671 = 1,710

앞쪽은 951을 적게 잡는다. current 안의 inactive_file은 파드가 더 요청하면 커널이 버리고 내줄 자리인데, 이미 쓰이는 것처럼 세기 때문이다. memory.current의 쓰임은 여기까지이고 뒤로는 working_set만 쓴다.

MemAvailable 은 노드 단위, working_set 은 파드 단위

2절에도 캐시를 다루는 계산이 하나 있었다. MemAvailable이다. 둘을 나란히 놓으면 이렇다.

	무엇을 재나	범위	계산식
`MemAvailable`	지금 더 줄 수 있는 양	노드 전체	`MemFree` + 페이지 캐시([`Active(file)` + `Inactive(file)`] + `SReclaimable` − 안전분
`working_set`	지금 실제로 쓰는 양	`/kubepods.slice`	`memory.current` − `inactive_file(file)`

식에 나오는 Inactive(file)과 inactive_file은 같은 것을 가리킨다. 둘 다 페이지 캐시이고, /proc/meminfo가 쓰는 표기와 cgroup의 memory.stat이 쓰는 표기가 다를 뿐이다.

MemAvailable은 노드 단위 값이다. 노드 전체에서 지금 더 내줄 수 있는 양이고, 회수할 수 있는 것은 전부 여유로 센다.

working_set은 cgroup 단위 값이다. 그 묶음이 지금 붙들고 있는 양이고, 회수되면 사라질 것만 빼고 센다.

둘은 답이 다른 게 아니라 묻는 것이 다르다. 그래서 한 계산식 안에 섞으면 안 되고, 6절에서 고칠 것이 그 자리다.

대시보드에서 파드가 얼마 쓰는지를 볼 때 필요한 값은 working_set 쪽이다. 그 값을 어디서 얻는지가 남았다.

이것이 cAdvisor 가 내는 값이다

working_set은 cgroup 파일에 적혀 있지 않다. memory.current와 memory.stat을 읽어 계산해야 나오고, 그 계산을 해서 Mimir로 보내는 것이 cAdvisor다.

컨테이너별 자원 사용량을 재려고 구글이 만든 것을 쿠버네티스가 kubelet 안에 넣었다. 그래서 별도 파드로 뜨지 않고 노드의 :10250/metrics/cadvisor를 긁으면 나온다.

이름 앞에 container_가 붙고, 읽어 온 cgroup 파일이 그대로 메트릭이 된다.

memory.stat 의 anon             →  container_memory_rss
memory.stat 의 file             →  container_memory_cache
memory.max                      →  container_spec_memory_limit_bytes
memory.current − inactive_file  →  container_memory_working_set_bytes

앞의 셋은 숫자를 형식만 바꿔 옮긴 것이고, 마지막 하나만 계산해서 만든다. 공짜로 회수될 몫(inactive_file)을 뺀 값이라 그 cgroup이 손해 없이는 못 놓는 양이 된다.

어느 위치의 cgroup 값인지는 라벨이 가른다. - cgroup은 계층 구조이기 때문에

cgroup 하나마다 시계열이 하나씩 나오는데, 이름은 전부 container_memory_working_set_bytes로 같고 중괄호 안만 다르다.

라벨	어느 범위의 working_set	무엇과 비교하나	지금 값
`id="/"`	노드의 모든 프로세스		5,906
`id="/kubepods.slice"`	파드 전부	`memory.max` 5,381	3,671
`pod="queue-xxxxx"`	파드 하나	그 안 `limits` 합
`container="queue"`	컨테이너 하나	그 컨테이너의 `limits`

container 라벨이 빈 시계열도 같이 나온다. 파드 cgroup 자체를 가리키는 것이라 pause 몫이 거기 들어 있고, 컨테이너만 세려면 container!=""로 걸러야 한다.

루트 id="/" 줄만 조립 방식이 다르다.

루트 cgroup 디렉터리에는 memory.current도 memory.stat도 없다 — 둘 다 비루트 전용 파일이고, 노드 전체는 커널이 이미 /proc/meminfo(node-exporter 역할)에서 세고 있다. 그래서 cAdvisor가 루트만은 그 파일로 같은 꼴을 조립한다.

비루트 cgroup   working_set = memory.current − inactive_file
루트 "/"       working_set = (MemTotal − MemFree) − Inactive(file)

"working set"을 구하는 것이기에 빼는 항의 정체는 페이지 캐시의 Inactive로 같다 — 그 범위에서 커널이 공짜로 회수할 몫.

층이 같은 이름으로 나오니 뺄셈이 그대로 쿼리가 된다.

container_memory_working_set_bytes{id="/"}
  − container_memory_working_set_bytes{id="/kubepods.slice"}
  = 2,235                                        시스템 몫

노드 전체와 파드 전부를 같은 기준으로 잰 값이라 빼도 어긋나지 않는다. 6절에서 표를 고칠 때 쓰는 것이 이 성질이다.

한계 — 지금 쓰는 양과 지금 걸린 상한까지

cAdvisor가 읽는 것은 cgroup 파일뿐이라, 거기 적혀 있는 것까지만 답한다.

답한다     파드 전부가 지금 얼마 쓰나            3,671
          그 상한이 얼마인가                   5,381
          컨테이너 하나가 자기 limits 를 넘었나

답 못 한다  그 상한이 왜 5,381 인가
          파드를 더 앉힐 자리가 있나            requests 는 cgroup 에 없다

memory.max가 7,941 − 2,560이라는 것까지는 봤지만 그 예약을 왜 그만큼 뗐는지, 스케줄러가 보는 선은 왜 또 다른지는 cgroup 밖에서 정해진다. 그 값을 계산해서 cgroup 파일에 적는 쪽이 4절이다.

4. 쿠버네티스 층 — 노드를 나누고 그 선을 cgroup 으로 옮긴다

앞의 두 층은 쿠버네티스가 없어도 있는 것이었다. 리눅스 서버라면 어디든 /proc/meminfo(node-exporter)가 있고 cgroup 디렉터리(cAdvisor)가 있다. 그 파일들을 채우는 것은 커널이다.

그중 memory.max 하나만 커널이 채운 것이 아니다. 누군가 계산해서 써 넣은 값이다. 그 일을 하는 것이 노드마다 하나씩 도는 kubelet 이고, 파드를 띄우는 것도 넘은 파드를 내보내는 것도 이 프로세스가 한다.

cAdvisor 는 kubelet 안에 있는데 층이 다르다

memory.max 파일 하나를 셋이 건드린다. 하나가 쓰고 둘이 읽는다.

쓴다    kubelet    이 파일에 5,381 을 적는다
읽는다  커널       적힌 값을 읽어 그 선을 강제한다
읽는다  cAdvisor   적힌 값을 읽어 메트릭으로 내놓는다
                    container_spec_memory_limit_bytes

cAdvisor는 kubelet 바이너리에 컴파일된 코드라 별도 프로세스가 아니다 — ps로 찾아도 안 나온다. 같은 프로세스 안에 있어도 cAdvisor는 읽는 쪽에만 서 있다.

그래서 층을 가르는 기준은 어느 프로세스에서 도느냐가 아니라 그 값을 누가 정했느냐다.

값	어디 적혀 있나	누가 정했나
`MemTotal` · `MemAvailable`	`/proc/meminfo`	커널이 센다
`memory.current` · `memory.stat`	cgroup 파일	커널이 센다
`memory.max`	cgroup 파일	kubelet 이 계산해 쓴다
`allocatable` · `requests`	노드의 파일에 없다. apiserver 에 있다	쿠버네티스가 정한다

커널이 다루는 위 둘은 초마다 움직인다. 아래 둘은 설정을 바꾸고 kubelet을 다시 띄울 때까지 고정이다. 대시보드에서 한쪽은 출렁이고 한쪽은 평평한 선으로 나온다.

뺄셈이 두 단이고, 값을 둘 뽑는다

kubelet은 부팅하며 노드 config.yaml의 예약 줄을 읽고 노드의 물리 메모리에서 뺄셈을 한다.

중간에 한 번 cgroup /kubepods.slice의 memory.max로 , 끝에 한 번 allocatable 값을 뽑아 apiserver로 보낸다.

capacity 7,941 MiB (7.76 GiB)   노드의 물리 메모리
  − kube-reserved     2,048     kubelet · containerd 몫
  − system-reserved     512     sshd · systemd 등 OS 몫
  ──────────────────────────
  = 5,381 MiB                   /kubepods.slice 의 memory.max 에 쓴다
  − eviction-hard       300     노드 여유가 이 아래면 파드를 내보낸다
  ──────────────────────────
  = 5,081 MiB (4.96 GiB)        allocatable 로 apiserver 에 보고한다

세 줄 전부 노드 config.yaml에 적어 둔 값이고, 그 프로세스들이 실제로 그만큼 쓴다는 뜻이 아니라 파드에게 안 주고 남겨 둔다는 뜻이다.

시스템 쪽을 그 안에 가둔다는 뜻도 아니다. kubelet이 상한을 적는 cgroup은 /kubepods.slice 하나라 /system.slice는 상한 없음 그대로이고, 시스템이 2,560을 넘게 써도 막는 선이 없다. 지금 시스템 몫 2,235가 예약 안에 있는 것은 강제된 결과가 아니라 관측값이다.

두 값이 다른 곳으로 가는 이유 — 읽는 쪽이 다른 데 있다

allocatable은 메트릭이 아니다. kubelet이 Node 오브젝트의 status.allocatable 필드에 실어 apiserver로 올리는 값이고, kubectl describe node로 보인다.

노드하나에 CPU 4를 할당. 위의 config.yaml을 읽어 kube-reserved / system-reserved의 CPU 500+200 값을 제외하여 Alloctable은 kubelet이 3300으로 할당.

memory.max    같은 노드의 커널이 읽는다.  cgroup 파일 하나로 끝난다
allocatable   스케줄러가 읽는다.          스케줄러는 다른 노드에 앉아 있다

쿠버네티스 클러스터의 컴포넌트인 스케줄러는 k3s-1의 /sys/fs/cgroup을 못 읽는다. 노드 사정이 클러스터에 올라가 있어야 자리를 판단할 수 있고, 그 통로가 apiserver다.

세 값이 각각 다른 것을 상대한다

파드 몫을 가리키는 값이 둘이 되고 300 MiB 어긋나지만, 어느 하나가 틀린 것이 아니다.

값	누가 보나	무엇과 비교하나	넘으면
5,081 `allocatable`	스케줄러	이 노드에 앉은 파드의 `requests` 합	파드를 더 안 앉힌다
5,381 `memory.max`	커널	파드 전부의 `working_set`	그 안에서 OOM 이 난다
300 `eviction-hard`	kubelet	노드 여유	파드를 골라 내보낸다

스케줄러가 보는 축과 커널이 보는 축이 다르다. 5,081은 스펙에 적힌 값끼리의 덧셈에 걸리는 선이고, 5,381은 지금 실제로 쓰는 양에 걸리는 선이다. 그래서 파드 전체가 5,081을 넘게 써도 커널은 5,381까지 안 죽인다. 그 사이 300 MiB는 kubelet이 먼저 개입하도록 비워 둔 자리다.

노드 한 대를 나누는 선은 여기까지다. 5,381도 5,081도 300도 전부 노드 config.yaml에서 나온 노드 단위 값이다. 그런데 표에 출처가 다른 값이 하나 끼어 있다. 스케줄러가 5,081과 견주는 requests 합 — 노드 설정이 아니라 파드마다 스펙에 적은 값을 더한 것이다. 그 스펙으로 내려간다.

파드 하나에 적는 값 — requests 와 limits, reqeusts와 alloctable

파드 스펙에 메모리 값을 두 개 적는다. 하나가 방금 그 requests이고, limits가 그 짝이다. 노드 층에서 갈린 두 축이 여기서 하나씩 제 값을 갖는다.

requests   스케줄러의 축      노드를 고를 때 allocatable 과 견주는 재료
limits     커널의 축          이 컨테이너 cgroup 의 memory.max 가 된다

requests는 앉힐 때만 쓰인다. 스케줄러는 새 파드가 오면 노드마다 이미 앉은 파드들의 requests 합에 새 파드 몫을 더해 allocatable과 견주고, 통과한 노드 중에서 고른다.

이 덧셈에 실사용은 안 들어간다. requests를 500Mi로 적은 컨테이너가 실제로 얼마를 쓰든 스케줄러는 500으로 더하고, 500Mi를 보장해 주는 것도 아니다. 앉은 뒤의 실행에는 관여하지 않는다.

limits는 앉은 뒤를 맡는다. 컨테이너 cgroup의 memory.max가 되어 커널이 강제한다. working_set이 그 값을 넘으면 커널이 회수를 시도하고, 회수해도 못 줄이면 그 cgroup 안의 프로세스를 죽인다.

선에 걸리면 벌어지는 일이 셋이다

파드가 앉지 못하거나 사라지는 경로가 셋이고, 세 선이 하나씩 맡는다.

            안 앉힌다              OOMKill                eviction
누가        스케줄러               커널                   kubelet
걸리는 선   allocatable 5,081     memory.max · limits    eviction-hard 300
견주는 값   requests 합           working_set            노드 여유
대상        새로 오는 파드         그 cgroup 안 프로세스  노드 위 파드 중 하나
결과        Pending 으로 대기      컨테이너 재시작         Evicted 로 남는다
이벤트 기록  FailedScheduling      OOMKilling             Evicted

왼쪽 하나는 선언 축이고, 오른쪽 둘은 실사용 축이다. 안 앉힘은 실사용과 무관하게 난다 — 노드가 한가해도 이미 앉은 파드들의 requests 합이 allocatable을 채우고 있으면 새 파드는 Pending으로 남는다.

OOMKill은 그 컨테이너가 자기 상한을 넘은 것이라 노드에 메모리가 남아 있어도 난다. eviction은 노드 전체가 모자란 것이라 자기 상한을 안 넘은 파드도 대상이 된다.

eviction에서 kubelet이 누구를 고를지는 requests와 limits의 관계가 정한다. 그 관계에 붙은 이름이 QoS 등급이다.

Guaranteed    requests == limits (CPU·메모리 모두)      나중에 내보낸다
Burstable     requests < limits, 또는 하나만 적음
BestEffort    둘 다 안 적음                            먼저 내보낸다

이것이 kube-state-metrics(KSM) 가 내는 값이다

kubelet이 계산한 allocatable과 파드 스펙에 적힌 requests는 apiserver에 오브젝트로 저장된다. 그것을 읽어 Mimir로 보내는 것이 kube-state-metrics(KSM)다.

노드와 무관한 유일한 출처다. 클러스터에 파드 하나로 뜨고, 읽는 곳도 apiserver 하나다. 노드마다 있을 이유가 없다 — cgroup도 /proc도 안 읽는다. 이름 앞에 kube_가 붙고, 오브젝트의 필드가 그대로 메트릭이 된다.

kube_node_status_capacity        노드가 보고한 물리 메모리
kube_node_status_allocatable     kubelet 이 계산한 allocatable
kube_pod_container_resource_requests   파드 스펙에 적힌 값

이 값이 필요한 이유는 스케줄러가 보는 세계가 이쪽이기 때문이다. 파드를 어디 앉힐지는 실사용이 아니라 allocatable과 requests로 정해지므로, "이 노드에 더 앉힐 수 있나"는 이 값으로만 답이 나온다.

한계는 실사용을 모른다는 것이다. requests: 500Mi라고 적혀 있으면 그 값을 낸다. 그 컨테이너가 실제로 50Mi를 쓰든 490Mi를 쓰든 같은 값이다.

답할 수 있다   파드를 새로 앉힐 자리가 있나       allocatable − requests 합
답 못 한다     지금 실제로 얼마 쓰나

apiserver를 거쳐 오는 것도 성질을 하나 만든다. etcd 쿼럼이 깨지면 갱신을 멈추고 마지막 값으로 굳는다. 노드가 죽어도 값이 그대로 남아 있을 수 있다.

kubelet 자신도 :10250/metrics로 지표를 내지만(kubelet_*) 이 대시보드에서는 쓰지 않는다. kubelet은 값을 내는 쪽보다 판정하는 쪽으로 이 글에 나온다 — allocatable을 계산하고, cgroup 상한을 설정하고, 누구를 내보낼지 고른다.

층 셋을 한 표로

2·3·4절을 접으면 이렇게 남는다.

층	값이 적히는 곳	재서 내보내는 곳	메트릭	성격
리눅스(2절)	`/proc/meminfo`	node-exporter	*`node_`**	노드 전체 합. 캐시는 전부 여유
cgroup(3절)	cgroup 파일	cAdvisor	*`container_`**	묶음별. `active_file`은 사용
쿠버네티스(4절)	apiserver 오브젝트	kube-state-metrics(KSM)	*`kube_`**	선언값. 실사용과 무관, 고정

세 층이 캐시와 실사용을 서로 다르게 세는 것까지 성격 칸에 들어 있다. 행1이 쓰는 값은 전부 이 세 줄 어딘가에서 나온다. 이것을 들고 대시보드로 돌아간다.

5. 층의 값으로 행1 을 짠다

처음에 던진 질문 셋을 다시 놓는다.

이 노드에 파드를 더 앉힐 수 있나
어디까지가 파드 몫이고 어디부터가 시스템 몫인가
노드마다 떼어 둔 예약 2,560 을 줄일 수 있나

첫 질문은 선언 축의 질문이다. 파드를 앉히는 것은 스케줄러이고, 스케줄러는 requests 합과 allocatable만 보므로 다른 값으로는 답이 안 나온다. 나머지 둘은 실사용 축의 질문이다. 지금 실제로 쓰는 양을 파드 몫과 시스템 몫으로 갈라 세야 한다.

축이 다른 값을 한 표에 섞으면 열마다 기준을 따져 읽어야 한다. 그래서 행1을 표 두 개로 갈랐다.

선언 — 스케줄러가 보는 세계    allocatable · requests 합 · 스케줄 여유
실사용 — 커널이 보는 세계      물리 · 파드 사용 · 시스템 사용
                             노드 여유 · 파드 여유 · 시스템 여유

첫 질문은 선언 표가 그 자리에서 답한다. 스케줄 여유 = allocatable − requests 합이고, 재료 둘 다 kube-state-metrics가 낸다. 남은 두 질문이 실사용 표의 몫이고, 이 표에서 문제가 났다.

그라파나가 표를 만드는 방식

Mimir에 저장되는 것은 시계열이다. 메트릭 이름 + 라벨 조합 하나가 시계열 하나이고, 거기에 시각과 값이 짝으로 쌓인다. 그라파나 패널은 PromQL 쿼리를 Mimir에 보내고, 돌아온 시계열을 그린다. 패널 종류가 정하는 것은 얼마나 요청해서 어떻게 그리느냐다.

표 패널     마지막 시각의 값 하나만 요청한다
            시계열마다 행 하나 — node 라벨 k3s-1·2·3 이 세 행이 된다
            쿼리 하나가 열 하나 — 여섯 열이면 쿼리 여섯
추이 패널   구간을 요청해 시각순으로 선을 잇는다
            정한 값 allocatable 은 평평한 선, 재는 값은 출렁이는 선

행이 노드별로 갈리려면 모든 쿼리 결과에 node 라벨이 있어야 한다. kube_*에는 있는데 node-exporter가 내는 값에는 없다. instance="192.168.0.201:9100" 형태뿐이라 그대로는 다른 출처와 안 붙는다. 그래서 노드 이름이 든 node_uname_info와 조인해 이름을 붙인다.

node_memory_MemTotal_bytes * on(instance) group_left(nodename) node_uname_info

행1의 node_* 쿼리마다 이 조각이 붙어 있는 것이 그래서다.

실사용 표의 여섯 열 — 넷이 뺄셈이다

실사용 쪽 두 질문에 답하려면 열이 여섯 필요하다.

가른다     파드 사용 · 시스템 사용
남은 양    파드 여유 · 시스템 여유
기준       물리 · 노드 여유

이 중 넷이 뺄셈으로 나온다. 뺄셈은 빼는 두 값이 같은 기준일 때만 성립한다 — 여기가 이 글이 막혔던 자리다.

시스템 사용 열이 두 층을 섞었다

행1을 처음 짤 때 시스템 사용을 이렇게 계산했다.

시스템 사용 = (MemTotal − MemAvailable) − Σ working_set{container!=""}
                  리눅스 층 값                  cgroup 층 값

노드 전체가 쓰는 양에서 파드가 쓰는 양을 빼면 시스템이 남는다는 계산인데, 앞항과 뒤항이 다른 층에서 왔다.

이 값이 맞는지는 화면 밖에서 확인된다. 시스템 몫의 대부분은 k3s.service 프로세스 하나이므로, 노드에 들어가 그 RSS와 나란히 놓으면 된다.

                      k3s-1    k3s-2    k3s-3     MiB
시스템 사용 열의 값     1,356      663      360
k3s.service RSS       1,708    1,120    1,082

k3s-3에서 이 열은 시스템 전체를 360으로 계산하는데, 그 안에서 도는 프로세스 하나가 1,082다. 세 노드 모두 프로세스 하나가 시스템 전체로 계산된 값보다 크다. 식이 틀렸다.

원인 — 캐시를 반대로 세는 값끼리 뺐다

리눅스 층은 active_file을 여유로 센다 — 커널이 MemAvailable에 더해 둔다. cgroup 층은 사용으로 센다 — cAdvisor가 working_set에 남긴다. 두 값을 한 식에 넣으면 k3s-1에서 이렇게 된다.

MemTotal − MemAvailable = 4,740     노드 전체의 "사용"
    MemAvailable = MemFree + 페이지 캐시 전부 + SReclaimable − 안전분
    → 캐시를 여유로 쳤다.  파드의 active_file 이 이 사용에는 없다

Σ working_set           = 3,384     파드 전부의 "사용"
    working_set = memory.current − inactive_file
    → active_file 을 사용으로 남겼다.  여기에는 들어 있다
                          ─────
                          1,356     앞항에 없는 몫을 뒤항이 들고 있어
                                    그만큼 한 번 더 빠진다

같은 층의 값끼리 빼면 active_file이 양쪽에 같은 방식으로 들어 있어 상쇄된다.

루트 / 의 working_set             5,906     노드 전체 (파드 + 시스템)
    (MemTotal − MemFree) − Inactive(file)
/kubepods.slice 의 working_set    3,671     파드 전부
    memory.current − inactive_file
                                  ─────
                                  2,235     시스템 몫만 남는다
                                            k3s.service RSS 1,708 을 담는다

세 노드를 다 재면 오차가 활성 캐시 양을 따라간다.

              Active_file    섞은 식     cgroup 기준    차이
k3s-1            1,649        1,356        2,235        880
k3s-2            1,566          663        1,550        887
k3s-3            1,980          360        1,548      1,188

활성 캐시 양은 그 노드에 앉은 파드가 무엇을 읽느냐가 정한다. 그래서 노드마다 다르게 어긋나고, 화면만 봐서는 어느 값이 맞는지 가릴 수 없는 종류의 오류다.

파드 사용 열도 범위가 어긋난다

같은 검산에서 하나 더 나왔다. 파드 전부가 쓰는 양을 구하는 방법이 둘 있는데, 행1의 파드 사용 열은 위쪽을 쓰고 있다.

Σ working_set{container!=""}        3,384   컨테이너 시계열을 전부 더한다
working_set{id="/kubepods.slice"}   3,671   디렉터리 값을 그대로 읽는다
                                            커널이 memory.max 와 비교하는 값

둘 다 cgroup 층이라 캐시 기준은 같은데 287 차이가 난다. 더한 값이 작은 이유는, /kubepods.slice 안에 컨테이너 시계열로 안 잡히는 몫이 있어서다.

/kubepods.slice                3,671 = 이 아래 전부의 합
├─ 파드 하나
│   ├─ pause 컨테이너            container 라벨이 없다 → Σ 에서 빠진다
│   └─ 앱 컨테이너               Σ 에 들어간다
├─ 파드 …
└─ 컨테이너 밖에 직접 얹힌 몫      죽은 컨테이너가 남긴 캐시는 부모
                                cgroup 으로 이관된다 → Σ 에서 빠진다

커널이 상한 5,381과 비교하는 값은 디렉터리 값 3,671이다. 개별 합 3,384로 여유를 계산하면 표가 파드 여유를 287만큼 크게 잡는다.

표가 말하는 파드 여유       5,381 − 3,384 = 1,997
커널이 실제로 허용하는 것    5,381 − 3,671 = 1,710

부하 판에서 "아직 자리 있다"로 읽은 곳에 커널은 287만큼 더 가까이 와 있는 셈이다.

고치는 원칙은 하나로 좁혀졌다.

6. 같은 기준 안에서만 뺀다

한 열의 뺄셈은 한 층의 값끼리만 한다. 바꾸기 전에, 식에 나오는 세 값을 한 번 더 세워 둔다.

MemAvailable — 노드 전체에서 지금 달라면 받을 수 있는 양.
- 커널이 MemFree + 파일 캐시 전부 + SReclaimable − 안전분으로 계산해 두고, node-exporter가 낸다.
- 캐시를 여유 쪽에 놓는 회계다.
working_set — 그 cgroup이 놓으면 손해인, 쓰는 중인 양.
- cAdvisor가 memory.current − inactive_file로 계산한다.
- active_file을 사용 쪽에 놓는 회계라, 같은 캐시가 MemAvailable과 반대편에 선다.
allocatable — 노드가 파드에게 내주기로 선언한 총량.
- kubelet이 capacity − 예약 2,560 − eviction 300 = 5,081로 계산해 apiserver에 보고한다.
- 실사용과 무관하게 고정이고, 스케줄러가 requests 합과 비교할 때만 쓴다.

여섯 열을 이렇게 바꾼다.

물리        MemTotal                                  리눅스 층 · 그대로 둔다

파드 사용    Σ container{container!=""}                cgroup 층
         →  working_set{id="/kubepods.slice"}         같은 층 · 범위 교정

시스템 사용  (MemTotal − MemAvailable) − Σ container   리눅스−cgroup 섞임
         →  working_set{id="/"} − working_set{id="/kubepods.slice"}
                                                      cgroup 층끼리

노드 여유    MemAvailable                              리눅스 층
         →  capacity − working_set{id="/"}            총량 − cgroup 층

파드 여유    allocatable − Σ container                 선언값−cgroup 섞임
         →  memory.max 5,381 − working_set{id="/kubepods.slice"}
                                                      cgroup 층끼리

시스템 여유  예약 2,560 − 시스템 사용                   상수−cgroup · 그대로

블록의 약칭이 쿼리에서는 이 이름이다.

MemTotal      node_memory_MemTotal_bytes            리눅스 층 · node-exporter
working_set   container_memory_working_set_bytes    cgroup 층 · cAdvisor
memory.max    container_spec_memory_limit_bytes     cgroup 층 · cAdvisor
capacity      kube_node_status_capacity             쿠버네티스 층 · KSM
예약 2,560     메트릭이 아니다.  config.yaml 에 적은 값

capacity는 선언값(KSM)인데 실사용 표에 껴도 어긋나지 않는다 — 안 움직이는 총량이라 캐시를 어떻게 세느냐는 회계가 아예 안 붙는다. 섞임이 문제가 되는 것은 움직이는 값들 사이다.

node_memory_MemAvailable_bytes가 행1에서 빠진다. 커널 관점의 여유라 cgroup 회계와 섞이지 않고, 실사용 표의 여유 세 칸은 전부 cgroup 기준으로 나온다.

파드 여유의 기준은 allocatable 5,081이 아니라 cgroup 상한 5,381이다. 이 열이 답하는 질문이 "기존 파드가 더 쓸 수 있나"이고, 그 선을 긋는 것은 커널의 memory.max이기 때문이다. 스케줄러 관점의 여유는 선언 표의 스케줄 여유가 따로 답하고 있다.

CPU 표는 고치지 않는다

실사용 CPU 표에도 같은 형태의 뺄셈이 있어 같은 검산을 했다.

                        k3s-1   k3s-2   k3s-3   millicore
node-exporter 기준         196     186     164
cgroup 기준               171     160     140
차이                      +25     +26     +24

세 노드가 모두 같은 방향으로 15퍼센트 남짓 크다. 메모리처럼 노드마다 뒤집히지 않는다.

CPU에는 페이지 캐시 같은 회계 차이가 없다. 대신 node-exporter가 세는 non-idle 시간에는 cgroup에 귀속되지 않는 것이 들어간다 — 인터럽트(irq·softirq)와 steal이다. 원래 다른 것을 세는 차이이고, 노드가 실제로 태우는 CPU에는 그것도 포함이 맞다.

예약 2,560 을 줄일 수 있나

세 번째 질문은 고친 시스템 사용으로 답이 나온다.

                                  k3s-1   k3s-2   k3s-3     MiB
시스템 사용 (cgroup 기준)            2,235   1,550   1,548
떼어 둔 예약                        2,560   2,560   2,560
여유                                 325   1,010   1,012

예약을 2 GiB로 줄이면 k3s-1은 187 MiB가 모자란다. 섞어 뺀 값 1,356으로 계산하면 여유가 1,204로 나와 줄여도 된다는 답이 됐을 자리다. 부하 판에서 이 값이 어디까지 오르는지를 보고 정한다.

여기까지가 행1을 고치는 근거다. 남은 일은 실사용 표의 쿼리 넷을 위 식으로 바꾸는 것이고, 표가 같은 기준으로 서 있어야 부하를 걸며 읽는 숫자도 같은 기준으로 읽힌다.

번외 — 클러스터 안 카프카

hsb_02 — Tue, 11 Aug 2026 21:55:38 +0900

1. 막힌 자리

11부에서 data 네임스페이스의 파드(MySQL·Redis·Kafka)에 NetworkPolicy 를 설계하는 중이다. 방식은 하나다. 일단 전부 막고, 들어와야 하는 것만 다시 연다. 그래서 대상마다 같은 질문에 답하게 된다 — 이 포트에 누가 붙어야 하나.

MySQL 3306 은 booking 하나였다. Redis 6379·26379 는 queue 와 booking 이었다. Kafka 9092 에서 답이 나오지 않았다. 브로커가 3대인 것도, 토픽이 5종인 것도, partitions: 4 와 min.insync.replicas: 2 가 무엇을 정하는 값인지도 조회해야 알 수 있었다. 그 설정은 AI 도움을 받아 쓴 것이고, 그때 읽고 넘어갔다고 생각했던 것들이다.

이 글은 그것을 조회로 다시 읽은 기록이다. 순서는 카프카 문서의 목차를 따르지 않는다. 앞 항목이 만들어 낸 문제를 뒤 항목이 푸는 순서로 간다.

여기서 쓰는 쿠버네티스 용어

파드(Pod) — 컨테이너를 실행하는 최소 단위. 한 파드는 한 노드(물리·가상 서버) 위에서 돈다.
네임스페이스(Namespace) — 클러스터 안을 이름으로 나눈 구획. app(frontend·queue·booking) / data(MySQL·Redis·Kafka) / observability 셋으로 나뉜다.
커스텀 리소스(CR)와 오퍼레이터 — 쿠버네티스가 원래 모르는 종류의 객체를 선언 형식으로 등록한 것이 CR, 그 선언을 읽어 실제 파드·설정을 만들고 유지하는 프로그램이 오퍼레이터. Kafka·KafkaNodePool·KafkaTopic 은 Strimzi 오퍼레이터(1.1.0)가 읽는 CR 이고, 그 결과로 Kafka 4.3.0 브로커 파드가 선다.
PV(PersistentVolume) — 파드가 재시작해도 남는 디스크 영역. 로컬 PV 는 특정 노드의 디스크를 그대로 쓰는 PV 라, 그 PV 를 쓰는 파드는 그 노드에 고정된다.
HPA(HorizontalPodAutoscaler) — 부하에 따라 파드 수를 min 과 max 사이에서 조절하는 객체.
NetworkPolicy — 파드가 주고받는 통신을 상대·포트 단위로 제한하는 객체. 정책이 하나도 없으면 전부 통과한다.

2. 요청이 사라지는 지점

이 클러스터에 올라간 서비스는 셋이다. frontend(정적 페이지), queue(Go, 대기열과 정원 판정), booking(Java/Spring, 예매).
queue 가 정원 통과자를 판정하면 booking 이 그 사람에게 좌석 접근 권한을 발급한다.
이 두 동작을 queue 가 booking 을 직접 HTTP 로 호출해 잇는다고 하면, booking 파드가 재시작 중인 순간의 호출은 실패하고 그 요청은 어디에도 남지 않는다.
queue 안에서 재시도를 돌려도 queue 파드 자신이 재시작하면 재시도 대상 목록이 함께 사라진다. 보내는 쪽과 받는 쪽 사이에 요청을 적어 두는 자리를 두면 이 구간이 끊기지 않는다. 카프카가 그 자리다.

카프카

들어온 레코드를 파일 끝에 덧붙이기만 하고, 읽는 쪽이 나중에 순서대로 가져가게 하는 서버. 이 구조를 append-only 로그라 부른다. 여기서 로그는 프로그램이 남기는 진단 메시지가 아니라, 기록을 파일 끝에만 덧붙이고 한 번 적힌 것은 고치지 않는 파일 구조 자체를 가리킨다.

세 가지 이름이 계속 나온다.

브로커(broker) — 레코드를 받아 디스크에 적고 읽기 요청에 답하는 서버 프로세스. 이 클러스터에서는 파드 하나가 브로커 하나다.
프로듀서(producer) — 레코드를 브로커에 보내는 쪽.
컨슈머(consumer) — 브로커에서 레코드를 읽는 쪽.

이 클러스터의 실제 흐름은 이렇게 이어진다.

사용자가 queue 에 붙는다. queue 가 Redis 에서 Lua 스크립트로 정원을 원자적으로 확인하고, 통과자만 admissions 에 발행한다.
booking 이 admissions 를 읽고 admitted:{movie}:{requestId} 키를 Redis 에 발급한다(TTL 180초). 좌석 조회·점유·예매 확정은 그 키를 요구한다. 없으면 403.
예매가 확정되면 booking 이 bookings-completed 를 발행하고, queue 가 그것을 읽어 자리를 반환해 다음 사람을 들여보낸다.
세션이 만료되거나 이탈하면 queue 가 admissions-revoked 를 발행하고, booking 이 인증 키를 지운다.

queue 와 booking 은 서로를 호출하지 않는다. 양쪽 다 브로커에만 붙는다.

3. 읽고 지우지 않는다 — 오프셋

읽은 레코드를 그 자리에서 지우는 방식이면 두 가지가 막힌다. 컨슈머가 레코드를 꺼낸 뒤 처리 도중 실패하면 그 레코드는 이미 없어서 다시 처리할 수 없다. 그리고 같은 레코드를 성격이 다른 두 소비자가 각각 읽을 수 없다.

카프카는 읽어도 지우지 않는다. 대신 컨슈머 쪽이 "어디까지 읽었는지" 를 숫자로 기억한다. 이 숫자가 오프셋(offset)이다. 로그에 적힌 레코드마다 0부터 1씩 증가하는 정수가 붙고, 컨슈머는 처리를 마친 위치를 커밋한다.

로그   [0][1][2][3][4][5][6]
                 ▲        ▲
      커밋한 위치 3        마지막 기록 6
                 └─ 밀린 레코드 3건

이 위치 값을 컨슈머 파드 안에 두면 파드가 재시작할 때 사라진다. 그래서 브로커가 __consumer_offsets 라는 자기 토픽에 적어 둔다. 토픽 목록을 뽑으면 선언한 적 없는 이 이름이 함께 나온다.

안 하면: 처리에 실패한 레코드를 다시 읽을 수 없고, 컨슈머 파드가 재시작하면 읽던 위치를 잃는다.

4. 이름으로 가른다 — 토픽

로그가 하나뿐이면 정원 통과, 예매 완료, 세션 회수가 한 로그에 섞여 들어온다. 읽는 쪽은 자기와 무관한 레코드까지 전부 읽어 걸러 내야 한다.

토픽(topic)은 레코드를 담는 로그에 붙인 이름이다. 프로듀서는 토픽 이름을 지정해 발행하고, 컨슈머는 토픽 이름을 지정해 구독한다. 이 클러스터는 토픽 5종을 KafkaTopic CR 로 선언해 둔다.

토픽	파티션	복제본	발행	소비	보존
`admissions`	4	3	queue	booking	3일
`admissions-revoked`	4	3	queue	booking	3일
`bookings-completed`	4	3	booking	queue	3일
`admissions.DLT`	1	3	booking 내부	없음	7일
`admissions-revoked.DLT`	1	3	booking 내부	없음	7일

DLT(Dead Letter Topic)는 booking 이 레코드 처리에 반복 실패했을 때 그 레코드를 옮겨 두는 토픽이다. 실패한 레코드가 원래 토픽의 진행을 막지 않게 분리한다.

브로커 설정에 따라 토픽은 앱이 처음 붙을 때 자동으로 만들어질 수도 있다. 저장소의 주석은 선언해 두는 이유를 이렇게 적어 두었다 — "선언하지 않으면 앱이 처음 붙을 때 브로커가 기본값(파티션 1)으로 만들고, 파티션은 줄일 수 없어 그 값이 굳는다."

안 하면: 종류가 다른 레코드가 한 로그에 섞이고, 자동 생성에 맡기면 파티션 수가 기본값으로 고정된다.

5. 한 토픽이 한 브로커에 묶인다 — 파티션

토픽 하나가 로그 파일 하나면 그 파일은 브로커 한 대의 디스크에 있다. 그 토픽으로 오는 발행과 소비 요청은 전부 그 한 대로 간다. 브로커를 몇 대 세워 두든 그 토픽에 대해서는 나머지가 아무 요청도 받지 않는다.

파티션(partition)은 한 토픽의 로그를 여러 개로 나눈 것이다. 각 파티션이 독립된 append-only 로그 파일이고, 파티션마다 그것을 맡는 브로커가 따로 정해진다. 레코드마다 붙는 정수인 오프셋도 파티션마다 따로 매겨진다.

나누면 대가가 하나 생긴다. 순서가 보장되는 범위가 파티션 안까지로 줄어든다. 같은 토픽에 발행한 두 레코드가 서로 다른 파티션에 들어가면 어느 쪽이 먼저 처리될지 정해지지 않는다.

프로듀서가 레코드에 키를 붙이면 같은 키는 같은 파티션으로 가고, 그 범위 안에서는 순서가 지켜진다. 이 클러스터의 발행 키는 requestId 이고, 선언에 적어 둔 이유는 "전역 순서는 포기하고 키 단위 순서만 지킨다" 다.

선언해 둔 값

KafkaTopic CR 로 선언한 토픽 5종 중 앱이 주고받는 3종은 파티션 4다. 격리용 admissions.DLT·admissions-revoked.DLT 는 1이다.

4로 정한 근거는 선언에 두 줄로 적혀 있다. 파티션은 늘리는 것만 되고 줄이는 것은 안 되므로 나중에 모자라지 않을 값으로 잡았다는 것("파티션은 늘리기만 가능(줄이기 불가)라 넉넉히 4"), 그리고 앱 HPA 상한과 맞춘 값이라는 것("partitions 4 = 앱 HPA 상한과 짝 — 한 그룹의 동시 소비 파드는 파티션 수를 넘지 못한다")이다.

뒤쪽 제약이 어디서 나오는지는 컨슈머 그룹을 다루는 다음 절에 있다. DLT 를 1로 둔 근거는 "소비자가 없고 사후 조사용이라 병렬성이 필요 없다" 로 적혀 있다.

브로커는 노드가 아니라 파드다

이 클러스터의 브로커는 파드 cgv-cgv-pool-0/1/2 셋이다. 노드(k3s-1/2/3)와 수가 같고 노드마다 하나씩 있어서 브로커와 노드가 같은 것으로 읽히지만, 그 배치는 두 가지가 만든 결과다.

podAntiAffinity 를 requiredDuringScheduling, topologyKey 를 kubernetes.io/hostname 으로 선언해 한 노드에 브로커 파드를 두 개 두지 않는다
저장소가 노드마다 하나씩 있는 정적 로컬 PV(local-kafkadata 10Gi)라, 그 PV 를 쓰는 파드는 그 노드에 고정된다

브로커 수를 늘리려면 노드와 PV 를 먼저 늘리게 된다. 조회 출력에 나오는 숫자 0·1·2 는 노드 번호가 아니라 브로커 ID 이고, 파드 이름 끝 숫자가 그 ID 다.

사본이 한 벌일 때 브로커 한 대가 내려간다

파티션 1개. 로그 파일이 하나뿐이라 브로커 한 대의 디스크에만 있다. 평소 발행도 소비도 그 한 대가 받고 남은 두 대는 이 토픽에 대해 아무 요청도 받지 않는다. 그 한 대가 내려가면 토픽 전체가 멈춘다. 디스크가 손상되면 그때까지 적힌 레코드는 돌아오지 않는다.

파티션 4개. 4개가 브로커 3대에 나뉘므로 한 대가 두 개를 맡는다. 평소 3대가 전부 요청을 받는다. 한 대가 내려가면 그 대가 맡던 파티션만 멈추고 나머지는 계속 받는다. 내려간 대가 무엇을 맡았느냐에 따라 4개 중 1개 또는 2개가 멈춘다.

나누면 평소 요청을 받는 브로커 수가 늘고, 한 대가 내려갈 때 멈추는 범위가 줄어든다. 줄어들 뿐 없어지지는 않는다. 몇 개로 나누든 파티션 하나의 로그는 여전히 브로커 한 대에만 있다.

6. 같은 파티션을 여러 브로커에 둔다 — 복제·RF·리더

파티션 하나의 로그가 브로커 한 대에만 있으면 그 브로커가 내려간 동안 그 파티션이 멈추고, 디스크가 손상되면 적힌 레코드가 돌아오지 않는다.

복제(replication)는 같은 파티션의 로그를 여러 브로커에 사본으로 두는 것이다. 사본 개수가 복제 계수(replication factor, RF)이고, 사본이 하나뿐인 구성이 RF 1 이다.

사본이 여럿이면 다음 문제가 따라온다. 프로듀서가 쓸 때, 컨슈머가 읽을 때 어디로 가는가. 셋 다 쓰기를 받으면 셋의 로그가 갈라진다. 그래서 파티션마다 사본 하나를 리더(leader)로 정하고 나머지를 팔로워(follower)로 둔다. 프로듀서와 컨슈머는 리더에만 붙고, 팔로워는 리더가 적은 것을 복사해 올 뿐 클라이언트 요청을 받지 않는다. 리더가 내려가면 팔로워 중 하나가 리더가 되어 요청을 이어받는다.

RF 는 브로커 수를 넘을 수 없다. 같은 파티션의 사본 둘을 한 브로커에 두면 그 브로커가 내려갈 때 둘이 함께 사라져 복제한 것이 되지 않으므로, 사본은 서로 다른 브로커에 배치된다. 브로커 3대인 이 클러스터에서 선언할 수 있는 최대 RF 는 3이고, 토픽 5종 전부 RF 3 으로 선언해 뒀다.

사본이 세 벌일 때 브로커 한 대가 내려간다

파티션 1개 · RF 3. 브로커 3대가 같은 로그를 하나씩 갖는다. 그중 리더는 한 대뿐이다. 평소 요청은 전부 그 한 대로 가고 나머지 두 대는 복사만 받는다. 한 대가 내려갈 때 결과는 그 대가 리더였는지로 갈린다. 팔로워였으면 요청 흐름이 그대로고, 리더였으면 남은 사본 중 하나가 리더가 되어 요청을 이어받는다. 어느 쪽이든 레코드는 남고, 어느 쪽이든 그 뒤에도 요청을 받는 것은 한 대다.

파티션 4개 · RF 3. 사본이 12개이고 브로커가 3대라 모든 브로커가 4개 파티션의 사본을 전부 갖는다. 갈리는 것은 리더 자리다. 리더가 파티션마다 다른 브로커에 있어서 평소 3대가 모두 요청을 받는다. 한 대가 내려가면 그 대가 리더였던 파티션만 리더가 바뀐다. 멈추는 파티션도 없고 잃는 레코드도 없다.

세 대가 다 갖고 있는데 왜 넷으로 나누나

설정을 다시 읽을 때 여기서 막혔다. 브로커가 3대이고 RF 3 이면 세 대가 같은 데이터를 전부 갖는다. 그러면 어느 대에 요청해도 답이 나올 텐데, 토픽을 파티션 넷으로 나눌 이유가 무엇인가.

답은 리더의 정의에 있다. 사본을 갖고 있다는 것과 요청을 받는다는 것이 다르다. 팔로워는 같은 데이터를 갖고도 클라이언트 요청을 받지 않는다. 파티션 1개에 RF 3 이면 브로커 3대가 같은 데이터를 갖지만 리더는 그중 1대뿐이고, 프로듀서와 컨슈머는 그 1대에만 붙는다. 남은 2대는 복제만 한다.

요청이 갈리는 것은 사본이 흩어져서가 아니라 리가 흩어져서다. 리더는 파티션마다 하나이므로, 리더가 여럿이 되려면 파티션이 여럿이어야 한다.

RF        사본이 몇 개인지를 정한다      →  잃지 않게 한다
파티션 수  리더가 몇 개인지를 정한다      →  일이 갈리게 한다

조회 출력에서 이것을 읽는다

kubectl -n data exec cgv-cgv-pool-0 -- \
  bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic admissions

Topic: admissions  PartitionCount: 4  ReplicationFactor: 3
  Configs: min.insync.replicas=2, retention.ms=259200000, retention.bytes=2147483648, segment.ms=86400000
   Partition: 0  Leader: 1  Replicas: 1,2,0  Isr: 0,1,2
   Partition: 1  Leader: 2  Replicas: 2,0,1  Isr: 0,1,2
   Partition: 2  Leader: 0  Replicas: 0,1,2  Isr: 0,1,2
   Partition: 3  Leader: 0  Replicas: 0,1,2  Isr: 0,1,2

Replicas 열부터 본다. 네 줄 모두 0, 1, 2 가 다 들어 있다. 파티션 4개가 각각 브로커 3대 전부에 사본을 두고 있고, 저장된 데이터만 놓고 보면 세 브로커의 내용은 같다.

갈리는 것은 Leader 열이다. 파티션 0의 리더는 브로커 1, 파티션 1은 브로커 2, 파티션 2와 3은 브로커 0이다. 프로듀서가 파티션 0으로 보내는 레코드는 브로커 1로, 파티션 1로 보내는 레코드는 브로커 2로 간다.

같은 출력을 배치로 그리면 두 열이 무엇을 정하는지가 한 장에 들어간다.

                브로커0        브로커1        브로커2
                (k3s-1)       (k3s-2)       (k3s-3)

   파티션0          사본          ★리더          사본
   파티션1          사본           사본         ★리더
   파티션2         ★리더           사본          사본
   파티션3         ★리더           사본          사본

   ── 가로로 읽으면 ──  한 파티션이 세 브로커에 다 있다   →  RF 3.  잃지 않는다
   ── 세로로 읽으면 ──  ★가 세 브로커에 흩어져 있다      →  파티션 4.  일이 갈린다

파티션을 1로 뒀다면 이 그림에 줄이 하나뿐이고 ★도 하나다. 사본 칸은 그때도 세 개 그대로다. 데이터가 3대에 있는 것은 RF 가 만들고, ★가 3대에 흩어지는 것은 파티션 수가 만든다.

리더가 3등분되지는 않았다. 브로커 0이 파티션 2개, 브로커 1과 2가 각각 1개다. 4를 3으로 나누면 2+1+1 이 최선이다. 이 배치는 조회한 시점의 상태이고, 브로커가 내려갔다 올라오면 리더가 다른 사본으로 옮겨간 상태가 될 수 있다.

파티션이 1개인 토픽에서는 이 배치가 한 줄로 끝난다. admissions.DLT 는 Replicas 가 1,2,0 이고 리더는 브로커 1 하나다. 브로커 0과 2는 이 토픽의 사본을 갖고 있지만 팔로워라서 클라이언트 요청을 받지 않는다.

ISR 과 min.insync.replicas

리더만 요청을 받는다는 것은 쓰기가 리더에 먼저 들어간다는 뜻이다. 리더가 레코드를 자기 로그에 덧붙인 직후, 팔로워가 아직 복제하기 전에 리더가 내려가면 남은 사본에는 그 레코드가 없다.

ISR(in-sync replicas)은 리더의 로그를 따라잡은 상태인 사본 목록이다. 위 출력의 Isr 열이 네 파티션 모두 0,1,2 인 것은 그 시점에 사본 3개가 전부 따라잡았다는 뜻이다. 복제가 늦어지면 그 사본은 ISR 에서 빠지고 숫자가 줄어든다. Replicas 는 사본이 어디에 배치되어 있는지를, Isr 은 그중 지금 따라잡고 있는 것이 어느 것인지를 나타낸다.

min.insync.replicas 는 쓰기를 성공으로 처리하는 데 필요한 ISR 최소 개수다. 선언해 둔 값은 2다.

RF 3 · min.insync.replicas 2

브로커 3대 정상  →  ISR 3  →  쓰기 성공
브로커 1대 다운  →  ISR 2  →  쓰기 성공
브로커 2대 다운  →  ISR 1  →  쓰기 거부. 읽기는 리더가 살아 있는 파티션에 대해 계속된다

선언에 적어 둔 "RF 3 = 브로커 하나 죽어도 유지" 가 이 조합이다. 2대가 내려간 상태에서 쓰기를 계속 받으면 사본 없이 한 브로커에만 있는 레코드가 생기므로, 그 상황에서는 받지 않고 멈추는 쪽으로 정해진다.

이 값은 프로듀서가 acks=all 로 보낼 때 적용된다. queue 와 booking 의 acks 설정은 조회하지 않았다.

7. 누가 무엇을 읽는가 — 컨슈머 그룹

파티션 4개는 발행과 소비 요청을 브로커 세 대로 갈라 놓았다. 갈라진 파티션을 누가 읽을지는 그것만으로 정해지지 않는다.

컨슈머는 파드가 아니다

컨슈머는 앱이 코드에서 만드는 카프카 클라이언트 객체다. "이 토픽을 읽겠다" 고 만든 연결 하나가 컨슈머 하나다.

// queue-go/kafka/kafka.go:221
r := kafkago.NewReader(kafkago.ReaderConfig{
    ...
    GroupID: "queue",
})

// booking/src/main/java/com/cgv/booking/kafka/AdmissionConsumer.java:37
@KafkaListener(topics = "admissions")

// booking/src/main/java/com/cgv/booking/kafka/AdmissionExpiryConsumer.java:44
@KafkaListener(topics = "${cgv.admission-revoked.topic:admissions-revoked}")

queue 는 NewReader 를 한 번 호출하므로 파드 하나에 컨슈머가 하나다. booking 은 @KafkaListener 가 둘이라 파드 하나에 컨슈머가 둘이다. 파드 수와 컨슈머 수는 같을 수도 다를 수도 있다.

`group.id` — 카프카가 보는 유일한 이름표

컨슈머는 접속할 때 문자열 하나를 함께 보낸다. 그것이 group.id 다. 위 코드의 GroupID: "queue" 가 그 값이고, booking 은 application.yml 한 곳에 적어 두 리스너가 같이 쓴다.

# booking/src/main/resources/application.yml:53
group-id: booking

카프카는 파드가 무엇인지 모른다. 어느 노드에 있는지, 같은 앱인지도 모른다. 아는 것은 "이 문자열을 달고 접속한 연결이 몇 개인가" 뿐이다. 문자열이 같으면 한 묶음(컨슈머 그룹)으로 보고 파티션을 나눠 주고, 다르면 서로 없는 것처럼 각자 전부 읽게 한다.

배정 규칙은 한 방향으로만 걸린다

파티션 하나  →  컨슈머 하나에게만      (파티션 하나를 둘이 나눠 갖는 것은 안 된다)
컨슈머 하나  →  파티션 여러 개 가능

앞 줄이 없으면 같은 레코드를 둘이 읽어 두 번 처리한다. bookings-completed 의 예매 완료 레코드가 두 번 처리되면 정원을 두 번 반환한다.

뒷 줄은 제한이 없다. 컨슈머가 파티션보다 적으면 하나가 여러 개를 맡는다.

조회한 두 가지 상태

kubectl -n data exec cgv-cgv-pool-0 -- \
  bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group queue

TOPIC               PARTITION  CONSUMER-ID
bookings-completed  0          queue-...-4826t
bookings-completed  1          queue-...-4826t
bookings-completed  2          queue-...-gtm24
bookings-completed  3          queue-...-gtm24

queue 는 파드 2대이고 각 파드가 컨슈머를 하나씩 만들었다. 그룹 멤버가 2개라 파티션 4개가 2개씩 나뉘었다. CONSUMER-ID 끝의 문자열이 파드 이름 뒤쪽과 같다.

... --describe --group booking

TOPIC               PARTITION  CONSUMER-ID
admissions          0          consumer-booking-1-5ffe...
admissions          1          consumer-booking-1-5ffe...
admissions          2          consumer-booking-1-5ffe...
admissions          3          consumer-booking-1-5ffe...
admissions-revoked  0          consumer-booking-2-9dfe...
admissions-revoked  1          consumer-booking-2-9dfe...
admissions-revoked  2          consumer-booking-2-9dfe...
admissions-revoked  3          consumer-booking-2-9dfe...

booking 은 파드 1대인데 CONSUMER-ID 가 둘로 갈린다. 파드가 2대여서가 아니라 리스너가 둘이라 컨슈머가 둘이다. 배정은 (그룹, 토픽, 파티션) 단위로 계산되므로 구독한 토픽이 다른 두 컨슈머는 서로 겹치지 않고 각자 4파티션을 전부 맡는다.

admissions 쪽은 컨슈머 하나가 파티션 4개를 맡은 상태다. 리더가 파티션0→브로커1, 파티션1→브로커2, 파티션2·3→브로커0 에 흩어져 있어 이 컨슈머 하나가 브로커 3대에 붙는다.

컨슈머가 늘거나 줄면 다시 배정한다

그룹에 컨슈머가 들어오거나 나가면 브로커가 배정을 다시 계산해 전체에 통보한다. 이것을 리밸런스라 한다.

파티션 4 개는 그대로 두고 컨슈머 수만 바꾸면

컨슈머 1개    컨슈머1 : 파티션 0,1,2,3

컨슈머 2개    컨슈머1 : 파티션 0,1        컨슈머2 : 파티션 2,3      ← queue 의 현재 상태

컨슈머 4개    컨슈머1 : 파티션 0     컨슈머2 : 파티션 1
              컨슈머3 : 파티션 2     컨슈머4 : 파티션 3

컨슈머 5개    위와 같고,  컨슈머5 : 배정 없음

앱 설정에 적는 것은 group.id 와 구독할 토픽 이름뿐이다. 어느 파티션을 읽으라는 지정은 코드에 없다. HPA 가 파드를 늘리면 컨슈머가 늘고, 그때마다 리밸런스가 돌아 배정표가 다시 만들어진다.

배정이 정해지면 각 컨슈머는 자기가 맡은 파티션의 리더 브로커에 붙는다. bookings-completed 의 리더는 파티션0→브로커0, 파티션1→브로커1, 파티션2→브로커2, 파티션3→브로커0 이라, 파티션 0·1 을 맡은 4826t 는 브로커 0·1 에, 파티션 2·3 을 맡은 gtm24 는 브로커 2·0 에 붙는다.

리밸런스가 도는 동안 소비가 잠시 멈춘다. 멈추는 범위가 그룹 전체인지 옮겨 가는 파티션에 한정되는지는 클라이언트가 쓰는 배정 전략에 달려 있고, 이 앱들의 전략은 조회하지 않았다.

읽은 위치도 `group.id` 로 저장된다

컨슈머가 재시작하면 "어디까지 읽었는지" 를 잃는다. 그 값을 컨슈머 안에 두면 새로 뜬 컨슈머는 처음부터 다시 읽거나(중복) 지금 들어오는 것부터 읽는다(유실).

그래서 카프카는 그 위치를 브로커의 내부 토픽 __consumer_offsets 에 적고, 키를 (group.id, 토픽, 파티션) 으로 잡는다. 파드 이름도 컨슈머 식별자도 키에 안 들어간다.

("queue", "bookings-completed", 0)  →  80

파드가 교체돼도 값은 브로커에 남는다. 리밸런스로 그 파티션을 새로 받은 컨슈머가 같은 group.id 로 접속하면 80 다음부터 이어 읽는다. 마지막 커밋 이후에 처리한 레코드는 다시 읽는다.

같은 조회의 오프셋 컬럼이 그 값이다.

PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG
0          80              80              0
1          -               0               -
2          11              11              0
3          2               2               0

CURRENT-OFFSET 은 커밋된 위치, LOG-END-OFFSET 은 다음 레코드가 붙을 위치, LAG 은 그 차이다. 네 파티션 모두 밀린 것이 없다. 파티션1 은 LOG-END-OFFSET 이 0 이라 들어온 레코드가 없고 커밋한 적도 없어 나머지 두 값이 - 다.

읽은 양은 파티션0 이 80, 파티션2 가 11, 파티션3 이 2 로 고르지 않다. 배정이 균등한 것과 부하가 균등한 것은 별개다. 발행 키에 따라 특정 파티션으로 몰리면 그 파티션을 맡은 컨슈머가 더 일한다.

파티션 수가 상한이 되는 자리

파티션 하나는 컨슈머 하나에게만 간다. 뒤집으면 동시에 읽을 수 있는 컨슈머 수의 상한이 파티션 수다. bookings-completed 는 파티션 4 이므로 queue 파드를 5대로 올리면 다섯 번째 컨슈머는 배정받을 파티션이 없어 그룹에 들어가 있기만 하고 아무것도 읽지 않는다.

같아야 하는 것은 아니다. 컨슈머가 파티션보다 적으면 하나가 여러 개를 맡을 뿐이고, 같을 때가 파티션을 남김없이 쓰는 지점이다.

정하는 순서는 파티션이 먼저다. 파티션은 늘리기만 되고 줄일 수 없어 나중에 모자라지 않을 값으로 잡고, 그 값이 소비 컨슈머의 천장이 된다.

queue 의 HPA 가 min 2 / max 4 인 것이 파티션 4에 맞춘 것이고, 저장소 주석에도 "partitions 4 = 앱 HPA 상한과 짝" 으로 적혀 있다. HPA max 를 파티션 수보다 크게 잡으면 초과분은 자원만 차지한다.

booking 은 replicas 1 이고 HPA 를 붙이지 않았다. 스키마 마이그레이션 도구가 없어 여러 대가 같은 스키마를 건드리면 충돌하기 때문이다. 파티션이 4 라서 못 늘리는 것이 아니라, 파티션 쪽은 4대까지 여유가 있는데 앱 쪽 제약으로 1대에 묶여 있다.

8. 여기까지의 정리

	푸는 것	못 푸는 것
파티션	요청이 브로커 한 대에 쏠리는 것, 컨슈머를 여러 대로 늘리는 것	데이터 유실
복제(RF)	데이터 유실	요청 쏠림 — 사본은 클라이언트를 안 받는다
리더	그 파티션의 일을 어느 브로커가 할지	—
컨슈머 그룹	같은 레코드를 여러 컨슈머가 중복 처리하는 것	파티션 수를 넘는 병렬성

낱말이 겹쳐 헷갈리는 다섯 자리

이렇게 읽기 쉽다	실제
브로커 = 노드	브로커는 파드다. 노드당 하나로 배치했을 뿐이다
컨슈머 = 파드	컨슈머는 앱이 코드에서 만든 객체다. 파드 하나에 여러 개일 수 있다
리더는 브로커의 성질	파티션의 성질이다. 같은 브로커가 어떤 파티션의 리더이면서 다른 파티션의 팔로워다
사본을 가지면 요청도 받는다	팔로워는 같은 데이터를 갖고도 요청을 받지 않는다
컨슈머 수 = 파티션 수	≤ 다. 적으면 하나가 여럿을 맡고, 넘으면 남는 컨슈머가 논다

숫자를 정하는 순서

잃지 않는 쪽    노드 수  →  브로커 ≤ 노드  →  RF ≤ 브로커
일을 나누는 쪽  그 토픽을 읽을 파드 수  →  파티션 ≥ 그 수  →  HPA max ≤ 파티션

두 사슬이 따로 시작한다. 브로커 3과 파티션 4가 가까운 숫자인 것은 우연이다.

9. 카프카를 세우는 것은 Strimzi 다

카프카를 쿠버네티스에 직접 세우려면 브로커를 서로 다른 노드에 띄우고, 디스크를 붙이고, 서로를 찾을 주소를 설정하고, 브로커 간 통신용 인증서를 만들어 나눠 주고, 한 대가 죽으면 같은 디스크로 다시 띄우는 일을 전부 손으로 써야 한다.

그 일을 대신 하도록 만들어 둔 프로그램이 Strimzi 다. 카프카를 쿠버네티스에서 운영하려고 오픈소스로 공개해 둔 것이고, strimzi.io 가 차트로 배포한다.

이런 프로그램을 오퍼레이터라 부른다. 선언을 지켜보다가 실물을 그 선언에 맞춰 놓는다.

들여오는 방법 — Helm 차트

# bootstrap/install.sh
helm repo add strimzi https://strimzi.io/charts
helm upgrade --install strimzi strimzi/strimzi-kafka-operator -n data \
  --version 1.1.0 -f strimzi/values.yaml

Helm 차트와 오퍼레이터는 층이 다른 말이다. 차트는 설치 방법이고 오퍼레이터는 설치된 프로그램의 종류다. 매니페스트를 직접 kubectl apply 해도 결과는 같다.

설치하면 들어오는 것 둘

CRD 10종. 쿠버네티스에 새 객체 종류를 등록한다. kafkas·kafkanodepools·kafkatopics·strimzipodsets 등이다. 이것이 없으면 kind: Kafka 라고 적은 파일을 API 서버가 "그런 종류를 모른다" 며 거부한다. CRD 가 그 종류의 문법(어떤 필드가 올 수 있는지)을 정하고, 그 문법대로 값을 채워 내가 쓰는 파일이 CR 이다.

오퍼레이터 파드 하나. strimzi-cluster-operator 다. 감시 범위는 STRIMZI_NAMESPACE=data 로 data 네임스페이스 하나다.

어떻게 동작하나

kafka-cluster.yaml  ·  kafka-topics.yaml
        │  kubectl apply
        ▼
API 서버에 CR 로 저장된다        ← 이 시점에는 아직 브로커가 없다
        │  watch
        ▼
strimzi-cluster-operator 가 알림을 받는다
        │
        ├─ 선언과 실물을 비교한다
        └─ 다르면 메운다 : 파드·Service·ConfigMap·Secret·NetworkPolicy·PVC 를 만들거나 고친다
        │
        └─ 그리고 2분마다 전체를 다시 비교한다
             (STRIMZI_FULL_RECONCILIATION_INTERVAL_MS=120000)

CR 은 주문서일 뿐 그 자체로는 아무것도 안 한다. 오퍼레이터가 읽고 실물을 만들어야 브로커가 선다. 그래서 손으로 쓴 것은 아래 두 파일이 전부다.

workloads/manifests/kafka/
  kafka-cluster.yaml   Kafka(버전·리스너·브로커 기본값) · KafkaNodePool(브로커 3대, 역할, 저장소)
  kafka-topics.yaml    KafkaTopic 5종(파티션·RF·보존)
        ▼
  브로커 파드 3 · StrimziPodSet · Service 2 · ConfigMap 5
  · Secret 11(인증서) · NetworkPolicy 2 · PVC 3 · entity-operator

이 구조가 해 주는 것

브로커가 죽으면 같은 디스크로 다시 띄운다. 어느 노드에 어느 볼륨을 물릴지를 오퍼레이터가 들고 있다.
선언을 고치면 실물이 따라온다. kafka-topics.yaml 의 파티션을 4에서 6으로 바꾸면 실제 토픽도 6이 된다.
인증서를 손으로 안 만든다. 클라이언트 리스너는 tls: false 라 평문인데 브로커 간 복제와 오퍼레이터 통로는 TLS 를 쓴다. 그 CA 와 인증서 11종을 Strimzi 가 만들어 배포해 둔다.

대가 — 만든 쪽이 계속 지킨다

같은 동작이 반대로도 작용한다. Strimzi 가 만든 객체를 손으로 고치면 다음 조정에서 되돌아간다. 늦어도 2분이다.

그 객체 중에 NetworkPolicy 가 있다. cgv-network-policy-kafka 가 브로커 앞에 서 있고, 이번 작업에서 좁혀야 하는 9092 규칙이 거기 들어 있다. 정책 파일을 새로 쓰는 방식이 카프카에만 안 통하는 이유가 이것이다.

10. 브로커가 여는 포트 넷

kubectl -n data get pod cgv-cgv-pool-0 \
  -o jsonpath='{range .spec.containers[*].ports[*]}{.name}{"="}{.containerPort}{"\n"}{end}'

tcp-kafkaagent=8443
tcp-ctrlplane=9090
tcp-replication=9091
tcp-clients=9092

IP 하나에 번호 넷이다. 포트는 한 IP 안에서 어느 프로그램이 받을지를 가르는 번호이고, 같은 브로커 프로세스가 용도별로 나눠 열었다.

포트	무엇이 오나	붙는 쪽
9092	발행·소비	`app` 의 queue · booking
9091	브로커 간 복제	브로커끼리, `data` 의 entity-operator
9090	컨트롤러 합의(KRaft)	브로커끼리
8443	브로커 상태 조회	strimzi-cluster-operator

9091 에 entity-operator 가 들어가는 것은 Strimzi 가 만든 정책이 그렇게 적고 있어 확인된다. cgv-network-policy-kafka 의 9091 규칙 출처에 strimzi.io/name: cgv-entity-operator 가 들어 있다. KafkaTopic 선언을 실제 토픽으로 반영하려면 이 경로가 필요하다.

9092 만 출처가 data 밖에 있다. 나머지 셋의 출처는 브로커 자신과 data 안의 오퍼레이터라, app 을 상대로 좁혀도 끊기는 것이 없다.

그리고 9092 는 브로커 3대 전부에 열어야 한다. 클라이언트는 cgv-kafka-bootstrap 으로 아무 브로커에나 붙어 파티션별 리더 목록을 받은 뒤 각 파티션의 리더에 직접 접속한다. 부트스트랩 주소로 지정한 브로커가 계속 중계하지 않는다. 리더가 3대에 흩어져 있으므로 한 대만 열면 그 브로커가 리더인 파티션만 쓸 수 있다.

11. 규칙을 적는 자리가 파드마다 다르다

11부에서 data 로 들어오는 접속을 좁히는 작업은 대상마다 적는 자리가 다르다. 같은 네임스페이스 안인데 세 갈래가 된다.

기준은 하나다 — 그 파드 앞에 이미 정책이 서 있는가, 그리고 그것을 만든 쪽이 계속 지키는가.

대상 파드	이미 서 있는 정책	만든 것	좁히는 자리
MySQL · Redis	`mysql` · `redis`	Helm 차트	차트 `values.yaml` 로 끄고 정책 파일을 쓴다
Kafka 브로커	`cgv-network-policy-kafka`	Strimzi 오퍼레이터	Kafka CR 의 리스너에 적는다
strimzi-cluster-operator	없다	—	정책 파일을 쓴다

왜 브로커만 CR 인가

브로커 앞의 정책은 오퍼레이터가 만든 것이고, 오퍼레이터는 2분마다 선언과 실물을 다시 맞춘다. 그래서 두 방식이 다 막힌다.

정책 파일을 새로 써서 더한다
   → 같은 파드를 고르는 정책이 여럿이면 허용이 합쳐진다
   → 출처가 빈 9092 규칙이 남아 있는 한 그 포트는 열린 채로 있다

Strimzi 정책을 지운다
   → 다음 조정에서 CR 에 적힌 대로 다시 만들어진다

그래서 오퍼레이터가 읽는 자리를 고친다.

리스너에 networkPolicyPeers 를 적으면 오퍼레이터가 그것을 읽고 cgv-network-policy-kafka 의 9092 규칙에 from 절을 넣어 재생성한다.

# workloads/manifests/kafka/kafka-cluster.yaml
    listeners:
      - name: plain
        port: 9092
        type: internal
        tls: false
        networkPolicyPeers:
          - namespaceSelector: {matchLabels: {kubernetes.io/metadata.name: app}}
            podSelector: {matchLabels: {app.kubernetes.io/name: queue}}
          - namespaceSelector: {matchLabels: {kubernetes.io/metadata.name: app}}
            podSelector: {matchLabels: {app.kubernetes.io/name: booking}}

kafka-cluster.yaml 을 고친다
        │  ArgoCD 가 반영
        ▼
API 서버의 Kafka CR 이 바뀐다
        │  watch
        ▼
strimzi-cluster-operator 가 읽는다
        │
        ▼
cgv-network-policy-kafka 의 9092 규칙에 from 절이 들어간 채로 재생성된다
        │
        ▼
Calico 가 그 정책을 노드 iptables 규칙으로 옮긴다

정책 객체를 내가 만들지 않는다. 오퍼레이터에게 무엇을 만들지 알려 줄 뿐이다.

9090·9091·8443 은 Strimzi 가 이미 출처를 파드 셀렉터로 지정해 두었으므로 이번에 적을 것이 없다.

클러스터 오퍼레이터는 제한하려는 대상이 아니다

브로커 쪽은 그것으로 끝나는데, 같은 네임스페이스에 정책이 하나도 안 걸린 파드가 하나 남는다. strimzi-cluster-operator 다. Strimzi 는 자기가 만드는 것들(브로커·entity-operator)에는 정책을 붙였지만 자기 자신에게는 안 붙였다.

이 파드에 정책을 쓰는 것은 좁히려는 것이 아니라 default-deny-ingress 가 휩쓴 것을 되돌리는 것이다.

1  mysql·redis·브로커를 좁히려면 default-deny 가 필요하다
      정책이 안 고른 파드는 전부 열려 있으므로, 일단 다 고르고 필요한 것만 다시 연다
2  default-deny 는 podSelector: {} — data 의 파드를 전부 고른다
3  아무 정책도 없던 strimzi-cluster-operator 가 여기서 처음 선택된다
4  그 순간 이 파드로 들어오는 것이 전부 막힌다
5  kubelet 이 노드 주소에서 보내는 8080 상태 검사도 막힌다
6  liveness 실패 → 재시작 → 또 실패 → 반복 → 카프카 조정이 멈춘다

되돌릴 것이 8080 하나뿐인 이유

오퍼레이터는 거의 다 나가는 쪽으로 일한다.

나가는 쪽    API 서버를 지켜본다(watch) · 브로커에 8443 으로 상태를 묻는다
             객체를 만들고 고친다

들어오는 쪽   kubelet 의 상태 검사 8080        ← 이것 하나뿐

브로커는 앱이 붙고 브로커끼리 붙고 오퍼레이터가 붙어서 포트가 넷인데, 오퍼레이터는 받는 것이 하나다. 그래서 되돌릴 규칙도 한 줄로 끝난다.

# workloads/manifests/netpol/data-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: strimzi-operator-probe
  namespace: data
spec:
  podSelector:
    matchLabels:
      strimzi.io/kind: cluster-operator     # 이 라벨을 단 파드가 대상
  policyTypes: [Ingress]                    # 나가는 쪽은 손대지 않는다
  ingress:
    - from:                                 # 원소 3개 = OR
        - ipBlock: {cidr: 192.168.0.201/32}
        - ipBlock: {cidr: 192.168.0.202/32}
        - ipBlock: {cidr: 192.168.0.203/32}
      ports:
        - port: 8080                        # from 과 AND

여는 범위는 "노드 3대에서 8080 으로 오는 것" 하나다.

노드 .201 → 8080     통과
노드 .202 → 8080     통과
노드 .203 → 8080     통과

노드 .201 → 다른 포트   막힘      포트가 다르다
파드      → 8080       막힘      출처가 노드가 아니다

/32 는 그 IP 하나만이라는 뜻이고, kubelet 은 파드가 아니라 노드에서 도는 프로세스라 라벨로 못 고른다. 그래서 노드 주소를 직접 적는다.

policyTypes 에 Ingress 만 적어서 나가는 쪽은 그대로 열려 있다. 나가는 쪽까지 막았으면 8080 을 열어 줘도 오퍼레이터는 API 서버를 못 보고 브로커에 못 붙어 아무 일도 못 한다.

여기는 CR 이 아니라 정책 파일인 이유

브로커 앞의 정책은 Strimzi 가 만들고 2분마다 다시 맞춘다. 그래서 CR 을 고쳐야 했다. 클러스터 오퍼레이터 앞에는 그 정책을 만든 쪽도, 지키는 쪽도 없다. 내가 쓴 파일이 되돌아갈 일이 없다.

data-ingress.yaml 을 쓴다
        │  ArgoCD 가 반영
        ▼
API 서버에 NetworkPolicy 객체가 저장된다     ← 오퍼레이터는 관여하지 않는다
        │
        ▼
Calico 가 노드 iptables 규칙으로 옮긴다

	이미 있는 정책	지키는 쪽	적는 자리
브로커	`cgv-network-policy-kafka`	Strimzi	Kafka CR
entity-operator	`cgv-entity-operator`	Strimzi	이번에 안 건드린다
클러스터 오퍼레이터	없음	없음	정책 파일

두 경로의 차이

정책 파일   내가 만든 객체를 Calico 가 집행한다
CR         오퍼레이터가 만든 객체를 Calico 가 집행한다

집행하는 쪽은 둘 다 Calico 로 같다. 갈리는 것은 그 객체를 누가 만들고 누가 계속 지키느냐다.

좁혀도 남는 것

리스너는 tls: false 에 인증 설정이 없다. 출처를 지정해도 저 두 라벨을 단 파드는 인증 없이 9092 에 붙는다. 라벨은 누구나 적을 수 있는 문자열이라 이 제한은 출처를 증명하지 않는다. 브로커 인증(SASL·mTLS)이나 메시지 서명은 이번에 하지 않는다.

노트북 홈서버 k3s 구축기 - 11. 앱 검증과 시뮬레이터

hsb_02 — Tue, 11 Aug 2026 21:52:31 +0900

시리즈 "노트북 홈서버 k3s 구축기" 11부.
지난 편까지 = 코드를 머지하면 사람 손 없이 3-4분 뒤 파드가 새 이미지로 돈다. 다만 그 파드 안의 앱을 브라우저에서 끝까지 태워본 적이 없다.
11부 = 앱. 어떻게 흐르는지 확인하고(E2E), 남에게 보여줄 시뮬레이터로 다시 만들고, 확인된 동작을 테스트 게이트로 남기고, LAN에 열기 전에 권한·통신을 조인다. 끝에서 이 앱이 돌아가는 판(가상 설정들)을 정리해 부하 실측으로 넘긴다.

0. 이어받기

이 시리즈는 노트북 한 대에서 시작했다. 1-5부가 물리 기반이고, 클러스터 인프라는 6부부터 쌓였다.

편	세운 것	남긴 상태
1-5	Proxmox + VM 3대(k3s-1·2·3) + 네트워크·용도별 디스크	노드 셋이 클러스터를 받을 준비
6	k3s 3노드(embedded etcd) + 로컬 PV	쿠버네티스가 섰다
7	GitOps 부트스트랩 — ArgoCD가 App 21개를 git에서 세움	git에 적힌 대로 클러스터가 맞춰진다
8	LGTM 관측 스택(분산 모드) 개통 + 관측 스택 자기 계기판	인프라 신호가 흐르고 담긴다. 인프라 대시보드 본편·알림은 뒤 편으로 미뤄둠
9	GitLab 자가호스팅 + webhook	커밋이 3초 만에 클러스터에 반영된다
10	CI 게이트 10종 + 레지스트리 + image-updater	머지 → 3-4분 → 파드 교체. 사람 손은 머지 클릭까지

10부가 끝난 지금을 한 줄로 하면: 코드가 클러스터까지 가는 길은 전부 자동인데, 그 길 끝에서 도는 앱은 검증된 적이 없다.

파드 넷(queue×2·booking·frontend)은 Running이고, LAN의 LB 주소까지 뚫려 있다
그러나 대기열 입장→좌석 선점→예매 확정을 클러스터 위에서 끝까지 태워본 적이 없다 — 이 앱은 로컬 docker-compose에서 curl 왕복까지 확인하고 올라온 상태다
테스트는 0건이라 CI의 test 단계가 빈칸이고, 앱 관측은 코드에만 들어 있고, 화면은 남에게 보여줄 데모가 아니다

이 편이 그 간극을 메운다.

1  앱은 어떻게 흐르나            아키텍처 · queue · booking · 프론트 · E2E 검증
2  프론트 — 시뮬레이터로 다시    화면 구성 · 콘솔(투입·오픈·자동예매) · 백엔드 추가 셋
3  테스트                       API 목록 · 맞물리는 방식 · 거기서 나오는 불변식
4  파드 사이 접근 범위 좁히기     NetworkPolicy — 정원 통제를 건너뛰는 경로를 닫는다

5  대조 · 6  다음

값의 대장(무엇이 가상값인지, 설계 문서와 실물이 어디서 갈라졌는지)은 분량이 편 하나라 번외로 뺐다 — 12부·13부가 그 대장을 입력으로 쓴다.

stg/prd 관점에서 이 편의 자리: 부하 실측(13부)으로 배포 스펙을 산정하려면 측정 대상이 기능적으로 검증돼 있어야 하고, 측정 중 코드를 고칠 때 테스트 게이트가 있어야 한다. 여기서 만드는 시뮬레이터가 그대로 부하 시나리오의 재현 장치가 된다.

1. 앱은 어떻게 흐르나

왜 이 앱인가 — 사건에서 문제로

시작은 실제 사건이다. 2024년 프로야구가 사상 처음 천만 관중을 돌파했고, 직관 티켓은 전쟁이 됐다. 한국시리즈 예매에선 접속자 폭주로 예매 버튼이 활성화되지도 않은 채 대기 인원이 16만 명까지 불어났다(덴 매거진 보도). 좌석은 순식간에 동났고, 표를 못 구한 수요가 그만큼 남았다.

넘친 수요를 극장이 받았다. CGV가 KBO와 협약을 맺고 야구 생중계를 극장에서 상영하기 시작했다 — 그리고 그 극장 티켓팅마저 시작과 동시에 매진됐다. "경기장에 못 간 수요가 극장 예매로 몰린다"는 것은 가정이 아니라 이미 일어난 일이다.

이 프로젝트는 그 상황을 모델로 한다. 설정은 이렇다 — 2026년 KBO 올스타전 생중계를 CGV가 열고, 그 예매 시스템을 내가 만든다. 오픈 순간 몰릴 폭주를 받아내는 것이 과제다.

시드 데이터가 그 설정 그대로다: 상영물은 "2026 KBO 올스타전 생중계" 하나(18시), 지점 5 × 관 4 = 회차 20, 관당 200석 = 좌석 4,000. 한 상영물에 전원이 몰리는 구조 — 대기열이 필요한 바로 그 모양이다.

대비 없이 열면 서버 안에서 벌어질 일은 일반적인 경로로 재구성할 수 있다(실제 예매 서버들의 내부는 공개된 바 없다 — 추정의 영역이다). 오픈 순간 수만 명이 좌석 조회·선점·결제 API를 동시에 때린다. 이 구간은 잠금(같은 좌석은 한 명만)과 트랜잭션(돈과 좌석의 원자적 기록)이라 동시에 처리할 수 있는 양에 상한이 있다 — DB 커넥션 수, 잠금 경합, 커밋 디스크 속도가 그 상한을 정한다. 상한을 넘는 요청은 줄을 서는 게 아니라 타임아웃·에러로 튕기고, 그 실패가 재시도를 부르며 부하를 더 키운다. 결과: 전원이 실패하는 서버.

처리량 상한은 없앨 수 없다. 그래서 문제를 뒤집는다 — 상한 안의 인원만 안으로 들이고, 나머지는 밖에서 순번을 주며 세운다. 그 장치가 대기열이고, 이 앱은 그 구조를 직접 구현한 것이다.

아키텍처를 쌓아보기 — 요구가 구조를 정한다

완성된 그림을 외우는 대신, 요구를 하나씩 따라가며 쌓는다. 각 조각은 앞 요구의 결과다.

요구 1 — 문지기가 필요하다. 입장 인원을 정원으로 제한하는 서비스, 그게 queue다. 정원은 "예매 구간이 건강하게 처리할 수 있는 동시 인원"이고, 지금은 데모값 2 — 실값은 부하 실측으로 정한다.

요구 2 — 대기열의 상태는 파드 밖에 있어야 한다. "누가 입장했고 누가 몇 번째인가"를 파드 메모리에 두면 두 가지가 무너진다: 파드가 재시작하면 대기열이 증발하고, 파드가 둘이면 대기열도 둘이 된다. 그래서 상태를 Redis 한 곳에 몰고 파드는 무상태로 둔다 — 어느 파드가 받아도 같은 명부를 보고, 파드는 언제든 갈아 끼운다. Redis인 이유: 메모리라 폭주 속도를 받아내고, 명령을 한 줄로 세워 직렬 실행하는 성질이 "동시 요청의 경합"을 푸는 재료가 된다(뒤에 나온다).

요구 3 — 예매는 성격이 정반대다. 대기열은 "빠르고 가볍게, 잃어도 복구되는 상태"이고, 예매는 "느려도 정확하게, 영원히 남는 기록"이다. 한 서비스에 두면 폭주 트래픽이 트랜잭션과 커넥션을 두고 싸운다. 그래서 서비스를 가른다 — booking은 돈이 걸린 확정본만 MySQL에 남기고, 임시 상태(좌석 잠금·입장 인증)는 Redis에 TTL(수명)을 붙여 두어 결제가 끊겨도 저절로 소멸하게 한다.

요구 4 — 갈랐으면 직접 부르지 않는다. queue가 booking을 HTTP로 부르면, booking이 죽는 순간 queue도 응답을 기다리다 같이 밀린다 — 가른 의미가 없다. 그래서 둘 사이에 Kafka를 둔다: 보내는 쪽은 브로커에 메시지를 두고 제 갈 길을 가고, 받는 쪽은 제 속도로 꺼내 읽는다. 죽어 있던 동안의 메시지도 브로커에 남아 재기동 후 이어진다. 토픽 셋이 닫힌 순환을 이룬다 — 입장 승인(admissions), 입장 회수(admissions-revoked), 예매 완료에 따른 자리 반환(bookings-completed).

요구 5 — 브라우저 진입점. 화면은 정적 파일 세 개(HTML·JS·CSS)를 주는 frontend가 맡고, "어떤 경로를 어느 서비스로"는 클러스터의 Ingress(Traefik)가 맡는다.

쌓고 나면 이 모양이 된다.

        브라우저  http://192.168.0.240   ← MetalLB가 준 LB IP (LAN)
            │
        Traefik  (Ingress 3경로, 파드 2)
            │ /api/admission/*        │ 나머지 /api/*         │ /
            ▼                         ▼                      ▼
        ┌────────┐               ┌─────────┐            ┌──────────┐
        │ queue  │               │ booking │            │ frontend │
        │  (Go)  │               │ (Java)  │            │ (정적만)  │
        └─┬────┬─┘               └─┬─────┬─┘            └──────────┘
          │    │                   │     │
       Redis   │                   │   Redis (좌석락·admitted)
    (대기열 전부)│                   │   MySQL (확정 예매)
               │                   │
               └──── Kafka ────────┘
                admissions ─────────▶   (queue → booking : 입장 승인)
                admissions-revoked ─▶   (queue → booking : 입장 회수)
                ◀─ bookings-completed   (booking → queue : 자리 반환)

.240에 닿는 과정은 요청마다 이렇다: 같은 LAN이라 브라우저가 ".240 누구냐"(ARP)를 물으면 MetalLB가 노드 하나의 MAC으로 답해 패킷을 클러스터까지 실어 오고, Traefik이 요청의 경로 문자열을 보고 세 규칙 중 하나를 고른다. 세 경로가 한꺼번에 열리는 게 아니라 요청 하나가 가지 하나를 탄다 — 화면 한 번 로드에도 /(정적 파일)와 /api/movies(booking 왕복)가 따로 갈라져 들어간다. 이 배선의 원리(ARP·kube-proxy·Ingress의 층)는 9부에서 다뤘다.

queue — 입장 통제

enter ──정원 여유──▶ 200 ADMITTED ──────────────┐
  │                                            │ Kafka admissions
  └──정원 참──▶ 202 WAITING (순번)               ▼
        │                            booking이 admitted 키 발급
        │  순번 폴링(1/2/5초)
        ▼
   승격 루프(2초마다) ── 빈자리만큼 앞에서 꺼냄 ──▶ ADMITTED

   회수: 예매 완료 / 이탈(leave) / 세션 60초 초과  →  빈자리  →  다음 승격
   대기 이탈: 30초 안에 폴링 없으면 대기열에서 제거

Redis에 있는 것은 명부 두 장이다. 입장자 명부(active)와 대기 줄 명부(waiting — 들어온 순서가 곧 순번).

부속으로 대기자별 마지막 폴링 시각, 발행 대기 저널, 승격 누계(속도 계산 재료)가 같이 산다. queue 파드가 하는 일은 이 명부를 읽고 고치는 것뿐이라, 파드는 몇 개든 무상태다.

입장 판정은 Redis Lua 한 번이다. "정원 확인 → 입장 또는 대기 등록"이 원자(중간에 아무도 못 끼어드는 한 단위)로 끝난다. 확인과 등록을 따로 하면 그 틈에 다른 요청이 껴 정원을 넘긴다 — 파드가 여럿이라 앱 안의 잠금으로는 못 막고, Redis가 스크립트를 한 줄로 세워 직렬 실행하는 성질을 잠금으로 쓴다(요구 2에서 Redis를 고른 이유가 여기서 회수된다).
폴링이 곧 생존 신호다. 서버가 대기자에게 먼저 말을 걸 수단이 없다(연결을 안 붙잡는 폴링 설계 — 연결을 유지하는 방식은 파드 증설·재시작마다 끊긴 연결을 수습해야 한다). 대신 순번 응답을 주면서 마지막 폴링 시각을 찍고, 30초 안에 안 물은 대기자는 지운다 — 브라우저를 닫고 사라진 사람이 유령으로 남지 않게.
시계가 두 개다 — 헷갈리기 쉬운 지점. 대기 중엔 "30초 안에 폴링"(생존 신호가 기준), 입장 후엔 "60초 세션"(입장 시각이 기준 — 폴링해도 안 늘어난다). 대기열은 성실히 서 있으면 유지되고, 입장석은 시간이 되면 무조건 비워진다 — 자리를 잡고 뭉개는 사람이 뒤를 막지 않게.
발행 유실을 저널로 막는다. 입장·회수 사실은 Kafka로 booking에 가야 하는데, 상태 변경과 발행 사이에서 파드가 죽으면 통보가 유실된다 — 화면상 입장했는데 booking이 몰라 계속 403인 사용자가 생긴다. 그래서 상태 변경과 같은 Lua 안에서 "알릴 의무"를 발행 대기 저널에 기록하고, 발행이 끝나야 지운다. 스윕 루프(5초)가 남은 항목을 재발행한다. 같은 통보가 두 번 갈 수는 있는데 소비 쪽이 멱등(두 번 받아도 결과가 같음)이라 무해하다 — 중복은 흘리고 유실만 막는다.

booking — 게이트 뒤의 예매

정원의 주인은 queue 하나다. booking은 "지금 몇 명까지 받아도 되나"를 스스로 판단하지 않는다 — 판단 근거를 둘로 나누면 언젠가 서로 어긋난다.

booking이 믿는 것은 입장 인증 키(admitted:{movie}:{requestId}) 하나뿐이고, 그 키의 수명은 queue가 보내는 이벤트가 관리한다: 승격되면 발급(admissions 수신), 자리를 잃으면 삭제(revoked 수신), 예매가 확정되면 소진. 키에 TTL 180초를 붙여 두는 것은 최후 방어다 — 회수 이벤트가 유실돼도 인증이 영원히 남지는 않게. 게이트를 안 거친 요청은 회차 목록부터 확정까지 어디서도 403이다.

좌석은 상태가 셋이다.

빈자리      어느 쪽에도 없음
임시점유    Redis  SET NX, TTL 45초   ← 결제 안 끝내면 자동으로 풀림
판매완료    MySQL  booking_seats 행    ← 영구. 화면의 taken = 판매완료 ∪ 임시점유

"임시"와 "영구"를 저장소부터 갈라놓은 배치다 — 좌석을 고르다 떠난 사람의 흔적은 TTL이 지우고, 돈이 오간 확정만 DB에 남는다.

확정(POST /api/bookings)은 순서가 고정돼 있다: 멱등키 확인 → 게이트 → 좌석 실재·판매 확인 → 락 연장 → PG 승인(mock) → MySQL 트랜잭션 → 커밋 후 후처리(락 해제·완료 발행·인증 소진). 멱등키는 "이 요청은 아까 보낸 그 요청과 같은 것"이라는 표식이다 — 더블클릭·응답 유실 재시도가 두 번 결제로 이어지지 않게, 같은 키가 다시 오면 저장해 둔 결과를 그대로 돌려준다.

멱등키 확인이 게이트보다 앞인 데 이유가 있다 — 결제까지 끝났는데 응답만 유실된 사용자가 재시도했을 때, 그 사이 세션이 만료됐다는 이유로 403에 막히면 돈은 빠졌는데 예매번호를 영영 못 받는다.

이중판매는 세 겹으로 막는다. 락은 필터고 UNIQUE가 보증이다.

겹	수단	성격
1차 필터	Redis 좌석락(SET NX)	대부분을 입구에서 차단. TTL 만료·장애 전환에 뚫릴 수 있음
판매 확인	MySQL 조회	확정 직후엔 락이 없어서, 팔린 좌석은 여기서 걸러짐
최종 보증	MySQL UNIQUE(회차, 좌석)	위가 다 뚫려도 커밋 순간 한쪽만 이김. 진 쪽은 롤백+환불

프론트 — 클라이언트가 계약의 반쪽이다

[로그인: requestId 발급(localStorage)]
    │
 movies ──클릭·enter──▶ waiting ──ADMITTED 발견──▶ entering ──▶ screenings ──▶ seats ──▶ pay ──▶ done
    ▲                  (순번 폴링)                 (전환 유예)
    └──────── EXPIRED(만료·이탈) / 홈·뒤로 ──────────┘

서버는 사용자에게 먼저 말을 걸지 않고(폴링 — push 없음), 사용자별 세션도 파드에 들고 있지 않다(무상태). 그 결과 신원 만들기, 물어보는 박자, 떠날 때 뒷정리가 전부 클라이언트로 넘어온다 — 서버 설계의 반쪽이 프론트에 구현돼 있는 셈이다. 프론트를 다시 만들 때 아래 여섯 줄이 빠지면 백엔드 설계가 반쪽이 된다.

몫	구현
신원	requestId = 자가발급 UUID(localStorage). 모든 요청에 실린다. 서버는 검증만, 발급 안 함
폴링	순번 뒤일수록 길게(1/2/5초) + jitter — 동시 폴링 무리를 분산
403 흡수	입장 직후 좌석·회차 403은 승격↔인증 발급의 시간차 — 0.3초 간격 최대 12회 재시도
지연 안내	503 RETRY_LATER(발행 지연) → 화면 유지 + 안내. 재시도하면 통과
정리	뒤로·홈 이동 시 좌석 해제(release)와 자리 반납(leave)을 짝으로 호출 — 안 하면 TTL까지 유령 점유
만료 감지	입장 후에도 5초 폴링 유지 — 서버가 자리를 거두면(EXPIRED) 감지해 홈으로

E2E — 실제로 흘러가는가

개통 확인. 외부 경로는 이미 git에 선언돼 라이브였다 — 확인만 한다: LB IP 192.168.0.240 배정, 3경로 도달(/ 프론트 HTML · /api/movies 시드 JSON · /api/admission/* queue 응답), 지표 비노출(/metrics·/actuator는 프론트 폴백만), 공유기 DHCP 대역(2-199)과 MetalLB 풀(240-250) 안 겹침, Kafka 토픽 5종 READY. 이 시점부터 집 안 어느 기기든 브라우저로 데모에 닿는다.

여정은 두 벌로 탄다. 브라우저로 한 벌 — 화면·폴링·전환이 사람에게 실제로 보이는가. API로 한 벌 — 프론트가 부르는 것과 같은 API를 직접 불러 응답 계약을 분기까지 확인한다.

흐름 한 바퀴 — 실측 타임라인.

4명 enter      → 앞의 2명 즉시 입장(200 ADMITTED), 3·4번째는 대기 1·2번(202 WAITING)
1번이 예매      → 좌석 잠금(LOCKED) → 확정(예매번호 발급)
+1초           → 대기 1번이 ADMITTED — 확정이 Kafka를 돌아 자리를 회수하고 승격까지 1초
입장자를 방치    → 60초 세션 만료(EXPIRED) → 같은 3초 관측창 안에서 다음 대기자 승격

예매 완료 소비 로그에는 trace_id가 붙어 나온다 — HTTP에서 Kafka 소비까지 추적이 이어진다는 표시다(실도달 검증은 관측 편에서).

API 열 개 전부, 분기 포함 통과.

API	확인된 분기
enter	즉시 입장 · 대기(순번·총원) · 재진입=자리 유지 · 대기 재진입=꼬리 밀림 · 형식 위반 400
position	WAITING(순번·뒤 인원·ETA) · ADMITTED · EXPIRED · 형식 위반 400
leave	이탈 → 즉시 EXPIRED, 뒷사람 순번 전진
complete	자리 반환(removed) → EXPIRED
movies	시드 응답 — 게이트 없음(입장 전 진입점, 설계대로)
screenings	입장자 200 · 미입장 403
seats	좌석도 200칸(3상태 합성)
seats/select	잠금 · 경합 409 · 다좌석 전부-아니면-전무(실패 시 부분 잠금 없음까지 확인)
seats/release	해제 → 남이 재선점 가능
bookings	확정 · 같은 멱등키 재시도=같은 예매번호(재결제 없음) · 같은 키+다른 좌석 409

검증이 남긴 발견 셋.

ETA는 아직 믿을 값이 아니다. 60초마다 2명 도는 상태에서 4번째 대기자에게 46분이 표시됐다 — 실제 기대는 약 2분. 승격 속도 평균(EMA)의 기억이 초 단위라, "한 번에 2명 승격 → 60초 침묵" 패턴을 평균하지 못하고 침묵 구간의 0에 눌린다. 승격 직후엔 십몇 초, 30초 뒤엔 수십 분, 곧 "계산 중"으로 널뛴다. 속도 계산을 공유 카운터 + 회전 주기보다 긴 창으로 바꾸는 재설계의 실물 근거다(결정은 시뮬레이터 절에서).
폴링을 멈춘 대기자는 30초 만에 사라진다. 대기자를 세워 두고 폴링 없이 예매 절차만 밟자 정확히 설계대로 강퇴됐다. 브라우저는 자동 폴링이라 안 밟는 함정인데, 가짜 대기자를 만드는 생성기는 전원 폴링 루프가 필수라는 제약이 실물로 확인됐다.
멀티팟 첫 실증 — 순번은 일치하고 ETA만 갈라진다. 폴링이 queue 두 파드에 번갈아 떨어지는데 순번·상태는 항상 같았다(상태가 Redis 하나라서). ETA만 파드마다 다르게 나온다(-1 ↔ 13초 ↔ 115초) — 속도 평균이 파드 메모리에 살아서다. 로컬에서 검증된 적 없던 다중 replica 동작이 여기서 처음 확인됐다.

여기서 안 한 것. admissions 후커밋 재현(Redis 단절), UNIQUE 최종 방어 실도달(락 만료 창을 인위로 열어야 함), 503 RETRY_LATER(Kafka 발행 실패)는 전부 장애 재현 장치가 필요하다 — 테스트 절과 장애 편으로 넘긴다. 검증이 만든 예매 3건은 DB 비우기 기능이 생기면 첫 청소 대상이다.

2. 프론트 — 시뮬레이터로 다시 만든다

예매 화면만 있던 프론트를 티케팅 대기열 시뮬레이터로 다시 만든다. 왼쪽은 서비스(스토리·아키텍처 다이어그램·전체 현황·예매 카드), 오른쪽은 시뮬레이터 콘솔이다. 방문자가 콘솔에서 가상 관객을 넣고, 대기열이 도는 것을 지켜보다가, 직접 줄을 서서 예매까지 해보는 구성이다. 노출은 LAN까지 — 인터넷 공개는 TLS·인증을 갖추는 14부에서 연다.

콘솔이 하는 일

관객 투입 — 가상 관객 = 가짜 requestId로 enter하는 클라이언트다. 3초마다 전원이 position을 폴링한다(6명씩 병렬). 이 폴링이 생존 신호이자 상태 관찰이라, 멈추면 대기자는 30초 만에 서버가 회수한다. 투입은 프리셋 드롭다운으로 최대 200명 — 이 상한은 브라우저 생성기의 한계(동시연결 6개로 생존 창 안에 전원 폴링)지 백엔드 정원이 아니다. 그 이상의 부하는 k6로 잰다(13부).
자동 예매 — 켜면 입장한 관객이 좌석을 예매하고 나간다. 예매 완료 이벤트가 Kafka로 queue에 돌아와 자리가 반환되고 다음 대기자가 승격된다 — 줄이 도는 원리가 화면에 그대로 나온다. 끄면 세션 60초를 다 쓰고 나가 정원이 막힌 상황이 된다.
예매 오픈 예약 — 오픈 시각을 걸면 예매 버튼이 잠기고 시계가 카운트다운한다. 오픈 전 투입한 관객은 서버에 줄을 세우지 않고 대기실에 모아 뒀다가, 오픈 순간 러시 인원과 함께 한꺼번에 줄을 세운다(미리 줄 세우면 오픈에 들어오는 사람이 이미 진 채로 시작하므로). 게이트는 localStorage 프론트 연출이라 브라우저마다 독립이고, 서버는 이 시각을 모른다.

백엔드에 추가한 것 셋

stats API — GET /api/admission/stats. 전체 대기·입장·누적 승격을 Redis 파이프라인 한 왕복으로 집계한다. 화면의 현황 타일이 이걸 3초마다 읽는다.
ETA 재설계 — 검증에서 파드마다 예상 시간이 제각각으로 갈라졌다(파드 메모리 EMA가 원인 — 승격은 60초에 한 번 몰아 도는 주기 신호라 짧은 평활은 빈 구간에서 0으로 수렴한다). 승격 수를 Redis 초 단위 버킷에 기록하고 90초 창 전체를 합산해 평균 내는 방식으로 바꾼다. 값이 Redis에 있어 전 파드가 같은 ETA를 주고, 창이 회전 주기보다 길어 주기 신호에도 버틴다. 실측: 승격 12명 시점 rate 0.133/s, 6번째 대기자 ETA 45초 — 계산과 일치.
DB 리셋 — 예매는 영구 기록이라 좌석이 다 팔리면 데모가 멈춘다. queue(대기열 키 전부)와 booking(예매·좌석락·입장인증 + 방송일을 실행일+7일로 재설정)에 초기화 API를 만든다. 인증은 X-Admin-Token 헤더 — 토큰을 주입하지 않은 배포에는 라우트 자체가 등록되지 않는다. 화면의 ?ops 도구는 토큰을 입력받아 호출할 뿐, 판정은 서버만 한다.

3. 테스트 — API 계약을 게이트로 남긴다

CI 파이프라인 5단(check·test·build·scan·publish) 중 test 칸이 비어 있다. 지금까지 이 앱의 동작 확인은 AI에게 "코드를 훑고 검증해 달라"고 시켜 한 번 돌린 것이고, 그 결과는 그때 화면에만 남았다. 다음 커밋이 같은 동작을 깨도 아무것도 울리지 않는다.

테스트를 쓰려면 무엇을 지킬지부터 정해야 하는데, 그것은 코드 줄이 아니라 API가 서로에게 한 약속에 있다. 그래서 이 절은 API 목록에서 출발해, 그것들이 어떻게 맞물리는지 따라가고, 거기서 나오는 불변식을 테스트로 옮긴다.

API 목록 — 두 서비스가 여는 창구

queue는 "누가 들어갈 수 있나"를, booking은 "들어온 사람이 무엇을 살 수 있나"를 소유한다. 창구도 그 경계대로 갈린다.

queue (Go) — 입장 통제

메서드·경로	하는 일	상태 변경	응답
`POST /api/admission/enter`	정원을 원자로 확인해 입장 또는 대기 등록	O	200 `ADMITTED`·`ALREADY_ACTIVE` / 202 `WAITING`+순번 / 400 / 503 `RETRY_LATER`
`GET /api/admission/position`	내 순번·상태 조회. 호출 자체가 생존 신호를 겸한다	O(생존 시각)	`WAITING`(순번·뒤 인원·예상) / `ADMITTED` / `EXPIRED`
`GET /api/admission/stats`	전체 현황 집계(입장·대기·정원·신규 진입 예상)	X	숫자 묶음
`GET /api/admission/events`	최근 이벤트 피드(커서 `after` 이후만)	X	이벤트 배열 + 마지막 id
`POST /api/admission/leave`	자발적 이탈 — 입장·대기·생존 추적에서 모두 제거	O	`LEFT`
`POST /api/admission/complete`	사용자가 부르는 자리 반환 — 입장에서만 제거	O	`COMPLETED`
`POST /api/admission/reset`	대기열 상태 전부 삭제(운영용, 토큰 필요)	O	`RESET`

booking (Java) — 예매

메서드·경로	하는 일	입장 인증	응답
`GET /api/movies`	상영 목록	불필요	목록
`GET /api/screenings`	회차 목록 + 잔여 좌석	필요	목록 / 403
`GET /api/seats`	좌석도(빈자리·임시점유·판매완료를 합친 값)	필요	목록 / 403
`POST /api/seats/select`	좌석 임시 점유(다중 좌석 전부 성공 또는 전부 실패)	필요	200 `LOCKED` / 409
`POST /api/seats/release`	점유 해제	필요	200
`POST /api/bookings`	결제·예매 확정	필요(멱등 재요청은 예외)	200 예매번호 / 400 / 403 / 409
`POST /api/admin/reset`	예매·좌석·인증 삭제 + 방송일 재설정(운영용, 토큰 필요)	토큰	`RESET`

두 서비스를 잇는 것은 HTTP가 아니라 Kafka 세 토픽이다. admissions(queue → booking, 입장 승인) · admissions-revoked(queue → booking, 입장 회수) · bookings-completed(booking → queue, 자리 반환). 서로를 직접 호출하지 않으므로 한쪽이 죽어도 다른 쪽이 함께 멈추지 않는다.

API가 어떻게 맞물리나 — 한 사람의 여정

모든 창구를 관통하는 열쇠는 requestId 하나다. 화면의 [익명으로 시작]을 누르면 브라우저가 UUID를 만들어 이 값으로 쓰고, 앞자리를 딴 라벨(관객-8e9e)을 이름 대신 보여준다. 대기열 등록도 좌석 점유도 예매 확정도 전부 이 값으로 이뤄지고, 값은 브라우저에 저장돼 새로고침해도 유지된다 — 새로고침 뒤에도 대기 순번이 이어지는 이유가 이것이다.

서버가 검증하는 것은 신원이 아니라 상태다. 형식만 확인하고(영숫자·_·-, 64자 이내), 그 값이 지금 대기 줄에 있는지·정원 안에 있는지·좌석을 잡았는지만 본다. 비밀번호도 서명도 없으므로 아무 값이나 만들어 보내도 받아준다 — 가상 관객을 만드는 방법이 bot- 접두의 값을 새로 찍어 입장을 부르는 것뿐인 것도 같은 이유다.

이 설계는 대기열의 동작을 보여주는 데는 충분하고, 공개하는 데는 부족하다. 남의 requestId를 알면 그 사람을 대기열에서 빼거나 좌석 점유를 풀 수 있다. 인터넷에 여는 단계에서 서명된 신원으로 바꾸는 것이 선행 조건이고, 이 편의 노출 범위를 LAN까지로 묶는 근거도 여기 있다.

클라이언트              queue                   Kafka                booking              저장소
    │
    │ POST /enter
    ├──────────────────▶ 정원 확인(Lua, 원자)
    │                     ├ 여유 있음 → active 등록 ─── admissions ──▶ 인증 발급 ──▶ Redis(키+TTL)
    │ ◀── 200 ADMITTED    │
    │                     └ 정원 참  → waiting 등록(진입 순서 score)
    │ ◀── 202 WAITING + 순번
    │
    │ GET /position  (1·2·5초 간격 반복)
    ├──────────────────▶ active에 있나 → 없으면 waiting 순번 → 둘 다 없으면 EXPIRED
    │ ◀── 상태 + 순번·예상        └ 이 호출이 '마지막으로 본 시각'을 갱신한다
    │
    │              ┌ 승격 루프(2초): 빈자리만큼 waiting 앞에서 active로 ─ admissions ─▶ 인증 발급
    │   백그라운드 ┤ 세션 타임아웃(10초): 오래된 active 회수 ───── admissions-revoked ─▶ 인증 삭제
    │              ├ 대기 타임아웃(10초): 폴링이 끊긴 waiting 회수
    │              └ 저널 스윕(5초): 발행이 끝나지 못한 이벤트 재발행
    │
    │ GET /screenings · /seats   (requestId 동봉)
    ├───────────────────────────────────────────────────▶ 인증 있나? ─ 없으면 403
    │ ◀── 회차·좌석
    │
    │ POST /seats/select
    ├───────────────────────────────────────────────────▶ 좌석락(Lua) ──▶ Redis(45초 TTL)
    │ ◀── 200 LOCKED / 409 이미 선점
    │
    │ POST /bookings  (idempotencyKey 동봉)
    ├───────────────────────────────────────────────────▶ 확정 8단계 ──▶ MySQL(UNIQUE)
    │ ◀── 200 예매번호                                          │
    │                     ◀───── bookings-completed ────────────┘
    │                     자리 반환(active에서 제거) → 다음 승격이 그 자리를 채운다

읽을 때 걸리는 지점 셋을 풀어 둔다.

입장은 두 곳에 기록된다. queue의 정원 명단(active)과 booking의 입장 인증이다. 사용자가 "들어갔다"고 느끼는 순간과 booking이 그것을 아는 순간 사이에 Kafka 한 구간이 있다. 그래서 입장 직후의 회차 조회가 403으로 튈 수 있고, 화면은 그 틈을 짧은 재시도로 흡수한다. 인증을 booking이 스스로 만들지 않는 이유도 여기 있다 — 정원 통제의 소유자를 한 곳(queue)으로 두기 위해서다.

나가는 길이 셋이다. 예매를 끝내거나(bookings-completed), 스스로 나가거나(leave·complete), 시간이 지나 서버가 회수한다(세션·대기 타임아웃). 어느 길로 나가든 queue의 명단에서 빠지고, 앞의 둘과 셋째는 admissions-revoked로 booking의 인증도 지운다. 이 통보가 빠지면 자리를 잃은 사용자가 계속 예매 API를 통과한다.

폴링이 곧 생존 신호다. 서버가 연결을 붙들지 않으므로 "끊겼다"를 직접 알 수 없다. 마지막 폴링 시각을 기록해 두고 오래된 항목을 회수하는 방식이라, 대기자는 계속 물어봐야 줄을 유지한다.

흐름에서 나오는 불변식

위 그림을 따라가면 "무엇이 깨지면 사용자가 피해를 보는가"가 나온다. 테스트가 지킬 대상은 이 목록이다.

불변식	깨지면	지키는 장치
입장 인원이 정원을 넘지 않는다	정원 산정이 무의미해지고 booking이 감당 못 하는 부하를 받는다	enter·승격 Lua의 원자 확인
같은 신원의 재진입이 자리를 늘리지 않는다	새로고침만으로 정원이 늘어난다	enter의 멱등 분기
대기 순번은 진입 순서를 지킨다	늦게 온 사람이 먼저 들어간다	대기 줄과 생존 추적을 다른 키로 분리
자리를 잃으면 예매 자격도 사라진다	정원 밖 사용자가 좌석을 산다	회수 이벤트 + 인증 TTL
같은 좌석이 두 번 팔리지 않는다	두 사람이 같은 자리 티켓을 받는다	좌석락(1차) + MySQL 유니크 제약(최종)
같은 멱등키는 같은 결과를 준다	응답이 유실된 재시도가 이중 결제가 된다	멱등키 조회가 확정보다 앞
좌석 요청이 정규화된다	중복 좌석이 결제 금액을 부풀리고, 순서 차이가 교착을 만든다	중복 제거·정렬·개수 상한

마지막 줄의 "순서 차이"를 덧붙이면 — 두 요청이 [A1,A2]와 [A2,A1]로 동시에 들어오면 서로가 잡은 행을 기다려 데이터베이스 교착이 된다. 정렬은 표시용이 아니라 그 교착을 막는 장치다.

테스트를 어떻게 구축하나

테스트도 코드이고 실행기가 있다. 빌드에 go build·mvn package가 있듯 go test·mvn test가 있고, CI의 test 단계는 그 명령을 부르는 job이다. 실패하면 종료 코드가 0이 아니라서 파이프라인이 멈춘다.

Go(queue) — 표준 라이브러리에 들어 있어 설치할 것이 없다. 대상 파일 옆에 _test.go를 만들고 Test로 시작하는 함수를 쓰면 go test ./...가 전부 실행한다.

Java(booking) — 관례는 같고 위치와 의존성이 다르다. 테스트는 src/test/java에 두고, pom.xml에 test 전용 의존성(spring-boot-starter-test, scope=test라 실행 이미지에는 안 들어간다)을 더한 뒤 @Test 메서드를 쓴다. 이 저장소의 booking에는 src/test 디렉터리 자체가 없어 그 추가가 첫 삽이다. 이미지 빌드가 -DskipTests로 테스트를 건너뛰는 것은 의도된 분리다 — build job은 이미지만 만들고, 테스트는 test job이 따로 돈다.

무엇 위에서 도느냐가 방법을 가른다. 앞의 불변식을 재료별로 나누면 세 층이 된다.

층	이 앱에서	필요한 것
순수 로직	좌석 요청 정규화, 식별자 형식 검증	없다. 입력을 넣고 출력을 비교한다
Redis 위	정원 확인, 승격, 만료 회수, 발행 저널	실제 Redis. 원자성이 Lua 스크립트에서 나오므로, 가짜로 흉내 내면 흉내 낸 자기 자신을 검증하게 된다
MySQL 위	이중 판매 최종 방어, 멱등키 조회	실제 MySQL. 인메모리 대체는 유니크 위반 시점과 잠금 의미가 달라 통과가 증명이 되지 않는다

둘째 줄이 이 앱의 특성이다. 정원을 지키는 주체가 Go 코드가 아니라 Redis 스크립트라서, 앱 코드만 단위 테스트하면 정작 지켜야 할 것이 검증 범위 밖에 남는다. 실물을 붙이는 이유는 "더 정확해서"가 아니라 검증 대상이 거기 있어서다.

깨짐이 동시일 때만 나타난다는 것도 방법을 정한다. 정원 초과는 순차 호출로는 절대 재현되지 않는다. 그래서 테스트가 고루틴으로 동시 요청을 만들어 같은 순간에 출발시킨다. 순차로 세 번 부르는 검사는 어떤 구현이든 통과하므로 회귀를 잡지 못한다.

넣은 것

이 프로젝트의 무게중심은 인프라이고 앱은 그 위에서 도는 대상이다. 그래서 앱 테스트는 게이트가 실제로 도는 최소로 둔다.

job	대상	붙인 실물
`test:queue-go`	동시 요청 50개에도 입장이 정원을 넘지 않는가 · 같은 신원의 재진입이 자리를 늘리지 않는가	Redis(서비스 컨테이너)
`test:booking`	좌석 요청 정규화 — 중복 제거·순서 고정·개수 상한·빈 요청 거절	없음(순수 로직)

test:queue-go:
  stage: test
  image: golang:1.26
  services:
    - name: redis:7-alpine
      alias: redis
  variables:
    REDIS_ADDR: "redis:6379"
  script: [ cd queue-go, go test ./... ]
  rules: [ changes: [ queue-go/**/*, .gitlab-ci.yml ] ]   # 안 바뀐 서비스의 테스트는 돌지 않는다

Redis에 닿지 않으면 실패가 아니라 건너뛰게 했다 — Redis 없이 go test ./...를 돌리는 개발 중 실행이 빨간불이 되지 않게. CI에는 서비스 컨테이너가 붙어 있어 항상 실행된다.

테스트가 실제로 회귀를 잡는지 확인했다. 통과하는 것만으로는 부족하다 — 항상 통과하는 테스트는 없는 것과 같다. 사본에서 정원 확인 조건을 activeCount < maxSessions + 10으로 망가뜨리고 돌리니 이렇게 잡혔다.

--- FAIL: TestEnterKeepsCapacityUnderConcurrency
    입장 인원이 정원과 다르다: 정원 3, 입장 13
    저장된 입장 인원이 정원을 넘었다: 13(정원 3)

응답만 세지 않고 저장된 명부(ZCARD active)까지 확인하는 이유도 여기 있다. 응답이 맞아도 명부가 넘칠 수 있다.

test 단계는 lint·secret·dependency와 같은 축으로 allow_failure 없이 건다. 조건 없이 막을 때만 게이트다.

넣지 않은 것 — 앱이 커지면 필요한 순서

앱의 비중을 여기까지로 잡았기 때문에 아래는 손대지 않았다. 예매 기능을 더 다루게 되면 이 순서로 늘린다.

멱등 재요청 — 같은 키의 재시도가 같은 예매번호를 돌려주는지. 다만 예매번호만 비교하는 테스트는 반쪽이다. 같은 번호를 돌려주면서 결제를 한 번 더 했을 수도 있어서, 결제 승인 호출이 1회인지까지 확인해야 이중 결제를 막는다.
이중 판매 최종 방어 — 좌석락이 1차에서 걸러내므로 유니크 제약까지 도달시키려면 락을 일부러 우회시켜야 한다. 그러려면 락 계층을 갈아끼울 수 있어야 하고, 지금 구조가 그것을 허용하는지 확인이 먼저다.
확정 경로 여덟 갈래 전수 — 지표 카운터의 결과 라벨 여덟 개(success·replay·lock_expired·seat_conflict·forbidden·no_screening·bad_request·error)와 하나씩 맞춘다. 폭이 넓어 한 번에 하면 오래 걸린다.
서비스 간 계약 — 입장 인증은 queue가 만들고 Kafka를 건너 booking이 소비한다. 한 서비스 안에서는 이 계약이 검증되지 않는데, 두 서비스와 브로커를 함께 띄우는 테스트는 CI에서 무겁다. 지금은 배포 후 확인으로 남긴다.
시간에 매달린 항목 — 좌석락 45초·세션 60초·인증 180초·대기 이탈 30초. 실시간으로 기다리면 테스트가 분 단위가 되므로, 짧은 값을 주입할 수 있는 구조가 먼저 필요하다.

정리(teardown)는 지금부터 규약으로 둔다. 테스트가 만든 신원과 좌석은 끝에서 회수한다. 남기면 다음 테스트가 정원이 찬 상태에서 시작해 원인 없이 실패하고, 좌석은 영구 기록이라 재고가 줄어든다. 좌석이 4,000석뿐이라 이 규약이 없으면 테스트를 돌릴수록 매진에 가까워진다.

4. 파드 사이 접근 범위 좁히기

앱 쪽 작업이 한 바퀴 끝났다. 다음은 통신 범위 좁히기다. 관측 배선과 k6 부하 실측이 다음 편들에서 이어지는데, 수치를 재기 시작한 뒤에 "누가 어디에 붙을 수 있나"를 바꾸면 다시 재야 한다 — 그래서 재기 전에 먼저 좁힌다.

이 절에서 다루는 단위는 파드다. 파드는 컨테이너 하나 이상을 묶어 IP 하나를 공유하는 배포 단위이고, 쿠버네티스가 띄우고 내리는 최소 단위다. 통신을 허용하거나 막는 대상도 파드다.

클러스터는 노드 3대이고, 객체는 네임스페이스로 갈라 둔다. 네임스페이스는 클러스터 안 객체를 이름으로 나누는 칸이다.

네임스페이스	들어 있는 것
`app`	frontend(정적 파일 서빙) · queue(대기열 판정) · booking(예매 처리)
`data`	MySQL · Redis · Kafka
`observability`	지표·로그 수집과 저장

막고 여는 단위는 파드와 포트 둘이다. 주소가 두 겹이라 그렇다 — IP 가 어느 파드인지를 가르고, 포트가 그 파드 안의 어느 프로그램인지를 가른다. 파드 하나가 여러 포트를 열어 두면 그 포트마다 다른 상대가 붙는다.

data 의 Redis 파드가 6379(데이터)·26379(마스터 조회)·9121(지표)을 함께 여는 것이 그렇다. 그래서 정책도 포트별로 따로 적는다.

범위는 data 로 들어오는 접속까지다. app 에서 나가는 쪽과 클러스터 밖에서 들어오는 경로는 이번에 안 건드린다.

무엇이 열려 있나

클러스터 안 어느 파드에서든 data 의 MySQL 3306, Redis 6379·26379, Kafka 9092 에 도달한다. 정적 파일만 서빙하는 frontend 도, observability·argocd·kube-system 의 파드도 MySQL 에 붙는다.

통신을 제한하는 규칙이 없어서가 아니다. 쿠버네티스에서 그 규칙을 담는 객체를 NetworkPolicy 라 부르고, 하나는 세 부분으로 되어 있다 — 대상 파드, 방향, 허용 목록. 허용 목록에는 출처와 포트를 적는다. 정책이 고른 파드는 들어오는 접속이 일단 전부 막히고, 허용 목록에 적은 것만 다시 통과한다.

kubectl get netpol -A 를 하면 8건이 나온다.

네임스페이스	이름	만든 주체	열린 포트	보내는 쪽
argocd	4건 (server·repo-server·application-controller·redis)	argo-cd 차트	argocd 안쪽 — 이번 대상 밖
data	mysql	`bitnami/mysql` 14.0.3	3306	안 적힘
data	redis	`bitnami/redis` 27.0.15	6379 · 26379 · 9121	안 적힘
data	cgv-network-policy-kafka	Strimzi 오퍼레이터	9090 · 9091 · 8443	지정돼 있음
data	cgv-network-policy-kafka	Strimzi 오퍼레이터	9092	안 적힘
data	cgv-entity-operator	Strimzi 오퍼레이터	8080 · 8081	안 적힘

문제는 오른쪽 끝 칸이다. 허용 목록에 포트만 있고 출처가 없으면 그 포트로 오는 것은 어디서 왔든 통과한다. mysql 정책이 막는 것은 3306 아닌 포트뿐이고, 지켜야 할 포트는 3306 이다.

출처가 빠진 이유가 만든 주체마다 다르고, 그래서 고치는 손잡이도 따로다.

차트가 만든 것. Helm 차트는 쿠버네티스 객체를 값에 따라 찍어 내는 템플릿 묶음이고, 그 값은 values.yaml 에 적는다. MySQL 과 Redis 는 Bitnami 가 배포한 차트를 값만 바꿔 감싼 래퍼 차트(cgv-mysql·cgv-redis)로 쓴다.

그 차트의 기본값은 networkPolicy.enabled: true, networkPolicy.allowExternal: true 다. allowExternal: true 면 템플릿이 출처를 빼고 정책을 만든다. 손잡이는 래퍼의 values.yaml 이다.

오퍼레이터가 만든 것. CRD 는 쿠버네티스에 새 객체 종류를 등록하는 정의이고, 그 정의대로 만든 객체 하나를 CR 이라 부른다. 오퍼레이터는 CR 을 지켜보다가 필요한 객체를 대신 만들어 두는 프로그램이고, Strimzi 는 Kafka 용 오퍼레이터다.

Kafka 쪽 정책은 Strimzi 가 Kafka CR 을 읽고 만든다. 9090·9091 은 브로커끼리 쓰는 복제와 제어, 8443 은 오퍼레이터가 쓰는 통로라 Strimzi 가 출처까지 적는다. 클라이언트가 붙는 9092 만 비어 있는데, 그 출처를 적는 자리인 리스너(브로커가 접속을 받는 창구 설정)에 아무것도 안 넣었기 때문이다. 정책을 지워도 오퍼레이터가 다시 만들어 놓으므로 지우는 방식은 안 통한다. 손잡이는 Kafka CR 이다.

열려 있으면 무엇이 깨지나

이 서비스는 좌석 정원만큼만 예매 화면에 들여보내려고 앞에 대기열을 둔다. queue 가 Redis 에서 남은 정원을 확인해 통과한 요청만 Kafka 의 admissions 토픽에 넣고, booking 이 그 토픽을 읽어 예매 자격을 발급한다. 열려 있는 포트 가운데 9092 는 그 통제가 통하지 않게 만든다.

정상   사용자 ─▶ queue ─(Redis 로 정원 확인)─▶ Kafka admissions ─▶ booking
우회   아무 파드 ─────────────────────────▶ Kafka admissions ─▶ booking
                                                                   │
                                admitted:{movie}:{requestId} 발급 = 예매 자격

두 줄의 차이는 queue 를 거치느냐 하나다. booking 은 메시지를 보낸 쪽을 확인하지 않아서, admissions 에 메시지를 넣는 것이 곧 예매 자격이 된다. 대기열·순번·정원을 건너뛴다. 리스너는 type: internal, tls: false, 인증 설정 없음이고 internal 은 클러스터 밖 노출만 막는다.

막는 층이 셋이다 — 메시지에 서명을 붙여 앱이 확인하는 것, 브로커가 접속자를 확인하는 것(아이디·비밀번호를 쓰는 SASL, 양쪽 인증서를 쓰는 mTLS), 애초에 도달 자체를 줄이는 것. 이번에 하는 건 세 번째다. 앱과 브로커 설정을 그대로 두고 도달 범위만 줄인다.

NetworkPolicy — 무엇을 적는 물건인가

정책이 하나도 고르지 않은 파드는 들어오는 것도 나가는 것도 전부 허용된다. 네임스페이스는 이름 공간이지 패킷의 경계가 아니다. app 의 파드와 data 의 파드는 정책이 없으면 같은 평면에 있다.

파일 하나를 통째로 놓고 줄마다 무엇을 정하는지 본다. 이 정책은 data 의 MySQL 로 들어오는 접속을 app 의 booking 파드가 3306 으로 보내는 것 하나로 제한한다.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: mysql-ingress
  namespace: data                            # ① 정책이 사는 곳. 대상 파드도 여기서만 고른다
spec:
  podSelector:                               # ② 대상 — 이 정책을 어느 파드에 붙이나
    matchLabels:
      app.kubernetes.io/name: mysql          #    이 라벨을 단 파드 = mysql-0
  policyTypes:
    - Ingress                                # ③ 방향 — 들어오는 쪽만 다룬다
  ingress:                                   # ④ 허용 목록. 여기 맞는 것만 통과, 나머지는 폐기
    - from:                                  # ⑤ 출처 — 누가 보내는 것을 허용하나
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: app     # 쿠버네티스가 모든 네임스페이스에
          podSelector:                             # 자동으로 붙이는 라벨. 네임스페이스도
            matchLabels:                           # 라벨로만 고를 수 있어 이것을 쓴다
              app.kubernetes.io/name: booking
      ports:                                 # ⑥ 통로 — 어느 포트로 오는 것을 허용하나
        - port: 3306

읽는 축은 ② 와 ④ 다. 정책이 파드를 고르는 순간 그 파드로 들어오는 접속이 전부 막히고, ingress 에 적은 것만 다시 통과한다. 차단할 것을 적는 게 아니라 뚫을 것을 적는다. 문법에 거부 규칙은 없다.

나머지는 이 구조에서 따라 나온다.

대상은 라벨로만 고른다. 파드 이름은 booking-5cff7c7fbb-wn4ph 처럼 배포마다 바뀌고 IP 도 바뀐다. podSelector: {} 는 그 네임스페이스 전부를 뜻한다.
대상은 정책이 있는 네임스페이스 안에서만 고르고, 출처는 다른 네임스페이스에서도 고른다. 그래서 app 에서 data 로 가는 통신을 제한하는 정책은 받는 쪽인 data 에 둔다.
from 과 ports 는 AND 로 읽고, 안 적은 축은 제한하지 않는다. 차트와 오퍼레이터가 만든 정책에 출처가 비어 있는 것이 이것이다 — ports 만 있으면 어디서 왔든 통과한다.
ingress: [] 는 전부 차단, ingress: [{}] 는 전부 허용이다. 규칙 개수가 뜻이 된다.
라벨로 못 고르는 출처는 ipBlock 으로 적는다. 파드는 10.42.0.0/16 대역을 받고 노드 IP 는 그 밖이라, 노드에서 오는 접속은 파드 셀렉터에 안 잡히고 ipBlock 으로 적는다.

from 안에서는 하이픈 하나가 AND 와 OR 를 가른다.

- from:
    - namespaceSelector: {matchLabels: {kubernetes.io/metadata.name: app}}
      podSelector: {matchLabels: {app.kubernetes.io/name: booking}}
      # 원소 하나 안에 셀렉터 둘 = AND → app 의 booking 파드만

- from:
    - namespaceSelector: {matchLabels: {kubernetes.io/metadata.name: app}}
    - podSelector: {matchLabels: {app.kubernetes.io/name: booking}}
      # 원소 둘 = OR → app 전체, 또는 정책과 같은 네임스페이스의 booking 파드

하이픈 하나로 파드 하나에서 네임스페이스 전체로 벌어진다.

문법에서 한 가지가 더 따라 나오고, 이것이 작업 순서를 정한다. 여러 정책이 같은 파드를 고르면 허용의 합집합이 적용된다. 우선순위도 거부도 없어서 좁은 정책을 더해도 넓은 정책이 열어 둔 것이 남는다.

정책 A (차트가 생성):  podSelector=mysql,  ingress[{ports:[3306]}]                 # from 없음
정책 B (직접 작성):    podSelector=mysql,  ingress[{from:[booking], ports:[3306]}]

A + B  →  3306 은 어디서든 통과        B 만  →  booking 에서만 통과

좁히려면 B 를 더하는 것으로는 안 되고 A 를 없애야 한다. 차트가 만드는 정책을 꺼야 하는 이유가 이것이다.

여기까지가 파일에 적는 내용이고, kubectl apply 를 하면 클러스터의 모든 객체를 받아 두는 API 서버에 저장된다. 저장된 글자가 패킷을 막지는 않는다.

그 선언이 패킷을 막기까지 — Calico

막는 쪽은 파드에 네트워크를 붙여 준 프로그램이다. 길을 놓은 쪽이라야 그 길에 문을 달 수 있다.

쿠버네티스는 파드를 어느 노드에 띄울지 정하고 컨테이너를 실행하는 데까지 한다. 파드에 IP 를 주는 일과 다른 노드의 파드까지 패킷을 보내는 일은 하지 않는다.

그 자리는 "프로그램을 하나 꽂아서 시켜라" 로 비워 두었고, 그 프로그램이 지켜야 할 규격이 CNI(Container Network Interface)다. Calico 는 그 자리에 꽂힌 프로그램이고 두 가지를 한다 — 길을 놓는 일과 그 길의 통행을 판정하는 일이다.

길

파드가 뜰 때 CNI 플러그인이 veth 쌍을 만든다. 랜선 하나의 양 끝 같은 것으로, 한쪽 끝은 파드 안에 들어가 eth0 이 되고 반대쪽 끝은 노드에 남아 cali 로 시작하는 이름을 받는다. 파드 하나에 노드 쪽 인터페이스 하나가 대응한다.

주소는 두 종류가 따로 논다. 파드는 10.42.0.0/16, 노드는 LAN 주소(192.168.0.201·202·203)다. 대역이 달라 파드 IP 는 LAN 에서 그대로 오갈 수 없어서, 노드를 넘을 때 원본 패킷을 노드 IP 봉투에 넣어 보내고 받는 쪽에서 벗긴다. 이 방식이 VXLAN 이다.

파드A ─veth─▶ k3s-1 ─[노드 IP 봉투]─▶ k3s-3 ─[벗김]─▶ veth ─▶ 파드B

판정

패킷이 파드로 들어가려면 마지막에 그 파드의 veth 를 지난다. Calico 는 veth 의 노드 쪽 끝마다 전용 규칙 묶음을 붙인다. 들어가는 방향과 나가는 방향이 따로 있어 ingress 와 egress 가 갈리고, 파드마다 인터페이스가 하나씩이라 판정도 파드 단위로 갈린다.

패킷을 통과시키거나 버리는 것은 리눅스 커널이고, 커널이 그 판정에 참조하는 규칙표가 iptables 다. 규칙 묶음을 체인이라 부르며, Calico 가 만드는 체인은 이름이 cali 로 시작한다.

라벨이 IP 로 바뀌는 곳

iptables 는 IP 와 포트로만 판정한다. 라벨은 문자열이라 커널이 모른다. 그 사이를 ipset 이 메운다 — IP 를 묶어 두고 규칙에서 한 덩어리로 참조하는 커널 목록이다.

정책에 적은 것   app 의 booking 라벨을 단 파드
      ▼          Calico 가 그 라벨을 단 파드의 IP 를 모은다
ipset            { 10.42.207.61 }
      ▼
iptables 규칙    "출발지가 이 묶음에 있으면 통과"

파드가 뜨고 지면 묶음의 멤버만 갱신되고 규칙 자체는 그대로 있다.

선언을 규칙으로 옮기는 것

veth 에 체인을 붙이고 ipset 을 채우는 일은 Felix 가 한다. 파일에 적은 정책이 거기까지 가는 경로다.

kubectl apply ─▶ API 서버 ─watch─▶ 각 노드의 Felix ─▶ 그 노드의 iptables · ipset

Felix 는 노드마다 하나씩 도는 calico-node 안의 데몬이고, 자기 노드에 있는 파드까지만 규칙을 쓴다. 정책이나 파드가 바뀌면 달라진 부분만 다시 쓴다. calico-system 의 나머지 파드는 이 경로를 거드는 것들이다 — calico-typha 는 Felix 들이 API 서버를 각자 지켜보지 않도록 중계하고, install-cni 는 노드에 CNI 플러그인을 설치하고, 나머지는 정리 작업과 Calico 전용 API 를 맡는다.

규칙을 iptables 에 넣을지 eBPF 로 넣을지는 felixconfiguration 이 정한다. 지금은 bpfEnabled: false 라 iptables 다.

flannel 과의 차이

k3s 가 기본으로 설치하는 CNI 플러그인은 flannel 이다. flannel 은 길만 놓는다. 판정은 k3s 에 내장된 별도 컨트롤러가 맡는다. flannel 을 쓰면 NetworkPolicy 가 적용되지 않는 것이 아니라 두 프로그램이 나눠 맡는다.

k3s 기본   flannel(길)  +  k3s 내장 컨트롤러(판정)
지금       Calico(길 + 판정)

Calico 에는 거부 규칙과 우선순위가 있는 전용 정책 API 도 딸려 온다. 그것으로 쓰면 Calico 에서만 해석되어 CNI 를 바꿀 때 다시 써야 하므로, 이번에 쓰는 것은 표준 NetworkPolicy 뿐이다.

k3s 설치 때 config.yaml 에 넣은 두 줄이 이 구성을 만든다.

flannel-backend: none          # 길을 놓는 k3s 기본 플러그인을 끈다
disable-network-policy: true   # 판정하는 k3s 내장 컨트롤러를 끈다

뒤의 줄을 안 넣었으면 같은 정책 객체를 두 집행자가 각자 노드에 넣는다. 결과는 같아도 노드에 들어간 규칙이 어느 쪽이 만든 것인지 갈라내기 어려워진다.

무엇을 남길지 정한다

문법과 집행 경로가 정해졌으니 남은 것은 출처에 무엇을 적을지다. data 로 들어오는 접속을 일단 전부 막고 필요한 것만 다시 여는 것이므로, 지금 들어오는 것을 빠짐없이 세야 한다. 목록에서 빠진 것은 적용하는 순간 끊긴다.

들어오는 것이 세 종류다.

종류	보내는 쪽	어디서 아나
앱이 쓰는 것	`app` 의 queue · booking	앱 env 와 차트 값에 적혀 있다
`data` 안에서 자기들끼리	Redis 복제·Sentinel 투표, Kafka 브로커 간, Strimzi 오퍼레이터에서 브로커로	구조를 알면 나온다
클러스터가 보내는 것	kubelet 의 상태 검사, Alloy 의 지표 수집	배선한 적이 없어서 조회해야 나온다

앞의 둘은 이미 아는 것이고, 세 번째를 조회한다.

kubelet 의 상태 검사

kubelet 은 노드마다 도는 에이전트로 컨테이너를 띄우고 내린다. 그 일 중 하나가 컨테이너가 살아 있는지 주기적으로 확인하는 것이고, 이것을 프로브라 부른다. 실패하면 컨테이너를 재시작한다.

찌르는 방식에 따라 정책에 걸리는지가 갈린다. exec 는 컨테이너 안에서 명령을 실행하므로 네트워크를 안 타고, httpGet 은 노드에서 파드 IP 로 요청을 보내므로 판정 대상이 된다. data 의 파드를 전부 조회한 결과다.

대상	프로브	네트워크	지금 걸린 정책
MySQL · Redis · Kafka 브로커	exec	안 탄다	각자 있다
Redis 파드의 지표 사이드카	httpGet 9121	탄다	redis (차트)
entity-operator	httpGet 8080 · 8081	탄다	cgv-entity-operator
strimzi-cluster-operator	httpGet 8080	탄다	없다

둘째 줄의 사이드카는 파드 하나에 컨테이너를 둘 이상 담을 수 있어서 생긴 것이다. Redis 파드 안에 지표를 내놓는 컨테이너가 따로 돌고, 그 포트가 9121 이다.

kubelet 은 노드 주소에서 접속한다. 출발지가 파드가 아니라 노드라 라벨로 못 고르고 ipBlock 에 노드 IP 를 적어야 한다.

마지막 줄만 지금 어떤 정책에도 걸려 있지 않다. data 전체를 고르는 정책을 넣으면 이 파드가 처음으로 선택되면서 8080 이 막히고, 재시작이 반복되면 Kafka 리소스 조정이 멈춘다. 허용 규칙을 같이 넣는다.

Alloy 의 지표 수집

Alloy 는 observability 에서 도는 지표 수집 에이전트다. 무엇을 긁을지는 ServiceMonitor 객체에 적혀 있고, data 에 있는 것은 redis 하나다. 9121 을 긁는다. Kafka 와 MySQL 은 ServiceMonitor 가 없어 긁는 것이 없다.

Alloy 도 kubelet 처럼 노드마다 하나씩 뜨지만 자기 파드 네트워크를 쓴다. 출발지가 노드 IP 가 아니라 파드 IP 라 라벨로 고른다. 같은 9121 인데 kubelet 은 ipBlock, Alloy 는 셀렉터로 적게 되는 이유다.

손댈 곳

정책 4개를 새로 쓴다 (workloads/manifests/netpol/data-ingress.yaml)

정책	대상	여는 것
`default-deny-ingress`	`data` 전체	없음. 판정 대상으로 만드는 것이 일이다
`mysql-ingress`	mysql	`app` 의 booking 에서 3306
`redis-ingress`	redis	`app` 의 queue·booking 에서 6379·26379 / Alloy·노드 3대에서 9121
`strimzi-operator-probe`	클러스터 오퍼레이터	노드 3대에서 8080

Kafka 브로커와 entity-operator 는 Strimzi 가 만든 정책이 이미 고르고 있고 허용은 합집합이라 그대로 통과한다. 새로 열 것이 없다.

Redis 는 두 포트가 함께 필요하다. 클라이언트가 26379(Sentinel)로 마스터 주소를 받고 그 주소로 6379 에 다시 접속하므로, 26379 만 열면 주소 조회는 되고 다음 명령에서 멈춘다.

차트 정책 2건을 끈다 (cgv-mysql·cgv-redis 의 values.yaml)

networkPolicy.enabled: false. 넓은 정책이 남아 있으면 좁은 정책을 더해도 합집합이라 안 좁아진다.

Kafka CR 에 출처를 적는다 (kafka-cluster.yaml 리스너의 networkPolicyPeers)

9092 의 출처는 app 의 queue 와 booking 이다. 리스너에 적으면 오퍼레이터가 정책을 좁게 다시 만든다.

적용은 두 단계로 나눈다. 정책을 먼저 넣고 그다음에 차트 정책을 끈다. 뒤집으면 그 파드를 고르는 정책이 하나도 없는 구간이 생겨 그동안 전부 열린다.

이번에 안 좁아지는 것

Kafka 는 무인증 평문 그대로다. 허용된 라벨을 단 파드는 인증 없이 admissions 에 발행한다
라벨은 누구나 적을 수 있는 문자열이라 이 제한은 출처를 증명하지 않는다
app 에서 나가는 방향, 클러스터 밖에서 traefik 을 거쳐 들어오는 경로는 안 건드린다

결과

data 로 들어오는 접속이 이렇게 바뀌었다.

	전	후
MySQL 3306	클러스터 안 아무 파드나	`app` 의 booking
Redis 6379·26379	아무 파드나	`app` 의 queue·booking
Redis 9121	아무 파드나	Alloy · 노드 3대
Kafka 9092	아무 파드나	`app` 의 queue·booking · 브로커 자신
`data` 의 정책	8건, 출처 없음 셋	6건, 출처 전부 지정

라벨이 없는 파드와 있는 파드에서 각각 붙어 확인했다.

observability, 라벨 없음    mysql 3306 · redis 6379 · kafka 9092   전부 timed out
app, booking 라벨          같은 셋                                 전부 open

정책은 패킷을 폐기하지 거절 응답을 보내지 않아 타임아웃으로 끝난다. 뒤쪽이 통과한다는 것이 라벨 하나로 갈린다는 뜻이기도 하다 — 두 번째 파드는 busybox 인데 라벨만 달고 통과했다.

파드 재시작은 없었고 컨슈머 오프셋도 계속 올라간다. 프로브와 앱 경로가 안 끊겼다.

걸린 것 둘

브로커 안에서 도는 관리 CLI 가 멈췄다. kafka-topics.sh --describe 가 타임아웃으로 끝났다. 클라이언트는 접속한 브로커에서 리더 목록을 받은 뒤 각 리더에 9092 로 직접 붙는데, 출처를 앱으로만 두니 브로커에서 브로커로 가는 9092 가 막혔다. 서비스 경로는 영향이 없다 — 복제는 9091, 컨트롤러는 9090, 오퍼레이터는 8443 을 쓴다. 9092 출처에 브로커 자신을 더해 풀었다. 브로커는 이미 그 데이터를 보관하는 주체라 열리는 범위가 늘지 않는다.

mysql 차트 정책이 안 지워졌다. 같은 변경인데 redis 는 반영되고 mysql 은 OutOfSync 로 남았다. 두 Application 의 prune 설정이 다르다.

prune: true    git 에서 없앤 객체를 클러스터에서도 지운다     redis
prune: false   git 에서 없어져도 클러스터에는 남겨 둔다      mysql

mysql 은 StatefulSet 과 PVC 가 실수로 빠질 때 볼륨이 지워지는 것을 막으려고 prune 을 꺼 두었고, 그 설정이 정책 삭제까지 함께 막았다. selfHeal: true 는 둘 다 켜져 있지만 그것은 git 에 있는 객체를 git 값으로 되돌리는 장치라 여기에 관여하지 않는다. 남은 정책은 손으로 지웠다.

5. 대조 — 이은 것과 빌린 것

간극은 메워졌나

10부 끝의 상태는 "코드가 클러스터까지 가는 길은 전부 자동인데, 그 길 끝에서 도는 앱은 검증된 적이 없다"였다. 지금은 대기 입장에서 예매 확정까지가 클러스터 위에서 실제로 돌았고, 그 흐름이 시뮬레이터로 화면에 보이고, 흐름의 약속은 테스트가 되어 CI 의 test 칸을 채웠고, data 로 들어오는 접속은 출처가 지정된 것만 남았다. 검증 안 된 앱은 없어졌다 — 남은 것은 검증 안 된 값들이고, 그 대장은 번외로 넘겼다.

이 편 안에서 닫은 것

E2E 왕복            대기 입장 → 좌석 선점 → 예매 확정이 LAN 에서 끝까지 돌았다
결함 4건            추적 등록 원자화 · 추적 해제 신설 · 입력 검증 · revoked DLT 토픽
ETA                파드마다 제각각이던 예상 시간 → Redis 버킷 90초 창 합산으로 재설계
초기화 API          ADMIN_TOKEN 이 인증이자 존재 스위치 — 미주입 배포에는 라우트 자체가 없다
CI test 칸          queue 정원 불변식 · booking 좌석 정규화 + Redis 미도달 시 실패 가드
data 접속           정책 8건(출처 없음 셋) → 6건(출처 전부 지정)
README 정정         토픽 "둘"→5종 · compose 검증 단계 서술 · VIRTUAL_THREADS 잔재

무엇을 빌렸나 — 부채 장부

Kafka 무인증 평문       허용 라벨을 단 파드는 인증 없이 발행한다 — 인증·TLS 는 인터넷 공개 편
발행 저널 지표 없음      저널 크기를 읽는 함수는 있는데 호출부가 0곳 — 12부
queue 결과 카운터 없음   회수가 세션 만료인지 대기 이탈인지 수치로 못 가른다 — 12부
마이그레이션 도구 없음    booking replica 가 1 에 묶여 파드 증설 실험이 막혀 있다 — 13부 블로커
시계 계약이 git 밖       좌석락 45초·승격 배치 100·이탈 판정 30초는 코드 기본값에만 있다
처리율 창 90초          설계 규칙(세션 미만)과 정면 충돌 — 13부 예상 시간 채점으로 판정
커밋 메시지≠내용 2건     스쿼시 머지가 낡은 MR 제목을 커밋 메시지로 남겼다 — dev 역사에 그대로

실무·보안 되짚기

이 편에서 실제로 만진 것에 맞닿는 것만.

세그먼테이션과 인증은 다른 층이다. NetworkPolicy 로 출처를 좁혔지만 판정 근거는 라벨이고, 라벨은 누구나 적을 수 있는 문자열이다 — 라벨만 단 busybox 가 통과하는 것을 실측으로 확인했다. 이 제한은 실수와 우회 경로를 막는 층이지 신원 증명이 아니다. 신원은 워크로드 인증(mTLS·SASL)의 몫이고, 트리거는 인터넷 공개다.
파괴적 API 는 존재부터 조건부로 한다. 초기화 API 는 토큰 인증에 더해, 토큰이 주입되지 않은 배포에서는 라우트 자체가 등록되지 않는다. "관리용 API 가 실수로 프로덕션에 열려 있었다"는 사고 유형을 설정 실수로 막는 게 아니라 구조로 막는다.
조용히 건너뛰는 테스트는 게이트가 아니다. 테스트가 Redis 에 못 닿으면 로컬 실행은 건너뛰고 CI 는 실패한다. 이 구분이 없으면 서비스 컨테이너 배선이 깨진 날부터 게이트가 아무것도 지키지 않으면서 통과로 보인다.
스쿼시 머지는 MR 제목을 커밋 메시지로 만든다. 이 편에서 내용과 메시지가 다른 커밋이 dev 에 두 번 남았다 — 브랜치가 바뀌었는데 MR 제목이 낡은 채로 머지 버튼을 눌러서다. 머지 다이얼로그의 커밋 메시지 칸을 확인하는 것이 절차다. 커밋 역사는 나중에 감사하는 쪽이 읽는다.

6. 다음

값의 대장 — 무엇이 가상이고, 설계 문서와 실물이 어디서 갈라졌고, 관측이 무엇을 보고 못 보는지 — 는 번외(설정 대장)에 있다. 12부와 13부가 그것을 입력으로 쓴다.

12부는 관측의 빈 곳을 채운다. 코드에만 있는 계측이 화면까지 실제로 닿는지 확인하고(트레이스·로그), 없는 신호를 배선하고(Kafka·MySQL 지표, 빠진 카운터), 그 위에 앱 대시보드와 클러스터 대시보드를 세운다. 서류에 필요한 것이 여기서 완성된다. 13부는 그 계기판으로 잰다 — 파드 1대의 한계, 파드를 늘렸을 때의 곱, 정원·리소스 확정, 장애 주입, 그리고 stg/prd 스펙 산정.

노트북 홈서버 k3s 구축기 - 10. CI 와 CD

hsb_02 — Sun, 9 Aug 2026 17:06:41 +0900

시리즈 "노트북 홈서버 k3s 구축기" 10부.
지난 편까지 = GitOps 원본이 데스크탑 GitLab이고, push하면 3초 만에 클러스터에 반영된다. 다만 배포되는 것은 인프라뿐이고 앱 세 종은 이미지가 없어 뜨지 않는다.
10부 = CI와 CD. 앞 토막(CI)은 push 한 번으로 검증된 이미지가 레지스트리에 서게 하고, 뒤 토막(CD)은 그 이미지가 노드에서 돌게 하고 무엇이 도는지 git이 적고 있게 한다.

0. 이어받기

9부에서 GitOps 원본을 데스크탑 GitLab으로 옮겼다. cgv-infra에 push하면 webhook을 타고 3초 만에 클러스터에 반영된다.

그 길로 흐르는 것은 인프라뿐이다. 앱 세 종(queue·booking·frontend)은 Deployment·Service·Ingress까지 다 서 있는데 ImagePullBackOff다 — ArgoCD 화면에서 Synced이면서 Degraded. GitOps가 보장하는 것은 "git에 적힌 대로 반영"까지고, 그것이 실행 가능한지는 다른 문제다.

멈춘 자리는 매니페스트에 적힌 이미지 주소다.

# cgv-infra — charts/apps/queue/values.yaml
image:
  repository: registry.cgv.local/queue-go   # 실재하지 않는 주소
  tag: dev

registry.cgv.local은 7부에서 일부러 비워 둔 자리 표시다. 주소가 정해지지 않았는데 먼저 적으면 두 번 고치게 되기 때문이다. 이 편에서 그 자리를 채운다.

이 편은 두 토막이다.

CI   cgv-onprem 에 push  →  검증  →  이미지  →  레지스트리
CD   레지스트리의 이미지  →  노드가 받아서  →  파드로 돈다
     그리고 무엇이 도는지를 git 이 적고 있게 한다

   ── CI ──
1  CI — 검증을 통과한 것만 이미지가 된다      개념 · 표준 8단계 · 게이트
2  어떻게 도는가                           GitLab · 러너 · job · stage
3  세운다                                 러너 · 레지스트리 · 손으로 한 번
4  파이프라인                              태그 · 규칙 · 검사 · 실측

   ── CD ──
5  CD — 배포 엔진은 이미 있다               끊긴 곳 둘
6  노드가 받아오게 한다                     자격 · 배선 · 파드 첫 기동
7  태그를 git 에 되쓴다                     argocd-image-updater

8  대조 · 9  다음

9부는 "클러스터 밖 누구도 클러스터를 건드리지 않는다"를 지키는 편이었다. 10부도 그 성질을 유지한 채로 간다 — 다만 끝에 가면 GitOps 저장소에 쓰는 쪽이 하나 생긴다. 그걸 누구에게 어디까지 줄지가 이 편의 마지막 결정이다.

1. CI — 검증을 통과한 것만 이미지가 된다

손으로 하면 안 되나

이미지는 세 줄이면 올라간다.

docker login  →  docker build  →  docker push

안 되는 게 아니라, 계속 하면 무너진다.

서비스마다 세 줄씩 쳐야 한다      셋이면 아홉 줄.  하나를 잊으면 그 서비스만 옛것
태그를 내가 정해야 한다          어제 올린 게 뭐였는지 내 기억이 장부다
검증이 없다                    깨진 코드도 컴파일만 되면 이미지가 된다

CI는 이 셋을 없앤다 — push가 트리거고, 태그는 규칙이 정하고, 검증을 통과한 것만 이미지가 된다.

CI 의 뜻

CI(Continuous Integration)는 "지속적 통합" — 자주 합치고, 합칠 때마다 자동으로 검증한다. 여럿이 몇 주씩 따로 작업하고 한 번에 합치면 충돌이 수백 개 쌓이고 누구 코드가 범인인지 갈리지 않는다. 자주 합치면 한 번에 섞이는 양이 적고, 합칠 때마다 검증하면 깨진 커밋이 그 자리에서 드러난다.

git과 CI가 보는 것이 다르다. git은 텍스트를 합칠 뿐이라 "충돌 없음"까지만 보장한다. A가 함수 이름을 바꾸고 B가 옛 이름으로 호출하는 코드를 쓰면, 파일이 달라 충돌 없이 합쳐지는데 결과는 컴파일이 안 된다. 합쳐진 결과가 실제로 도는지는 CI가 본다.

혼자 하는 프로젝트에도 값이 있다. 사람 대신 시간이 벌린다 — 어제의 나와 오늘의 내가 서로를 모른다. 그리고 CI는 매번 빈 컨테이너에서 clone부터 다시 하므로, 로컬에 우연히 깔린 것에 기대던 빌드가 거기서 드러난다. "내 PC에서는 됐는데"가 성립하지 않게 된다.

표준 8단계

CI가 검증하고 배달하는 것을 펼치면 여덟이다.

1  lint             내가 쓴 코드의 정적 결함.  컴파일은 되는데 이상하게 도는 자리
2  build            컴파일이 되는가
3  test             단위 테스트
4  secret scan      커밋에 자격(토큰·키·비밀번호)이 섞였는가
5  dependency scan  가져다 쓰는 라이브러리에 알려진 취약점이 있는가
6  package          이미지로 만다
7  image scan       만든 이미지 안에 취약점이 있는가
8  publish          레지스트리에 올린다

손으로 하던 세 줄은 이 중 package(이미지 생성)과 publish(레지스트리 푸시)이다. 나머지가 검증이고, 검증이 빠지면 CI가 아니라 빌드 자동화다. 이미지는 검증을 통과한 결과물이다.

3(test)은 이 편에서 못 넣는다. 저장소에 돌릴 테스트가 0개다 — queue-go에 *_test.go가 없고 booking은 src/test가 없어 -DskipTests로 빌드한다. 코드만 읽고 테스트를 쓰면 껍데기가 되기 쉬워서, 앱을 실제로 띄우고 동작을 보면서 쓰는 11부로 미룬다. 이 편에서는 들어올 자리만 만들어 둔다.

실패하면 막는가 — 게이트

각 단계(Stage)가 실패했을 때 publish를 막을 것인가가 파이프라인의 설계다. 안 막으면 검사는 로그일 뿐이고, 로그는 다음 주면 아무도 안 연다.

막으려면 고칠 수 있어야 한다.

lint · test · secret scan   내가 쓴 코드다.  실패하면 내가 고친다        →  조건 없이 막는다
dependency scan             내가 고른 라이브러리.  버전을 올리면 고쳐진다   →  조건 없이 막는다
image scan                  베이스 이미지의 OS 패키지가 대부분이다         →  조건이 필요하다

eclipse-temurin:21-jre나 nginx를 훑으면 CVE가 수십 개 나오고 상당수는 아직 패치가 없다. 손쓸 수 없는 것으로 막으면 파이프라인이 영구히 빨간불이 되고, 결국 게이트를 끄게 된다 — 게이트가 죽는 방식이 이것이다. 그래서 이미지 스캔만 조건을 붙인다: 수정 가능한 HIGH 이상이면 막는다. 나머지는 기록만 남긴다.

게이트가 가장 강해야 하는 자리는 secret scan이다. 자격이 한 번 커밋에 들어가면 파일에서 지워도 히스토리에 그대로 남아 되돌릴 수 없다.

2. 어떻게 도는가 — GitLab 은 목록을 만들고 러너가 실행한다

`.gitlab-ci.yml` — job 목록을 적는 파일

CI 전체가 저장소 루트의 파일 한 장으로 정의된다. GitLab은 그 파일 하나만 읽고, 서비스가 몇이든 job을 그 안에 적는다.

job은 코드가 아니라 "할 일" 한 덩어리다.

build-queue:                 # job 이름.  아무거나 된다
  script:                    # 돌릴 명령.  이게 본체다
    - docker build ...

파일에 적혀 있는 동안은 글자다. push가 그 글자에 대상 커밋을 붙여 실체로 만든다. 한 push로 생긴 job 묶음을 파이프라인이라 부른다.

stage — 순서 칸

job이 여럿이면 순서가 필요하다. stage는 종류가 아니라 순서 칸이다.

같은 stage 의 job      순서가 없다.  동시에 돌 수 있는 후보
stage 와 stage 사이    앞 stage 가 전부 성공해야 다음 stage 가 열린다

나누는 기준은 한 줄이다 — 앞것이 실패했을 때 뒷것을 돌릴 이유가 없으면 stage를 나눈다. 20초짜리 검사가 깨졌는데 3분짜리 빌드를 돌릴 이유가 없으니 그 사이에 벽을 세우고, 서로 무관한 검사끼리는 같은 stage에 나란히 둔다.

러너 — 가져가서 실행하는 쪽

GitLab은 파일을 읽고 job 목록을 만드는 데서 멈춘다. 실행까지 하면 저장소 서버가 빌드마다 눌리기 때문에, 실행은 밖으로 뺐다. 그 실행을 맡는 상주 프로그램이 러너다.

방향이 한쪽이다. 러너가 GitLab에 "내 몫 일 있냐"고 주기적으로 묻고, GitLab은 러너를 부르지 못한다. 그래서 러너는 GitLab에서 보이는 자리에 있을 필요가 없고 — 실제로 러너 컨테이너에는 열린 포트가 하나도 없다 — 밖으로 나갈 수만 있으면 어디서든 돈다.

러너는 파일을 읽지 않는다. GitLab이 파일을 해석해서 job 하나치 명세(이미지 · script · 변수 · 저장소 주소와 커밋 · 그 job 전용 토큰)만 넘긴다. stages도 extends도 러너에게는 안 간다 — 이미 펼쳐진 결과만 온다. 그래서 러너는 프로젝트가 뭔지, 언어가 뭔지 모르고, 몰라도 된다. 언어는 job의 image:가 정하고 러너는 그 이미지를 띄울 뿐이다.

한 바퀴

①  git push                커밋이 GitLab 에 도착한다
②  GitLab 이 파일을 읽는다   job 을 만든다.  첫 stage 는 pending · 뒤 stage 는 created
③  러너가 물어서 가져간다     pending 인 것만.  created 는 후보에 안 오른다
④  명세를 받는다            이미지 · script · 변수 · 저장소 · 커밋 · 토큰
⑤  실행한다                컨테이너를 띄우고 → clone → script 한 줄씩 → 로그를 실시간 전송
⑥  보고하고 치운다          종료 코드 0 이면 success → 컨테이너 삭제 → 다시 ③
⑦  stage 가 넘어간다        앞 stage 가 전부 success 면 다음 stage 가 created → pending
                          하나라도 failed 면 뒤 stage 는 skipped

성패는 로그가 아니라 종료 코드로 정해진다. script는 위에서부터 돌다가 0이 아닌 코드가 나오면 그 자리에서 멈춘다 — push 앞줄에 검사를 두면 통과 못 한 이미지는 올라가지 않는다. 게이트는 별도 장치가 아니라 이 순서다.

컨테이너는 job마다 새로 뜨고 끝나면 지워진다. 그 안의 소스·임시 파일·로그인 자격이 전부 사라지고, GitLab에는 로그와 종료 코드만 남는다.

3. 세운다 — 러너 · 레지스트리 · 손으로 한 번

러너를 어디에 — 데스크탑

클러스터 안       파드로 뜬다.  빌드가 노드 자원과 디스크를 쓴다
데스크탑 Docker   GitLab 옆에 컨테이너로                       ← 고른 것

노드 셋이 USB SSD 한 장 위에 있고, 13부에서 그 클러스터에 부하를 걸어 stg·prd 스펙을 산정한다. 빌드가 같은 디스크를 쓰면 그때 나올 숫자가 흔들린다. 데스크탑도 자원이 남아서 고른 게 아니라(이 시점 RAM 16GB에 WSL VM 상한 6GB, 그중 GitLab이 3GB — 파이프라인이 자리 잡은 뒤 RAM 20GB·상한 8GB로 늘린다), 눌리는 곳이 나중에 재야 할 곳이 아니라서다.

누구 일을 받나 — `cgv` 그룹

프로젝트 러너    한 저장소의 job 만
그룹 러너        그룹 안 모든 저장소의 job                     ← 고른 것
인스턴스 러너    이 GitLab 전체.  관리자만 만든다

이미지를 만드는 저장소는 cgv-onprem 하나지만, cgv-infra에도 CI가 붙는다 — 이미지 빌드가 아니라 매니페스트 검사(렌더가 깨지는지, 스키마가 맞는지, 봉인본이 빠졌는지)다. 러너 하나로 둘 다 받게 그룹에 둔다. 대가는 cgv-infra의 job도 이 러너의 권한을 그대로 물려받는 것 — 두 저장소를 나 혼자 고치는 동안은 두고, 사람이나 저장소가 늘면 프로젝트 러너로 가른다.

job 을 어떻게 돌리나 — `docker` executor

shell     러너 안에서 직접 명령을 돈다.  도구를 미리 깔아 둬야 하고 그 안이 쌓인다
docker    job 마다 컨테이너를 새로 띄운다                      ← 고른 것

앱 셋의 빌드 환경이 Go·Maven·nginx로 다르다. job마다 필요한 이미지로 새로 뜨는 쪽이 맞다.

이미지 빌드는 어떻게 — 소켓 마운트

docker executor를 고르면 바로 걸리는 게 있다. job 컨테이너 안에는 Docker가 없다.

Docker는 실제로 일하는 데몬(dockerd, root로 돈다)과 부탁하는 명령어(docker)로 나뉘어 있고, 둘이 대화하는 통로가 /var/run/docker.sock이라는 파일이다. 크기 0짜리 소켓 파일이고 오가는 것은 HTTP다. docker build를 쳐도 그 명령이 빌드하는 게 아니라 — 소켓 너머 데몬에게 부탁하는 것이다.

docker build  ──▶  /var/run/docker.sock  ──▶  dockerd 가 실제로 빌드한다

이 소켓 파일을 컨테이너 안에 마운트하면, 컨테이너 안의 docker 명령이 데스크탑 데몬에게 부탁할 수 있게 된다. 그게 소켓 마운트다. 대안인 dind(컨테이너 안에 데몬을 또 띄우는 것)는 격리되는 대신 privileged와 메모리가 들고, job마다 데몬이 새것이라 빌드 캐시가 매번 사라진다. 띄울 RAM이 없어 소켓으로 간다.

대가는 권한이다. 소켓으로는 빌드만 시킬 수 있는 게 아니라 Docker API 전부를 부를 수 있다 — 데스크탑의 /를 통째로 마운트한 컨테이너를 띄우라는 요청도 그중 하나고, 데몬이 root로 도니 소켓을 쥔 쪽은 사실상 데스크탑 root다. 거기에 GitLab 컨테이너와 레지스트리 볼륨이 있다. RAM에 여유가 생기면 dind로 바꾼다.

세우고 등록한다

러너 설정은 두 군데로 갈려 있다. 범위·태그·Protected는 GitLab이 들고 있고, executor·이미지·볼륨은 러너 쪽 파일이 들고 있다. 그래서 GitLab에서 먼저 만든다.

그룹 cgv → Build → Runners → Create group runner. 태그 칸에 docker를 적는다 — 태그는 러너가 여럿일 때 job을 어디로 보낼지 고르는 이름표고, GitLab은 그 글자의 뜻을 모르고 같은지만 본다. Protected(보호 브랜치 job만 받기)는 아직 안 켠다 — 돌릴 job도 브랜치 규칙도 없는데 켜면 첫 파이프라인이 안 도는 것부터 겪는다. 저장하면 glrt-로 시작하는 토큰이 그 화면에 한 번만 표시된다.

러너 프로세스는 GitLab을 띄우고 있는 데스크탑 docker-compose.yml에 서비스로 하나 더 넣는다.

# 데스크탑의 docker-compose.yml — 서비스 하나 추가
gitlab-runner:
  image: gitlab/gitlab-runner:v19.2.1     # GitLab CE 와 같은 버전
  volumes:
    - gitlab-runner-config:/etc/gitlab-runner
    - /var/run/docker.sock:/var/run/docker.sock   # 러너가 job 컨테이너를 띄우는 통로

뜬 것만으로는 아무 GitLab도 모르는 빈 일꾼이다. 아까 받은 토큰으로 도커컴포즈로 생성한 깃랩에 접속(exex)해서 등록한다.

docker exec -it gitlab-runner gitlab-runner register \
  --non-interactive \
  --url http://192.168.0.167:8929 \
  --token <glrt- 토큰> \
  --executor docker \
  --docker-image alpine:3.20 \
  --docker-volumes /var/run/docker.sock:/var/run/docker.sock

--url · --token       어느 GitLab 의 어느 범위 job 을 받을지.  판단 재료는 GitLab 쪽에 있다
--executor docker     job 마다 컨테이너를 새로
--docker-image        job 이 image: 를 안 적었을 때의 기본값.  실제 job 은 전부 적는다
--docker-volumes      job 컨테이너 안에도 소켓을 넣는다 — script 의 docker build 가 데몬에 닿게

소켓은 두 번 나온더. docker-compose.yml에 그리고, exec로 접속해서 깃랩에 설정 등록할때. 이는 이유가 갈린다.

compose의 것은 러너가 job 컨테이너를 만들려고(러너 자신도 컨테이너라 안에 데몬이 없다),
register의 것은 job 안의 docker build가 데몬에 닿으려고다.
그리고 러너가 부탁해 만들어진 job 컨테이너는 러너 안이 아니라 러너 옆에 생긴다 — 만든 쪽이 데스크탑 데몬이기 때문이다. 파이프라인이 도는 동안 docker ps를 치면 gitlab·gitlab-runner 옆에 runner-xxxx-concurrent-0이 잠깐 보인다.

register가 한 일은 /etc/gitlab-runner/config.toml에 항목 하나를 적은 것이다. 러너는 이후로 그 파일만 읽고 돈다 — 파일 안의 토큰으로 GitLab에 "내 몫 job 있냐"고 몇 초마다 묻고, 받으면 파일 안의 설정(executor·기본 이미지·소켓)대로 job 컨테이너를 띄워 실행하고, 끝나면 보고하고 다시 묻는다. 그 경로를 볼륨으로 빼 둔 이유가 이것이고, 컨테이너를 다시 만들어도 등록이 남는다. 등록이 끝나면 그룹 러너 목록에 Online·Idle로 뜬다. Idle은 붙어서 묻고는 있는데 받아 갈 job이 없다는 뜻이다.

레지스트리 — 이미지를 둘 곳

러너가 빌드한 이미지는 데스크탑 데몬 안에만 남는다. 노드 셋은 그 안을 들여다볼 방법이 없다. 양쪽이 같이 보는 자리가 필요하고, 그게 레지스트리다.

따로 세우지 않고 GitLab 내장 Container Registry를 쓴다 — 이미 있는 것을 쓰면 자격과 백업이 한 자리에 모인다. 켜는 것은 데스크탑 docker-compose.yml의 두 줄이다.

GITLAB_OMNIBUS_CONFIG: |
  external_url 'http://192.168.0.167:8929'
  registry_external_url 'http://192.168.0.167:5050'    # 더한 줄 — 레지스트리 프로세스가 뜬다
ports:
  - '8929:8929'
  - '5050:5050'                                        # 더한 줄

같은 컨테이너인데 포트가 갈리는 것은 규약이 달라서다. git은 git 프로토콜로, 레지스트리는 Docker Registry API로 대화하고, docker push는 항상 호스트[:포트]/경로:태그 형태로만 부르기 때문에 한 포트에서 경로로 가를 수 없다.

그 형태가 곧 이미지 이름이다.

192.168.0.167:5050  /  cgv/cgv-onprem  /  queue-go  :  dev
└─ 어느 서버 ────┘     └─ 어느 프로젝트 ┘   └ 이름 ┘   └ 태그 ┘

가운데가 GitLab의 그룹/프로젝트 경로 그대로다. 레지스트리 프로세스와 저장 공간은 하나고, 프로젝트마다 갈리는 것은 경로와 권한이다 — 그 프로젝트에 권한이 있어야 그 경로를 읽고 쓴다.

http://로 연 것은 평문으로 열겠다는 뜻이다. TLS를 붙이려면 자체 서명 인증서를 만들어 노드 셋과 데스크탑 Docker에 CA를 심어야 하는데, 14부에서 전 구간 TLS를 할 때 어차피 다시 한다 — 두 번 할 일이라 지금은 안 한다. 대가는 같은 망에서 들여다보면 이미지도 로그인 토큰도 읽힌다는 것이고, 닫는 시점은 14부다.

컨테이너를 다시 올리고 확인한다.

$ curl -i http://192.168.0.167:5050/v2/
HTTP/1.1 401 Unauthorized
Www-Authenticate: Bearer realm="http://192.168.0.167:8929/jwt/auth",service="container_registry"

401이 맞는 응답이다. "인증하고 오라"는 뜻이고, 인증 서버로 GitLab의 8929를 가리킨다 — 둘이 제대로 물려 있다는 확인이다.

데스크탑 Docker는 레지스트리를 HTTPS로 가정하므로, 평문 주소를 예외로 등록해야 한다.

// Docker Desktop → Settings → Docker Engine
{ "insecure-registries": ["192.168.0.167:5050"] }

전역 해제가 아니라 이 주소 하나만 인증서 검증을 건너뛰고 평문으로 내려간다. 주소는 이미지 이름 앞부분과 글자까지 같아야 걸린다. 데몬 설정이라 적용하면 데몬이 재시작하고, 그 데몬이 물고 있는 GitLab·러너 컨테이너도 같이 내려갔다 올라온다.

손으로 한 번 올린다

CI를 붙이기 전에 경로부터 확인한다. 여기서 안 되면 나중에 CI 문제인지 레지스트리 문제인지 갈리지 않는다.

자격은 personal access token으로 만든다. scope는 read_registry·write_registry 둘 — git을 읽는 read_repository와는 다른 칸이고, 올리는 데는 읽기·쓰기가 둘 다 있어야 한다.

docker login 192.168.0.167:5050
docker build -t 192.168.0.167:5050/cgv/cgv-onprem/queue-go:test ./queue-go
docker push  192.168.0.167:5050/cgv/cgv-onprem/queue-go:test

-t에 적은 이름이 곧 보낼 주소다. Go 빌드가 128초, push가 끝나면 GitLab의 Deploy → Container Registry에 cgv-onprem/queue-go가 나타난다.

여기서 셋이 한 번에 확인된다 — Dockerfile이 로컬 compose 밖에서도 돌고, 이미지 경로가 맞고, 자격이 통한다. 그리고 그 화면에 하나 더 적혀 있다: Cleanup is not scheduled. 올라온 태그를 지우는 규칙이 없다는 뜻인데, 태그를 늘리기 전에 걸어야 하는 것이라 파이프라인을 붙이면서 함께 정리한다.

4. 파이프라인 — 손으로 한 것을 규칙으로

손으로 하던 login·build·push를 .gitlab-ci.yml로 옮긴다. 파일을 쓰기 전에 정할 것이 둘 있다 — 이미지에 붙일 이름과, 쌓일 이름을 지우는 규칙이다.

태그부터 정한다

docker build -t ...:<여기>에 무엇을 넣을지가 배포 방식을 통째로 가른다.

지금 차트는 tag: dev 고정에 pullPolicy: IfNotPresent다. IfNotPresent는 "노드에 그 이름이 이미 있으면 안 받아온다"는 뜻이라, :dev를 새로 빌드해 올려도 노드는 예전에 받아 둔 :dev를 그대로 쓴다. 배포했는데 안 바뀐다.

A  태그를 고정한다     :dev 를 계속 덮어쓴다.  매니페스트는 안 고쳐도 된다
B  태그를 매번 바꾼다   커밋마다 다른 이름.  매니페스트에 그 이름을 적어야 한다

A는 배포를 시킬 방법이 없다. 매니페스트가 안 변하니 ArgoCD는 할 일이 없고, 파드를 다시 띄우려면 CI가 클러스터에 kubectl rollout restart를 걸어야 한다 — 클러스터 접근 자격이 밖으로 나가고, 9부에서 지킨 "밖이 안을 안 건드린다"가 깨진다. 이전 :dev가 무엇이었는지 기록도 없어 롤백이 안 된다.

B로 간다. 매니페스트의 tag 한 줄이 바뀌면 ArgoCD가 sync하고 파드가 교체된다 — 트리거가 git 커밋이 되어 9부에 세운 길을 그대로 탄다. 롤백은 git에서 이전 태그로 되돌리는 일이 된다.

이름에는 셋을 담는다.

dev-42-a1b2c3d
 │   │    └ 커밋 해시.  이미지와 커밋이 1:1 — 장애 때 "지금 도는 게 어느 코드냐" 가 태그로 나온다
 │   └ 파이프라인 번호.  1 씩 늘어 순서가 눈에 보인다
 └ 브랜치.  stg 브랜치가 생기면 목록에서 갈린다

번호만 쓰면 어느 커밋인지 몰라 찾아 들어가야 하고 같은 커밋을 재빌드하면 내용이 같은 이미지가 둘 생긴다. 해시만 쓰면 순서를 못 읽는다.

GitLab이 job에 넣어 주는 변수를 그대로 쓴다 $CI_COMMIT_REF_SLUG·$CI_PIPELINE_IID·$CI_COMMIT_SHORT_SHA.

늘리기 전에 지우는 쪽을 먼저 건다

파이프라인이 붙으면 커밋마다 서비스 셋씩 태그가 쌓인다. cgv-onprem의 Settings → Packages and registries → Container registry cleanup policies.

Enable cleanup policy    켠다
Run cleanup              Every day
Keep the most recent     10 tags per image name
Remove tags older than   7 days        기본값 90 일에서 줄였다
Remove tags matching     .*            필수 칸.  전부를 후보로 올린다

GitLab은 Remove tags matching으로 후보를 모은 뒤 최근 10개와 7일 안쪽을 후보에서 뺀 나머지를 지운다. 하루에 몇 번을 올리든 최근 10개는 항상 남고, 롤백할 여지가 그만큼이다. 90일을 7일로 줄인 것은 — 최근 10개 유지가 이미 롤백을 보장하는데 90일을 얹으면 처음 석 달 동안 아무것도 안 지워지기 때문이다.

태그를 지워도 디스크는 바로 안 준다. 규칙은 목록에서 없애는 데까지고, 레이어를 치우는 것은 별도 작업(gitlab-ctl registry-garbage-collect)이다. 규칙만 걸어 두고 볼륨이 실제로 부풀면 돌린다.

파일의 뼈대 — 설정 · job · 틀

.gitlab-ci.yml의 최상위 이름은 세 부류다.

설정    workflow · stages · default · variables     GitLab 이 정해 둔 예약어
job     그 밖의 이름 전부.  실제로 도는 것
틀      점(.)으로 시작하는 이름.  실행되지 않고 extends 로 가져다 쓴다

default는 적는 순간 모든 job에 자동으로 붙는 것이다. 셋을 둔다.

러너 태그 docker — 지목해야 그 러너가 가져간다
interruptible: true — 같은 브랜치에 새 커밋이 오면 돌던 파이프라인을 취소한다. 옛 커밋의 결과는 볼 이유가 없는데 실행 슬롯을 계속 잡는다
timeout: 30m — 프로젝트 기본값 1시간이면 멈춘 job이 그동안 슬롯을 잡는다

variables에는 정해 둔 TAG가 앉는다. 틀은 extends한 job만 받는다. 이제 파일을 위에서부터 짚는다.

workflow — 같은 커밋이 두 번 돌지 않게

파일 맨 위는 "이 push로 파이프라인을 만들까 말까"다. 이 층이 필요한 것은 push 하나가 GitLab 안에서 사건 둘이 되기 때문이다 — "브랜치에 새 커밋이 왔다"와 "열린 MR의 소스 브랜치가 바뀌었다". 사건마다 따로 판단하므로 MR이 열린 브랜치에 push하면 같은 커밋이 두 번 돈다. job에 조건(rules)을 적기 시작하면 "브랜치 파이프라인만 만든다"는 GitLab 기본 동작이 꺼져서, 이 위층에서 명시해야 한다.

workflow:
  rules:
    # MR 사건이면 만든다.  "머지해도 되나" 를 판정하는 쪽이라 이걸 남긴다
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    # 브랜치 push 인데 그 브랜치에 열린 MR 이 있으면 만들지 않는다.  위에서 이미 만들었다
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    # 브랜치 파이프라인은 dev(머지 결과 검증)만.  일반 브랜치까지 열어 두면 push 를 먼저 하고
    # MR 을 나중에 만들었을 때 push 사건과 MR 생성 사건이 각각 파이프라인을 만든다 —
    # 위의 차단은 "push 시점에 MR 이 이미 열린" 경우만 걸러서 그 반대 순서를 못 막는다
    - if: $CI_COMMIT_BRANCH == "dev"

규칙은 위에서부터 보다가 처음 맞는 줄에서 멈추고, 아무 줄에도 안 걸리면 안 만든다. 일반 브랜치는 MR을 열어야 CI가 돌고, 그 대신 파이프라인은 언제나 하나다.

stage 다섯, 그리고 job 지도

stage는 다섯을 선언한다. 벽마다 근거가 있다 — 검사가 깨졌는데 분 단위 빌드를 돌릴 이유가 없고, 스캔의 대상은 build가 만든 이미지고, 스캔에 걸린 이미지는 레지스트리에 안 올린다.

stages:
  - check      # 코드를 훑는다.  여기서 걸리면 뒤로 안 간다
  - test       # 단위 테스트.  11부에서 채운다
  - build      # 이미지를 만든다.  올리지는 않는다
  - scan       # 방금 만든 이미지의 취약점을 훑는다
  - publish    # 스캔까지 통과한 것을 레지스트리로.  dev 에서만 생긴다

build·scan·publish가 다른 job인데도 이미지가 이어지는 것은 소켓 마운트 덕이다. build가 만든 이미지는 job 컨테이너가 아니라 데스크탑 데몬에 남고, 다음 stage의 job이 같은 이름($SVC:$TAG)으로 그것을 본다. dind였으면 job마다 데몬이 새것이라 이미지를 파일로 저장해 넘겨야 했고, 이 분리 자체가 성립하지 않았다. 갈라서 얻는 것은 둘이다 — 실패가 job 단위로 화면에 갈리고(scan:booking 빨강이면 클릭 없이 원인이 보인다), 스캔 결과를 MR 화면에 붙일 자리가 생긴다.

이 다섯을 채우는 job이 열셋이다.

stage      job                                  이미지           하는 일
check      secret-scan                          gitleaks        저장소 전체.  과거 커밋까지
           dep-scan:queue-go                    trivy           go.sum 의 의존성 취약점
           lint:queue-go                        golang:1.26     go vet
           lint:booking                         maven           컴파일 + SpotBugs
test       (비어 있다)                                           11부에서 채운다
build      build:{queue-go·booking·frontend}    docker:27-cli   이미지를 만든다
scan       scan:{...}                           trivy           만든 이미지를 훑는다
publish    publish:{...}                        docker:27-cli   dev 에서만 생긴다

lint와 dep을 나눠 두는 것은 실패의 원인과 대응이 다르기 때문이다. lint는 내가 코드를 건드려야 새로 실패하고 고치는 법도 코드 수정이다. dep은 코드가 그대로여도 새 CVE가 발표되면 어제 통과한 커밋이 오늘 실패하고, 고치는 법은 버전 올리기다. 합쳐 두면 "내가 뭘 잘못했나"부터 뒤지게 된다.

frontend는 정적 파일뿐이라 check·test에 없다 — build·scan·publish만 타고, scan이 그 서비스의 유일한 검사가 된다. booking의 의존성 검사가 check에 따로 없는 것도 같은 자리에서 해결된다 — scan:booking이 이미지 안의 app.jar를 직접 읽으므로, 선언(pom.xml)이 아니라 실제로 담긴 것을 판정한다.

check — 항상 도는 것과 바뀔 때만 도는 것

secret scan은 조건 없이 모든 커밋에서 돈다. 어느 파일이 바뀌든 자격이 섞였을 수 있어서다.

secret-scan:
  stage: check
  image:
    name: zricethezav/gitleaks:latest
    entrypoint: [""]   # 이미지가 gitleaks 를 바로 실행하게 돼 있어, script 를 넣으려면 비운다
  variables:
    GIT_DEPTH: 0       # 기본은 얕은 clone — 과거 커밋이 안 온다.  히스토리 전체를 받는다
  script:
    - gitleaks detect --source . --no-banner --redact   # redact = 찾은 값을 로그에 안 찍는다

dep 검사도 조건이 없다 — 코드가 안 바뀌어도 새 CVE 하나로 결과가 바뀌는 검사라, "바뀐 파일"을 조건으로 걸 이유가 없다.

dep-scan:queue-go:
  stage: check
  image:
    name: aquasec/trivy:latest
    entrypoint: [""]
  variables:
    TRIVY_NO_PROGRESS: "true"                        # DB 내려받기 진행바를 로그에 안 찍는다
    TRIVY_CACHE_DIR: /root/.cache/trivy/$CI_JOB_NAME
  script:
    - trivy fs --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 ./queue-go

대상이 ./queue-go 하나다. go.sum은 간접 의존까지 버전이 전부 파일에 적혀 있어 원격 조회 없이 판정된다. pom.xml은 반대다 — 버전을 부모 POM이 정하므로 읽으려면 Maven Central에 물어야 하고, 같은 IP에서 빌드가 판마다 의존성을 수백 개 받고 있으면 그 조회가 429(Too Many Requests)로 차단된다. Java 의존성은 scan:booking이 app.jar를 직접 읽는 것으로 판정한다 — 잃는 것은 build 전에 잡는 이점 하나다.

서비스별 lint는 다르다. 저장소 하나에 서비스 셋이 들어 있어서(모노레포), 조건이 없으면 booking 한 줄을 고쳐도 세 서비스의 job이 다 돈다. rules: changes가 커밋에서 바뀐 파일을 보고 그 job을 만들지 말지를 정한다.

lint:queue-go:
  stage: check
  image: golang:1.26
  script:
    - cd queue-go
    - go vet ./...          # 컴파일은 되는데 의도와 다르게 도는 자리를 잡는다
  rules:
    - changes: [ "queue-go/**/*", ".gitlab-ci.yml" ]

안 바뀐 서비스의 job은 건너뛰는 게 아니라 화면에 아예 없다. .gitlab-ci.yml을 목록에 넣는 것은 — CI 파일만 고친 커밋에서 job이 하나도 안 생기면 고친 게 도는지 확인할 방법이 없어서다.

booking의 lint는 SpotBugs다. 소스가 아니라 컴파일된 바이트코드를 훑는 도구라 compile이 먼저 온다.

lint:booking:
  stage: check
  image: maven:3.9-eclipse-temurin-21
  variables:
    MAVEN_OPTS: "-Xmx768m"
  script:
    - cd booking
    - mvn -B compile spotbugs:check
  artifacts:
    when: always               # 실패했을 때야말로 받아 봐야 한다
    expire_in: 1 week
    paths:
      - booking/target/spotbugsXml.xml
  rules:
    - changes: [ "booking/**/*", ".gitlab-ci.yml" ]

두 설정에 각각 이유가 있다.

MAVEN_OPTS — JVM은 힙 상한을 안 주면 컨테이너가 보는 메모리의 25%를 잡는다. job 컨테이너에 메모리 제한이 없어 VM 전체(7.8GB)를 보고 혼자 2GB 가까이 쓴다. 동시에 도는 job 수만큼 곱해지므로 빌드 스테이지와 같은 값으로 고정한다.
artifacts — 콘솔에는 결함 개수만 남고 어느 파일 몇 줄인지는 spotbugsXml.xml에 있다. job이 끝나면 컨테이너째 사라지므로 리포트를 GitLab에 올려 둬야 실패를 추적할 수 있다.

검사 규칙은 booking/pom.xml(플러그인 선언)과 booking/spotbugs-exclude.xml(제외 필터)에 있다. 생성자 주입으로 받은 스프링 빈을 필드에 저장하는 자리가 전부 EI_EXPOSE_REP 계열로 걸리는데, 컨테이너가 관리하는 싱글턴이라 방어적 복사가 성립하지 않는다. 그 두 패턴만 제외하고 나머지 Medium 이상은 그대로 실패로 본다.

build · scan · publish — 서비스마다 셋, 올리는 건 dev 만

서비스마다 build·scan·publish job이 하나씩 서고, 같은 서비스의 셋이 같은 경로 규칙을 공유한다 — 안 바뀐 서비스는 셋이 함께 안 생긴다. publish에만 조건이 하나 더 붙는다.

publish:queue-go:
  extends: .publish
  variables:
    SVC: queue-go
  rules:
    - if: $CI_COMMIT_BRANCH == "dev"    # dev 가 아니면 이 job 은 만들어지지 않는다
      changes: [ "queue-go/**/*", ".gitlab-ci.yml" ]

build와 scan은 브랜치에서도 돌린다 — 컴파일이 되는지, 취약점이 있는지는 머지 전에 걸러야 한다. 올리는 것은 다르다. 아무 브랜치에서나 push되면 리뷰를 통과하지 않은 이미지가 배포 후보와 같은 자리에 쌓인다.

그래서 브랜치·MR 파이프라인은 check → build → scan에서 끝나고, publish job은 화면에 아예 없다.

부수 효과로 태그가 정리된다 — 실험 브랜치 이름이 섞인 태그가 레지스트리에 안 생기고 dev-*만 남는다.

브랜치에서도 build는 도니 레이어 캐시는 데스크탑에 그대로 쌓이고, 머지 뒤의 build가 그 캐시로 빨리 끝나고 publish가 올린다. 서비스마다 태그가 다른 상태가 정상이 된다 — 안 바뀐 서비스는 예전 이미지가 그대로 맞는 것이다.

틀 — 절차는 한 번만 적는다

build 이후의 절차는 서비스 셋이 똑같다. 언어별 차이가 CI가 아니라 각 서비스의 Dockerfile 안에 있어서다 — CI는 "그 디렉터리에서 docker build 해라"만 알고, 그 안에서 Go를 컴파일하는지(queue-go) Maven이 도는지(booking) 복사만 하는지(frontend)는 멀티스테이지 Dockerfile이 품고 있다. 나온 이미지를 훑고(scan) 올리는(publish) 데는 애초에 언어 구분이 없다.

그래서 절차를 틀에 한 번만 적고, 각 job은 SVC 값 하나만 바꾼다. SVC는 서비스 디렉터리 이름이고, 그 한 값이 빌드 컨텍스트(./$SVC)와 이미지 이름(.../$SVC:$TAG)을 함께 정한다 — 디렉터리 이름과 이미지 이름을 같게 지어 둔 것이 여기서 값을 한다.

.build:
  stage: build
  image: docker:27-cli        # 등록 기본값 alpine 엔 docker 명령이 없다.  CLI 만 든 이미지
  dependencies: []
  script:
    # --pull: 같은 태그라도 업스트림은 패치를 넣어 다시 굽는다.  로컬 캐시가 있으면 낡은 것으로 빌드된다
    - docker build --pull -t "$CI_REGISTRY_IMAGE/$SVC:$TAG" "./$SVC"

.scan:
  stage: scan
  image:
    name: aquasec/trivy:latest
    entrypoint: [""]
  dependencies: []
  variables:
    TRIVY_NO_PROGRESS: "true"
    TRIVY_CACHE_DIR: /root/.cache/trivy/$CI_JOB_NAME
    TRIVY_TIMEOUT: 20m
  script:
    # 수정 가능한 HIGH 이상이면 종료 코드 1 → job 실패 → publish 가 안 열린다
    - trivy image --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 "$CI_REGISTRY_IMAGE/$SVC:$TAG"

.publish:
  stage: publish
  image: docker:27-cli
  dependencies: []
  interruptible: false        # push 중간에 끊기면 레이어가 일부만 올라간 상태로 남는다
  before_script:
    # job 마다 발급되고 끝나면 폐기되는 토큰.  만들 것도 보관할 것도 없다
    # -p 로 주면 비밀번호가 명령줄 인자에 남으므로 파이프로 넣는다
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
  script:
    - docker push "$CI_REGISTRY_IMAGE/$SVC:$TAG"

build:queue-go:
  extends: .build
  variables:
    SVC: queue-go             # booking · frontend 도 이 값 하나만 다르다

로그인이 .publish에만 있다 — build는 공개 베이스 이미지만 받아오고, scan은 데몬에 있는 로컬 이미지를 보므로 레지스트리 자격이 필요 없다. 주소와 자격도 파일에 안 적는다: $CI_REGISTRY_IMAGE가 "레지스트리 주소 + 프로젝트 경로"를 담고 있어 레지스트리가 옮겨 가도 이 파일은 안 고친다 — 하드코딩된 IP가 하나 안 늘었다.

틀 셋에 공통인 dependencies: []는 앞 stage의 아티팩트를 안 받는 선언이다. 기본값이 "앞 stage 전부에서 받는다"라, 이게 없으면 lint:booking이 남긴 SpotBugs 리포트를 build·scan·publish가 job마다 내려받고 풀고 지운다 — 쓰지도 않는 파일에 시간을 쓴다.

.scan의 변수 셋은 각각 이렇다.

TRIVY_NO_PROGRESS — 진행바 갱신이 로그 줄로 쌓여 한 번의 내려받기가 수백 줄이 된다. 결과 표가 그 뒤로 밀린다.
TRIVY_CACHE_DIR — trivy는 캐시 디렉터리에 배타 잠금을 건다. scan job 셋이 한 디렉터리를 공유하면 먼저 잡은 하나만 돌고 나머지는 잠금 대기로 죽는다. job 이름으로 하위 폴더를 갈라 잠금이 안 겹치게 한다.
TRIVY_TIMEOUT — 기본 제한 5분 안에 DB 내려받기까지 들어간다. Java DB가 903MB라 캐시가 비었거나 만료(3일)된 판은 내려받기만으로 제한을 넘기고, 취약점 유무와 무관하게 job이 죽는다.

반복해서 받지 않게 — 캐시는 두 층이다

job 컨테이너는 끝나면 지워진다. 안에서 내려받은 것도 같이 사라져, 손대지 않으면 매 판이 처음이다 — trivy 취약점 DB 103MB에 Java DB 903MB, Maven 의존성, Go 모듈을 판마다 다시 받는다. 해법은 하나다: 죽는 곳에서 받은 것을 안 죽는 곳에 둔다. 그게 캐시다.

그런데 이 파이프라인에서는 "죽는 곳"이 두 군데다. 같은 Maven 다운로드가 job에 따라 다른 방에서 일어난다.

lint:booking     job 컨테이너 안에서 mvn 이 직접 돈다
                 받은 jar 는 그 컨테이너 안에 쌓인다 → job 끝 = 컨테이너 삭제 = 같이 삭제

build:booking    job 컨테이너는 "docker build 해라" 명령만 소켓으로 보낸다
                 실제 빌드는 데스크탑 데몬의 세계에서 돈다 — 거기서 mvn 이 또 받는다
                 job 컨테이너와는 다른 방이다

방이 다르면 선반도 따로 놔야 한다. 그래서 두 층이다.

층 하나 — job 컨테이너의 방: 러너 볼륨. 컨테이너 안의 경로 자체를 바깥 창고(이름 붙인 도커 볼륨)로 연결한다. 도구는 평소 쓰던 경로에 쓸 뿐인데 그 문이 밖으로 나 있어서, 컨테이너가 죽어도 내용물은 창고에 남고 다음 job이 그대로 이어받는다 — 러너를 세울 때 소켓 파일 하나를 꽂아 줬던 것과 같은 기술이고, 이번엔 디렉터리다.

# 러너 config.toml — job 컨테이너마다 이 볼륨들이 꽂힌다
volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache",
           "maven-cache:/root/.m2",                # lint:booking 의 의존성
           "trivy-cache:/root/.cache/trivy",       # 취약점 DB.  안에서 job 별 폴더로 갈린다
           "gomod-cache:/go/pkg/mod",              # Go 모듈
           "gobuild-cache:/root/.cache/go-build"]  # Go 컴파일 결과.  go vet 도 컴파일을 한다

이 볼륨이 둘째 방에는 안 닿는다 — 볼륨은 job 컨테이너에 꽂는 것인데, build의 다운로드는 그 컨테이너 밖(데몬)에서 일어난다. 옆방에 꽂은 콘센트다.

층 둘 — 데몬의 방: 레이어 캐시, 그리고 그 틈. 데몬에는 선반이 기본으로 하나 있다. 레이어 캐시 — COPY pom.xml의 내용이 지난번과 같으면 그 아래 RUN(의존성 다운로드)의 결과를 통째로 재사용한다. 평소 build가 십몇 초로 끝나는 이유다. 약점은 조건부다: 그 파일이 한 글자라도 바뀌면 "재료가 달라졌다"로 보고 아래를 전부 무효로 만들어 수백 개를 처음부터 다시 받는다.

pom.xml이 바뀌는 커밋이 언제인가 — 의존성을 올린 커밋, "이거 올려도 되나"를 CI로 제일 급히 확인하고 싶은 바로 그 순간이다.

그 틈을 메우는 것이 BuildKit의 캐시 마운트다. BuildKit은 도커가 이미지를 굽는 빌드 엔진인데, RUN 한 줄에 레이어 바깥의 전용 선반을 꽂아 주는 기능이 있다. 레이어가 무효가 돼 RUN이 다시 돌아도 그 선반은 무효화와 무관하게 남아 있으니, Maven이 이미 있는 것은 건너뛰고 바뀐 것만 받는다 — 층 하나의 볼륨과 똑같은 발상을 데몬의 세계 안에서 한 번 더 한 것이다.

# syntax=docker/dockerfile:1                       ← 이 기능을 쓰는 문법 버전 선언
RUN --mount=type=cache,target=/root/.m2 mvn -q -B dependency:go-offline    # booking
RUN --mount=type=cache,target=/go/pkg/mod go mod download                  # queue-go

정리하면:

방                    죽는 것              선반                      쓰는 job
job 컨테이너           컨테이너 자체         러너 볼륨 4종              lint · scan · dep-scan
데몬 (docker build)    무효화된 레이어       레이어 캐시(기본)           build 셋
                                          + BuildKit 캐시 마운트(보강)

캐시의 대가는 디스크다. trivy 캐시는 job별 폴더라 DB가 네 벌로 앉아 8GB대가 된다. 그리고 러너 볼륨은 job이 돌 때만 컨테이너에 붙어 있어 docker volume prune에는 "안 쓰는 볼륨"으로 보인다 — 정리 명령을 돌리면 캐시가 통째로 지워진다.

concurrent — 동시에 몇 개. needs 는 보류

concurrent는 러너 설정(config.toml 맨 위)이다. 러너가 GitLab에 묻는 창구 수라서, 1이면 job을 하나 끝내야 다음을 받고 2면 둘을 동시에 든다. 러너 개수와는 별개다. 2로 둔다. 더 올려도 한 stage의 시간은 그 안에서 제일 오래 걸리는 job이 정한다 — check 넷이 0:14 · 0:15 · 0:15 · 0:36일 때 슬롯 2개면 0:44, 4개면 0:36으로 차이가 초 단위다. 슬롯을 늘리는 값은 메모리와 캐시 동시 접근으로 치른다.

needs는 job이 기다릴 대상을 앞 stage 전체가 아니라 특정 job으로 좁히는 것이다 — build:queue-go가 check:booking을 안 기다리게 된다. 다만 걸어 둔 job은 나중에 stage를 추가해도 그것을 조용히 건너뛴다. 11부에 test stage를 채울 예정이라, 기본은 stage로 두고 특정 job이 유독 길어 나머지가 그것만 기다리는 게 보일 때만 건다. rules: changes가 붙으면 대부분의 커밋에서 서비스 하나 것만 돌아 기다릴 대상 자체가 적기도 하다.

돌아간 결과

캐시가 채워진 상태의 MR 파이프라인 — job 10개, 전체 1분 54초. publish 셋은 dev가 아니라 화면에 없다.

check     secret-scan 0:15 · dep-scan:queue-go 0:15 · lint:queue-go 0:14 · lint:booking 0:36
build     queue-go 0:16 · booking 0:15 · frontend 0:11
scan      queue-go 0:12 · booking 0:32 · frontend 0:16

캐시가 빈 첫 판은 다르다 — trivy DB와 Java DB, Maven 의존성, Go 모듈을 처음 한 번 받으므로 job 몇 개가 분 단위로 걸리고, 그다음 판부터 위 숫자가 된다.

MR을 스쿼시로 머지하면 dev에 커밋 하나가 생기고, 브랜치 파이프라인이 돈다. 이번엔 $CI_COMMIT_BRANCH == "dev"가 참이라 publish 셋까지 13개다. 전체 2분 35초. publish는 셋 다 20초 안쪽 — 레지스트리가 같은 데스크탑에 있어 push가 바깥 회선을 안 탄다.

레지스트리에 서비스 셋이 같은 태그로 선다.

booking     dev-15-17dcc495     277.5 MiB     JRE 가 들어 있어 셋 중 제일 크다
queue-go    dev-15-17dcc495      46.5 MiB     distroless
frontend    dev-15-17dcc495      42.0 MiB     nginx alpine

목록에는 지나온 흔적도 그대로 있다 — 손으로 올려 본 test, push를 dev 머지 뒤로 묶기 전에 올라간 ci-pipeline-1·2. cleanup 규칙이 7일이 지난 것부터 걷어 간다.

여기까지가 CI다. push 한 번이면 — 자격이 섞였는지 훑고, 코드를 검사하고, 이미지를 만들어 취약점까지 확인한 뒤, dev에 머지된 것만 레지스트리에 오른다. 검증을 통과한 이미지가 dev-15-17dcc495라는 이름으로 레지스트리에 서 있다. 남은 것은 그 이미지를 클러스터가 받아서 돌게 하는 일 — CD다.

5. CD — 배포 엔진은 이미 있다

CD 의 뜻

CD는 두 뜻으로 쓰인다.

Continuous Delivery     언제든 배포할 수 있는 상태를 유지한다.  버튼은 사람이 누른다
Continuous Deployment   검증을 통과하면 사람 손 없이 배포까지 나간다

차이는 마지막 한 걸음에 사람이 있느냐뿐이다. 환경마다 갈라 쓴다 — dev는 자동으로 나가고(Deployment), stg·prd는 사람이 승인한다(Delivery). cgv-infra가 환경을 디렉터리로 갈라 둔 것(environments/dev/)이 여기서 값을 한다: dev 파일만 자동으로 움직이고 stg·prd 파일은 사람이 고치는 형태가 그대로 성립한다.

Push 냐 Pull 이냐

CD를 거는 방식이 둘로 갈린다.

Push    CI 가 끝나면 CI 가 클러스터에 직접 명령한다 (kubectl · helm)
        → 클러스터 접근 자격이 클러스터 밖 CI 에 있어야 한다
Pull    클러스터 안의 도구가 git 을 지켜보다 스스로 당겨 온다
        → 밖에서 클러스터를 건드리지 않는다

Pull 쪽은 이미 서 있다. 9부의 ArgoCD가 그것이다 — cgv-infra를 읽고, 커밋이 오면 webhook을 받아 3초 안에 반영한다. 그래서 CD를 새로 세우는 게 아니라, CI가 만든 이미지가 그 길을 타게 끊긴 곳만 이으면 된다.

끊긴 곳이 둘이다

①  노드가 레지스트리에서 이미지를 못 받아온다      자격도 없고, 평문 레지스트리를 믿지도 않는다
②  git 이 무엇이 도는지 모른다                  레지스트리엔 dev-42-… 가 서는데
                                             매니페스트의 tag 는 옛 글자 그대로다

①을 이어야 파드가 뜨고, ②를 이어야 push 한 번이 파드 교체까지 간다. 순서대로 간다 — 받을 수 있게 만들어 놓고 자동화한다. 반대로 하면 git은 맞는데 파드만 계속 죽어서, 태그가 틀린 건지 자격이 없는 건지 갈리지 않는다.

6. 노드가 받아오게 한다

받아오는 주체가 노드다

컨테이너는 이미지를 자기 디스크에 가진 쪽에서만 만들어진다.

ArgoCD 가 Deployment 를 만든다
  ↓
스케줄러가 파드를 노드 하나에 배정한다        셋 중 어디가 될지는 그때 정해진다
  ↓
그 노드의 kubelet 이 containerd 에 시킨다
  ↓
containerd 가 디스크에 그 이미지가 없으면 레지스트리에서 받아온다
  ↓
못 받으면 ImagePullBackOff

프로젝트가 private이라 받아오는 데도 자격이 필요하다. 내가 손으로 쓴 자격은 내 PC의 ~/.docker/config.json에 있고 러너의 토큰은 job이 끝나면 사라진다 — 노드는 둘 다 볼 수 없다. 노드는 클러스터 안의 Secret에서만 자격을 읽고, 어느 노드에 뜰지 모르니 셋 다 받아올 수 있어야 한다.

자격 — 노드 몫을 좁혀 만든다

personal access token을 그대로 넣지 않는다. 그건 내 계정에 딸린 열쇠라 내가 닿는 모든 프로젝트에 통한다. 노드에게 필요한 것은 cgv-onprem의 이미지를 받아오는 권한 하나뿐이다.

personal access token    내 계정.  내가 닿는 전부         손으로 올릴 때 썼다
deploy token             프로젝트 하나.  고른 권한만       노드 몫.  read_registry 만 준다

이 Secret(Deploy token)은 지금까지의 12종과 타입이 다르다. Opaque(키·값을 그냥 담는 것)가 아니라 kubernetes.io/dockerconfigjson — kubelet이 읽는 정해진 구조다. 그래서 낱개 봉인 스크립트(generic 전용)로는 못 만들고, kubectl이 만들어 주는 것을 봉인한다.

kubectl create secret docker-registry gitlab-registry -n app \
  --docker-server=192.168.0.167:5050 \
  --docker-username='<deploy token 사용자명>' \
  --docker-password='<토큰>' \
  --dry-run=client -o yaml \
| kubeseal --format yaml \
    --controller-name sealed-secrets --controller-namespace kube-system \
> gitlab-registry.yaml

--docker-server는 차트의 image.repository 앞부분과 글자까지 같아야 한다 — kubelet이 그 문자열 비교로 "이 이미지에는 이 자격"을 매칭한다. 이걸로 봉인본이 13종이 됐다. 재구축 스크립트의 개수 검사와 계약 문서도 같이 움직인다 — 이 편 뒤쪽에서 image updater 몫이 더해져 최종 14종이 된다.

배선 — 차트와 노드가 그것을 보게 한다

파드가 이미지를 받는 데는 셋이 다 맞아야 한다. 하나만 빠져도 결과는 똑같이 ImagePullBackOff인데, 사유가 달라 어디가 빠졌는지는 갈린다.

어느 이미지냐      매니페스트의 image          빠지면  no such host
어느 자격으로냐    파드의 imagePullSecrets     빠지면  401 Unauthorized
그 주소를 믿느냐   노드 containerd 설정        빠지면  http: server gave HTTP response to HTTPS client

앞의 둘은 차트라 git으로 간다.

# charts/apps/cgv-app/values.yaml — 세 인스턴스가 쓰는 공통 차트라 한 번만
imagePullSecrets:
  - name: gitlab-registry

# charts/apps/queue/values.yaml — booking · frontend 도 같은 꼴
image:
  repository: 192.168.0.167:5050/cgv/cgv-onprem/queue-go

셋째는 노드 파일이다. containerd도 레지스트리를 HTTPS로 가정하므로 평문 주소를 예외로 적는다.

# /etc/rancher/k3s/registries.yaml — 노드 3대 공통
mirrors:
  "192.168.0.167:5050":
    endpoint:
      - "http://192.168.0.167:5050"

인증은 이 파일에 안 적는다 — 적으면 노드 디스크에 자격이 평문으로 남는다. 그 몫은 봉인본이 한다.

이 파일은 노드에 놓고 k3s를 재시작해야 읽힌다. 한 대씩 한다. 노드 셋이 etcd 쿼럼 3이라 한 대씩이면 클러스터가 살고, 둘을 동시에 내리면 쿼럼이 깨져 전체가 멈춘다. 7부에서 미룬 kube-reserved 2Gi 반영도 같은 재시작에 얹는다 — 이것도 재시작이 필요한 변경이라, 두 번 내릴 일을 한 번으로 줄인다.

한 대씩 재시작한다

파일 둘을 scp로 노드 홈에 올려 두고, 한 대씩 들어가 제자리에 놓고 재시작한다.

# 노드마다 (k3s-3 → k3s-2 → k3s-1 순)
sudo cp /etc/rancher/k3s/config.yaml /etc/rancher/k3s/config.yaml.bak-1gi
sudo mv ~/config.yaml /etc/rancher/k3s/config.yaml
sudo mv ~/registries.yaml /etc/rancher/k3s/registries.yaml
sudo systemctl restart k3s

재시작이라고 워크로드가 끊기지는 않는다. 컨테이너는 k3s가 아니라 별도 프로세스(shim)가 붙들고 있어, k3s가 내려간 몇십 초 동안도 계속 돈다 — 멈추는 것은 제어면 일(스케줄·kubectl 응답)뿐이다. drain도 걸지 않는다. 로컬 PV에 묶인 파드(ingester WAL 등)는 다른 노드로 못 가는 것들이라, 쫓아내 봐야 Pending으로 떠 있다 제자리로 돌아올 뿐이다.

세 대가 끝나면 둘이 바뀌어 있다.

allocatable    6105Mi → 5081Mi (세 노드 동일)      kube-reserved 2Gi 반영
앱 파드 오류    http: server gave HTTP response to HTTPS client
               →  frontend:dev: not found

오류가 바뀐 것이 배선의 증명이다. 앞엣것은 문전 거절 — 레지스트리에 닿지도 못했다. 뒤엣것은 http로 접속했고 자격 검사까지 통과한 뒤 "그런 태그는 없다"는 답을 받은 것이다. 길은 열렸고, 남은 것이 태그 하나라는 뜻이다.

태그 한 줄이 첫 배포다

environments/dev의 값 파일 셋에서 tag를 CI가 올린 실물로 바꾼다.

image:
  tag: dev-15-17dcc495     # ← dev 였던 자리

이 커밋이 MR로 main에 머지되면 — webhook이 ArgoCD를 깨우고(cgv-infra gitops), sync가 Deployment의 이미지를 바꾸고, 노드가 방금 연 길로 받아온다. 머지 몇 분 뒤 세 서비스가 처음으로 Running이 됐다. 배선을 만든 이래 줄곧 ImagePullBackOff로 서 있던 파드들이다.

줄어든 살림의 청구서 — request 를 실측으로 조인다

kube-reserved 2Gi는 노드당 할당 가능량 1Gi 감소로 돌아온다. 재시작 직후 mimir-ingester-1이 Pending에 걸렸다 — WAL이 로컬 PV라 k3s-2에만 갈 수 있는 파드인데, 그 노드의 request 합이 92%라 1Gi짜리가 앉을 자리가 없다.

이때 기준은 실측이다. request가 실사용보다 크게 잡힌 컴포넌트를 kubectl top으로 골라 조인다.

                  request     실사용(실측)      조정
mimir-ingester    1Gi         410-510Mi       768Mi     만재(시리즈 30만, 약 1.2Gi) 접근 시 재상향
mimir-compactor   512Mi       54Mi 미만       192Mi     병합 스파이크는 limit 1Gi 가 받는다
tempo             256Mi       54Mi 미만       128Mi

limit은 안 건드린다 — limit은 스케줄링에 쓰이지 않아 자리를 잡아먹지 않는다. 커밋이 머지되자 세 컴포넌트가 새 request로 돌고 ingester-1이 앉았다. 최종 request 비율은 k3s-1 81% · k3s-2 94% · k3s-3 74% — k3s-2는 남은 자리가 263Mi라, 다음 증설은 다른 노드 몫이다.

7. 태그를 git 에 되쓴다

마지막 한 줄이 남는다

여기까지로 이미지는 dev-*-abcdefg로 서고 노드는 그것을 받아올 수 있다. 그런데 매니페스트의 tag는 아직 옛 글자다. 그 한 줄을 누가 고치나.

사람이 매번 손으로     자동화한 의미가 없다.  잊으면 그만인 상태로 되돌아간다
CI 가 고친다          GitOps 저장소 쓰기 자격이 클러스터 밖으로 나간다.  Push 방식으로 회귀
클러스터 안의 도구     9부의 성질이 유지된다                              ← 고른 것

argocd-image-updater

클러스터 안에서 레지스트리를 지켜보다 새 이미지가 오르면 git에 되쓰는 도구다.

CI 가 push        레지스트리에 dev-43-e5f6a7 이 선다
  ↓
image-updater     레지스트리를 폴링하다 새 태그를 본다
  ↓
git 커밋          cgv-infra 의 environments/dev/values-<서비스>.yaml 의 tag: 한 줄
  ↓
webhook           9부에 걸어 둔 그 길.  3초 안에 ArgoCD 가 refresh
  ↓
ArgoCD sync       파드가 새 이미지로 교체된다

배포는 여전히 ArgoCD가 한다. image-updater는 파드를 만지지 않고 커밋 한 줄을 쓸 뿐이다 — CI와 CD 사이의 다리다.

비용도 있다. 파드가 하나 늘고, 레지스트리를 뒤지는 폴링이 하나 생기고, git에 쓰는 자격이 새로 필요하다.

이 편에서 자격을 쥔 쪽이 ArgoCD(저장소 읽기) · 나(손 push) · 노드(pull)에서 늘어나는 마지막 자리가 여기다. 되쓰는 대상을 environments/dev/로 한정하므로 dev만 자동으로 움직이고 stg·prd는 사람이 고치는 구도가 유지된다.

설치 — GitOps 로, 단 자리는 가려서

updater 자체도 GitOps로 배달한다 — argo-helm 차트를 App 하나로 선언하고, 값은 이 저장소에서 읽는다. ArgoCD가 이미 떠 있으니 배포 주체의 순환이 없다(본체와 다른 점 — 본체는 빈 클러스터에 배포해 줄 주체가 없어 최초 한 번을 손으로 설치했다).

자리는 골라야 했다. metallb·traefik이 타는 platform 틀은 대상 네임스페이스에 PodSecurity 라벨을 무조건 거는데, updater의 대상은 이미 존재하는 argocd 네임스페이스다 — 라벨이 걸리면 ArgoCD 본체까지 enforce 대상이 된다. 그래서 root 직속 App으로 세워 네임스페이스를 건드리지 않는다.

버전 하나가 동작 방식을 갈랐다. 핀한 1.2 계열은 컨트롤러 방식이다 — ImageUpdater라는 CR이 있어야 일을 시작하고, 없으면 Application에 annotation이 붙어 있어도 아무것도 하지 않는다(기동 로그: "No ImageUpdater CRs to process"). CR은 처리 대상만 고르고, 무엇을 어떻게 갱신할지는 useAnnotations로 각 App의 annotation에서 읽게 한다.

# 차트 extraObjects 로 같은 App 이 배달
kind: ImageUpdater
spec:
  applicationRefs:
    - namePattern: queue
      useAnnotations: true
    # booking · frontend 동일

자격 둘 — 읽는 손과 쓰는 손

updater가 손대는 곳이 저장소 둘이라, 자격도 저장소마다 하나씩이다.

레지스트리 폴링    cgv-onprem 의 deploy token (read_registry)
                  — 레지스트리가 그 프로젝트에 딸려 있다.  노드 pull 자격과 권한이 같지만
                    주체(노드/봇)가 달라 가른다 — 새면 그것만 폐기
git 커밋          cgv-infra 의 project access token (write_repository, role Maintainer)
                  — 태그를 적는 값 파일이 그 저장소에 있다

쓰기 토큰의 role이 Maintainer인 것은 protected main 때문이다. main은 직접 push가 막혀 있고(사람은 MR로만 간다), 무료판(CE)은 push 예외를 유저 단위가 아니라 role 단위로만 열 수 있다 — "Allowed to push = Maintainers"로 열고, 토큰을 그 role로 만들어 봇만 문을 통과하게 한다. 토큰을 만들면 GitLab이 봇 유저(project_N_bot_…)를 같이 만드는데, 이후 자동 커밋의 작성자가 그 봇으로 찍힌다 — git 이력에서 사람과 자동화가 작성자로 갈린다.

어느 태그를 "새것"으로 보나

update-strategy: newest-build     빌드 시각 기준.  태그(dev-<번호>-<해시>)가 사전순 정렬이
                                  안 되는 형태라(dev-9 > dev-15) 시각으로 고른다
allow-tags: regexp ^dev-…$        dev 계열만 후보.  MR 파이프라인의 ci-pipeline-* 은 배포 후보가 아니다
write-back-target: helmvalues     이 App 이 읽는 바로 그 값 파일(environments/dev/values-<앱>.yaml)의
                                  image.tag 에 쓴다

평문의 마지막 청구서 — 자격 경로를 바꾼다

첫 실행에서 updater가 새 태그를 발견하고 커밋하려다 죽었다.

could not get creds for repo 'http://…/cgv-infra.git': unknown repository type

전용 시크릿으로 git 자격을 주는 경로(git:secret:)는 코드가 ssh와 https 저장소만 받는다. 이 GitLab은 평문 http라, 설정으로 열 수 없는 벽이다 — 이 편에서 평문이 만든 네 번째 비용이고, 유일하게 예외 등록으로 못 넘는 것이었다.

우회는 같은 코드 안에 있다. ArgoCD의 저장소 자격을 빌리는 경로(repocreds)는 스킴을 검사하지 않는다. 그래서 저장소 자격(argocd-repo-cgv-infra)에 쓰기 토큰을 넣어 읽기와 쓰기를 한 자격으로 통합했다. 원칙의 후퇴다 — 다만 노출 반경은 안 변한다: 쓰기 토큰은 어차피 같은 네임스페이스의 봉인본에 있었고, 그 네임스페이스를 뚫은 쪽은 어느 구성이든 그것을 얻는다. TLS를 도입하는 날 read 전용 토큰 + 전용 쓰기 시크릿으로 되돌린다 — 계약 문서에 되돌리기 항목으로 적어 뒀다.

한 바퀴 — 사람 손 없이

frontend에 한 줄짜리 커밋을 만들어 경로 전체를 태웠다.

사람      코드 커밋 → MR 머지                    ← 마지막 개입
54초      CI 5개 job — 바뀐 서비스 것만 생겼다     dev-18-767410b6 이 레지스트리에
2분 내    봇 커밋                                 author: argocd-image-updater
                                                 "updates image … 'dev-15-…' to 'dev-18-…'"
수십 초   webhook → ArgoCD sync → 파드 교체

폴링 주기는 2분이다. ArgoCD처럼 webhook으로 당기지 않는 것은 보내는 쪽이 없어서다 — GitLab 무료판의 컨테이너 레지스트리는 "이미지 올라옴" 이벤트를 쏘는 기능이 없다. 폴링 비용은 내 서버·같은 망·이미지 세 개의 태그 목록 조회라 0에 가깝다. 폴링이 기본이고 webhook은 보내는 쪽이 있을 때의 가속이다.

"git에 적으면 배포된다"가 "머지하면 배포된다"가 됐다. 사람은 코드와 승인만 남고, 이미지 이름이 오가는 길은 전부 기계가 맡는다.

8. 대조 — 이은 것과 빌린 것

끊긴 곳은 이어졌나

끊긴 곳은 둘이었다 — 노드가 이미지를 못 받는 것, 새 태그를 git이 모르는 것. 둘 다 이어졌고, 그 증명이 위의 한 바퀴다. 코드 한 줄이 머지 클릭 하나를 지나 3-4분 안에 파드가 된다. 이 편의 목적이었던 문장이 실물이 됐다.

이 편 안에서 닫은 것

손 push 토큰(docker-push-manual) · 옛 ArgoCD 읽기 토큰    revoke — CI job 토큰과 새 자격이 대체
Pipelines must succeed                                  켬 — 빨간불이면 머지 버튼이 잠긴다
러너 allowed_images                                      6종 화이트리스트 — 소켓을 쥔 러너가
                                                        아무 이미지나 못 띄우게
같은 커밋이 두 번 돌던 workflow 구멍                       브랜치 파이프라인을 dev 로 한정
백업                                                    sealed-secrets 개인키 · GitLab 본체·설정을
                                                        클러스터 밖으로 반출

무엇을 빌렸나 — 부채 장부

평문 http 청구서 4건       ① 데스크탑 insecure-registries  ② 노드 registries.yaml
                          ③ updater 레지스트리 insecure    ④ git 자격 경로 통합(코드 벽)
                          TLS 는 이름(DNS)이 생기는 네트워크 재구성 편에서 넷을 함께 걷는다.
                          ④의 자격 통합은 그때 원상복구.
                          트립와이어: 코드 벽이 한 번 더 나오면 그 자리에서 TLS 를 당긴다

러너 소켓 마운트           호스트 도커 전권.  Protected 러너는 안 켰다 —
                          MR 파이프라인이 비보호 브랜치에서 돌아야 해서 켜면 CI 가 굶는다

러너 config.toml 이 git 밖  concurrent·캐시 볼륨 설정이 도커 볼륨 안에만 있다.
                          데스크탑을 갈아엎으면 사라진다 (GitLab 백업이 유일한 사본)

CI 이미지의 데몬 축적       판마다 이미지 셋이 데스크탑 데몬에 쌓인다.  레지스트리 cleanup 은
                          걸었는데 데몬 쪽 지우는 규칙이 없다

캐시의 디스크              trivy 캐시 8.5GB(잠금 회피로 DB 네 벌).  도커 VM 디스크(VHDX)는
                          안에서 지워도 저절로 안 줄고, 캐시 볼륨은 volume prune 에 지워진다

GitLab 무인 운영 불가      Docker Desktop 이 로그인 세션 앱이라 재부팅 후 로그인 전엔 안 뜬다
미러 토큰 평문             GitHub PAT 가 GitLab 미러 설정 안에 산다
ingester request           만재(시리즈 30만) 접근 시 재상향 — 부하 실측 편에서 시리즈 수와 함께

실무·보안 되짚기

이 편에서 실제로 만진 것들에 맞닿는 것만 짚는다.

자격 수명이 관리되지 않는다. 이 편에서만 토큰이 넷 생겼는데 만료·로테이션 계획이 없다. deploy token은 무기한으로 만들었고, PAT 만료가 오면 봇 커밋이 조용히 죽는다 — 만료 캘린더든 만료 알림이든, 죽기 전에 아는 장치가 실무의 기본이다.
이미지 출처 증명이 없다. 레지스트리의 이미지가 "이 파이프라인이 만든 것"이라는 증거는 push 자격뿐이다. 서명(cosign)·SBOM이 없어, 자격이 새면 위조 이미지가 정품과 구분되지 않는다. 게이트 다음 단계의 공급망 방어다.
게이트는 기계뿐이다. 파이프라인 초록이 머지 조건이 됐지만 사람 리뷰(approval)는 0명 설정이다 — 혼자라서 그런 것이고, 사람이 늘면 가장 먼저 켤 항목.
백업이 반출까지고 검증 전이다. 개인키·GitLab을 클러스터 밖에 뒀지만 "그걸로 실제로 복원되는가"는 안 해 봤다. 복원 리허설 없는 백업은 희망사항이다 — VM 백업(vzdump)·etcd 스냅샷 반출과 함께 남은 몫.

9. 다음

파드는 돌지만 아직 앱이 잘되는지 체크해보지는 않았다 — 트래픽 0, 테스트 0. 11부에서 앱을 실제로 태운다: 대기열 입장부터 좌석 선택, 예매 확정까지 흐름을 돌려 보고, 그 동작을 근거로 테스트를 써서 이 편에 자리만 만들어 둔 test 칸을 채운다. 지킬 대상이 실물이 됐으니 RBAC과 NetworkPolicy 최소 한 벌도 그때 함께 붙인다.

번외 — CI 파이프라인 기록

hsb_02 — Sun, 9 Aug 2026 13:17:13 +0900

10부 CI는 완성본만 설명 했다. 이 글은 순서를 뒤집는다.

최종본 해부 — stage마다, job마다 무엇이고 왜 그 자리에 있는지
여정 — job 실타래마다, 뭐에 막혔고 무슨 작업으로 풀었는지
판정 — 그래서 이게 맞는 CI인지

최종본 — 지금 무엇이 돌고 있나

push 한 번에 이렇게 흐른다.

push ─→ check ─→ test ─→ build ─→ scan ─→ publish
        4 job    (빈칸)   3 job    3 job    3 job (dev 에서만)

stage는 벽이다. 한 칸에서 실패가 하나라도 나오면 다음 칸은 실행되지 않는다.
job은 "명령 목록 + 그걸 돌릴 이미지"다. 러너가 컨테이너를 띄워 돌리고, 끝나면 버린다. 그래서 모든 job은 두 질문으로 읽힌다 — 무엇을 보는가, 실패가 무엇을 뜻하는가.

check — 코드 층의 게이트 넷

이미지를 만들기 전에, 소스만 보고 판정할 수 있는 것들. 넷은 서로 독립이라 한 칸에서 동시에 돈다.

secret-scan — 자격이 섞였나 (gitleaks)

무엇을 보나 — 커밋에 토큰·키·비밀번호가 들어갔는지. 대상은 히스토리 전체(GIT_DEPTH: 0) — 자격은 지워도 과거 커밋에 남는다.
언제 도나 — 조건 없이 모든 커밋. 어느 파일이 바뀌든 자격은 섞일 수 있다.
설정 하나 — --redact: 찾은 값을 로그에 안 찍는다. CI 로그도 유출 경로다.
실패의 의미 — 유출. 대응은 커밋 수정이 아니라 그 자격의 폐기·재발급이 먼저다.

dep-scan:queue-go — 선언한 의존성에 알려진 결함이 있나 (trivy fs)

무엇을 보나 — go.sum의 모듈 버전들을 공개 취약점 목록과 대조.
CVE란 — 공개된 보안 취약점 하나하나에 붙는 전 세계 공통 일련번호. 번호가 있어야 스캐너가 "이 버전에 이 결함 있음"을 기계적으로 대조한다. 심각도는 별도로 CVSS 점수(0–10)로 매기며 HIGH·CRITICAL이 그 등급이다.
언제 도나 — 조건 없이 모든 커밋. 단 이유가 secret-scan과 다르다 — 코드가 그대로여도 새 CVE 발표 하나로 결과가 바뀐다. 어제 통과한 커밋이 오늘 실패할 수 있다.
실패의 의미 — 내 잘못이 아니라 낡음. 대응은 버전 올리기.

lint:queue-go — 컴파일은 되는데 틀린 코드 (go vet)

무엇을 보나 — Printf 인자 불일치, 잠긴 뮤텍스 복사처럼 컴파일러는 통과시키지만 의도와 다르게 도는 자리.
특성 — 판정에 타입 정보가 필요해서 의존 패키지를 전부 컴파일한다. 이 job의 시간은 코드 크기가 아니라 컴파일 캐시가 정한다.
실패의 의미 — 코드 결함. 대응은 코드 수정.

lint:booking — 바이트코드 정적 분석 (SpotBugs)

무엇을 보나 — null 역참조·자원 미해제·오버라이드 실수류. 소스가 아니라 컴파일된 바이트코드를 훑는 도구라 mvn compile이 앞에 온다.
딸린 설정 셋 —

설정	왜
MAVEN_OPTS: -Xmx768m	JVM은 힙 상한이 없으면 "컨테이너가 보는 메모리"의 25%를 잡는다. job 컨테이너에 제한이 없어 VM 전체가 보인다 → 상한 고정
artifacts (when: always)	콘솔엔 개수만 남고 상세는 리포트 파일에 있다. 컨테이너째 사라지기 전에 GitLab에 올린다. 실패했을 때야말로 받아 봐야 하므로 always
spotbugs-exclude.xml	도구가 프레임워크를 모른다. 스프링 생성자 주입을 캡슐화 위반으로 오탐 → 그 패턴만 근거와 함께 제외

실패의 의미 — 코드 결함이거나 오탐. 오탐이면 "왜 오탐인지"를 필터에 근거로 남기고 좁게 제외한다.

test — 비어 있는 칸

stage 선언만 있고 job이 없다. 11부에서 채운다.
미룬 이유 — 테스트는 앱을 띄워 동작을 보면서 써야 의미 있는 단언이 나온다. 껍데기 테스트를 채우면 초록불이 거짓말을 한다.
이 칸이 빈 동안 이 파이프라인을 뭐라고 불러야 하는지는 판정 절에서.

build — 이미지를 만든다, 올리지는 않는다

이미지 — docker:27-cli. CLI만 들어 있고 데몬은 소켓 너머 데스크탑 것.
CI는 한 줄만 안다 — docker build ./$SVC. Go 컴파일인지 Maven인지 정적 파일 복사인지는 각 서비스의 멀티스테이지 Dockerfile이 품는다. 언어 차이를 CI가 아니라 Dockerfile이 가둔다.
--pull — 베이스 이미지를 매번 레지스트리에서 확인. 같은 태그라도 업스트림은 패치를 넣어 다시 굽는다.
산출물 — job 컨테이너가 아니라 데몬에 남는다. 다음 칸이 이름($SVC:$TAG)으로 이어받는다.

scan — 만든 이미지의 실물 검사 (trivy image)

dep-scan이 "선언"을 봤다면 여기는 "실제로 담긴 것"을 본다 — 베이스 OS 패키지, jar 안 라이브러리, Go 바이너리 안 모듈까지 이미지를 열어 읽는다.

--severity HIGH,CRITICAL   높은 등급만
--ignore-unfixed           수정판이 나온 것만    ← "막으려면 고칠 수 있어야 한다"
--exit-code 1              걸리면 job 실패 → publish 가 안 열린다

수정판이 없는 결함으로 막으면 파이프라인이 영구히 빨간불이 되고, 결국 게이트를 끄게 된다. 그래서 고칠 수 있는 것만 막는다.
운영 특성 둘 — 캐시 디렉터리가 job 이름별로 갈라져 있다(TRIVY_CACHE_DIR). 제한 시간이 20분이다(TRIVY_TIMEOUT). 왜 그래야 했는지는 여정의 scan 실타래에 나온다.

publish — 검증 통과본만, dev 만

$CI_COMMIT_BRANCH == "dev" — dev가 아니면 이 job은 화면에 생기지도 않는다. 아무 브랜치의 이미지가 배포 후보와 같은 자리에 쌓이지 않게 하는 벽.
로그인 — job마다 발급되고 끝나면 폐기되는 토큰. 표준 입력으로 넣는다(--password-stdin) — -p는 비밀번호가 명령줄 인자에 남는다.
interruptible: false — push가 중간에 끊기면 레지스트리에 레이어가 일부만 올라간 채 남는다.

파일 밖의 짝 — 러너와 Dockerfile

.gitlab-ci.yml만으로는 이 파이프라인이 재현되지 않는다.

어디	무엇	왜
러너 config.toml	concurrent = 2	러너가 동시에 드는 job 수
러너 config.toml	캐시 볼륨 넷 (maven·trivy·gomod·gobuild)	job 컨테이너는 버려진다. 내려받은 것을 남기려면 밖(볼륨)에 둬야 한다
각 Dockerfile	BuildKit 캐시 마운트 (RUN --mount=type=cache)	docker build는 데몬에서 돈다. 러너 볼륨이 안 닿는다 — 캐시가 두 층인 이유

이 상태로 캐시가 채워진 판이 job 10개, 1분 54초다. 여기까지가 지도다.

여정

판     결과      시간      한 일
#1     Passed    6:06     3단(check·build·package) 첫 판.  이미지 빌드 + push
#2     Passed    0:46     로그인을 표준 입력으로
#3~4   Passed    0:40대   push 는 dev 머지 뒤에만
#5     Failed    9:03     5단 재편.  scan 셋 전부 실패 — 72건
#6     Failed   10:04     1차 수정.  booking 21 · frontend 33 남음
#7     Failed   11:16     2차 수정 + 새 게이트 둘.  booking 1 · SpotBugs 23 · 429 등장
#8     Warning  10:15     3차 수정.  게이트 전부 통과, 유예 하나만 빨강
#9     Failed    8:42     캐시 도입.  캐시끼리 충돌
#10    Failed   14:26     충돌 해소.  이번엔 시간 초과
#11    Passed    4:27     시간 제한 상향.  전부 초록 (유예 2개 있는 상태)
#12    Passed    3:40     유예 제거.  열 job 이 전부 막는 게이트로
#13    Passed    4:00     메모리 상한 · 자동 취소 · Go 컴파일 캐시
#14    Passed    1:54     빈 커밋 — 캐시가 채워진 상태의 실측

아래부터는 실타래순이다 — 절 하나가 job 하나의 처음부터 끝. 절의 배열은 이야기가 시작된 판 순서라, 기록표와 같은 방향으로 흐른다.

실타래	판	막힌 것	한 작업	지금
출발점	#1–#4	—	태그 규칙 · dev 한정 · stdin 로그인	—
공통 배경	—	판마다 같은 것을 다시 받음	캐시 두 층	—
scan 셋	#5–#11	72건 → 잠금 충돌 → 시간 초과	코드·베이스 수정 → 캐시 폴더 분리 → TIMEOUT 20m	0:12–0:32
게이트 반입	#7 → #12	새 게이트가 첫 판부터 막음	allow_failure 유예 → 정리 → 제거	유예 0
dep-scan	#7–#10	429 차단	대상을 queue-go로 축소	0:15
lint:booking	#7–#13	오탐 23 → 상세 안 보임 → 힙 2GB	필터 → artifacts → MAVEN_OPTS	0:36
build 셋	#9	의존성 바꾼 커밋마다 전부 재다운로드	BuildKit 캐시 마운트	0:11–0:16
lint:queue-go	#12–#14	판마다 전부 재컴파일 + 옆 job까지 밀림	컴파일 결과 캐시 볼륨	0:14
캐시의 대가	#14 결산	디스크 — C: 여유 1GB	(부채로 기록)	—

출발점 — 검증 없이 올리던 시절 (#1–#4)

첫 파일은 stage 셋(secret scan·build·package)이었고 네 판이 다 통과했다. 통과한 이유는 잘돼서가 아니라 검증이 없어서다.

이 시기에 정해져 뒤까지 살아남은 것:

태그 규칙 <브랜치>-<파이프라인번호>-<커밋해시>
push는 dev 머지 뒤에만
로그인은 표준 입력으로
6:06 → 0:46 실측 — 소켓 마운트 덕에 레이어 캐시가 job 컨테이너 밖(데몬)에 남는다는 첫 확인

공통 배경 — 캐시란, 그리고 왜 CI에서 문제인가

여러 실타래가 이 개념 위에 서 있어서 먼저 놓는다.

캐시란 — 한 번 받아 둔 것을 버리지 않고 뒀다가, 다음에 같은 게 필요할 때 다시 쓰는 저장소.
왜 CI에서 문제인가 — job 컨테이너가 버려질 때 안에서 내려받은 것도 같이 사라진다. 캐시가 없으면 매 판이 처음이다.
하면 뭐가 바뀌나 — 첫 판만 받고, 그다음 판부터는 네트워크에 안 나간다.

이 파이프라인에서 "판마다 다시 받던 것"이 이만큼이었다. #7의 11:16 중 실제 작업은 2–3분, 나머지가 전부 다운로드다.

trivy 취약점 DB   103MB    × scan 계열 job 4개
trivy Java DB     903MB    × 1 (booking)
Maven 의존성       수백 개   × lint 와 build 각각
Go 모듈            수십 개

trivy DB가 뭔가 — 스캐너가 대조할 "알려진 결함 목록". 전 세계 패키지의 CVE 목록이라 크고, 새 CVE가 매일 등록되므로 낡으면 다시 받는다(3일 만료).
의존성 다운로드가 뭔가 — pom.xml·go.mod에 적힌 건 이름과 버전뿐이다. 실물(jar·소스)은 중앙 저장소에서 받아야 컴파일이 된다.

남길 자리는 두 층이다.

job 안에서 받는 것 → 러너 볼륨
docker build 안에서 받는 것 → BuildKit 마운트 (빌드는 데몬에서 돌아 러너 볼륨이 안 닿는다)

둘 다 #9에서 넣었다. 그 뒤 각 실타래에서 무슨 일이 났는지가 아래다.

scan 셋 — 72건에서 0까지, 그리고 스캐너 자신의 두 사건 (#5–#11)

72건이 쏟아졌다

5단 재편 첫 판(#5)에서 scan 셋이 전부 실패했다.

scan:queue-go    HIGH 2
scan:booking     HIGH 33 · CRITICAL 4
scan:frontend    HIGH 31 · CRITICAL 2

게이트가 --ignore-unfixed니 72건은 전부 수정판이 이미 나와 있는 결함이다. 문제는 왜 이렇게 쌓였느냐 — 서비스마다 층이 달랐다.

queue-go — 간접 의존 (2건)

걸린 golang.org/x/text·google.golang.org/grpc는 직접 import한 적이 없다. OTel 익스포터와 gin의 검증기가 딸고 들어온 간접 의존이다.
그래도 바이너리에 들어가는 것은 마찬가지라 스캐너가 잡는다.
수정 — go get <모듈>@<버전> && go mod tidy 두 줄.

booking — BOM이 정하는 버전들 (37건)

jar에서 37건, 베이스 OS는 0건. 걸린 tomcat·spring·jackson·netty는 전부 pom.xml에 버전이 안 적힌 것들이다.
BOM(Bill of Materials) — Spring Boot 부모 POM이 수백 개 라이브러리의 버전을 한 번에 정한다. 개발자는 이름만 적고 버전은 부모가 준다. 대가 — 부모를 안 올리면 딸린 전부가 함께 낡는다. 3.3.4는 그 사이 tomcat에 RCE(원격 코드 실행)급이 쌓일 만큼 낡아 있었다.
수정도 같은 구조로, 부모 한 줄. 다만 한 번에 안 끝났다:

3.5.14     37 → 21     전부 "한 패치 모자람" (#6)
3.5.16     21 → 1      3.5 라인 최신 (#7)
netty 핀    1 → 0      BOM 이 주는 4.1.135 가 수정판 4.1.136 보다 한 칸 낮았다 (#8)

BOM 기본값 → 안 되는 것만 개별 핀. 순서가 그렇다.

frontend — 죽은 베이스 태그 (33건)

코드도 의존성도 없는 서비스에서 33건. 전부 베이스 이미지(alpine 3.21.3)의 OS 패키지.
처음엔 로컬 캐시가 낡은 탓으로 보고 --pull을 붙였다. 33건이 그대로였다 — 진단이 틀렸다.
실제 원인 — nginx-unprivileged:1.27-alpine은 업스트림이 더 굽지 않는 멈춘 태그. 새로 받아도 같은 낡은 이미지가 온다.
살아 있는 라인(1.31-alpine)으로 옮기니 0. --pull은 살아 있는 태그에는 맞는 조치라 남겼다.

셋을 관통하는 결론

queue-go    모듈 버전을 고정해 뒀다     →  낡았다
booking     BOM 버전을 고정해 뒀다      →  낡았다
frontend    베이스 태그를 고정해 뒀다    →  낡았다 (태그가 죽기까지 했다)

고정해 둔 것은 시간이 지나면 낡는다. 코드가 안 바뀌었으니 아무 신호가 없었고, 스캔이 처음으로 그 시간을 드러냈다.

사건 1 — 캐시가 서로를 깨뜨렸다 (배타 잠금)

찾은 것을 다 고치자, 이번엔 스캐너 자신이 깨졌다. #9에서 scan 둘이 죽었다 — cache may be in use by another process: timeout.

잠금(lock)이 뭔가 — 여러 프로세스가 같은 파일을 동시에 고치면 반쯤 쓰인 데이터를 읽는 쪽이 생긴다. 그래서 "하나가 잡으면 나머지는 기다린다"는 표시를 걸어 둔다. '배타'는 한 번에 하나만.
왜 터졌나 — trivy는 DB 갱신을 지키려고 캐시 디렉터리에 이 잠금을 건다. 볼륨 하나를 scan 셋이 공유했는데, 같은 판에 concurrent(러너가 동시에 드는 job 수)를 1→2로 올렸다. 둘이 실제로 동시에 그 디렉터리를 열었고, 늦은 쪽은 기다리다 죽었다.
배운 것 — 동시성은 숨어 있던 공유 자원을 드러낸다.
해소 — TRIVY_CACHE_DIR를 job별 폴더로(#10). 잠금이 안 겹친다. 대가 — DB가 폴더 수만큼 여러 벌(디스크 실타래에서 돌아온다).

사건 2 — 시간 제한의 범위

폴더를 가르자 다음이 나왔다. #10에서 scan:booking이 context deadline exceeded(시한 초과)로 죽었다.

타임아웃이 뭔가 — "이 시간 안에 안 끝나면 강제로 실패"라는 상한. 멈춘 작업이 슬롯을 무한정 잡는 것을 막는 장치다.
함정은 범위다 — trivy 기본 5분 안에 DB 내려받기가 포함된다. 갈라진 새 폴더에 Java DB 903MB를 받는데, 옆 scan이 같은 회선으로 제 DB를 받고 있어 9분 10초가 걸렸다. 스캔은 시작도 못 하고 시간이 끝났다 — 취약점 유무와 무관한 실패.
해소 — TRIVY_TIMEOUT: 20m(#11). 캐시가 더운 판은 이 값 근처에도 안 간다. 죽은 판이 캐시는 채워 놓아서(로그 끝 "Java DB is cached") 다음 판부터 다운로드 줄 자체가 없다.

이 실타래의 끝 — scan:booking 3:21 → 0:32.

게이트 반입 — allow_failure 유예 → 정리 → 제거 (#7 → #12)

다음 두 실타래(dep-scan · lint:booking)는 #7에서 함께 들어왔다. 들어올 때 공통 장치가 있었다 — allow_failure: true. job은 돌고 결과도 남지만 실패해도 뒤 stage를 막지 않는 스위치다.

왜 — stage는 벽이다. 새 게이트가 check에서 빨간불이면 build·scan이 아예 안 돈다. 새 게이트는 "이미 쌓여 있던 것"을 처음 훑는 것이라 첫 판에 반드시 뭔가를 들고 나온다(실제로 SpotBugs 23건, dep-scan은 못 돌았다). 막는 상태로 넣었다면 같은 판의 이미지 쪽 수정이 먹혔는지 확인할 길이 없었다.
순서 — ① 유예로 넣는다(무엇을 잡는지 본다) ② 잡힌 것을 정리한다 ③ 유예를 걷는다. ③을 안 하면 아무도 안 보는 노란불로 남는다 — 게이트가 아니라 장식이 된다.
#12에서 두 줄을 지웠다. 그 판부터 열 job이 전부 조건 없이 막는다.
파이프라인 상태가 넷인 이유가 여기 있다 — Passed / Warning(통과인데 유예 job 중 실패가 있음, #8이 그것) / Failed / Canceled.

이 장치를 달고 들어온 두 job이 각자 무엇에 막혔는지가 다음 두 실타래다.

dep-scan — 남의 서버가 화를 냈다 (429, #7–#10)

붙인 첫 판(#7)부터 429 Too Many Requests로 죽었다.

rate limit이 뭔가 — 서버가 한 이용자(보통 IP 단위)의 요청 횟수에 상한을 거는 것. Maven Central은 전 세계가 무료로 쓰는 공용 서버라, 한 IP가 과도하게 받으면 다른 이용자 몫이 줄어든다. 넘으면 429와 Retry-After(몇 초 뒤에 오라)를 돌려준다 — 처음엔 89초, 나중엔 30분.
왜 걸렸나 — 당시 dep-scan은 저장소 전체를 봤다. pom.xml은 버전을 부모 POM이 정하므로 trivy가 실제 버전을 알려면 Maven Central에서 부모를 받아야 한다. 그런데 같은 공인 IP에서 booking 빌드가 판마다 의존성 수백 개를 받고 있었다. 서버 눈에는 전부 한 명이다.
배운 것 — 원인이 내 코드가 아니라 외부 서비스의 정책인 실패가 있다. 오류의 주체가 누구인지부터 갈라야 한다.
해소 — 대상을 ./queue-go로 좁힌다(#10). go.sum은 모든 버전이 파일 안에 있어 원격 조회가 아예 없다. 429가 "덜 나는" 게 아니라 날 수가 없어진다.
Java를 버린 게 아니다 — scan:booking이 jar 실물을 읽는 쪽이 선언 추정보다 정확하고, 37건을 0까지 몰고 간 것도 그쪽이다. 잃은 것은 "build 전에 잡는다"는 이점 하나.

이 실타래의 끝 — 0:15, 원격 조회 0회.

lint:booking — 오탐 23건, 리포트, 그리고 JVM (#7–#13)

붙인 첫 판(#7)에 23건이 나왔다. 이 실타래는 사건 셋이 연달아다.

오탐 23건 — 전부 두 패턴(EI_EXPOSE_REP/EI_EXPOSE_REP2), 해부에서 본 스프링 주입 오탐이다. 실제 결함 0. 두 패턴만 필터로 빼고 나머지 규칙을 살리니 0(#8). 도구를 붙이는 첫 판은 "무엇이 오탐인지 근거를 정리하는 판"이 된다.
상세가 안 보였다 — 콘솔엔 "23 bugs"만 찍힌다. 어느 파일 몇 줄인지는 리포트 파일에 있는데, job이 끝나며 컨테이너째 사라졌다. → artifacts(when: always)로 리포트를 GitLab에 올린다.
힙 2GB — 해부의 25% 규칙 그대로, JVM이 VM 전체(7.8GB)를 보고 힙을 2GB 가까이 잡았다. 동시에 도는 job 수만큼 곱해지는 값이라 MAVEN_OPTS: -Xmx768m로 고정(#13).

이 실타래의 끝 — 0:36.

build 셋 — 의존성을 바꾼 날만 느려지는 문제 (#9)

build는 평소 빠르다. 도커 레이어 캐시가 있어서다 — COPY pom.xml 내용이 그대로면 그 아래 RUN(의존성 다운로드) 결과를 재사용한다.

함정 — 그 파일이 한 글자만 바뀌어도 아래가 통째로 무효가 되어 처음부터 다시 받는다. 하필 의존성을 고친 커밋, CI 결과가 제일 필요한 순간에 그렇게 된다. 실제로 pom을 고치던 판들에서 build:booking이 1:33–2:27까지 늘었다.
해소 — BuildKit 캐시 마운트(RUN --mount=type=cache,target=/root/.m2). 내려받은 것을 레이어 밖 저장소에 두어, 목록이 바뀌어도 바뀐 것만 받는다(#9).

이 실타래의 끝 — build 셋 0:11–0:16.

lint:queue-go — 판마다 전부 재컴파일, 그리고 경합 (#12–#14)

전부 초록이 된 #12에서도 이 job이 2:34로 제일 길었다.

Go의 캐시는 둘이다 — 모듈 캐시(/go/pkg/mod)는 내려받은 소스를, 빌드 캐시(/root/.cache/go-build)는 그것을 컴파일한 결과를 담는다. 소스가 안 바뀐 패키지는 빌드 캐시가 있으면 다시 컴파일하지 않는다.
뭐가 빠졌었나 — 러너 볼륨에 모듈 캐시만 있었다. 소스는 안 받는데 컴파일은 판마다 처음부터 했다. go vet이 의존 전부를 컴파일하므로 그게 2분을 먹었다.
해소 — gobuild-cache 볼륨 추가. #13이 캐시를 채우고(399.7MB), 같은 소스로 한 판 더: 2:34 → 0:14.
덤 — 경합의 발견. 같은 판에서 lint:booking도 1:37 → 0:36이 됐다. 설정을 하나도 안 바꾼 job이다. 경합(contention) — CPU·디스크·회선은 한정돼 있고 동시에 도는 job들이 나눠 쓴다. 2분 34초짜리가 CPU를 잡는 동안 옆 슬롯이 밀리고 있었던 것. 병목 하나를 지우면 그늘의 job들이 제 속도를 되찾는다.

캐시의 대가 — 디스크, 그리고 VHDX (#14 결산)

캐시 실타래들의 공통 청구서다. #14 시점 캐시 볼륨:

maven 145MB · gomod 433MB · gobuild 400MB · trivy 8.5GB

trivy가 큰 것은 잠금 문제로 폴더를 갈라 DB가 네 벌이 됐기 때문 — 잠금 충돌과 디스크를 맞바꾼 것이다.
VHDX가 뭔가 — Docker Desktop은 리눅스 VM(WSL2) 안에서 돈다. 그 VM의 디스크 전체가 Windows에는 docker_data.vhdx라는 파일 하나로 보인다. 이미지 10GB·빌드 캐시 9GB·볼륨 12GB가 전부 그 안이다.
무슨 일이 — 이 파일이 32GB까지 자라 C 드라이브 여유가 1.0GB까지 내려갔다. VHDX는 안에서 늘어난 만큼 자동으로 커지지만, 안에서 지워도 저절로 줄지는 않는다. 회수는 별도 작업이다.
함정 하나 더 — 캐시 볼륨은 job이 돌 때만 컨테이너에 붙어서, docker volume prune(안 쓰는 볼륨 일괄 삭제)에는 "안 쓰는 볼륨"으로 보인다. 정리 명령 한 번이 캐시 전부를 지운다.
캐시를 운영한다는 것은 그 수명과 크기를 관리하는 일까지다.

판정 — 그래서 이게 맞는 CI인가

표준 8단계와 대조

CI 표준 구성(lint · build · test · secret scan · dependency scan · package · image scan · publish)에 겹쳐 보면:

있다      lint(go vet · SpotBugs) · secret(gitleaks) · dep(trivy fs)
          build → image scan(trivy image) → publish(dev 한정)
없다      test        ★ 칸만 선언.  11부에서 앱 동작을 보며 채운다
          SBOM · 이미지 서명 · 커버리지
미설정    러너 Protected · allowed_images / MR "Pipelines must succeed"

test가 비어 있는 동안은 온전한 CI가 아니다. CI의 정의가 "합칠 때마다 자동 검증"인데 그 핵심이 테스트다. 지금은 "빌드·보안 스캔 자동화"까지다.
그 한계를 그대로 두는 쪽을 골랐다 — 껍데기 테스트로 초록불을 만드는 것보다 낫다.
머지 게이트가 꺼져 있는 것도 남은 구멍이다. 빨간불이어도 머지 버튼이 눌린다.

SonarQube와 무엇이 다른가

겹치는 것은 lint 계열.

	SonarQube	이 파이프라인
내가 쓴 코드	정적 분석·중복·커버리지. 서버에 쌓여 추이가 남는다	go vet · SpotBugs (판마다 일회성)
가져다 쓴 것 (의존성 CVE)	범위 밖 (Community 기준)	dep-scan · scan (trivy)
이미지 안 OS 패키지	범위 밖	scan (trivy)

이번 14판에 대입하면 — SpotBugs 23건만 SonarQube 영역이다. queue-go 2건·booking 37건·frontend 33건은 SonarQube를 깔았어도 그대로 통과했다. trivy 두 job은 어느 쪽이든 필요하다.
구조에서 배울 것 — allow_failure로 손으로 만든 순서("기존 부채는 기준선, 새로 들어오는 것만 막는다")를 SonarQube는 New Code라는 기능으로 제공한다. 기준일 이후 코드만 Quality Gate로 판정하는 방식이다.
도입하지 않은 근거 둘 — 서버+DB로 상시 2GB대 메모리를 더 쓴다. 무료판(Community)은 브랜치·MR 분석이 없어 MR 게이트로는 반쪽이다. 13부 실측 후 재평가.

채용공고의 문구와 대조

공고에 반복되는 문구는 넷이다. 각각 무슨 뜻이고, 이 기록의 어느 부분이 답이 되는지.

공고 문구	무슨 뜻인가	이 기록에서
CI/CD 파이프라인 구축·운영	push부터 배포 직전까지를 자동 단계로 잇고, 깨지면 고치며 유지하는 일	14판 전체. 특히 "넣고 → 깨지고 → 고치는" 순환
컨테이너 기반 빌드	빌드 도구(Go·Maven)를 머신에 안 깔고 컨테이너로 쓰는 것. 어느 머신에서든 같은 결과	job마다 이미지 지정 · 소켓 마운트 대 dind 선택 · 멀티스테이지 · BuildKit
DevSecOps / 보안 스캔	보안 검사를 배포 뒤가 아니라 파이프라인 안(개발 단계)으로 당기는 것	secret·dep·image 3종 게이트 · 72건 → 0 · "고칠 수 있는 것만 막는다"
빌드 최적화	파이프라인 소요를 줄이는 일. 피드백이 10분을 넘으면 개발자가 결과를 안 기다리고 떠난다	10:15 → 1:54. 두 층 캐시 · 병목 추적(잠금·타임아웃·경합)

답이 안 되는 것도 그대로 남는다 — 테스트 자동화(11부 전까지), 대규모·다인원 환경(러너 한 대, 개발자 한 명의 기록이다).

부록

A — 커밋 열아홉

eed81cd   CI 파이프라인을 붙인다 — 이미지 빌드와 레지스트리 push
02e0792   레지스트리 로그인을 표준 입력으로 받는다
394d5bc   push 는 dev 에 머지된 뒤에만 한다
71c7383   파이프라인을 5단으로 재편한다 — check·test·build·scan·publish
a4751ec   queue-go: 취약점이 보고된 간접 의존 모듈을 올린다
957a2ee   booking: Spring Boot 부모 버전을 3.3.4 에서 3.5.14 로 올린다
5a534f3   이미지 빌드에 --pull 을 붙이고 스캔 로그의 진행바를 끈다
ebbfa2d   check 칸에 의존성 스캔과 booking 정적분석을 붙인다
9c4c4fa   booking: Spring Boot 부모를 3.5.16 으로 올린다
2f408f7   frontend: nginx 베이스를 1.31-alpine 으로 올린다
fdf3ed2   booking: netty 를 4.1.136.Final 로 고정한다
9cf1c05   SpotBugs 제외 필터를 두고 리포트를 아티팩트로 남긴다
ac6b801   빌드 안에서 받는 의존성을 BuildKit 캐시 마운트로 옮긴다
1e7f85c   scan job 마다 trivy 캐시 폴더를 갈라 준다
a6c9c49   의존성 스캔 대상을 queue-go 로 좁힌다
07f087a   build·scan·publish 가 앞 stage 아티팩트를 안 받게 한다
c6c508d   이미지 스캔 제한 시간을 20분으로 둔다
ec17637   의존성 스캔과 정적 분석을 막는 게이트로 돌린다
060bee1   job 의 메모리 상한 · 제한 시간 · 자동 취소를 정한다

git 밖이라 커밋에 없는 변경 — 러너 config.toml(concurrent = 2 + 캐시 볼륨 넷), .wslconfig(메모리 상한 6→8GB). 러너 설정은 도커 볼륨 안에 있어 저장소에 남지 않는다. 데스크탑을 갈아엎으면 사라지는 부채로, 10부 §9에서 다룬다.

B — job별 시간 변화 (초록 판 기준)

job                 #8       #12      #14
secret-scan         0:10     0:14     0:15
dep-scan(:queue-go) 0:27✗    0:15     0:15
lint:queue-go       1:53     2:17     0:14    ← gobuild-cache
lint:booking        1:04     1:15     0:36    ← 경합 해소
build:queue-go      0:12     0:19     0:16
build:booking       1:33     0:18     0:15    ← BuildKit 캐시
build:frontend      0:14     0:11     0:11
scan:queue-go       0:43     0:14     0:12
scan:booking        3:21     0:36     0:32    ← trivy 캐시
scan:frontend       0:33     0:18     0:16
─────────────────────────────────────────────
전체                10:15    3:40     1:54

※ 파이프라인 목록 화면이 #11·#14를 Warning으로 표시하는 문제가 남았다. GitLab 내부 데이터(status=success, has_warnings=false)와 어긋나는 표시다. 상세 화면과 API가 맞다.

번외 — WSL2와 커밋 한도

hsb_02 — Wed, 5 Aug 2026 13:22:23 +0900

9부에서 GitLab을 데스크탑에 세우고 작업하는 동안 하루에 몇 번씩 가까이 뭔가가 죽었다.
GitLab이 내려가고, Chrome 탭이 비워지고, VS Code가 다시 뜨고, Docker Desktop이 아예 시작을 못 했다.
작업 관리자를 열면 메모리가 80퍼센트를 넘어 있었다. 물리 램이 모자란다고 판단하고
DDR3 4GB 네 장 중 두 장을 8GB로 바꿀 주문을 넣었다.

그런데 원인은 램이 아니었다. 이 글은 그 판단이 왜 틀렸는지, 무엇이 진짜 원인이었는지,
어떻게 찾아서 고쳤는지를 순서대로 적은 것이다.

원인을 가리려면 무엇이 무엇 위에 있는지부터 알아야 했다. WSL2·배포판·컨테이너·Vmmem이
각각 무엇이고 어느 층에 있는지를 갈라 놓고 시작한다.

0. 무엇이 안 잡혔나

말로 못 하던 것들이 이랬다.

Docker Desktop · docker · dockerd · WSL2 · wsl · 배포판 · 컨테이너 · Vmmem

이름은 다 들어 봤는데 무엇이 무엇 위에 있는지가 안 그려졌다. 그 상태로는 작업 관리자에서 Vmmem이 1위인 것을 봐도 그게 무엇인지조차 몰랐고, 화면에 OOMKilled가 찍혀도 어느 층에서 난 일인지 가릴 수 없었다.

그래서 층부터 갈랐다. 무엇이 무엇 위에 서 있는지를 모르면 어디를 손댈지도 모른다.

1. 개념 — 무엇이 무엇 위에 있나

출발점은 이것 하나다. 이 데스크탑의 Windows에 WSL2를 켜고 Ubuntu 배포판을 깔아서 써 왔다. Vmmem이 무엇이고 왜 그렇게 먹는지를 알려면 그 두 단어부터 갈라야 한다.

1.1 WSL2 — Windows 안에 띄운 가상머신

WSL2는 Windows 안에서 리눅스 커널을 실제로 부팅시키는 가상머신이다. "실제로"가 핵심이고, 그게 이전 세대와 갈리는 지점이다.

WSL1   가상머신이 아니었다. 리눅스 커널이 없었다.
       리눅스 프로그램이 커널에 하는 요청을 Windows 커널이 받아 바꿔 처리했다
       → 커널 기능 자체가 필요한 도커는 아예 못 돌았다

WSL2   가상머신이다. 리눅스 커널이 그 안에서 부팅한다
       → cgroup · namespace 가 진짜로 있다  → 도커가 돈다

커널이 실제로 있는지는 명령 한 줄로 확인된다.

wsl --version

WSL 버전: 2.7.11.0
커널 버전: 6.18.33.2

리눅스 커널이 버전까지 찍힌다. Microsoft가 만들어 배포하는 커널이고, 이것이 안에서 부팅해 있다는 뜻이다.

그 가상머신은 무엇 위에 올라가나 — 하이퍼바이저

컴퓨터 한 대에 OS는 원래 하나다. CPU도 메모리도 디스크도 그 OS가 전부 자기 것으로 쓴다. OS를 둘 이상 동시에 돌리려면 그것들을 나눠서, 서로의 존재를 모른 채 쓰게 해 줄 층이 하나 필요하다. 그 층이 하이퍼바이저다.

하는 일     CPU 시간 · 메모리 영역 · 디스크를 게스트마다 잘라서 준다
            한 게스트가 다른 게스트의 메모리를 못 건드리게 막는다

Type 1      하드웨어 바로 위에서 돈다      Hyper-V · KVM(Proxmox) · ESXi
Type 2      OS 위에서 앱으로 돈다        VirtualBox · VMware Workstation

WSL2를 켤 때 Windows 기능에서 Virtual Machine Platform을 켜는데, 그것이 Windows의 하이퍼바이저 Hyper-V다. Proxmox VE 쪽은 Debian 리눅스 커널에 모듈로 들어 있는 KVM이 같은 자리에 있다. 둘 다 Type 1이고, OS에 이미 딸려 온 것을 켜서 쓴다. VirtualBox처럼 따로 설치하는 프로그램이 아니다.

여기서 순서가 한 번 뒤집힌다. 하이퍼바이저를 켜면 그것을 켠 OS 자신도 하이퍼바이저 아래로 내려앉는다.

물리 하드웨어
  └ Hyper-V (하이퍼바이저)
       ├ Windows 자신                          ← 게스트가 된다
       └ WSL2 VM  →  리눅스 커널 6.18.33.2

켜기 전에는 Windows가 하드웨어를 직접 쓰지만, 켜고 나면 하이퍼바이저가 하드웨어를 잡는다. WSL2 VM은 Windows 밑이 아니라 Windows 옆에 나란히 놓인다. Proxmox도 같아서, Debian이 KVM을 켜는 순간 그 Debian도 VM 3대와 나란한 자리로 내려간다.

Proxmox만 특별한 방식이 아니다. 노트북에서 하던 것과 데스크탑에서 도는 것이 같은 구조이고, 다른 것은 그 위에 무엇을 올렸느냐뿐이다.

구조는 같고 방향이 반대다

Proxmox    서버 한 대를 여러 대로 나눠 쓴다      게스트를 호스트에서 떼어낸다
WSL2       Windows 에서 리눅스를 쓴다           게스트를 호스트에 붙인다

그 방향 차이가 네 군데에서 나온다.

① 메모리를 받는 방식

Proxmox VM   만들 때 8GB 로 지정하면 켜져 있는 동안 계속 8GB 를 점유한다
WSL2 VM      Windows 의 물리 메모리에서 그때그때 받아 온다
             0 에서 시작해 상한까지 오르내린다

WSL2는 받아 오는 곳이 Windows의 물리 메모리다. 별도로 떼어 둔 몫이 없으니, VM이 커지는 만큼 Windows 쪽에서 그만큼이 빠진다.

물리 16GB
  ├ Windows 앱들이 쓰는 몫
  └ WSL2 VM 이 받아 간 몫        0 에서 상한 사이를 오르내린다

상한이 있고, 그 상한은 Windows 쪽 설정 파일이 정한다. 어느 파일에 무엇을 적어 뒀는지는 배포판을 다룬 뒤에 연다.

켜 놓은 채로도 쓰는 양이 계속 오르내린다. 안에서 뭔가 돌면 더 받아 오고, 한가해지면 일부를 돌려준다. Windows 쪽에서 그 오르내림이 어떤 숫자로 보이는지는 뒤의 Vmmem 절에서 다룬다.

② 켜져 있는 시간

Proxmox VM   켜 두면 계속 떠 있다
WSL2 VM      아무것도 안 켜면 VM 자체가 없다.  명령 하나를 치는 순간 뜬다

③ 부팅

Proxmox VM   BIOS/UEFI → 부트로더 → 커널 → init      수십 초
WSL2 VM      커널 이미지를 바로 올린다. 부트로더가 없다   1초 안쪽

④ 호스트와의 경계

Proxmox VM   완전히 분리. 네트워크로만 닿는다 (SSH)
WSL2 VM      /mnt/c 로 Windows 디스크가 들어와 있다
             localhost 를 Windows 와 공유한다
             리눅스 셸에서 .exe 를 실행할 수 있다

그중 작업 방식을 정하는 것이 /mnt/c다. 같은 파일을 두 이름으로 보는 것이라 복사본이 아니다(마운트의 효과 — Windows 드라이브를 리눅스 파일시스템 안의 한 자리에 붙여 둔 것).

Windows   C:\Users\on\Desktop\loadmap\cgv-infra\...
Linux     /mnt/c/Users/on/Desktop/loadmap/cgv-infra/...

VS Code에서 저장하면 리눅스 셸에서 바로 읽힌다. Proxmox VM이었으면 scp로 옮겨야 했을 일이다.

넷 중 이 글에 걸리는 것

넷째, 호스트와의 경계가 없는 것이 데스크탑에서 WSL2를 고른 이유다. VS Code로 Windows 쪽에서 편집하고 같은 파일을 리눅스에서 빌드한다. 옮기는 절차가 없다.

그것을 얻은 대가가 첫째와 둘째다.

메모리를 빌려 온다      떼어 받은 메모리라면 Windows 가 모자라도 VM 은 자기 몫을 쥔다
                     빌려 오니 Windows 쪽이 막히면 VM 도 같이 막힌다

필요할 때만 뜬다        없다가 생기고, 생기면 커지고, 커지면 잘 안 줄어든다
                     숫자가 계속 움직여서 무엇이 정상인지 잡히지 않는다

k3s 노드는 서로 떨어져 있어야 하니 Proxmox가 맞고, 데스크탑에서 파일을 옮기지 않고 두 쪽을 오가려면 WSL2가 맞다. 호스트에 붙인 대가로 호스트 사정도 같이 넘어온다.

다루는 명령은 `wsl` 하나다

wsl -l -v           뭐가 켜져 있나
wsl -d <이름>        그것으로 들어간다
wsl --terminate     하나를 내린다
wsl --shutdown      VM 을 통째로 내린다

<이름> 자리에 무엇이 들어가는지가 다음 절이다. 커널은 섰지만, 커널만으로는 명령 한 줄 못 친다.

1.2 커널과 배포판

둘이 각각 무엇을 하는지는 ls 한 줄을 따라가면 갈린다.

`ls` 하나를 칠 때 무슨 일이 나나

$ ls

   ① bash 가 "ls" 라는 파일을 찾는다              /usr/bin/ls
   ② bash 가 커널에게 부탁한다                    "이 파일 실행해 줘"
★ ③ 커널이 디스크를 읽어 메모리에 올린다          →  ls 프로세스가 뜬다
   ④ ls 가 커널에게 부탁한다                      "이 디렉터리에 뭐 있는지 알려 줘"
★ ⑤ 커널이 디스크를 실제로 읽어서 알려 준다
   ⑥ ls 가 화면에 찍는다

★ = 디스크를 실제로 건드리는 단계.  둘 다 커널이 한다

커널 — 하드웨어를 직접 만지는 유일한 것

커널이 독점하는 것    CPU 시간 배분 · 메모리 할당 · 디스크 읽고 쓰기 · 네트워크 카드
프로그램이 하는 것     커널에게 부탁한다 (= 시스템콜)

왜 독점하나. 프로그램이 하드웨어를 직접 만지면 서로 같은 메모리를 덮어쓰고 같은 디스크를 동시에 긁는다. 그래서 창구를 하나로 몰았고, 그 창구가 커널이다.

배포판 — 커널에게 부탁하는 프로그램들의 묶음

위 ①의 bash, ②의 ls, 그리고 /usr/bin이라는 디렉터리 자체까지 전부 배포판이 넣어 준 것이다.

셸               명령을 입력받을 창구 (bash)
기본 명령어       ls · cp · ps · grep
패키지 관리자      프로그램을 설치하는 도구 (apt · dnf · apk)
디렉터리 배치      /etc · /usr · /var 를 어디에 어떻게 둘지
초기화 시스템      부팅하며 뭘 순서대로 띄울지 (systemd)

"리눅스"는 원래 "커널 이름"이고, 위를 골라 한 벌로 묶어 놓은 것이 배포판이다. 누가 어떻게 묶었느냐로 이름이 갈린다.

Ubuntu · Debian        패키지 apt · .deb
Rocky · RHEL · CentOS  패키지 dnf · .rpm
Alpine                 패키지 apk. 작아서 컨테이너 베이스로 많이 쓴다

커널만 있으면 부팅이 끝까지 못 간다

리눅스가 켜지는 순서는 이렇다.

① 커널을 메모리에 올린다
② 커널이 하드웨어를 초기화한다            CPU · 메모리 · 디스크 · NIC 인식
③ 커널이 루트 파일시스템(/)을 마운트한다
④ 커널이 /sbin/init 을 실행한다           PID 1
⑤ init 이 나머지를 띄운다                 로그 · 네트워크 · sshd · 셸

커널이 직접 하는 것은 ①②까지다. ③의 /도 ④의 /sbin/init도 커널 안에 없다 — 배포판이 준다. 없으면 이 줄에서 멈춘다.

Kernel panic - not syncing: No init found.

명령이 안 먹는 정도가 아니라 프롬프트를 띄울 bash 자체가 없다.

내가 미리 예전에 깐 것이 Ubuntu 배포판이다

실물은 Windows에 있는 파일 하나다.

Get-ChildItem "$env:LOCALAPPDATA\wsl" -Recurse -Filter "ext4.vhdx" | Select-Object FullName

C:\Users\on\AppData\Local\wsl\{a3e25de2-...}\ext4.vhdx

vhdx는 가상 디스크 파일이고, 그 안에 리눅스 파일시스템 하나가 통째로 들어 있다. 부팅 ③에서 커널이 /로 마운트하는 것이 이 파일이다.

열어 보면 디렉터리 구조가 그대로 나온다.

wsl -d Ubuntu -- ls /

bin  boot  dev  etc  home  lib  media  mnt  opt  proc  root
run  sbin  snap  srv  sys  tmp  usr  var

정체와 커널을 각각 물어보면 답이 갈린다.

wsl -d Ubuntu -- cat /etc/os-release
wsl -d Ubuntu -- uname -r

PRETTY_NAME="Ubuntu 24.04.4 LTS"
6.18.33.2-microsoft-standard-WSL2

배포판은 Ubuntu인데 커널은 Microsoft가 만든 것이다. 둘이 따로라는 것이 이 두 줄에서 확인된다.

부팅 ④의 /sbin/init도 그 파일 안에 있다.

wsl -d Ubuntu -- ps aux

USER   PID  COMMAND
root     1  /sbin/init          ← Ubuntu 의 ext4.vhdx 에 든 파일이 PID 1 이 됐다
root    43  systemd-journald
root   151  systemd-resolved

여기까지로 완성된 것

WSL2 VM  ─  리눅스 커널 6.18.33.2         Microsoft 가 준다.  고를 여지가 없다
             └ Ubuntu 배포판               내가 깔았다.  ext4.vhdx 파일 하나
                  bash · ls · apt · systemd · /etc · /home

부팅 ①에서 ⑤까지가 다 돌았다는 증거가 "wsl"명령어로 들어가는 프롬프트다.

PS C:\Users\on\Desktop\loadmap> wsl
on@DESKTOP-BSPGJMO:/mnt/c/Users/on/Desktop/loadmap$

이 프롬프트가 Ubuntu 배포판이 준 bash다. 커널만 있었으면 이 줄이 안 나온다. 여기서 kubectl·kubeseal·git을 치면 먹는다.

Windows 안에 리눅스가 섰다. 여기에 필요한 것을 apt로 얹으면 되는 상태다.

그 VM에 준 자원 — `.wslconfig`

VM이 Windows에서 받아 갈 수 있는 상한은 Windows 쪽 파일 하나로 정한다. 리눅스 안이 아니라 밖이다.

C:\Users\on\.wslconfig

[wsl2]
memory=6GB
processors=6
swap=4GB

memory       VM 이 Windows 물리 메모리에서 받아 갈 수 있는 최대치
processors   VM 에 줄 논리 프로세서 수 (i7-2600K 8스레드 중 6)
swap         VM 안의 스왑.  Windows 페이지파일과는 별개

파일이 없으면 기본값이 쓰인다. memory 기본값은 물리의 절반이라 이 데스크탑에서는 8GB가 된다. 6GB로 낮춘 것은 Windows 쪽에 자리를 남기려던 것이다.

바꾼 값은 VM을 다시 띄워야 먹는다.

wsl --shutdown

.wslconfig가 정하는 것은 상한 하나뿐이다. 실제로 얼마를 받아 가는지는 그때그때 달라진다.

1.3 GitLab을 어떻게 세울 것인가

여기까지가 데스크탑 환경이었다 — WSL2 가상머신 하나에 Ubuntu 배포판 하나. 그 상태에서 프로젝트를 이어가려면 GitLab을 이 데스크탑에 세워야 했다.

GitLab이 요구하는 환경

OS        리눅스만.  Windows 에서는 어떤 방식으로도 네이티브로 안 돈다
CPU       4코어 권장 (최소 2)
RAM       4GB 필수 최소, 8GB 권장.  swap 은 별도로 더 필요
디스크      설치에 2.5GB + 저장소 데이터

이 데스크탑과 대조하면 걸리는 줄이 하나다.

요구            이 데스크탑
──────────────────────────────────────────────
리눅스           WSL2 안에 커널이 있다                    ✅
4코어            .wslconfig  processors=6                ✅
디스크           C 드라이브 여유 49.7GB                    ✅
RAM 4GB         VM 상한이 6GB.  Ubuntu 배포판과 나눠 쓴다   ← 여기

GitLab 최소가 4GB인데 VM 전체가 6GB다. 그 6GB를 Ubuntu 쪽 작업(kubectl·빌드)과 나눠 쓰면 남는 것이 2GB 남짓이다. 그래서 GitLab 쪽 설정을 눌러 공식 최소 아래로 돌리고 있고, 무엇을 눌렀는지는 방식을 고른 뒤 기동 파일에서 같이 본다.

세울 수 있는 방법 셋

① Ubuntu 배포판에 직접 설치            apt install gitlab-ce.  도커 없이
② Docker Desktop 을 깔고 컨테이너로
③ Ubuntu 배포판에 도커 엔진만 깔고 컨테이너로

k3s 클러스터에 Helm으로 올리는 길과 노트북에 VM을 하나 더 두는 길도 있지만, 노드 RAM 8GB에 LGTM 스택이 이미 돌고 노트북 RAM도 노드 3대에 배분돼 있어 자리가 없다.

① Ubuntu 배포판에 직접 설치

sudo apt install gitlab-ce

WSL2 VM
  └ 리눅스 커널
      └ Ubuntu 배포판
          └ gitlab-ce 패키지     PostgreSQL · Redis · nginx 가 같이 깔린다

얻는 것    셋 중 제일 가볍다.  GitLab 말고 얹히는 것이 없다

치르는 것   GitLab 이 그 Ubuntu 를 점유한다.  앞으로 무엇을 깔든 한 공간을 쓴다
          apt purge 해도 설정과 데이터가 남는다
          버전을 올렸다 문제가 생기면 배포판째 되돌려야 한다
          → 미리 wsl --export 로 통째 백업을 해 뒀어야 한다

GitLab은 서비스로 돌아야 해서 systemd가 필요하다. WSL2는 지원하지만 기본이 꺼져 있어 켜야 한다.

# /etc/wsl.conf
[boot]
systemd=true

② Docker Desktop을 깔고 컨테이너로

Windows
  ├ Docker Desktop.exe            앱.  GUI · 자동 업데이트 · 백엔드 관리
  └ WSL2 VM
      ├ Ubuntu 배포판
      └ docker-desktop 배포판       앱이 자기 몫으로 깐 것
           └ dockerd
                └ gitlab 컨테이너

Docker Desktop은 Windows 앱이고, 깔면 배포판과 엔진이 따라온다. GitLab은 그 엔진이 만든 컨테이너 안에서 돈다.

얻는 것    GUI 로 컨테이너 · 이미지 · 볼륨을 본다
          엔진 설치와 업데이트를 앱이 한다
          WSL 통합 설정을 앱이 해 준다

치르는 것   배포판이 하나 더 생긴다 (docker-desktop)
          Windows 쪽에 앱 프로세스가 뜬다 — 작업 관리자에서 약 200MB
          로그인하면 자동으로 뜬다 (설정으로 끌 수 있다)

③ Ubuntu 배포판에 도커 엔진만 깔기

sudo apt install docker-ce
docker compose up -d

WSL2 VM
  └ 리눅스 커널
      └ Ubuntu 배포판
          └ dockerd (엔진)
               └ gitlab 컨테이너     그 안에 리눅스 한 벌 + GitLab

컨테이너로 돌리는 것은 ②와 똑같다. 다른 것은 엔진을 앱이 관리하느냐 내가 apt로 깔고 관리하느냐뿐이고, 그 차이로 배포판 하나와 Windows 앱이 빠진다.

얻는 것    배포판은 그대로 1개인데 GitLab 이 Ubuntu 를 점유하지 않는다
          PostgreSQL · Redis · nginx 가 전부 컨테이너 안에서 끝난다
          이미지 태그가 버전을 고정한다.  문제가 생기면 태그만 바꿔 다시 띄운다
          지울 때 컨테이너와 볼륨만 지우면 Ubuntu 는 그대로다

치르는 것   dockerd 가 뜬다.  ① 보다 그만큼 더 쓴다
          엔진 설치 · 업데이트 · WSL 설정을 직접 한다
          GUI 가 없다.  상태는 docker ps · docker stats 로 본다

셋을 나란히

                    ① 직접 설치         ② Docker Desktop     ③ 엔진 직접
────────────────────────────────────────────────────────────────────────────
배포판                1개                2개                  1개
추가로 뜨는 것          없음               dockerd + Windows 앱   dockerd
GitLab 이 사는 곳      Ubuntu 안          컨테이너 안           컨테이너 안
버전 되돌리기           배포판째 백업/복원    태그를 바꾼다          태그를 바꾼다
지운 뒤               잔재가 남는다        Ubuntu 그대로         Ubuntu 그대로
관리                  손수               앱이 해 준다           손수

② "Docker Desktop을 깔고 컨테이너로" 방식을 골랐다

메모리만 놓고 보면 셋의 차이는 수백 MB다. GitLab 본체가 2.87GB이므로 어느 쪽을 골라도 그것이 제일 큰 몫이고, 뒤에 겪은 크래시도 이 선택과는 무관했다.

갈리는 것은 다루기 쉬움이다. ①은 버전을 되돌리려면 배포판을 통째로 백업해 뒀어야 하고, ②③은 이미지 태그만 바꾸면 된다. 처음 세워 보는 것이라 설정을 바꿔 가며 다시 띄울 일이 많았으므로 ②③ 쪽이 맞았다.

②와 ③ 사이에서는 ③이 같은 이득을 더 가볍게 준다. 배포판 하나와 Windows 앱 200MB를 안 쓰고 끝난다. 그것을 모르고 ②를 골랐다.

기동 파일 — 4GB 최소를 어떻게 눌렀나

컨테이너를 어떤 설정으로 띄울지는 docker-compose.yml 한 장에 적는다.

services:
  gitlab:
    image: gitlab/gitlab-ce:19.2.1-ce.0
    container_name: gitlab
    restart: unless-stopped
    shm_size: '256m'
    ports: ['8929:8929', '2424:22']
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://192.168.0.167:8929'
        puma['worker_processes'] = 0
        sidekiq['max_concurrency'] = 10
        prometheus_monitoring['enable'] = false
        gitlab_kas['enable'] = false

아래 넷이 공식 최소 4GB를 2GB대로 끌어내린 설정이다.

puma worker_processes = 0        웹 요청을 받는 워커 프로세스를 안 띄운다
                                 마스터 하나가 직접 처리한다.  혼자 쓰니 동시 요청이 없다

sidekiq max_concurrency = 10     백그라운드 작업 스레드 수.  기본 20 의 절반

prometheus_monitoring = false    GitLab 이 자체 내장한 감시 스택을 끈다
                                 exporter 프로세스가 여럿 안 뜬다

gitlab_kas = false               쿠버네티스 에이전트 서버.  안 쓰는 기능이라 끈다

넷 다 "프로세스 수를 줄이는" 설정이다. GitLab이 무거운 이유가 기능 하나가 커서가 아니라 한 컨테이너 안에서 여럿이 같이 뜨기 때문이라, 안 쓰는 것을 빼는 것이 제일 크게 듣는다.

restart: unless-stopped도 뒤에 걸린다. 엔진이 뜨면 GitLab이 따라 뜬다는 뜻이라, 내가 켜지 않아도 로그인만 하면 올라와 있다.

1.4 그렇게 세우니 무엇이 생겼나

docker compose up을 친 것이 전부였다. 실제로 무엇이 생겼는지는 명령 두 줄로 확인된다.

배포판이 하나 더 생겼다

wsl -l -v

 * Ubuntu           Running
   docker-desktop   Stopped

docker-desktop은 내가 깐 적이 없는데 목록에 있다. Docker Desktop이 엔진을 둘 자리로 만든 것이다.

State 칸의 뜻은 이렇다.

Running    그 배포판의 ext4.vhdx 안에 든 프로그램들이 프로세스로 돌고 있다
Stopped    파일은 그대로 있고, 돌고 있는 것이 하나도 없다

Stopped는 없어진 것이 아니다. 파일은 그대로 있고 아무것도 안 돌 뿐이라, 명령 한 줄이면 다시 Running이 된다.

내 Ubuntu에 얹지 않고 따로 깐 이유는 앱이 업데이트할 때 그 배포판을 통째로 갈아엎기 때문이다. 내 Ubuntu에 얹었으면 Docker를 갱신할 때마다 거기 깔아 둔 것이 날아간다.

이름이 겹쳐서 헷갈리는 것 셋을 갈라 두면 이렇다.

Docker Desktop     Windows 앱.  아이콘으로 켜는 것
docker-desktop     배포판.  wsl -l -v 에 나오는 것.  엔진(dockerd)이 여기 산다
docker             명령어.  Windows 에 있다.  엔진에 지시만 보낸다

GitLab은 그 위에(docker-desktop 위에) 얹었다.

docker-compose.yml     C:\Users\on\Desktop\loadmap\gitlab\
docker compose up -d   PowerShell 에서 친다

  → docker (Windows) 가 dockerd (VM 안) 에 지시를 보낸다
     → dockerd 가 gitlab/gitlab-ce 이미지로 컨테이너를 띄운다
        → 그 안에서 프로세스 아홉이 돈다

docker 명령이 Windows에 있어서 PowerShell에서 친다. Ubuntu 배포판 쪽에서는 안 먹는다 — Docker Desktop의 WSL 통합을 그 배포판에 대해 안 켰기 때문이다.

그런데 가상머신은 여전히 하나다

가상머신     1개      Get-Process vmmem 을 쳐도 vmmem 하나만 나온다
커널        1개      두 배포판 다 6.18.33.2-microsoft-standard-WSL2
배포판       2개      Ubuntu · docker-desktop
컨테이너     1개      gitlab

배포판이 늘어도 VM은 안 는다. GitLab 컨테이너도 마찬가지다 — 자기 커널이 없어서 VM의 커널을 빌려 쓴다.

그래서 결과가 하나 나온다.

.wslconfig 의 memory=6GB 는 배포판마다 6GB 가 아니라, 둘이 합쳐 6GB 다

Ubuntu 쪽 작업과 GitLab이 각자 몫을 갖는 것이 아니라 한 통을 나눠 쓴다. 한쪽이 커지면 다른 쪽이 밀린다.

1.5 Vmmem — VM 전체를 Windows가 보는 이름

작업 관리자 목록에 gitlab이라는 줄은 없다. VM 안에 있던 것 전부가 Vmmem 한 줄에 뭉쳐 있다.

Windows가 프로그램을 실행하면 그 메모리는 그 프로세스 앞으로 달린다. 그런데 WSL2 VM은 Windows가 실행하는 프로그램이 아니라 하이퍼바이저가 돌리는 것이라, 어떤 Windows 프로세스에도 안 속한다. 그대로 두면 작업 관리자에서 "메모리가 80퍼센트인데 목록을 다 더해도 그만큼이 안 나오는" 상태가 된다. 그 구멍을 표시하려고 Windows가 만든 자리가 Vmmem이다.

① 프로세스가 아니다     작업 끝내기로 못 끈다.  내리려면 wsl --shutdown
② 안이 안 보인다        배포판 둘과 GitLab 컨테이너가 한 숫자에 뭉쳐 있다
③ CPU 도 대표한다      Vmmem 의 CPU % 는 VM 안 리눅스가 쓰는 양이다
④ 물리 RAM 기준이다     VM 이 요구한 양이 아니라 지금 물리 RAM 에 올라와 있는 양이다

②는 켜 보면 눈으로 확인된다.

PowerShell 에서 wsl 을 쳐서 Ubuntu 배포판을 켠다    →  Vmmem 이 오른다
Docker Desktop 에서 GitLab 컨테이너를 켠다         →  같은 Vmmem 이 또 오른다

배포판을 켜든 컨테이너를 켜든 늘어나는 것은 Vmmem 한 줄이다. 목록에 새 줄이 생기지 않는다.

1.6 전체 그림

Windows 10  (물리 16GB, i7-2600K 4코어 8스레드)
  │
  ├─ Docker Desktop.exe       앱. VM 과 엔진을 켜고 끈다
  ├─ docker.exe               명령어. 엔진에 지시를 보낸다
  ├─ wsl.exe                  명령어. 배포판을 켜고 셸을 연다
  │
  ├─ Chrome · VS Code · Claude Code · Defender
  │
  └─ WSL2 가상머신                        ← 작업 관리자에 Vmmem 으로 보인다
       │  리눅스 커널 6.18.33.2-microsoft-standard-WSL2
       │
       ├─ Ubuntu 배포판                   kubectl · kubeseal · kubeconfig
       │
       └─ docker-desktop 배포판
            └─ dockerd
                 └─ gitlab 컨테이너
                      nginx · workhorse · puma · sidekiq · postgresql
                      redis · gitaly · sshd · logrotate       프로세스 아홉

"GitLab은 프로세스인가 컨테이너인가"의 답이 여기 있다 — 둘 다다. 컨테이너 하나 안에 프로세스가 아홉이다.

1.7 켤 때마다 무엇이 오르나

wsl 을 친다                      Docker Desktop 아이콘을 클릭한다
──────────────────────────────────────────────────────────────
① VM 을 띄운다                   ① VM 을 띄운다            ← 같은 VM 하나
② Ubuntu 배포판을 띄운다          ② docker-desktop 배포판을 띄운다
③ 셸을 하나 연다                  ③ 그 안에서 dockerd 를 띄운다
                                ④ dockerd 가 gitlab 컨테이너를 띄운다
                                ⑤ 컨테이너 안에서 프로세스 아홉이 뜬다

둘 다 같은 가상머신을 쓰고, 각자 자기 배포판을 켠다. 그래서 Vmmem이 두 개로 갈라지지 않고 한 숫자가 커진다.

무엇으로 재나 — 명령 넷

wsl -l -v                            배포판이 켜져 있나
wsl -d docker-desktop -- free -h     VM 전체 장부
docker stats --no-stream             컨테이너별
Get-Process vmmem                    Windows 가 본 VM 의 몫

free -h에 -d docker-desktop을 쓴 이유가 하나 있다. 이 값은 커널이 보고하는 것이고 커널은 VM에 하나뿐이라, Ubuntu에서 묻든 docker-desktop에서 묻든 같은 숫자가 나온다. 배포판을 고르는 것이 아니라 아무 배포판이나 하나를 통해 커널에게 묻는 것이다.

그런데 -d Ubuntu로 물으면 꺼져 있던 Ubuntu가 그 명령 때문에 켜진다. 재려고 친 명령이 재는 대상을 바꿔 버리므로, 이미 떠 있는 쪽(데스크탑과 함께 자동 부팅되는 docker-desktop)을 통해 묻는다.

free -h는 두 줄을 준다. Mem과 Swap이고, 칸 이름은 두 줄이 같이 쓴다. 각 줄이 무엇인지는 아래에서 하나씩 본다.

               total   used   free   shared  buff/cache  available
Mem:           5.8G    2.9G   483M   97.8M    2.4G        2.6G
Swap:          4.0G    0      4.0G

Mem 줄 — VM 의 물리 메모리

total 5.8G — 상한이 정한다
- .wslconfig의 memory=6GB가 출발점이다
- VM이 부팅하면서 리눅스 커널이 자기 코드와 자료구조 몫을 먼저 떼어 간다
- 남은 것이 total이라 6GB를 줬는데 5.8G로 보인다
- VM 안에서 무슨 짓을 해도 이 위로는 못 간다. memory를 8GB로 올리면 total도 같이 커진다
used 2.9G — 프로세스가 쥐고 있는 양
- docker stats가 보여준 gitlab 2.906GiB와 거의 같다
- 컨테이너도 같은 커널 위의 프로세스라 여기 합산된다
- 프로세스가 끝나면 즉시 돌아온다
free 483M — 아무도 안 쓰는 순수 빈 공간
- 작아 보이지만 이게 정상이다
- 리눅스는 빈 메모리를 놀리지 않는다. 놀려도 얻는 게 없으니 읽은 파일로 채워 둔다
- 그래서 오래 쓸수록 free는 0에 가까워진다. 부족을 뜻하지 않는다
shared 97.8M — 프로세스끼리 공유하는 몫
- tmpfs나 /dev/shm 같은 공유 메모리다
- GitLab 기동 파일의 shm_size: '256m'가 여기 반영된다
- used에 이미 포함된 값이라 따로 더하면 안 된다
buff/cache 2.4G — 쓰고 있지만 언제든 내놓는 것
- 커널이 디스크에서 읽은 내용을 들고 있는 것이다
- 같은 파일을 또 읽으면 디스크에 안 가고 여기서 준다
- 요구가 오면 버려서 내준다. used와 성격이 다르다
  - used — 프로세스가 요구한 것. 못 뺏는다
  - buff/cache — 커널이 알아서 채운 것. 요구가 오면 내놓는다
- 전부 내놓지는 못한다. 그 예외는 available 항목에서 다룬다
available 2.6G — 이 칸을 본다
- 지금부터 새 프로그램이 받을 수 있는 양이고, 커널이 계산해서 알려 준다
- available = free + buff/cache 중 버릴 수 있는 부분
- 단순히 더한 값보다 작다
```
free 483M  +  buff/cache 2.4G  =  2.88G
available                       =  2.6G
차이                             약 280M   ← 못 버리는 몫
```
- buff/cache 중 못 버리는 것
  - shared 97.8M — tmpfs·/dev/shm. 디스크에 원본이 없어서 버리면 내용이 사라진다
  - dirty 페이지 — 고쳤는데 아직 디스크에 안 쓴 것. 먼저 써야 버릴 수 있다
- 나머지는 디스크에서 읽어 온 사본이라 버려도 원본이 남는다. 그래서 대부분 회수된다
- free가 483M이라고 겁먹을 게 아니라 available 2.6G가 실제 여유다
- 반대로 이 칸이 0에 가까워지면 캐시를 다 버려도 모자란 상태다

세 칸이 total을 나눠 갖는다.

total  =  used  +  free  +  buff/cache
5.8G   =  2.9G  +  483M  +  2.4G

Swap 줄 — 모자랄 때 디스크로 밀어내는 자리

스왑이 무엇인지부터 짚는다.

RAM 이 모자라면
   지금 당장 안 쓰는 내용을 디스크에 내보내고 그 자리를 비운다
   나중에 그 내용이 필요해지면 디스크에서 다시 읽어 온다
   RAM 보다 훨씬 느리지만, 메모리가 모자라 죽는 것은 막는다

"메모리를 늘리는 것"이 아니라 "느려지더라도 버티게 하는 것"이다.

total 4.0G — .wslconfig의 swap=4GB가 만든 것
- VM 안의 스왑이고, Mem의 5.8G와는 별개로 더 있는 자리다
- 상한 memory=6GB에 포함되는 값이 아니다
- Windows에도 같은 역할을 하는 것이 있고, 그것의 이름이 페이지파일이다
  - Swap — VM 안. 게스트 리눅스가 자기 몫 5.8G가 모자랄 때 쓴다
  - 페이지파일 — VM 밖. Windows가 물리 RAM 16GB가 모자랄 때 쓴다
  - 층이 달라서 서로 무관하게 동작한다. 하나가 가득 차도 다른 하나는 모른다
used 0 — 아직 안 쓰고 있다
- Mem의 available이 0에 가까워져야 여기로 밀어내기 시작한다
- 밀어내기 시작하면 그만큼 더 버틴다. 그 대신 디스크를 오가느라 느려진다
- 이 값이 오르고 있다면 VM 메모리가 빠듯하다는 신호다
free 4.0G — 남은 스왑

출발점 — GitLab만 떠 있는 상태

내가 켠 것이 없어도 로그인만 하면 여기까지 온다.

Docker Desktop 설정 AutoStart=true            로그인하면 앱이 뜬다 (창은 안 열린다)
docker-compose.yml  restart: unless-stopped   엔진이 뜨면 GitLab 이 따라 뜬다

Ubuntu는 안 켰다. 그 상태에서 재면 이렇다.

wsl -l -v         Ubuntu Stopped  /  docker-desktop Running
docker stats      gitlab  2.906 GiB / 5.787 GiB
free -h           total 5.8G  used 2.9G  free 483M  cache 2.4G  available 2.6G
Vmmem             2,508 MB
Windows           물리 여유 5.5GB

used 2.9G와 gitlab 2.906GiB가 거의 같다. VM 안에서 쓰는 것의 거의 전부가 GitLab이고, 엔진과 그 배포판은 수십 MB다.

여기서 Ubuntu를 켜면

wsl

3초 간격으로 3분간 재면 이렇게 움직인다.

07:56:41   Vmmem 3,138 MB
07:56:52   Vmmem 3,740 MB
07:57:00   Vmmem 3,781 MB     ← 20초 만에 여기까지
07:59:59   Vmmem 3,819 MB     ← 그 뒤 3분간 38MB

부팅은 20초 안에 끝나고 그 뒤로는 거의 안 는다.

전후를 나란히

                    Ubuntu Stopped     Ubuntu Running     차이
────────────────────────────────────────────────────────────────
Vmmem               2,508 MB           3,822 MB          +1,314 MB
게스트 used          2.9 G              2.9 G             변화 없음
게스트 buff/cache     2.4 G              2.8 G             +0.4 G
게스트 available      2.6 G              2.6 G             변화 없음
Windows 물리 여유     5.5 GB             4.1 GB            -1.4 GB

게스트 쪽 세 줄 — VM 안에서 무슨 일이 있었나

used         2.9 G → 2.9 G      Ubuntu 프로세스 약 120MB 는 반올림에 묻혔다
                                init · journald · resolved · systemd --user
buff/cache   2.4 G → 2.8 G      부팅하며 ext4.vhdx 에서 파일을 읽었다
available    2.6 G → 2.6 G      늘어난 게 캐시라 여유는 그대로다

VM 안에서 실제로 일어난 일은 "캐시가 0.4G 늘었다"가 거의 전부다. Ubuntu 배포판 자체가 무거운 것을 띄우지 않아서 used는 눈에 띄게 안 늘었고, available도 그대로다.

그런데 `Vmmem`은 1.3GB 올랐다

게스트는 0.4G만 늘었는데 Vmmem은 그 세 배가 넘게 올랐다. 두 숫자가 재는 대상이 다르기 때문이다.

게스트 회계    프로세스가 요구해서 받아 둔 양          used + cache  =  5.3G → 5.7G
Vmmem        그중 지금 물리 RAM 에 올라와 있는 양                    2.5GB → 3.8GB

게스트가 5.7G를 쥐고 있다고 계산해도 물리 RAM에는 3.8GB만 있다. 나머지는 물리 RAM 밖에 나가 있다.

그리고 vmmem에 대한 배정은 고정이 아니다.

VM 이 한가하면     Windows 가 물리 RAM 배정을 줄인다     Ubuntu 켜기 전  2.5 GB
VM 이 활발해지면    배정을 늘린다                      Ubuntu 켠 뒤   3.8 GB

Ubuntu 부팅은 파일을 대량으로 읽는 작업이다. 한가하던 VM이 갑자기 활발해지자 Windows가 vmmem에 배정을 늘렸다.

늘어난 1.3GB의 내역은 위 네 숫자에서 그대로 나온다.

켜기 전    게스트 보유 5.3 G  −  물리 배정 2.5 GB  =  물리 밖 2.8 G
켠 뒤      게스트 보유 5.7 G  −  물리 배정 3.8 GB  =  물리 밖 1.9 G
                                                  물리 밖이 0.9G 줄었다

Vmmem 증가  1.3 GB  =  새로 요구한 0.4 G  +  밖에서 되돌아온 0.9 G

증가분의 절반 이상이 새로 쓴 것이 아니다. 원래 물리 밖에 있던 몫이 다시 올라온 것이고, 그만큼 Windows 쪽 여유가 줄었다.

그래서 표를 이렇게 읽는다

게스트 세 줄    VM 안에서 무엇이 얼마나 쓰는지
Vmmem 줄      Windows 가 그 VM 에 물리 RAM 을 얼마나 내주고 있는지

두 줄이 같은 것을 재지 않으므로 증가분도 같지 않다. 이 표에서 읽을 것은 "Ubuntu를 켜니 Windows 쪽에서 1.4GB가 빠졌다" 하나다.

Vmmem 밖에 나가 있던 그 몫이 어디에 있었는지는 뒤에서 다시 나온다.

여기까지가 아무것도 안 하고 있을 때의 값이다

GitLab 이 떠 있고 Ubuntu 를 켰다.  그게 전부다
게스트 available   2.6 G
Windows 물리 여유   4.1 GB

실제 작업은 여기에 kubectl·git·빌드가 올라가고, GitLab이 clone·push를 처리하고, Chrome과 VS Code가 얹힌 상태다.

2. 증상 — 작업하다 하나씩 죽었다

작업을 하려면 넷을 켠다.

GitLab           Docker Desktop 이 띄운 컨테이너.  저장소와 MR 이 여기 있다
Ubuntu 배포판     kubectl · kubeseal.  노트북 k3s 클러스터를 만진다
Chrome           GitLab · Proxmox · Grafana · ArgoCD 화면을 띄운다
VS Code          Claude Code 와 문서 작업

2.1 작업 중에 하나씩 멈추거나 다시 떴다

Chrome 탭이 비워진다              다시 열면 처음부터 불러온다
VS Code 가 통째로 다시 뜬다        다시 뜨는 화면에 OOMKilled 가 찍힌다
kubectl 이 갑자기 안 먹는다        wsl -l -v 를 보면 Ubuntu 가 Stopped 로 바뀌어 있다
GitLab 화면이 안 열린다            docker ps 에 gitlab 이 없다
Docker Desktop 이 아예 시작을 못 한다

규칙이 없었다. 어떤 날은 Chrome만 날아가고, 어떤 날은 Ubuntu가 통째로 Stopped가 되고, 어떤 날은 Docker Desktop이 시작조차 못 했다.

2.2 작업 관리자를 열어 보니 메모리가 차 있었다

메모리        80–90 퍼센트
상위 셋       Vmmem · Chrome · VS Code

작업을 이어 갈수록 셋이 계속 올랐다. Chrome은 탭을 열수록, VS Code는 창과 확장이 늘수록, Vmmem은 GitLab이 일할수록 커졌다.

2.3 메모리가 꽉 차서 하나씩 죽는 것으로 봤다

증상과 숫자와 에러 문구가 같은 방향을 가리켰다.

화면에 OOMKilled 가 찍혔다        Out Of Memory — 글자 그대로 메모리 부족이다
메모리가 80퍼센트를 넘어 있었다
제일 많이 먹는 셋이 계속 올랐다

물리 램이 모자라서 순서대로 밀려나 죽는다고 결론지었다.

2.4 그래서 램을 늘리기로 했다

현재      DDR3 4GB × 4 = 16GB      슬롯 넷이 전부 차 있다
교체 후    8GB × 2 + 4GB × 2 = 24GB

슬롯이 비어 있지 않아 추가가 아니라 교체다. 4GB 두 장을 빼고 8GB 두 장을 넣는 것으로 주문을 넣었다.

보드    Gigabyte P67A-UD3R-B3   슬롯 4개 · 최대 32GB · DDR3
CPU     i7-2600K               4코어 8스레드
BIOS    F9 (2012-03)            8GB 모듈을 못 잡던 초기 리비전이 아니다
모듈    DDR3 8GB PC3-12800 240핀 Unbuffered DIMM

2.5 램이 오기 전에 로그를 한 번 더 봤다

주문은 넣었지만 무엇이 무엇을 죽였는지는 여전히 설명할 수 없었다. 그래서 넷을 전부 띄워 메모리를 채우고, 죽는 순간의 기록을 남겼다.

GitLab 컨테이너를 띄운다
Ubuntu 배포판을 켠다
Chrome 으로 GitLab · Grafana · ArgoCD 를 연다
VS Code 를 띄운다
그 상태에서 GitLab 에 clone · push 를 걸어 부하를 준다

그리고 죽었다. 이번에는 남은 기록이 있었다.

3. 로그가 진단과 안 맞았다

3.1 GitLab — `SIGKILL`을 받았다는 것까지만 나왔다

죽은 직후의 컨테이너를 그대로 조회했다. docker ps는 이름과 상태를 한 줄로 요약해 주는 데 그치지만, docker inspect는 그 컨테이너의 설정과 상태를 전부 꺼내 준다. 지워지지 않고 Exited로 남아 있으면 죽은 컨테이너도 조회된다.

그냥 치면 JSON이 200줄 넘게 나오므로 --format으로 넷만 뽑았다.

docker inspect gitlab --format "restart={{.HostConfig.RestartPolicy.Name}} memlimit={{.HostConfig.Memory}} oomkilled={{.State.OOMKilled}} exit={{.State.ExitCode}}"

restart=unless-stopped  memlimit=0  oomkilled=false  exit=137

넷을 같이 뽑은 이유는 앞의 둘과 뒤의 둘이 성격이 다르기 때문이다. HostConfig는 컨테이너를 만들 때 준 설정이라 안 변하고, State는 마지막 종료 결과라 죽을 때마다 갱신된다. "내가 뭘 걸어 뒀나"와 "실제로 어떻게 끝났나"를 나란히 놓아야 뒤의 이야기가 보인다.

`exit=137` — 강제 종료됐다는 것까지만 알려준다

리눅스에서 신호로 종료된 프로세스의 종료 코드는 128 + 신호번호다. 137은 128 + 9이고 9번 신호가 SIGKILL이니, 강제 종료 신호를 받고 끝났다는 뜻이다.

거기까지다. 누가 그 신호를 보냈는지는 안 알려준다.

`oomkilled=false` — 판정할 경로가 없었다

메모리 부족으로 죽었다면 이 값이 true여야 할 것 같은데 아니었다. memlimit=0이 이유다.

도커는 컨테이너마다 메모리 한도를 걸 수 있는데, 안 걸면 0이 되고 한도 없음이다. 그리고 도커가 true를 찍는 것은 자기가 건 한도를 넘었을 때뿐이라, 한도가 없으면 그 판정 자체가 성립하지 않는다.

SIGKILL이 오는 길이 여럿인데 그중 하나만 도커가 판정한다.

① 컨테이너가 자기 한도를 넘었다    cgroup 이 죽인다              OOMKilled=true    메모리 때문
② VM 전체 메모리가 바닥났다       리눅스 커널이 골라 죽인다        OOMKilled=false   메모리 때문
③ VM · 엔진이 내려갔다           그 위의 것이 전부 끌려간다       OOMKilled=false   원인 미상
④ 사람이 docker kill 을 쳤다                                 OOMKilled=false   메모리 무관

memlimit=0이면 ①이 아예 일어날 수 없다. 그래서 이 값은 ①만 배제할 뿐 나머지에 대해서는 아무것도 말해 주지 않는다.

여기까지 알아낸 것

알아낸 것    SIGKILL 을 받고 끝났다
            ① (컨테이너 한도 초과) 은 아니다 — 한도를 안 걸었으니까

못 알아낸 것  ②③④ 중 무엇인지
            메모리 때문인지조차 이 기록으로는 모른다

"메모리가 꽉 차서 죽었다"는 것은 증상을 보고 세운 짐작이었고, 기록은 그것을 확인해 주지 않았다.

한도를 걸어 뒀다면 true/false 하나로 ①인지 아닌지가 갈렸을 것이다. 한도는 제한이자 진단 도구인데 안 걸어 둬서 다른 기록을 더 뒤져야 했다. 어디에 어떻게 거는지는 뒤에서 다룬다.

그래서 Docker Desktop 쪽 기록을 봤다.

3.2 Docker Desktop — 시작조차 못 하고 `wsl.exe`가 죽었다

GitLab을 다시 띄우려고 Docker Desktop을 켰다. 그런데 이번엔 앱이 시작조차 못 하고 에러창을 띄웠다.

running wslexec: DockerDesktop/Wsl/ExecError:
  wsl.exe -d docker-desktop -u root -e wsl-bootstrap run ...
  exit status 0xc00000fd

`0xc00000fd` — 스택을 늘리지 못했다는 뜻이다

0xc00000fd  =  STATUS_STACK_OVERFLOW

스택은 프로그램이 함수를 부를 때 쓰는 메모리 영역이다.

함수를 부른다      그 함수의 지역 변수와, 끝나고 돌아갈 주소가 스택에 쌓인다
함수가 끝난다      그만큼 걷힌다
깊이 들어간다      함수 안에서 함수를 부르면 계속 쌓인다

처음부터 크게 잡아 두면 낭비라, 작게 시작해서 깊이 들어갈수록 늘려 간다. 그 늘리기가 실패하면 이 코드가 난다.

스택도 메모리다. 늘린다는 것은 곧 Windows에 메모리를 더 달라고 요청하는 것이고, 그 요청이 거절되면 이 코드가 난다.

죽은 대상이 `wsl.exe`였다

GitLab도 아니고 엔진도 아니다. wsl.exe는 배포판을 켜는 Windows 쪽 명령이고, 컨테이너 메모리와는 상관이 없다. GitLab이 아무리 커져도 이 명령이 죽을 일은 아니다.

로그를 순서대로 읽으면 어디서 터졌는지 나온다

wsl-bootstrap은 Docker Desktop이 docker-desktop 배포판 안에서 돌리는 준비 프로그램이다. 엔진이 뜰 환경을 만드는 일을 순서대로 한다.

componentsVersion.json 없음               [W] 경고.  첫 부팅이면 정상
detected existing ext4 file system        데이터 디스크를 찾았다 (이미지 · 볼륨)
docker-desktop.iso is present in cache    엔진 이미지가 이미 있다
starting linuxkit container with unshare  엔진을 격리해서 띄운다
Restoring existing exposed ports          전에 열려 있던 포트를 복원한다
starting cross-distro routing service     배포판끼리 통신하는 경로를 연다
tcp forward 0.0.0.0:2424 → 172.18.0.2:22
tcp forward 0.0.0.0:8929 → 172.18.0.2:8929
                                          ← 여기서 exit 0xc00000fd

마지막 두 줄이 GitLab 컨테이너의 포트를 Windows 쪽으로 내보내는 작업이다.

2424 · 8929      docker-compose.yml 에 적어 둔 포트.  SSH 와 HTTP
172.18.0.2       GitLab 컨테이너가 받은 IP

GitLab은 이미 떠서 IP까지 받은 상태였다. restart: unless-stopped가 걸려 있어 엔진이 뜨자마자 따라 뜬 것이고, 그 마지막 연결 작업 중에 wsl.exe가 죽었다.

`wsl.exe`가 죽으면 그 밑이 전부 끌려간다

wsl.exe 가 죽는다
  → WSL2 VM 이 내려간다
     → docker-desktop 배포판이 내려간다  →  gitlab 컨테이너도 끝난다
     → Ubuntu 배포판도 같이 내려간다

GitLab에 SIGKILL을 보낸 것이 무엇인지가 여기서 갈린다. 컨테이너가 자기 한도를 넘은 것도, VM 안에서 리눅스 커널이 골라 죽인 것도 아니었다. VM 자체가 내려가면서 그 위의 것이 전부 끝난 것이다.

작업 중에 kubectl이 갑자기 안 먹고 wsl -l -v에 Ubuntu가 Stopped로 바뀌어 있던 것도 같은 이유였다. Ubuntu 쪽에서 뭘 잘못한 게 아니라 Docker 쪽 사고에 같이 휩쓸린 것이다.

질문이 옮겨진다

전    GitLab 이 왜 죽었나
후    wsl.exe 가 스택을 늘리려는 요청은 왜 거절됐나

문제가 리눅스 안이 아니라 Windows 쪽에 있다. 그러면 다음으로 볼 것은 하나다 — 그때 Windows에 메모리가 없었나.

3.3 물리 메모리는 남아 있었다

요청이 거절됐다면 물리 RAM이 바닥나 있어야 말이 된다. 그때 값을 봤다.

Get-CimInstance Win32_OperatingSystem | ForEach-Object {
  "물리 {0:N1}GB / 여유 {1:N1}GB" -f ($_.TotalVisibleMemorySize/1MB), ($_.FreePhysicalMemory/1MB) }

물리 16.0GB / 여유 6.6GB

6GB 넘게 남아 있었다. 메모리가 없어서 못 준 것이 아니다.

3.4 그래서 남은 것

wsl.exe가 죽은 순간에 한 일은 하나였다. 스택을 한 칸 더 쓰려고 Windows에 "메모리를 조금만 더 달라"고 한 것이다. Windows는 그것을 거절했고, 그래서 STATUS_STACK_OVERFLOW로 끝났다.

① 물리 메모리는 6.6GB 남아 있었다        메모리가 없어서 못 준 것이 아니다
② 그런데 그 요청은 거절됐다               있는데도 안 준 것이다

주문까지 넣은 진단이 여기서 무너졌다. 램을 24GB로 늘려도, 물리가 남아 있는데 거절하는 그 무언가가 그대로면 같은 일이 또 난다.

Windows 는 물리 RAM 이 남아 있어도 메모리 요청을 거절할 수 있다
그렇게 만드는 다른 한도가 있다

그 한도가 무엇인지 찾기 시작했다.

4. 진짜 원인 — 커밋 한도

작업 관리자 성능 탭을 열었다. 프로세스 목록이 프로그램별로 보여주는 것과 달리, 여기는 Windows 쪽 메모리를 통째로 보여준다.

사용 중 (압축)   프로세스들이 쥐고 있는 물리 메모리.  괄호는 그중 압축해 눌러 담은 몫
사용 가능        지금부터 새 프로그램이 받을 수 있는 양
캐시됨          디스크에서 읽어 둔 사본.  필요하면 버린다
커밋됨          ← 이것만 성격이 다르다                                        ★
페이징 풀        커널이 쓰는 몫 중 디스크로 밀어낼 수 있는 것
비페이징 풀       커널이 쓰는 몫 중 항상 물리에 있어야 하는 것 (드라이버 등)
사용된 슬롯       메모리 슬롯이 몇 개 차 있나

`free -h`와 나란히 놓아 보면

VM 안을 볼 때 쓴 명령이 free -h였다. 같은 "메모리 장부"인데 재는 대상이 다르다 —
이쪽은 VM 안(total 5.8Gi는 .wslconfig의 memory=6GB에서 커널 몫을 뺀 값)이고,
성능 탭은 Windows 전체(물리 16.0GB)다.

아래 값은 다른 시점에 잰 것이라 위 성능 탭 숫자와 짝이 맞지 않는다. 여기서 볼 것은 값이 아니라 칸 이름이다.

wsl -d Ubuntu -- free -h

               total   used   free   shared  buff/cache  available
Mem:           5.8Gi   3.2Gi  98Mi   98Mi    2.8Gi       2.6Gi
Swap:          4.0Gi   424Ki  4.0Gi

칸끼리 대응시키면 이렇다.

used ↔ 사용 중 — 프로세스가 실제로 쥐고 있는 양
buff/cache ↔ 캐시됨 — 디스크에서 읽은 파일을 RAM에 남겨 둔 사본이다. 원본이 디스크에 그대로 있어 언제든 버려도 되고, 그래서 available·사용 가능 안에 이미 포함돼 있다
available ↔ 사용 가능 — 지금부터 새로 쓸 수 있는 양
Swap ↔ 페이지파일 — RAM이 모자랄 때 안 쓰는 것을 내려두는 디스크 자리다. 캐시와 방향이 반대라 버릴 수 없다 — RAM에만 있던 내용이라 디스크에 써 두지 않으면 사라진다. 다만 이 Swap 4.0Gi는 VM 안 리눅스의 것(.wslconfig의 swap=4GB)이고, Windows 페이지파일과는 별개다
커밋됨 ↔ 대응하는 칸이 없다 ★

`free -h`에는 커밋에 해당하는 칸이 없다

리눅스는 요청을 일단 받아준다. 예약 총량으로 벽을 세우지 않고, 실제로 물리가 바닥나면 그때 OOM killer가 프로세스를 골라 죽인다.

Windows는 반대다. 예약 단계에서 한도를 넘으면 그 자리에서 거절한다. 죽이는 대신 요청이 실패하고, 요청한 쪽이 알아서 무너진다.

리눅스      일단 받는다   →  물리가 바닥나면  →  누군가를 죽인다      OOM killer 가 있다
Windows    한도를 넘으면  →  그 자리에서 거절  →  요청한 쪽이 실패한다   OOM killer 가 없다

free -h만 봐서는 이번 원인이 안 잡히는 이유가 여기 있다. 문제를 만든 항목이 리눅스 쪽 화면에는 아예 없다.

`커밋됨`만 분모가 다르다

사용 중 · 사용 가능    합치면 물리 RAM 이 된다        9.4 + 6.6 = 16.0 GB
커밋됨               분모가 물리 RAM 이 아니다       15.5 / 17.9 GB

물리 여유             6.6 GB
커밋 여유             2.4 GB

분모가 물리보다 크다는 것은 물리와 다른 것을 재고 있다는 뜻이고, 여유도 물리 쪽과 따로 논다. 물리가 요청을 막은 것이 아니라면 남는 후보는 이쪽이다.

그래서 둘을 봐야 했다 — 커밋이 무엇이고, 왜 한도가 하필 17.9GB인가.

4.1 커밋이 무엇인가

프로그램이 메모리를 요청하면 Windows는 물리 RAM을 바로 주지 않는다. "이만큼은 보장한다"고 예약만 해 둔다.

1GB 를 요청한다        예약 +1GB      물리 RAM 은 아직 안 썼다
100MB 를 실제로 쓴다    물리 +100MB    예약은 여전히 1GB
나머지 900MB          안 쓰고 있는데도 계속 예약돼 있다

안 쓰고 있어도 다른 프로그램이 그 자리를 못 쓴다. Windows가 이미 약속해 뒀기 때문이다.

한 번에 다 예약하는 것도 아니다. 탭을 열고 파일을 열 때마다 조금씩 더 요청하고, 프로그램이 끝나면 그 몫이 통째로 풀린다. 커밋은 작업하는 내내 오르내리는 값이다.

지금 돌고 있는 모든 프로그램의 예약을 전부 더한 것이 커밋이고, 그 합이 넘을 수 없는 선이 커밋 한도다.

커밋됨   15.5 / 17.9 GB
         커밋      한도

한도가 물리 RAM보다 크다

물리 RAM     16.0 GB
커밋 한도     17.9 GB      물리보다 1.9GB 더 크다

없는 메모리를 약속해 둔 셈이다. 그게 가능한 이유가 페이지파일이고, 이 1.9GB가 곧 페이지파일 크기다.

4.2 페이지파일이 무엇인가

약속을 지키려면 실제로 내줄 자리가 있어야 한다. 물리 RAM이 비어 있으면 거기서 주고, 다 찼으면 페이지파일에서 자리를 만든다.

페이지파일은 디스크에 만들어 둔 파일이고, 물리 RAM 자리를 돌려쓰게 해 주는 임시 보관소다.

물리 RAM 16GB 가 다 찼는데 새 프로그램이 1GB 를 달라고 한다

① Windows 가 지금 안 쓰는 1GB 를 고른다        예: 30분째 안 만진 Chrome 탭
② 그 내용을 페이지파일에 써 둔다                디스크로 옮긴다
③ 비워진 물리 RAM 1GB 를 새 프로그램에게 준다
④ 나중에 그 Chrome 탭을 다시 보면              디스크에서 읽어 다시 올린다.  느리다

리눅스의 swap과 같은 역할이다. 약속한 총량이 동시에 물리에 올라와 있을 필요가 없어지므로, 물리 16GB로 그보다 큰 총량을 약속할 수 있다. 페이지파일이 한도에 그대로 더해지는 것이 이 때문이다.

대가는 속도다. 디스크로 내려간 것을 다시 쓰려면 읽어 올려야 하고, RAM보다 훨씬 느리다.

크기는 보통 Windows에 맡긴다

Windows 기본값이 자동 관리이고, 그때 Windows가 하는 일이 이렇다.

크기 결정    물리 메모리 · 커밋 총량 · 크래시 덤프 설정을 보고 정한다
최소        RAM ÷ 8 (최대 32GB)
확장        커밋이 한도의 90% 를 넘으면 늘린다
최대        물리 메모리의 3배 또는 4GB 중 큰 값.  단 그 볼륨 크기의 1/8 이하

얼마로 잡아야 하는지에 대해 공식 문서는 고정 비율을 주지 않는다.

페이지파일 크기는 크래시 덤프 설정과 커밋 총량의 피크에 달려 있고, 둘 다 시스템마다 다르다. 그래서 페이지파일 크기도 시스템마다 다르며 일반화할 수 없다.
— How to determine the appropriate page file size for 64-bit versions of Windows

자동 관리는 그 판단을 Windows가 대신해 주는 것이다. 커밋이 차오르면 늘리고 한가해지면 줄이니, 내가 피크를 재서 숫자를 정할 필요가 없다.

대신 디스크를 먹는다

페이지파일은 실제로 디스크에 만들어지는 파일이다. 8GB로 잡으면 그 드라이브에서 8GB가 사라지고, 자동으로 두면 필요할 때 더 커지므로 그만큼 더 먹는다.

그래서 "디스크 용량 확보"를 검색하면 페이지파일을 줄이거나 끄라는 방법이 나온다.

자동 관리를 끈다
C: 를 "페이징 파일 없음" 으로 바꾼다      C 에서 그만큼 용량이 돌아온다
필요하면 다른 드라이브에 작게 만든다

공간은 실제로 늘어난다. 대신 커밋 한도가 그만큼 깎인다.

그래서 설정을 열어 봤다

뺄셈으로 나온 페이지파일 크기가 1.9GB(커밋 한도 17.9 − 물리 16.0)였다. 자동 관리였다면 커밋이 한도에 닿아 가는 동안 늘어났어야 한다. 안 늘어났다는 것은 누군가 수동으로 크기를 고정해 뒀다는 뜻이다.

어떻게 잡혀 있는지 보러 갔다.

4.3 고정 페이징 파일 크기가 2GB로 고정돼 있었다

Win + R → sysdm.cpl → 고급 탭 → 성능 설정 → 고급 탭 → 가상 메모리 변경\

가상 메모리 대화상자 — C: 없음, E: 512 - 2048

자동 관리 체크가 꺼져 있다        크기를 Windows 가 아니라 내가 정하고 있다
C:  없음                       232GB 짜리 드라이브에 페이지파일이 아예 없다
E:  512 - 2048                 여기 하나뿐이고 최대가 2048MB 다
현재 총 크기 1960MB

1960MB가 뺄셈으로 나온 그 1.9GB다. 예상한 대로였다.

두 줄이 겹쳐서 천장이 고정됐다

자동 관리 해제      크기를 정하는 주체가 Windows 에서 나로 바뀐다
최대 2048MB       그렇게 내가 넣어 둔 천장이 2GB 다

이 둘은 나란한 두 원인이 아니라 하나를 두 각도에서 말한 것이다. 체크를 풀지 않으면 크기 칸이 잠겨서 값을 넣을 수 없고, 값을 넣어 두면 Windows는 그 위로 못 올린다(내 데스크탑 상황).

커밋 한도 = 물리 16.0GB + 페이지파일 1.9GB = 17.9GB

이 값이 뒤의 모든 거절을 만든다.

이 설정을 언제 했는지도 기억이 났다. 예전에 C 드라이브 용량이 모자라 "디스크 용량 확보"를 찾아보고 그대로 따라 한 것이다. 그때는 페이지파일이 커밋 한도를 정한다는 것을 몰랐다.

4.4 왜 그게 `0xc00000fd` 를 만드나

여기까지 나온 것을 모으면 이렇다.

4.1   커밋 = 프로그램들이 약속받아 둔 총량.  커밋 한도 = 그 합이 넘을 수 없는 선
4.2   커밋 한도 = 물리 RAM + 페이지파일
4.3   자동 관리가 꺼진 채 페이지파일이 2GB 로 고정돼 있었다  →  한도 17.9GB

문제의 상황에 물리적인 램 사용율과 커밋률에 대한 숫자가 이랬다.

사용 중 9.4 GB  +  사용 가능 6.6 GB  =  16.0 GB      물리는 이렇게 나뉘어 있다
커밋됨          15.5 / 17.9 GB                      약속은 이만큼 나가 있다

물리와 커밋은 다른 장부다

물리 장부    지금 실제로 어디에 무엇이 올라와 있나
커밋 장부    앞으로 누구에게 얼마를 주기로 했나

약속(15.5GB)이 실제 사용(9.4GB)보다 크다. 차이 6.1GB는 약속만 받고 아직 안 쓴 몫이고, 지금 어디에도 실체가 없다. 장부에만 적혀 있다.

그래서 `사용 가능 6.6GB`를 새로 못 준다

약속은 했는데 아직 안 쓴 몫       6.1 GB   (커밋됨 − 물리 사용 중 = 15.5 − 9.4)
그것이 나중에 쓰이면 들어갈 자리    사용 가능 6.6 GB

사용 가능 6.6GB는 아무나 써도 되는 자리가 아니라, 이미 약속된 6.1GB가 들어올 자리다.(왜 6.1GB? 커밋된 용량 15.5에서 물리적 사용중인 용량 6.4를 빼면 나오는 값 - 미리 쓴다고 약속된 값 = 커밋)

여기에 새 요청까지 받아주면 같은 자리를 두 번 약속하는 셈이 된다. Windows는 그것을 안 한다.

빼고 남는 것이 실제로 새로 줄 수 있는 양이다.

사용 가능           6.6 GB
− 이미 약속된 몫      6.1 GB
────────────────────────
물리에서 남는 것      0.5 GB
+ 페이지파일          1.9 GB
────────────────────────
커밋 여유           2.4 GB      ← 17.9 − 15.5 와 같다

작업 관리자가 보여주던 커밋 여유 2.4GB가 바로 이 계산의 결과다.

거기서 GitLab을 띄웠다

.wslconfig의 memory=6GB는 VM 쪽 상한이지, Windows가 그만큼 내주겠다는 보장이 아니다. VM이 커지는 만큼 Windows 커밋 장부를 그대로 먹는다.

그 상태            커밋 여유 2.4 GB
wsl 을 친다        Ubuntu 부팅으로 VM 이 커진다.  실측 Vmmem +1.3GB
                  → 커밋 여유 약 1.1 GB
GitLab 까지 뜬다    컨테이너 정착만 2.9 GiB 를 요구한다
                  → 남은 1.1GB 로는 못 받는다

여유가 여기서 바닥났다.

거절당한 것은 `wsl.exe` 였다

GitLab이 요청했다가 거절당한 것이 아니다. 여유를 먹은 쪽과 거절당한 쪽이 다르다.

GitLab 이 커진다  →  VM 이 Windows 에 커밋을 더 요구한다  →  여유가 바닥난다
                                                          ↓
                            wsl.exe 가 스택 커밋을 요청한다  →  거절  →  0xc00000fd

스택은 처음부터 크게 잡지 않고 깊이 들어갈 때마다 새 페이지를 커밋해 늘려 간다. 그 커밋이 거절되면 Windows는 STATUS_STACK_OVERFLOW로 보고한다. 요청이 크든 작든 상관없다 — 여유가 모자라면 똑같이 거절이다.

그리고 wsl.exe가 죽으면 VM이 통째로 내려가면서 그 위의 배포판과 컨테이너가 전부 끝난다. GitLab이 oomkilled=false에 exit 137만 남긴 것이 이래서다. 자기 한도를 넘은 것이 아니라 밑이 꺼진 것이다.

그래서 어떤 날은 되고 어떤 날은 죽었다

커밋은 탭을 열고 닫을 때마다 오르내리는데 한도는 17.9GB에 고정돼 있다. 여유가 2.4GB밖에 없는 상태에서는, 그날 켜 둔 것이 조금만 달라도 GitLab이 들어가기도 하고 안 들어가기도 한다.

같은 작업인데 결과가 갈리던 것이 이 폭이었다.

4.5 사슬 전체

① 페이지파일을 E 드라이브에 최대 2048MB 로 고정해 뒀다     자동 관리 해제 상태
② 커밋 한도 = 물리 16.0GB + 1.9GB = 17.9GB
③ 크롬 · VS Code · Windows 가 15.5GB 를 약속받아 뒀다     여유 2.4GB
④ GitLab 을 띄우자 VM 이 커밋을 더 요구했다               여유가 바닥난다
⑤ 그다음 커밋 요청이 거절됐다                            물리는 6.6GB 남았지만 한도가 먼저 막았다
⑥ 그 요청을 한 쪽이 wsl.exe 의 스택이었다                 0xc00000fd
⑦ wsl.exe 가 죽고 VM 이 통째로 내려갔다                   Ubuntu 도 GitLab 도 같이

⑤에서 거절당하는 쪽은 그때그때 다르다. Chrome이 요청했으면 탭이 비워지고, VS Code면 통째로 다시 뜬다. 날마다 죽는 것이 달라 규칙이 없어 보이던 것이 이것이었다 — 원인은 하나인데 걸리는 쪽이 매번 달랐다.

문제는 요구가 아니라 천장이었다

요구    크롬 탭 · VS Code 확장 · VM.  작업하는 내내 오르내린다
천장    자동 관리를 꺼 두고 2048MB 로 고정해 뒀다.  안 움직인다

Windows에서 커밋이 물리 RAM을 넘는 것은 사고가 아니라 기본 동작이다. 프로그램은 언제나 실제 쓸 양보다 크게 예약하고, 그 초과분을 받아주라고 페이지파일이 있다. 커밋이 15.5GB까지 오른 것 자체는 정상이다.

문제는 천장이 물리보다 1.9GB밖에 높지 않았던 것이고, 그것은 램이 모자라서가 아니라 내가 그렇게 설정해 뒀기 때문이다.

천장을 올리는 방법은 둘이고, 둘 다 유효하다.

램을 24GB 로 늘린다        한도 = 24 + 1.9 = 25.9 GB     8GB 오른다.  부품값이 든다
페이지파일 상한을 올린다     한도 = 16 + 12 = 28.0 GB      12GB 오른다.  돈이 안 든다

다만 막힌 곳이 천장이라면 먼저 되돌릴 것은 내가 잘라 놓은 쪽이다. 램은 그다음이다.

5. 고친 과정

5.1 페이지파일을 다시 세웠다

두 번에 나눠 했다. 먼저 C:에 8GB를 잡아 한도부터 올려 죽는 것이 멈추는지 봤고, 멈춘 것을 확인한 뒤 자리를 E:로 옮기면서 12GB로 키웠다.

고치기 전    C: 없음           E: 512 - 2048       한도 17.9 GB
1차         C: 8192 - 16384   E: 없음             한도 24.0 GB
2차         C: 없음           E: 12288 - 16384    한도 28.0 GB

1차만으로 GitLab이 죽지 않고 계속 떠 있었다. 원인을 제대로 짚었다는 것이 여기서 확인됐다.

다만 그동안 커밋이 최고 20.4GB까지 올라갔다. 한도 24.0GB에 3.6GB까지 붙은 것이라, 2차에서 자리를 옮기면서 크기를 키웠다.

Win + R → sysdm.cpl → 고급 탭 → 성능 설정 → 고급 탭 → 가상 메모리 변경

자동 관리 체크    해제 그대로 둔다
C:              페이징 파일 없음
E:              사용자 지정 크기.  처음 12288 MB / 최대 16384 MB

값을 넣고 설정(S)을 눌러야 목록에 반영된다. 그 상태로 확인하고 재부팅해야 적용된다.

왜 `C:`가 아니라 `E:`인가

디스크 0   Samsung SSD 850 EVO 120GB   →  E:   111GB 중 35.5GB 여유
디스크 1   WDC WDS250G2B0A (WD Blue)   →  C:   232GB 중 16.8GB 여유

C:의 16.8GB는 이미 8GB 페이지파일이 올라간 상태의 여유다. 여기에 12GB를 두면 12.8GB가 남고, 나중에 16GB까지 자라면 8.8GB가 된다. 232GB짜리 시스템 드라이브에 남길 여유로는 빠듯하다.

E:에 두면 C:의 여유가 24.8GB로 돌아오고, E:에도 19.5GB가 남아 나중에 더 키울 자리가 있다.

성능상으로도 불리하지 않다. 둘 다 SATA SSD라 느려질 이유가 없고, 물리 디스크가 서로 달라 OS의 디스크 작업과 페이징이 같은 디스크를 놓고 다투지 않는다.

왜 자동 관리가 아니라 수동인가

자동 관리로 두면 Windows가 최대치를 물리의 3배 또는 4GB 중 큰 값, 단 그 볼륨 크기의 1/8 이하로 잡는다. E:에 대입하면 이렇게 된다.

물리의 3배        48.0 GB
볼륨의 1/8        111GB ÷ 8 = 13.9 GB      ← 둘 중 작은 쪽이 천장이 된다

E:에 자동 관리를 걸면 최대가 13.9GB에서 막힌다. 수동으로 16384를 넣는 쪽이 천장이 더 높다.

왜 12288 - 16384 인가

관측된 커밋 피크    20.4 GB       GitLab + Ubuntu + Chrome + VS Code 를 다 켠 상태
물리              16.0 GB
최소로 필요한 것    20.4 − 16.0 = 4.4 GB

처음 12288        한도 28.0GB 로 부팅한다.  피크 대비 7.6GB 여유
최대 16384        모자라면 32.0GB 까지 자란다

처음 크기를 크게 잡으면 커밋이 몰릴 때 파일이 자라기를 기다리지 않아도 되고, 파일이 한 덩어리로 잡혀 조각나지 않는다. 대가는 E:에서 12GB가 계속 나가 있는 것 하나다.

5.2 커밋 한도가 28.0GB가 됐다

재부팅하고 같은 자리를 다시 봤다.

                    고치기 전            고친 후
──────────────────────────────────────────────────────
페이지파일            E:  512 - 2048      E:  12288 - 16384
커밋 한도             17.9 GB             28.0 GB       ← 바뀐 것은 이 줄뿐이다
물리 RAM             16.0 GB             16.0 GB        한 장도 안 바꿨다

커밋 총량이 비슷한 시점끼리 견주면 여유가 이렇게 갈린다.

고치기 전    커밋 15.5 / 17.9 GB    여유  2.4 GB
고친 후      커밋 15.1 / 28.0 GB    여유 12.9 GB

켜 둔 것이 같아서가 아니라 한도가 달라서 벌어진 차이다. 커밋을 만든 쪽은 그때나 지금이나 Chrome·VS Code·Windows이고, 바꾼 것은 페이지파일 한 줄이다.

정리

증상          하루에 열 번 가까이 뭔가가 죽었다
처음 진단      메모리 80퍼센트.  물리 램 부족으로 보고 8GB 두 장을 주문했다
안 맞은 기록    oomkilled=false  ·  0xc00000fd  ·  물리 여유 6.6GB
진짜 원인      커밋 한도 17.9GB.  페이지파일을 2GB 로 고정해 둔 설정이 그대로 남아 있었다
고친 것        페이지파일 12GB.  한도 28.0GB.  커밋 여유 2.4 → 12.9GB

증상이 가리키는 곳과 원인이 있는 곳이 달랐다. 메모리가 80퍼센트라는 것은 사실이었지만 그것이 죽은 이유는 아니었고, 죽은 이유는 같은 화면의 다른 칸에 있었다.

그 칸을 읽을 줄 몰라서 램을 주문했다.

그래서 램 주문은 취소했다

주문한 것    DDR3 8GB × 2      4GB 두 장을 빼고 넣을 생각이었다
근거        메모리 80퍼센트.  뭔가가 계속 죽는다

그 근거가 기록과 안 맞았다. 물리 RAM은 6.6GB가 남은 상태에서 요청이 거절됐고, 페이지파일만 바꾸니 커밋이 비슷한 시점끼리 견줘 여유가 2.4GB에서 12.9GB가 됐다.

램이 한 일이 없다.

그렇다고 안 사도 된다는 뜻은 아니다

물리 16GB는 그대로다. 천장을 올린 것이지 RAM을 늘린 것이 아니다. 그래서 언제 사야 하는지를 미리 숫자로 정해 뒀다.

① 천장을 더 올려도 또 닿는다

지금        16 + 12 = 28.0 GB       필요하면 16 까지 자라 32.0 GB
더 올린다    최대를 24576 으로       16 + 24 = 40.0 GB.  E: 여유로 가능하다

아직 페이지파일 쪽에 올릴 자리가 남아 있다. 그것까지 하고도 거절이 나면 물리가 답이다.

② 안 죽는데 느려진다

천장이 낮다      요청이 거절된다    →  죽는다        천장을 올리면 해결된다
물리가 모자라다   요청은 통과한다    →  디스크를 오간다  →  느려진다   천장으로는 해결 안 된다

페이지파일을 40GB로 잡아도 물리 16GB를 넘는 몫은 결국 디스크를 오간다. 이것은 램 말고 답이 없다.

둘을 가르는 값

PeakUsage 하나다. 페이지파일로 실제로 얼마나 밀려났는지를 알려주는 값이고, 지금은 1MB다.

1MB 근처에 머문다      밀어낼 일이 없었다.  물리로 충분하다  →  램은 아직 필요 없다
GB 단위로 오른다       물리가 모자라 밀어내기 시작했다        →  ②

이 값이 오르기 시작하는 때가 램을 다시 볼 때다.

넣는다면

지금    DDR3 4GB × 4 = 16GB              슬롯 4개가 전부 차 있다
교체    8GB × 2 + 4GB × 2 = 24GB          추가가 아니라 교체다
한도    24 + 12 = 36.0 GB                 페이지파일을 안 건드려도 8GB 오른다

램을 늘렸다고 페이지파일을 따라 늘릴 이유는 없다. 물리가 커지면 밀어낼 일이 줄어들어 수요는 오히려 준다.

노트북 홈서버 k3s 구축기 - 9. GitLab 세우기

hsb_02 — Tue, 4 Aug 2026 09:49:11 +0900

0. 이어받기

8부 끝에서 관측 파이프라인은 흐른다. 같은 k3s 프로세스를 kubelet·apiserver 두 job으로 겹쳐 긁던 시리즈 사본을 걷어 거절이 0이 됐고, 파이프라인 자신을 보는 계기판도 Mimir 3축 12패널로 섰다. 계기판은 git에 push하면 ArgoCD가 가져가 Grafana에 앉힌다 — 커밋이 곧 배포다.

1–5부에서 호스트와 노드, 6부에서 클러스터, 7부에서 플랫폼과 GitOps 인계, 8부에서 관측까지 섰다. 남은 길은 앱을 향한다 — 10부 이미지, 11부 앱 배포, 12부 앱 관측, 13부 부하와 스펙 산정, 14부 외부 공개.

지금 비어 있는 자리는 넷이다.

push마다 최대 3분을 기다린다. ArgoCD가 GitHub를 주기적으로 다시 읽는 방식이라, 8부에서 계기판을 고칠 때마다 이 대기를 반복했다.
계기판은 열어봐야 안다. 알림 셋은 조건까지 확정했고 구현이 비어 있다.
클러스터 자체를 보는 눈이 없다. 계기판의 질문은 "관측이 도는가"였다. "클러스터가 건강한가"를 보는 대시보드는 아직 한 장도 없다.
Grafana·ArgoCD가 kubectl port-forward로만 열린다. 명령을 띄워 둔 동안만 내 PC의 포트가 파드로 이어지고, 터미널을 닫으면 끊긴다.

이 편이 하는 일

Git 서버(GitLab)를 데스크탑에 세우고 GitOps 소스를 그리로 옮긴다. Git 서버가 ArgoCD와 같은 망에 서면 webhook이 성립해 push 즉시 sync가 된다.

지금:  push ─▶ GitHub ─(3분 폴링)─ ArgoCD ─▶ 클러스터
9부:   push ─▶ GitLab(데스크탑) ─ webhook ─▶ ArgoCD ─▶ 클러스터
                     └─ 미러 ─▶ GitHub(쇼케이스)

webhook이 성립하려면 GitLab이 ArgoCD를 주소로 부를 수 있어야 하고, 그러려면 ArgoCD가 포워딩이 아니라 고정된 주소로 서야 한다 — 넷째 자리가 여기서 같이 닫힌다. 루프가 초 단위가 되면 그 위에서 알림 룰과 인프라 대시보드를 만든다. 둘 다 git push로 배달되는 물건이라, 네 자리가 이 한 흐름으로 닫힌다.

순서는 이렇게 간다.

1. 왜 Git 서버를 직접 세우나   지금 끊긴 구간
2. 개념과 출발선              Git 서버 · CI/CD · GitOps — 지금 배선과 자리 만들기
3. 구조와 설치                물건 · 부품 · omnibus · 기동 · 저장소 이전 · 미러
4. GitLab을 운영 원본으로     브랜치 · 자격 · 노출 · repoURL 전환 · webhook
5. 루프 위에서                알림 셋 · 인프라 대시보드 두 장
6. 대조와 다음                닫는 조건 · 보안 되짚기 · 10부로

1. 왜 Git 서버를 직접 세우나

이 홈랩의 목표는 온프레미스 서버 한 대에 stg·prd로 나아갈 수 있는 dev 환경을 세우는 것이다. 배포판은 k3s, 배포할 서비스는 CGV 예매 대기열(queue·booking·frontend)이고 docker compose에서 예매 왕복까지 확인된 상태다(cgv-onprem).

서비스가 클러스터에 뜨려면 코드만으로는 안 된다. 코드가 배포까지 가는 길이 있어야 한다.

Git 저장소 ─▶ CI(러너)가 이미지 빌드 ─▶ 레지스트리에 저장 ─▶ CD가 클러스터에 반영

7부에서 App으로 걸어만 둔 앱 셋이 ImagePullBackOff(받아 올 이미지가 없어 파드가 재시도만 반복하는 상태)로 멈춰 있는 것이 이 길이 끊겼다는 증거다. 구간별로 보면 이렇다.

Git 저장소 — 코드는 GitHub(관리형)에 있다. 직접 운영하는 Git 서버는 없다.
CI(러너) — 없다. 이미지를 만들 곳이 없다.
레지스트리 — 없다. 만든 이미지를 올릴 곳이 없다.
CD — ArgoCD가 자리를 잡고 있다(7부에서 인계). 앱 이미지가 흘러들 길이 없을 뿐이다.

이 빈 구간들을 채우는 답으로 GitLab 셀프호스팅을 골랐다. 저장소·CI 러너·레지스트리가 한 제품에 들어 있어, GitHub가 맡던 저장소 자리까지 옮기면 코드가 배포되기까지의 전 구간이 한 자리에 선다.

폴링 문제도 같은 자리에서 풀린다. GitHub은 인터넷 쪽에 있고 이 클러스터는 공유기 뒤 사설 IP라, 밖에서 안으로 들어오는 연결이 닿지 않는다 — GitHub이 ArgoCD를 부를 방법이 없다. Git 서버가 같은 망에 서면 그 호출이 성립한다.

세우는 모양은 셋으로 정했다.

자리 = 클러스터 밖. 정본이 자기가 정의하는 대상 안에 살면 대상과 함께 무너진다. 어느 장비인지는 무게까지 재서 정한다.
역할 = GitLab이 운영의 원본. GitOps 소스도 러너·CI·레지스트리도 여기 얹고, GitHub는 미러로 받는 사본이 된다.
범위 = 이 편은 루프 완성까지. 나머지 셋이 10부에서 서면 앱 이미지가 생기고, 11부에서 앱이 뜬다.

2. 개념과 출발선 — Git 서버, CI/CD, GitOps

이 편에서 만지는 이름은 셋이다 — Git 서버, CI/CD, GitOps. 겹쳐 다니지만 다른 물건이다.

2.1 Git 서버 — 원본이 앉는 자리

Git 자체는 어느 한 곳을 원본으로 정하지 않는다. 저장소의 완전한 복제가 내 컴퓨터에도 서버에도 있고, push·pull은 복제끼리 맞추는 동작이다. 다만 여러 사람과 여러 도구가 한 저장소를 쓰려면 "여기가 원본"이라고 합의한 자리가 필요하다. 그 자리를 드는 것이 Git 서버고, 지금까지 그 자리는 GitHub였다.

2.2 CI/CD — 코드가 클러스터까지 가는 길

CI(Continuous Integration) — push된 코드를 자동으로 빌드·검사해 산출물로 만드는 것. 여기서 산출물은 컨테이너 이미지고, 빌드를 실제로 도는 일꾼이 러너다. 러너가 만든 이미지는 레지스트리에 올라간다.
CD(Continuous Deployment) — 그 산출물이 실제 환경에 반영되는 것.

CD에는 방향이 둘 있다.

push형 — 파이프라인이 밖에서 클러스터로 kubectl·helm을 쏜다.
pull형 — 클러스터 안의 에이전트가 git을 보고 스스로 상태를 맞춘다.

이 클러스터는 pull형이다. 클러스터 전권 자격을 바깥 파이프라인에 내주지 않아도 되고, git과 클러스터가 계속 대조된다. 그 방식의 이름이 GitOps다.

2.3 GitOps — git이 정본, 클러스터가 따라온다

선언은 하나다. 저장소가 원하는 상태의 정본이고, 클러스터의 실제 상태는 그걸 따라온다. 7부에서 "커밋이 곧 배포"가 된 것이 이 선언을 켠 것이다.

따라오게 만드는 동작은 ArgoCD의 세 단계 반복이다.

① refresh   저장소를 읽어 "원하는 상태"를 갱신한다     ← 기본 3분 주기 폴링
② diff      클러스터의 "실제 상태"와 비교한다
③ sync      다르면 적용한다

sync를 자동으로 돌릴지는 Application의 정책으로 정한다. 손으로 kubectl을 쳐서 바꾼 것을 되돌리고(selfHeal), 정본에서 지운 것을 클러스터에서도 걷는(prune) 동작은 그 정책 아래 각각 켜 두는 옵션이고 기본값은 꺼짐이다. 켜야 정본과 실제가 계속 같아진다.

폴링은 설정 없이 돌지만 push와 반영 사이에 최대 한 주기가 낀다. webhook은 방향이 반대다 — git 서버가 push를 받는 순간 ArgoCD의 수신 주소(/api/webhook)를 호출해 refresh를 그 자리에서 당긴다. 그래서 webhook은 설정 문제이기 전에 "git 서버가 ArgoCD에 닿을 수 있는가"라는 네트워크 문제다.

2.4 지금 배선의 좌표 셋

개념을 실물에 대면 세 가지가 잡힌다.

클러스터가 저장소를 보게 만든 것은 7부의 root-app이다 — 저장소에 있는 다른 Application 정의들을 읽어 오는 최상위 Application 하나로, 이것만 손으로 넣으면(kubectl apply 한 번) 나머지는 저장소에서 딸려 온다.
App 19개가 각각 repoURL로 GitHub의 cgv-infra를 가리킨다. repoURL은 그 App이 읽어 갈 저장소 주소를 적는 칸이고, 그 자리는 13개 파일에 걸친 14줄이다(repoURL 11줄 + AppProject의 sourceRepos 3줄. AppProject는 App 묶음이 어느 저장소를 읽어도 되는지 범위를 정하는 리소스라, 여기 없는 주소는 App이 가리켜도 거부된다). 소스를 옮긴다는 것은 이 14줄을 바꾼다는 뜻이다.
앱 코드(cgv-onprem)는 ArgoCD가 보지 않고, ArgoCD 자신은 ClusterIP뿐이다. 앱 배포는 차트가 가리키는 이미지로 일어나고, ArgoCD는 클러스터 밖에서 닿을 주소가 없다.

2.5 자리 만들기 — 주소 고정과 Docker

데스크탑에 GitLab이 서기 전에 자리 둘을 만든다.

주소 고정. GitLab이 서면 데스크탑을 찾아오는 쪽이 생긴다 — repoURL·git remote·webhook에 이 주소가 들어간다. 데스크탑 IP는 DHCP 자동 할당이라 바뀔 수 있으므로, 공유기에 DHCP 예약(이 MAC에는 항상 이 주소)을 건다. 기기 쪽 설정은 그대로고 결과만 고정된다.
Docker Desktop. GitLab은 리눅스 프로그램이라 Windows에서 직접 못 돈다. Docker Desktop은 WSL2(Windows 안에서 리눅스 커널을 통째로 돌리는 가상머신 계층) 안의 리눅스에서 컨테이너를 돌리고, 컨테이너가 연 포트를 Windows 호스트 포트로 이어준다 — 클러스터가 데스크탑 IP로 찾아왔을 때 컨테이너까지 닿는 길이 이 배선이다.

3. GitLab의 구조와 설치

두 블록이다. 앞은 세울 물건을 여는 쪽 — 어떤 제품이고(3.1), 어떤 부품으로 이루어졌고(3.2), 무엇으로 묶여 있고(3.3), 어디에 두나(3.4). 기동 파일에 들어가는 값이 전부 여기서 나온다.

뒤는 그 물건을 실제로 세우는 쪽이고, 이 편의 설치는 넷이다.

① 컨테이너 기동      3.5 기동 파일 · 3.6 기동과 확인
② root 계정 정리     3.7 첫 로그인과 잠그기
③ 저장소 둘 이전     3.8
④ GitHub 미러 연결   3.9

GitLab 안에서 파이프라인을 만들어 러너에게 일을 나눠 주는 쪽(Build → Pipelines)과 컨테이너 레지스트리는 켜지 않는다 — 러너 자체도 컨테이너 밖 별도 프로세스라 10부에서 붙인다.

3.1 GitLab이라는 물건

Git 저장소 호스팅에서 출발해 CI/CD·컨테이너 레지스트리·이슈·MR(Merge Request — GitHub의 Pull Request에 해당하는, 브랜치를 합치자는 요청)까지 한 제품에 붙여 온 소프트웨어다. 셀프호스팅 판이 원형이고, GitLab.com이라는 관리형 서비스는 그 위에 얹힌 것이다.

라이선스는 오픈코어 — 핵심은 오픈소스로 열고 그 위 기능을 유료로 파는 모델이다. 무료인 CE(Community Edition)와 유료 기능을 얹은 EE로 나뉘고, 여기서 쓰는 것은 CE다. 이 편과 다음 편에 필요한 기능은 전부 CE에 있다.

요구조건은 둘이다 — 저장소·CI·레지스트리를 한 제품으로, 그리고 내 망 안에. 이 둘을 받을 후보는 셋이었다.

	Git 서버	CI	레지스트리	내 망에 설치
GitHub	서비스로만	Actions	GHCR	안 된다 (기업용 유료판 제외)
Gitea	된다 — 단일 바이너리, 메모리 수백 MB급	GitHub Actions 호환(2023)	경량 내장(2022)	된다
GitLab CE	된다	된다	된다	된다

GitHub는 내 망 조건에서 탈락한다. Gitea는 형식상 조건을 채우지만 CI·레지스트리가 뒤에 붙은 경량 구현이다. 온프렘·사내망에서 셀프호스팅 Git 서버로 널리 쓰이는 쪽은 GitLab이다.

조각을 모으는 길도 있다 — Gitea(Git 서버) + Jenkins(CI) + Harbor(레지스트리). 조각마다 기능은 더 깊지만 세 제품을 설치·연결·운영해야 하고, 제품 사이마다 인증·webhook 배선이 생긴다.

3.2 부품과 요청의 길

한 제품이라고 안까지 하나인 것은 아니다. GitLab은 역할이 나뉜 부품 묶음이다 — Mimir가 distributor·ingester·querier로 나뉘어 있던 것과 같은 구도다. HTTP로 들어오는 길을 위에서 아래로 따라가면 이렇다.

브라우저 · git (HTTP)
   │
   ▼
 nginx ─────────── HTTP 문
   │
   ▼
 workhorse ─────── 중계. 무거운 git 전송은 여기서 직접
   │      │
   │      └──────▶ gitaly  (clone·push의 실제 전송)
   ▼
 puma ──────────── 화면·API를 만드는 Rails 웹앱
   │
   ├──▶ PostgreSQL          장부: 사용자·프로젝트·권한
   ├──▶ gitaly              코드 조회
   └──▶ Redis 큐 ──▶ sidekiq ──▶ 미러 push · webhook 발사

 git (SSH) ──▶ sshd ──▶ gitlab-shell ──▶ gitaly

컴포넌트	언어	역할	하는 일
nginx	C — 기성품	리버스 프록시(요청을 대신 받아 뒤로 넘기는 앞단 서버)	포트를 열고 요청을 뒤로 넘긴다
workhorse	Go	git 전송 프록시	pack 데이터(git이 커밋·파일을 한 덩어리로 압축해 주고받는 형식)와 대용량 업로드를 Rails 대신 받는다
puma	Ruby (Rails)	웹 애플리케이션 서버	화면과 API를 만든다
PostgreSQL	C — 기성품	관계형 DB	메타데이터 — 사용자·프로젝트·MR·권한
gitaly	Go	git 저장소 접근 서비스	git 저장소 파일을 만지는 유일한 프로세스. 다른 부품은 RPC(다른 프로세스의 기능을 호출로 쓰는 방식)로만 닿는다
Redis	C — 기성품	인메모리 캐시·잡 큐	잡(응답과 분리해 나중에 처리할 작업 한 건)을 쌓아 두는 대기열
sidekiq	Ruby (Rails)	비동기 잡 워커	큐에서 잡을 꺼내 미러 push·webhook 발사·메일을 처리한다
sshd + gitlab-shell	Go (sshd는 OpenSSH — C)	SSH 접속 처리	git 명령의 권한을 내부 API(puma)에 물어 확인받고 gitaly로 넘긴다

언어에 규칙이 보인다. 몸통(화면·로직)은 Ruby, 굵은 통로(전송·git 연산·SSH)는 Go, 문·장부·큐는 기성품. 대기열은 Go, 예매는 Java로 가른 이 프로젝트의 폴리글랏과 같은 논리다.

통로가 Go인 이유는 연결을 무는 방식에 있다. Rails가 전송을 직접 물면 clone 하나에 웹앱이 전송 내내 묶이는데, Go는 동시 연결 여럿을 적은 메모리로 오래 문다. 뒷일을 맡는 sidekiq만 Ruby인 것은 그것도 앱의 규칙이어서다 — 언어를 가르면 같은 로직을 두 벌 짜게 된다.

이 구조에서 두 가지가 따라온다.

코드의 실물은 DB에 없다. PostgreSQL은 사용자·권한·MR 같은 둘레 장부고, 코드는 gitaly가 드는 git 저장소에 있다. 화면 한 장을 만들 때도 puma는 두 곳을 다 묻는다.
push의 응답과 뒷일은 분리돼 있다. gitaly가 저장을 마치면 push는 성공으로 돌아가고, 미러 push·webhook 발사 같은 뒷일은 그 시점에 Redis 큐에 들어가 있을 뿐이다. 실제 처리는 sidekiq이 따로 하므로 뒷일은 각자의 지연이나 실패를 가진다.

고장이 났을 때 어디를 열지도 이 그림에서 나온다.

증상	볼 부품
화면이 안 열린다	nginx · puma
push·clone이 안 된다	gitaly — 인증에서 막히면 puma
미러·webhook이 안 온다	sidekiq

3.3 omnibus — 부품을 하나로 묶는 방식

GitLab이 내놓는 배포 형태는 둘이다.

omnibus 패키지 — GitLab과 그것이 돌아가는 데 필요한 소프트웨어를 전부 묶은 설치 패키지. 공식 설명은 "GitLab을 돌리는 데 필요한 서비스와 도구를 전부 한 패키지에 묶는다"고 적는다. 담긴 목록과 버전은 설치 후 /opt/gitlab/version-manifest.txt에서 확인된다.
cloud-native — 쿠버네티스 차트로 부품을 파드 여럿에 흩는 형태.

우리가 받아 돌리는 gitlab/gitlab-ce 이미지가 omnibus 패키지를 담은 것이고, 그 이미지로 만든 컨테이너 하나 안에서 프로세스 아홉이 돈다.

묶는 층으로 보면 중간이다. k3s는 컨트롤플레인 넷을 한 프로세스로 합쳐 하나가 죽으면 다 죽지만, omnibus는 프로세스가 각자라 sidekiq이 죽어도 puma는 산다. 그렇다고 파드로 흩은 Mimir처럼 부품별로 자원을 제한할 수는 없다 — 컨테이너가 하나라 limit도 하나다.

묶이면 이런 것이 달라진다.

	부품을 직접 세운다면	omnibus 패키지면
설치	nginx·PostgreSQL·Redis… 여덟을 각각 깔고 버전 궁합을 맞춘다	패키지 하나에 검증된 조합으로 담겨 온다
설정	부품마다 설정 문법이 달라 파일을 여덟 벌 쓴다	`gitlab.rb` 한 장에 쓰면 `gitlab-ctl reconfigure` 가 부품별 파일(nginx 설정·postgresql.conf·puma 설정…)로 펼친다
기동	부품마다 서비스로 등록하고 순서를 잡는다	runit이 전부 띄우고, 죽은 것만 다시 세운다
조작	부품마다 start·stop·status 명령이 다르다	`gitlab-ctl` 하나로 GitLab 전체를 세우고 멈추고 본다

오른쪽 열의 이름 넷은 설정 → 기동 → 조작 순으로 이렇다.

gitlab.rb — 설정 파일 하나. Ruby 문법이라 puma['worker_processes'] = 0 같은 줄을 쓴다. Docker에서는 이 파일 대신 환경변수 GITLAB_OMNIBUS_CONFIG에 같은 내용을 적는다.
gitlab-ctl reconfigure — gitlab.rb 한 장을 읽어 부품별 설정 파일을 만들어 내고, 내용이 바뀐 부품만 다시 세운다. 패키지에 함께 담긴 구성 관리 도구(Chef)가 이 일을 한다. 몇 번을 돌려도 결과가 같고, 부품 설정 파일을 직접 고쳐 두면 다음 reconfigure가 덮어쓴다.
runit — 부품들을 프로세스로 띄워 두고 지켜보는 프로그램(프로세스 슈퍼바이저). 죽으면 다시 세운다. 보통 리눅스 서버에서 systemd가 하는 일을, 컨테이너 안에서 이 프로그램이 대신한다.
gitlab-ctl — GitLab을 다루는 명령이고, 위의 reconfigure도 그 하위 하나다. 나머지는 status(부품별 생사), start·stop·restart, tail(로그).

설치되면 이 파일들이 성격에 따라 네 경로로 나뉜다.

경로	담기는 것
`/opt/gitlab`	프로그램 본체 — 부품들의 실행 파일과 `gitlab-ctl`. 담긴 목록인 `version-manifest.txt`도 여기
`/etc/gitlab`	설정 — `gitlab.rb`와 인증서·비밀
`/var/opt/gitlab`	데이터 — gitaly가 드는 git 저장소와 PostgreSQL 실물
`/var/log/gitlab`	로그

바뀌는 것과 안 바뀌는 것이 갈려 있다. 프로그램 본체는 패키지가 정하니 손댈 일이 없고, 나머지 셋은 쓰는 동안 계속 바뀐다. 이 구분이 그대로 기동 파일의 볼륨이 된다.

3.4 어디에 세우나

자리는 데스크탑의 Docker다. 근거 셋과 대가 하나.

① 정본은 자기가 정의하는 대상 밖에 있어야 한다. 대상이 무너졌을 때 다시 세울 근거가 정본인데, 대상 안에 살면 함께 무너진다. 이 축이 클러스터 안(차트로 배포)과 클러스터 호스트인 노트북(VM 추가)을 지운다. 데스크탑은 물리적으로 분리된 장비다.

② webhook은 밖에서 안으로 들어오는 연결이다. ArgoCD가 저장소를 읽는 것은 안에서 밖으로 나가는 연결이라 GitLab이 어디 있든 된다 — 지금 인터넷의 GitHub를 읽는 것이 그 증거다. webhook은 반대로 GitLab이 ArgoCD를 부른다. 클러스터는 공유기 NAT 뒤 사설 IP(192.168.0.201–203)에 있어 인터넷에서 먼저 거는 연결이 닿지 않고, 데스크탑(192.168.0.167)은 같은 사설망이라 그 호출이 그대로 선다. GitHub로 걸려면 포트포워딩으로 클러스터를 인터넷에 내놓아야 하는데, 그것은 외부 공개(14부)의 일이다.

③ 빌드 I/O를 클러스터 디스크에서 뗀다. 클러스터 호스트인 노트북은 단일 USB SSD라 CI 빌드의 I/O가 부하 실측(13부)에 섞인다. 10부에서 러너가 붙으면 그 부하는 데스크탑 디스크에서 돈다.

데스크탑에 쿠버네티스를 새로 세워 차트로 올리는 길도 있었지만, Git 서버 하나를 위해 관리할 클러스터가 하나 더 생긴다.

대가 — 데스크탑 전원에 매인다. 꺼지면 sync가 멈춘다. 뜬 워크로드는 그대로 돌고, 켜면 ArgoCD가 따라잡는다.

3.5 기동 파일 — 컨테이너를 정의하는 한 장

자리가 정해졌으니 파일을 쓴다. 받아 올 것은 omnibus 패키지를 담은 공식 이미지고, 이 파일이 정하는 것은 그 이미지로 만들 컨테이너의 모양이다 — 어떤 주소로 서고, 어느 포트를 잇고, 무엇을 남기고, 어느 버전을 쓰고, 메모리를 어디까지 줄일지.

파일은 데스크탑 로컬 폴더에 둔다. cgv-infra 저장소에 넣으면 버전 관리가 따라오지만, 그 저장소는 클러스터를 정의하는 코드이기에 경계를 지킨다 — 클러스터 밖 장비의 파일을 섞지 않는다.

services:
  gitlab:
    image: gitlab/gitlab-ce:19.2.1-ce.0
    container_name: gitlab
    restart: unless-stopped
    shm_size: '256m'    # 공유 메모리(/dev/shm) — 도커 기본 64m로는 내부 프로세스가 모자란다
    ports:
      - '8929:8929'     # HTTP
      - '2424:22'       # SSH — 밖 2424를 안의 22로
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://192.168.0.167:8929'
        gitlab_rails['gitlab_shell_ssh_port'] = 2424
        gitlab_rails['time_zone'] = 'Asia/Seoul'
        puma['worker_processes'] = 0            # single 모드 — 메모리 절감
        sidekiq['max_concurrency'] = 10         # 뒷일 동시성도 낮춤
        prometheus_monitoring['enable'] = false # 자기 관측 exporter 끔
        gitlab_kas['enable'] = false            # 클러스터 안 에이전트가 GitLab에 붙어 배포하는
                                                # GitLab 자체 GitOps 경로. ArgoCD가 그 자리라 안 씀
    volumes:
      - gitlab-config:/etc/gitlab
      - gitlab-logs:/var/log/gitlab
      - gitlab-data:/var/opt/gitlab
volumes:
  gitlab-config:
  gitlab-logs:
  gitlab-data:

이 파일에는 층이 둘 섞여 있다.

바깥쪽(image·ports·volumes·shm_size)은 도커가 읽어 컨테이너를 만드는 값이고,
GITLAB_OMNIBUS_CONFIG 블록은 컨테이너 안에서 gitlab.rb 자리에 들어가 GitLab이 읽는 값이다.
컨테이너가 처음 뜰 때 reconfigure가 이 블록을 부품별 설정 파일로 펼친다.

GITLAB_OMNIBUS_CONFIG 블록

external_url부터. GitLab은 자기 주소를 알아야 한다. 화면의 clone 주소, 링크·리다이렉트(브라우저를 다른 주소로 넘기는 응답 — 로그인 뒤 이동이 이걸로 돈다), 그리고 webhook을 발사하는 sidekiq(비동기 잡 워커)이 밝힐 발신처가 전부 이 값에서 나온다. 값에 포트를 붙이면 안의 nginx가 그 포트로 listen한다.

포트 매핑은 HTTP와 SSH가 비대칭이다.

	컨테이너 안 listen	매핑	번호가 정해지는 곳
HTTP	8929	`8929:8929`	external_url의 포트가 곧 nginx listen 포트
SSH	22	`2424:22`	`gitlab_shell_ssh_port`는 clone 주소에 표시할 번호만 바꾼다

80·22를 그대로 안 쓰는 이유는 데스크탑의 다른 프로그램과 충돌 여지다.

볼륨은 셋이다. 설치 경로 넷 중 프로그램 본체(/opt/gitlab)는 이미지 안에 그대로 들어 있어 남길 필요가 없다. 나머지 셋 — 설정 /etc/gitlab, 데이터 /var/opt/gitlab, 로그 /var/log/gitlab — 은 쓰는 동안 계속 바뀌고 그 안에 운영의 원본이 있으므로, 컨테이너가 죽어도 남아야 한다. 컨테이너를 지웠다 다시 만들어도 이 셋이 살아 있으면 저장소도 계정도 그대로다.

버전은 핀으로 고정한다. latest 대신 19.2.1-ce.0을 쓴다. GitLab은 업그레이드 경로 규칙이 엄격해서(마이너를 건너뛰지 못하는 구간이 있다) 지금 무엇을 돌리는지 모르면 다음 업그레이드가 도박이 된다.

메모리 손잡이 셋도 이 파일에 들어간다. GitLab의 기본 설정은 수백 명 규모 서버를 전제해(공식 최소 권장 RAM 4GB) 유휴에도 4GB급을 흡수하는데, 도커의 memory limit은 컨테이너 전체에 하나라 안의 부품별로는 못 건다. 조절은 gitlab.rb 쪽에서 한다.

puma worker 수 — 동시 처리량과 맞바꿔 메모리를 크게 줄인다. 사용자가 하나라 성립한다.
sidekiq 동시성 — 같은 논리.
내장 모니터링 — 패키지에 함께 담긴 exporter가 자기 지표를 따로 내는데, 같은 대상을 LGTM이 이미 본다. 켜 두면 같은 값을 두 곳에서 재면서 메모리만 더 쓴다.

3.6 기동과 확인

절차는 넷이다.

[PowerShell] docker version — 클라이언트·서버 둘 다 나와야 한다. 명령이 인식되지 않으면 설치 전에 열어 둔 세션이므로 터미널을 새로 띄운다.
[PowerShell] 기동 파일을 둔 폴더에서 docker compose up -d — 첫 실행은 이미지 수 GB를 받는다.
[PowerShell] docker logs -f gitlab — 첫 기동은 reconfigure가 돌아 수 분 걸린다.
[PowerShell] docker ps로 STATUS가 (healthy)가 될 때까지 기다린 뒤 [브라우저] http://192.168.0.167:8929.

(healthy)는 이미지에 정의된 헬스체크 명령이 통과했다는 표시다(그 전에는 starting). 다만 이 체크는 HTTP 응답 한 곳만 보므로, 안의 부품 하나가 죽어 있어도 healthy로 보일 수 있다. 그래서 컨테이너 안은 따로 본다.

부품 아홉이 전부 run 상태다. gitlab-shell이 목록에 없는 것은 상주 데몬이 아니어서다 — SSH 연결이 올 때마다 sshd가 그때 호출한다. logrotate는 로그 파일을 잘라 보관하는 유틸로, 패키지에 함께 담겨 온 것이다. down:이 찍힌 부품이 있으면 gitlab-ctl tail <부품>으로 그 로그를 본다(실물은 /var/log/gitlab/<부품>/, 볼륨 셋 중 로그 볼륨이 그것이다).

옆의 가동 시간이 데이터 계층(redis·postgresql) → 앱(puma·sidekiq) → 전송·입구(workhorse·nginx·gitaly) 순으로 벌어져 있다. 이 순서를 만드는 것은 reconfigure다 — reconfigure가 부품을 이 순서로 활성화하고, runit은 활성화된 것을 띄운 뒤 죽으면 다시 세우는 일만 한다(의존 순서 개념이 없다).

데스크탑을 껐다 켜도 손댈 것은 없다. Windows 로그인 → Docker Desktop 자동 시작(Settings → General에서 켠다) → restart: unless-stopped가 컨테이너를 다시 세우고, 볼륨이 컨테이너 밖이라 데이터도 그대로다. GitLab이 내려가 있는 동안은 sync가 멈추지만 뜬 워크로드는 돌고, 켜면 ArgoCD가 따라잡는다.

작업 중 Windows가 메모리 압박으로 VS Code와 Docker Desktop 창을 정리했을 때도 GitLab은 계속 돌았다. 창과 엔진이 다른 프로세스이고, 컨테이너는 WSL2 VM 안에서 돌아 호스트 쪽 정리 대상이 아니어서다.

3.7 첫 로그인과 잠그기

이미지에는 비밀번호를 넣을 수 없다 — 모두가 같은 이미지를 받는다. 그래서 첫 기동 때 무작위 비밀번호를 만들어 컨테이너 안에 파일로 남기고, 24시간이 지난 뒤 처음 도는 reconfigure에서 지운다.

docker exec gitlab cat /etc/gitlab/initial_root_password

Password: 줄의 값으로 사용자명 root 로그인. 안내 화면이 둘 뜨는데 둘 다 Skip한다 — 그룹·프로젝트 마법사는 공개 범위와 README 초기화를 고를 칸이 없어 다음 절에서 직접 만들고, 프로필 설정은 메일 발송(SMTP) 설정이 없어 이메일을 바꿔도 확인 메일이 안 온다.

로그인한 뒤 할 일은 셋이다.

① 비밀번호 교체 — "`/-/user_settings/password/edit"`

비밀번호 칸은 프로필 편집이 아니라 왼쪽 메뉴의 별도 항목에 있다. 초기값을 넣어 바꾸면 로그아웃되고, 새 값으로 다시 로그인한다.

지금 하는 이유 — 초기값 파일이 다음 재시작에서 지워진다. 그 전에 안 바꾸면 로그인 경로를 컨테이너 안에서 직접 되살려야 한다.

② 가입 차단 — "`/admin/application_settings/general"`

New user account restrictions → Allow new user accounts 해제 → Save changes. Admin area 위에 뜬 경고 배너의 Deactivate 버튼도 같은 설정이다.

왜 — 켜져 있으면 /users/sign_up 주소를 아는 사람은 누구나 계정을 만든다. 이 서버는 곧 인프라 코드의 원본이 되고 클러스터가 여기서 배포 정의를 읽어 간다.

끄면 안 되는 것 — 같은 페이지 Sign-in restrictions의 Allow password authentication for Git over HTTP(S). 다음 절의 push가 이 인증을 쓴다.

③ Web IDE 단일 출처 대체 끄기 — 같은 페이지 아래 Web IDE 섹션

Enable single origin fallback 해제 → Save changes. Admin area의 둘째 경고 배너가 이것이다.

왜 — 웹 편집기의 확장 자산은 본체와 분리된 출처에서 받아오는데, 그 주소가 안 닿으면 GitLab 서버가 대신 내주는 설정이다. 제3자 코드가 이 서버 주소로 서빙되면 브라우저가 같은 출처(프로토콜·호스트·포트로 스크립트 권한을 가르는 기준)로 취급해 이 서버의 쿠키·세션에 닿는다. 코드는 로컬에서 고쳐 push하므로 웹 편집기를 쓸 일이 없다.

3.8 저장소 이전 — 그릇과 프로토콜

GitLab은 섰고 비밀번호도 잠갔다. 이제 저장소를 github에서 gitlab으로 옮긴다.

GitHub의 사용자/저장소에 대응하는 GitLab의 단위는 그룹/프로젝트다. 그룹은 폴더가 아니라 권한·설정·러너를 물려주는 단위여서, 그룹에 등록한 러너는 아래 프로젝트 전부가 쓴다. 그래서 개인 계정 밑이 아니라 그룹 cgv를 만들어 둘을 담는다.

공개 범위는 세 단계다 — private(멤버만) / internal(로그인한 사용자 전부) / public(로그인 없이도 read). 지금은 private로 만든다. ArgoCD가 자격 없이 읽으려면 public이어야 하지만, 여는 것은 설정 하나고 자격 방식은 다음 절의 [결정]이다.

그릇 만들기

New group으로 cgv(private)를 만들고, 그 안에서 New project → Create blank project로 cgv-infra·cgv-onprem 둘을 만든다.

기본값에서 세 개를 끈다.

Initialize repository with a README — 화면 설명이 그대로 말한다: *"Skip this if you plan to push up an existing repository."* 체크하면 첫 커밋이 생겨서 밀어 넣을 히스토리와 갈라진다.
Enable SAST(Static Application Security Testing) — 소스를 정적으로 훑어 취약점을 찾는 검사
Enable Secret Detection — 둘 다 CI로 도는 검사다. 러너가 없어 돌 수 없고(10부), 켜면 파이프라인 정의 파일인 .gitlab-ci.yml이 커밋으로 들어가 README와 같은 문제가 생긴다.

만들고 나면 빈 저장소 안내 화면에 clone 주소가 뜬다 — ssh://git@192.168.0.167:2424/.... 기동 파일에 넣은 gitlab_shell_ssh_port = 2424가 화면에 그대로 반영된 것이다.

프로토콜 — SSH 대신 HTTP

같은 저장소에 들어가는 문이 둘이라 안내 화면에도 SSH·HTTPS 탭이 나란히 있다. remote 주소의 앞부분이 어느 문으로 들어갈지를 정한다.

	HTTP	SSH
주소	`http://192.168.0.167:8929/cgv/cgv-infra.git`	`ssh://git@192.168.0.167:2424/cgv/cgv-infra.git`
포트	8929	2424
인증	사용자명 + 비밀번호(또는 토큰)	공개키를 서버에 미리 등록
받는 부품	nginx → workhorse	sshd → gitlab-shell
전송	평문(HTTPS면 암호화)	항상 암호화

remote 재배선

저장소마다 세 줄이다.

git remote rename origin github
git remote add origin http://192.168.0.167:8929/cgv/cgv-infra.git
git push -u origin main

origin = GitLab. GitHub는 github라는 이름으로 남기고 직접 push하지 않는다.

첫 push는 자격 단계에서 막혔다.

fatal: Unencrypted HTTP is not recommended for GitLab.
Ensure the repository remote URL is using HTTPS ...

GitLab이 아니라 Windows의 Git 자격 관리자(Git for Windows에 함께 깔려 저장된 자격을 git에 넣어 주는 도구)가 거부한 것이다. 평문으로는 자격이 그대로 흘러서다. 이 서버는 공유기 망 안에 있고 인터넷에 열려 있지 않아 그 위험을 수용하되, 전역 허용 대신 이 주소에만 예외를 준다.

git config --global "credential.http://192.168.0.167:8929.allowUnsafeRemotes" true

TLS는 클러스터를 밖으로 열 때(14부) 인증서와 함께 들어온다. 그때 이 예외도 걷힌다.

예외를 준 뒤 다시 push하면 자격 창이 뜬다. 기본이 Token 탭인데 개인 액세스 토큰을 아직 안 만들었으므로 Password 탭으로 바꿔 root + 새 비밀번호를 넣는다. 같이 뜨는 missing OAuth configuration 경고는 자격 관리자가 비밀번호 대신 브라우저 로그인으로 자격을 받아 오는 경로(OAuth)를 쓰려 했는데 이 서버에 그 앱 등록이 없다는 안내라, 비밀번호로 넣으면 무관하다. 한 번 인증하면 Windows 자격 관리자가 저장해 다음부터는 안 묻는다.

결과

출력에서 확인되는 것 셋.

535 오브젝트(커밋·디렉터리·파일 하나하나가 오브젝트다) — 받는 쪽이 빈 저장소라 겹치는 것이 없어 히스토리 전부가 통째로 전송됐다. 빈 그릇으로 만든 이유가 이것이다.
Resolving deltas — 보내는 쪽은 오브젝트를 통째로가 아니라 이전 버전과의 차이(delta)로 압축해 보내고, 받는 쪽이 그걸 원본으로 되살린다. 그 일을 한 부품이 gitaly다.
set up to track 'origin/main' — 이 저장소의 기본 push 대상이 GitLab이 됐다.

cgv-onprem도 같은 세 줄로 옮긴다(주소만 바꿔서). 자격은 이미 저장돼 있어 묻지 않는다.

3.9 GitHub는 쇼케이스로 — push 미러

repository mirroring(push 방향)은 GitLab이 push를 받으면 그 내용을 다른 저장소로 밀어 주는 기능이다. 미는 일은 응답과 분리된 뒷일이라 sidekiq(미러링, 웹훅 전문)이 큐에서 꺼내 처리하고, 그래서 GitHub에 뜨는 시점은 push 시점과 조금 어긋난다. 미러는 마지막 push까지만 복제한다 — 백업과 같지 않고, 강제 push도 그대로 전파된다.

[GitHub] 토큰 발급: Settings → Developer settings → Personal access tokens(비밀번호 대신 쓰는 접근 자격) → Fine-grained tokens — 대상 저장소와 권한 항목을 하나씩 좁힐 수 있는 쪽이다. 저장소를 cgv-infra·cgv-onprem 둘로 한정하고, 권한은 Contents: Read and write 하나만 준다. 이 토큰은 GitLab 서버에 저장되므로, 새어 나갔을 때의 범위가 곧 이 권한 범위다.
[GitLab] cgv-infra → Settings → Repository → Mirroring repositories. URL은 https://github.com/<계정>/cgv-infra.git로 넣는다 — 사용자명을 URL에 넣지 않는다(화면 안내가 그렇게 말한다). 사용자명은 Username 칸에, 토큰은 Password 칸에, Direction은 Push. 체크박스 둘은 해제한 채로 둔다.
- Keep divergent refs — GitHub 쪽이 갈라졌을 때 덮어쓰지 않고 남기는 옵션이다. 끄면 GitLab이 자기 것으로 덮어쓴다. 이 항목은 미러를 만든 뒤에는 API로만 바꿀 수 있다.
- Mirror only protected branches — 보호된 브랜치만 밀지 여부. 작업 브랜치가 생겨도 사본에 같이 보이는 편이 쇼케이스 목적에 맞다.
cgv-onprem도 동일하게(주소만 바꿔서, 토큰은 같은 값).
검증 — 커밋 하나를 push하고, 미러 상태(Last successful update)와 GitHub의 커밋 목록이 따라왔는지 확인한다.

여기까지가 설치다. sidekiq이 맡는 뒷일 중 지금 도는 것은 미러 하나고, webhook은 아직 등록하지 않았다. 저장소가 옮겨졌을 뿐 ArgoCD는 여전히 GitHub를 본다 — 소스를 갈아타고 webhook을 거는 것은 다다음 절에서 진행하려한다

4. GitLab의 층과 기능

서버는 섰고 저장소 둘이 그 안에 있다. 남은 것은 이 제품으로 무엇을 할 수 있고 그중 무엇을 쓸지다. 메뉴가 방대해서 정해 두지 않으면 화면에 끌려다니게 된다.

왼쪽 사이드바는 고정돼 있지 않고 지금 보고 있는 컨텍스트를 따라 통째로 바뀐다. 덮는 범위가 넓은 것부터 좁은 것까지 넷이다.

4.1 Admin area   이 서버 전체                       상단바 오른쪽 Admin 버튼
4.2 Your work    그중 내가 걸친 것만 "나" 기준으로     로그인 첫 화면 · 로고 클릭
4.3 그룹 cgv     걸면 아래 프로젝트가 전부 물려받는다   Your work → Groups → cgv
4.4 프로젝트      저장소 하나                        그룹 목록에서 클릭

4.1 Admin area — 이 서버 전체

그룹·프로젝트가 "무엇을 만드나"라면 여기는 "이 서버를 어떻게 굴리나"다. 아래 층들은 자기 것만 보이는데, 여기서만 소유자와 무관하게 서버에 있는 전부가 보인다.

Overview    프로젝트 · 사용자 · 그룹을 전수로
CI/CD       서버 전체가 쓰는 러너 등록
Monitoring  서버 자신의 상태 — 자원 · 뒷일 · DB 점검
Settings    서버 동작 — 가입 제한 · 네트워크 · 외관

이 층이 있는 이유는 "누구의 것도 아닌 결정"이 생기기 때문이다. 계정을 만들 수 있는지, 서버가 밖으로 요청을 보내도 되는지, 러너를 누가 공유하는지 — 프로젝트 주인도 그룹 주인도 정할 수 없다. GitLab.com에서는 그 자리가 GitLab이라는 회사이고, 셀프호스팅을 고르면 나에게 온다.

이 편에서 세 번 온다. 가입 차단과 Web IDE 끄기는 설치할 때 했고, 남은 하나는 webhook이 사설망으로 나가게 허용할 때(Settings → Network → Outbound requests)다.

무료판 CE라는 것도 이 층에서 보인다. 유료판(Premium · Ultimate) 이름이 붙은 기능은 이 서버에서 안 된다.

4.2 Your work — 내가 걸친 것 전부

로그인하면 서는 첫 화면이다. 특정 서버·그룹·프로젝트를 보는 곳이 아니라 내가 닿는 칸 전부를 소속과 무관하게 한 목록으로 펴 놓은 곳이다.

이 층은 층 구조의 대가를 갚는다. 프로젝트와 그룹으로 잘게 나누면 권한과 범위는 깔끔해지는데, 사람은 그 여러 칸에 걸쳐 일한다. 칸마다 찾아다니면 내 차례인 일을 놓친다. 그래서 나눠 놓은 것을 "나"라는 축으로 다시 펴 보는 화면이 따로 있고, 그중 "내 차례"만 추린 것이 To-Do List다.

지금은 쓸 것이 없다. 개수가 전부 0이다 — 칸이 둘뿐이고 걸쳐 있는 사람이 하나라 값이 안 나온다. 다만 혼자라서 원리적으로 안 쌓이는 것은 아니다. 파이프라인 실패나 내가 저자인 MR의 충돌은 남이 없어도 발화한다. 첫 MR이 서고 10부에서 러너가 붙으면 채워지기 시작한다.

4.3 그룹 cgv — 아래로 물려주는 단위

저장소를 옮기며 만든 그릇이다. GitHub의 사용자/저장소에 대응하는 GitLab 단위가 그룹/프로젝트라, 개인 계정 밑이 아니라 cgv 그룹에 저장소 둘을 담았다.

상위 층인데 메뉴가 프로젝트보다 적다. 프로젝트에 있는 Secure·Monitor·Analyze가 여기엔 아예 없고, 남은 묶음도 안이 얇다. 이유는 하나다 — 그룹은 코드를 담지 않는다. 저장소가 프로젝트에 있으니 Code에는 여러 프로젝트에 걸친 MR 목록만 남고, 파이프라인이 도는 곳도 프로젝트라 Build에는 러너를 등록하는 자리만 남는다. 스캔·관측·분석은 코드 실물에 붙는 것이라 자리가 없다.

그래서 남는 것이 곧 이 층의 정의다 — 아래로 물려줄 것들.

멤버 권한 · 러너 · CI/CD 변수 · 액세스 토큰 · 패키지 레지스트리

팀에서 입사자를 프로젝트가 아니라 팀 그룹에 넣는 이유가 이것이고, 퇴사도 그룹에서 한 번 빼면 하위 접근이 한꺼번에 끊긴다.

눈여겨볼 것 둘

Settings에 Webhooks가 없다. 그룹 webhook은 유료판 전용이라 메뉴 자체가 나타나지 않는다 — 유료 기능은 잠긴 채 보이는 게 아니라 사라진다. 그래서 webhook은 프로젝트마다 건다.
Build에 Runners가 독립 메뉴로 있다. 프로젝트에서는 Settings 안에 묻혀 있는 것이 여기서는 묶음 하나를 통째로 차지한다 — 러너가 이 층의 주 용도라는 뜻이다.

4.4 프로젝트 cgv-infra · cgv-onprem — 저장소가 사는 곳

뒤이어 손대는 작업 대부분이 이 층에서 일어난다. 묶음이 일곱에서 아홉으로 늘고, 가운데가 계획 → 코드 → 빌드 → 검사 → 배포 → 운영 → 관측 → 분석 순으로 늘어선다. GitLab이 자신을 Git 호스팅이 아니라 "DevOps 플랫폼"이라 부르는 근거가 이 배열이다.

그룹에도 있던 것    Manage · Plan · Deploy · Operate · Settings

여기서 처음        Code      저장소 실물 — 파일 · 브랜치 · 커밋 · 태그 · 두 지점 비교
                 Build     파이프라인을 정의하고 돌리고 결과를 본다
                 Secure    이 코드에 보안 스캔을 건다
                 Monitor   이 코드가 낸 에러와 알림
                 Analyze   파이프라인 성공률 · 기여자 · 코드 통계

새로 생긴 다섯이 전부 한 가지에서 나온다 — 코드가 여기 있다. 거꾸로 그룹에만 있는 것(공유 러너·외부 이미지 캐시·멤버 배지)은 전부 여러 프로젝트에 걸치는 것들이다.

그래서 두 층은 상하 관계이면서 역할이 갈린다 — 그룹은 물려주고, 프로젝트는 만든다.

눈여겨볼 것 — Auto DevOps enabled가 켜져 있다. 저장소에 .gitlab-ci.yml이 없을 때 GitLab이 준비된 기본 파이프라인을 대신 돌리는 기능인데, 러너가 없어 지금은 아무 일도 하지 않는다. 10부에서 러너를 붙이는 순간 cgv-onprem에서 스스로 돌기 시작하므로, 그때는 러너보다 .gitlab-ci.yml이 먼저인 순서가 된다.

내가 쓸 것 — Code의 Merge requests·Branches, Settings → Repository의 보호 브랜치와 미러, Settings → Webhooks.

5. GitLab을 운영 원본으로

ArgoCD의 repoURL은 아직 GitHub를 가리킨다. GitLab에 push해도 클러스터에는 아무 일도 일어나지 않는다. 이 절이 끝나면 ArgoCD가 GitLab을 원본으로 본다.

push ─▶ GitLab ─▶ ArgoCD ─▶ 클러스터
          └─ 미러 ─▶ GitHub          (쇼케이스)

순서가 서로를 문다. 자격 없이 주소만 바꾸면 App 열아홉이 한꺼번에 저장소를 못 읽는다. 길 내기가 맨 앞인 것은 repoURL을 바꾸는 커밋이 그 길로 지나가는 첫 손님이어서다.

길을 낸다
  5.1 변경이 지날 길     브랜치 · main 보호 · MR 문턱
  5.2 합치는 방식        대상 브랜치에 무엇이 남나

옮긴다
  5.3 기계의 자격        ArgoCD가 저장소를 읽을 자격      [결정]
  5.4 시선 전환          repoURL 을 한 커밋으로           [결정]

반영이 폴링 3분에 걸려 있는 것과 ArgoCD가 port-forward로만 열리는 것은 네트워크 쪽 문제라 6장에서 따로 다룬다.

5.1 변경이 지날 길 — 브랜치와 보호

브랜치 구조를 정한다

cgv-infra는 main 하나로 둔다. ArgoCD가 보는 브랜치가 곧 "배포된 상태의 정의"인데 클러스터가 하나뿐이라, 브랜치를 둘로 나눠도 나머지 하나를 볼 대상이 없다. 환경 구분은 workloads/environments/{dev,stg,prd} 디렉터리가 이미 하고 있어서, 브랜치에 환경 이름을 또 쓰면 같은 것을 두 축이 가리킨다.

cgv-onprem에는 dev를 만든다. 앱 코드는 ArgoCD가 읽지 않는다. 빌드 대상이라 브랜치가 곧 이미지 태그를 정하는 축이 되고(10부), 거기서는 브랜치가 실제 대상을 가리킨다.

git switch -c dev
git push -u origin dev

push 응답에 Total 0 (delta 0)이 찍힌다. 커밋은 이미 서버에 있고 이름표(ref) 하나만 새로 만들어져서, 실제로 전송된 것이 없다는 뜻이다. 같은 응답에 MR을 만들 주소도 함께 오는데, 앞으로 작업 브랜치를 올릴 때마다 이 줄이 뜬다.

기본 브랜치를 dev로 바꾼다

기본 브랜치가 정하는 것이 넷이다.

clone 하면 체크아웃되는 브랜치
MR 을 만들 때 대상(target)으로 잡히는 브랜치
저장소 첫 화면에 뜨는 브랜치
새로 만든 브랜치에 보호가 자동으로 걸리는 대상

작업 흐름이 작업 브랜치 → MR → dev라 기본이 dev여야 한다. 안 바꾸면 MR마다 대상을 손으로 고쳐야 하고, 한 번 놓치면 main으로 들어간다. GitHub 쪽도 같이 바꾼다 — main이 당분간 멈춰 있게 되는데, 쇼케이스의 첫 화면이 그 낡은 상태로 굳는 것을 피한다.

GitLab   Settings → Repository → Branch defaults → Default branch
GitHub   Settings → General → Default branch → 연필 아이콘

보호를 걸고 실제로 밀어 본다

Settings → Repository → Protected branches에서 cgv-infra의 main, cgv-onprem의 dev·main에 같은 값을 건다.

Allowed to push and merge   No one         브랜치에 직접 쓰는 것을 누가 하나
Allowed to merge            Maintainers    MR 을 이 브랜치로 합치는 것을 누가 하나
Allow force push            꺼짐

이름이 비슷하지만 거는 대상이 다르고, 둘이 같이 있어야 MR이 유일한 길이 된다. Allowed to push and merge를 역할로 열어 두면 뒤에 붙일 파이프라인 게이트를 직접 push로 우회할 수 있다.

혼자 쓰는 동안 실제로 일하는 것은 Allowed to push and merge 하나다. root가 Owner라 Allowed to merge에 무엇을 넣어도 결과가 같다 — 사람이 늘 때를 위해 미리 좁혀 두는 자리다.

설정만 보고 넘어가지 않고 빈 커밋 하나로 밀어 본다.

git commit --allow-empty -m "protection test"
git push origin main

remote: GitLab: You are not allowed to push code to protected branches on this project.
 ! [remote rejected]      main -> main (pre-receive hook declined)

세 가지가 확인된다.

서버가 막는다. pre-receive hook declined — 클라이언트 설정으로는 우회되지 않는다.
Owner도 예외가 없다. 역할 기준 차단이라 소유자라고 따로 열린 길이 없다.
막힌 지점이 ref 갱신이다. git은 커밋 객체를 먼저 보내고 브랜치 이름표를 옮기는 단계를 훅이 검사한다. 객체는 이미 서버에 갔고, 주인 없이 남은 것은 나중에 정리된다.

거부됐으니 로컬만 되돌리면 끝난다.

git reset --hard HEAD~1

그 길에 세울 수 있는 문턱

길은 하나가 됐다. 그 위에 무엇을 세울 수 있는지가 남는다.

회사 수습 때 Azure DevOps에서 일하던 흐름을 그대로 세워 보려 했다.

① 작업 브랜치를 판다
② MR 을 올린다
③ 리뷰를 받는다              ← 빠진다
④ 승인자가 승인한다           ← 빠진다
⑤ 머지한다

③④가 두 가지 이유로 빠진다.

수행할 사람이 없다. 혼자라 리뷰할 사람도 승인할 사람도 나뿐이다.

조건으로 걸 수도 없다. GitLab 무료판에도 승인(approve) 버튼은 있는데, 눌러도 머지 가능 여부가 안 바뀐다. 승인 N명을 받아야 머지된다는 규칙 자체가 유료판 기능이라, 승인을 문턱으로 세울 방법이 없다.

사람이 서는 자리가 비었으니 남은 것은 자동 검사인데, 그것도 아직 못 켠다. 러너가 없어 돌릴 파이프라인이 없다.

보호 브랜치                이미 걸었다.  머지를 막는 게 아니라 MR 을 거치게 만든다 — 길이다
승인                      문턱이 될 수 없다.  무료판이라 조건으로 못 건다
Pipelines must succeed    유일하게 문턱이 되는 것.  러너가 서면 켠다 (10부)

그래서 지금은 머지를 막는 것이 없다. 길만 하나로 고정돼 있는 상태다.

그래도 혼자 올리고 혼자 머지하며 이 길로만 간다. 변경 전체를 한 화면 diff로 확인하고 넘어가려는 것이고, 커밋이 한 덩어리로 기록되게 하려는 것이며, 10부에 그 문턱을 붙일 자리를 미리 세워 두려는 것이다.

5.2 합치는 방식 — 대상 브랜치에 무엇이 남나

길은 냈지만 그 길을 지난 변경이 대상 브랜치에 어떻게 남을지는 아직 안 정했다. 앞으로 계속 MR을 보낼 것이므로 그 전에 정해 둔다.

작업 브랜치에 커밋 셋을 쌓았다고 하자.

main   A ── B
            └── X ── Y ── Z      작업 브랜치

머지하면 main에 무엇이 남는가. 설정에 따라 결과가 이렇게 갈린다.

그냥 Merge commit        A ── B ── X ── Y ── Z ── M      커밋 4개
스쿼시 + Merge commit     A ── B ── Z' ── M              커밋 2개
스쿼시 + Fast-forward     A ── B ── Z'                   커밋 1개      ← 고른 것

첫 줄이 넷인 것은 X·Y·Z가 그대로 올라오고 거기에 M이 더해져서다. '가 붙은 것은 원본과 다른 새 커밋이라는 표시다.

셋이 각각 하는 일과 쓰는 자리

합치는 방식이 둘이고, 그 앞에 붙는 스쿼시가 따로 하나다.

	하는 일	대가	쓰는 자리
Merge commit	부모가 둘인 새 커밋 M을 만들어 두 갈래를 잇는다. 자기 변경은 없다	작업 커밋이 다 올라와 목록이 지저분해진다	오래 살아 있는 브랜치를 합칠 때
Fast-forward	새 커밋을 안 만든다. main이라는 이름표를 Z'로 옮기는 것이 전부다	갈래가 있으면 안 되고 "언제 합쳤나"가 안 남는다	작업 브랜치가 짧고 자주 합쳐질 때
스쿼시	X·Y·Z의 변경을 다 담은 새 커밋 Z'를 만든다. 셋을 지우는 게 아니라 원본은 작업 브랜치에 남는다	커밋 단위 이력이 사라진다	작업 브랜치를 MR 단위로 다룰 때

스쿼시는 어느 방식으로 붙이든 먼저 일어난다. 위의 결과 세 줄이 합치는 방식 × 스쿼시 여부로 갈린 것이 그래서다.

스쿼시 + Fast-forward를 고른 이유

MR 하나 = 커밋 하나가 되는 조합이다. 혼자 쓰고 MR이 작업 단위와 1:1이라, main의 커밋 목록이 그대로 "무엇을 했나"의 목록이 된다. 되돌릴 때도 git revert <sha> 하나로 그 MR 전체가 돌아간다 — 커밋이 흩어져 있으면 어디부터 어디까지가 그 작업인지 찾아 여러 개를 되돌려야 한다.

대가는 표에 적은 커밋 단위 이력인데, 없어지는 것은 아니다.

main 히스토리       안 보인다.  스쿼시된 커밋 하나만 들어간다
GitLab             MR 화면의 Commits 탭에 원본 그대로.  브랜치를 지워도
                   refs/merge-requests/<번호>/head 로 보관된다
로컬 작업 브랜치      git branch -D 로 지우기 전까지 남는다

잃는 것은 "main의 커밋 목록으로 좇는 길"이고, 무엇을 왜 바꿨는지는 MR이 갖고 있다.

설정

Settings → Merge requests에서 넷을 정한다.

Squash commits when merging     Require              작업 커밋을 하나로 누른다
Merge method                    Fast-forward merge   그 하나를 이름표 이동으로 붙인다
                                + 자동 rebase        붙이기 전에 작업 브랜치를
                                                     대상 브랜치 위에 다시 얹는다
Enable "Delete source branch"   켬                   붙인 뒤 작업 브랜치를 지운다

Merge method의 기본값은 Merge commit이다. 그대로 두면 스쿼시를 켜도 그 위에 머지 커밋이 한 겹 더 얹혀 커밋이 둘 들어간다. 두 축이라 둘 다 바꿔야 한다.

Squash는 Allow·Encourage로도 켤 수 있는데 그 둘은 MR 화면에서 끌 수 있다. 한 번 잊으면 그 MR만 작업 커밋이 통째로 올라가므로 Require로 둔다.

같은 화면 아래쪽의 커밋 메시지 템플릿이 커밋 제목과 본문을 정한다.

%{title} (%{reference})        →  ArgoCD가 GitLab 저장소를 읽을 자격 추가 (cgv/cgv-infra!2)
%{description}                 →  MR 본문이 커밋 메시지 본문으로

!2가 그 프로젝트의 MR 번호다. GitLab은 이슈(#)와 MR(!)이 기호도, 번호를 세는 통도 따로라 기호만 보고 갈리고, 커밋에서 MR로 서로 넘어갈 수 있게 된다.

자동 rebase — 갈래가 생겼을 때

넷 중 자동 rebase만 이름으로 안 보인다. GitLab이 체크박스 아래에 "머지하기 전에 작업 브랜치를 대상 브랜치 위에 자동으로 다시 얹는다"고 적어 둔다.

Fast-forward가 대상 브랜치가 내 커밋의 조상일 때만 붙기 때문이다.

브랜치를 딸 때       대상 브랜치가 내 커밋의 조상이다            →  붙는다
그 사이 머지가 남     대상 브랜치가 앞서 나가 조상이 아니게 된다    →  안 붙는다
                                                          MR 에 N commits behind 로 뜬다
자동 rebase        작업 브랜치를 최신 대상 브랜치 위에 다시 얹는다   →  다시 붙는다

이 편에서는 그것으로 다 지나갔고 손으로 푼 적이 없다. 다만 충돌이 나면 자동 rebase가 거기서 멈춘다.

5.3 기계의 자격 — ArgoCD가 저장소를 읽을 자격

ArgoCD가 GitLab의 저장소를 읽어야 하는데 지금은 못 읽는다. GitHub 쪽이 도는 것은 그 저장소가 공개라 자격 없이 읽히기 때문이고, GitLab으로 옮긴 저장소는 private다.

그리고 ArgoCD는 사람이 아니다. 브라우저를 열어 로그인할 수 없고, 미리 쥐여준 자격 문자열 하나만 제시할 수 있다.

그래서 할 일이 둘이다.

① 자격을 만든다     GitLab 에서 저장소를 읽을 수 있는 문자열 하나를 발급한다
② 자리에 둔다       ArgoCD 가 집어 갈 수 있는 곳 = argocd 네임스페이스의 Secret
                  거기에 url · username · password 를 넣어 두면
                  ArgoCD 가 url 이 맞는 저장소를 읽을 때 그것을 쓴다

②는 그 Secret을 봉인해서 git에 올리는 일이라 뒤에서 다룬다. 먼저 ①인데, GitLab이 내주는 자격이 다섯 종류라 무엇을 고르느냐가 그대로 새어 나갔을 때의 범위를 정한다.

사람 자격을 기계에 주지 않는다

root 비밀번호를 넣으면 전권이 넘어가고, 비밀번호를 바꾸는 순간 배선이 끊긴다. GitLab에는 사람과 기계의 자격이 종류로 갈려 있다.

자격	주인	범위·수명
Personal access token	사람 계정	그 사람의 권한 전부 · 최대 365일
Project/Group access token	자동 생성되는 bot 계정	역할+스코프 지정 · 최대 365일
Deploy token	프로젝트/그룹 자체	스코프만 · 만료 선택
Deploy key	SSH 공개키	읽기(쓰기 선택) · SSH 전용
CI job token	실행 중인 잡	잡이 도는 동안만

그 앞에 갈림길이 하나 있다.

A. public으로 연다        ArgoCD가 자격 없이 clone. 설정 한 번으로 끝
                          대가 — 이 서버에 닿는 누구나 로그인 없이 인프라 코드를 읽는다
B. private + deploy token 읽기 전용 자격 하나를 만들어 ArgoCD에 쥐여준다
                          대가 — 재구축 절차에 손 단계가 하나 생긴다

공개 범위 셋 중 internal은 로그인한 사용자를 뜻하므로 ArgoCD에는 해당이 없다. 자격 없이 읽게 하려면 public이어야 한다.

B로 간다. 사설망 안이라 public의 위험이 지금 당장 크지는 않지만, 외부로 여는 편에서 반드시 되돌려야 하고 "왜 열어뒀나"에 답을 만들어야 한다. 자격 종류는 deploy token — 사람 계정과 무관하고, API 스코프가 없어 새어 나가도 저장소 읽기 밖을 못 한다. ArgoCD 공식 문서가 GitLab 연결에서 안내하는 것도 이것이다.

울타리를 먼저 넓힌다 — 첫 MR

자격은 쿠버네티스 Secret으로 argocd 네임스페이스에 있어야 한다. 그런데 봉인본을 배달하는 AppProject가 대상 네임스페이스를 셋으로 한정하고 있다.

destinations:
  - namespace: data
  - namespace: app
  - namespace: observability      # argocd 가 없다

지금까지의 봉인본은 전부 워크로드가 쓸 자격이었다 — MySQL·Redis·MinIO에 붙으려고. 이번 것은 성격이 다르다. ArgoCD가 배달해서 ArgoCD 자신이 쓴다.

이 두 줄이 첫 MR이 된다.

    - server: https://kubernetes.default.svc
      namespace: argocd

작은 변경으로 길을 먼저 확인하는 것이 이 순서의 목적이다. 봉인본을 먼저 올리면 울타리가 거부해서 배달이 실패하고, 그때는 길 문제인지 봉인 문제인지 구분이 안 된다.

머지하고 한 바퀴가 도는지 본다.

kubectl -n argocd get appproject secrets -o jsonpath="{.spec.destinations[*].namespace}"

data app observability argocd

로컬 → 브랜치 → MR → 머지 → GitLab main → 미러 → GitHub → ArgoCD 폴링 → 클러스터. 앞에서 낸 길이 실제로 돈다는 것이 이 한 줄로 확인된다.

이 MR은 Merge method를 바꾸기 전에 보낸 것이라 기본값(Merge commit)으로 붙었다. 그래서 main에 커밋이 둘 들어갔다.

0742eb2  Merge branch 'chore/...' into 'main'      내용 없는 껍데기
69cb617  AppProject secrets: …                      실제 변경 (스쿼시된 것)

스쿼시는 걸려 있어 작업 커밋이 69cb617 하나로 눌렸는데, 그 위에 머지 커밋이 한 겹 더 얹혔다. 두 축을 둘 다 맞춰야 한다는 것이 이 한 줄에서 눈으로 확인된다. 이걸 보고 Fast-forward merge로 바꿨고, 다음 MR부터는 커밋이 하나만 올라간다.

토큰을 만든다

프로젝트 단위로 만든다. 그룹에 만들면 cgv-onprem까지 읽을 수 있는데, ArgoCD가 읽는 저장소는 cgv-infra 하나뿐이다. 앱 배포도 이 저장소의 차트가 하므로 앞으로도 늘지 않는다.

cgv-infra → Settings → Repository → Deploy tokens에서 발급한다.

Name      argocd
Scopes    read_repository        ← 이것 하나만
만료       비움

만료를 걸면 그날 이후 ArgoCD가 저장소를 못 읽고 배포가 조용히 멈춘다. 갱신을 알려줄 장치가 없는 환경이라 만료를 두지 않고, 새어 나가면 손으로 걷는 쪽을 택한다. 발급하면 사용자명(gitlab+deploy-token-{n})과 토큰이 한 번만 표시된다.

낱개 봉인 스크립트

기존 seal-secrets.sh는 값 다섯 개를 물어 10종을 일괄 만드는 초기 구축용이다. 하나를 더하려고 다시 돌리면 값 다섯 개를 전부 재입력해야 하고, 그중 하나라도 지금 클러스터에 떠 있는 것과 다르면 해당 워크로드가 붙지 못한다.

그래서 낱개용을 따로 둔다.

./bootstrap/seal-one.sh <이름> <네임스페이스> [라벨 key=value ...]

설계는 넷이다.

값을 인자가 아니라 프롬프트로     셸 히스토리에 안 남는다
값 입력이 화면에 안 보인다        어깨너머·스크롤백 방지
평문 Secret 파일을 만들지 않는다  kubectl → kubectl label → kubeseal 파이프로만 흐른다
컨트롤러 이름을 고정              차트 기본값과 달라 매번 지정해야 하는 것을 실수로 빠뜨리지 않게

라벨을 인자로 받는 이유는 ArgoCD 저장소 자격처럼 라벨이 있어야 인식되는 Secret이 있어서다.

./bootstrap/seal-one.sh argocd-repo-cgv-infra argocd \
  argocd.argoproj.io/secret-type=repository

키: type       값: git
키: url        값: http://192.168.0.167:8929/cgv/cgv-infra.git
키: username   값: gitlab+deploy-token-1
키: password   값: (토큰)

url은 뒤에서 바꿀 repoURL과 글자까지 같아야 한다. ArgoCD가 그 문자열로 자격과 저장소를 짝짓는다.

나온 봉인본의 구조가 이렇다.

kind: SealedSecret
metadata:
  namespace: argocd
spec:
  encryptedData:
    password: AgAFBbWac80q…      값이 전부 암호문
    type: AgCoETqHf+PX…
    url: AgDYnvD7HZ6v…
    username: AgCoAU6Oq7ih…
  template:
    metadata:
      labels:
        argocd.argoproj.io/secret-type: repository    ← 풀려서 만들어질 Secret에 붙을 라벨
      name: argocd-repo-cgv-infra
      namespace: argocd

template이 핵심이다. 컨트롤러가 이것을 풀 때 그 안의 metadata를 그대로 가진 Secret을 만들고, 라벨이 여기 실려 있어야 ArgoCD가 저장소 자격으로 알아본다.

자격이 자기가 여는 문 안에 있다

이 봉인본에는 성질이 하나 더 있다. ArgoCD가 GitLab을 읽는 데 쓸 자격인데, 그 자격 자체가 GitLab 저장소 안에 들어 있다.

ArgoCD 가 GitLab 을 읽으려면      자격 Secret 이 있어야 한다
그 Secret 은 어디서 오나          git 의 봉인본을 ArgoCD 가 읽어 배달한다
그 git 을 읽으려면               자격 Secret 이 있어야 한다     ← 제자리로 돌아온다

문을 여는 열쇠가 그 문 안에 있다. 이대로면 아무도 못 들어간다.

지금은 그 순환이 안 생긴다

ArgoCD가 아직 GitHub를 보고 있어서다. github 저장소는 public이라 자격 없이 읽힌다.

로컬        평문 Secret
   │ kubeseal 이 공개키로 잠근다
   ▼
git        SealedSecret (암호문)  →  GitLab main  →  미러  →  GitHub
   │                                                            │
   │                                   ArgoCD 가 여기를 읽어 apply  ← 공개라 자격이 필요 없다
   ▼
클러스터    SealedSecret 리소스     아직 암호문
   │ 컨트롤러가 개인키로 푼다
   ▼
클러스터    Secret                 ArgoCD 가 이것을 자기 자격으로 쓴다

ArgoCD는 개인키를 모르고 알 필요도 없다. 암호문을 클러스터에 놓는 데까지가 그 일이고, 푸는 것은 컨트롤러다.

그래서 순서가 정해진다. 자격을 먼저 배달하고, 그다음에 시선을 GitLab으로 옮긴다. 뒤집으면 ArgoCD가 GitLab을 못 읽는 상태가 되는데 열쇠는 그 안에 있다.

재구축할 때는 그 상황이 온다

클러스터를 처음부터 다시 세우면 repoURL이 이미 GitLab이다. 자격 Secret은 없고, 그것을 담은 봉인본은 GitLab 안에 있다.

그때 하는 일    이 Secret 하나만 손으로 apply 하고 시작한다

실무의 GitOps도 대부분 "첫 자격 하나는 사람이 넣는다"는 지점을 갖는다. 자동화의 시작점은 자동화될 수 없다.

올리고 머지한다

봉인본과 낱개 봉인 스크립트를 한 커밋으로 묶어 브랜치에 올리고 MR을 연다.

Commits 1  ·  Changes 4

The source branch is 2 commits behind the target branch.
Source branch will be rebased without pipeline.
1 commit will be added to main.

이 브랜치는 첫 MR을 머지하기 전에 딴 것이라 그동안 main이 두 칸 앞섰다. 머지 버튼 하나에 스쿼시·rebase·fast-forward가 순서대로 돌고, 결과가 마지막 줄이다.

git log --oneline -3 origin/main

34e12ca ArgoCD가 GitLab 저장소를 읽을 자격 추가 (cgv/cgv-infra!2)
0742eb2 Merge branch 'chore/secrets-project-argocd-ns' into 'main'
69cb617 AppProject secrets: 배달 대상에 argocd 네임스페이스 추가

첫 MR에서 커밋이 둘 들어갔던 자리가 이번엔 하나다. 승인 버튼은 누르기 전에도 뒤에도 Ready to merge!로 같았다.

로컬을 맞춘다. 원격 브랜치는 Delete source branch가 이미 지웠고, 로컬 브랜치는 rebase로 sha가 갈라져 git이 머지 안 된 것으로 보므로 -D로 지운다.

git switch main
git pull
git branch -D feat/argocd-gitlab-repo-credential

클러스터에 닿았다

kubectl -n argocd get sealedsecret,secret argocd-repo-cgv-infra

NAME                                             STATUS   SYNCED   AGE
sealedsecret.bitnami.com/argocd-repo-cgv-infra            True     95m

NAME                           TYPE     DATA   AGE
secret/argocd-repo-cgv-infra   Opaque   4      95m

두 줄이 경로를 그대로 보여준다.

SealedSecret   SYNCED True   ArgoCD 가 GitHub 에서 읽어 클러스터에 apply 했다.  아직 암호문
Secret         DATA 4        컨트롤러가 개인키로 풀었다 — type · url · username · password

ArgoCD가 만든 것은 암호문까지고, 평문으로 바꾼 것은 컨트롤러다. 자격이 argocd 네임스페이스에 섰으니 repoURL을 GitLab으로 돌릴 수 있다.

여기에 남길 것이 하나 있다. 시선을 GitLab으로 옮기고 나면 GitLab을 꺼둘 수 없게 된다. 지금은 ArgoCD가 GitHub를 보고 있어 GitLab이 내려가도 클러스터가 돌지만, 전환 뒤에는 sync가 함께 끊긴다.

5.4 시선 전환 — repoURL을 GitLab으로, 한 커밋

자격은 argocd 네임스페이스에 섰지만 ArgoCD는 아직 GitHub를 본다. 바꿀 줄을 세는 것부터 한다.

Select-String -Path (Get-ChildItem cgv-infra -Recurse -Include *.yaml) -Pattern "github.com/sss654654"

argocd/applications/*.yaml            6줄    dashboards · kafka · metallb-pool · mysql · redis · sealed-secrets
argocd/applicationsets/apps.yaml      2줄    generator 와 source 에 각각
argocd/applicationsets/observability  1줄    값 제공용 git 소스
argocd/applicationsets/platform       1줄    값 제공용 git 소스
bootstrap/root-app.yaml               1줄
                                     ──────
                                     11줄

업스트림 헬름 차트 저장소 12줄(grafana.github.io·charts.min.io 등)은 안 건드린다. 바꾸는 것은 "내 인프라 코드를 어디서 읽나"뿐이다.

울타리를 먼저 넓힌다 — 순서가 있다

repoURL만 바꾸면 안 된다. AppProject가 읽어도 되는 저장소 목록을 따로 갖고 있다.

# argocd/projects/{apps,infra,secrets}.yaml
sourceRepos:
  - https://github.com/sss654654/cgv-infra.git

여기에 GitLab이 없는 상태로 repoURL을 바꾸면 App 전부가 repository not permitted in project로 막힌다. 그래서 순서가 셋이 된다.

① 넓힌다    sourceRepos 에 GitLab 을 추가.  GitHub 는 남긴다
           이 시점에는 repoURL 이 아직 GitHub 라 그것도 허용돼 있어야 한다
② 옮긴다    repoURL 11줄을 GitLab 으로
③ 좁힌다    sourceRepos 에서 GitHub 제거.  전환을 확인한 뒤

②를 되돌려야 할 때 ①이 살아 있어야 한다. 그래서 ③은 확인이 끝난 다음이다.

커밋 둘, MR 하나

9818372   AppProject 허용 저장소에 GitLab 주소 추가      3파일 3줄
c0f6ac0   ArgoCD가 읽는 저장소를 GitLab으로 전환         10파일 11줄

브랜치 하나에 쌓아 MR로 올린다. 스쿼시가 걸려 있어 main에는 하나로 들어가고, MR의 Commits 탭에 둘이 그대로 남는다.

59203d1  AppProject 허용 저장소에 GitLab 주소 추가 (cgv/cgv-infra!3)
         13 files changed, 14 insertions(+), 11 deletions(-)

root-app은 자기 자신을 배달하지 않는다

머지해도 클러스터의 root Application은 안 바뀐다.

# bootstrap/root-app.yaml
source:
  repoURL: …
  path: argocd            ← argocd/ 만 본다.  bootstrap/ 은 안 본다

root-app이 관리하는 것은 argocd/ 아래이고, 자기 정의 파일은 그 밖에 있다. 아무도 그 파일을 배달하지 않으므로 손으로 넣어야 한다.

kubectl apply -f bootstrap/root-app.yaml

application.argoproj.io/root configured

그 한 줄이 전환이다

root-app이 default AppProject에 속하고, 그 프로젝트는 sourceRepos: ["*"]다. 어느 저장소든 읽을 수 있어서 GitLab을 곧장 본다.

kubectl apply
  → root Application 의 repoURL 이 GitLab 으로 바뀐다
    → root-app 이 GitLab 에서 argocd/ 를 읽는다      ← 자격 Secret 을 여기서 처음 쓴다
      → AppProject 3개 · Application 6개 · ApplicationSet 3개가 갱신된다
        → 그 App 들도 GitLab 을 보기 시작한다

미러가 GitHub로 나가기를 기다릴 필요가 없다. 어차피 해야 하는 단계를 앞으로 당긴 것뿐이고, 그 순간이 곧 전환이다.

확인

kubectl -n argocd get app -o custom-columns='NAME:.metadata.name,REPO:.spec.source.repoURL,SYNC:.status.sync.status,HEALTH:.status.health.status'

NAME                 REPO                                          SYNC     HEALTH
dashboards           http://192.168.0.167:8929/cgv/cgv-infra.git   Synced   Healthy
kafka                http://192.168.0.167:8929/cgv/cgv-infra.git   Synced   Healthy
mysql                http://192.168.0.167:8929/cgv/cgv-infra.git   Synced   Healthy
redis                http://192.168.0.167:8929/cgv/cgv-infra.git   Synced   Healthy
…
grafana              <none>                                        Synced   Healthy
mimir                <none>                                        Synced   Healthy

<none>으로 보이는 열 개는 멀티소스 App이다. 업스트림 차트와 값 제공용 git 소스를 함께 쓰므로 .spec.source가 아니라 .spec.sources[*]에 들어 있다.

kubectl -n argocd get app -o custom-columns='NAME:.metadata.name,SOURCES:.spec.sources[*].repoURL'

NAME       SOURCES
grafana    https://grafana.github.io/helm-charts,http://192.168.0.167:8929/cgv/cgv-infra.git
mimir      https://grafana.github.io/helm-charts,http://192.168.0.167:8929/cgv/cgv-infra.git
minio      https://charts.min.io/,http://192.168.0.167:8929/cgv/cgv-infra.git
traefik    https://traefik.github.io/charts,http://192.168.0.167:8929/cgv/cgv-infra.git

소스가 둘씩이고, 앞은 업스트림 차트 그대로 뒤만 GitLab이다. 관측 스택은 차트를 업스트림에서 받고 환경값만 내 저장소에서 읽는 구조라, 전환이 "내 인프라 코드를 어디서 읽나"에만 걸렸다는 것이 이 목록으로 확인된다.

App 20개 전부, 20개 모두 Synced. 업스트림 차트는 그대로고 값 소스만 GitLab으로 옮겨졌다.

Degraded 넷은 이 작업과 무관하다

booking · frontend · queue    ImagePullBackOff   AGE 7d23h
root                          자식이 Degraded 라 따라 Degraded

이미지가 아직 없어서다. 앱 이미지를 빌드해 레지스트리에 올리는 것이 10부, 그 이미지로 앱이 뜨는 것이 11부다. SYNC가 Synced인 것이 그 증거다 — git에 적힌 대로 클러스터가 맞춰져 있고, 다만 그 선언이 요구하는 이미지가 아직 세상에 없다.

남은 것 — 좁힌다

전환이 확인됐으니 sourceRepos에서 GitHub를 뺀다. 안 빼도 지금 GitHub를 보고 있지는 않다 — sourceRepos는 "보는 곳"이 아니라 "봐도 되는 곳"이다. 다만 안 쓰는 문이 열려 있으면, 실수로 GitHub를 가리키는 App이 들어와도 안 막힌다.

그 커밋은 다음 장 작업과 함께 보낸다.

6. 울타리와 제어면

원본은 옮겼는데 구멍이 둘 남았다.

① ArgoCD 자신이 GitOps 밖에 있다     설정 파일은 git 에 있는데 적용은 helm 을 손으로 친다
                                   커밋만 하고 적용을 잊어도 아무 표시가 없다

② root App 만 울타리가 없다          default 프로젝트라 저장소 · 네임스페이스 · 리소스가 전부 "*"
                                   울타리를 세우는 App 이 울타리 밖에 있다

6.1 AppProject — Application이 할 수 있는 일의 범위

Application 하나는 반드시 프로젝트 하나에 속하고, 그 프로젝트가 반경을 정한다.

sourceRepos                  어느 저장소를 읽어도 되나
destinations                 어느 클러스터 · 네임스페이스에 배포해도 되나
clusterResourceWhitelist     ClusterRole · CRD 같은 클러스터 범위 리소스를 만들어도 되나
namespaceResourceWhitelist   네임스페이스 안 리소스는 어떤 종류까지

ArgoCD는 클러스터 관리자 권한으로 돈다. App 하나만 잘못돼도 클러스터에 뭐든 만들 수 있어서, 그 반경을 미리 좁혀 둔다.

지금 넷을 나란히 놓으면 이렇다.

프로젝트    저장소                  네임스페이스                          cluster 리소스   ns 리소스
────────────────────────────────────────────────────────────────────────────────────────
default    *                     *                                   *             *
apps       cgv-infra             app                                 없음           *
infra      cgv-infra + 업스트림 6   data · observability · …  다섯       *             *
secrets    cgv-infra             data · app · observability · argocd  없음        SealedSecret

갈린 기준은 네임스페이스가 아니라 "무엇을 하는 App인가"다. secrets가 그 예다 — 네 방에 들어가지만 만들 수 있는 것은 SealedSecret 하나뿐이라, 그 App이 읽는 디렉터리에 Deployment가 섞여도 거부된다.

apps가 업스트림 저장소를 안 여는 것도 같은 축이다. 앱 차트는 내가 썼으므로 외부에서 받을 일이 없고, 안 열어 뒀으니 그 App이 인터넷에서 무언가 받아 배포하는 길이 막혀 있다.

6.2 울타리를 좁힌다

허용 저장소를 GitLab 하나로

repoURL이 전부 GitLab을 가리키므로 GitHub 주소는 더 이상 참조되지 않는다. 목록에 남겨 두면 GitHub를 가리키는 Application이 실수로 들어와도 프로젝트가 안 막는다.

argocd/projects/{apps,infra,secrets}.yaml    각 1줄 삭제

root 전용 프로젝트

root는 default에 있었다. GitOps 진입점이 클러스터에서 가장 넓은 권한을 갖는 상태다.

# argocd/projects/bootstrap.yaml
sourceRepos:
  - http://192.168.0.167:8929/cgv/cgv-infra.git
destinations:
  - namespace: argocd
clusterResourceWhitelist: []          # cluster-scoped 리소스를 만들지 않는다
namespaceResourceWhitelist:
  - group: argoproj.io
    kind: AppProject / Application / ApplicationSet

root가 만드는 것은 선언뿐이다. 워크로드는 그 선언이 만든 App들이 각자의 프로젝트 안에서 만들므로, root에는 그 권한이 필요 없다.

bootstrap/root-app.yaml의 project를 바꾸고 손으로 apply한다. 그 파일은 argocd/ 밖에 있어 root가 배달하지 않는다.

kubectl apply -f bootstrap/root-app.yaml

6.3 ArgoCD가 자기를 관리한다

bootstrap/argocd/values.yaml은 git에 있는데 적용은 helm upgrade를 손으로 친다. 커밋만 하고 적용을 잊어도 아무 표시가 없다.

차트를 Application으로 만든다

# argocd/applications/argocd.yaml
spec:
  project: argocd
  sources:
    - repoURL: https://argoproj.github.io/argo-helm
      chart: argo-cd
      targetRevision: 10.1.4                       # 설치된 버전과 같게
      helm:
        valueFiles: [ $values/bootstrap/argocd/values.yaml ]
    - repoURL: <GitLab>
      ref: values                                  # 값만 제공.  이 소스는 배포하지 않는다
  syncPolicy:
    automated:
      prune: false
      selfHeal: false

targetRevision이 다르면 이 App이 처음 sync하는 순간 ArgoCD가 자기를 업그레이드하며 재시작한다. 설치된 것과 같게 둔다.

두 스위치를 끄는 이유

prune      이 파일이 사라지면 ArgoCD 가 자기 리소스를 지운다.  지우고 나면 되살릴 주체가 없다
selfHeal   sync 가 argocd-server · application-controller 를 재시작시키고,
           그 재시작이 다시 sync 를 유발하는 순환에 들어갈 수 있다

끄고 나면 클러스터 쪽 drift 교정은 못 얻는다. 남는 것은 git 변경이 자동으로 반영되는 것과, 어긋나면 OutOfSync로 드러나는 것이다.

전용 프로젝트인 이유

argo-cd 차트가 만드는 것    Deployment · Service · ConfigMap · ServiceAccount
                        ClusterRole · ClusterRoleBinding · CRD

infra에 합치면 플랫폼 워크로드 App도 제어면 네임스페이스에 닿을 수 있게 된다. 반경이 다르므로 분리한다.

최초 설치는 여전히 helm이 한다

클러스터가 비어 있을 때는 ArgoCD를 배포할 주체가 없다. install.sh가 helm install로 넣고, 이 App이 그렇게 만들어진 리소스를 이어받는다. 그래서 소유자가 잠시 둘이 된다.

helm      Secret sh.helm.release.v1.argocd.*  이 남는다.  helm list 에 계속 보인다
ArgoCD    같은 리소스를 관리하기 시작한다

ArgoCD의 Helm 지원은 helm template 방식이라 release를 만들지 않는다. 옛 release 기록이 남아 있으면 누가 helm uninstall argocd를 쳤을 때 관리 중인 리소스가 통째로 사라진다. 인수인계를 확인한 뒤 그 기록만 지운다.

kubectl -n argocd delete secret -l owner=helm,name=argocd

인수인계 확인

프로젝트 목록에서 나이가 갈린다.

$ kubectl -n argocd get appproject
NAME        AGE
apps        8d
argocd      114s      ← root 가 방금 만든 것
bootstrap   114s      ← root 가 방금 만든 것
default     8d
infra       8d
secrets     8d

root가 배달한 결과다. bootstrap과 argocd는 커밋에만 있던 파일인데, 폴링 한 번에 클러스터 객체가 됐다.

$ kubectl -n argocd get app -o custom-columns='NAME:.metadata.name,PROJECT:.spec.project,SYNC:.status.sync.status,HEALTH:.status.health.status'
NAME      PROJECT     SYNC     HEALTH
argocd    argocd      Synced   Healthy    ← 새로 선 App
root      bootstrap   Synced   Healthy    ← default 에서 옮겨졌다
...       infra · apps · secrets          나머지 19 개 Synced

argocd가 Synced라는 것은 차트를 렌더한 결과와 클러스터에 있는 것이 같다는 뜻이다. helm이 만들어 둔 리소스를 그대로 이어받았다는 확인이다. 다르게 나왔다면 렌더 결과로 덮어썼을 것이므로, 설치 때 쓴 값 파일과 targetRevision이 같아야 이 결과가 나온다.

apps 프로젝트의 셋(booking·frontend·queue)은 Degraded다. 컨테이너 이미지를 아직 안 만들어 ImagePullBackOff에 있고, 이미지는 10부와 11부에서 만든다. Synced는 선언대로 배포됐다는 뜻이고 Healthy는 그것이 실제로 뜬다는 뜻이라, 둘은 따로 움직인다.

이제 옛 소유자를 지운다.

$ kubectl -n argocd delete secret -l owner=helm,name=argocd
secret "sh.helm.release.v1.argocd.v1" deleted
secret "sh.helm.release.v1.argocd.v2" deleted
secret "sh.helm.release.v1.argocd.v3" deleted

$ helm list -n argocd
NAME  NAMESPACE  REVISION  UPDATED  STATUS  CHART  APP VERSION

목록이 비었다. helm uninstall argocd로 제어면을 통째로 날릴 경로가 사라졌고, 소유자가 ArgoCD 하나로 남았다.

바뀐 것은 값을 고치는 자리다. bootstrap/argocd/values.yaml을 고치고 커밋하면 그것으로 끝난다 — helm upgrade를 치는 자리가 없어졌고, 커밋했는데 적용을 잊는 경우도 없어졌다. 대신 sync가 실패하면 제어면 자신이 못 고치는 상태가 되므로, install.sh의 helm install은 그 자리에 남는다.

7. 밖에서 안으로 — 이름과 즉시 반영

여기까지 원본이 옮겨졌다. ArgoCD가 GitHub 대신 데스크탑의 GitLab을 읽는다 — Application 스물한 개의 repoURL이 전부 그리로 향해 있고, 그 Application들이 할 수 있는 일의 반경도 프로젝트로 갈라 뒀다. ArgoCD는 자기 설정까지 커밋으로 받는다.

여기서는 남은 일 두 가지를 한다. 서로 별개의 일이다.

하나, ArgoCD와 Grafana를 여는 방법이 아직 kubectl port-forward뿐이다. 이름을 붙여 브라우저에서 바로 열리게 한다. 문을 낼 자리를 정하려면 요청이 밖에서 파드까지 가는 길을 전부 알아야 해서, 클러스터 네트워크를 여기서 같이 짚는다.

둘, 커밋하고 나면 여전히 기다린다. ArgoCD가 저장소를 주기적으로 다시 읽는 방식이라 커밋과 반영 사이에 최대 3분이 낀다. ArgoCD가 어떻게 돌고 있는지부터 보고, GitLab이 커밋을 받는 순간 알려 주도록 webhook을 건다.

7.1  문이 없다             port-forward 뿐 · 파드는 밖에서 안 보인다    ┐
7.2  주소를 전부 짚는다     클러스터 네트워크 · 세 층 · 문을 어디에       ├ 이름
7.3  이름을 붙인다         Ingress 둘 · hosts 두 줄                    ┘
7.4  ArgoCD는 어떻게 도나   루프 · watch 와 폴링 · 넣어 둔 자격의 자리    ┐
7.5  webhook으로 바꾼다    문서 둘로 고른다 · 폴링은 남긴다   [결정]      ├ 즉시 반영
7.6  webhook을 건다        GitLab 허용 · 비밀 · 등록                    ┘

두 일은 별개인데 순서에는 이유가 있다. 첫째 일이 낸 문을 둘째 일이 그대로 쓴다. 네트워크를 전면으로 다루는 것은 14부다. 여기서는 그때 바뀔 축만 미리 잡아 둔다.

7.1 문이 없다

ArgoCD 화면을 여는 방법이 지금 kubectl port-forward뿐이다. 8부 내내 그렇게 열었고 Grafana도 같다. 명령 하나가 늘 떠 있어야 하고, 끄면 닫힌다.

막힌 이유는 거리가 아니다. 데스크탑에서 노드까지는 닿는다 — 192.168.0.201로 ping도 되고 :6443으로 kubectl도 된다. 그런데 ArgoCD는 노드가 아니라 그 위에서 도는 파드이고, 파드가 사는 대역은 클러스터 밖에서 보이지 않는다. 데스크탑에는 그리로 가는 길이 아예 없다.

방향에 따라 갈리는 것이 이 구조의 성질이다. 파드가 밖으로 나가는 것은 된다 — ArgoCD가 데스크탑의 GitLab을 읽어 가는 것이 그 길이고, 나갈 때는 출발지가 감춰져 있어도 된다. 밖에서 파드로 들어오는 것이 안 된다 — 들어올 때는 목적지가 드러나 있어야 하는데, 파드 주소는 사설망에 없다.

port-forward는 이 벽을 문이 아니라 우회로로 넘는다. kubectl이 API 서버(:6443)에 터널을 뚫고 내 PC의 포트를 그 끝에 붙이는 것이라, kubeconfig(클러스터 전권 자격)가 있어야 하고 명령이 떠 있는 동안만 산다.

그러니 할 일은 밖에서 안으로 들어오는 문을 내는 것이다. 어디에 낼지 정하려면 클러스터가 쓰는 주소를 전부 짚어야 한다.

7.2 주소를 전부 짚는다 — 클러스터 네트워크

주소가 어디서 오나

사설망  192.168.0.0/24     공유기가 정한 대역
          .2 - .199        공유기가 DHCP 로 자동 발급
          .200 - .254      자동 발급 밖 — 손으로 정한다

  .1     공유기
  .167   데스크탑            DHCP 예약
  .200   노트북 = Proxmox    설치할 때 손으로 지정
           └ vmbr0 브리지가 VM 을 이 사설망에 그대로 참여시킨다
  .201   k3s-1  ┐
  .202   k3s-2  ├ 노드.  게스트 OS 에 고정으로 지정
  .203   k3s-3  ┘
  .240   MetalLB 가 풀(.240-250)에서 뗀 주소.  노드 것이 아니다

  ══════  여기부터 클러스터 안 — 사설망에서 안 보인다  ══════

10.43.x.x   Service    apiserver 가 만들 때 준다.  그 뒤 안 바뀐다
              traefik              ← .240 이 붙은 곳
              frontend · booking · queue
              argocd-server · grafana

10.42.x.x   Pod        Calico 가 뜰 때 준다.  죽으면 회수
              traefik 파드 2 (k3s-1 · k3s-2)
              앱 파드 · argocd-server 파드 · grafana 파드

노드와 MetalLB 풀을 자동 발급 구간 밖에 둔 것은 충돌을 막기 위해서다. 공유기가 같은 주소를 다른 장비에 내줄 일이 없다.

이 그림이 지금 문제를 다 말한다. argocd-server도 grafana도 클러스터 안에 있고, 그 안은 사설망에서 부를 수 없다. 선을 넘어 서 있는 것은 .240 하나뿐이고 그것은 Traefik Service에 붙어 있다. 밖에서 안으로 들어오는 길은 지금 이것뿐이다.

그 길이 어떻게 도는가 — 세 층

.240으로 들어온 요청이 파드에 닿기까지 세 층을 지난다. 층마다 볼 수 있는 것이 달라서, 정할 수 있는 것도 다르다.

1층 · MAC을 본다 → 어느 노드가 받나

브라우저 ──"192.168.0.240 누구?"──▶ 노드 하나가 자기 MAC 으로 답한다

.240은 클러스터로 들어오는 입구 주소다. 클러스터 안의 어떤 Service가 type: LoadBalancer로 "밖에서 닿는 IP를 하나 달라"고 선언했고, MetalLB가 풀에서 떼어 붙였다. 그 Service가 누구 것인지는 1층의 관심사가 아니다 — 여기서 정할 것은 어느 노드가 받느냐까지다.

그런데 Service는 etcd에 적힌 선언일 뿐이라, .240을 실제로 지고 있는 장비가 없다. 사설망에서 IP로 보내려면 그 IP를 가진 장치의 MAC을 알아야 하는데(그걸 묻는 것이 ARP다) 주인이 없으면 답이 없다.

MetalLB가 대신 답한다. 노드마다 파드가 하나씩 떠 있고 그중 하나가 "그 주소는 내 노드"라며 자기 MAC을 내준다. 셋이 떠 있어도 답이 하나인 것은 겨뤄서가 아니라 셋이 같은 계산(노드 이름 + 그 IP를 해시해 정렬)을 해서다. 매번 같은 노드가 받고, 그 노드가 죽으면 다음 순번이 이어받는다.

여기까지가 MetalLB의 전부다. ARP에 답할 뿐 요청 자체는 지나가지 않으니, 클라우드의 ELB처럼 트래픽을 나누는 일도 안 한다 — MetalLB 문서도 "does not implement a load balancer"라 적고 하는 일을 failover라 부른다. 그런데도 이 자리가 필요한 것은 주소 하나를 고정해 주기 때문이다. MetalLB가 없으면 NodePort뿐이라 부르는 쪽이 192.168.0.201:31234처럼 노드를 지목해야 한다.

1층의 목적은 하나였다 — 밖에 있는 요청을 클러스터 안의 어느 노드까지 실어 오는 것, 그것도 부르는 쪽이 노드를 하나도 모른 채로. .240이 그 발판이다. 노드 주소도 파드 주소도 아닌, "클러스터로 들어오는 입구"라는 뜻만 가진 주소다. 뒤에 노드가 몇 대인지 누가 살아 있는지는 MetalLB가 감춘다.

결과는 이렇다. 요청이 k3s-3에 도착했고, 그 안에 적힌 목적지는 아직 192.168.0.240:80 그대로다. ARP로 정한 것은 어느 장비로 배달할지였을 뿐, 목적지는 건드리지 않았다.

그래서 k3s-3은 자기 IP가 아닌 목적지를 든 요청을 손에 든 상태다. 보통 노드라면 이런 것을 버린다.

2층 · 목적지를 바꾼다 → 어느 파드가 받나

목적지 192.168.0.240:80  ──kube-proxy 규칙──▶  목적지 10.42.207.59

k3s-3은 그것을 버리지 않는다. 이유는 곧 나오고, 먼저 .240이 누구 것인지부터 밝혀야 한다. 1층에서 이름을 안 밝힌 그 Service가 Traefik의 것이다. 여기서 이름 셋이 나오는데 서로 층이 다르다.

Traefik            Ingress 를 읽어 실제로 보내는 프로그램.  = Ingress 컨트롤러
Traefik 파드        그 Traefik 이 도는 곳.  지금 둘
Traefik Service    그 파드 앞에 선 고정 주소.  .240 이 붙어 있다
Ingress            "어떤 이름으로 오면 어디로" 를 적어 둔 규칙.  Traefik 이 읽는다

규칙과 실행이 갈려 있다는 것이 그 이름의 뜻이다. Ingress는 적어 둔 문서일 뿐이고, 그것을 읽어 실제로 보내는 쪽이 Traefik이다. 규칙을 읽는 일은 3층에서 하고, 2층은 Traefik이 도는 파드까지 요청을 데려다 놓는 데까지다.

그러면 2층이 할 일이 정해진다. Traefik은 Ingress에 적힌 규칙 — 지금 서 있는 것은 /api/admission이면 queue로, /api면 booking으로, 나머지는 frontend로 — 을 보고 최종 목적지를 고르는 프로그램이고, 그것이 도는 곳은 파드이지 .240이 아니다. 그래서 목적지를 그 파드 주소로 바꿔야 한다.

그런데 k3s-3에는 그 파드가 없다. Traefik 파드를 두 개만 띄워 뒀기 때문이다 — 진입점이 하나 죽어도 남은 하나가 받도록 둘을 서로 다른 노드에 강제했고, 노드가 셋이니 한 대는 비게 된다. 그리고 1층에서 답할 노드를 고른 기준은 해시 순서였지 "Traefik이 있는 노드"가 아니었다.

파드는 죽고 다시 뜰 때마다 다른 주소를 받아서 어디에도 적어 둘 수가 없다. 그래서 부를 이름은 Service 쪽에 두고, 그 Service 뒤에 지금 살아 있는 파드 목록을 따로 관리한다. 그 목록이 엔드포인트다. Traefik Service의 엔드포인트는 지금 파드 둘 — 10.42.207.59(k3s-1)와 10.42.47.249(k3s-2)다.

그런데 엔드포인트도 API에 적힌 목록일 뿐이다. 그 목록을 읽어 실제로 목적지를 갈아 끼워 줄 것이 따로 있어야 하는데, 그 자리가 kube-proxy다.

proxy라는 이름은 보통 중간에서 요청을 받아 대신 전달하는 것을 뜻하는데, kube-proxy는 그렇게 하지 않는다. 요청은 kube-proxy를 거치지 않고 노드 커널에서 곧장 처리된다. kube-proxy가 하는 일은 Service와 엔드포인트를 쿠버네티스 API에서 지켜보다가, 그 내용을 커널이 알아들을 규칙으로 번역해 깔아 두는 것이다.

목적지가 192.168.0.240:80 이면
   → 10.42.207.59  (k3s-1 의 Traefik 파드)
   → 10.42.47.249  (k3s-2 의 Traefik 파드)
   둘 중 하나로 바꿔라

kube-proxy는 이 규칙을 노드마다 깐다. Traefik 파드를 하나도 안 가진 k3s-3의 커널에도 똑같이 들어 있다. 그래서 앞의 문제가 풀린다 — k3s-3이 요청을 받아도 그 노드의 커널이 k3s-1·k3s-2에 있는 파드 주소를 알고 있으니, 그리로 보내면 된다.

그래서 k3s-3이 받아 든 요청의 목적지가 여기서 처음 바뀐다. k3s-3의 커널이 두 파드 주소 중 하나를 골라 목적지 칸을 갈아 끼운다. 목적지 쪽을 바꾸는 것이라 DNAT라 부른다. 커널이 패킷마다 고르므로 요청이 자연히 두 파드로 나뉘고, 1층에서 한 노드로 몰렸던 것이 여기서 분배된다.

고른 파드가 k3s-3이 아닌 다른 노드에 있으면, 그 패킷은 Calico가 깔아 둔 파드 네트워크를 타고 한 홉 더 간다. 이때 k3s-3의 커널이 출발지 칸도 바꾼다 — 응답이 돌아올 길을 남기려면 거쳐 간 노드를 출발지로 적어야 하기 때문이다. 출발지 쪽을 바꾸는 것이라 SNAT다. 그 결과 Traefik 파드에는 브라우저 주소가 아니라 k3s-3의 주소가 찍히고, 14부에서 이 값이 다시 나온다.

2층이 끝난 지점은 이렇다. 요청의 목적지가 192.168.0.240:80에서 Traefik 파드 주소로 바뀌었고, 그 파드에 도착했다. 그런데 여기까지 아무도 요청 안을 열어 보지 않았다. 1층은 MAC만, 2층은 IP와 포트만 보고 옮겼다. 어떤 이름으로 접속했는지는 아직 아무도 모른다.

3층 · Host와 경로를 본다 → 어느 서비스로 가나

Traefik ──Host + 경로를 Ingress 규칙과 대조──▶ 앱 파드

여기서 Traefik이 처음으로 요청을 열어 안을 읽는다. 브라우저는 Host 헤더에 "어떤 이름으로 접속했는지"를 적어 보냈고, Traefik은 그 값과 경로를 대조할 규칙을 갖고 있다. 그 규칙이 2층에서 이름만 나왔던 Ingress다.

지금 이 클러스터에 서 있는 Ingress는 하나뿐이다.

kind: Ingress
spec:
  ingressClassName: traefik      # 누가 이 규칙을 맡나
  rules:
    - http:                      # host 조건이 없다
        paths:
          - path: /api/admission
            backend: { service: { name: queue } }
          - path: /api
            backend: { service: { name: booking } }
          - path: /
            backend: { service: { name: frontend } }

host 조건이 없다는 것은 "아무거나 다 받는다"는 뜻이다. rules 항목에 host:를 적으면 그 이름으로 온 요청만 그 규칙이 잡는데, 여기엔 안 적혀 있다. 이름을 아직 안 정했기 때문이다. hosts에도 DNS에도 등록한 것이 없으니 적어 봐야 아무도 그 이름으로 올 수 없고, 규칙 뒤에 설 앱 이미지도 아직 없다(10부·11부).

Ingress는 요청이 지나가는 물건이 아니라 이 문서 자체다. 읽어서 실행하는 것은 Traefik이고, 쿠버네티스 API를 지켜보다가 Ingress가 생기거나 바뀌면 재시작 없이 자기 라우팅 표를 갱신한다.

ingressClassName이 첫 칸에 있는 이유는 한 클러스터에 Ingress 컨트롤러가 여럿 있을 수 있어서다. 컨트롤러는 설치될 때 IngressClass 리소스를 하나 만들어 "이 이름이 적힌 Ingress는 내가 맡는다"고 선언하고, Ingress는 이 한 줄로 담당자를 고른다. 지금 이 클러스터에 선 Ingress 컨트롤러는 Traefik 한 벌뿐이라 이 줄을 비워도 그 컨트롤러가 맡는다.

Traefik은 읽은 값을 이 rules와 위에서부터 대조한다. 요청 경로가 /api면 path: /api 줄이 걸리고, 그 줄의 backend에 적힌 booking이 목적지 Service로 정해진다. Ingress가 주는 답은 여기까지 — 어느 Service냐다.

그다음 Traefik이 그 booking Service의 엔드포인트에서 앱 파드 하나를 골라 보낸다. 엔드포인트 목록을 자기가 들고 있어서, 여기서는 커널 규칙을 빌리지 않는다.

3층이 끝난 지점은 이렇다. Traefik이 요청을 열어 Host와 경로를 읽었고, 규칙에서 짝을 찾아 뒤에 있는 앱 파드(queue·booking·frontend 중 하나)로 보냈다.

MetalLB가 ARP에 답해 어느 노드까지 데려오고, kube-proxy가 Service와 엔드포인트를 커널 규칙으로 옮겨 어느 파드인지를 정하고(그 파드가 다른 노드면 Calico가 나른다), 그 파드의 Traefik이 Ingress를 읽어 어느 서비스인지를 정한다. 층이 올라갈수록 볼 수 있는 것이 늘고 정해지는 것이 좁아진다.

그래서 문을 어디에 내면 되나

ArgoCD도 10.42.x.x에 있는 파드다. 방금 요청이 닿은 queue·booking·frontend와 처지가 같은데, 그 셋은 밖에서 닿고 ArgoCD는 안 닿는다. 차이는 하나뿐이다 — 앱 셋에는 .240에서 자기에게로 오는 Ingress 규칙이 있고, ArgoCD에는 없다.

지금 밖에서 닿는 것   192.168.0.240 → queue · booking · frontend
그 밖 전부           port-forward 로만 — ArgoCD · Grafana · MinIO …

앱 3종이 ImagePullBackOff라 지금 .240을 열면 503이긴 하다. 규칙은 서 있고 뒤가 비어 있는 상태이고, 이미지는 10부, 앱 기동은 11부다.

그러니 새 문을 뚫을 일이 아니다. MetalLB에 IP를 더 받을 것도, Service를 새로 만들 것도 아니다. .240에서 Traefik 파드까지 오는 길은 이미 서 있고, 거기서 ArgoCD로 갈라지는 규칙 한 줄이 없을 뿐이다.

그 한 줄에는 host 조건을 단다. host와 경로는 둘 중 하나를 고르는 게 아니라 축이 둘이다 — host가 어떤 사이트인지를 가르고, 경로가 그 사이트 안 어디인지를 가른다.

앱 셋이 경로로 갈린 것은 폴리글랏 MSA라 서비스는 셋이어도 브라우저에서는 한 사이트여서다. /는 화면, /api는 예매, /api/admission은 대기열 — 이름 하나 아래에서 경로로 나누는 게 맞다. ArgoCD와 Grafana는 예매 서비스와 관계없는 각각 별개의 사이트이고 사람이 따로 연다. 그러니 경로가 아니라 이름으로 갈라야 한다.

그래서 다음 절에서 할 일이 셋으로 정해진다. ArgoCD와 Grafana에 Ingress를 하나씩 세우고, 각각에 host 조건을 달고, 그 이름을 .240으로 풀어 줄 자리를 만든다. 그러면 port-forward 없이 이름으로 열린다.

7.3 이름을 붙인다

이름 둘을 정한다

argocd.cgv.lan과 grafana.cgv.lan으로 간다. .local은 mDNS가 예약해 쓰는 자리라 이름 해석이 엉키고, .lan은 공인 DNS에 올릴 수 없어 밖에서는 그 이름이 존재하지 않는다.

MetalLB 풀에 .241부터 열 개가 남아 있어 주소를 하나씩 줄 수도 있다. 그렇게 안 하는 것은 주소가 늘면 그 주소마다 방화벽 규칙과 TLS 인증서가 따로 늘기 때문이다. .240 하나가 다 받고 이름으로 가르면 인증·TLS를 한 자리에서 건다.

.240에는 이미 host 조건 없는 Ingress가 하나 있다. 거기에 host를 가진 규칙 둘을 더하면 조건이 있는 쪽이 더 구체적이라 먼저 맞고, 조건 없는 쪽이 나머지를 받는 자리로 남는다. 기존 규칙은 건드리지 않는다.

Host: argocd.cgv.lan     →  argocd-server
Host: grafana.cgv.lan    →  grafana
그 밖 전부                →  frontend  (조건 없는 기존 규칙이 받는다)

값 두 개를 켠다

두 차트 모두 Ingress를 만드는 템플릿을 원래 갖고 있고 꺼져 있을 뿐이다. 차트를 고칠 일은 없고 값만 넘긴다.

# bootstrap/argocd/values.yaml
server:
  ingress:
    enabled: true
    ingressClassName: traefik
    hostname: argocd.cgv.lan
    tls: false

# workloads/charts/observability/grafana/values.yaml
ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - grafana.cgv.lan

같은 물건을 만드는데 값의 이름이 서로 다르다. argo-cd는 hostname으로 문자열 하나를 받고, grafana는 hosts로 리스트를 받는다. tls: false는 argo-cd 차트가 argocd-server-tls 시크릿을 참조하지 않게 한다 — 인증서를 아직 발급하지 않았고, ArgoCD 자신이 평문으로 받는 설정과 짝이다.

argocd/ 아래에서 이 저장소를 가리키는 소스는 전부 targetRevision: main이라, 브랜치에 push해도 ArgoCD는 보지 않는다. 머지한 뒤 grafana 쪽 Ingress가 먼저 서고 argocd 쪽은 3분 남짓 뒤에 섰다 — 같은 커밋인데 시차가 나고, 그동안 argocd App은 Synced로 보였다. 왜 그런지는 다음 절에서 ArgoCD를 뜯을 때 풀린다.

$ kubectl get ingress -A

NAMESPACE       NAME            CLASS     HOSTS             ADDRESS         PORTS
app             frontend        traefik   *                 192.168.0.240   80
argocd          argocd-server   traefik   argocd.cgv.lan    192.168.0.240   80
observability   grafana         traefik   grafana.cgv.lan   192.168.0.240   80

HOSTS가 *인 줄이 조건 없는 기존 규칙이다. 셋이 같은 ADDRESS를 쓴다 — IP는 하나고 이름으로만 갈린다.

설치 안내 세 곳에 남아 있는 port-forward도 같이 손본다. 지우지 않고 뒤에 붙인다 — 부트스트랩 도중에는 Traefik도 Ingress도 아직 없어서 그 경로가 실제로 유일하다.

※ argocd는 traefik(GitOps) 뜨기 전엔 ingress 없음 → 초기 접근 port-forward
  traefik이 뜬 뒤 argocd.cgv.lan · grafana.cgv.lan
  두 이름은 접근하는 기기의 hosts 또는 DNS가 traefik 주소로 풀어줘야 한다

이름을 풀어 줄 자리

여는 기기의 hosts 파일에 두 줄을 더한다. OS는 DNS 서버에 묻기 전에 이 파일을 먼저 보고, 여기 적힌 이름은 질의 없이 그 IP로 확정된다. Windows에서는 C:\Windows\System32\drivers\etc\hosts이고 관리자 권한이 필요하다 — 이 파일을 고칠 수 있으면 어떤 이름이든 원하는 IP로 돌릴 수 있어서다.

192.168.0.240  argocd.cgv.lan
192.168.0.240  grafana.cgv.lan

같은 이름이 두 군데 나오는데 하는 일이 다르다. hosts의 argocd.cgv.lan은 "이 이름이 어느 IP냐"에 답하고, Ingress의 host는 "이 이름으로 온 요청을 어디로 보내냐"에 답한다. 앞의 것이 없으면 출발을 못 하고, 뒤의 것이 없으면 .240까지 가서 조건 없는 규칙으로 흘러 503이 돌아온다.

둘을 잇는 것은 브라우저다. http://argocd.cgv.lan을 열면 브라우저는 이름을 IP로 바꿔 연결한 다음, 그 이름을 요청 안에 Host: 한 줄로 다시 적어 보낸다. 이름이 사라지지 않고 따라오기 때문에 Traefik이 어느 이름으로 왔는지 알 수 있고, 한 IP 위에 사이트를 여럿 얹을 수 있다.

넣고 나면 두 이름 모두 192.168.0.240으로 풀린다. argocd는 200, grafana는 로그인 화면으로 넘기는 302가 돌아온다.

이건 파일을 고친 기기 한 대에서만 통한다. 다른 기기에서 같은 이름을 열려면 그 기기에도 같은 두 줄을 넣어야 하고, .240이 바뀌면 넣어 둔 곳을 전부 고쳐야 한다. 이름에 답하는 자리를 기기 밖 한 곳으로 옮기는 것이 DNS이고, 그건 클러스터를 밖으로 열 때(14부) 함께 세운다.

무엇이 바뀌었나

kubeconfig를 가진 사람에게만 열리던 우회로가, 자격 없이 열리는 문이 됐다. 전에는 쿠버네티스가 터널을 내주기 전에 신원을 확인했고, 이제는 .240에 닿을 수 있으면 누구나 로그인 화면까지 온다. 그 자리를 ArgoCD와 Grafana의 로그인이 맡는다.

7.4 ArgoCD는 어떻게 돌고 있나

이름 붙이는 일은 끝났고, 둘째 일로 넘어간다. 커밋과 반영 사이의 대기를 없애려면 그 대기가 어디서 생기는지부터 알아야 한다.

파드 다섯이 루프 하나를 돈다

argocd 네임스페이스에 역할이 다른 파드 다섯이 있다.

argocd-server                     UI 와 API.  방금 이름을 붙여 연 곳
argocd-repo-server                git 을 읽어 매니페스트를 렌더한다
argocd-application-controller     Application 하나마다 렌더 결과와 클러스터를 비교하고 적용한다
argocd-applicationset-controller  한 층 위 — ApplicationSet 을 읽어 Application 여럿을 만든다
argocd-redis                      렌더 결과와 리소스 상태를 담는 캐시

앞의 셋이 App 스물한 개마다 같은 루프를 돈다.

①  repo-server 가 git 을 읽어 렌더한다             ─ 원하는 상태
②  application-controller 가 클러스터와 비교한다     ─ 현재 상태
③  다르면 적용한다                                ─ automated 라 사람 승인 없이

이 루프에 붙은 이름이 GitOps다. git이 원하는 상태의 정본이고, 클러스터 안의 ArgoCD가 그것을 읽어 스스로 맞춘다. CI가 밖에서 kubectl apply를 쏘는 방식과 갈리는 지점은 클러스터 밖 누구도 클러스터를 건드릴 자격을 갖지 않는다는 것이다.

① repo-server 가 git 을 읽으려면

repo-server는 아무 저장소나 읽는 것이 아니라 Application에 적힌 대로 읽는다. 어느 저장소인지(repoURL), 어느 리비전인지(targetRevision), 무엇을 어떤 값으로 렌더할지(chart·path·valueFiles)가 전부 그 매니페스트에 있다. ApplicationSet이 만든 App이면 그 지시서가 자동으로 여럿 찍혀 나온 것뿐이다.

그 지시서를 들고 도는 ①은 이 루프에서 클러스터 밖으로 나가는 단계 하나뿐이다. 안을 열면 넷으로 갈린다.

(밖 — GitLab)   targetRevision 에 적힌 브랜치의 지금 커밋 SHA 를 묻는다
(안 — redis)    그 커밋의 렌더 결과가 있으면 꺼내 쓰고 끝낸다
(밖 — GitLab)   없으면 저장소를 받아
(안)              valueFiles 를 겹쳐 helm template 을 돌리고 redis 에 넣는다

밖으로 나가는 자리가 둘이다 — 커밋 SHA를 물을 때, 그리고 저장소를 받을 때. 그 둘이 되려면 경로와 자격이 있어야 하고, 이 편에서 만든 것이 정확히 그 둘이다.

경로는 원래 있었다. 노드와 데스크탑이 같은 사설망 192.168.0.0/24 안이라 repo-server가 192.168.0.167:8929로 나가면 바로 닿는다. GitHub를 읽던 시절에는 공유기를 지나 인터넷으로 나갔을 뿐, 나가는 방향은 막힌 적이 없다.

자격은 저장소가 private이라 필요하다. 닿아도 거부당하기 때문이다. deploy token을 argocd-repo-cgv-infra Secret으로 봉인해 넣은 것이 이 자리다.

가운데 칸에 나온 argocd-redis는 데이터베이스가 아니라 캐시라 파드가 죽어도 잃을 것이 없다. 다시 렌더하느라 느려질 뿐이다. 대신 커밋이 그대로면 렌더를 건너뛴다 — 확인이 자주 돌아도 매번 App 스물한 개를 통째로 렌더하지는 않는다.

② application-controller 가 견주는 두 값 — watch 와 폴링

경로도 자격도 있으니 루프는 돈다. 그런데 application-controller가 견주는 두 값은 갱신되는 방식이 서로 다르다. 하나는 repo-server가 렌더해 둔 원하는 상태이고, 하나는 클러스터의 현재 상태다.

클러스터의 현재 상태는 즉시 안다. application-controller가 쿠버네티스 API에 watch를 걸어 두어서, 누가 리소스를 손으로 바꾸면 그 순간 통지가 온다. selfHeal이 손댄 것을 곧바로 되돌리는 것이 이 축이다.

원하는 상태는 물어봐야 안다. GitLab은 클러스터 밖의 남의 서버라 watch를 걸 수 없다. 그래서 repo-server가 저장소를 주기적으로 다시 읽는다 — 이것이 폴링이다. 주기는 argo-cd 차트가 주는 timeout.reconciliation: 120s에 지터 60s가 붙어 한 번의 대기가 2분에서 3분 사이이고, 지터는 App 스물한 개의 확인이 한 순간에 몰리는 것을 흩는다.

그래서 Synced가 뜻하는 것도 좁다. repo-server가 마지막으로 읽은 커밋 기준으로 클러스터가 같다는 뜻이지, 저장소의 최신 커밋 기준이 아니다.

여기까지가 지금 도는 방식이다. 이 대기를 없애는 다른 길이 webhook이고, 둘을 견줘 정한다.

7.5 webhook으로 바꾼다

얻는 것 — ArgoCD 문서

Argo CD polls Git/OCI/Helm repositories every three minutes to detect changes to the manifests.

To eliminate this delay from polling, the API server can be configured to receive webhook events.

— Argo CD, Webhook Configuration

폴링의 방향을 뒤집는 것이다. ArgoCD가 물으러 가는 대신, GitLab이 push를 받는 순간 ArgoCD의 수신 주소를 불러 "다시 읽어라"를 그 자리에서 당긴다.

지금        커밋 → (최대 3분 대기) → 읽는다 → 비교 → 적용
webhook 뒤   커밋 → (알림 즉시)    → 읽는다 → 비교 → 적용

앞당겨지는 건 읽기 시작하는 시점 하나라, 루프는 그대로 두고 대기만 걷어낸다.

받는 자리를 문서는 API 서버 — argocd-server — 로 지정한다. 방금 이름을 붙여 연 그 파드다. 사람이 브라우저로 들어가는 문을 GitLab도 쓰는 것이라 새로 낼 것이 없고, 두드릴 주소만 정해진다: http://argocd.cgv.lan/api/webhook.

그래도 폴링을 남기는 이유 — GitLab 문서

Webhooks are temporarily disabled if they fail four consecutive times.

Temporarily disabled webhooks are initially disabled for one minute, with the duration extending on subsequent failures up to 24 hours.

To re-enable a disabled webhook, send a test request. The webhook is re-enabled if the test request returns a response code in the 2xx range.

— GitLab, Webhooks

실패한 전송을 다시 보내지 않고, 네 번 연속이면 GitLab이 그 webhook을 스스로 끈다. 다시 켜는 조건이 사람이 보내는 테스트 요청이라 아무도 안 보내면 최대 24시간까지 꺼져 있고, 꺼졌다고 알려 주는 장치도 없다.

이 조건이 이 홈랩에서 자주 성립한다. 데스크탑과 노트북을 따로 켜므로 노트북(클러스터)이 꺼진 채 push를 몇 번 하면 네 번이 채워진다. webhook만 믿고 있었다면 그때부터 커밋이 조용히 안 반영된다.

→ webhook 단독으로는 반영이 보장되지 않는다.

그래서 둘을 같이 둔다

webhook이 평소에 즉시 반영하고(최대 3분 → 초), 폴링이 webhook이 놓친 것을 줍는다. webhook이 꺼져 있어도 최악 3분이면 따라잡는다.

폴링을 남기기로 했으니 주기를 얼마로 둘지가 결정 하나로 남는다. 흔한 권고는 webhook이 도는 것을 확인한 뒤 15분·1시간으로 늘리라는 것이고, 근거는 규모다 — App이 수백 개면 짧은 폴링이 repo-server 부하와 프로바이더 rate limit으로 돌아온다.

App 21개에 Git 서버가 내 데스크탑이면 그 전제가 없다. 늘려서 얻는 것은 측정되지 않는데, webhook이 꺼져 있을 때의 최악 대기는 3분에서 30분이 된다. 기본값을 그대로 둔다. 클러스터나 App이 크게 늘면 이 계산이 뒤집힌다 — 그때는 폴링을 늘리고 "webhook이 살아 있나"를 보는 장치를 따로 붙인다.

7.6 webhook을 건다

두드릴 주소는 이미 있다. argocd.cgv.lan에 Ingress로 이름을 붙였고 브라우저에서 열리는 것도 봤다. 남은 것은 GitLab이 그 주소를 두드리게 만드는 일이다.

지금       ArgoCD ──"바뀐 거 있어?"──▶ GitLab      폴링.  최대 3분
webhook    GitLab ──"방금 바뀌었다"──▶ ArgoCD      주소가 있어야 성립

그런데 주소가 있다고 바로 되지 않는다. 넘어야 할 것이 셋이다.

하나 — GitLab 이 사설 IP 로는 webhook 을 안 보낸다

webhook은 GitLab이 HTTP 요청을 하나 보내는 것이고, 보낼 주소는 사람이 폼에 적는다. 여기서 문제가 생긴다.

GitLab은 보통 여러 사람이 쓰는 서버이고, 그 서버는 어떤 망 안에 놓여 있다. 그 망에는 밖에서 못 닿는 것들이 있다 — 관리 페이지, DB, 클라우드 메타데이터 서버. GitLab이 폼에 적힌 주소를 검사 없이 두드린다면 이렇게 된다.

공격자가 프로젝트를 하나 만들고
webhook URL 에  http://10.0.0.5/admin/...  을 적는다
커밋 하나 push
   → GitLab 서버가 그 주소를 대신 두드린다

공격자는 사내망에 못 들어가는데 GitLab을 시켜서 들어갔다. 서버를 속여 대신 요청을 보내게 하는 이 패턴을 SSRF(Server-Side Request Forgery)라 부른다. 그래서 GitLab은 webhook이 10.x·192.168.x·127.0.0.1 같은 사설 대역으로 나가는 것을 기본으로 막는다.

우리 주소가 거기 걸린다. argocd.cgv.lan은 192.168.0.240으로 풀리고 그건 사설망이다. 그대로 등록하거나 Test를 누르면 GitLab이 거부한다.

푸는 자리는 Admin → Settings → Network → Outbound requests다. 전체를 열 수도 있고 허용 목록에 주소 하나만 넣을 수도 있는데, 후자로 간다 — 여는 범위가 좁다.

그 목록에는 IP가 아니라 이름을 적는다. GitLab의 허용 목록은 도메인 이름도 받는다. 이름으로 적어 두면 나중에 그 이름이 가리키는 IP가 바뀌어도 이 설정은 손댈 것이 없다.

둘 — GitLab 은 그 이름을 못 푼다

데스크탑 hosts에 두 줄을 넣어서 argocd.cgv.lan이 192.168.0.240으로 풀린다. 그런데 GitLab은 그 데스크탑에서 도는 Docker 컨테이너다.

컨테이너는 자기 파일시스템을 갖는다. 호스트의 hosts 파일을 안 보고, 컨테이너 안의 /etc/hosts에는 그 두 줄이 없다. 그래서 GitLab이 그 이름을 두드리려 하면 이름을 못 풀어 출발조차 못 한다. 사설망 차단을 풀어도 이건 따로 막힌다.

이름을 푸는 자리는 기기마다 따로 있는데, 같은 데스크탑 안이라도 컨테이너는 다른 기기처럼 군다.

푸는 법은 compose에 같은 매핑을 적는 것이다. 컨테이너가 뜰 때 그 줄이 컨테이너의 /etc/hosts에 들어간다.

services:
  gitlab:
    extra_hosts:
      - "argocd.cgv.lan:192.168.0.240"

여기는 이름만 적을 수 없다. hosts 파일이 하는 일이 이름을 IP로 바꾸는 것이라 IP가 따라 붙는다. 앞의 허용 목록과 성격이 갈린다.

GitLab 허용 목록      "이 이름으로 나가는 건 허용"        이름만
compose extra_hosts   "이 이름은 이 IP 다"              이름 + IP

그래서 이 줄은 임시다. 데스크탑 hosts 두 줄과 같은 처지로, 이름 푸는 자리를 손으로 채운 것이다. 내부 DNS가 서면 컨테이너도 그 DNS에 물어보면 되니 이 줄은 없어진다.

셋 — 그 주소는 로그인을 안 묻는다

브라우저로 argocd.cgv.lan을 열면 로그인 화면이 뜬다. 그런데 같은 주소라도 /api/webhook 경로만은 로그인을 안 묻는다. 요청 둘을 나란히 놓으면 보인다.

GET  /applications HTTP/1.1          브라우저가 화면을 열 때
Host: argocd.cgv.lan
Cookie: argocd.token=eyJhbGci...     ← 로그인해서 받은 것

POST /api/webhook HTTP/1.1           GitLab 이 알릴 때
Host: argocd.cgv.lan
X-Gitlab-Token: a3f9c2...            ← 공유 비밀
{ "ref": "refs/heads/main", ... }

아래에는 쿠키가 없다. GitLab에는 ArgoCD 계정이 없어서 받아 둘 쿠키도 없다. 그래서 ArgoCD는 /api/webhook 경로에서 쿠키를 찾지 않는다 — 찾는다면 GitLab이 보낸 요청이 전부 로그인 화면으로 돌아가고 webhook은 성립하지 않는다.

쿠키를 안 보니 그 자리가 열려 있다. 주소를 아는 쪽이면 누구나 같은 POST를 흉내낼 수 있다. 받아서 하는 일은 "저장소를 다시 읽어라" 하나뿐이라 배포 내용이 바뀌지도 저장소 자격이 새지도 않고, 최악이 반복 요청으로 repo-server에 부하를 주는 정도다. 그래서 안 걸어도 webhook은 돈다.

여기에 값 하나를 걸어 좁힌다. 무작위 값을 하나 만들어 GitLab 폼과 ArgoCD 양쪽에 같은 것을 넣는다. GitLab이 요청마다 그 값을 X-Gitlab-Token에 실어 보내고, ArgoCD는 자기가 가진 것과 같은지만 본다. 쿠키 대신 볼 줄을 하나 정해 둔 셈이다.

쿠키 — 로그인한 사람. 권한이 따라온다.
X-Gitlab-Token — 아는 쪽에서 온 요청. 권한은 안 따라온다.

이 편에서 만든 자격이 하나 더 있어 헷갈리기 쉬운데, 서로 다른 물건이다.

deploy token       GitLab 이 발급.  ArgoCD 가 저장소를 읽을 때 쓴다
                   ArgoCD → GitLab

webhook 공유 비밀    우리가 만들어 양쪽에 같게 넣는다
                   GitLab → ArgoCD

지금 위험이 큰 것은 아니다. 사설망 안이고 요청이 시키는 일도 하나뿐이다. 그래도 넣는 것은 14부 때문이다 — 클러스터를 밖으로 열 때 비밀 없는 열린 엔드포인트가 남아 있으면 그 자리로 다시 돌아와야 한다. 지금 드는 것은 봉인본 한 장과 문서 세 곳이다.

비밀을 argocd-secret 에 얹는다

argo-cd 차트에 configs.secret.gitlabSecret 칸이 있어서 값을 넣으면 차트가 argocd-secret에 담아 준다. 그런데 values 파일은 평문이고 이 저장소는 GitHub로 미러된다. 이 칸은 비워 두고 봉인해서 넣는데, 거기서 제약이 하나씩 딸려 나온다.

건다

1  비밀을 만들어 봉인하고 커밋한다        argocd-secret 에 한 칸
2  GitLab Admin 에서 사설망 차단을 푼다   허용 목록에 이름으로
3  compose 에 extra_hosts 를 넣고 다시 올린다
4  프로젝트 Webhooks 에 등록하고 Test 를 누른다
5  커밋 하나로 반영 시간을 잰다

8. 걸고, 대조한다

8.1 다섯 단계를 실제로

1 — 비밀을 만들어 봉인한다

값은 아무 난수면 된다. 양쪽에 같기만 하면 되는 것이라 의미 있는 문자열일 필요가 없다.

openssl rand -hex 32

이 값을 GitLab 폼에도 넣어야 하니 봉인이 끝나도 지우지 않는다. 봉인은 낱개 스크립트로 한다.

./seal-one.sh -a sealedsecrets.bitnami.com/patch=true argocd-secret argocd

키를 물으면 webhook.gitlab.secret, 값에 위의 난수를 넣는다. 값 칸은 화면에 안 뜨고 글자 수만 나온다. 나온 봉인본을 커밋해 머지하면 GitOps가 배달한다.

여기서 한 번 걸렸다. 컨트롤러가 거부했다.

failed update: Resource "argocd-secret" already exists and is not managed by SealedSecret

patch 애노테이션을 봉인본에 적었는데도 그랬다. 원인은 컨트롤러가 그 애노테이션을 봉인본이 아니라 클러스터에 이미 있는 Secret에서 읽기 때문이다.

if !IsControlledBy(secret, ssecret) && !isAnnotatedToBeManaged(secret)
                                    && !isAnnotatedToBePatched(secret)

닭과 달걀이다. 봉인본이 Secret을 고쳐야 애노테이션이 붙는데, 애노테이션이 붙어 있어야 고칠 수 있다. argocd-secret은 argo-cd 차트가 먼저 만들어 둔 것이라 여기 걸린다.

처음 한 번만 손으로 붙이면 풀린다.

kubectl -n argocd annotate secret argocd-secret sealedsecrets.bitnami.com/patch=true

한 번 통과하고 나면 봉인본의 애노테이션이 Secret에 남아 이후로는 계속 통과한다. 저장소 자격 한 장을 root-app.sh 전에 손으로 apply하는 것과 같은 성격의 선행 단계이고, 계약 문서에 그렇게 적어 뒀다.

붙이고 나서 키가 넷이 됐다. 기존 셋이 살아남은 것이 patch가 일했다는 증거다.

admin.password          ← 살아남음
admin.passwordMtime     ← 살아남음
server.secretkey        ← 살아남음
webhook.gitlab.secret   ← 새로 얹힘

2 — GitLab 이 사설 IP 로 나가게 허용한다

Admin → Settings → Network → Outbound requests. 여는 방법이 둘인데 범위가 다르다.

Allow requests to the local network from webhooks    사설망 전체가 열린다
allowlist 에 주소 하나                                그 주소만 열린다

뒤를 골랐다. 그리고 허용 목록에는 IP가 아니라 이름을 적었다 — argocd.cgv.lan. 이 목록은 도메인 이름도 받으므로, 나중에 그 이름이 가리키는 IP가 바뀌어도 이 설정은 손댈 것이 없다.

Allow requests to the local network from system hooks는 기본이 켜짐인데 껐다. system hook은 관리자용이라 프로젝트 webhook과 다른 물건이고, 하나도 안 쓰고 있다.

3 — GitLab 컨테이너가 그 이름을 풀게 한다

argocd.cgv.lan은 데스크탑 hosts 파일에만 있는데, GitLab은 그 데스크탑에서 도는 컨테이너라 그 파일을 안 읽는다. 컨테이너 안의 /etc/hosts에는 그 줄이 없어서 이름을 못 풀고 출발조차 못 한다.

compose에 같은 매핑을 적으면 컨테이너가 뜰 때 그 줄이 들어간다.

services:
  gitlab:
    extra_hosts:
      - 'argocd.cgv.lan:192.168.0.240'

다시 올리고 컨테이너 안에서 확인한다. 이름이 풀리는지와 그 주소가 실제로 응답하는지는 별개라 둘 다 본다.

docker exec gitlab getent hosts argocd.cgv.lan
#   192.168.0.240   argocd.cgv.lan

docker exec gitlab curl -s -o /dev/null -w "%{http_code}\n" http://argocd.cgv.lan/
#   200

200이 나오면 컨테이너에서 Traefik을 지나 argocd-server까지 통한 것이다. 여기까지 확인하고 등록하면, 실패했을 때 원인이 GitLab 설정 하나로 좁혀진다.

4 — webhook 을 등록한다

프로젝트 → Settings → Webhooks.

URL             http://argocd.cgv.lan/api/webhook
Secret token    1 에서 만든 그 값
Trigger         Push events

토큰 칸이 둘인데 Secret token을 쓴다. GitLab은 그 칸에 "not recommended"를 붙여 두고 Signing token을 권한다 — 값을 그대로 보내지 않고 서명만 보내는 방식이라 더 안전하다. 그런데 ArgoCD가 검사하는 것은 X-Gitlab-Token 헤더 하나뿐이다.

tokenHash := sha512.Sum512([]byte(r.Header.Get("X-Gitlab-Token")))
if subtle.ConstantTimeCompare(tokenHash[:], hook.secretHash[:]) == 0 {
    return nil, ErrGitLabTokenVerificationFailed
}

서명 헤더는 아예 보지 않으므로 선택지가 없다. 권장되지 않는 쪽을 고른 것이고, 그 이유가 우리 판단이 아니라 받는 쪽의 제약이다.

저장하고 Test → Push events를 누르면 200이 온다. 값이 틀렸으면 403이므로, 이 200은 토큰까지 맞았다는 뜻이다.

5 — 반영 시간을 잰다

커밋 하나를 main에 넣고 ArgoCD 로그를 본다.

22:11:43 +09:00   머지 커밋
13:11:46 UTC      refreshing app 'argocd' from webhook
                  refreshing app 'root'  from webhook
                  ...  App 스물한 개 전부

3초다. 폴링이었으면 최대 3분 기다렸을 자리다.

로그에 하나 더 찍혔다. 머지되면서 소스 브랜치가 삭제됐는데 그때도 이벤트가 왔고, ArgoCD가 이렇게 넘겼다.

Received push event repo: .../cgv-infra, revision: fix/sealedsecret-patch-bootstrap,
                          touchedHead: false

main이 안 바뀌었으니 아무것도 안 한다는 판단이다. webhook은 push마다 오지만 그중 반영이 필요한 것만 걸러 낸다.

8.2 닫는 조건과 대조

이 편이 열 때 잡은 자리는 둘이었다.

push 마다 최대 3분을 기다린다        →  3초.  webhook 이 알리고 폴링은 그물로 남는다
ArgoCD 가 port-forward 로만 열린다   →  argocd.cgv.lan.  Grafana 도 같이 열렸다

둘 다 닫혔다. 그 사이에 원본도 옮겨졌다 — Application 스물한 개의 repoURL이 전부 데스크탑 GitLab을 가리키고, ArgoCD는 자기 설정까지 커밋으로 받는다.

8.3 무엇이 함께 열렸나

문을 내면 그만큼 열린다. 이 편에서 늘어난 것을 적어 둔다.

ArgoCD와 Grafana의 로그인 화면이 사설망에 드러났다. 전에는 kubeconfig가 없으면 화면을 볼 수도 없었는데, 이제 .240에 닿을 수 있으면 누구나 로그인 화면까지 온다. 비밀번호를 반복해 넣어 볼 대상이 생긴 것이다.

신원을 확인하는 주체가 바뀌었다. 쿠버네티스가 인증서와 RBAC으로 사람마다 권한을 가르던 자리를, ArgoCD와 Grafana의 로컬 계정 하나가 대신한다.

그 비밀번호가 평문으로 오간다. 전 구간이 HTTP라 같은 망에서 패킷을 보면 읽힌다. webhook의 공유 비밀도 매 요청 헤더에 값 그대로 실려 간다.

GitLab이 사설망으로 나가는 것을 의도적으로 풀었다. 다만 전체가 아니라 이름 하나만 열었고, 그 이름은 공인 DNS에 존재하지 않는다.

앞의 셋은 TLS를 붙이면 성격이 달라진다. 14부에서 Traefik 한 곳에 인증서를 올리고, 망을 갈라 관리용 주소를 밖에서 못 닿게 두고, 방화벽으로 들어오는 쪽을 막는다. 지금은 사설망 안이라는 것 하나에 기대고 있는 상태이고, 그게 방어의 전부라는 것을 알고 있는 것과 모르고 있는 것이 다르다.

9. 다음

지금 클러스터에서 앱 셋(frontend·booking·queue)만 Degraded다. 매니페스트도 서 있고 Ingress 규칙도 있는데 이미지가 없다. registry.cgv.local을 가리키고 있고 그런 레지스트리가 아직 없어서 ImagePullBackOff에서 멈춰 있다.

10부가 그 구간을 잇는다.

지금    소스 → GitLab → (끊김) → 클러스터
10부    소스 → GitLab → CI 가 빌드 → 레지스트리 → 클러스터

세울 것은 셋이다. 러너가 CI를 돌릴 자리고, 레지스트리가 나온 이미지를 둘 자리고, 파이프라인이 그 둘을 잇는 규칙이다. 레지스트리는 GitLab 내장을 쓴다 — Harbor를 따로 세우지 않는 것과 같은 이유로, 이미 있는 것을 쓰면 자격과 백업이 한 자리에 모인다.

노트북 홈서버 k3s 구축기 - 8. 관측 파이프라인

hsb_02 — Sun, 2 Aug 2026 17:56:04 +0900

0. 이어받기

7부 끝에서 토대와 워크로드가 다 섰다. 노드 세 대가 Ready, 파드 69개, 데이터 디스크 열 장이 전부 Bound. 플랫폼(Calico·MetalLB·Traefik·cert-manager·sealed-secrets·ArgoCD)과 데이터 계층(MySQL·Redis·Kafka), 관측 스택(Mimir·Loki·Tempo·Grafana·Alloy·MinIO)이 올라왔고, 손을 떼고 GitOps에 넘겼다.

두 자리가 비어 있다.

앱은 아직. queue·booking·frontend의 Deployment·Service는 클러스터에 있는데, 이미지를 받아올 레지스트리가 없어 ImagePullBackOff다. 파드 69개 중 4개가 그 상태고, 레지스트리는 10부에서 세운다.
Grafana 안이 백지다. 대시보드가 한 장도 없다.

여기서 채울 건 이렇다 — 관측이 실제로 흐르는지 열어 확인하고, 막힌 데를 뚫고, 그 파이프라인이 다시 막히는 걸 알아채는 계기판을 세운다. 인프라 자체를 들여다보는 대시보드는 그 위에 서는 것이라 다음 편이다.

열어 볼 파이프라인은 이런 모양이다.

[긁는 쪽]                    [담는 쪽]                    [보는 쪽]

Alloy (노드마다) ─ 메트릭 ──▶ Mimir  ┐
                 ─ 로그   ──▶ Loki   ├─ 몸통은 MinIO(S3)로 ──▶ Grafana
                 ─ 트레이스 ─▶ Tempo  ┘

긁는 쪽과 담는 쪽의 구조를 먼저 본다. 담는 쪽을 모르면 "값이 안 보인다"가 수집 문제인지 저장 문제인지 가를 수가 없다. 그리고 그 전에 배포판(k3s)의 생김새부터 본다 — 뒤에서 메트릭이 그 구조를 그대로 비춘다.

앱이 없다는 사실이 이 편에서 볼 신호를 정한다. 지금 흐르는 것은 앱 트래픽이 아니라 인프라 자신이 내는 신호다 — 노드 자원, 컨트롤플레인 상태, 컨테이너 실사용, 그리고 관측 스택이 자기 자신에 대해 내는 지표.

7부가 남긴 숙제도 하나 걸려 있다. 노드 자원 예약(kube-reserved)을 2Gi로 올려 잡기로 했는데 설정 파일에만 반영하고 노드에는 아직 안 넣었다. 반영하려면 노드를 한 대씩 재시작해야 하고, 앱이 올라와 실사용을 다시 잰 뒤 한 번에 하기로 미뤄 뒀다.

1. k3s는 어떻게 생겼나

1.1 컨트롤플레인 넷이 프로세스 하나 안에 있다

kubeadm으로 세운 클러스터는 컨트롤플레인 컴포넌트가 각각 스태틱 파드로 뜬다. apiserver 파드, scheduler 파드, controller-manager 파드, etcd 파드 — 넷이 서로 다른 컨테이너이자 서로 다른 프로세스다.

k3s는 이 넷을 하나로 합쳤다.

[프로세스] k3s server   (systemd 유닛 하나)
    ├ apiserver           (고루틴)
    ├ etcd (embedded)     (고루틴)
    ├ scheduler           (고루틴)
    ├ controller-manager  (고루틴)
    ├ kubelet             (고루틴)
    └ kube-proxy          (고루틴)

세 노드 전부 server 역할이라 이 프로세스가 노드마다 하나씩, 클러스터에 셋 있다.

왜 합쳤나. k3s는 저사양·엣지·단일 바이너리를 노리고 만든 배포판이다. 컴포넌트를 프로세스로 나누면 각각 컨테이너 이미지와 매니페스트가 필요하고, 기동 순서와 인증서 배선을 따로 맞춰야 한다. 그걸 하나로 합치면 바이너리 하나 내려받아 systemd 유닛 하나 띄우는 것으로 클러스터가 선다. 설치가 단순해지는 대신 뒤에 나오는 성질들이 따라온다.

이 합침은 자원 계산에 이미 영향을 줬다. kubelet은 자기가 띄운 파드만 셀 수 있다. kubeadm 쪽 컨트롤플레인은 스태틱 파드라 kubelet이 띄우고 관리하므로 그 사용량이 파드 몫으로 잡히고, 노드의 할당 가능량에서도 그만큼 빠진다.

k3s server는 파드가 아니라 systemd 프로세스다. kubelet의 셈에 아예 안 들어온다. 그래서 그 몫을 kube-reserved로 직접 떼어 두지 않으면, 실제로는 쓰이고 있는데 스케줄러 쪽에서는 비어 있는 공간으로 남아 파드에게 배정된다. 실측으로 노드당 1.5–1.8GiB를 쓰고 있어 예약을 2Gi로 잡았다.

같은 이유로 PriorityClass로 컨트롤플레인을 보호할 수도 없다. 파드가 아니니 eviction 대상 목록에 없다.

1.2 나머지는 전부 파드다

컨트롤플레인 밖의 것은 전부 컨테이너로 뜬다. 즉 각각 별개 프로세스다.

계층	무엇이 떠 있나	배치
플랫폼	Calico · MetalLB · Traefik · cert-manager · sealed-secrets · ArgoCD	노드에 분산
데이터	MySQL · Redis 3 · Kafka(Strimzi)	디스크 라벨로 고정
관측 — 수집	Alloy	DaemonSet, 노드마다 1
관측 — 저장	Mimir(인제스터 3 + 컴포넌트 8) · Loki 1 · Tempo 1 · MinIO 1	인제스터는 노드마다 1
관측 — 조회·부가	Grafana · kube-state-metrics · node-exporter	node-exporter는 DaemonSet
앱	queue 2 · booking · frontend	오브젝트만, 컨테이너 미기동

배치가 아무 데나 앉은 것은 아니다. 노드마다 용도 라벨(cgv.io/data = db · obs · obj)을 붙여 뒀고, 디스크를 쓰는 것은 그 디스크가 있는 노드에 고정된다. MySQL은 데이터 디스크가 있는 노드로, Loki·Tempo는 각자 WAL 디스크가 있는 노드로, MinIO는 100G 디스크가 있는 노드로 간다.

Mimir 인제스터만 다르다. 세 대가 노드에 하나씩 앉는다. 노드마다 인제스터용 WAL 디스크를 한 장씩 잘라 둔 것이 그래서다. 왜 이렇게 흩어 뒀는지는 담는 쪽 구조를 볼 때 이어서 나온다.

여기서 컨트롤플레인과 갈리는 성질이 생긴다. 파드는 각자 프로세스라 자기 메모리를 갖고, 컨테이너 단위로 limit을 걸 수 있고, 하나가 죽어도 옆이 안 죽는다. 합쳐 놓은 넷은 그 반대다.

1.3 합쳐 놓은 대가

Go에서 고루틴이 패닉하고 아무도 받지 않으면 프로세스 전체가 죽는다. 그래서 "apiserver만 죽고 kubelet은 산다"가 k3s에는 없다. 죽으면 그 노드의 컨트롤플레인이 통째로 나간다.

	kubeadm(스태틱 파드)	k3s(한 프로세스)
컴포넌트 하나가 패닉	그 컨테이너만 재시작	넷이 함께 종료
메모리 폭주	해당 컨테이너만 OOMKilled	프로세스 전체 OOM
컴포넌트별 메모리 limit	걸 수 있다	못 건다
재시작 범위	죽은 것 하나	넷 전부 + etcd WAL 재생

여기에 관측 쪽으로 바로 걸리는 것이 하나 더 있다. 컴포넌트별 자원을 따로 잴 수가 없다. 프로세스가 하나라 "메모리를 apiserver가 먹었나 kubelet이 먹었나"가 안 갈린다. 프로세스 사용량 지표는 k3s server 하나의 값으로만 나온다. 대시보드를 세울 때 이 한계를 전제로 깔아야 한다.

그래서 격리를 컴포넌트가 아니라 노드 단위로 만든다. 세 대를 전부 server로 두고 etcd를 3-member로 묶은 것이 그 대응이다. 한 노드의 k3s server가 통째로 죽어도 남은 두 대로 쿼럼이 유지되고 apiserver도 계속 답한다. 같은 이유로 설정을 바꿔 재시작할 때 세 노드를 동시에 만지지 않는다 — 한 대씩 순차로 돌린다. 동시에 내리면 쿼럼이 끊긴다.

이 합침은 뒤에서 한 번 더 나타난다. 자원과 장애에서만이 아니라 메트릭에서도 넷이 하나로 묶여 있다.

2. Alloy는 무엇을 어떻게 긁나

2.1 "긁는다"가 무슨 뜻인가

메트릭을 내는 쪽은 HTTP 주소를 하나 열어 둔다. 주소:포트/metrics로 요청하면 그 순간의 값이 텍스트로 돌아온다. 한 줄이 값 하나다.

apiserver_request_total{verb="GET",resource="pods",code="200"} 41823
node_cpu_seconds_total{cpu="0",mode="idle"} 918273.44

수집기(alloy)가 하는 일은 하나다. 그 주소로 주기적으로 요청을 보내고, 돌아온 텍스트를 저장소로 넘긴다. 이 한 번의 요청·응답을 스크레이프(scrape)라고 부른다.

여기서 뒤까지 계속 쓰는 용어 둘이 갈린다.

시리즈 — 메트릭 이름 하나에 라벨 조합 하나가 붙은 것. 위 예에서 verb="GET"과 verb="LIST"는 서로 다른 시리즈다.
샘플 — 그 시리즈의 한 시점 값 하나. 시리즈 하나를 15초마다 긁으면 15초마다 샘플이 하나 생긴다.

up{~}

그리고 수집기인 Alloy는 스크레이프마다 값을 하나 직접 만들어 붙인다.

up{job="kubelet", instance="k3s-1"} 1     ← 붙는 데 성공
up{job="kubelet", instance="k3s-2"} 0     ← 실패

up은 긁히는 쪽이 내는 값이 아니다. 수집기가 성공·실패를 판정해 만드는 값이라, 대상이 죽어도 0으로 남는다. 그래서 "무엇을 긁고 있고 그중 뭐가 실패하나"를 이 하나로 훑는다.

2.2 Alloy는 노드마다 하나씩 있다

Alloy는 DaemonSet이라 노드마다 파드 하나씩, 셋이 돈다.

문제는 셋이 각자 전부를 긁으면 같은 값이 세 벌 들어온다는 것이다. 대상 목록은 클러스터 단위로 발견되므로, 세 파드가 같은 목록을 보고 각자 다 긁는다.

그래서 clustering을 켠다. 세 파드가 서로의 존재를 알아본 뒤 대상 하나하나를 누가 맡을지 나눠 갖는다. 결과적으로 대상은 셋 중 한 파드만 긁고, 어느 파드가 긁었든 값은 같은 저장소로 간다. 파드가 하나 죽으면 그 몫이 남은 둘에 다시 분배된다.

로그와 이벤트도 같은 장치를 쓴다. 쿠버네티스 이벤트는 노드가 아니라 클러스터 단위 스트림이라, 세 파드가 각자 읽으면 같은 이벤트가 세 벌 적재된다. 그래서 이벤트도 한 파드만 담당하게 나눠 둔다.

2.3 지금 무엇을 긁고 있나

수집 목록은 두 갈래로 선언돼 있다.

① Alloy 설정에 주소를 직접 적은 것

대상	주소	job	타깃 수
kubelet	각 노드IP `:10250/metrics`	`kubelet`	3 (노드마다)
cAdvisor	각 노드IP `:10250/metrics/cadvisor`	`cadvisor`	3
apiserver	각 노드IP `:6443/metrics`	`k3s-apiserver`	3
MinIO	`minio.observability.svc:9000/minio/v2/metrics/cluster`	`minio`	1

노드 주소를 손으로 적지는 않는다. 설정에 적힌 실제 모양이 이렇다.

discovery.kubernetes "nodes" { role = "node" }        // ① 노드 목록을 받아온다

discovery.relabel "apiserver" {                       // ② 그 목록을 스크레이프 대상으로 고쳐 쓴다
  targets = discovery.kubernetes.nodes.targets
  rule {
    source_labels = ["__meta_kubernetes_node_address_InternalIP"]
    replacement   = "$1:6443"
    target_label  = "__address__"                     //    내부 IP 뒤에 :6443을 붙여 주소로
  }
}

prometheus.scrape "apiserver" {                       // ③ 그 주소를 실제로 긁는다
  targets      = discovery.relabel.apiserver.output
  job_name     = "k3s-apiserver"                      //    붙일 job 라벨
  metrics_path = "/metrics"
  scheme       = "https"
  bearer_token_file = "/var/run/secrets/kubernetes.io/serviceaccount/token"
  tls_config { insecure_skip_verify = true }          //    노드 인증서가 자체 서명이라 이름 검증 생략
  forward_to = [prometheus.remote_write.mimir.receiver]   // ④ 받은 값을 Mimir로 보낸다
  clustering { enabled = true }
}

세 단계로 읽으면 — 목록을 받고(①), 주소로 고쳐 쓰고(②), 긁어서 보낸다(③④). 노드가 늘면 ①이 알아서 늘어나므로 대상도 따라 는다.

가운데의 relabel이 뒤에서 다시 나온다. 이름 그대로 라벨을 고쳐 쓰는 단계인데, 하는 일이 두 가지다. 하나는 여기처럼 대상 주소를 만드는 것이고, 다른 하나는 저장소로 보내기 직전에 라벨을 바꾸거나 시리즈를 걸러 내는 것이다. 수집 단계에서 무언가를 덜어 내려면 손댈 자리가 이 relabel뿐이다.

cAdvisor는 kubelet에 내장된 부분이다. 별도 프로세스가 아니라 kubelet 코드 안에 들어 있고, 컨테이너 런타임이 만든 컨테이너의 실사용을 커널의 cgroup에서 직접 읽어 낸다. 그래서 주소는 kubelet과 같은 :10250이되 경로가 다르다.

메트릭이 아닌 것도 이 갈래에 있다.

파드 stdout → Loki — 컨테이너가 찍는 로그
쿠버네티스 이벤트 → Loki(k8s-events) — 파드가 왜 죽었는지는 컨테이너 로그가 아니라 이벤트에 남는다. 이벤트는 약 한 시간 뒤 사라지므로 담아 둬야 사후 추적이 된다
OTLP 수신 → Tempo — :4317·:4318로 트레이스를 받아 넘긴다. 보내는 앱이 있어야 채워진다

② ServiceMonitor·PodMonitor로 자동 발견되는 것

이쪽은 Alloy 설정에 이름이 없다. 각 컴포넌트가 자기 옆에 ServiceMonitor라는 오브젝트를 두면 Alloy가 그것을 주워 수집 대상으로 바꾼다. 대부분의 차트가 그 오브젝트를 자동으로 같이 배포한다.

대상	주소	타깃 수
etcd	각 노드IP `:2381/metrics`	3
node-exporter	파드(노드마다)	3
kube-state-metrics	파드 1	1
Redis exporter	파드 3	3
Mimir 각 컴포넌트 · Loki · Tempo · Grafana · Alloy 자신	각 파드	각 1
앱 queue · booking	파드	오브젝트만 있어 발견은 된다

etcd만 사정이 다르다. ServiceMonitor는 Service를 보고 대상을 찾는데, etcd는 파드가 아니라 노드 프로세스라 가리킬 Service가 없다. 그래서 셀렉터 없는 Service를 만들고, 거기 붙는 Endpoints에 노드 IP 셋을 직접 적어 실체 없는 대상을 세웠다.

2.4 왜 방법이 갈렸나

갈림은 대상의 성질 두 가지에서 나온다 — 가리킬 Service가 있는가, 인증이 필요한가.

대상	Service	인증	그래서
kubelet · cAdvisor · apiserver	없음(노드 프로세스)	필요	Alloy 설정에 직접
etcd	없음(노드 프로세스)	불필요(`:2381` 평문)	Service를 손으로 만들어 ServiceMonitor
node-exporter · KSM · Redis · LGTM	있음(파드)	불필요	차트가 붙인 ServiceMonitor 그대로
MinIO	있음(파드)	불필요	차트가 ServiceMonitor 대신 Probe로 내서 직접 지목

apiserver가 직접 설정으로 간 이유를 한 겹 더 본다. :6443/metrics는 그냥 요청하면 막는다. apiserver는 그 특징으로 요청 헤더에 서비스어카운트 토큰을 실어야 값을 준다. 파드는 뜰 때 그 토큰을 파일로 받으므로, 수집 설정에 적을 것은 "그 파일을 읽어 헤더에 실어라" 하나다.

Alloy 설정에는 그 칸이 있어 한 줄로 끝난다. ServiceMonitor에는 인증을 적는 칸 둘이 다 막혀 있다.

파일 경로를 적는 칸 — 없어지는 방향이라 CRD 버전에 따라 무시되거나 거부된다. ServiceMonitor는 어느 네임스페이스에서나 만들 수 있는 오브젝트라, 거기에 "수집기 파드의 이 경로를 읽어라"를 적게 두면 토큰이 아닌 파일도 읽어 밖으로 내보낼 수 있다.
Secret을 참조하는 칸 — 그러려면 Alloy가 그 Secret을 직접 읽어야 하는데, 그 권한은 RBAC에서 빼뒀다. 주면 데이터 계층의 DB 시크릿, 앱 네임스페이스의 앱 시크릿까지 전부 읽힌다.

3. Mimir는 어떻게 담나

3.1 무엇의 개수를 세는가 — 시리즈와 카디널리티

Mimir가 세고 제한하는 단위가 시리즈다.

node_cpu_seconds_total{node="k3s-1", cpu="0", mode="idle"}     ← 시리즈 하나
node_cpu_seconds_total{node="k3s-1", cpu="0", mode="system"}   ← 라벨 하나만 달라도 다른 시리즈

라벨 값의 가짓수가 곱해지며 시리즈가 는다. 노드 3 × 코어 4 × mode 8이면 이름 하나에 시리즈가 96개다. 이 곱이 부는 정도를 카디널리티라고 부른다.

여기서 뒤에 그대로 걸리는 성질이 하나 있다. 라벨이 하나라도 다르면 값이 같아도 다른 시리즈다. 같은 값을 다른 라벨로 두 번 넣으면 저장 비용이 두 배가 된다.

담는 단위도 하나 짚어 둔다. Mimir는 여러 테넌트를 한 클러스터에 나눠 담도록 만들어졌다. 모든 요청은 X-Scope-OrgID 헤더로 "누구 것인가"를 밝히고, 테넌트마다 저장 공간과 상한이 따로 매겨진다. 이 클러스터는 테넌트를 나누지 않아 전부 하나(anonymous)로 들어간다. 뒤에 나오는 상한이 "테넌트당" 값인 것이 이 때문이고, 테넌트가 하나뿐이라 그 값이 곧 클러스터 전체 값이 된다.

3.2 쓰기 경로 — 들어온 값이 어디에 앉나

Alloy (노드마다)
   │ remote_write
   ▼
mimir-gateway ──▶ distributor
                      │  시리즈마다 해시를 계산해 해시 링에서 담당 인제스터를 찾고
                      │  RF=3이므로 링에서 이어지는 세 대로 복제 전송
                      ▼
              ingester-0   ingester-1   ingester-2      ← 두 대가 받으면 쓰기 성공(quorum)
                      │
                      │  받은 값을 메모리에 들고 있다가 2시간마다 블록으로 만든다
                      ▼
                    MinIO (S3)

mimir-gateway — 모든 요청이 처음 닿는 입구. 쓰기는 distributor로, 조회는 query-frontend로 넘긴다.
distributor — 받은 시리즈를 어디로 보낼지 정하는 문지기. 시리즈 이름·라벨로 해시를 내고 해시 링에서 담당자를 찾는다. 링은 인제스터들이 자기 위치를 등록해 둔 원형 목록이다.
RF(replication factor) = 3 — 시리즈 하나를 인제스터 세 대에 복사해 둔다. 쓰기는 그중 두 대가 받으면 성공으로 친다. 세 대 중 과반이 받았으면 값이 남는다고 보는 것이고, 그래서 한 대가 느리거나 죽어도 쓰기가 멈추지 않는다.
인제스터 — 최근 값을 메모리에 들고 있는 컴포넌트. 2시간마다 그 구간을 블록 파일로 만들어 MinIO에 올린다. 올린 뒤에도 그 블록을 한동안 자기 디스크에 남겨 둔다 — 조회하는 쪽이 새 블록을 발견하고 색인을 내려받을 시간이 필요해서다.
WAL — 메모리에 있는 동안 프로세스가 죽으면 값이 사라지므로, 들어온 값을 영속 디스크에도 순서대로 적어 둔다. 재시작하면 이 기록을 되읽어 메모리 상태를 복원한다. 그래서 인제스터는 디스크를 붙일 수 있는 StatefulSet으로 뜬다.

3.3 읽기 경로 — 조회가 어디를 보나

Grafana ──▶ mimir-gateway ──▶ query-frontend ──▶ query-scheduler ──▶ querier
                                                                        │
                                            최근 구간 ────────────────┤──▶ ingester (메모리)
                                            지난 구간 ────────────────┘──▶ store-gateway ──▶ MinIO

조회는 한 군데를 보지 않는다. 최근 두 시간 남짓은 아직 MinIO에 없고 인제스터 메모리에만 있으므로, querier가 인제스터와 저장소를 같이 뒤져 합쳐 돌려준다.

각 컴포넌트가 맡는 일은 이렇게 나뉜다.

query-frontend · query-scheduler — 들어온 쿼리를 시간 구간으로 쪼개고 줄 세워 querier에게 나눠 준다. 무거운 쿼리 하나가 전체를 막지 않게 하는 층이다.
querier — 실제로 값을 모아 계산하는 쪽. 인제스터와 store-gateway 양쪽에 물어본다.
store-gateway — MinIO에 있는 블록들의 색인을 들고 있다가, 지난 구간을 물으면 어느 블록을 읽어야 하는지 찾아 준다.
compactor — 인제스터 세 대가 2시간마다 각자 올린 블록을 뒤에서 병합한다. 복제본이 셋이라 같은 구간의 블록도 셋 올라오는데, 그걸 합쳐 조회할 때 뒤질 파일 수를 줄인다.

읽기에도 quorum이 걸린다. 인제스터가 재시작하면 멈춰 있던 동안의 값이 그 대에만 비므로, 한 대만 물어보면 구멍 난 답을 받을 수 있다. 그래서 RF가 3이면 읽을 때도 두 대에서 받아 맞춰 본다.

3.4 그래서 인제스터만 HA가 필요하다

이 구조에서 각 구간의 안전도가 다르다.

구간	어디에 있나	잃으면
오래된 값	MinIO(오브젝트 스토리지)	저장소가 지킨다. 컴포넌트가 죽어도 데이터는 남는다
최근 값	인제스터 메모리(+ WAL)	그 인제스터가 죽으면 그 구간이 빈다

store-gateway·compactor·querier는 죽어도 MinIO에 있는 것을 다시 읽으면 된다. 상태를 자기가 들고 있지 않다. 반면 인제스터는 아직 아무 데도 안 올라간 최근 구간을 자기 메모리에 들고 있는 유일한 지점이다.

WAL이 이 구간을 지키긴 하지만 한계가 분명하다. WAL은 프로세스가 죽었다 살아나는 것을 복구할 뿐, 그 디스크가 있는 노드 자체가 나가면 같이 못 쓴다. 그리고 복구되는 동안은 조회가 안 된다.

그래서 최근 구간의 가용성은 WAL이 아니라 복제로 확보한다. 이 편에서 계속 나오는 RF=3이 그것이다.

3.5 노드마다 인제스터를 하나씩 — 그리고 왜 monolithic이 아닌가

Mimir는 두 가지 배포 모드를 제공한다.

모드	성격	문서 권장
monolithic	모든 컴포넌트를 프로세스 하나로	시작·개발 환경
microservices	컴포넌트를 각각 별도 프로세스로	프로덕션

자원만 보면 dev에는 monolithic이 맞다. 파드 하나면 되고 설정 항목도 적다. 그런데 이 클러스터는 microservices로, 인제스터를 세 대 띄워 노드마다 하나씩 뒀다. 이유가 둘이다.

monolithic으로는 최근 구간을 복제할 수 없다. 프로세스 하나에 전부 들어 있으면 그 프로세스가 죽을 때 인제스터도 같이 죽고, 메모리에만 있던 최근 구간이 통째로 빈다. 복제를 하려면 인제스터가 독립된 복제본 여럿으로 존재해야 한다.
dev를 stg·prd와 같은 구조로 두는 것이 이 홈랩의 목적이다. 규모만 낮추고 구조는 같게 가져가야, 여기서 잰 값이 위 환경의 스펙을 정하는 근거가 된다. 인제스터를 노드마다 두는 것은 Kafka 브로커나 Redis 복제본을 노드에 흩어 두는 것과 같은 결이다 — 한 노드를 잃어도 나머지로 버티게 만드는 배치.

대가도 분명하다. 파드 수가 늘고(Mimir만 11개), 그만큼 자원을 더 쓴다. 이 규모에 과한 구성이라는 점은 인정하고 가는 선택이다.

3.6 그 구조가 만드는 제약 — 시리즈 상한

인제스터가 최근 값을 메모리에 든다는 것은, 메모리가 유한 자원이라는 뜻이다. 카디널리티가 폭주하면 메모리를 끝없이 먹다가 커널에 종료된다(OOMKilled).

그 전에 끊는 장치가 시리즈 상한이다. 상한에 닿으면 새 시리즈만 거절하고 기존 시리즈는 계속 받는다. 크래시로 통째로 잃는 대신 새로 들어오려는 것만 막는다. 노드 메모리가 마를 때 커널 OOM 전에 kubelet이 파드를 내보내는 것과 같은 결의 가드레일이다.

값은 max_global_series_per_user이고, 차트에 따로 지정하지 않아 Mimir 기본값 150,000이 그대로 걸려 있다.

이 값이 세는 대상은 "복제 전, 테넌트 전체의 고유 시리즈" 수다. 인제스터 한 대가 지는 몫은 이렇게 나온다.

인제스터당 = 전역 상한 × RF ÷ 인제스터 개수
           = 150,000 × 3 ÷ 3
           = 150,000

RF가 3인데 인제스터도 정확히 3대라 모든 시리즈가 세 대 전부에 복제된다. 그래서 전역 상한과 인제스터당 보유량이 같은 값이 된다. 세 대가 15만씩 나눠 갖는 게 아니라, 같은 15만을 세 벌 복사해 각자 다 들고 있다.

4. 그런데 절반만 흐른다

앱은 하나도 안 떠 있다. 지금 들어오는 것은 인프라 자신이 내는 신호뿐인데, 그것만으로 Mimir의 시리즈 상한을 넘어선다.

4.1 증상 — 도착한 것과 안 온 것이 갈린다

Grafana에서 무엇이 들어와 있는지 훑으면 목록이 고르지 않다.

대상	상태
kube-state-metrics	통째로 없음 (`kube_pod_info` 0건)
node-exporter	세 노드 중 한 대분만
kubelet · cAdvisor · apiserver	각각 한 노드분만
MinIO	원천이 250줄인데 55개만
etcd · Redis	세 노드분 온전

수집기 파드는 셋 다 Running이고 재시작도 없다. 배선이 끊긴 모양은 아니다. 조회를 맡는 mimir-querier만 93분 사이 25번 재시작했다.

그리고 이 상태에서 화면에 에러가 안 뜬다. 쿼리는 정상으로 응답하고 값만 없다. 무언가 버려지고 있다는 신호는 수집기 로그에만 남는다.

4.2 저장소가 상한에 붙어 있다

cortex_ingester_memory_series

인제스터가 나란히 150000이다. 이 값은 "최근에 샘플이 있던 시리즈"가 아니라 인제스터가 지금 메모리에 들고 있는 시리즈 수이고, 상한이 걸리는 대상이 정확히 이것이다.

수집기 로그에도 거절이 주기적으로 찍힌다.

... err-mimir-max-series-per-user (per-user series limit of 150000 exceeded)

밀리는 순서는 선착순이다. 상한에 닿기 전 등록된 시리즈는 계속 받고, 그 뒤에 오는 것만 거절된다.

이게 추정이 아니라는 증거가 나왔다. 노트북 배터리가 나가 클러스터가 통째로 재기동됐는데, 설정을 하나도 안 바꿨는데 도착한 세트가 뒤바뀌었다.

                     재기동 전      재기동 후
k3s-apiserver        약 5만         약 7만 5천
kubelet              약 7만 7천     약 3만
kube-state-metrics       0          약 6천 5백    ← 없다가 전부 들어옴
node-exporter        1노드분        3노드분
────────────────────────────────────────────
인제스터가 든 총량    150,000        150,000      ← 총량은 늘 같다

kube-state-metrics가 고장이었다면 재기동으로 저절로 고쳐질 리 없다. 등록 순서가 다시 섞였을 뿐이다. 차오르는 속도도 그와 맞는다 — 재기동 뒤 30초 만에 150,000에 닿고 그 뒤로 계속 붙어 있다.

죽은 게 아니라 거절이다. 겉보기가 비슷한 OOMKilled과 갈라 둔다. 처방이 반대라서다.

	상한 포화(지금)	OOMKilled
파드 상태	`1/1 Running`, 재시작 거의 없음	`RESTARTS` 상승 · `CrashLoopBackOff`
수집기가 받는 응답	살아 있는 쪽이 400으로 거절	연결 거부 · 타임아웃
`memory_series`	상한 값에 붙어 있음	재시작마다 0에서 다시 오름

OOMKilled이면 컨테이너 메모리 limit을 올려 푼다. 지금은 설정 상한에 걸린 거절이라 limit으로 될 일이 아니다.

4.3 그 15만의 절반이 사본이다

15만을 job별로 쪼갠다 — 아래 숫자는 재기동 전 스냅샷이다.

topk(20, count by (job) ({__name__=~".+", job=~".+"}))

kubelet          약 7만 7천
k3s-apiserver    약 5만          두 job 합이 15만의 약 85%
cadvisor         약 5천 8백
k3s-etcd         약 5천 3백
나머지 전부       약 1만 2천

kubelet과 k3s-apiserver가 시리즈 상한 15만의 대부분을 차지한다. 그런데 job="kubelet" 안을 열면 kubelet 지표가 아니다. 두 job을 각각 열어 나란히 놓는다.

topk(12, count by (__name__) ({job="kubelet"}))
topk(12, count by (__name__) ({job="k3s-apiserver"}))

메트릭 이름	`job="k3s-apiserver"`	`job="kubelet"`
`etcd_request_duration_seconds_bucket`	14,400	5,760
`apiserver_request_duration_seconds_bucket`	11,640	3,672
`apiserver_request_sli_duration_seconds_bucket`	8,558	2,904
`apiserver_watch_list_duration_seconds_bucket`	4,626	1,512
`apiserver_watch_cache_read_wait_seconds_bucket`	3,682	1,428
`apiserver_request_body_size_bytes_bucket`	3,072	1,760
`apiserver_response_sizes_bucket`	2,336	600
`apiserver_watch_events_sizes_bucket`	2,241	783
`apiserver_admission_controller_admission_duration_seconds_bucket`	770	770
`workqueue_queue_duration_seconds_bucket`	964	407

kubelet 주소를 긁었는데 apiserver·etcd·workqueue 지표가 나온다. k3s-apiserver 주소도 마찬가지다 — 두 목록이 같은 이름을 같은 순서로 늘어놓는다. 개수가 다른 것은 두 job에 착지한 노드분이 달라서고, 같은 노드분끼리 만난 항목은 값까지 똑같다(표에서 admission_controller 770, 이 둘만 그렇다).

두 주소가 같은 것을 내고 있다. "메트릭은 포트에 붙어 있는 게 아니라 프로세스에 붙어 있어"서다.

프로그램이 메트릭을 하나 만들면 프로세스 안의 목록에 등록한다.
이 목록을 레지스트리라고 부른다. /metrics 요청이 하는 일은 하나다 — 그 레지스트리를 통째로 텍스트로 찍어 보낸다. 그러니 포트가 달라도 읽는 레지스트리가 같으면 응답이 같다.
컨트롤플레인 넷이 한 프로세스(k3s)라 그 레지스트리가 하나다. apiserver·kubelet·scheduler·controller-manager가 전부 그 하나에 등록하고, :6443과 :10250이 각자 같은 그것을 찍어 보낸다.

원천을 직접 받아 대조하면 그대로 나온다.

k3s-1  :10250/metrics    72,093 줄
k3s-1  :6443/metrics     72,093 줄

메트릭 이름 종류      536 / 536
한쪽에만 있는 이름      0            ← 이름 집합이 완전히 같다

같은 프로세스라는 것이 값으로도 보인다.

process_resident_memory_bytes{job=~"kubelet|k3s-apiserver"}

k3s-3  job="k3s-apiserver"    1,125 MB
k3s-3  job="kubelet"          1,130 MB     ← 같은 프로세스, 스크레이프 시점만 다르다

이 1.1GB는 k3s server 프로세스 하나의 값이다. 노드 예약(2Gi)의 근거로 쓴 1.5–1.8GiB는 컨테이너 런타임까지 포함한 서비스 단위 실측이라 더 크다.

그런데 job 라벨이 다르다(내가 alloy에서 다르게 설정했기에). 시리즈는 라벨이 하나라도 다르면 다른 시리즈다. Mimir는 이 둘을 사본으로 알아보지 못하고 각각 세고 각각 저장한다. 15만의 85%를 차지한 두 job이 실은 한 벌의 데이터다.

kubeadm으로 세운 클러스터에서는 이게 정상이고 필요한 설정이였을 것이다. 컨트롤플레인이 각각 별개 프로세스라 포트마다 다른 내용이 나오니 둘 다 긁어야 한다. 컨트롤플레인을 한 프로세스로 합친 배포판에서만 사본이 된다.

다만 한 프로세스 안이라고 레지스트리가 하나뿐인 것은 아니다. - 한 프로세스에 여러 메트릭

주소	어느 레지스트리	노드당
`:6443/metrics`	공용 — apiserver·kubelet·scheduler·controller-manager	약 3만–7만
`:10250/metrics`	같은 공용 레지스트리	위와 동일
`:10250/metrics/cadvisor`	cAdvisor 전용	약 5,300–5,800
`:2381/metrics`	etcd 전용	약 1,800

cAdvisor — kubelet 안에 있지만 컨테이너 cgroup을 읽는 별개 수집기라 경로도 레지스트리도 따로다. /metrics만 긁으면 컨테이너 지표가 아예 안 온다.
etcd — 쿠버네티스 컴포넌트가 아니라 별개 오픈소스를 품어 돌린 것이라 자기 레지스트리를 쓴다.

이름이 헷갈리는 것 하나. etcd_request_duration_seconds는 etcd 레지스트리에 없다. "apiserver가 etcd에 다녀온 시간"이라 apiserver가 재는 값이고 공용 레지스트리에 있다.
디스크 압력을 보는 쪽은 :2381의 etcd 전용 레지스트리 매트릭인 etcd_disk_wal_fsync_duration_seconds다.

그리고 scheduler·controller-manager는 자기 메트릭 포트(:10259·:10257)가 노드 밖으로 안 열려 있는데도 지표가 이미 들어와 있다. 공용 레지스트리에 함께 등록돼 있어서다. 표준 문서를 따라 그 포트를 여는 인자를 넣으면 같은 레지스트리를 세 번째·네 번째로 긁게 된다.

4.4 원천은 얼마를 내나

저장소 안의 숫자는 상한을 통과해 들어온 것이라 실제 생산량을 모른다. 상한과 무관한 값은 각 엔드포인트가 내놓는 줄 수를 직접 세면 나온다.

대상	합
kubelet `/metrics` 3노드	179,225
apiserver `:6443` 3노드	179,225 (같은 레지스트리 사본)
cAdvisor 3노드	16,937
etcd · KSM · node-exporter · MinIO · Redis · Alloy · LGTM 자기 지표	약 32,000
합계	약 407,000

상한 15만에 원천이 약 40만이다. 2.7배고, 그중 약 17.9만이 사본이다.

이 값은 고정된 수가 아니다. verb × resource × scope 조합은 apiserver가 겪은 요청 종류만큼 생기므로 재기동 직후에는 작고 클러스터가 돌수록 는다. 재기동 40분 뒤에 다시 세니 노드 세 대 합이 118,642였다. 원천은 자라는데 상한은 고정이라는 것이 이 구도의 성질이다.

막힌 것은 Mimir 하나다. Loki는 인메모리 스트림이 73개로 기본 상한 5,000의 1.5%고 거절이 0이다. 세는 단위가 달라서다 — Loki가 세는 스트림은 라벨 조합이고 로그 본문은 압축된 청크에 들어가므로, 로그는 양이 늘어도 스트림이 안 는다. Tempo는 보낼 앱이 없어 유입이 0이다.

k3s가 컨트롤플레인 넷을 한 프로세스로 합침   →  메트릭 레지스트리도 하나
Alloy가 :6443 과 :10250 을 각각 긁음        →  같은 레지스트리를 두 번
Mimir는 라벨이 다르면 다른 시리즈로 저장      →  사본이 상한의 절반을 차지
──────────────────────────────────────────────────────────
원천 약 40만  vs  상한 15만
   사본을 걷어도 약 22만  —  그래도 15만보다 크다

한쪽만 손봐서는 안 뚫린다. 무엇을 어떻게 손댈지는 다음에 정한다.

5. 뚫는다

손댈 수 있는 자리가 둘이고, 둘 다 필요하다.

사본을 걷는다 — 같은 레지스트리를 두 번 긁는 것을 한 번으로. 약 17.9만이 줄어 원천이 약 22만이 된다.
상한을 올린다 — 그래도 22만이 15만보다 크다. 천장을 올려야 나머지가 들어온다.

한쪽만으로는 안 된다. 사본만 걷으면 22만이 15만에 여전히 막히고, 상한만 올리면 아무도 안 읽는 사본에 메모리를 지불한다.

5.1 사본을 어떻게 걷을까

:6443/metrics와 :10250/metrics가 같은 레지스트리를 찍으므로, 둘 중 하나만 남기면 된다. 어떻게 남기느냐가 갈린다.

한쪽 scrape를 통째로 지운다 — 설정에서 블록 하나를 뺀다. 대신 그 job의 up도 같이 사라진다.
둘 다 두되 한쪽은 up만 남긴다 — 보내기 직전 relabel에서 그 job의 메트릭을 걸러 낸다. up은 수집기가 스스로 만드는 값이라 본문을 다 버려도 남는다.

up 둘이 갈리는 경우가 있다. 같은 프로세스지만 통과하는 경로가 다르다.

up{job="k3s-apiserver"}   :6443  → apiserver 인증·flowcontrol을 지난다
up{job="kubelet"}         :10250 → kubelet의 단순한 경로를 지난다

apiserver 처리 경로가 막히면 앞엣것만 0이 되고 뒤엣것은 1로 남는다. 다만 그 지경이면 kubectl도 안 되는 상태라 다른 데서 먼저 드러난다. 그리고 노드 생존은 이미 다른 신호가 본다 — node-exporter의 up, KSM이 내는 노드 상태, etcd 리더 유무.

결정 — :6443 scrape를 지우고 :10250만 남긴다. 그리고 job 이름을 k3s-server로 바꾼다.

:10250을 고른 이유는 둘이다. apiserver의 인증·flowcontrol 경로를 지나지 않아 apiserver가 밀릴 때도 응답하고, cAdvisor가 같은 포트의 다른 경로라 설정이 나란히 붙는다.

이름을 바꾸는 이유는 어느 쪽 이름도 사실과 안 맞기 때문이다. 이 레지스트리에는 apiserver·kubelet·scheduler·controller-manager 지표가 전부 들어 있다. kubelet이라 부르면 안의 대부분인 apiserver 지표를 가리키지 못하고, k3s-apiserver라 불러도 반만 맞다. k3s-server는 그 프로세스 전체를 가리키므로 나중에 값을 볼 때 헷갈리지 않는다.

이름을 합쳐도 컴포넌트를 못 나누게 되는 것은 아니다. 컴포넌트 구분은 job이 아니라 메트릭 이름이 한다.

apiserver_request_*        apiserver
scheduler_*                스케줄러
workqueue_*                컨트롤러 매니저
kubelet_*                  kubelet
etcd_server_* · etcd_disk_* etcd

job은 "어디서 긁었나"를 적는 라벨이고 "무슨 컴포넌트냐"는 이름이 말한다. 그래서 job을 하나로 두어도 대시보드에서 컴포넌트를 나눠 보는 데 지장이 없다.

5.2 상한을 얼마로 둘까 — 실측으로 계산한다

사본을 걷으면 원천이 약 22만이 된다. 그래도 15만보다 크니 천장을 올려야 하고, 얼마로 올릴지는 인제스터 메모리가 정한다. 얼마나 더 쓰는지는 추정할 필요가 없다 — 인제스터가 자기 값을 낸다.

cortex_ingester_memory_series
process_resident_memory_bytes{job="observability/ingester"}

시리즈 150,000  ↔  RSS 506–618 MiB (세 대, 재는 시점에 따라)
                →  시리즈 하나당 3.5–4.2 KiB

값이 한 자리에 머물지 않는다. 시리즈 수는 15만으로 고정인데 RSS는 계속 오르내린다. Go가 회수한 메모리를 운영체제에 바로 돌려주지 않고, 2시간 블록 주기 안에서 메모리에 든 구간이 자랐다 줄고, 조회가 오면 그만큼 더 쓰기 때문이다. 재기동 직후가 가장 낮고(3.5 KiB) 안정되면 4.2 KiB다. 상한을 정할 때는 저점이 아니라 안정 상태 값을 쓴다.

Mimir 공식 용량 계획은 시리즈당 약 8.3KB를 잡는다(인메모리 30만당 2.5GB). 실측의 두 배다. 공식 값은 피크와 여유를 포함한 프로비저닝 권장치라 그렇고, 여기 값은 앱이 없어 시리즈 교체가 적은 상태의 값이다. 둘 다 두고 계산한다.

RF가 3인데 인제스터도 3대라 전역 상한이 곧 인제스터 한 대가 지는 양이다. 그래서 상한이 그대로 노드당 메모리가 된다.

상한	실측 4.2KiB 기준	공식 8.3KB 기준
15만 (지금)	약 0.6 GiB	약 1.2 GiB
25만	약 1.0 GiB	약 1.9 GiB
30만	약 1.2 GiB	약 2.3 GiB
50만	약 2.0 GiB	약 3.9 GiB

여기에 걸리는 제약이 둘이다.

인제스터 컨테이너 limit — 지금 1Gi로 걸어 뒀다. 이 값을 넘기면 컨테이너가 OOMKilled 된다. 25만에서 이미 닿는다.
노드 여유 — 노드 8GB에서 자원 예약을 뺀 몫 안에 인제스터 말고도 다 들어가야 한다.

그런데 "노드 여유"에 값이 두 개 있다. 스케줄러가 세는 여유와 실제로 남은 메모리가 서로 다르다.

스케줄러가 세는 여유 = 할당 가능량 − 그 노드 파드들의 request 합
실제 남은 메모리     = 커널이 보는 값 (free)

스케줄러는 파드가 얼마를 쓰는지 안 보고 선언한 request만 더한다. dev라 대부분의 파드가 자기 request보다 적게 쓰므로 두 값이 벌어진다.

             스케줄러가 세는 여유    실제 남은 메모리
k3s-1            1,969 MiB          3,532 MiB
k3s-2            1,671 MiB          3,030 MiB
k3s-3            2,427 MiB          4,268 MiB

둘이 막는 것이 다르다. 스케줄러가 세는 여유가 모자라면 파드가 그 노드에 뜨지 못하고(Pending), 실제 메모리가 모자라면 뜬 파드가 죽는다(OOMKill·eviction). 그래서 request를 올릴 때는 왼쪽으로, limit을 올릴 때는 오른쪽으로 검산한다.

결정 — 상한 30만, 인제스터 limit 2Gi, request 1Gi.

상한 30만 — 사본을 걷은 뒤 실수요는 가동 시간에 따라 약 17만–22만 사이를 오르내리고(재기동 직후 낮고 돌수록 는다), 앱이 붙으면 더 는다. 25만은 여유가 13%뿐이라 앱이 붙으면 곧 다시 찬다. 30만이면 36% 여유고, 실측 기준 인제스터당 1.2 GiB다.
limit 2Gi — 30만이 실측 4.2KiB로 약 1.2 GiB라 1Gi로는 컨테이너가 OOMKilled 된다. limit은 스케줄링에 쓰이지 않으므로 올려도 다른 파드를 밀어내지 않는다.
request 1Gi — 지금 512Mi인데 실사용이 571–581 MiB이고 30만이면 1.2 GiB가 된다. request가 실사용보다 작으면 그 초과분 때문에 인제스터가 eviction 우선순위 앞쪽에 놓인다. 상태를 들고 있는 컴포넌트라 그건 피한다. 512Mi를 더 떼도 스케줄러가 세는 여유가 가장 빠듯한 k3s-2에서 1,159 MiB 남고, 실제 메모리는 30만을 다 채워도 2,390 MiB 남는다.

5.3 무엇을 고치나

수집 쪽과 저장 쪽에서 파일 두 개가 바뀐다.

수집 — Alloy 설정

삭제   prometheus.scrape "apiserver"     :6443 — 같은 레지스트리의 사본
삭제   discovery.relabel "apiserver"     그 블록만 쓰던 주소 변환
변경   prometheus.scrape "kubelet"       job_name 을 "k3s-server" 로

discovery.kubernetes "nodes"는 남긴다 — 남은 kubelet·cAdvisor scrape가 그 노드 목록을 쓴다.

저장 — Mimir 설정

추가   limits.max_global_series_per_user: 300000     기본값 150000 을 덮어씀
변경   ingester.resources  requests.memory  512Mi → 1Gi
변경   ingester.resources  limits.memory    1Gi   → 2Gi

적용 — 롤링 교체와 WAL 재생

값이 반영되면 인제스터가 한 대씩 새 파드로 교체된다. StatefulSet의 교체 순서는 번호가 큰 쪽부터다. 30초 간격 기록.

17:44:00   2번 옛 파드 마지막 값     150,000
17:44:30   2번 새 파드 첫 값        196,456
17:45:30   2번                     297,078
17:47:30   세 대 모두               300,000

새 파드가 0이 아닌 값에서 시작하는 것은 디스크에 적어 둔 WAL을 되읽어 메모리 상태를 복원하기 때문이다. 196,456은 재생이 끝나기 전에 긁힌 값이고, 1분 뒤 297,078로 올라간다. 상태를 들고 있는 컴포넌트에 디스크를 붙이면 교체가 데이터 손실 없이 끝난다.

교체 후 인제스터가 든 것은 30만이다. 사본을 걷은 뒤 들어오는 양은 약 18만이므로 12만이 더 있다.

잔존 — 라벨을 바꾸면 옛 시리즈가 옆에 남는다

job 이름은 라벨이고, 라벨 조합이 다르면 다른 시리즈다. 새 이름의 시리즈는 옛 이름의 자리를 대체하지 않고 별도로 생성된다. 옛 시리즈는 샘플이 끊겨도 즉시 사라지지 않는다.

새로 들어오는 것    k3s-server 계열               약 18만
아직 안 빠진 것     kubelet · k3s-apiserver 계열   약 12만
──────────────────────────────────────────────
인제스터가 든 것                                 30만

그래서 적용 직후에는 사용률이 다시 100%가 되고 거절도 이어진다. 이름을 바꾸는 변경에는 옛것과 새것을 동시에 들고 있는 구간이 따라온다.

제거 — head 절단이 시점을 정한다

인제스터가 메모리에 들고 있는 최근 구간을 head라 부른다. 샘플이 끊긴 시리즈를 head에서 덜어내는 동작이 head 절단(truncation) 이고, 블록 생성과는 다른 동작이다.

	하는 일	시리즈가 빠지나
블록 생성	head의 데이터를 파일로 떠서 오브젝트 저장소로 보낸다	아니오
head 절단	head가 담는 시간 구간의 시작점을 앞으로 민다	마지막 샘플이 그 시작점보다 앞서면 빠진다

두 시간 간격으로 도는 절단을 5분 간격으로 기록했다.

시각     보유 시리즈   제거 누적   head 절단   거절/초
17:47    300,000          0          0       0.0
18:02    300,000          0          1      26.9   1회차 — 제거 0
19:58    300,000          0          1      36.7   115분째
20:03    300,000    120,973          2      28.3   2회차 — 120,973 제거
20:08    181,128    120,973          2       1.4

1회차에 제거가 0인 이유는 절단의 정의에서 나온다. 옛 라벨의 샘플이 끊긴 시각은 17:4x이고, 18:02의 절단이 민 시작점은 아직 그보다 앞이라 옛 시리즈의 마지막 샘플이 head 구간 안에 남아 있었다. 20:03의 절단에서 시작점이 17:4x를 넘어가며 120,973이 한 번에 빠졌다.

대기 시간 = 샘플이 끊긴 시각부터 최대 두 주기(약 4시간). 이번은 17:47에서 20:03까지 2시간 16분이었다. 주기가 두 시간이므로 한 주기 미만의 관찰로는 "안 도는 것"과 "아직 안 온 것"이 갈리지 않는다.

확인 — `count`로는 이 12만이 안 보인다

옛 시리즈가 남아 있는지를 count로 확인하면 0이 나온다. count는 최근 몇 분 안에 샘플이 있는 시리즈만 세기 때문이다. 옛 라벨은 샘플이 끊겼으므로 count에는 잡히지 않고, 인제스터 메모리에는 남아 있다.

sum(scrape_samples_scraped)          타깃이 지금 생산하는 양   약 18만
max(cortex_ingester_memory_series)   인제스터가 든 양         30만
max(cortex_ingester_active_series)   최근 샘플이 온 시리즈     약 18만

memory_series는 "지금 메모리에 들고 있는 시리즈", active_series는 "최근 샘플이 온 시리즈"다. 자리를 차지하는 것은 memory_series 쪽이다. 두 값의 간격이 잔존량이고, 12만 벌어져 있다가 20:08에 붙었다.

결과

인제스터 보유    182,397   상한 300,000 의 61%
활성 시리즈      182,397   보유와 같다 = 잔존 0
거절            0/s
실제 메모리      469 · 486 · 479 MiB   limit 2Gi 의 약 24%
파드 재시작      0

사본을 걷어 이 시점 생산량이 약 18만이 됐다 — 걷기 직전에는 두 벌을 합쳐 약 25만이었다. 진단 때 계산한 "걷은 뒤 약 22만"보다 작은 것은, 재기동 뒤 apiserver 계열 시리즈가 아직 다 자라지 않은 시점이라서다. 상한을 30만으로 올려 12만의 여유를 뒀고, 시리즈당 실측 4.2 KiB로 30만을 다 채워도 1.2 GiB라 limit 2Gi 안에 든다.

6. 계기판 — Mimir가 정의하는 세 축으로 짓는다

이 대시보드의 질문은 하나다 — 관측이 도는가. 클러스터가 건강한가는 다음 편 인프라 대시보드의 질문이라 여기 없다.

행 구조는 Mimir 공식(mimir-mixin)이 자기 관측을 나누는 세 축을 그대로 쓴다.

쓰기        받아지는가     Alloy → distributor → ingester
읽기        답하는가       query-frontend → querier
저장 여정    내려가는가     ingester → MinIO / ring · 메모리

시리즈 상한 사건에서 나온 신호들(수집 생존·전송 실패·거절·보유 vs 상한)은 전부 쓰기 축 소속이라 첫 행에 모인다. 패널은 12개로 잡는다 — 빠진 신호가 드러나면 그날 추가한다. 패널 제목은 "컴포넌트 — 신호" 형식이고, 설명(ⓘ)은 역할 · 패널 · 읽는 법 세 줄이다. 화면만 봐도 어느 컴포넌트의 어느 단계인지 읽히게.

대시보드는 git에 푸시하면 Grafana까지 자동으로 배달된다.

① git push        대시보드 JSON을 담은 ConfigMap (라벨 grafana_dashboard: "1")
② ArgoCD          3분 주기 폴링으로 새 커밋 발견 → sync → ConfigMap 생성·갱신
③ 사이드카         Grafana 파드 안의 보조 컨테이너가 쿠버네티스 API를 watch → 라벨 감지
④ 파일 반영        JSON을 공유 볼륨에 파일로 (ConfigMap이 지워지면 파일도 제거)
⑤ 리로드           Grafana 리로드 API 호출 → 재시작 없이 반영

push부터 화면까지는 ②의 폴링 주기가 지배한다 — 최대 약 3분. Grafana에는 영속 저장소가 없어 UI 수정은 재시작에 사라진다 — 수정이 남는 경로는 git push 하나다.

6.1 쓰기 행 — 받아지는가

데이터가 저장소에 앉기까지: Alloy가 긁고, 자기 WAL(전송 전 값을 로컬 디스크에 적어 두는 버퍼)에 적어 배치로 밀고(remote_write), distributor가 해시 링에서 담당 인제스터를 찾아 RF3로 복제하고, ingester가 메모리에 든다. 이 여정의 어디가 끊겨도 결과는 같다 — 값이 조용히 사라진다. 여섯 패널이 그 여정을 단계 순서로 지킨다.

Alloy 수집 — job별 생존 이력

min by (job) (up)

up: 수집기가 스크레이프 성공(1)·실패(0)를 판정해 직접 만드는 값 — 대상이 죽어도 남는 유일한 신호
min by (job): 타깃을 job으로 접기 — 하나만 죽어도 그 줄이 빨강. 이산 상태라 색 블록(state timeline)
빨간 두 줄(booking·app/queue) = 이미지 반입 전 앱. 필터로 가리지 않는다 — 쿼리는 사실만, 맥락은 운영자 몫

distributor·ingester — 거절 (사유별)

sum by (reason) (rate(cortex_discarded_samples_total[5m]))

두 컴포넌트가 한도·유효성 검사에서 거부한 샘플 — reason 라벨에 사유가 문자열로 붙는다
0이 정상. per_user_series_limit = 시리즈 상한 도달 — 늦게 온 시리즈부터 선착순으로 밀린다
상한 사건 때 로그를 뒤져서야 봤던 그 신호의 상시화

Alloy remote_write — 전송 실패·재시도

sum by (pod) (rate(prometheus_remote_storage_samples_failed_total[5m]))
sum by (pod) (rate(prometheus_remote_storage_samples_retried_total[5m]))

실패 = 재시도 없이 버려진 샘플(4xx) = 곧 유실. 옆 거절 패널과 같은 사건의 양면이다
재시도 = 일시 오류(5xx·네트워크)로 재전송 중 — 노드 재시작 때 튀었다가 유실 0으로 회복해야 정상
Mimir가 통째로 죽으면 거절 카운터는 침묵하지만 여기는 뜬다 — 백업 신호

distributor — 유입 (샘플/초)

sum(rate(cortex_distributor_received_samples_total[5m]))

모든 쓰기가 처음 닿는 관문이 받은 초당 샘플 — Mimir Writes 대시보드의 첫 헤드라인
Alloy 전송 처리량 합과 같아야 정상 — 유실 0의 교차 증거 (실측 둘 다 약 3,500–3,650)
꺼지면 상류(수집·전송)가 멈춘 것

ingester — 시리즈 보유·활성 vs 상한 300,000

cortex_ingester_memory_series            (보유 — 파드별 세 선)
max(cortex_ingester_active_series)       (활성 — 한 선)

보유 = 메모리에 든 것 — 상한이 세는 대상(각 노드마다). 활성 = 최근 샘플이 온 것
두 선의 간격 = 잔존. 라벨 변경 뒤 최대 두 절단 주기(약 4시간)까지 정상 — 사본 걷을 때 12만이 이 모양
보유가 파드별 세 선인 이유 = RF3 복제 — 셋이 같아야 하고, 갈라지면 복제 이상. 집계하면 그 신호를 잃는다

Alloy 수집 — job별 생산 시리즈

topk(12, sum by (job) (scrape_samples_scraped))

스크레이프 한 번에 시리즈당 샘플 하나 → 이 값 = 그 타깃의 시리즈 수 — 저장소를 훑지 않고 세는 방법
패널 쿼리는 자동 갱신으로 열어 두면 상시 부하가 된다 — 전 시리즈를 세는 쿼리 하나가 조회 컴포넌트를 42번 죽인 전례가 있어, 무거운 쿼리를 패널에 걸지 않는다
bar gauge: 숫자 = 절대치, 막대 배경 전체 = 상한 300,000
누가 상한을 먹는지 — 상한 튜닝의 근거. k3s-server 하나가 절반 가까이

6.2 읽기 행 — 답하는가

쓰기와 읽기는 독립적으로 고장 난다 — 상한 사건 때 쓰기가 거절로 막히는 동안, 읽기는 별개로 querier가 93분 사이 25번 재시작하고 있었다. 조회는 query-frontend가 쿼리를 쪼개 querier에게 나눠 주고, querier가 인제스터(최근 2시간)와 store-gateway(그 전, MinIO 블록)를 합쳐 답한다. 컴포넌트를 나눈(microservices) 구성의 격리가 여기서 보인다 — 읽기가 죽어도 쓰기는 돈다.

query-frontend — 조회 요청 (상태코드)

sum by (status_code) (rate(cortex_request_duration_seconds_count{
  job="observability/query-frontend", route=~"prometheus_api.*"}[5m]))

조회 입구의 응답 분포 — 조회 API(route 필터)만 남겨 내부 gRPC·헬스체크 소음 제거
499 = 기다리다 취소(느림의 증상), 5xx = 고장
이 대시보드의 패널 쿼리도 여기로 들어온다 — 계기판 자신이 이 경로의 고객

query-frontend — 조회 지연 p99

histogram_quantile(0.99, sum by (le) (rate(
  cortex_request_duration_seconds_bucket{
    job="observability/query-frontend", route=~"prometheus_api.*"}[5m])))

_bucket(지연이 le 이하인 요청 수의 구간별 누적)에서 "100건 중 99건이 든 시간"을 역산 — 백분위의 표준 조합
오르면 화면 체감이 먼저 느려진다
최근 조회만 느리면 ingester 쪽, 과거 구간 조회가 느리면 store-gateway(MinIO) 쪽

6.3 저장 여정·상태 행 — 내려가는가

인제스터의 메모리는 종착지가 아니다. 2시간마다 메모리 구간(head)을 블록으로 떠 MinIO에 올리고(shipper), RF3라 세 벌 올라간 블록을 compactor가 병합한다. 이 길이 막히면 겉은 멀쩡한데 로컬 WAL 디스크만 차오른다 — 증상이 늦게 드러나는 고장이라 축이 "마지막 성공 후 경과"다.

ingester shipper — 마지막 블록 업로드 후 경과

time() - cortex_ingester_shipper_last_successful_upload_timestamp_seconds

"마지막 성공 시각" 게이지를 time()에서 빼면 경과 초 — 이 류 메트릭의 표준 사용법
평시 2시간 미만(업로드 주기). 4시간(빨강) = Mimir 공식 알림 기준
그 너머면 블록이 안 나가 디스크만 차는 중 — 끝은 쓰기 정지

compactor — 마지막 병합 성공 후 경과

time() - cortex_compactor_last_successful_run_timestamp_seconds

같은 패턴, 대상만 compactor. 24시간(빨강) = 공식 알림 기준
멈추면 같은 데이터가 세 벌씩 쌓여 저장·조회 비용이 계속 는다

ingester ring — ACTIVE 수

max(cortex_ring_members{name="ingester", state="ACTIVE"})

해시 링 = 인제스터들이 자기 위치를 등록한 원형 명단 — distributor가 여기서 담당자를 찾는다
링을 지켜보는 컴포넌트마다 각자 보고하므로 sum은 관찰자 수만큼 부풀려진다(실측 21) → max = 실제 멤버 수
3 = 초록. 하나 빠지면 쓰기 quorum(2/3)의 여유가 사라진 상태

ingester — 메모리 vs limit 2Gi

process_resident_memory_bytes{job="observability/ingester"}

시리즈를 메모리에 드는 대가 — 시리즈당 실측 약 4.2KiB, 30만 만재 시 약 1.2GiB
빨간 선 = 컨테이너 limit 2Gi. 닿으면 OOMKilled — WAL 재생으로 복구되지만 그동안 조회가 빈다
시리즈 상한(거절)이 이 OOM을 막는 가드레일 — 두 패널이 짝이다

6.4 알림 후보 — 대시보드에서 역추적한 셋

대시보드는 열어야 보이고, 알림은 안 봐도 온다. 개별 고장마다 알림을 걸지 않고, 여러 고장이 결국 흘러드는 하류 세 지점에만 건다 — 울리면 어느 행을 열지도 정해져 있다.

알림	조건	여는 행	우산 아래 들어오는 고장
데이터 유실	거절 > 0 or 전송 실패 > 0	쓰기	상한 포화 · 카디널리티 폭발 · Mimir 사망
인제스터 이탈	ring ACTIVE < 3	저장 여정·상태	인제스터 크래시·OOM — 최근 구간을 유일하게 든 컴포넌트가 빠짐
저장 정체	블록 업로드 경과 > 4시간	저장 여정·상태	플러시 정체 · MinIO 이상 · 디스크 문제

구현은 다음 편으로 넘긴다. Grafana Alerting으로 룰을 ConfigMap에 담으면 대시보드와 같은 사슬로 배달되고, 수신 채널(Discord webhook)의 URL은 시크릿이라 봉인이 필요하다. 그 봉인 작업이 다음 편의 저장소 이전 작업과 같은 결이라 거기 묶는다.

7. 대조, 그리고 되짚기

7.1 시작할 때와 대조

이 편을 열 때 비어 있던 두 자리가 이렇게 됐다.

열 때	지금
관측이 실제로 흐르는지 확인한 적이 없다	구조를 열어 저장된 15만의 절반이 사본임을 찾았다 — 사본을 걷고 상한을 올려 거절 0, 보유 182,397 / 상한 300,000 (61%)
Grafana 안이 백지다	파이프라인 자신을 보는 계기판 한 장이 코드로 들어갔다 — Mimir 3축 12패널
앱 세 종이 `ImagePullBackOff`	그대로 — 이미지는 10부(CI/CD·레지스트리)에서 생긴다

그 과정에서 이 배포판의 성질 하나가 드러났다. 컨트롤플레인을 한 프로세스로 합쳤다는 사실이 자원 계산·장애 반경·메트릭 세 곳에서 같은 모양으로 나타난다. kube-reserved를 따로 떼야 했던 것, 하나가 죽으면 넷이 같이 죽는 것, 두 포트가 같은 응답을 내던 것이 전부 같은 원인이다.

7.2 남은 것과 걸렸던 것

알림. 후보 셋(데이터 유실 · 인제스터 이탈 · 저장 정체)과 조건까지 확정했고 구현은 9부다. 그때까지 이 계기판은 "열어봐야 아는" 상태로 남는다 — 이 공백은 9부까지 안고 간다.
노드 자원 예약 반영. 설정 파일에는 2Gi, 노드에는 아직 1Gi다. 세 대 순차 재시작이 필요하고, 앱이 올라와 실사용을 다시 잰 뒤 request 전반과 함께 조정한다. 그 재시작이 복제(RF3)가 실제로 일하는지 보는 첫 시험이 된다.
인제스터 request가 지금은 실사용보다 크다. request 1Gi에 실사용 약 478 MiB — 30만 만재(약 1.2 GiB)를 내다보고 절충한 값이라 지금은 절반이 놀고, 만재에 실제로 가까워지면 재조정이 다시 필요하다. 앱 이후 실측으로 다시 잡는다.
MinIO 요청 실패가 초당 0.29로 잡혀서 파봤다 — 고장이 아니었다. 실패의 전부가 compactor의 get이고, MinIO 응답은 4xx(없음)다. compactor는 "이 블록의 인덱스 헤더가 이미 있나", "이 조각(partial) 블록의 메타가 있나"를 조회해 없으면 만들거나 치우는데, 그 "없음(404)" 응답이 실패 카운터에 계수된다. 작업 성공 로그까지 확인했다. 실패 카운터가 0이 아닌 것과 고장은 다르다 — 이 값으로 알림을 걸었다면 상시 오탐이었다.

실측 없이 잡았다가 걸린 자원 값이 이 편에서만 셋 나왔다. 전부 같은 모양이다 — 재보지 않고 정한 값.

무엇	잡았던 값	무슨 일이 났나	고친 값
인제스터 request	512Mi	실사용이 넘어서 eviction 우선순위가 앞당겨지는 상태	1Gi
대시보드 사이드카 limit	64Mi	기동 직후 `exit 137` 반복 — watch 연결과 런타임을 든 컨테이너였다	192Mi
조회 컴포넌트 limit	256Mi	전 시리즈를 훑는 패널 쿼리에 42회 `exit 137`, 다른 패널까지 전부 시간 초과	512Mi

세 번째는 자원만의 문제가 아니었다 — 계기판에 넣은 쿼리 자체가 저장소를 무너뜨리고 있었고, 쿼리를 가벼운 것으로 바꾼 뒤에야 안정됐다. 계기판을 세우는 일이 그 자체로 저장소에 부하를 얹는다는 것을 여기서 겪었다. 진단 첫머리에 보였던 25회 재시작도 같은 자리다 — 무거운 조회가 올 때마다 256Mi에 걸려 죽던 것이고, 512Mi로 올린 뒤 재시작은 0이다.

7.3 실무에서 짚이는 것 — 보안 쪽

이 편에서 실제로 손댄 것에 걸리는 항목만.

상한을 올린 만큼 방어선이 물러났다. 시리즈 상한은 자원 보호 장치이면서 카디널리티 폭탄에 대한 방어다 — 라벨에 요청 ID처럼 값이 무한한 것을 넣는 코드 하나면 저장소가 마비된다. 30만으로 올린 만큼 그 방어선도 뒤로 갔고, 그 자리를 메울 알림이 9부까지 비어 있다.
수집기 권한을 좁혀 둔 것이 여기서 값을 했다. Alloy에서 Secret 읽기 권한을 뺐기 때문에 apiserver 인증을 ServiceMonitor로 못 걸었고 설정에 직접 쓰는 경로로 갔다. 권한을 넓혔다면 더 편했겠지만, 수집기 하나가 클러스터의 모든 시크릿을 읽는 상태가 됐을 것이다.
대시보드 사이드카의 감시 범위도 같은 결이다. 전역으로 두면 편하지만 RBAC이 전 네임스페이스로 넓어진다. 대시보드를 한 네임스페이스에만 두기로 하고 범위를 거기로 묶었다.
메트릭 자체가 유출 통로가 될 수 있다. 라벨에 경로·쿼리스트링이 통째로 들어가면 토큰이 메트릭에 실려 저장소로 간다. 지금은 인프라 지표뿐이라 해당이 없고, 앱이 붙는 편에서 앱이 내는 라벨을 볼 때의 확인 항목이다.
Grafana는 아직 클러스터 밖으로 안 열려 있다. 노출하는 순간 인증·TLS·접근 제어가 따라온다 — 9부에서 Traefik으로 열 때의 일이다. 알림에 쓸 webhook URL도 시크릿이라 봉인(SealedSecret) 대상이고, GitLab 저장소 접근 자격과 같은 결로 그때 함께 처리한다.

7.4 다음 — GitOps 루프부터

이 편에서 대시보드를 고칠 때마다 push 후 최대 3분을 기다렸다. ArgoCD가 저장소를 3분 주기 폴링으로 보고 있어서인데 — 사실 이 지연을 체감하기 전까지 webhook이라는 선택지를 검토한 적 자체가 없었다. 폴링은 선택한 것이 아니라 기본값이라 그냥 돌던 것이다. 이번에 따져 보니 지금 구조에서는 걸고 싶어도 못 건다 — GitHub(인터넷)가 ArgoCD에 요청을 보내려면 ArgoCD가 밖으로 열려 있어야 하는데, 노출은 뒤로 미뤄 둔 상태다.

9부는 그 루프부터 고친다 — GitLab을 데스크탑에 세워 GitOps 소스를 옮기면 Git 서버와 ArgoCD가 같은 망에 있게 되고, 노출 없이 webhook이 성립해 push 즉시 sync가 된다. 알림 세 개가 그 위에서 서고, 그다음 인프라 대시보드 — 클러스터 자체를 보는 눈 — 를 짓는다.

노트북 홈서버 k3s 구축기 - 번외. e1000e NIC hang

hsb_02 — Wed, 29 Jul 2026 17:08:12 +0900

0. 먼저 — 내 네트워크 골목의 구조

홈랩을 진행하던 도중 장애가 발생했다. 데스크탑에서 서버로의 ssh, proxmox web, argocd web이 전부 다운되었다. 그래서 서버가 죽었나 싶어서 닫혀있던 노트북을 열고 root로 진입해보니 pve(내가 만든 proxmox 호스트 - .200)는 잘 살아있었고, pve에서 201,202,203으로도 접근이 잘 되었다. 근데 왜 데스크탑에서 연결이 갑자기 한순간에 다 끊어졌을까.

이 장애는 "안에서는 되는데 밖에서만 안 된다"는 모양이었다. 그래서 원인을 이해하려면, 3부에서 세운 네트워크 구조를 먼저 알아야 한다. 3부에서 깐 배선을 한 장으로 요약하면:

                      공유기 (TP-Link, 192.168.0.1)
                          │  (유선)
                     노트북 유선 NIC = nic0 (내장 Intel, 드라이버 e1000e)
                          │
                     ┌──  vmbr0 (Proxmox 가상 스위치)  ──┐
                     │                                    │
             Proxmox 호스트(.200)              k3s VM  .201 · .202 · .203

핵심 세 가지(3부에서 정한 것):

노트북에 유선 랜은 하나뿐이고, 그게 내장 Intel NIC(nic0, 드라이버 e1000e)다. 3부 설치 때 관리 인터페이스로 이걸 고정했다.
Proxmox는 vmbr0라는 가상 스위치를 만들어, 그 위에 호스트 자신(.200)과 VM 세 대(.201~203)를 다 물린다. 그 가상 스위치의 "바깥 포트"에 물리 NIC(nic0)을 꽂아 진짜 네트워크로 내보낸다. 그래서 공유기 눈에는 노트북 1대로만 보인다.
데스크탑(콘솔, 192.168.0.x)은 같은 공유기 골목에 있고, 여기서 kubectl·SSH·Proxmox 웹UI로 서버를 관리한다.

이 구조에서 "밖으로 나가는 유일한 길이 nic0"라는 게 이 사건의 전부다.

1. 증상 — 갑자기 다 안 닿는다

평소처럼 데스크탑에서 클러스터를 만지려는데, 전부 막혔다.

# kubectl
Unable to connect to the server: dial tcp 192.168.0.201:6443: connect: no route to host

# SSH
ssh: connect to host 192.168.0.201 port 22: Connection timed out

k3s 노드(.201)만이 아니라 Proxmox 웹UI(https://192.168.0.200:8006)도 안 열렸다. 선은 안 건드렸는데.

이때 머릿속에 스치는 건 최악들이다 — 서버가 죽었나? 디스크가 나갔나? 침해인가? 근데 여기서 답으로 점프하면 안 된다. "어디가 문제인가"를 한 번에 반씩 좁혀 내려가야 한다.

2. 반씩 좁히기 (1) — 클러스터냐, 호스트냐

.201(k3s 노드)도 .200(Proxmox 호스트)도 안 된다. 노드 하나만 문제면 다른 노드는 됐을 텐데, 호스트까지 안 되니 "한 대"가 아니라 "그 위 전부"가 안 닿는 것이다.

여기서 구조(§0)가 값을 한다 — .200은 노트북 본체(Proxmox 호스트)고, .201~203은 그 위 VM이다. 호스트가 안 닿으면 그 위 VM도 다 같이 안 닿는다. 그러니 문제는 k3s가 아니라 노트북 본체 쪽으로 좁혀진다.

no route to host라는 에러도 힌트다 — 이건 "상대가 응답을 거부했다"가 아니라 "상대 기계로 가는 길 자체가 없다"(호스트가 꺼졌거나 네트워크에서 사라짐)는 신호다.

→ 좁혀진 것: k3s 문제 아님. 노트북 본체가 통째로 안 닿는다.

3. 반씩 좁히기 (2) — 호스트가 죽었나, 네트워크만 죽었나

노트북 본체로 걸어가 콘솔에 직접 로그인해 봤다.

root@pve:~#

잘 들어가진다. 서버는 켜져 있고 OS도 멀쩡하다. 그러면 "기계가 죽은" 게 아니라 "네트워크로만 못 닿는" 것이다. 여기서 최악의 시나리오(디스크·침해)는 일단 배제된다.

→ 좁혀진 것: 호스트는 살아 있다. 네트워크 도달성 문제다.

4. 반씩 좁히기 (3) — 어느 쪽이 끊겼나 (세 번의 ping)

네트워크가 문제면, 끊긴 지점이 호스트 쪽인지 · 데스크탑 쪽인지 · 그 사이(공유기)인지를 갈라야 한다. 세 군데를 찔러 본다.

① 호스트 → VM (.200에서 .201로 SSH) — 된다.
vmbr0(가상 스위치) 내부는 살아 있다는 뜻이다. 물리 NIC을 거치지 않고 소프트웨어 스위치 안에서만 오가는 길이라, 여기가 되는 건 "내부는 정상"의 증거다.

② 호스트 → 공유기 (.200에서 .1로 ping) — 안 된다.

root@pve:~# ping -c2 192.168.0.1
(응답 없음)

③ 데스크탑 → 공유기 (.167에서 .1로 ping) — 된다.

세 결과를 겹치면 답이 나온다:

경로	결과	뜻
호스트 → VM (vmbr0 내부)	O	가상 스위치 내부 정상
데스크탑 → 공유기	O	공유기·데스크탑은 멀쩡
호스트 → 공유기	X	호스트가 밖으로 못 나간다

공유기는 살아 있고(데스크탑이 닿으니까), vmbr0 내부도 살아 있는데(호스트↔VM 되니까), 오직 호스트에서 공유기로 나가는 업링크(상위 망으로 나가는 연결)만 죽었다.

Proxmox의 가상 스위치인 vmbr0의 바깥 포트로 물린 nic0이 문제다.

→ 좁혀진 것: 호스트의 업링크(nic0 → 공유기) 구간이 끊겼다.

5. 물리냐 데이터냐 — carrier와 ARP

업링크가 죽었다니, 제일 먼저 의심할 건 "선이 빠졌나"다. 근데 확인해 보면 선은 멀쩡하다.

root@pve:~# ip -br link
lo          UNKNOWN
nic0        UP           ← 유선 NIC (밖으로 나가는 길)
wlp0s20f3   DOWN         ← WiFi (안 씀)
vmbr0       UP           ← 가상 스위치
tap201i0    UNKNOWN      ┐
tap202i0    UNKNOWN      ├ VM 3대가 붙은 가상 포트
tap203i0    UNKNOWN      ┘

root@pve:~# ethtool nic0 | grep -i link
        Link detected: yes

ip -br link: 리눅스 네트워크 도구(ip)로 포트(인터페이스) 자체를 보는 것(link). 짧게 한 줄씩(-br).
ethtool nic | grep -i link: nic 하드웨어에 직접 물어봐서(ethtool nic), link가 든 줄만 검색 - 물리적 선이 연결 되어있나

nic0은 UP, Link detected: yes. 선은 물리적으로 붙어 있다. 여기서 개념 하나가 필요하다.

carrier(링크) ≠ 데이터 흐름

carrier = "선이 전기적으로 연결됐다." NIC과 공유기가 서로 "우리 연결됨"을 확인한 상태. 랜포트 LED가 켜지는 게 이거다.
데이터가 흐른다 = 실제로 프레임(데이터 조각)이 오간다. carrier가 있어도 이게 따로 안 될 수 있다.

전화선 비유를 AI가 들어줬다. —

carrier는 수화기를 들었을 때 "뚜—" 하는 다이얼톤이다(선은 살아 있다).

데이터는 실제 통화다. 다이얼톤은 들리는데 통화가 안 되는 상태 = carrier 있는데 데이터 안 감. 지금이 딱 그거다.

그러면 이제 데이터가 실제로 가는지를 봐야 한다. 그 지표가 ARP다.

ARP — IP를 실제 주소(MAC)로 바꾸는 과정

같은 골목(랜-192.168.0.~)에서 IP로 통신하려면, 그 IP의 MAC 주소(하드웨어 주소)가 필요하다. IP는 "이름", MAC은 "실제 집주소"라고 보면 된다. 이름만으론 택배를 못 보낸다 — 집주소를 알아야 보낸다.

그 집주소를 알아내는 게 ARP(Address Resolution Protocol)다. - 주소 해석 프로토콜.

공유기가 만든 사설망에 대고 "192.168.0.1(공유기) 가진 놈 누구야? MAC 알려줘"라고 외치고(브로드캐스트), 공유기가 "나야, 내 MAC은 이거야"라고 답하면, 그제서야 프레임을 보낼 수 있다.

서버에서 직접 ARP 결과를 봤다.

root@pve:~# ip neigh show 192.168.0.1
192.168.0.1 dev vmbr0 FAILED

ip neigh show " 192.168.0.1 ": 같은 사설망에 있는 주소(공유기가 제공하는)에 즉, L2에 있는 기기들(공유기, VM, 데스크탑) 중 공유기 주소(192.168.0.1)의 MAC을 보여줘

FAILED — 공유기의 MAC을 못 얻었다. "공유기 누구야?"라고 외쳤는데 답이 안 온 것이다. 즉 프레임이 서버에서 공유기까지 건너가지 못한다.

정리하면 — carrier(불)는 켜졌는데, ARP는 실패한다. 선은 붙었지만 실제 데이터는 한 발짝도 못 나간다. 모순이 아니라, 이 둘이 서로 다른 층이라서 이렇게 갈린다. 원인은 "선"이 아니라, 그 위 어딘가에서 데이터가 얼어붙은 것이다.

(브리지 설정도 의심해 ip link show master vmbr0로 확인했지만, nic0은 정상적으로 vmbr0에 물려 있었다. 브리지 문제도 아니다.)

→ 좁혀진 것: 물리 선은 정상(carrier yes), 그런데 데이터가 안 감(ARP FAILED). 그 사이 어딘가에서 프레임이 멈춘다.

6. 근본 원인 — NIC이 멈췄다 (dmesg)

"선은 붙었는데 데이터가 멈춘다"의 답은 커널 로그에 있다. dmesg를 봤더니 같은 줄이 수십 번 찍혀 있었다.

dmesg: 커널이 남긴 로그를 화면에 뿌려주는 명령어

root@pve:~# dmesg -T | grep -iE "e1000e|nic0|hang|link" | tail
... e1000e 0000:00:1f.6 nic0: Detected Hardware Unit Hang:      (34번 반복)
... e1000e 0000:00:1f.6 nic0: NIC Link is Down
... vmbr0: port 1(nic0) entered disabled state
... e1000e 0000:00:1f.6 nic0: NIC Link is Up 1000 Mbps Full Duplex
... vmbr0: port 1(nic0) entered forwarding state

e1000e 0000:00:1f.6 nic0 — 3부에서 고정했던 그 내장 Intel NIC(PCI 주소 00:1f.6, 드라이버 e1000e)다. 그리고 Detected Hardware Unit Hang. 이걸 이해하려면 두 개념이 필요하다.

NIC "hang"이 뭐냐

NIC 안에는 패킷을 실제로 처리하는 회로(엔진)가 있다. 컴퓨터가 보낼 프레임들을 NIC의 송신 큐(TX queue, 보낼 것 대기줄)에 넣으면, NIC 엔진이 거기서 하나씩 꺼내 선으로 밀어낸다.

hang = 그 엔진이 멈춰버린 것. 큐에서 프레임을 안 꺼내고 얼어붙어, 대기줄에 쌓이기만 하고 밖으로 하나도 안 나간다. NIC은 전원 들어와 있고 링크(carrier)도 붙어 있는데, 처리 회로만 멈춘 상태다.

Detected Hardware Unit Hang은 드라이버(e1000e)가 "NIC 처리 회로가 큐를 안 비우고 멈췄다"를 감지해 찍는 메시지다. 34번 반복 = 34번 감시하는 동안 계속 멈춰 있었다는 뜻. 그래서 ARP 프레임조차 못 나갔고(§5의 FAILED), carrier만 켜진 채 데이터가 정지했던 것이다.

AI가 우편 분류기로 비유해줬다. — NIC은 편지를 in-tray(큐)에서 꺼내 밖으로 보내는 자동 기계다. hang은 그 기계 모터가 잼(jam) 걸려 멈춘 것. 전원은 켜졌는데(불) 편지가 안 나간다.

왜 하필 이 NIC이 멈췄나 — 오프로드 버그

큰 데이터는 그대로 못 나가고 작은 프레임(약 1500바이트씩)으로 쪼개야 한다. 이 쪼개는 일을 보통은 CPU가 하는데, 성능을 위해 NIC 하드웨어한테 떠넘기는 기능이 있다 — 이걸 오프로드(TSO: TCP Segmentation Offload 등)라고 한다. "큰 덩어리 줄 테니 네가 쪼개서 보내" 하고 NIC에 통째로 넘기는 것이다.

문제는 Intel e1000e 계열(I219/I218) 칩의 그 쪼개기 하드웨어에 결함이 있다는 점이다. 특정 상황에서 큰 덩어리를 쪼개다가 엔진이 잼(hang) 걸린다. 그게 Hardware Unit Hang의 정체 — 쪼개다가 멈춘 것이다. 널리 알려지고 문서화된 버그다.

(참고로 4부에서 "USB 자동절전 차단"을 해뒀지만, 그건 외장 SSD(USB)를 위한 거였다. 이 NIC은 USB가 아니라 노트북 내장 이라 절전과 무관하다. 실제로 확인해도 usbcore.autosuspend는 -1(꺼짐), sleep 타깃은 masked(차단)로 이미 다 막혀 있었다. 그래서 전력관리가 아니라 드라이버 버그가 원인이라는 게 분명해진다.)

→ 근본 원인: Intel e1000e NIC의 세그멘테이션 오프로드 버그로 인한 TX hang.

7. 해결 — 오프로드를 끈다

https://forum.proxmox.com/threads/intel-nic-e1000e-hardware-unit-hang.106001/

[SOLVED] - Intel NIC e1000e hardware unit hang

This has been discussed many times, is there a solution/workaround yet, as the specified steps are not working for me? I've the following in /etc/network/interfaces auto lo iface lo inet loopback iface eno1 inet manual offload-gso off offload-gro off offlo

forum.proxmox.com

원인이 "NIC이 쪼개다가 멈춘다"이니, 해결은 "NIC 말고 CPU가 쪼개게" 바꾸는 것이다. 그러면 버그난 쪼개기 회로를 아예 안 쓴다.

# 문제 오프로드 끄기 (CPU가 쪼개도록)
ethtool -K nic0 tso off gso off gro off

이렇게 하면 CPU가 미리 1500바이트짜리로 쪼개 넘겨주고, NIC은 밀어내기만 한다 → 불량 쪼개기 회로를 안 쓰니 잼이 안 난다. 대가는 CPU가 쪼개기를 대신 하는 것뿐인데, 기가비트 홈랩에선 체감이 없다.

재부팅해도 유지되게 udev 규칙으로 못 박는다.

echo 'ACTION=="add", SUBSYSTEM=="net", KERNEL=="nic0", RUN+="/sbin/ethtool -K nic0 tso off gso off gro off"' \
  > /etc/udev/rules.d/70-nic0-offload.rules
udevadm control --reload

적용됐는지 확인.

root@pve:~# ethtool -k nic0 | grep -iE "tcp-segmentation|generic-segmentation|generic-receive"
tcp-segmentation-offload: off
generic-segmentation-offload: off
generic-receive-offload: off

셋 다 off. 이 시점부터 hang은 안 난다. 데스크탑에서 kubectl·SSH·Proxmox 웹UI가 전부 다시 붙었다.

8. 정리 — 이 장애에서 남는 것

결과부터 — 클러스터·VM·데이터는 한 번도 죽지 않았다. 죽은 건 데스크탑에서 서버로 가는 네트워크 경로 하나(내장 NIC의 드라이버 버그)뿐이었다. 처음엔 "서버가 나갔나, 침해인가" 싶던 게, 층층이 좁히니 "NIC 드라이버 quirk"까지 내려왔다.

디버깅 방법으로 남는 것:

한 번에 반씩 좁힌다. 클러스터냐 호스트냐 → 호스트가 죽었냐 네트워크냐 → 어느 쪽이 끊겼냐. 답으로 점프하지 않고 매 단계에서 절반을 배제한다.
아래 층부터 위로 본다. 물리(선/carrier) → 데이터(ARP) → 드라이버(dmesg). 밑이 안 되면 위는 볼 필요도 없다.
carrier(불) ≠ 데이터. 랜포트 불이 켜졌다고 통신되는 게 아니다. ethtool의 Link detected와 ip neigh의 상태를 나눠 봐야 "선인지 데이터인지"가 갈린다.
원인은 결국 로그(dmesg)가 말해줬다. 증상만 쫓지 말고, 커널이 남긴 기록을 봐야 근본이 나온다.

개념 흐름으로 남는 것:

기계가 네트워크에 붙는 길 = NIC(부품) → 드라이버(그걸 굴리는 SW) → vmbr0(가상 스위치, 호스트·VM·NIC을 묶음). 그래서 밖은 막혀도 호스트↔VM은 됐다.
carrier vs 데이터 / IP·MAC·ARP — 불 켜졌는데 왜 안 됐나.
hang(엔진 잼)·오프로드·Intel e1000e 버그 — 왜 멈췄고 왜 오프로드를 끄면 낫나.

홈랩을 켜놓고 운영한다는 건, 이런 물리·드라이버 층의 quirk를 만나 밑단부터 짚어 내려가는 일이기도 하다. 이번엔 그게 오래된 Intel NIC 하나였다.

9. 후속 — 며칠 후, 같은 자리가 또 끊겼다

며칠 후 데스크탑에서 같은 증상이 났다. kubectl은 no route to host, 공유기(.1)는 응답하고 호스트(.200)·VM(.201–203)은 전부 무응답 — 같은 분기다. 이번엔 좁히기가 빨랐다. 콘솔에서 dmesg를 보니 같은 줄이 다시 쌓여 있었다.

dmesg: 커널이 남긴 로그를 화면에 뿌려주는 명령어

[Sun Aug  2 14:54:04 2026] e1000e 0000:00:1f.6 nic0: Detected Hardware Unit Hang:
(약 5분 동안 164회)

같은 hang이다. 그런데 오프로드 상태를 확인하니 이야기가 달랐다.

root@pve:~# ethtool -k nic0 | grep -E "tcp-segmentation|generic-segmentation|generic-receive"
tcp-segmentation-offload: on
generic-segmentation-offload: on
generic-receive-offload: on

꺼 뒀던 셋이 전부 도로 켜져 있다. 그리고 uptime이 이유를 말해줬다 — 하루 전에 재부팅이 있었다.(노트북 전원 나가서 서버도 꺼져버려서 다시킴)

끈 날        ethtool로 off → hang 멈춤
하루 전      재부팅 → 오프로드가 기본값(on)으로 복귀
오늘 14:54   켜진 오프로드로 같은 버그 → hang 164회

hang이 "다시" 난 게 아니라, 처방이 사라진 자리에서 원래 병이 그대로 난 것이다. 왜 처방이 사라졌는지를 이해하려면, 그때 쓴 도구 둘의 정체부터 갈라야 한다.

ethtool이 고치는 것은 파일이 아니라 메모리다

ethtool: 리눅스 환경에서 네트워크 카드(NIC)의 상태를 조회하고 하드웨어 설정을 변경하는 데 쓰는 명령어 도구

드라이버에는 조절 손잡이가 여럿 있다 — 속도, 각종 오프로드의 켜고 끄기, 통계. ethtool은 그 손잡이를 만지는 명령줄 도구다(-k 소문자는 보기, -K 대문자는 바꾸기).

성질이 하나 있다. ethtool은 지금 떠 있는 드라이버의 상태만 바꾼다. 어떤 파일에도 기록되지 않는다. 재부팅하면 드라이버가 새로 뜨면서 공장 기본값 — 오프로드 전부 켜짐 — 으로 돌아온다. 오프로드를 끈 그 명령은 살아 있는 드라이버의 값을 바꾼 것뿐이었고, 재부팅과 함께 증발했다. 메모리니까, 재부팅하면 그 값은 유지되지 않는다.

그 증발을 막으라고 심은 것이 udev 규칙이었다

udev: 리눅스 커널을 위한 장치 관리자. /dev 디렉터리의 장치 파일을 동적으로 생성하고 관리하며, USB 등 장치 연결 이벤트를 처리.

리눅스에서 장치가 꽂히거나 부팅 중에 발견되면, 커널이 "장치가 나타났다(add)"는 이벤트를 쏜다. udev는 그 이벤트를 받아 반응하는 상주 서비스고, 반응 내용은 규칙 파일(/etc/udev/rules.d/*.rules)에 "이런 조건의 장치가 이런 이벤트를 내면 → 이걸 해라" 꼴로 적는다. USB를 꽂으면 장치 파일이 생기는 것, 이 NIC이 nic0이라는 고정 이름을 갖는 것 — 전부 udev가 규칙대로 반응한 결과다.

그래서 만든 규칙이 "이름이 nic0인 장치가 나타나면(add) → ethtool로 오프로드를 꺼라( NIC 말고 CPU가 쪼개게 )"였다. 부팅마다 자동으로 다시 꺼지게 하려는 의도였다.

불발 — add 순간엔 nic0이라는 이름이 없다

부팅 로그가 불발의 이유를 말해준다.

root@pve:~# journalctl -b | grep -iE "renamed" | head -2
Aug 01 11:46:08 pve kernel: e1000e 0000:00:1f.6 eno0: renamed from eth0
Aug 01 11:46:08 pve kernel: e1000e 0000:00:1f.6 nic0: renamed from eno0

부팅 때 이 NIC은 eth0이라는 임시 이름으로 태어나, eno0을 거쳐 nic0이 된다. 이 개명은 이름 고정용 설정(/usr/local/lib/systemd/network/50-pmx-nic0.link — 3부에서 이름을 고정할 때 생긴 파일)을 읽은 udev가, add 이벤트를 처리하는 과정에서 수행한다.

여기서 순서가 갈린다. add 이벤트가 접수되는 순간의 이름은 eth0이고, nic0은 그 이벤트 처리의 결과물이다. 그런데 규칙의 조건은 "이름이 nic0인 장치가 나타나면"이었다 — 나타나는 순간엔 그 이름이 아직 없다. 조건이 성립하는 순간 자체가 존재하지 않는다.

[add 이벤트]   이름 = eth0
    ├─ 심어둔 규칙: "nic0이면 실행" → eth0이라 불일치, 통과
    ├─ .link 처리: "nic0으로 개명" 결정
[처리 끝]      이름 = nic0        ← 이제야 nic0인데, 이벤트는 끝났다

개명됐다고 add 이벤트가 다시 오지도 않는다 — 접수는 한 번이다. 그래서 이 규칙은 문법이 맞았을 뿐 단 한 번도 실행된 적이 없다. hang이 없던 나흘은 규칙이 지켜준 게 아니라, 손으로 끈 라이브 상태가 재부팅 전까지 살아 있었던 것뿐이다. "적용했다"와 "재부팅을 견딘다"는 서로 다른 검증인데, 끈 날에는 앞엣것만 하고 뒤엣것을 했다고 믿었다.

교체 — 이름이 확정된 뒤에 도는 층으로

같은 명령을, 실행이 보장되는 자리로 옮긴다. Proxmox가 네트워크를 올릴 때 읽는 설정(/etc/network/interfaces)의 해당 인터페이스 구절에 건다.

iface nic0 inet manual
        post-up /sbin/ethtool -K nic0 tso off gso off gro off

post-up은 "이 인터페이스를 올린 직후 실행"이다. 네트워크를 올리는 것은 장치 접수·개명이 모두 끝난 뒤의 일이라, 그 시점엔 nic0이라는 이름이 확정돼 있다. 같은 ethtool 한 줄인데, 어느 층의 어느 시점에 거느냐가 실행 여부를 갈랐다.

이번엔 심고 끝내지 않고 실행되는 것까지 확인한다 — 재부팅 없이 설정 재적용으로 태워 본다.

root@pve:~# ifreload -a
root@pve:~# ethtool -k nic0 | grep -E "tcp-segmentation|generic-segmentation|generic-receive"
tcp-segmentation-offload: off
generic-segmentation-offload: off
generic-receive-offload: off

안 먹는 게 실증된 udev 규칙은 지운다(rm /etc/udev/rules.d/70-nic0-offload.rules) — 남겨두면 다음에 또 "돼 있겠지"로 속는다.

남은 검증이 하나 있다 — 실제 재부팅 통과. 이번 일의 교훈이 정확히 "같겠지를 검증으로 치지 마라"이므로, 다음에 호스트를 재부팅할 일이 있을 때 이 세 값이 off로 올라오는지 확인하는 것까지가 마무리다.

이 후속에서 남는 것:

검증에는 층위가 있다. "지금 적용됐다" → "올라올 때마다 적용된다"(ifreload) → "재부팅을 넘는다"(실부팅). 셋은 각각 따로 확인해야 하는 다른 사실이다.
조건이 맞는 설정과 실행된 설정은 다르다. 설정을 넣었으면 실행된 흔적(여기서는 부팅 직후의 ethtool 상태)까지 봐야 한다.
이름에도 층이 있다. eth0 → eno0 → nic0 — 한 장치가 부팅 중 이름을 두 번 갈아입고, 어느 층의 이름으로 조건을 걸었느냐가 규칙의 생사를 갈랐다.