Kubernetes 입문

Kubernetes 입문 — Pod·Deployment·Service 한 번에 정리. 컨테이너 하나는 Docker로 띄웠다. 그런데 수십 개를, 여러 서버에서, 죽으면 살리고 트래픽에 맞춰 늘리려면? 그게 쿠버네티스다. 오케스트레이션이 필요한 이유부터 핵심 오브젝트와 kubectl까지, 실제 매니페스트와 출력으로 정리한다.

---

들어가며

예전 Spark를 Kubernetes 위에 올리면 무엇이 달라지는가 글에서 쿠버네티스를 "컨테이너 워크로드를 운영하는 표준 운영 체계"라고 한 문단으로만 짧게 짚고 넘어갔다. 이번 글은 그 한 문단을 제대로 펼치는, 쿠버네티스 입문 상세판이다.

흐름은 이렇게 이어진다. Docker 입문에서 애플리케이션을 이미지로 만들고 컨테이너로 띄웠고, GitHub Actions로 CI/CD에서 그 이미지를 자동으로 빌드·배포했다. 그럼 다음 질문은 자연스럽다. "컨테이너 하나가 아니라 수십 개를, 여러 서버에 걸쳐, 죽으면 되살리고, 트래픽이 늘면 늘리면서 운영하려면?" 이 질문의 답이 컨테이너 오케스트레이션, 즉 쿠버네티스(Kubernetes, 줄여서 K8s)다.

쿠버네티스의 핵심 한 줄: "원하는 상태(desired state)를 선언하면, 클러스터가 알아서 그 상태를 유지한다." 사람이 컨테이너를 일일이 띄우고 감시하는 게 아니라, "나는 이게 3개 떠 있길 원해"라고 선언하면 시스템이 그걸 책임진다.

이 글에서는 왜 Docker만으로는 부족한지부터 시작해, 클러스터의 구조, 가장 작은 단위인 Pod, 선언적 관리와 자가복구를 담당하는 Deployment, 안정적인 진입점인 Service, 그리고 이 모든 걸 조작하는 kubectl까지 실제 매니페스트와 함께 정리한다.

---

1. 왜 Kubernetes인가 — Docker만으로 부족한 지점

Docker로 컨테이너 하나를 띄우는 건 쉽다. 문제는 실서비스 규모가 되는 순간이다. 컨테이너가 수십 개로 늘고, 서버도 여러 대가 되면 이런 일들을 누군가 해야 한다.

• 어느 컨테이너를 어느 서버에 배치할지 (리소스 여유를 보고)
• 컨테이너가 죽으면 자동으로 되살리기
• 트래픽이 늘면 개수를 늘리고, 줄면 줄이기 (스케일링)
• 새 버전을 무중단에 가깝게 교체하고, 문제 생기면 되돌리기 (롤링 업데이트·롤백)
• 죽고 살아나며 IP가 계속 바뀌는 컨테이너들에게 안정적인 주소로 트래픽 보내기

이걸 docker run과 셸 스크립트로 사람이 직접 하면, 서버 몇 대만 넘어가도 곧 한계에 부딪힌다. 이 운영 작업 전체를 자동화하는 시스템이 컨테이너 오케스트레이터이고, 그 사실상의 표준이 쿠버네티스다. 구글이 내부에서 쓰던 Borg에서 출발해 오픈소스로 공개됐고, 지금은 CNCF가 관리하는 클라우드 네이티브 운영의 기반이 됐다.

핵심 철학은 선언적(declarative)이라는 점이다. "이 명령을 실행해라"(명령형)가 아니라 "최종 상태가 이래야 한다"(선언형)를 적어두면, 쿠버네티스가 현재 상태와 비교해 그 차이를 끊임없이 메운다.

---

2. 클러스터의 구조 — 컨트롤 플레인과 워커 노드

쿠버네티스는 여러 서버를 묶어 하나의 클러스터(cluster)로 다룬다. 클러스터는 두 종류의 구성원으로 나뉜다.

