컨테이너 오케스트레이션 실무 가이드

Kubernetes 완전 가이드

Kubernetes의 기본 개념과 아키텍처부터 kubectl, Pod, Deployment, Service, ConfigMap, Secret, Ingress, HPA와 Helm까지 실무 예제로 정리합니다.

Pod
Deployment
Service
Ingress
HPA
Helm

핵심 요약
Kubernetes는 컨테이너를 직접 실행하는 도구가 아니라 원하는 상태를 선언하고 배포·복구·확장·네트워크를 자동화하는 운영 플랫폼입니다. YAML 문법뿐 아니라 resource, probe, rollout, secret과 장애 복구 기준을 함께 이해해야 합니다.

1. Kubernetes란?

Kubernetes(K8s)는 컨테이너화된 애플리케이션의 배포, 확장과 자가 치유를 자동화하는 오픈소스 오케스트레이션 플랫폼입니다. 사용자는 원하는 상태를 선언하고 Kubernetes 컨트롤러가 실제 상태를 지속적으로 원하는 상태에 맞춥니다.

기능	설명
자동 배포와 롤백	선언적 설정을 기반으로 롤링 업데이트와 이전 버전 복구를 수행합니다.
자가 치유	비정상 Pod를 재시작하고 노드 장애 시 다른 노드로 재스케줄링합니다.
수평 확장	CPU·메모리 등의 지표를 기준으로 Pod 수를 조정합니다.
서비스 디스커버리	DNS와 Service를 이용해 안정적인 접근 경로를 제공합니다.
설정 관리	ConfigMap과 Secret으로 애플리케이션 설정을 이미지에서 분리합니다.

Manifest
원하는 상태

API Server
요청 수신

Scheduler
노드 배치

Kubelet
Pod 실행

Controller
상태 유지

2. Kubernetes 아키텍처

영역	구성 요소	역할
Control Plane	kube-apiserver	kubectl과 내부 구성 요소 요청의 진입점입니다.
	etcd	클러스터 상태를 저장하는 분산 key-value 저장소입니다.
	kube-scheduler	Pod를 실행할 노드를 결정합니다.
	kube-controller-manager	Deployment, ReplicaSet 등의 원하는 상태를 유지합니다.
Worker Node	kubelet	Pod를 실행하고 상태를 보고합니다.
	kube-proxy	Service 트래픽 전달을 위한 네트워크 규칙을 관리합니다.
	Container Runtime	containerd 또는 CRI-O가 실제 컨테이너를 실행합니다.

3. kubectl 설치와 기본 명령

Bash

# macOS 설치
brew install kubectl
kubectl version --client

# Minikube 로컬 클러스터
brew install minikube
minikube start
minikube status
minikube dashboard

자주 사용하는 명령

# 조회
kubectl get pods
kubectl get pods -n kube-system
kubectl get pods -A
kubectl get pods -o wide
kubectl get all -n production

# 상세 정보와 이벤트
kubectl describe pod myapp-abcde -n production
kubectl get events -n production --sort-by=.metadata.creationTimestamp

# 로그
kubectl logs myapp-abcde -n production
kubectl logs myapp-abcde -n production -f --tail=100
kubectl logs myapp-abcde -n production -c app

# 컨테이너 접속
kubectl exec -it myapp-abcde -n production -- /bin/sh

# 선언적 적용
kubectl apply -f manifest.yaml
kubectl diff -f manifest.yaml
kubectl delete -f manifest.yaml

# 포트 포워딩
kubectl port-forward pod/myapp-abcde 8080:3000

# 컨텍스트 확인
kubectl config get-contexts
kubectl config current-context
kubectl config use-context prod-cluster

운영 작업 전에는 현재 context와 namespace를 확인하세요. 개발·운영 kubeconfig와 터미널 표시를 분리하면 실수를 줄일 수 있습니다.

4. Pod

Pod는 Kubernetes의 최소 배포 단위입니다. 하나 이상의 컨테이너가 네트워크와 스토리지를 공유합니다. 실제 운영에서는 Pod를 직접 만들기보다 Deployment, StatefulSet 또는 Job으로 관리합니다.

pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: myapp
  labels:
    app: myapp
    version: "1.0"
spec:
  containers:
    - name: app
      image: myapp:1.0.0
      ports:
        - containerPort: 3000
      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"
        limits:
          cpu: "500m"
          memory: "512Mi"
      readinessProbe:
        httpGet:
          path: /ready
          port: 3000
        initialDelaySeconds: 5
        periodSeconds: 5
      livenessProbe:
        httpGet:
          path: /health
          port: 3000
        initialDelaySeconds: 15
        periodSeconds: 10

