쿠버네티스 내부 동작

Kubernetes 컴포넌트의 내부 메커니즘과 데이터 흐름

---

Kubernetes 컴포넌트의 내부 메커니즘과 데이터 흐름

목표: Kubernetes가 어떻게 동작하는지 깊이 이해하고 문제를 진단할 수 있는 수준

---

🏗️ 컴포넌트 아키텍처

graph TB
    subgraph "Control Plane"
        API["🔷 API Server"]
        ETCD["🗄️ etcd"]
        SCHED["📅 Scheduler"]
        CM["🎮 Controller Manager"]
        
        API <--> ETCD
        SCHED --> API
        CM --> API
    end
    
    subgraph "Worker Node"
        KUBELET["🔧 kubelet"]
        PROXY["🌐 kube-proxy"]
        CRI["📦 Container Runtime"]
        
        KUBELET --> API
        KUBELET --> CRI
        PROXY --> API
    end
    
    CLI["💻 kubectl"] --> API

---

🗄️ etcd

역할

모든 클러스터 데이터의 분산 저장소.

graph LR
    API["API Server"] -->|"gRPC"| ETCD["etcd"]
    ETCD -->|"Watch"| API

특징:

• Raft 합의 알고리즘
• Key-Value 저장소
• Watch API로 변경 감지
• 백업 필수

주요 데이터

경로	내용
/registry/pods	Pod 정보
/registry/services	Service 정보
/registry/deployments	Deployment 정보
/registry/nodes	Node 정보

etcdctl 사용

# etcdctl 설치
apt-get install etcd-client

# 스냅샷 백업
ETCDCTL_API=3 etcdctl snapshot save backup.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

# 복원
ETCDCTL_API=3 etcdctl snapshot restore backup.db

# 데이터 조회
ETCDCTL_API=3 etcdctl get /registry/pods/default/my-pod

---

🔷 API Server

역할

모든 요청의 중앙 게이트웨이.

graph LR
    CLI["kubectl"] -->|"HTTP/REST"| API["API Server"]
    NODE["kubelet"] -->|"HTTP/REST"| API
    CTRL["Controller"] -->|"HTTP/REST"| API
    
    API -->|"인증"| AUTH["Authentication"]
    API -->|"인가"| RBAC["Authorization"]
    API -->|"변환"| ADM["Admission Control"]

요청 흐름

# 1. 인증 (Authentication)
# - 클라이언트 인증서, 토큰, 기본 인증

# 2. 인가 (Authorization)
# - RBAC, ABAC, Webhook

# 3. 어드미션 (Admission)
# - Mutating: 요청 수정
# - Validating: 요청 검증

어드미션 컨트롤러

# 기본 활성화된 컨트롤러
--enable-admission-plugins=NodeRestriction,NamespaceLifecycle,LimitRanger,ServiceAccount,DefaultStorageClass,ResourceQuota

# 커스텀 웹훅
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: my-webhook
webhooks:
- name: my-webhook.example.com
  clientConfig:
    service:
      name: webhook-service
      namespace: default
      path: "/validate"
    caBundle: <CA_BUNDLE>
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: ["apps"]
    apiVersions: ["v1"]
    resources: ["deployments"]

---

📅 Scheduler

역할

Pod를 적절한 Node에 배치.

graph TB
    subgraph "스케줄링 과정"
        PENDING["⏳ Pending Pod"] --> FILTER["🔍 필터링"]
        FILTER --> SCORE["📊 점수 계산"]
        SCORE --> BIND["🔗 바인딩"]
        BIND --> RUNNING["✅ Running"]
    end

스케줄링 단계

# 1. 필터링 (Predicates)
# - 리소스 충분?
# - 노드 셀렉터 일치?
# - 테인트/톨러레이션?
# - 볼륨 바인딩 가능?

# 2. 점수 계산 (Priorities)
# - 리소스 여유 (더 여유로운 노드 선호)
# - Pod 분산 (여러 노드에 분산)
# - 어피니티/안티어피니티

# 3. 바인딩
# - 선택된 노드에 Pod 할당

커스텀 스케줄러

apiVersion: v1
kind: Pod
metadata:
  name: custom-scheduled-pod
spec:
  schedulerName: my-custom-scheduler
  containers:
  - name: app
    image: nginx

---

🎮 Controller Manager

역할

클러스터 상태를 원하는 상태로 유지.

graph LR
    DESIRED["Desired State"] --> CTRL["Controller"]
    CURRENT["Current State"] --> CTRL
    CTRL -->|"조정"| ACTION["Action"]

주요 컨트롤러

컨트롤러	역할
Deployment	ReplicaSet 관리, 롤링 업데이트
ReplicaSet	Pod 복제본 수 유지
StatefulSet	상태유지 Pod 관리
DaemonSet	모든 노드에 Pod 배포
Job	배치 작업 완료 보장
CronJob	주기적 Job 실행
Node	노드 상태 모니터링
Endpoint	Service 엔드포인트 관리
ServiceAccount	토큰 관리

컨트롤러 루프

# 1. Watch API로 변경 감지
# 2. 현재 상태와 원하는 상태 비교
# 3. 차이를 해소하는 액션 수행
# 4. 반복

---

🔧 kubelet

역할

노드 에이전트. Pod 생명주기 관리.

graph TB
    KUBELET["kubelet"] -->|"CRI"| RUNTIME["Container Runtime"]
    KUBELET -->|"CNI"| NETWORK["Network Plugin"]
    KUBELET -->|"CSI"| STORAGE["Storage Plugin"]
    
    KUBELET -->|"상태 보고"| API["API Server"]

주요 기능

# 1. PodSpec 수신 (API Server)
# 2. 컨테이너 생성/실행 (CRI)
# 3. 볼륨 마운트 (CSI)
# 4. 네트워크 설정 (CNI)
# 5. 상태 보고 (API Server)
# 6. 프로브 실행 (Liveness, Readiness)
# 7. 리소스 모니터링

---

🐛 문제 해결

컴포넌트 로그

# Control Plane (Static Pod)
kubectl logs -n kube-system kube-apiserver-master
kubectl logs -n kube-system kube-scheduler-master
kubectl logs -n kube-system kube-controller-manager-master
kubectl logs -n kube-system etcd-master

# Worker Node
journalctl -u kubelet
kubectl logs -n kube-system kube-proxy-xxx

etcd 문제

# etcd 상태 확인
ETCDCTL_API=3 etcdctl endpoint health

# 리더 확인
ETCDCTL_API=3 etcdctl endpoint status --write-out=table

# 알람 확인
ETCDCTL_API=3 etcdctl alarm list

---

📋 체크리스트

• etcd 백업/복원
• API Server 요청 흐름
• 어드미션 컨트롤러
• 스케줄링 단계
• 컨트롤러 루프
• kubelet 기능
• 컴포넌트 로그 확인

---

🔗 관련 노트

• 01-01-K8s-아키텍처-이해 — 전체 아키텍처
• 02-11-Pod-실패-원인-분석 — 문제 해결
• 03-02-Operator-패턴 — 커스텀 컨트롤러

---

마지막 업데이트: 2026-06-01