빌드/배포
코드를 작성했다면, 이제 실제로 동작하는 서비스로 만들어야 합니다. KIWI는 복잡한 빌드/배포 과정을 몇 번의 클릭으로 처리할 수 있도록 도와드립니다.
서비스가 [서비스 관리] 페이지에 등록되어 있어야 합니다. 아직 등록하지 않았다면 서비스 등록 가이드를 먼저 참고하세요.
왜 빌드/배포가 필요한가요?
개발한 코드를 사용자가 접근할 수 있는 서비스로 만들려면, 코드를 컨테이너 이미지로 패키징하고 서버에 배포해야 합니다. 이 과정을 수동으로 하면 실수가 발생하기 쉽고 시간도 많이 걸립니다.
KIWI는 이 과정을 자동화하여 일관성 있고 안정적인 배포를 가능하게 합니다.
빌드/배포 흐름
KIWI의 빌드/배포는 다음 단계로 진행됩니다:
- 1. 빌드 설정 (최초 1회만): Dockerfile과 빌드 옵션을 구성합니다.
- 2. 이미지 빌드 (2~10분): Kaniko로 소스 코드를 컨테이너 이미지로 변환합니다.
- 3. 이미지 푸시 (1~3분): 빌드된 이미지를 Harbor/DockerHub에 저장합니다.
- 4. 배포 (1~5분): Kubernetes 또는 Docker에 이미지를 배포합니다.
Kaniko는 Docker 데몬 없이 컨테이너 내부에서 이미지를 빌드할 수 있는 도구입니다. Kubernetes 환경에서 보안상 권한 상승 없이 안전하게 이미지를 빌드할 수 있어, 기업 환경에서 널리 사용됩니다.
CI 빌드 설정하기
서비스의 CI 빌드 파이프라인을 설정합니다. 한 번 설정하면 이후 빌드에 자동으로 적용됩니다.
Step 1: 서비스 상세 페이지 이동
[서비스 관리] 페이지에서 빌드할 서비스를 클릭하여 상세 페이지로 이동합니다.
Step 2: 빌드 탭에서 설정 열기
상단 탭에서 빌드 탭을 클릭한 후, 빌드 설정 버튼을 클릭하여 설정 모달을 엽니다.
Step 3: Dockerfile 설정
Dockerfile을 구성하는 방법을 선택합니다:
- 자동 감지 (권장): 저장소 내 Dockerfile을 자동으로 찾습니다. 대부분의 프로젝트에 권장합니다.
- 경로 지정: Dockerfile 경로를 직접 입력합니다. 여러 Dockerfile이 있을 때 사용합니다. (예:
./docker/Dockerfile.prod) - 빌드 마법사: KIWI가 Dockerfile을 자동 생성합니다. Dockerfile이 없는 프로젝트에서 사용하세요.
빌드 마법사를 사용하면 Node.js, Python, Java 등 주요 언어에 맞는 Dockerfile을 자동으로 생성해 줍니다. 프로젝트 언어와 프레임워크만 선택하면 됩니다.
Step 4: 빌드 인자 설정 (선택사항)
필요한 경우 빌드 인자를 설정합니다:
- 빌드 경로: Docker 빌드 시 사용할 파일들이 있는 폴더입니다. 기본값은
.(프로젝트 루트)입니다. - 빌드 인자(ARG): Dockerfile에 전달할 값입니다. 환경별 설정에 유용합니다.
- 예:
NODE_ENV=production,API_URL=https://api.example.com
- 예:
- 타겟 스테이지: 멀티스테이지 빌드에서 특정 단계까지만 빌드합니다.
빌드 경로는 Dockerfile의 COPY, ADD 명령어가 접근할 수 있는 파일 범위를 결정합니다. 보통 프로젝트 루트(.)를 사용하지만, 모노레포 구조에서는 특정 하위 폴더를 지정할 수 있습니다.
Step 5: 이미지 레지스트리 설정
빌드된 이미지를 저장할 레지스트리 정보를 입력합니다:
- 레지스트리 URL: Harbor 또는 DockerHub 주소 (예:
harbor.company.com) - 프로젝트/네임스페이스: 이미지 저장 위치 (예:
library) - 이미지 이름: 이미지 이름 (예:
my-web-app) - 태그 규칙: 버전 태깅 방식
사용 가능한 태그 변수:
${BRANCH}: Git 브랜치 이름입니다. (예:main)${SHORT_SHA}: 커밋 해시 앞 7자리입니다. (예:a1b2c3d)${TAG}: Git 태그입니다. (예:v1.0.0)${BUILD_NUMBER}: 빌드 번호입니다. (예:42)
예: ${BRANCH}-${SHORT_SHA} → main-a1b2c3d
Step 6: 빌드 트리거 설정
빌드가 실행되는 조건을 선택합니다:
- 수동: 빌드 버튼 클릭 시에만 실행합니다. 테스트 빌드나 긴급 배포에 사용합니다.
- 커밋 푸시: 특정 브랜치에 코드 푸시 시 자동으로 빌드합니다. 개발/스테이징 환경에 적합합니다.
- 태그 생성: Git 태그 생성 시 자동으로 빌드합니다. 릴리스 배포에 사용합니다.
- 스케줄: cron 스케줄 기반으로 정기 빌드합니다. 야간 빌드나 주간 빌드에 사용합니다.
- develop 브랜치: 커밋 푸시 → 개발 환경 자동 배포
- main 브랜치: 커밋 푸시 → 스테이징 환경 자동 배포
- v 태그*: 태그 생성 → 운영 환경 배포
Step 7: 설정 저장
저장 버튼을 클릭하여 빌드 설정을 저장합니다.
컨테이너 이미지 빌드하기
설정이 완료되면 실제로 이미지를 빌드해 봅시다.
Step 1: 빌드 탭에서 브랜치 선택
[서비스 관리] → 서비스 선택 → 빌드 탭으로 이동합니다. 브랜치 선택 드롭다운에서 빌드할 브랜치를 선택합니다.
Step 2: 빌드 실행
빌드 시작 버튼을 클릭합니다. 빌드가 시작되면 실시간 로그 뷰어가 표시됩니다.
Step 3: 빌드 진행 상황 확인
빌드는 다음 단계로 진행됩니다:
- 소스 클론 (10~30초): Git 저장소에서 코드를 가져옵니다.
- Dockerfile 분석 (5~10초): 빌드 계획을 수립합니다.
- 레이어 빌드 (1~5분): 이미지 레이어를 순차적으로 빌드합니다.
- 이미지 푸시 (30초~2분): 완성된 이미지를 레지스트리에 업로드합니다.
빌드 중 오류가 발생하면 로그에서 error 또는 failed 키워드를 검색하세요. 대부분의 문제는 Dockerfile 문법 오류나 의존성 설치 실패입니다.
Step 4: 빌드 완료 확인
빌드가 완료되면 결과 화면에서 다음 정보를 확인합니다:
- 빌드 상태: 성공 또는 실패
- 이미지 태그: 생성된 이미지의 전체 경로와 태그
- 이미지 크기: 최종 이미지 크기 (작을수록 배포가 빠릅니다)
- 소요 시간: 빌드에 걸린 총 시간
Kubernetes에 배포하기
빌드된 이미지를 Kubernetes 클러스터에 배포합니다. Kubernetes는 컨테이너를 자동으로 관리하고, 장애 시 자동 복구해 주는 강력한 플랫폼입니다.
- Kubernetes 클러스터가 **[런타임 환경]**에 등록되어 있어야 합니다.
- 이미지가 빌드되어 레지스트리에 푸시되어 있어야 합니다.
Step 1: 배포 탭에서 환경 선택
[서비스 관리] → 서비스 선택 → 배포 탭으로 이동합니다. 배포할 환경을 선택합니다:
- Development: 개발 환경입니다. 빠른 테스트에 적합하며 낮은 리소스를 사용합니다.
- Staging: QA/테스트 환경입니다. 운영과 유사한 설정으로 구성합니다.
- Production: 운영 환경입니다. 높은 가용성과 충분한 리소스를 할당합니다.
Step 2: 클러스터와 네임스페이스 선택
클러스터 선택 드롭다운에서 배포할 Kubernetes 클러스터를 선택하고, 네임스페이스를 지정합니다.
네임스페이스는 Kubernetes에서 리소스를 논리적으로 분리하는 방법입니다. 예를 들어 development, staging, production 네임스페이스로 환경을 분리할 수 있습니다.
Step 3: 배포 설정 구성
배포에 필요한 설정을 입력합니다:
- 이미지 태그: 배포할 이미지 버전 (예:
main-abc123) - 레플리카 수: Pod 복제본 개수
- 개발 환경: 1개면 충분합니다.
- 스테이징: 2개 이상 권장 (운영과 유사하게)
- 운영 환경: 최소 2개 이상 (가용성 확보)
레플리카가 2개 이상이면, 하나의 Pod에 문제가 생겨도 다른 Pod가 요청을 처리합니다.
Step 4: 리소스 설정
Pod에 할당할 CPU와 메모리를 설정합니다:
- CPU 요청: 최소 보장 CPU입니다. (예:
100m= 0.1 코어) - CPU 제한: 최대 사용 CPU입니다. (예:
500m= 0.5 코어) - 메모리 요청: 최소 보장 메모리입니다. (예:
128Mi= 128 메가바이트) - 메모리 제한: 최대 사용 메모리입니다. (예:
512Mi= 512 메가바이트)
메모리 제한을 너무 낮게 설정하면 애플리케이션이 OOM(Out of Memory)으로 종료될 수 있습니다. 애플리케이션의 평균 메모리 사용량보다 여유 있게 설정하세요.
Step 5: 환경 변수 설정 (선택사항)
애플리케이션에 필요한 환경 변수를 설정합니다:
- 직접 입력: 키-값 쌍을 직접 입력합니다.
- ConfigMap 참조: Kubernetes ConfigMap에서 값을 가져옵니다.
- Secret 참조: 비밀번호, API 키 등 민감한 정보는 Secret을 사용합니다.
Step 6: 배포 전략 선택
배포 전략에 따라 서비스 중단 여부가 달라집니다:
- Rolling Update (기본 권장): 점진적으로 새 버전을 배포합니다. 서비스 중단 없이 배포되며, 대부분의 경우에 권장합니다.
- Recreate: 기존 Pod를 종료한 후 새 버전을 배포합니다. 서비스 중단이 발생하며, DB 마이그레이션 등 특수한 경우에 사용합니다.
- Blue-Green: 새 버전을 별도로 배포한 후 트래픽을 전환합니다. 서비스 중단 없이 배포되며, 즉시 롤백이 필요한 경우에 적합합니다.
Step 7: 배포 실행 및 상태 확인
배포 버튼을 클릭합니다. 배포 진행 상태를 실시간으로 모니터링할 수 있습니다.
배포가 완료되면 다음을 확인하세요:
- Pod 상태: Running이어야 정상입니다.
- 레플리카 수: Ready/Total이 일치해야 합니다 (예: 3/3)
- 이벤트 로그: 오류가 없는지 확인합니다.
Docker/Podman에 배포하기
Kubernetes가 아닌 단일 서버 환경에서는 Docker 또는 Podman에 직접 배포할 수 있습니다. 설정이 간단하고 소규모 프로젝트에 적합합니다.
Docker/Podman 런타임이 **[런타임 환경]**에 등록되어 있어야 합니다.
Step 1: 배포 탭에서 Docker 선택
[서비스 관리] → 서비스 선택 → 배포 탭으로 이동합니다. 배포 유형에서 Docker를 선택하고, 런타임 드롭다운에서 대상 런타임을 선택합니다.
Step 2: 컨테이너 설정
컨테이너 정보를 입력합니다:
- 컨테이너 이름: 컨테이너를 식별하는 이름입니다. (예:
my-web-app) - 이미지 태그: 배포할 이미지 전체 경로입니다. (예:
harbor.company.com/library/app:latest) - 포트 매핑: 호스트:컨테이너 포트를 지정합니다. (예:
8080:80)
8080:80은 "호스트의 8080 포트로 들어오는 요청을 컨테이너의 80 포트로 전달한다"는 의미입니다. 웹 애플리케이션은 보통 컨테이너 내부에서 80 또는 8080 포트를 사용합니다.
Step 3: 볼륨 마운트 설정 (선택사항)
컨테이너가 재시작되어도 데이터를 유지하려면 볼륨을 설정합니다:
- 호스트 경로: 서버의 디렉토리 (예:
/data/app) - 컨테이너 경로: 컨테이너 내 마운트 위치 (예:
/app/data) - 읽기 전용: 설정 파일 등 변경이 불필요한 경우 체크
- 업로드된 파일을 저장하는 경우
- 로그 파일을 호스트에 보관하는 경우
- 데이터베이스 파일을 영속화하는 경우
Step 4: 환경 변수 설정 및 배포
필요한 환경 변수를 입력하고 배포 버튼을 클릭합니다.
배포가 완료되면 컨테이너 상태를 확인하세요:
- Running: 정상 실행 중
- Stopped: 중지됨 (수동 또는 오류)
- Error: 오류 발생 (로그 확인 필요)
이전 버전으로 롤백하기
배포 후 문제가 발생했나요? 걱정하지 마세요. KIWI를 사용하면 몇 번의 클릭으로 이전 버전으로 돌아갈 수 있습니다.
롤백하면 현재 버전의 변경사항이 모두 되돌려집니다. 데이터베이스 스키마 변경이 있었다면, 롤백 전에 데이터 마이그레이션 영향을 확인하세요.
Step 1: 배포 이력에서 롤백 대상 선택
[서비스 관리] → 서비스 선택 → 배포 탭에서 배포 이력 테이블을 확인합니다.
각 배포 항목에서 다음 정보를 확인할 수 있습니다:
- 배포 시간: 언제 배포되었는지
- 이미지 태그: 어떤 버전인지
- 배포 상태: 성공/실패 여부
- 배포자: 누가 배포했는지
Step 2: 롤백 실행
롤백할 배포 항목의 롤백 버튼을 클릭하고, 확인 모달에서 롤백 실행을 클릭합니다.
Step 3: 롤백 완료 확인
롤백이 완료되면 서비스 상태와 Pod 상태가 정상인지 확인합니다. Rolling Update 전략을 사용하면 롤백 중에도 서비스 중단이 없습니다.
Blue-Green 배포 전략을 사용하면 트래픽만 전환하므로 롤백이 거의 즉시 완료됩니다. 중요한 서비스에는 Blue-Green 전략을 고려해 보세요.
빌드 시간 최적화
빌드가 5분 이상 걸린다면, 최적화가 필요할 수 있습니다. 다음 방법들로 빌드 시간을 크게 줄일 수 있습니다.
캐시 활용하기
빌드 설정에서 캐시 옵션을 활성화하세요:
- 레이어 캐시: 변경되지 않은 Docker 레이어를 재사용합니다. 가장 효과적인 방법입니다.
- 레지스트리 캐시: 레지스트리에 저장된 기존 이미지 레이어를 활용합니다. 첫 빌드를 제외하고 효과적입니다.
- 로컬 캐시: 빌드 노드의 로컬 캐시를 사용합니다. 동일 노드에서 빌드할 때 효과적입니다.
Dockerfile 최적화 팁
- 변경이 적은 레이어를 앞에 배치: 의존성 설치(npm install, pip install)를 코드 복사보다 먼저 실행
- 멀티스테이지 빌드 사용: 빌드 도구는 빌드 스테이지에만, 최종 이미지에는 실행에 필요한 것만 포함
.dockerignore활용:node_modules,.git, 테스트 파일 등 불필요한 파일 제외- 작은 베이스 이미지 사용:
alpine기반 이미지는 크기가 작아 빌드와 배포가 빠릅니다.
자주 묻는 질문
빌드가 실패합니다
원인 확인 방법:
- 빌드 로그에서
error또는failed키워드 검색 - Dockerfile 문법 오류 확인 (들여쓰기, 명령어 순서)
- 의존성 설치 명령어 확인 (네트워크, 버전 호환성)
가장 흔한 원인은 의존성 설치 실패입니다. npm install이나 pip install 부분의 로그를 먼저 확인하세요.
이미지 푸시가 실패합니다
확인 사항:
- 레지스트리 URL이 정확한지 확인
- 인증 정보(사용자명/비밀번호 또는 토큰)가 올바른지 확인
- 레지스트리에 프로젝트/네임스페이스가 존재하는지 확인
배포 후 Pod가 시작되지 않습니다
확인 사항:
- ImagePullBackOff: 이미지 경로가 올바른지, 레지스트리 인증 Secret이 설정되어 있는지 확인
- CrashLoopBackOff: 애플리케이션 시작 오류. 컨테이너 로그 확인 필요
- Pending: 리소스(CPU/메모리)가 부족하거나 노드 스케줄링 문제
롤백이 안 됩니다
이전 이미지가 레지스트리에 존재해야 롤백이 가능합니다. 레지스트리의 이미지 보관 정책을 확인하세요.
최소 최근 10개 버전의 이미지는 보관하는 것을 권장합니다. 레지스트리에서 오래된 이미지 자동 삭제 정책을 설정할 때 주의하세요.