쿠버네티스 전반 ③ — 설치 · 도구 · 트러블슈팅

01. 클러스터 설계

지금까지는 이미 만들어진 클러스터를 다뤘어요. 12부는 클러스터를 직접 짓는 이야기예요. 짓기 전에 먼저 정할 것은 “어디에 쓸 클러스터인가”예요. 목적에 따라 노드 수, 설치 도구, 누가 컨트롤 플레인을 관리할지가 전부 달라져요.

1. 목적에 따라 고르기

2. 규모와 노드 크기

쿠버네티스 한 클러스터가 감당하도록 설계된 한계가 있어요. 이 숫자를 넘길 일은 드물지만, “노드당 Pod 110개”는 작은 클러스터에서도 자주 만나요.

운영에서는 컨트롤 플레인 노드에 앱 Pod를 올리지 않아요. kubeadm은 컨트롤 플레인 노드에 node-role.kubernetes.io/control-plane:NoSchedule taint를 자동으로 달아 줘요(3부 03). etcd는 디스크 속도에 민감해서, 큰 클러스터에서는 SSD를 쓰거나 etcd만 따로 떼어 내요(03).

3. 어디에, 어떻게 설치하나

02. 고가용성(HA) 구성

고가용성(High Availability)은 “한 대가 죽어도 클러스터는 계속 동작한다”는 뜻이에요. 워커는 원래 여러 대라 괜찮지만, 컨트롤 플레인이 한 대뿐이면 그 한 대가 단일 장애점이에요.

1. 컨트롤 플레인 여러 대와 로드밸런서

API 서버는 상태를 etcd에 두고 자기는 아무것도 기억하지 않아서, 여러 대가 동시에 요청을 받아도 돼요(active-active). 그래서 앞에 로드밸런서를 두고, kubectl · kubelet · 다른 부품이 모두 로드밸런서 주소로 접속하게 해요. kubeadm에서는 이 주소를 --control-plane-endpoint로 정해요.

2. 리더 선출 — 스케줄러와 컨트롤러 매니저

스케줄러나 컨트롤러 매니저가 세 대 모두 일하면 같은 Pod를 세 번 배치하거나 ReplicaSet이 Pod를 세 배로 만들 수 있어요. 그래서 이 둘은 active-standby예요. kube-system의 Lease 객체를 먼저 잡은 쪽이 리더가 되고, 리더는 주기적으로 Lease를 갱신해요. 갱신이 끊기면 대기하던 쪽이 Lease를 가져가요.

$ kubectl get lease -n kube-system
NAME                      HOLDER                                       AGE
kube-controller-manager   cp1_7f3c…                                    3d
kube-scheduler            cp1_a91e…                                    3d
$ kubectl get lease kube-scheduler -n kube-system -o yaml | grep -E "holder|renew"
  holderIdentity: cp1_a91e…
  renewTime: "2026-10-30T09:12:41.118Z"

03. etcd HA

etcd는 클러스터의 기억이에요(1부 03). API 서버는 여러 대여도 결국 etcd에 읽고 쓰니까, etcd도 여러 대여야 HA가 완성돼요. 그런데 etcd는 API 서버처럼 “아무 데나 쓰면 되는” 구조가 아니에요. 여러 대가 같은 내용을 갖도록 합의하는 규칙이 필요해요.

1. Raft와 쿼럼

etcd는 Raft라는 합의 알고리즘을 써요. 핵심은 세 가지예요.

2. 왜 홀수인가

표에서 보듯 4대는 3대와, 6대는 5대와 견디는 수가 같아요. 한 대를 더 사도 안전해지지 않고, 복제할 곳만 늘어 쓰기가 느려져요. 짝수는 네트워크가 반으로 갈라졌을 때도 불리해요. 6대가 3 · 3으로 나뉘면 어느 쪽도 과반(4)이 안 돼서 클러스터 전체가 멈춰요. 그래서 3대나 5대가 표준이에요. 2대는 1대보다 오히려 위험해요(둘 중 하나만 죽어도 멈춤).

3. stacked vs external

어느 쪽이든 API 서버는 --etcd-servers에 etcd 멤버 전부를 적어서, 한 멤버가 죽으면 다른 멤버로 붙어요. etcd끼리는 2380 포트로 서로를 알아요.

# etcd1 (10.0.0.11)
--name=etcd1
--initial-advertise-peer-urls=https://10.0.0.11:2380
--listen-client-urls=https://10.0.0.11:2379,https://127.0.0.1:2379
--initial-cluster=etcd1=https://10.0.0.11:2380,etcd2=https://10.0.0.12:2380,etcd3=https://10.0.0.13:2380

# kube-apiserver
--etcd-servers=https://10.0.0.11:2379,https://10.0.0.12:2379,https://10.0.0.13:2379

$ export ETCDCTL_CACERT=/etc/kubernetes/pki/etcd/ca.crt \
         ETCDCTL_CERT=/etc/kubernetes/pki/etcd/server.crt \
         ETCDCTL_KEY=/etc/kubernetes/pki/etcd/server.key
$ etcdctl --endpoints=https://10.0.0.11:2379 member list -w table
$ etcdctl --endpoints=https://10.0.0.11:2379,https://10.0.0.12:2379,https://10.0.0.13:2379 \
    endpoint status -w table          # IS LEADER 열에서 리더 확인

04. kubeadm으로 설치하기

kubeadm은 쿠버네티스 프로젝트가 만든 공식 설치 도구예요. 인증서 · kubeconfig · Static Pod 매니페스트를 대신 만들어 주고, 노드를 붙이는 과정을 자동화해요. 컨트롤 플레인 1대 + 워커 2대 클러스터를 만들어 봐요. 6부의 업그레이드(6부 02)도 같은 도구였어요.

1. VM 준비 — 모든 노드에서

학습 자료는 Vagrant + VirtualBox로 VM 3대(controlplane · node01 · node02)를 만들어요. VM이 준비되면 모든 노드에서 같은 준비를 해요. 각 노드는 hostname · MAC 주소 · product_uuid가 서로 달라야 해요(VM을 복제했다면 확인).

$ sudo swapoff -a
$ sudo sed -i '/[[:space:]]swap[[:space:]]/ s/^[^#]/#&/' /etc/fstab     # 재부팅 후에도 꺼지게

$ cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF
$ sudo modprobe overlay && sudo modprobe br_netfilter

$ cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF
$ sudo sysctl --system

$ sudo apt-get update && sudo apt-get install -y containerd
$ sudo mkdir -p /etc/containerd
$ containerd config default | sudo tee /etc/containerd/config.toml > /dev/null
$ sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
$ sudo systemctl restart containerd

$ sudo apt-get install -y apt-transport-https ca-certificates curl gpg
$ sudo mkdir -p -m 755 /etc/apt/keyrings
$ curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.36/deb/Release.key \
    | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
$ echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.36/deb/ /' \
    | sudo tee /etc/apt/sources.list.d/kubernetes.list
$ sudo apt-get update
$ sudo apt-get install -y kubelet kubeadm kubectl
$ sudo apt-mark hold kubelet kubeadm kubectl        # apt upgrade로 멋대로 올라가지 않게

설치 직후 kubelet이 몇 초마다 재시작하는데 정상이에요. kubeadm이 설정 파일을 만들어 줄 때까지 기다리는 중이에요.

2. kubeadm init · join

$ sudo kubeadm init \
    --apiserver-advertise-address=192.168.56.11 \
    --pod-network-cidr=10.244.0.0/16
…
Your Kubernetes control-plane has initialized successfully!
…
kubeadm join 192.168.56.11:6443 --token abcdef.0123456789abcdef \
    --discovery-token-ca-cert-hash sha256:1a2b3c…

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

kubeadm init은 정해진 순서(phase)대로 일해요. 각 phase가 앞에서 배운 내용과 그대로 이어져요.

