Kubernetes 배포
빌드된 컨테이너 이미지를 Kubernetes 클러스터에 배포하는 방법을 안내합니다. Kubernetes는 고가용성, 자동 복구, 수평 확장을 지원하여 프로덕션 환경에 적합합니다.
- 고가용성: 여러 Pod이 동시에 실행되어 하나가 실패해도 서비스가 중단되지 않습니다 .
- 자동 복구: Pod이 비정상이면 자동으로 재시작됩니다 .
- 수평 확장: 트래픽에 따라 Pod 수를 자동으로 늘리거나 줄일 수 있습니다 (HPA)
- 롤링 업데이트: 서비스 중단 없이 새 버전을 배포할 수 있습니다 .
사전 요구사항
배포를 시작하기 전에 다음을 확인하세요:
- Kubernetes 클러스터 등록: [런타임 환경] 페이지에 K8s 클러스터가 등록되어 있어야 합니다 .
- 이미지 빌드 완료: 이미지가 레지스트리에 푸시되어 있어야 합니다 .
- Registry Secret 생성: K8s 클러스터에 레지스트리 인증 Secret이 있어야 합니다 .
Auto CI 설정의 Step 4에서 Registry Secret을 자동으로 생성할 수 있습니다.
Step 1: Deploy 단계로 이동
- [서비스 관리] 페이지로 이동합니다 .
- 배포할 서비스를 클릭하여 상세 페이지로 이동합니다 .
- 파이프라인에서 Deploy 단계를 클릭합니다 .
Step 2: 배포 환경 선택
배포할 환경을 선택합니다. 환경별로 리소스와 설정이 다를 수 있습니다.
- Development: 기능 개발 및 테스트 환경입니다. 권장 레플리카 수는 1개입니다.
- Staging: 배포 전 최종 검증 환경입니다. 권장 레플리카 수는 2개입니다.
- Production: 실제 서비스 운영 환경입니다. 권장 레플리카 수는 3개 이상입니다.
프로덕션 환경에 처음 배포할 때는 충분한 테스트를 거친 이미지인지 확인하세요. 가능하면 스테이징 환경에서 먼저 검증하는 것을 권장합니다.
Step 3: 클러스터 및 네임스페이스 선택
배포 대상을 설정합니다:
- 클러스터: 배포할 K8s 클러스터를 선택합니다 (예:
prod-cluster-01) - 네임스페이스: 배포할 K8s 네임스페이스를 선택합니다 (예:
production,staging) - 이미지 태그: 배포할 이미지 버전을 선택합니다 (예:
main-abc123)
네임스페이스는 Kubernetes 클러스터 내에서 리소스를 논리적으로 분리하는 방법입니다. 환경별(dev, staging, prod)로 네임스페이스를 분리하면 리소스 격리와 관리가 쉬워집니다.
Step 4: 배포 설정
4.1 레플리카 설정
레플리카 수는 동시에 실행할 Pod 개수입니다.
- 개발 환경: 1개 권장 (리소스 절약을 위해)
- 스테이징 환경: 2개 권장 (기본 이중화를 위해)
- 프로덕션 환경: 3개 이상 권장 (고가용성 보장을 위해)
- 최소 2개: 한 Pod이 업데이트되거나 장애가 나도 서비스 유지
- 3개 이상: 트래픽 분산 및 안정성 향상
- HPA 설정 시: 최소 레플리카 수만 지정하면 트래픽에 따라 자동 조절
4.2 리소스 설정
Pod에 할당할 CPU와 메모리를 설정합니다.
- CPU 요청(Request): 최소 보장 CPU입니다 (예:
100m= 0.1 코어) - CPU 제한(Limit): 최대 사용 CPU입니다 (예:
500m= 0.5 코어) - 메모리 요청(Request): 최소 보장 메모리입니다 (예:
128Mi) - 메모리 제한(Limit): 최대 사용 메모리입니다 (예:
512Mi)
- 요청(Request): Pod 스케줄링에 사용됩니다. 이 만큼의 리소스가 있는 노드에 배치됩니다.
- 제한(Limit): 실제 사용 상한입니다. 이를 초과하면 CPU는 쓰로틀링, 메모리는 OOMKilled 됩니다.
권장: 요청은 평균 사용량, 제한은 피크 사용량 기준으로 설정
4.3 환경 변수 설정
애플리케이션에 필요한 환경 변수를 설정합니다:
- 직접 입력: 키-값을 직접 입력합니다. 간단한 설정값에 추천합니다.
- ConfigMap: K8s ConfigMap을 참조합니다. 환경별 설정에 추천합니다.
- Secret: K8s Secret을 참조합니다. 비밀번호, API 키 등 민감 정보에 추천합니다.
비밀번호, API 키 등 민감한 정보는 직접 입력하지 말고 반드시 Secret을 사용하세요. 직접 입력한 값은 배포 설정에 그대로 저장됩니다.
Step 5: 배포 전략 선택
새 버전을 어떻게 배포할지 전략을 선택합니다.
- Rolling Update: 기존 Pod을 점진적으로 교체합니다
.
- 장점: 무중단 배포, 리소스 효율
- 단점: 일시적 버전 혼재
- Recreate: 기존 Pod 모두 종료 후 새로 생성합니다
.
- 장점: 깔끔한 전환
- 단점: 다운타임 발생
- Blue-Green: 새 버전을 별도로 배포 후 전환합니다
.
- 장점: 빠른 롤백, 완전 분리
- 단점: 리소스 2배 필요
- 개발 환경: Recreate 권장 (빠르고 간단)
- 스테이징 환경: Rolling Update 권장 (프로덕션 환경 시뮬레이션)
- 프로덕션 환경: Rolling Update 또는 Blue-Green 권장 (무중단 필수)
Rolling Update 상세 설정
- maxSurge: 업데이트 중 추가 생성 가능한 Pod 비율/개수입니다 (기본값: 25%)
- maxUnavailable: 업데이트 중 동시 종료 가능한 Pod 비율/개수입니다 (기본값: 25%)
예: 레플리카 4개, maxSurge=1, maxUnavailable=1 → 항상 3~5개 Pod 유지
Step 6: 배포 실행
- 모든 설정을 검토합니다 .
- 배포 버튼을 클릭합니다 .
- 배포 진행 상태를 모니터링합니다 .
배포 진행 상태
[1/4] Creating Deployment...
[2/4] Waiting for Pods to be ready...
→ Pod my-app-xxx-1: Running (1/3)
→ Pod my-app-xxx-2: Running (2/3)
→ Pod my-app-xxx-3: Running (3/3)
[3/4] Updating Service...
[4/4] Deployment completed!
Pod 시작 시간은 이미지 크기, 애플리케이션 시작 시간에 따라 다릅니다. 첫 배포는 이미지 풀링이 필요해 더 오래 걸릴 수 있습니다.
Step 7: 배포 상태 확인
Pod 상태 이해하기
- Running: 정상 실행 중입니다. 별도 조치가 필요 없습니다.
- Pending: 스케줄링 대기 중입니다. 노드 리소스 또는 이미지 풀을 확인하세요.
- CrashLoopBackOff: 반복적으로 크래시가 발생하고 있습니다. 로그를 확인하세요.
- ImagePullBackOff: 이미지 풀에 실패했습니다. Registry Secret 또는 이미지 태그를 확인하세요.
상세 정보 확인
Operate 단계에서 다음을 확인할 수 있습니다:
- K8s Pods 탭: Pod 목록, 상태, 리소스 사용량
- K8s Resources 탭: Deployment, Service, ConfigMap 등
- K8s Deployment 탭: 롤아웃 상태, 리비전 이력
- Logs 탭: 실시간 Pod 로그
HPA (Horizontal Pod Autoscaler) 설정
트래픽에 따라 Pod 수를 자동으로 조절하려면 HPA를 설정하세요.
Horizontal Pod Autoscaler는 CPU, 메모리 사용률에 따라 Pod 수를 자동으로 늘리거나 줄이는 Kubernetes 기능입니다. 트래픽 급증 시 자동으로 확장하고, 트래픽이 줄면 축소하여 리소스를 절약합니다.
HPA 생성 방법
- Operate 단계 → K8s Deployment 탭 이동
- HPA 설정 버튼 클릭
- 설정 입력:
- 최소 레플리카: 축소 시 최소 Pod 수입니다 (권장: 2)
- 최대 레플리카: 확장 시 최대 Pod 수입니다 (권장: 10)
- CPU 타겟: CPU 사용률 타겟입니다 (권장: 70%)
- 메모리 타겟: 메모리 사용률 타겟입니다 (선택, 권장: 80%)
- 최소 레플리카를 2 이상으로 설정하여 항상 이중화 유지
- CPU 타겟을 70% 정도로 설정하면 버스트 트래픽에도 여유 있게 대응
- 확장/축소 속도는 기본적으로 점진적이므로 급격한 트래픽 변화에는 Pre-warming 고려
도메인 설정 (Ingress)
외부에서 서비스에 접근할 수 있도록 도메인을 설정합니다.
Ingress 생성
- Operate 단계 → Domain Settings 탭 이동
- 도메인 정보 입력:
- 호스트: 도메인 이름 (예:
api.company.com) - 경로: URL 경로 (예:
/,/api) - TLS: HTTPS 활성화 (체크 권장)
- 호스트: 도메인 이름 (예:
자세한 내용은 도메인/SSL 설정 가이드를 참고하세요.
문제 해결
Pod가 시작되지 않음
- Pending (리소스 부족): 노드 리소스를 확인하고 요청값을 감소시키세요.
- Pending (이미지 풀 대기): Registry Secret을 확인하세요.
- ImagePullBackOff: 이미지가 없습니다. 이미지 태그와 Registry 접근 권한을 확인하세요.
- CrashLoopBackOff: 애플리케이션 오류입니다.
kubectl logs또는 KIWI 로그 탭에서 확인하세요.
배포 실패
- 네임스페이스 없음: 네임스페이스를 먼저 생성합니다 .
- 권한 부족: 클러스터 관리자에게 RBAC 권한을 요청합니다 .
- ResourceQuota 초과: 리소스 쿼터를 확인하거나 요청값을 조정합니다 .
배포 후 서비스 접근 불가
- Pod가 Ready 아님: Health Check 설정 및 애플리케이션을 확인합니다 .
- Service 설정 오류: 포트 매핑을 확인합니다 .
- Ingress 미설정: Ingress를 생성하거나 도메인을 설정합니다 .
Operate 단계의 Logs 탭에서 실시간 로그를 확인하세요. 대부분의 문제는 애플리케이션 로그에서 원인을 찾을 수 있습니다.