• 컨트롤 플레인(Control Plane) — 클러스터의 두뇌. 무엇을 어디에 배치할지 결정하고 전체 상태를 관리한다.
• 워커 노드(Worker Node) — 실제로 컨테이너(Pod)를 실행하는 일꾼 서버들.

컨트롤 플레인의 주요 구성요소는 다음과 같다.

• API Server — 클러스터의 정문. kubectl을 비롯한 모든 요청이 여기를 거친다.
• Scheduler — 새 Pod를 어느 노드에 올릴지 결정한다.
• Controller Manager — "원하는 상태"와 "현재 상태"를 비교해 끊임없이 맞춘다. 자가복구의 주역이다.
• etcd — 클러스터의 모든 상태를 저장하는 키-값 데이터베이스.

워커 노드에는 kubelet(노드에서 Pod를 실제로 띄우고 상태를 보고), kube-proxy(네트워크 라우팅), 그리고 컨테이너 런타임(containerd 등, 실제 컨테이너 실행)이 돈다. 개발자는 보통 이 내부를 직접 만질 일이 없다. kubectl로 API Server에 "원하는 상태"를 던지면, 나머지는 클러스터가 알아서 처리한다.

---

3. 가장 작은 배포 단위 — Pod

쿠버네티스에서 컨테이너를 직접 다루지는 않는다. 최소 단위는 Pod다. Pod는 컨테이너 하나(또는 긴밀히 묶인 몇 개)를 감싼 껍데기로, 같은 Pod 안의 컨테이너들은 네트워크(같은 IP)와 스토리지를 공유한다. 대부분의 경우 "Pod 하나 = 컨테이너 하나"로 생각하면 된다.

중요한 성질이 하나 있다. Pod는 일회용(ephemeral)이라는 점이다. 죽으면 고쳐 쓰는 게 아니라 버리고 새로 만든다. 그리고 새로 뜬 Pod는 IP가 바뀐다. 이 "Pod는 언제든 사라지고 새로 생긴다"는 전제가 뒤에 나올 Deployment(자가복구)와 Service(안정적 주소)가 존재하는 이유다.

그래서 실무에서 Pod를 직접 만드는 일은 드물다. Pod를 직접 만들면 그 Pod가 죽었을 때 아무도 되살리지 않는다. 대신 Pod를 관리해주는 상위 오브젝트 — Deployment를 쓴다.

---

4. 선언적 관리와 자가복구 — Deployment

Deployment는 "이 Pod를 몇 개로, 어떤 이미지로 유지해라"를 선언하는 오브젝트다. 그러면 쿠버네티스가 그 개수를 항상 맞춘다. Pod가 죽으면 새로 띄우고, 개수를 바꾸면 거기에 맞춘다. 이 일은 내부적으로 ReplicaSet이 담당한다.

CI/CD에서 ghcr.io에 올린 이미지를 3개로 띄우는 Deployment 매니페스트는 이렇게 생겼다.

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3                # Pod를 항상 3개 유지 (desired state)
  selector:
    matchLabels:
      app: myapp
  template:                  # 이 틀로 Pod를 찍어낸다
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: myapp
          image: ghcr.io/jinoism/myapp:main   # CI/CD에서 빌드·푸시한 이미지
          ports:
            - containerPort: 3000

이 파일을 kubectl apply로 클러스터에 던지면, Pod 3개가 뜬다.

kubectl apply -f deployment.yaml
# deployment.apps/myapp created

kubectl get pods

NAME                     READY   STATUS    RESTARTS   AGE
myapp-7d9f8c6b4c-2xk9p   1/1     Running   0          12s
myapp-7d9f8c6b4c-8fmlq   1/1     Running   0          12s
myapp-7d9f8c6b4c-q7r2t   1/1     Running   0          12s

이제 자가복구를 눈으로 확인해보자. Pod 하나를 강제로 지운다.