$ sudo kubeadm join 192.168.56.11:6443 --token abcdef.0123456789abcdef \
    --discovery-token-ca-cert-hash sha256:1a2b3c…

# 토큰이 만료됐거나 출력을 잃어버렸다면 컨트롤 플레인에서 다시 만들기
$ kubeadm token create --print-join-command

join은 토큰으로 API 서버에 “처음 인사”를 하고, --discovery-token-ca-cert-hash로 상대가 진짜 우리 클러스터인지 확인해요. 그다음 kubelet이 자기 인증서를 신청해서 받는 TLS 부트스트랩을 해요(7부 04의 CSR이 자동으로 승인되는 과정).

apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
kubernetesVersion: v1.36.0
controlPlaneEndpoint: "k8s-api.example.local:6443"   # HA를 대비한 이름 (02)
networking:
  podSubnet: 10.244.0.0/16
  serviceSubnet: 10.96.0.0/12
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: systemd

$ sudo kubeadm init --config kubeadm.yaml --upload-certs

3. CNI 설치까지

init과 join이 끝나도 노드는 전부 NotReady예요. Pod 네트워크가 없어서 kubelet이 “아직 Pod를 받을 수 없다”고 보고하는 거예요(11부 03). CoreDNS Pod도 Pending이에요. CNI를 설치하면 풀려요.

$ kubectl get nodes
NAME           STATUS     ROLES           VERSION
controlplane   NotReady   control-plane   v1.36.0
node01         NotReady   <none>          v1.36.0
node02         NotReady   <none>          v1.36.0

# 예: Flannel (기본 Pod 대역이 10.244.0.0/16 이라 init 값과 맞음)
$ kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml

$ kubectl get nodes
NAME           STATUS   ROLES           VERSION
controlplane   Ready    control-plane   v1.36.0
node01         Ready    <none>          v1.36.0
node02         Ready    <none>          v1.36.0
$ kubectl get pods -A                      # coredns · kube-proxy · flannel 모두 Running

$ echo 'KUBELET_EXTRA_ARGS=--node-ip=192.168.56.12' | sudo tee /etc/default/kubelet
$ sudo systemctl restart kubelet

4. 12부 셀프 체크

1. 혼자 학습할 때, 직접 서버에 구축할 때, 운영할 때 각각 어울리는 방식은?

   학습: minikube · kind. 직접 구축: kubeadm. 운영: 컨트롤 플레인 3대 이상의 HA 구성이나 EKS · GKE · AKS 같은 관리형.
2. kubelet의 노드당 기본 최대 Pod 수는?

   110개(maxPods).
3. 컨트롤 플레인이 한 대일 때 그 노드가 죽으면 이미 떠 있는 Pod는 어떻게 되나요?

   kubelet이 계속 돌려서 Pod는 살아 있어요. 하지만 API 서버가 없어서 배포 · 스케일 · 재스케줄 같은 변경은 전부 안 돼요.
4. HA 구성에서 kubectl과 kubelet은 어느 주소로 접속하나요?

   컨트롤 플레인들 앞의 로드밸런서(또는 가상 IP) 주소. kubeadm의 --control-plane-endpoint로 정해요.
5. API 서버는 여러 대가 동시에 일하는데, 스케줄러는 왜 한 대만 일하나요?

   여러 대가 동시에 결정하면 같은 Pod를 중복 처리할 수 있어서요. kube-system의 Lease를 잡은 리더 하나만 일하고 나머지는 대기해요.
6. etcd 5대 클러스터의 쿼럼과, 견딜 수 있는 장애 수는?

   쿼럼 3, 2대까지 죽어도 동작해요.
7. etcd를 4대로 두지 않는 이유는?

   4대의 쿼럼은 3이라 견디는 수가 3대와 같은 1대예요. 복제만 늘어 느려지고, 2 · 2로 갈라지면 양쪽 다 과반이 안 돼요.
8. etcd의 쿼럼이 깨지면 클러스터는 어떻게 되나요?

   etcd가 쓰기를 거부해서 API를 통한 모든 변경이 실패해요. 이미 떠 있는 Pod는 계속 돌아요.
9. stacked etcd와 external etcd의 차이는?

   stacked는 컨트롤 플레인 노드마다 etcd가 함께 있어 서버가 적게 들지만 노드 하나에 둘을 같이 잃어요. external은 etcd 전용 서버를 따로 둬서 서버가 더 들지만 장애가 서로 번지지 않아요.
10. kubeadm 설치 전 모든 노드에서 하는 준비 세 가지는?

    swap 끄기, 커널 모듈(overlay · br_netfilter)과 sysctl(ip_forward 등) 설정, 컨테이너 런타임(containerd) 설치. 그다음 kubeadm · kubelet · kubectl 설치와 hold.
11. 워커 join 명령을 잃어버렸어요. 어떻게 다시 얻나요?

    컨트롤 플레인에서 kubeadm token create --print-join-command.
12. init과 join이 끝났는데 노드가 모두 NotReady예요. 왜인가요?

    CNI 플러그인이 아직 없어서 Pod 네트워크가 준비되지 않았기 때문이에요. CNI를 설치하면 Ready가 되고 CoreDNS도 Running이 돼요.

01. Helm이란

지금까지는 리소스를 YAML 하나씩 만들고 지웠어요. 그런데 실제 앱 하나는 Deployment · Service · PVC · Secret · ConfigMap · Ingress처럼 YAML 여러 개의 묶음이에요. Helm은 이 묶음을 하나의 앱 단위로 설치 · 업그레이드 · 되돌리기 · 삭제하는 쿠버네티스의 패키지 관리자예요. 앱의 apt · Homebrew, Flutter의 pub 같은 존재예요.

1. YAML 묶음을 손으로 관리하면

2. 설치와 첫 명령

Helm은 클러스터에 아무것도 설치하지 않는 CLI 하나예요. kubectl과 같은 kubeconfig(7부 05)로 클러스터에 접속해요.

$ brew install helm                        # macOS (Linux는 공식 설치 스크립트나 패키지)
$ helm version
version.BuildInfo{Version:"v4.x.x", …}

$ helm repo add podinfo https://stefanprodan.github.io/podinfo   # 저장소 등록
$ helm repo update                                           # 목록 새로 받기
$ helm search repo podinfo                                   # 등록한 저장소에서 찾기
$ helm search hub wordpress                                  # Artifact Hub 전체에서 찾기

$ helm install web podinfo/podinfo                           # release 이름 web으로 설치
$ helm list                                                  # 설치된 release 목록 (-A: 모든 Namespace)
$ helm uninstall web                                         # 묶음 전체 삭제

02. Helm 2 · 3 · 4

학습 자료는 Helm 2와 3의 차이를 설명해요. Helm 2는 이미 오래전에 끝났고, 지금은 Helm 4가 나와 있어요. 차이를 알면 오래된 블로그 글을 읽을 때 헷갈리지 않아요.

1. Tiller 제거와 3방향 병합

3방향 병합 덕분에 누군가 kubectl edit으로 손댄 부분도 Helm이 알아채요. 롤백하면 손으로 바꾼 값까지 차트 값으로 돌아가고, 업그레이드할 때는 차트가 다루지 않는 필드(예: 손으로 붙인 레이블)는 남겨 둬요.

2. Helm 4에서 달라진 것

Helm 4.0은 2025년 11월에 나왔어요. Helm 3 차트(apiVersion: v2)와 기존 release는 그대로 동작해서, CLI만 바꾸면 돼요. 저장 방식이 같아 변환 작업도 없어요.

03. 구성 요소

1. chart · release · repository · values

release 이름은 리소스 이름의 앞부분이 되기 때문에, 같은 chart로 my-site와 my-second-site를 설치해도 리소스가 서로 겹치지 않아요. release 기록은 그 Namespace의 Secret에 버전마다 하나씩 저장돼요.

