[DevOps] Kubernetes 초보자 가이드 (백엔드 개발자를 위한 입문)

0. 개요

1. 핵심 개념과 아키텍처(K8s 101)
   • 1-1. 클러스터·노드·파드·컨트롤러
   • 1-2. 오브젝트(Deployment/Service/ConfigMap/Secret)
2. 로컬 실습 환경 준비(kubectl, kind/minikube)
   • 2-1. 설치 및 첫 클러스터 생성
   • 2-2. 컨텍스트·네임스페이스 기본
3. 첫 백엔드 앱 배포(컨테이너 → 쿠버네티스)
   • 3-1. Docker 이미지 빌드/푸시
   • 3-2. Deployment·Service YAML 작성
4. 구성 관리와 헬스체크
   • 4-1. ConfigMap/Secret 주입
   • 4-2. Liveness/Readiness Probe
5. 스케일링과 롤링 업데이트
   • 5-1. HPA(오토스케일)
   • 5-2. 롤링/카나리 전략
6. 네트워킹과 Ingress
   • 6-1. Service 타입(ClusterIP/NodePort/LoadBalancer)
   • 6-2. Ingress Controller·도메인·TLS
7. 스토리지와 상태ful 워크로드
   • 7-1. Volume/PVC/StorageClass
   • 7-2. StatefulSet 사용 패턴
8. 관측성과 디버깅
   • 8-1. 로그/메트릭/트레이싱
   • 8-2. kubectl 디버깅 치트시트
9. 보안 기초와 권한
   • 9-1. RBAC/ServiceAccount
   • 9-2. 네트워크 폴리시·이미지 보안
10. 배포 자동화와 GitOps
    • 10-1.Helm/Kustomize
    • 10-2. Argo CD 개요
11. 운영 팁과 비용 최적화
    • 11-1. 리소스 요청/제한·노드풀
    • 11-2. 네임스페이스·라벨링 전략
12. 체크리스트 & 학습 로드맵
    • 12-1. 오늘 바로 해볼 것
    • 12-2. 30일 로드맵
13. 결론 요약
14. FAQ

---

Kubernetes 초보자 가이드 (백엔드 개발자를 위한 입문)

이 가이드는 백엔드 개발자가 컨테이너 → 쿠버네티스로 자연스럽게 넘어갈 수 있도록 핵심 개념과 실습 흐름을 한 번에 정리합니다. 로컬 클러스터로 시작해 첫 배포, 구성/스케일링, 네트워킹, 보안·관측성, Helm/GitOps까지 “실무에 바로 쓰는” 순서로 안내합니다.

1. 핵심 개념과 아키텍처(K8s 101)

1-1. 클러스터·노드·파드·컨트롤러

• 클러스터: 컨트롤 플레인 + 워커 노드 집합.
• 노드: 컨테이너가 도는 머신(VM/물리).
• 파드(Pod): 배포 최소 단위(하나 이상의 컨테이너 + 같은 네트워크/스토리지).
• 컨트롤러: 원하는 상태를 맞추는 오브젝트(Deployment, StatefulSet 등).

1-2. 오브젝트(Deployment/Service/ConfigMap/Secret)

• Deployment: 파드의 수명과 롤링 업데이트 관리.
• Service: 파드 집합의 안정된 접근 지점(클러스터 내부/외부 노출).
• ConfigMap/Secret: 애플리케이션 설정과 비밀값을 이미지 밖에서 주입.

2. 로컬 실습 환경 준비(kubectl, kind/minikube)

2-1. 설치 및 첫 클러스터 생성

# macOS 예시 (brew) brew install kubectl kind kind create cluster --name demo kubectl get nodes

2-2. 컨텍스트·네임스페이스 기본

kubectl config get-contexts kubectl config use-context kind-demo kubectl create namespace app kubectl -n app get all

3. 첫 백엔드 앱 배포(컨테이너 → 쿠버네티스)

3-1. Docker 이미지 빌드/푸시

# 예시: 간단한 Go/Node/Java API 이미지를 레지스트리에 푸시 docker build -t registry.example.com/app:1.0.0 . docker push registry.example.com/app:1.0.0

3-2. Deployment·Service YAML 작성

apiVersion: apps/v1 kind: Deployment metadata: { name: app, namespace: app, labels: { app: app } } spec: replicas: 2 selector: { matchLabels: { app: app } } template: metadata: { labels: { app: app } } spec: containers: - name: app image: registry.example.com/app:1.0.0 ports: [ { containerPort: 8080 } ] --- apiVersion: v1 kind: Service metadata: { name: app, namespace: app } spec: type: ClusterIP selector: { app: app } ports: [ { port: 80, targetPort: 8080 } ]

kubectl apply -f app.yaml kubectl -n app port-forward svc/app 8080:80 # http://localhost:8080

4. 구성 관리와 헬스체크

4-1. ConfigMap/Secret 주입

apiVersion: v1 kind: ConfigMap metadata: { name: app-config, namespace: app } data: APP_ENV: "dev" --- apiVersion: v1 kind: Secret metadata: { name: app-secret, namespace: app } type: Opaque stringData: DB_PASSWORD: "changeme"

# Deployment에 주입 (발췌) envFrom: - configMapRef: { name: app-config } - secretRef: { name: app-secret }

4-2. Liveness/Readiness Probe

# 컨테이너 사양에 추가 (발췌) livenessProbe: httpGet: { path: /healthz, port: 8080 } initialDelaySeconds: 10 readinessProbe: httpGet: { path: /ready, port: 8080 } initialDelaySeconds: 5

5. 스케일링과 롤링 업데이트

5-1. HPA(오토스케일)

kubectl autoscale deployment app -n app --cpu-percent=70 --min=2 --max=6 kubectl -n app get hpa