kubectl delete pod myapp-7d9f8c6b4c-2xk9p
kubectl get pods

NAME                     READY   STATUS    RESTARTS   AGE
myapp-7d9f8c6b4c-8fmlq   1/1     Running   0          40s
myapp-7d9f8c6b4c-q7r2t   1/1     Running   0          40s
myapp-7d9f8c6b4c-vv5n8   1/1     Running   0          3s    ← 새로 생성됨

지운 Pod 자리에 새 Pod가 자동으로 생겼다. "나는 3개를 원해"라는 선언을 쿠버네티스가 계속 지키는 것이다. 개수를 바꾸는 것도 한 줄이다.

kubectl scale deployment myapp --replicas=5   # 5개로 확장

새 버전 배포도 이미지 태그만 바꿔 apply하면, 쿠버네티스가 Pod를 하나씩 교체(롤링 업데이트)하며 무중단에 가깝게 갱신한다. 문제가 생기면 kubectl rollout undo로 되돌린다.

---

5. 안정적인 진입점 — Service

3번에서 봤듯 Pod는 죽고 살아나며 IP가 바뀐다. 그러면 다른 서비스나 사용자는 어떤 주소로 접속해야 할까? 바뀌는 Pod IP를 직접 부를 수는 없다. 이 문제를 푸는 게 Service다.

Service는 변하지 않는 가상 IP(와 이름)를 제공하고, 그 뒤의 여러 Pod들로 트래픽을 로드밸런싱한다. Pod가 교체돼도 Service 주소는 그대로다. 라벨 셀렉터(app: myapp)로 "어떤 Pod들에게 보낼지"를 고른다.

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: myapp
spec:
  selector:
    app: myapp          # 이 라벨을 가진 Pod들로 트래픽 전달
  ports:
    - port: 80          # Service가 받는 포트
      targetPort: 3000  # 전달할 Pod(컨테이너) 포트
  type: ClusterIP       # 노출 방식 (기본값)

type이 노출 범위를 정한다.

• ClusterIP (기본) — 클러스터 내부에서만 접근. 서비스 간 내부 통신용.
• NodePort — 각 노드의 특정 포트로 외부에서 접근.
• LoadBalancer — 클라우드의 로드밸런서를 붙여 외부에 노출. EKS·GKE 같은 매니지드 환경에서 흔히 쓴다.

여러 Service를 하나의 도메인/경로 규칙으로 묶어 외부에 노출하려면 그 위에 Ingress(또는 Gateway API)를 둔다. 입문 단계에선 "Service = 바뀌는 Pod들 앞의 고정 주소 + 로드밸런서"로 이해하면 충분하다.

---

6. kubectl — 손에 익혀야 할 기본 명령

kubectl은 클러스터와 대화하는 CLI다. 거의 모든 작업이 이 명령으로 이뤄진다. 먼저 클러스터와 노드 상태부터 본다.

kubectl get nodes

NAME       STATUS   ROLES           AGE   VERSION
node-1     Ready    control-plane   5d    v1.36.2
node-2     Ready    <none>          5d    v1.36.2
node-3     Ready    <none>          5d    v1.36.2

자주 쓰는 명령을 표로 정리하면 이렇다.

명령어	하는 일
kubectl apply -f 파일.yaml	매니페스트의 상태를 클러스터에 적용 (생성·갱신)
kubectl get pods / get deploy / get svc	Pod·Deployment·Service 목록 보기
kubectl describe pod 이름	특정 리소스의 상세 정보·이벤트 (장애 원인 추적)
kubectl logs 이름	Pod 로그 보기 (-f로 실시간)
kubectl exec -it 이름 -- sh	실행 중인 Pod 안으로 셸 진입
kubectl scale deploy 이름 --replicas=N	레플리카 개수 조정
kubectl rollout undo deploy 이름	직전 배포로 롤백
kubectl delete -f 파일.yaml	매니페스트가 만든 리소스 삭제