$ kubectl get secret -l owner=helm
NAME                            TYPE                 DATA
sh.helm.release.v1.my-site.v1   helm.sh/release.v1   1
sh.helm.release.v1.my-site.v2   helm.sh/release.v1   1

2. 저장소 — Artifact Hub와 OCI

공개 chart는 Artifact Hub(artifacthub.io)에서 찾아요. helm search hub가 여기를 검색해요. chart를 담는 방식은 두 가지예요.

04. Chart

1. chart 폴더 구조

$ helm create web            # 뼈대 chart 만들기
web/
├── Chart.yaml               # chart 이름 · 버전 · 의존성
├── values.yaml              # 기본값
├── values.schema.json       # (선택) values 검사 규칙
├── charts/                  # 의존 chart가 들어오는 곳
├── templates/               # 빈칸이 있는 YAML들
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── _helpers.tpl         # 이름 만들기 같은 공통 조각 (_로 시작하면 리소스가 아님)
│   └── NOTES.txt            # 설치 후 화면에 보여 줄 안내
└── README.md

apiVersion: v2               # Helm 3 · 4 차트
name: web
description: 작은 웹 앱
type: application            # application 또는 library(공통 템플릿만 제공)
version: 0.1.0               # chart 자체의 버전 — 템플릿을 고치면 올림
appVersion: "1.27.0"         # 안에 든 앱의 버전 — 참고용
dependencies:                # 다른 chart를 함께 설치
  - name: postgresql
    version: "15.x.x"
    repository: https://charts.example.com
    condition: postgresql.enabled

2. 템플릿과 values