5-2. 롤링/카나리 전략

• 롤링: maxSurge/maxUnavailable로 점진 교체.
• 카나리: 라벨로 v1/v2를 나눠 Service에 가중 라우팅(Ingress/서비스 메시).

# Deployment 전략 (발췌) strategy: rollingUpdate: { maxSurge: 1, maxUnavailable: 0 } type: RollingUpdate

6. 네트워킹과 Ingress

6-1. Service 타입(ClusterIP/NodePort/LoadBalancer)

• ClusterIP: 내부 통신 기본.
• NodePort: 각 노드 고정 포트로 외부 노출(개발/테스트용).
• LoadBalancer: 클라우드 LB 연동(운영 기본).

6-2. Ingress Controller·도메인·TLS

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app namespace: app annotations: kubernetes.io/ingress.class: nginx spec: tls: - hosts: [ "api.example.com" ] secretName: tls-cert rules: - host: api.example.com http: paths: - path: / pathType: Prefix backend: service: { name: app, port: { number: 80 } }

7. 스토리지와 상태ful 워크로드

7-1. Volume/PVC/StorageClass

apiVersion: v1 kind: PersistentVolumeClaim metadata: { name: data, namespace: app } spec: accessModes: [ "ReadWriteOnce" ] resources: { requests: { storage: 5Gi } } storageClassName: standard

7-2. StatefulSet 사용 패턴

• DB/메시지 브로커 등 정체성과 순서가 필요한 워크로드.
• 각 파드에 고유 PVC가 바인딩됩니다.

8. 관측성과 디버깅

8-1. 로그/메트릭/트레이싱

• 로그: kubectl -n app logs deploy/app -f
• 메트릭: Prometheus + Grafana(리소스/HPA 지표).
• 트레이싱: OpenTelemetry SDK → OTLP 수집기.

8-2. kubectl 디버깅 치트시트

kubectl -n app describe pod <pod> # 이벤트·이슈 kubectl -n app exec -it deploy/app -- sh # 컨테이너 셸 kubectl get events --sort-by=.lastTimestamp kubectl -n app rollout status deploy/app kubectl -n app top pods # 리소스 사용량

9. 보안 기초와 권한

9-1. RBAC/ServiceAccount

apiVersion: v1 kind: ServiceAccount metadata: { name: app-sa, namespace: app } --- apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: { name: app-role, namespace: app } rules: - apiGroups: [""] resources: ["configmaps"] verbs: ["get","list"] --- kind: RoleBinding apiVersion: rbac.authorization.k8s.io/v1 metadata: { name: app-rb, namespace: app } subjects: [ { kind: ServiceAccount, name: app-sa, namespace: app } ] roleRef: { kind: Role, name: app-role, apiGroup: rbac.authorization.k8s.io }

9-2. 네트워크 폴리시·이미지 보안

• NetworkPolicy로 기본 거부 후 필요한 통신만 허용.
• 이미지 스캔·서명(cosign), 루트리스 컨테이너 권장.

10. 배포 자동화와 GitOps

10-1. Helm/Kustomize

# Helm 배포 예시 helm upgrade --install app charts/app -n app --set image.tag=1.0.1

10-2. Argo CD 개요

• Git 선언(YAML/Helm)을 싱크하여 자동 배포.
• PR 머지 → 스테이징 → 승인 → 프로덕션 흐름 표준화.

11. 운영 팁과 비용 최적화

11-1. 리소스 요청/제한·노드풀

• requests/limits를 현실적으로 설정(과도하면 스케줄 실패, 과소하면 OOM).
• 워크로드 성격별 노드풀 분리(일반/고메모리/GPU, 스팟 혼합).

11-2. 네임스페이스·라벨링 전략

• 스테이지(dev/stg/prod)·팀·서비스 기준으로 분리.
• 라벨/어노테이션으로 선택·관측·비용을 모두 잡기.

12. 체크리스트 & 학습 로드맵

12-1. 오늘 바로 해볼 것

• kind로 클러스터 생성 → app 네임스페이스 만들기.
• 간단한 API 이미지를 배포하고 Service로 노출.
• ConfigMap/Secret 주입, Readiness Probe 추가.

12-2. 30일 로드맵

• Ingress + TLS, HPA, Helm 차트화.
• Prometheus/Grafana 관측, RBAC/NetworkPolicy.
• GitOps(Argo CD)로 PR 기반 배포 파이프라인 완성.

13. 결론 요약

Kubernetes는 “원하는 상태를 선언하고, 컨트롤러가 맞춰준다”가 본질입니다. 백엔드 개발자에게 중요한 것은 Deployment/Service/ConfigMap/Secret 4종의 숙달, 헬스체크·스케일링·네트워킹의 표준화, 그리고 관측/보안을 기본값으로 두는 습관입니다. 로컬에서 시작해 작은 성공을 쌓고, Helm/GitOps로 자동화하면 운영 복잡도는 크게 낮아집니다.

14. FAQ

- Docker Compose만 쓰던 팀도 바로 옮길 수 있나요?

가능합니다. 컨테이너는 그대로 쓰고, 서비스 디스커버리·스케일링·롤링 업데이트를 Kubernetes 오브젝트로 치환하면 됩니다. 초기엔 dev/stg 한 곳부터 시작하세요.

- Ingress 없이도 외부 노출이 되나요?

클라우드 환경에선 Service 타입을 LoadBalancer로 설정하면 됩니다. 도메인·TLS, 라우팅 규칙이 필요하면 Ingress가 더 유연합니다.

- HPA가 작동하려면 무엇이 필요하죠?

메트릭 서버가 필요합니다(클러스터에 metrics-server 설치). 그리고 파드에 CPU/메모리 requests가 정의되어 있어야 합니다.