Probe	실패 시 동작	목적
startupProbe	초기 구동 완료 전 다른 probe를 지연합니다.	시작 시간이 긴 애플리케이션
readinessProbe	Service endpoint에서 Pod를 제외합니다.	트래픽 수신 가능 여부
livenessProbe	컨테이너를 재시작합니다.	복구 불가능한 비정상 상태 감지

livenessProbe를 지나치게 민감하게 설정하면 일시적인 부하에도 컨테이너가 반복 재시작될 수 있습니다. readiness와 liveness의 목적을 분리하고 실제 부하 조건에서 임계값을 검증하세요.

5. Deployment와 롤링 업데이트

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: production
spec:
  replicas: 3
  revisionHistoryLimit: 5
  selector:
    matchLabels:
      app: myapp
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: app
          image: myapp:2.0.0
          ports:
            - containerPort: 3000
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"
          readinessProbe:
            httpGet:
              path: /ready
              port: 3000
            periodSeconds: 5

롤링 업데이트와 롤백

kubectl set image deployment/myapp \
  app=myapp:2.1.0 \
  -n production

kubectl rollout status deployment/myapp -n production
kubectl rollout history deployment/myapp -n production
kubectl rollout undo deployment/myapp -n production

6. Service

Pod IP는 재생성될 때 변경될 수 있습니다. Service는 label selector로 Pod 그룹을 선택하고 안정적인 DNS와 가상 IP를 제공합니다.

service.yaml

apiVersion: v1
kind: Service
metadata:
  name: myapp
  namespace: production
spec:
  selector:
    app: myapp
  ports:
    - name: http
      port: 80
      targetPort: 3000
  type: ClusterIP

유형	접근 범위	용도
ClusterIP	클러스터 내부	서비스 간 통신의 기본 유형
NodePort	노드 IP와 고정 포트	개발·테스트 또는 외부 LB 연동
LoadBalancer	클라우드 Load Balancer	외부 TCP·UDP 서비스 공개
ExternalName	외부 DNS 이름	외부 서비스를 클러스터 내부 이름으로 참조

7. ConfigMap과 Secret

config-secret.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: myapp-config
  namespace: production
data:
  APP_ENV: production
  LOG_LEVEL: info
---
apiVersion: v1
kind: Secret
metadata:
  name: myapp-secret
  namespace: production
type: Opaque
stringData:
  DB_PASSWORD: change-me
  API_KEY: change-me

Kubernetes Secret은 기본적으로 Base64 인코딩이며 자체적으로 안전한 암호 저장소가 아닙니다. etcd 암호화, RBAC과 외부 Secret Manager 연동을 함께 검토하세요.

8. Ingress

Ingress는 HTTP와 HTTPS 트래픽을 host 또는 path 기준으로 Service에 전달합니다. Ingress 리소스와 별도로 NGINX Ingress Controller 같은 구현체가 필요합니다.

ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp
  namespace: production
spec:
  ingressClassName: nginx
  rules:
    - host: myapp.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 80
          - path: /
            pathType: Prefix
            backend:
              service:
                name: frontend-service
                port:
                  number: 80

9. HPA 수평 자동 확장

hpa.yaml

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: myapp
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  minReplicas: 2
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60

CPU 사용률 기반 HPA는 컨테이너에 resource request가 설정되어 있어야 정상 계산됩니다. 요청 수나 queue 길이가 중요한 서비스는 사용자 정의 지표도 함께 검토하세요.

10. Helm

Helm은 Kubernetes 애플리케이션을 재사용 가능한 Chart로 패키징하고 환경별 값과 배포 이력을 관리하는 패키지 관리자입니다.

Bash

brew install helm
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

helm upgrade --install my-pg bitnami/postgresql \
  --namespace database \
  --create-namespace \
  --set auth.postgresPassword='change-me'

helm list -A
helm history my-pg -n database
helm rollback my-pg 1 -n database

11. 다음 단계

GitOps: Argo CD 또는 Flux
서비스 메시: Istio 또는 Linkerd
모니터링: Prometheus와 Grafana
로깅: Fluent Bit, Loki 또는 Elasticsearch
보안: NetworkPolicy, Pod Security, image scanning
자격: CKA와 CKAD

12. Kubernetes 실무 설계