템플릿은 Go 템플릿 문법이에요. {{ }} 안에 넣을 값을 적고, Helm이 설치 직전에 채워서 평범한 YAML로 만들어요.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-web
  labels:
    app.kubernetes.io/instance: {{ .Release.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: web
          image: "{{ .Values.image.repo }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          {{- if .Values.resources }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
          {{- end }}

$ helm lint ./web                                  # 문법 · 모범 사례 검사
$ helm template my-site ./web --set replicaCount=3 # 채운 결과만 화면에 (클러스터와 무관)
$ helm install my-site ./web --dry-run=server      # API 서버 검증까지, 실제 생성은 안 함
$ helm get manifest my-site                        # 설치된 release의 최종 YAML 보기

3. values 덮어쓰기 순서

값은 여러 곳에서 올 수 있고, 뒤에 올수록 이겨요.

$ helm show values podinfo/podinfo > my-values.yaml   # 기본값을 받아서
$ vi my-values.yaml                                    # 필요한 것만 고치고
$ helm install web podinfo/podinfo -f my-values.yaml   # 파일로 적용
$ helm get values web                                  # 내가 덮어쓴 값만 보기 (--all: 전체)

$ helm pull podinfo/podinfo --untar                    # chart를 폴더로 받아서 직접 고친 뒤
$ helm install web2 ./podinfo                          # 로컬 폴더로 설치

05. 라이프사이클

1. install · upgrade · rollback · history

$ helm install web podinfo/podinfo                       # revision 1
$ helm upgrade web podinfo/podinfo --set replicaCount=3  # revision 2
$ helm history web
REVISION  STATUS      CHART           DESCRIPTION
1         superseded  podinfo-6.x.x   Install complete
2         deployed    podinfo-6.x.x   Upgrade complete

$ helm rollback web 1                                    # 1번 설정으로 → revision 3
$ helm history web
REVISION  STATUS      CHART           DESCRIPTION
1         superseded  podinfo-6.x.x   Install complete
2         superseded  podinfo-6.x.x   Upgrade complete
3         deployed    podinfo-6.x.x   Rollback to 1

2. 롤백이 되돌리지 못하는 것

롤백은 쿠버네티스 리소스의 설정을 예전 revision으로 돌려요. 그 사이 데이터베이스에 쌓인 데이터, PV 안의 파일, 외부 서비스에 보낸 요청은 되돌리지 않아요. 데이터 구조를 바꾸는 업그레이드라면 먼저 백업해야 해요.

3. 13부 셀프 체크

1. Helm을 한 문장으로 설명하면?

   여러 YAML로 이루어진 앱을 하나의 단위(release)로 설치 · 업그레이드 · 롤백 · 삭제하는 쿠버네티스 패키지 관리자.
2. Helm 3에서 Tiller를 없앤 이유는?

   Tiller가 큰 권한으로 모든 사용자의 요청을 대신 처리해서 보안 구멍이 됐기 때문이에요. Helm 3부터는 CLI가 사용자의 kubeconfig와 RBAC로 API 서버에 직접 요청해요.
3. 3방향 병합 패치에서 비교하는 세 가지는?

   이전 revision의 차트, 클러스터의 실제(live) 상태, 새로 적용할 차트.
4. chart · release · revision의 차이는?

   chart는 설치 묶음, release는 그 chart를 클러스터에 설치한 인스턴스(이름 있음), revision은 release가 바뀔 때마다 1씩 늘어나는 버전 번호예요.
5. 같은 chart로 release를 두 개 설치해도 리소스가 겹치지 않는 이유는?

   템플릿이 리소스 이름에 .Release.Name을 넣기 때문에 release마다 다른 이름이 만들어져요.
6. Helm 3 · 4는 release 기록을 어디에 저장하나요?

   release가 있는 Namespace의 Secret(sh.helm.release.v1.<이름>.v<revision>, 타입 helm.sh/release.v1).
7. Chart.yaml의 version과 appVersion의 차이는?

   version은 chart 자체의 버전, appVersion은 chart가 설치하는 앱의 버전이에요.
8. values.yaml에 replicaCount: 1, -f prod.yaml에 2, --set replicaCount=3을 주면 결과는?

   3. --set이 가장 나중에 적용돼서 이겨요.
9. 클러스터에 설치하지 않고 템플릿 결과만 보려면?

   helm template 이름 ./chart (API 서버 검증까지 하려면 helm install --dry-run=server).
10. revision 2에서 helm rollback web 1을 하면 history는 어떻게 되나요?

    revision 1의 설정으로 새 revision 3이 생기고 STATUS가 deployed가 돼요. 기록은 지워지지 않아요.
11. Helm 4에서 --atomic은 무엇으로 바뀌었나요?

    --rollback-on-failure. --force는 --force-replace로 바뀌었어요.
12. 롤백했는데 DB 데이터가 그대로예요. 왜인가요?

    롤백은 쿠버네티스 리소스 설정만 되돌리고, PV 안의 데이터는 건드리지 않기 때문이에요. 데이터는 hook이나 별도 백업으로 관리해요.

01. Kustomize가 푸는 문제

13부의 Helm은 빈칸이 있는 템플릿에 값을 채웠어요. Kustomize는 다른 길을 가요. 평범한 YAML을 그대로 두고, 환경마다 “여기만 이렇게 바꿔”라는 덮어쓰기만 따로 적어요. 템플릿 문법이 없어서 원본 YAML이 그대로 읽히는 게 장점이에요.

1. 환경마다 조금씩 다른 YAML

Flutter로 치면 flavor(dev · prod)마다 앱 전체를 복사하지 않고, 공통 코드는 하나로 두고 환경 설정만 바꾸는 것과 같은 생각이에요.

2. Helm과 비교 · 설치

둘은 경쟁이라기보다 함께 쓰기도 해요. 공개 chart를 helm template으로 YAML로 뽑은 뒤 Kustomize로 우리 환경에 맞게 덮어쓰는 식이에요.

$ kubectl version --client
Client Version: v1.36.x
Kustomize Version: v5.x.x             # kubectl 안에 들어 있는 Kustomize

$ brew install kustomize               # 단독 CLI (kubectl 내장보다 새 버전이 먼저 나옴)
$ kustomize version

02. kustomization.yaml

1. 무엇을 · 어떻게 바꿀지 적는 파일

Kustomize는 폴더 안의 kustomization.yaml 하나만 봐요. 여기에 두 가지를 적어요. ① 어떤 YAML을 가져올지(resources), ② 그 YAML을 어떻게 바꿀지(transformer · patch).

k8s/
├── kustomization.yaml
├── nginx-deployment.yaml
└── nginx-service.yaml

apiVersion: kustomize.config.k8s.io/v1beta1   # 생략해도 되지만 적는 걸 권장
kind: Kustomization

resources:                  # ① 가져올 YAML (파일 · 폴더 · URL)
  - nginx-deployment.yaml
  - nginx-service.yaml

labels:                     # ② 바꿀 내용 — 모든 리소스에 레이블 추가 (04)
  - pairs:
      company: example

2. 결과 보기와 적용

$ kubectl kustomize k8s/                     # 결과 YAML을 화면에만 (= kustomize build k8s/)
$ kubectl kustomize k8s/ | kubectl apply -f -  # 결과를 파이프로 넘겨 적용
$ kubectl apply -k k8s/                      # 위와 같은 일을 한 번에
$ kubectl diff -k k8s/                       # 적용하면 무엇이 바뀌는지 미리
$ kubectl delete -k k8s/                     # 그 결과물을 삭제

03. 디렉터리 관리

1. 폴더마다 kustomization.yaml

파일이 많아져 폴더로 나누면, 예전에는 폴더마다 kubectl apply -f api/ · -f db/를 따로 했어요. 루트에 kustomization.yaml을 두면 한 번에 돼요. 폴더 안에도 kustomization.yaml을 두면 루트는 폴더 이름만 알면 돼요.

k8s/
├── kustomization.yaml        # resources: [api/, cache/, db/]
├── api/
│   ├── kustomization.yaml    # resources: [api-depl.yaml, api-service.yaml]
│   ├── api-depl.yaml
│   └── api-service.yaml
├── cache/ …
└── db/ …

# k8s/kustomization.yaml
resources:
  - api/
  - cache/
  - db/

04. Transformer

transformer는 “모든 리소스에 이걸 해 줘”처럼 여러 리소스를 한꺼번에 바꾸는 규칙이에요. kustomization.yaml에 필드 하나만 적으면 돼요.

1. 공통 transformer

labels:                      # 학습 자료의 commonLabels 대신
  - pairs:
      org: example
    includeSelectors: true     # selector · Pod 템플릿에도 넣기 (commonLabels와 같은 동작)
namePrefix: shop-              # api → shop-api
nameSuffix: -dev               # shop-api → shop-api-dev
namespace: dev                 # 모든 리소스의 metadata.namespace
commonAnnotations:
  owner: team-a

transformer는 그 kustomization.yaml이 가져온 모든 것에 적용돼요. 루트에 적으면 하위 폴더(api · db)까지 전부, db/kustomization.yaml에 적으면 db 리소스에만 적용돼요. 이름을 바꿔도 Service의 selector나 Deployment가 참조하는 ConfigMap 이름처럼 서로 가리키는 부분은 Kustomize가 함께 고쳐 줘요.

2. Image transformer

images:
  - name: nginx                # 원본 YAML의 image 이름이 nginx인 곳을 찾아
    newName: haproxy           # 이미지를 바꾸고   → haproxy
    newTag: "2.9"              # 태그도 바꿈        → haproxy:2.9
  - name: web
    digest: sha256:4f1c…       # 태그 대신 digest로 고정 (8부 01)

name은 컨테이너 이름이 아니라 image 값을 찾는 조건이에요. 원본 YAML을 건드리지 않고 환경마다 다른 버전을 쓰게 할 때, CI가 빌드한 새 태그를 넣을 때(kustomize edit set image web=registry/web:1.4.2) 많이 써요. 같은 방식의 replicas 필드도 있어요.

replicas:
  - name: api-deployment
    count: 5

3. ConfigMap · Secret generator

학습 자료에는 없지만 실무에서 아주 많이 써요. 파일이나 값에서 ConfigMap · Secret을 만들어 주고, 이름 뒤에 내용의 해시를 붙여요.

configMapGenerator:
  - name: app-config
    files:
      - application.properties
    literals:
      - LOG_LEVEL=info

$ kubectl kustomize .
kind: ConfigMap
metadata:
  name: app-config-7g2h9k5f8m          # 내용이 바뀌면 해시도 바뀜
…
        envFrom:
        - configMapRef:
            name: app-config-7g2h9k5f8m  # Deployment의 참조도 자동으로 고쳐 줌

ConfigMap 내용만 바꾸면 Pod는 그대로라 새 설정을 안 읽어요(5부 03). generator를 쓰면 이름이 바뀌어 Deployment의 Pod 템플릿이 달라지니까 롤링 업데이트가 자동으로 일어나요.

05. Patch

transformer가 “모두에게 똑같이”라면, patch는 “이 리소스의 이 필드만”이에요. 예를 들어 api Deployment의 replicas만 5로 바꾸는 식이에요.

1. 두 가지 patch 방식

patch에는 세 가지 정보가 있어요. 무엇을(target: kind · name · label), 어떻게(add · remove · replace), 무슨 값으로.

# ① JSON 6902 — inline
patches:
  - target:
      kind: Deployment
      name: api-deployment
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5

# ② strategic merge — inline
patches:
  - patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: api-deployment
      spec:
        replicas: 5

2. inline과 별도 파일

patch가 길어지면 별도 파일로 빼고 path로 가리켜요. 두 방식 모두 가능해요.

patches:
  - path: replicas-patch.yaml          # strategic merge 파일
  - path: replicas-json.yaml           # JSON 6902 파일은 target을 함께
    target:
      kind: Deployment
      name: api-deployment

3. 딕셔너리(키-값) patch

레이블처럼 키-값으로 된 곳을 바꾸는 예예요. JSON 6902에서 경로의 /는 ~1로 적어요(예: app.kubernetes.io~1name).

4. 리스트 patch

컨테이너 목록처럼 리스트를 바꿀 때가 가장 헷갈려요. JSON 6902는 위치 번호로, strategic merge는 name으로 짝을 맞춰 찾아요.

# strategic merge — name이 sidecar인 컨테이너 삭제
spec:
  template:
    spec:
      containers:
        - name: sidecar
          $patch: delete

06. Overlay와 Component

1. base와 overlays

k8s/
├── base/
│   ├── kustomization.yaml       # resources: [nginx-depl.yaml, service.yaml, redis-depl.yaml]
│   ├── nginx-depl.yaml          # replicas: 1
│   ├── service.yaml
│   └── redis-depl.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    ├── stg/
    │   └── kustomization.yaml
    └── prod/
        ├── kustomization.yaml
        └── grafana-depl.yaml    # prod에만 있는 리소스

# overlays/prod/kustomization.yaml
resources:
  - ../../base                   # 학습 자료의 bases: 대신 resources에 적음
  - grafana-depl.yaml            # base에 없는 리소스 추가
namespace: prod
patches:
  - target:
      kind: Deployment
      name: nginx-deployment
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5

$ kubectl apply -k overlays/dev     # dev 환경
$ kubectl apply -k overlays/prod    # prod 환경 — base는 한 벌

overlay 폴더 구조는 자유예요. 환경(dev · prod) 말고 지역(kr · us)이나 고객별로 나눠도 돼요. 공통 수정은 base에서 한 번만 하면 모든 환경에 반영돼요.

2. Component — 골라 넣는 기능 묶음

overlay는 “환경”별 차이예요. 그런데 “캐시 기능” · “외부 DB 사용”처럼 일부 환경에만 넣는 기능이 있으면 어떨까요. dev와 prod에는 넣고 stg에는 빼야 한다면, overlay에 복사하면 또 중복이 생겨요. 이 기능을 component로 한 번 만들어 두고, 필요한 overlay만 가져다 써요.

k8s/
├── base/
├── components/
│   └── caching/
│       ├── kustomization.yaml   # kind: Component
│       ├── redis-depl.yaml
│       └── deployment-patch.yaml
└── overlays/
    ├── dev/      # components: [../../components/caching]
    ├── stg/      # (넣지 않음)
    └── prod/     # components: [../../components/caching]

# components/caching/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component                  # Kustomization이 아니라 Component
resources:
  - redis-depl.yaml
secretGenerator:
  - name: redis-creds
    literals:
      - password=change-me
patches:
  - path: deployment-patch.yaml  # 앱에 REDIS_HOST 환경 변수 추가

# overlays/dev/kustomization.yaml
resources:
  - ../../base
components:
  - ../../components/caching

3. 학습 자료와 달라진 필드

학습 자료의 일부 필드는 Kustomize v5에서 사용 중단(deprecated) 경고가 나와요. 아직 동작은 하지만 새로 쓸 때는 오른쪽 필드를 쓰세요. 단독 CLI의 kustomize edit fix가 옛 필드를 새 필드로 바꿔 줘요.

4. 14부 셀프 체크

1. Kustomize가 Helm과 가장 다른 점은?

   템플릿 없이 평범한 YAML을 두고, 바꿀 부분만 patch · transformer로 덧씌워요. 패키지 · release · 롤백 개념은 없어요.
2. kustomization.yaml에 적는 두 가지는?

   가져올 YAML 목록(resources)과 그것을 어떻게 바꿀지(transformer · patch).
3. 결과 YAML만 보려면? 바로 적용하려면?

   보기: kubectl kustomize 폴더(= kustomize build). 적용: kubectl apply -k 폴더.
4. 하위 폴더에도 kustomization.yaml을 두면 루트 resources에는 무엇을 적나요?

   파일 경로 대신 폴더 이름(api/, db/)만 적어요.
5. 루트 kustomization.yaml의 namePrefix는 하위 폴더 리소스에도 적용되나요?

   네. 그 kustomization이 가져온 모든 리소스에 적용돼요. 하위 폴더에 적으면 그 폴더 리소스에만 적용돼요.
6. images transformer의 name은 무엇과 비교하나요?

   컨테이너 이름이 아니라 원본 YAML의 image 값(이미지 이름)이에요.
7. configMapGenerator가 이름 뒤에 해시를 붙이면 좋은 점은?

   내용이 바뀌면 이름이 바뀌고 Deployment의 참조도 같이 바뀌어서, 설정 변경 때 롤링 업데이트가 자동으로 일어나요.
8. patch에 필요한 세 가지 정보는?

   대상(target), 동작(add · remove · replace), 값(value).
9. JSON 6902로 컨테이너 리스트 맨 뒤에 추가하는 path는?

   /spec/template/spec/containers/- (op: add).
10. strategic merge patch로 리스트 항목을 지우는 방법은?

    그 항목의 name과 함께 $patch: delete를 적어요.
11. overlay와 component의 차이는?

    overlay는 환경 하나(dev · prod)의 최종 설정이고, component는 여러 overlay가 골라서 가져다 쓰는 기능 묶음(kind: Component)이에요.
12. 학습 자료의 commonLabels · patchesStrategicMerge · bases는 지금 무엇으로 쓰나요?

    labels, patches, resources.

01. CRD

지금까지 쓴 Pod · Deployment · Service는 쿠버네티스에 처음부터 들어 있는 리소스였어요. 쿠버네티스는 여기에 우리만의 리소스 종류를 새로 추가할 수 있어요. 11부의 Gateway API, 9부의 VolumeSnapshot도 사실 이렇게 추가된 리소스예요.

1. 리소스 = API에 저장된 기록 + 그걸 실행하는 컨트롤러

Deployment를 만들면 두 가지가 일어나요. API 서버가 그 내용을 etcd에 기록하고, 컨트롤러 매니저 안의 Deployment 컨트롤러가 그 기록을 보고 ReplicaSet을 만들어요(1부 05). 새 리소스를 추가할 때도 이 두 가지가 필요해요.

2. CRD 만들기

학습 자료의 예제는 항공권 예약이에요. 먼저 만들고 싶은 CR을 정해요.

apiVersion: flights.com/v1      # CRD에서 정할 group/version
kind: FlightTicket
metadata:
  name: my-flight-ticket
spec:
  from: Seoul
  to: Jeju
  number: 2                     # 좌석 수

이 YAML을 그대로 적용하면 no matches for kind "FlightTicket" 오류가 나요. 그런 종류를 API 서버가 모르기 때문이에요. 그래서 CRD로 종류부터 등록해요.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: flighttickets.flights.com       # 반드시 <plural>.<group>
spec:
  group: flights.com                    # apiVersion의 앞부분
  scope: Namespaced                     # 또는 Cluster
  names:
    kind: FlightTicket
    singular: flightticket
    plural: flighttickets               # URL · kubectl get 에 쓰임
    shortNames: [ft]
  versions:
    - name: v1
      served: true                      # 이 버전으로 API 요청을 받음
      storage: true                     # etcd에 저장하는 버전 (딱 하나)
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                from:   { type: string }
                to:     { type: string }
                number: { type: integer, minimum: 1, maximum: 10 }

$ kubectl apply -f flightticket-crd.yaml
customresourcedefinition.apiextensions.k8s.io/flighttickets.flights.com created
$ kubectl api-resources | grep flight
flighttickets   ft   flights.com/v1   true   FlightTicket
$ kubectl apply -f my-flight-ticket.yaml
flightticket.flights.com/my-flight-ticket created
$ kubectl get ft
NAME               AGE
my-flight-ticket   5s

3. 더 똑똑한 CRD — 검증 규칙 · 출력 열 · status

그 뒤로 CRD가 할 수 있는 일이 많아졌어요. 아래 필드는 같은 versions[] 항목 안에 적어요.

      schema:
        openAPIV3Schema:
          properties:
            spec:
              type: object
              x-kubernetes-validations:          # CEL 검증 규칙 (1.29 GA)
                - rule: "self.from != self.to"
                  message: "출발지와 도착지가 같을 수 없어요"
      additionalPrinterColumns:                  # kubectl get 에 보일 열
        - name: From
          type: string
          jsonPath: .spec.from
        - name: To
          type: string
          jsonPath: .spec.to
      subresources:
        status: {}                               # spec과 status를 따로 갱신

$ kubectl get ft
NAME               FROM    TO
my-flight-ticket   Seoul   Jeju

02. Custom Controller

CRD만 있으면 FlightTicket은 etcd에 저장된 메모일 뿐이에요. 실제로 항공권을 예약하려면 이 메모를 읽고 일하는 컨트롤러가 필요해요.

1. 조정 루프 (reconcile loop)

모든 컨트롤러는 같은 일을 반복해요. 원하는 상태(spec)와 실제 상태를 비교하고, 다르면 맞추고, 결과를 status에 적어요. 1부에서 본 ReplicaSet 컨트롤러가 “Pod 3개를 원하는데 2개다 → 하나 더”를 반복하는 것과 똑같은 구조예요.

2. 컨트롤러는 어떻게 만드나

컨트롤러는 보통 Go로 만들어요. 쿠버네티스 자체가 Go로 쓰여 있고, 공식 라이브러리가 가장 잘 갖춰져 있기 때문이에요(다른 언어도 가능해요).

학습 자료는 이 부품들을 직접 엮은 sample-controller 저장소를 보여 줘요. 요즘은 kubebuilder(controller-runtime 기반)로 뼈대를 만들고 Reconcile 함수만 채우는 경우가 많아요.

func (r *FlightTicketReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    var ticket flightsv1.FlightTicket
    if err := r.Get(ctx, req.NamespacedName, &ticket); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err) // 이미 지워졌으면 끝
    }
    booked := r.Airline.CountSeats(ticket.Spec.From, ticket.Spec.To) // 실제 상태
    if booked < ticket.Spec.Number {                                 // 원하는 상태와 비교
        r.Airline.Book(ticket.Spec.Number - booked)                  // 차이만큼 맞추기
    }
    ticket.Status.Booked = ticket.Spec.Number
    return ctrl.Result{}, r.Status().Update(ctx, &ticket)            // status 기록
}