장애가 났을 때 가장 먼저 보는 건 보통 describe와 logs다. describe는 "왜 이 Pod가 안 뜨는가"(이미지 pull 실패, 스케줄링 실패 등)를 이벤트로 보여주고, logs는 컨테이너 내부에서 무슨 일이 있었는지 알려준다. Spark on Kubernetes 글에서 "디버깅 관점이 애플리케이션에서 클러스터까지 넓어진다"고 했던 게 바로 이 지점이다.

---

7. 언제 Kubernetes를 써야 하나 — 그리고 매니지드

쿠버네티스는 강력하지만 공짜가 아니다. 클러스터 자체를 운영하는 부담, 네트워킹·스토리지·보안(RBAC·Secret) 설계, 학습 곡선이 모두 비용이다. 그래서 판단이 필요하다.

• 잘 맞는 경우: 서비스가 여러 개로 쪼개져 있고(마이크로서비스), 트래픽 변동이 크거나, 무중단 배포·자동 확장·복원력이 중요하고, 운영을 표준화하고 싶을 때.
• 과한 경우: 작은 단일 서비스, 트래픽이 안정적이고, 팀의 인프라 여력이 작을 때. 이럴 땐 Docker Compose나 매니지드 PaaS(Vercel 등)가 더 합리적이다.

직접 클러스터를 구축·운영하는 부담을 줄이려면 매니지드 쿠버네티스를 쓴다. AWS의 EKS, Google의 GKE, Azure의 AKS가 대표적이다. 컨트롤 플레인 운영을 클라우드가 대신 맡아주므로, 팀은 워크로드(매니페스트)에 집중할 수 있다. 입문·학습용으로 로컬에서 가볍게 띄우려면 minikube나 kind가 좋다.

기술적으로 쓸 수 있다는 것과 조직에 이득이라는 것은 다르다. "남들이 쓰니까"가 아니라, 위의 "잘 맞는 경우"에 해당할 때 도입하는 게 맞다.

---

마치며

쿠버네티스는 "원하는 상태를 선언하면 클러스터가 그 상태를 유지한다"는 선언적 운영 모델 위에 서 있다. Pod(최소 실행 단위)를 Deployment(개수 유지·자가복구·롤링 업데이트)가 관리하고, Service(고정 주소·로드밸런싱)가 그 앞을 지키며, 이 모든 걸 kubectl로 조작한다. 이 네 가지만 손에 익혀도 쿠버네티스의 8할은 읽힌다.

핵심만 다시 짚으면, 컨테이너는 Pod로 감싸고, Pod는 Deployment로 유지하며, 접근은 Service로 안정화한다. 그리고 그 토대에는 "현재 상태를 원하는 상태로 끊임없이 맞춘다"는 컨트롤 플레인의 일이 있다.

이로써 Docker(컨테이너) → CI/CD(자동 빌드·배포) → 쿠버네티스(여러 서버에서의 운영)로 이어지는 인프라 시리즈가 한 바퀴 돌았다. 컨테이너 하나를 만들던 데서 출발해, 그것을 자동으로 배포하고, 규모 있게 운영하는 그림까지 온 셈이다.

---

참고 출처

• Kubernetes Documentation — Overview — https://kubernetes.io/docs/concepts/overview/
• Kubernetes Documentation — Pods — https://kubernetes.io/docs/concepts/workloads/pods/
• Kubernetes Documentation — Deployments — https://kubernetes.io/docs/concepts/workloads/controllers/deployment/
• Kubernetes Documentation — Service — https://kubernetes.io/docs/concepts/services-networking/service/
• Kubernetes Documentation — Command line tool (kubectl) — https://kubernetes.io/docs/reference/kubectl/
• CNCF Artwork — Kubernetes logos (SVG/PNG) — https://github.com/cncf/artwork/tree/main/projects/kubernetes

Kubernetes 및 Kubernetes 로고는 The Linux Foundation의 등록 상표이며, 본 글에서는 식별·설명 목적으로만 사용했습니다.