Kubernetes 배포
빌드된 컨테이너 이미지를 Kubernetes 클러스터에 배포하는 방법을 안내합니다. Kubernetes는 고가용성, 자동 복구, 수평 확장을 지원하여 프로덕션 환경에 적합합니다.
왜 이 가이드를 읽어야 하는가
이 가이드를 따라가면 빌드된 이미지를 Kubernetes 클러스터에 무중단으로 배포하고, 트래픽에 맞춰 Pod 수를 자동으로 조절(HPA) 하는 운영 환경을 만들 수 있습니다. 비개발 운영팀도 환경(개발/스테이징/운영) 선택 → 리소스 입력 → 배포 전략 선택 순서를 따라가면 폼만으로 안전한 K8s 배포를 구성할 수 있습니다.
- 고가용성: 여러 Pod이 동시에 실행되어 하나가 실패해도 서비스가 중단되지 않습니다.
- 자동 복구: Pod이 비정상이면 자동으로 재시작됩니다.
- 수평 확장: 트래픽에 따라 Pod 수를 자동으로 늘리거나 줄일 수 있습니다 (HPA)
- 롤링 업데이트: 서비스 중단 없이 새 버전을 배포할 수 있습니다.
시작하기 전에: 알아둘 용어
본문에 들어가기 전에 자주 등장하는 용어를 한 줄씩 정리합니다. 본문에서 처음 등장할 때 "(용어 사전 참고)" 안내를 함께 표시합니다.
| 용어 | 정의 + 일상 비유 |
|---|---|
| Pod | 컨테이너를 묶어 K8s에서 실행하는 최소 실행 단위. 아파트 한 호(號)와 같습니다. 같은 호 안의 컨테이너들은 자원을 공유합니다. |
| Deployment | Pod를 정해진 개수만큼 유지·관리하는 리소스. 빌딩 관리소처럼 빈 호(Pod)가 생기면 자동으로 채웁니다. |
| Service | Pod의 변하지 않는 고정 주소. Pod가 바뀌어도 같은 주소로 들어가면 살아 있는 Pod에 연결됩니다. |
| replicas | 동시에 띄울 Pod 복제본 수(spec.replicas). 편의점 계산대 개수와 같습니다. 많을수록 동시 손님을 빨리 처리합니다. |
| RollingUpdate | 기존 Pod를 점진적으로 새 버전으로 교체하는 배포 전략. 에스컬레이터처럼 끊김 없이 새 단으로 옮겨 탑니다. |
| Recreate | 기존 Pod를 모두 종료한 뒤 새 Pod를 생성하는 배포 전략. 가게 문 닫고 인테리어 바꿔 다시 여는 것과 같습니다. |
| namespace | 같은 클러스터 안에서 리소스를 구분하는 칸막이. 회사 안의 부서처럼 같은 건물(클러스터)을 부서별로 나눠 씁니다. |
사전 요구사항
배포를 시작하기 전에 다음을 확인하세요:
- Kubernetes 클러스터 등록: [런타임 환경] 페이지에 K8s 클러스터가 등록되어 있어야 합니다.
- 이미지 빌드 완료: 이미지가 레지스트리에 푸시되어 있어야 합니다.
- Registry Secret 생성: K8s 클러스터에 레지스트리 인증 Secret이 있어야 합니다.
Auto CI 설정을 저장하면 Registry Secret이 자동으로 생성됩니다.
Step 1: Deploy 단계로 이동
- [서비스 관리] 페이지로 이동합니다.
- 배포할 서비스를 클릭하여 상세 페이지로 이동합니다.
- 파이프라인에서 Deploy 단계를 클릭합니다.
Step 2: 배포 환경 선택
배포할 환경을 선택합니다. 환경 이름은 자유롭게 정의할 수 있으며, 일반적으로 다음 권장사항을 따릅니다.
- 개발(Development): 기능 개발 및 테스트 환경. 일반적으로 레플리카 1개.
- 스테이징(Staging): 배포 전 최종 검증 환경. 일반적으로 레플리카 2개.
- 운영(Production): 실제 서비스 운영 환경. 일반적으로 레플리카 3개 이상.
프로덕션 환경에 처음 배포할 때는 충분한 테스트를 거친 이미지인지 확인하세요. 가능하면 스테이징 환경에서 먼저 검증하는 것을 권장합니다.
Step 3: 클러스터 및 네임스페이스 선택
배포 대상을 설정합니다: (namespace 참고)
- 클러스터: 배포할 K8s 클러스터를 선택합니다 (예:
prod-cluster-01) - 네임스페이스: 배포할 K8s 네임스페이스를 선택합니다 (예:
production,staging) - 이미지 태그: 배포할 이미지 버전을 선택합니다 (예:
main-abc123)
배포 직전 환경 변수(DATABASE_URL, API_KEY 등) 입력을 잊으면 Pod는 정상 기동되지만 애플리케이션이 곧바로 크래시되어 CrashLoopBackOff 상태에 빠집니다. 운영 모달의 로그 조회 탭에서 "missing environment variable" 류의 메시지가 보이면 Step 4의 환경 변수 설정을 다시 확인하세요. 민감 정보는 직접 입력 대신 Secret을 사용하세요.
네임스페이스는 Kubernetes 클러스터 내에서 리소스를 논리적으로 분리하는 방법입니다. 환경별(dev, staging, prod)로 네임스페이스를 분리하면 리소스 격리와 관리가 쉬워집니다.
Step 4: 배포 설정
4.1 레플리카 설정
레플리카 수는 동시에 실행할 Pod 개수입니다. (Pod, replicas 참고)
- 개발 환경: 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: 배포 전략 선택
새 버전을 어떻게 배포할지 전략을 선택합니다. KIOPS는 다음 두 가지 전략을 지원합니다(Blue-Green은 현재 지원하지 않음). (RollingUpdate, Recreate 참고)
- RollingUpdate: 기존 Pod을 점진적으로 교체합니다.
- 장점: 무중단 배포, 리소스 효율
- 단점: 일시적 버전 혼재
- Recreate: 기존 Pod 모두 종료 후 새로 생성합니다.
- 장점: 깔끔한 전환
- 단점: 다운타임 발생
Recreate 전략은 기존 Pod 전부를 한 번에 종료하므로 새 Pod이 Ready 상태가 될 때까지 서비스가 일시 중단됩니다. 개발 환경에서는 빠르고 깔끔해 선호되지만, 운영 환경에서 무심코 Recreate를 선택하면 사용자 측에서 502/connection refused 가 발생합니다. 운영은 반드시 RollingUpdate + 기본값(maxSurge=1, maxUnavailable=0) 조합을 사용하세요.
- 개발 환경: Recreate 권장 (빠르고 간단)
- 스테이징/프로덕션 환경: RollingUpdate 권장 (무중단 배포)
RollingUpdate 상세 설정
- maxSurge: 업데이트 중 추가로 생성 가능한 Pod 수입니다. KIOPS 기본값:
1 - maxUnavailable: 업데이트 중 동시 종료 가능한 Pod 수입니다. KIOPS 기본값:
0
예: 레플리카 3개, maxSurge=1, maxUnavailable=0 → 항상 최소 3개의 Pod이 유지되고, 잠시 4개가 떠 있다가 점진적으로 교체됩니다.
maxUnavailable을 0보다 크게 설정하면 일시적으로 사용 가능한 Pod 수가 줄어듭니다. 운영 환경에서는 기본값(maxSurge=1, maxUnavailable=0)을 그대로 사용하는 것을 권장합니다.
Step 6: 배포 실행
- 모든 설정을 검토합니다.
- 배포 버튼을 클릭합니다.
- 배포 진행 상태를 모니터링합니다.
배포 순서 (Deployment가 여러 개일 때)
매니페스트에 Deployment가 2개 이상이면, 배포 실행 모달의 "서비스별 빌드 버전 선택" 바로 아래에 배포 순서 섹션이 나타납니다. 백엔드가 먼저 떠야 프론트엔드가 정상 동작하는 것처럼 Deployment 사이에 의존 관계가 있을 때 순서를 지정할 수 있습니다.
- 순차 배포 토글 (기본: 꺼짐 = 일괄): 토글을 켜고 끄는 카드형 스위치입니다.
- 꺼짐(일괄): 모든 Deployment를 동시에 배포합니다. 의존성이 없으면 꺼두세요.
- 켜짐(순차): 지정한 순서대로 하나씩 배포합니다. 앞 Deployment가 Ready 상태가 된 뒤 다음을 배포합니다.
- 순서 지정: 순차 배포를 켜면 Deployment 목록이 나타나며, 드래그앤드롭으로 순서를 바꿉니다.
- 저장: 지정한 순서는 저장되어 다음 배포(수동·자동)에도 적용됩니다. 저장된 순서가 있으면 모달을 열 때 순차 토글이 켜진 상태로 시작합니다.
배포 순서 섹션은 매니페스트의 Deployment가 2개 이상일 때만 표시됩니다. 단일 Deployment 서비스에는 순서 개념이 없어 나타나지 않습니다.
원시 YAML을 직접 편집한 경우 Deployment의 selector.matchLabels와 Pod 템플릿의 template.metadata.labels가 달라지면 Pod는 떠 있지만 Service의 Endpoint가 비어 502 또는 connection refused 가 발생합니다. KIOPS 폼에서 배포하면 두 값이 자동으로 동기화되지만, K8s YAML 생성 가이드로 YAML을 직접 편집할 때는 두 값을 반드시 같이 수정하세요. (Deployment, Service 참고)
배포 진행 상태
[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 런타임의 운영 모달은 다음 탭으로 구성됩니다(로그 조회·명령 실행 탭은 해당 권한이 있을 때만 표시됩니다).
- 개요: 서비스 요약과 핵심 메트릭
- 파드 목록: Pod 목록 / 상태 / CPU·메모리 / 이미지 / 작업. HPA 설정 섹션도 이 탭 안에 포함됩니다.
- 배포 관리: Deployment 롤아웃 상태, 리비전 히스토리 조회, 즉시 롤백 버튼
- 설정/시크릿: 네임스페이스 단위 ConfigMap·Secret 키-값 관리 (관리 권한 필요)
- 로그 조회: 실시간 Pod 로그
- 명령 실행: 단발성/스트리밍 모드로
kubectl ...명령 실행 (-it,port-forward,-A,--all-namespaces등은 차단) - 도메인 설정: Ingress 도메인/TLS 구성
도메인 대상 DAST 스캔은 운영 모달에서 분리되어 [보안 분석] 페이지로 이관되었습니다.
HPA (Horizontal Pod Autoscaler) 설정
트래픽에 따라 Pod 수를 자동으로 조절하려면 HPA를 설정하세요.
Horizontal Pod Autoscaler는 CPU 사용률에 따라 Pod 수를 자동으로 늘리거나 줄이는 Kubernetes 기능입니다.
HPA 생성 방법
- Operate 단계 운영 모달을 엽니다.
- 파드 목록 탭으로 이동합니다 (HPA 설정 섹션은 이 탭 내부에 있습니다)
- HPA 설정 버튼 클릭
- 설정 입력:
- 최소 레플리카(minReplicas): 축소 시 최소 Pod 수 (권장: 2)
- 최대 레플리카(maxReplicas): 확장 시 최대 Pod 수 (권장: 10)
- CPU 타겟(targetCPU%): CPU 사용률 타겟 (기본값 80, 일반적인 시작값으로 70~80% 권장)
KIOPS의 HPA는 CPU 사용률 기반 단일 메트릭만 지원합니다(kubectl autoscale --cpu-percent로 동작). 메모리 기반 HPA, 다중/커스텀 메트릭, 스케일 안정화 윈도우 설정은 KIOPS 화면에서는 지원하지 않습니다. 필요한 경우 kubectl edit hpa로 직접 편집해야 합니다.
도메인 설정 (Ingress)
외부에서 서비스에 접근할 수 있도록 도메인을 설정합니다.
Ingress 생성
- Operate 단계 → 운영 모달의 도메인 설정 탭 이동
- 도메인 정보 입력:
- 호스트: 도메인 이름 (예:
api.company.com) - 경로: URL 경로 (예:
/,/api) - TLS: HTTPS 활성화 (체크 권장)
- 호스트: 도메인 이름 (예:
자세한 내용은 도메인/SSL 설정 가이드를 참고하세요.
문제 해결
Pod가 시작되지 않음
- Pending (리소스 부족): 노드 리소스를 확인하고 요청값을 감소시키세요.
- Pending (이미지 풀 대기): Registry Secret을 확인하세요.
- ImagePullBackOff: 이미지가 없습니다. 이미지 태그와 Registry 접근 권한을 확인하세요.
- CrashLoopBackOff: 애플리케이션 오류입니다. 운영 모달의 로그 조회 탭에서 확인하세요.
배포 실패
- 네임스페이스 없음: 네임스페이스를 먼저 생성합니다.
- 권한 부족: 클러스터 관리자에게 RBAC 권한을 요청합니다.
- ResourceQuota 초과: 리소스 쿼터를 확인하거나 요청값을 조정합니다.
배포 후 서비스 접근 불가
- Pod가 Ready 아님: Health Check 설정 및 애플리케이션을 확인합니다.
- Service 설정 오류: 포트 매핑을 확인합니다.
- Ingress 미설정: 운영 모달의 도메인 설정 탭에서 Ingress를 생성하세요.
운영 모달의 로그 조회 탭에서 실시간 로그를 확인하세요. 대부분의 문제는 애플리케이션 로그에서 원인을 찾을 수 있습니다.
다음에 할 일
K8s 배포가 정상적으로 완료됐다면, 다음 동선을 권장합니다.
- HPA 자동 확장: 운영 모달 → 파드 목록 탭에서 HPA를 설정해 트래픽에 따라 Pod 수가 자동으로 조절되도록 만드세요. 최소 2개 / 최대 10개 / CPU 70%가 일반적인 시작값입니다.
- 도메인/SSL 설정: 외부에서 서비스에 접근할 수 있도록 운영 모달의 도메인 설정 탭에서 Ingress를 등록합니다. 자세한 절차는 도메인/SSL 설정 가이드를 참고하세요.
- 롤백 시나리오 준비: 운영 모달의 배포 관리 탭에서 이전 리비전으로 즉시 롤백할 수 있습니다. 한 번 롤백 가이드를 검토해 두면 장애 시 대응 시간이 크게 줄어듭니다.