$ kubebuilder init --domain flights.com
$ kubebuilder create api --group flights --version v1 --kind FlightTicket
$ make manifests                 # Go 구조체에서 CRD YAML 생성
$ make run                       # 노트북에서 실행 (kubeconfig로 접속)
$ make docker-build docker-push deploy   # 이미지로 만들어 클러스터에 Deployment로

클러스터 안에서 돌릴 때는 Deployment로 띄우고, ServiceAccount에 FlightTicket을 읽고 status를 쓸 수 있는 RBAC 권한을 줘요(7부 08).

3. 좋은 컨트롤러의 조건 — 멱등성 · finalizer · ownerReference

03. Operator Framework

1. Operator = CRD + 컨트롤러 + 운영 지식

Operator는 특정 앱(데이터베이스 등)을 운영하는 사람의 노하우 — 설치 순서, 백업, 복구, 업그레이드, 장애 대응 — 를 CRD와 컨트롤러로 담은 묶음이에요. 학습 자료의 예는 etcd Operator예요. EtcdCluster · EtcdBackup · EtcdRestore 같은 CRD를 만들면, 12부에서 손으로 하던 멤버 관리와 6부의 스냅샷 백업을 Operator가 대신해요.

apiVersion: etcd.example.com/v1
kind: EtcdCluster
metadata:
  name: my-etcd