결정 지점	확인 질문	실무 기준
Workload	무상태, 상태 저장, 배치 작업 중 어느 유형인가?	Deployment, StatefulSet, Job을 목적에 맞게 선택합니다.
Resource	정상·최대 부하에 필요한 CPU와 메모리는 얼마인가?	측정 결과를 기준으로 requests와 limits를 설정합니다.
네트워크	어떤 서비스가 내부 또는 외부에 공개되는가?	Service, Ingress, NetworkPolicy와 TLS 경계를 구분합니다.
배포	새 버전 실패 시 얼마나 빠르게 복구할 수 있는가?	readiness, rollout status와 rollback 절차를 자동화합니다.

13. 운영 기준

모든 컨테이너에 requests를 설정합니다.
startup, readiness와 liveness probe 역할을 분리합니다.
PDB와 topology spread로 계획된 중단과 노드 장애에 대비합니다.
Namespace별 ResourceQuota와 LimitRange를 적용합니다.
RBAC과 ServiceAccount를 최소 권한으로 구성합니다.
로그, metric, event와 audit log를 중앙에서 수집합니다.
영구 데이터의 backup과 restore 절차를 실제로 검증합니다.

14. 검증 전략

품질 축	검증 방법	완료 기준
Manifest	서버 dry-run, schema validation과 Helm lint	API 버전과 필수 필드 오류 없이 렌더링됩니다.
보안	privileged, root, hostPath와 과도한 RBAC 검사	조직의 admission policy를 통과합니다.
기능	readiness, Service와 Ingress 경로 확인	핵심 사용자 시나리오가 정상 동작합니다.
배포 안정성	rolling, canary와 rollback 리허설	서비스 중단 없이 변경과 복구가 가능합니다.
장애 대응	Pod 삭제, node drain과 dependency 장애 재현	정의한 복구 시간 안에 정상 상태로 돌아옵니다.

배포 전 검증

kubectl apply --dry-run=server -f manifests/
kubectl diff -f manifests/
helm lint ./chart
helm template myapp ./chart -f values-prod.yaml > rendered.yaml
kubectl rollout status deployment/myapp -n production --timeout=5m

마무리

Kubernetes 학습은 Pod와 Deployment YAML 작성에서 시작하지만 실제 운영 품질은 resource, probe, Service, Ingress, 보안, 관측과 복구 전략에서 결정됩니다. 작은 로컬 클러스터에서 동작 원리를 익힌 뒤 배포 자동화와 장애 복구까지 단계적으로 확장하는 것이 좋습니다.

핵심 정리

Pod를 직접 운영하기보다 적절한 workload controller를 사용합니다.
resource request, readiness와 rollout 전략을 배포 전에 정의합니다.
Service와 Ingress의 역할을 구분합니다.
ConfigMap과 Secret을 애플리케이션 이미지에서 분리합니다.
manifest validation, rollback과 장애 복구 훈련을 자동화합니다.

원문: AI DevOps Korea Kubernetes 가이드

'개발 가이드 > Cloud Devops' 카테고리의 다른 글

[Cloud Devops] Kubernetes 심화/실무 완전 가이드 (0)	2026.07.19

Plog Dev Insight - 클라우드, 아키텍처, 개발 .. 블로그

[Cloud Devops] Kubernetes 완전 가이드

Kubernetes 완전 가이드

1. Kubernetes란?

2. Kubernetes 아키텍처

3. kubectl 설치와 기본 명령

4. Pod

5. Deployment와 롤링 업데이트

6. Service

7. ConfigMap과 Secret

8. Ingress

9. HPA 수평 자동 확장

10. Helm

11. 다음 단계

12. Kubernetes 실무 설계

13. 운영 기준

14. 검증 전략

마무리

'개발 가이드 > Cloud Devops' 카테고리의 다른 글

댓글

티스토리툴바

[Cloud Devops] Kubernetes 완전 가이드

Kubernetes 완전 가이드

1. Kubernetes란?

2. Kubernetes 아키텍처

3. kubectl 설치와 기본 명령

4. Pod

5. Deployment와 롤링 업데이트

6. Service

7. ConfigMap과 Secret

8. Ingress

9. HPA 수평 자동 확장

10. Helm

11. 다음 단계

12. Kubernetes 실무 설계

13. 운영 기준

14. 검증 전략

마무리

'개발 가이드 > Cloud Devops' 카테고리의 다른 글

관련글

댓글

티스토리툴바