spec:
  size: 3                 # 멤버 3개 — 홀수 (12부 03)
  version: "3.6.0"

2. 도구와 OperatorHub

Operator 성숙도(capability level)는 5단계로 나눠요. ① 기본 설치 → ② 매끄러운 업그레이드 → ③ 백업 · 복구 등 전체 라이프사이클 → ④ 지표 · 알림 같은 깊은 관찰 → ⑤ 자동 조정(스케일 · 튜닝). Operator를 고를 때 몇 단계까지 해 주는지 보면 좋아요.

# Helm으로 Operator를 설치하는 경우가 많아요 (13부)
$ helm install cert-manager oci://quay.io/jetstack/charts/cert-manager \
    -n cert-manager --create-namespace --set crds.enabled=true
$ kubectl get crd | grep cert-manager
certificates.cert-manager.io    …
issuers.cert-manager.io         …

3. 자주 만나는 CRD · Operator

4. 15부 셀프 체크

1. CRD와 Custom Resource의 차이는?

   CRD는 “이런 종류가 있다”는 정의(종류 등록), Custom Resource는 그 종류로 만든 객체 하나예요.
2. CRD 없이 FlightTicket YAML을 적용하면 어떤 오류가 나나요?

   no matches for kind "FlightTicket" in version "flights.com/v1" — API 서버가 그 종류를 몰라요.
3. CRD의 metadata.name은 어떤 형식이어야 하나요?

   <plural>.<group> — 예: flighttickets.flights.com.
4. versions의 served와 storage의 차이는?

   served는 그 버전으로 API 요청을 받는지, storage는 etcd에 저장할 때 쓰는 버전(하나만 true)이에요.
5. CRD만 만들고 컨트롤러가 없으면 어떻게 되나요?

   CR은 etcd에 저장되고 조회도 되지만, 그걸 보고 실제 일을 하는 쪽이 없어서 아무 일도 일어나지 않아요.
6. 조정 루프의 네 단계는?

   지켜보기(watch) → 원하는 상태와 실제 상태 비교 → 차이만큼 맞추기 → status에 기록. 이를 계속 반복해요.
7. informer가 하는 일은?

   API 서버를 watch해서 변경을 받아 오고 메모리 캐시에 복사본을 유지해요. 컨트롤러가 매번 API 서버에 묻지 않아도 돼요.
8. 컨트롤러를 멱등하게 짜야 하는 이유는?

   재시작이나 중복 이벤트로 같은 객체를 여러 번 처리하기 때문이에요. 여러 번 실행해도 결과가 같아야 중복 예약 같은 사고가 안 나요.
9. finalizer는 언제 쓰나요?

   객체가 지워지기 전에 외부 리소스 정리(예약 취소, 클라우드 디스크 삭제 등)를 해야 할 때요. 정리가 끝나고 finalizer를 지워야 삭제가 완료돼요.
10. Deployment를 지우면 ReplicaSet과 Pod도 같이 지워지는 원리는?

    하위 리소스의 ownerReference에 주인이 적혀 있어서, 가비지 컬렉터가 주인이 사라진 하위 리소스를 지워요.
11. Operator를 한 문장으로 설명하면?

    특정 앱을 운영하는 사람의 지식(설치 · 백업 · 복구 · 업그레이드)을 CRD와 컨트롤러로 자동화한 것.
12. CRD에서 필드끼리 비교하는 검증은 어떻게 하나요?

    x-kubernetes-validations에 CEL 식(예: self.from != self.to)을 적어요. 1.29부터 정식 기능이에요.

01. 좁혀 가는 순서

장애는 대부분 “안 돼요” 한마디로 시작해요. 쿠버네티스는 부품이 많아서 아무 데나 열어 보면 길을 잃어요. 그래서 요청이 지나가는 길을 따라 한 칸씩 확인하며 범위를 좁혀요. 지금까지 배운 1~15부가 전부 여기서 쓰여요.

1. 바깥에서 안으로

2. STATUS가 알려 주는 첫 단서

$ kubectl describe pod web-7d9f-x2kq        # 맨 아래 Events가 핵심
$ kubectl logs web-7d9f-x2kq --previous     # 직전에 죽은 컨테이너의 로그
$ kubectl events --for pod/web-7d9f-x2kq    # 그 객체의 이벤트만 시간 순으로
$ kubectl get events -A --sort-by=.lastTimestamp | tail   # 클러스터 전체 최근 이벤트

02. 애플리케이션 장애

1. 사용자에서 DB까지 따라가기

학습 자료의 2계층 앱은 web(프론트)과 db(MySQL)로 이루어져요. 사용자에 가까운 쪽부터 한 칸씩 확인해요.

$ curl http://web-service-ip:node-port             # ① 입구가 응답하나
$ kubectl describe service web-service             # ② Selector · TargetPort · Endpoints
Selector:     name=webapp-mysql
TargetPort:   8080/TCP
Endpoints:    <none>                               #    ← 비어 있으면 selector와 Pod 레이블 비교
$ kubectl get pod --show-labels                    # ③ Pod 레이블
$ kubectl get pod web-… -o jsonpath='{.spec.containers[0].ports}'   # ④ 컨테이너 포트 = targetPort?
$ kubectl logs web-… -f                            # ⑤ 앱 로그 (DB 접속 오류 등)
$ kubectl get pod web-… -o yaml | grep -A1 DB_     # ⑥ 접속 정보 (DB_Host · DB_User · DB_Password)
$ kubectl describe service mysql-service           # ⑦ 다음 칸 — db Service 이름 · 포트 3306

2. CrashLoopBackOff 읽기

CrashLoopBackOff는 원인이 아니라 “계속 죽어서 재시작 간격을 늘리는 중”이라는 결과예요. 원인은 직전 컨테이너가 남긴 로그와 종료 코드에 있어요.

$ kubectl get pod web-…
NAME     READY   STATUS             RESTARTS      AGE
web-…    0/1     CrashLoopBackOff   5 (40s ago)   4m
$ kubectl describe pod web-… | grep -A5 "Last State"
    Last State:     Terminated
      Reason:       Error
      Exit Code:    1                    # 1: 앱 오류 · 137: SIGKILL(OOM 등) · 143: SIGTERM
$ kubectl logs web-… --previous          # 죽기 직전의 마지막 말

03. 컨트롤 플레인 장애

1. 증상으로 부품 찾기

2. kubeadm 클러스터 — Static Pod 확인

$ kubectl get pods -n kube-system                  # API가 살아 있으면 여기서 상태 확인
kube-scheduler-controlplane   0/1   CrashLoopBackOff
$ kubectl logs kube-scheduler-controlplane -n kube-system
$ kubectl describe pod kube-scheduler-controlplane -n kube-system

# API 서버가 죽어 kubectl이 안 되면 컨트롤 플레인 노드에 접속해서
$ sudo crictl ps -a | grep kube-apiserver          # 컨테이너 상태 (Exited?)
$ sudo crictl logs <container-id>                # 마지막 로그
$ sudo vi /etc/kubernetes/manifests/kube-apiserver.yaml   # 옵션 · 경로 · 포트 오타 (3부 07)
$ sudo journalctl -u kubelet -f                    # kubelet이 매니페스트를 왜 못 띄우는지

3. 서비스로 설치된 클러스터

kubeadm이 아니라 “The Hard Way”(12부 01)처럼 부품을 systemd 서비스로 설치했다면 Pod가 아니라 서비스를 봐요.

$ sudo systemctl status kube-apiserver kube-controller-manager kube-scheduler
$ sudo journalctl -u kube-apiserver --since "10 min ago"
$ sudo systemctl status kubelet kube-proxy             # 워커 노드

04. 워커 노드 장애

1. 노드 조건과 NotReady

$ kubectl get nodes
NAME     STATUS     ROLES    AGE
node01   NotReady   <none>   12d
$ kubectl describe node node01
Conditions:
  Type             Status    Reason
  MemoryPressure   Unknown   NodeStatusUnknown    # Unknown = kubelet이 보고를 멈춤
  DiskPressure     Unknown   NodeStatusUnknown
  PIDPressure      Unknown   NodeStatusUnknown
  Ready            Unknown   NodeStatusUnknown

2. 노드에 들어가서

$ ssh node01
$ top ; df -h ; free -m                               # 자원 — 메모리 · 디스크
$ sudo systemctl status kubelet                       # active (running)?
$ sudo journalctl -u kubelet -n 50 --no-pager         # 왜 멈췄나
$ sudo systemctl status containerd                    # 런타임도 같이
$ sudo systemctl restart kubelet

# 자주 나오는 kubelet 오류
$ sudo cat /var/lib/kubelet/config.yaml               # kubelet 설정 (clientCAFile · cgroupDriver 등)
$ sudo cat /etc/kubernetes/kubelet.conf               # API 서버 주소 · 포트 (6443?)
$ sudo openssl x509 -noout -subject -issuer -enddate \
    -in /var/lib/kubelet/pki/kubelet-client-current.pem   # 인증서 만료 · 발급자

05. 네트워크 장애

1. CNI → kube-proxy → CoreDNS 순서로

2. 진단용 Pod로 직접 확인

$ kubectl run tmp --rm -it --image=busybox:1.36 --restart=Never -- sh
/ # nslookup kubernetes.default                   # DNS — 실패하면 CoreDNS 쪽
/ # nslookup web-service.default.svc.cluster.local
/ # wget -qO- -T 3 http://web-service:80          # Service IP — 실패하면 kube-proxy · Endpoints
/ # wget -qO- -T 3 http://10.244.1.5:8080          # Pod IP 직접 — 실패하면 CNI · NetworkPolicy · 앱

$ kubectl run net --rm -it --image=nicolaka/netshoot -- bash   # dig · curl · tcpdump가 다 든 이미지

순서가 중요해요. Pod IP → Service IP → 이름 순으로 확인하면 어느 층에서 끊겼는지 바로 보여요.

06. kubectl debug와 임시 컨테이너

1. 셸이 없는 컨테이너 들여다보기

보안 때문에 요즘 이미지는 셸조차 없는 경우가 많아요(distroless, 8부 01). 그러면 kubectl exec -it … -- sh가 executable file not found로 실패해요. 임시 컨테이너(ephemeral container, 1.25 GA)는 이미 실행 중인 Pod에 디버깅용 컨테이너를 잠깐 붙이는 기능이에요. Pod를 다시 만들지 않아요.

$ kubectl exec -it web -- sh
error: … exec: "sh": executable file not found in $PATH

$ kubectl debug -it web --image=busybox:1.36 --target=app
/ # ps aux                       # --target 덕분에 app 컨테이너의 프로세스가 보임
/ # wget -qO- localhost:8080     # 같은 Pod라 네트워크(localhost)도 공유
/ # cat /proc/1/root/etc/config.yaml   # app 컨테이너의 파일 시스템 엿보기

2. 세 가지 사용법

--profile로 디버그 컨테이너의 권한을 골라요: general(일반), baseline · restricted(제한), netadmin(tcpdump 등 네트워크 권한), sysadmin(노드 전체 권한). 필요한 만큼만 주고, 노드 디버깅이 끝나면 만든 Pod를 지워요(kubectl get pods에 node-debugger-…로 남아 있어요).

3. 16부 셀프 체크

1. “웹이 안 열려요”를 받았을 때 확인 순서는?

   입구(Ingress · LB) → Service · Endpoints → Pod 상태 → 컨테이너 로그 → 노드 → 컨트롤 플레인. 바깥에서 안으로 한 칸씩.
2. Service의 Endpoints가 비어 있으면 무엇을 비교하나요?

   Service의 selector와 Pod의 레이블(--show-labels). Pod가 Ready가 아니어도 빠져요.
3. Endpoints는 있는데 connection refused가 나요. 의심할 곳은?

   Service의 targetPort와 컨테이너가 실제로 듣는 포트가 다른지, 앱이 0.0.0.0이 아니라 127.0.0.1에만 열려 있지 않은지.
4. CrashLoopBackOff인 Pod의 원인을 보려면?

   kubectl logs --previous로 직전 컨테이너 로그, describe의 Last State 종료 코드를 봐요.
5. 종료 코드 137은 보통 무엇을 뜻하나요?

   SIGKILL — 메모리 limit 초과(OOMKilled)나 livenessProbe 실패로 강제 종료된 경우가 많아요.
6. 새 Pod가 Pending인데 Events에 아무것도 없어요. 무엇을 의심하나요?

   스케줄러. kubectl get pods -n kube-system으로 kube-scheduler 상태를 확인해요.
7. kubectl이 6443 connection refused로 실패하면 어떻게 조사하나요?

   컨트롤 플레인 노드에 접속해 crictl ps -a · crictl logs로 API 서버 컨테이너를 보고, /etc/kubernetes/manifests/kube-apiserver.yaml과 journalctl -u kubelet을 확인해요.
8. 노드 조건이 모두 Unknown이에요. 무슨 뜻인가요?

   kubelet이 상태 보고를 멈췄다는 뜻이에요. 노드에 들어가 systemctl status kubelet, journalctl -u kubelet을 봐요.
9. Pod IP로는 되는데 Service 이름으로는 안 돼요. 다음 확인은?

   Service IP로 시도해 봐요. IP로 되면 CoreDNS 문제, IP로도 안 되면 kube-proxy · Endpoints 문제예요.
10. CoreDNS가 CrashLoopBackOff이고 로그에 loop가 보여요. 원인은?

    노드의 resolv.conf가 로컬 DNS(127.0.0.53 등)를 가리켜 CoreDNS가 자기에게 질문을 되돌려 보내는 루프예요. kubelet의 resolvConf나 Corefile의 forward 대상을 바꿔요.
11. 셸이 없는 컨테이너를 조사하려면?

    kubectl debug -it <pod> --image=busybox --target=<컨테이너>로 임시 컨테이너를 붙여요.
12. ssh 없이 노드의 파일을 보려면?

    kubectl debug node/<노드> -it --image=busybox — 노드 파일 시스템이 /host에 붙어요. 끝나면 디버거 Pod를 지워요.

01. JSON Path

지금까지 kubectl get은 사람이 보기 좋은 표를 보여 줬어요. 그런데 “모든 노드의 CPU 수만”, “이 Pod의 이미지 이름만” 같은 딱 한 값이 필요할 때가 많아요. 스크립트에 넣거나 시험에서 답을 파일로 낼 때는 더 그래요. 그때 쓰는 게 JSON Path예요.

1. JSON Path 문법

kubectl이 주고받는 데이터는 사실 JSON이에요. YAML은 같은 구조를 다르게 적은 것뿐이라, -o yaml로 보던 그 트리를 JSON Path로 따라 내려갈 수 있어요. Dart로 치면 json['car']['wheels'][1]['model']를 짧은 문자열로 쓰는 셈이에요.

2. kubectl -o jsonpath

순서는 항상 같아요. ① -o json(또는 -o yaml)으로 구조를 보고, ② 원하는 값까지의 경로를 적고, ③ -o jsonpath='{…}'로 뽑아요. kubectl에서는 맨 앞의 $를 생략하고 .으로 시작해요. 여러 개를 조회하면 결과는 items 리스트 안에 들어 있어요.

$ kubectl get nodes -o json | less                       # ① 구조 보기
$ kubectl get pod web -o jsonpath='{.spec.containers[0].image}'
nginx:1.27
$ kubectl get nodes -o jsonpath='{.items[*].metadata.name}'
controlplane node01
$ kubectl get nodes -o jsonpath='{.items[*].metadata.name}{"\n"}{.items[*].status.capacity.cpu}{"\n"}'
controlplane node01
4 2
$ kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.capacity.cpu}{"\n"}{end}'
controlplane	4
node01	2

02. 출력 다듬기

1. custom-columns · sort-by

$ kubectl get nodes -o custom-columns=NODE:.metadata.name,CPU:.status.capacity.cpu
NODE           CPU
controlplane   4
node01         2

$ kubectl get nodes --sort-by=.status.capacity.cpu       # 정렬 (경로는 items[*] 아래 기준)
$ kubectl get pods --sort-by=.metadata.creationTimestamp # 오래된 순
$ kubectl get pv --sort-by=.spec.capacity.storage \
    -o custom-columns=NAME:.metadata.name,CAPACITY:.spec.capacity.storage

custom-columns의 경로에는 { }도 .items[*]도 안 써요. 항목 하나 기준의 경로만 적으면 kubectl이 항목마다 적용해요. 열 이름은 자유예요.

2. 출력 형식 한눈에

3. 고르기 — 레이블과 필드

$ kubectl get pods -l app=web                          # 같음
$ kubectl get pods -l 'env in (prod,stg),tier!=db'     # 집합 · 같지 않음 (3부 02)
$ kubectl get pods -l '!canary'                        # 그 레이블이 없는 것
$ kubectl get pods --field-selector status.phase=Running
$ kubectl get pods -A --field-selector spec.nodeName=node01   # node01의 모든 Pod
$ kubectl get pods -A --field-selector status.phase!=Running --no-headers | wc -l

레이블(-l)은 우리가 붙인 표시로, 필드(--field-selector)는 status.phase · spec.nodeName · metadata.name처럼 리소스마다 정해진 몇몇 필드로 걸러요.

03. 빠르게 쓰는 습관

1. YAML은 손으로 처음부터 쓰지 않는다

$ export do="--dry-run=client -o yaml"                  # 자주 쓰는 꼬리를 변수로
$ kubectl create deployment web --image=nginx --replicas=3 $do > web.yaml
$ kubectl run tmp --image=busybox $do -- sleep 3600 > pod.yaml
$ kubectl create service clusterip web --tcp=80:8080 $do
$ kubectl expose deployment web --port=80 --target-port=8080 $do
$ kubectl create configmap app --from-literal=LOG=info $do
$ kubectl create job once --image=busybox $do -- date
$ kubectl create cronjob tick --image=busybox --schedule="*/5 * * * *" $do -- date

$ kubectl explain deployment.spec.strategy              # 필드 설명
$ kubectl explain pod.spec.containers --recursive | less  # 하위 필드 전체 트리

2부 05의 명령형 · 선언형을 합친 방법이에요. 뼈대는 명령으로 정확하게 만들고, 명령으로 안 되는 부분(probe · volume · resources)만 YAML에서 고쳐요.

2. alias · 자동 완성 · kuberc

$ alias k=kubectl
$ source <(kubectl completion bash)        # zsh면 completion zsh
$ complete -o default -F __start_kubectl k  # k에도 자동 완성
$ k get po<Tab>                             # pods · 이름까지 자동 완성

kubectl 1.34부터 kuberc(beta)로 kubectl 자체에 alias와 기본 옵션을 설정할 수 있어요. 파일은 ~/.kube/kuberc예요. kubeconfig(접속 정보)와 달리 개인 취향만 담아요.

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
defaults:
  - command: delete
    options:
      - name: interactive      # 지우기 전에 항상 확인
        default: "true"
  - command: apply
    options:
      - name: server-side
        default: "true"
aliases:
  - name: getw                 # kubectl getw pods → kubectl get pods -o wide
    command: get
    options:
      - name: output
        default: wide

3. 자주 쓰는 손버릇

4. 17부 셀프 체크

1. $.car.wheels[*].model은 무엇을 뽑나요?

   car의 wheels 리스트에 있는 모든 항목의 model 값(리스트).
2. JSON Path 조건식에서 @는 무엇인가요?

   지금 검사하고 있는 리스트 항목 하나. [?(@.location == "rear-right")]처럼 써요.
3. $[0:3]은 몇 번째 항목들을 고르나요?

   0 · 1 · 2번째. 끝 번호(3)는 포함하지 않아요.
4. kubectl jsonpath에서 여러 객체를 조회할 때 경로는 무엇으로 시작하나요?

   .items[*] — 목록 결과는 items 리스트에 담겨 있어요.
5. 노드마다 “이름 탭 CPU”를 한 줄씩 출력하려면?

   -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.capacity.cpu}{"\n"}{end}'
6. custom-columns의 경로가 jsonpath와 다른 점은?

   { }와 .items[*] 없이 항목 하나 기준 경로만 적어요(NODE:.metadata.name).
7. PV를 용량 순으로 보려면?

   kubectl get pv --sort-by=.spec.capacity.storage
8. node01에서 도는 모든 Pod를 보려면?

   kubectl get pods -A --field-selector spec.nodeName=node01 (또는 -o wide 후 확인)
9. Deployment YAML을 빠르게 만드는 방법은?

   kubectl create deployment web --image=nginx --dry-run=client -o yaml > web.yaml로 뼈대를 만들고 필요한 부분만 고쳐요.
10. Pod의 probe 필드 이름이 기억나지 않으면?

    kubectl explain pod.spec.containers.livenessProbe (또는 --recursive).
11. 현재 컨텍스트의 기본 Namespace를 dev로 바꾸려면?

    kubectl config set-context --current --namespace=dev
12. kuberc와 kubeconfig의 차이는?

    kubeconfig는 클러스터 주소 · 인증 정보, kuberc는 alias · 기본 옵션 같은 개인 취향 설정(~/.kube/kuberc, 1.34 beta)이에요.