수동 빌드
Auto CI를 사용하지 않고 직접 빌드를 설정하고 실행하고 싶으신가요? 수동 빌드를 사용하면 빌드 과정을 완전히 제어할 수 있습니다. 특정 브랜치나 커밋으로 빌드하거나, 배포 전에 테스트용 이미지를 만들 때 유용합니다.
수동 빌드는 다음과 같은 상황에서 사용합니다:
- Auto CI 설정 전에 빌드를 테스트해보고 싶을 때
- 특정 브랜치나 커밋으로 임시 빌드가 필요할 때
- 긴급 핫픽스를 바로 빌드하고 싶을 때
- 빌드 설정을 변경한 후 검증하고 싶을 때
빌드 개요
KIOPS는 컨테이너 이미지 빌드를 위해 BuildKit 단일 빌드 엔진을 사용합니다. BuildKit은 Docker 데몬 없이 Kubernetes Pod 내부에서 동작하며, 빌드 Pod는 kiwi-builds 네임스페이스에서 실행됩니다.
- 병렬 DAG 빌드와 캐시 마운트로 빠른 빌드 속도를 제공합니다.
- 다양한 secret 마운트를 지원하여 빌드 시 인증 정보를 안전하게 사용할 수 있습니다.
BuildKit의 주요 장점은 다음과 같습니다:
- 보안: Docker 데몬이 필요 없어 권한 상승 공격의 위험이 낮습니다.
- K8s 친화적: 별도 빌드 서버 없이 Kubernetes Pod 내에서 직접 빌드합니다.
- 캐싱 지원: 레이어/레지스트리 캐시 + cache mount로 빌드 시간을 단축합니다.
지원하는 레지스트리:
- Harbor (권장)
- Docker Hub
- 사설 Docker Registry
빌드 설정하기
Step 1: 서비스 상세 페이지로 이동
- [서비스 관리] 페이지로 이동합니다.
- 빌드할 서비스 카드를 클릭하여 상세 페이지로 이동합니다.
Step 2: Build 단계 클릭
- 파이프라인에서 빌드 단계를 클릭합니다.
- 빌드 설정 모달이 열립니다.
Step 3: Dockerfile 확인
빌드 모달은 저장소를 분석하여 빌드 가능한 Dockerfile을 자동으로 감지하고, 감지된 대상을 체크박스 목록으로 표시합니다. 빌드할 대상을 선택하면 됩니다. (Dockerfile 경로를 직접 입력하는 필드는 없습니다.)
- 표준 구조(루트
Dockerfile)나 모노레포의 서비스별 Dockerfile은 자동으로 감지됩니다. - 빌드 불가로 판정된 항목은 "빌드 불가" 배지와 사유가 함께 표시됩니다.
- Dockerfile이 없는 프로젝트는 별도의 빌드 환경 생성(Build Wizard) 탭에서 Dockerfile을 생성한 뒤 빌드하세요. (빌드 모달 내 선택 옵션이 아니라 서비스 빌드 페이지의 별도 탭입니다.)
프로젝트 루트에 Dockerfile을 두는 것이 가장 일반적이고 권장됩니다. 특별한 이유가 없다면 자동으로 감지된 대상을 그대로 사용하세요.
Step 4: 빌드 대상 서비스 확인 (모노레포)
서비스가 모노레포 구조라면 빌드 모달이 저장소를 분석하여 빌드 가능한 서브 프로젝트 목록을 자동으로 감지합니다. 감지된 목록에서 빌드할 대상 서비스를 선택할 수 있으며, 단일 프로젝트 구조라면 이 단계는 생략됩니다.
빌드 인자(ARG)와 타겟 스테이지: 빌드 실행 창에는 빌드 경로, 빌드 인자(ARG), 타겟 스테이지를 직접 입력하는 UI 필드가 제공되지 않습니다. 해당 값은 Dockerfile 내부에서 ARG 선언과 멀티스테이지 구문(FROM ... AS <stage>)으로 직접 정의하세요.
Step 5: 이미지 레지스트리 정보 확인
레지스트리 정보는 별도 입력하지 않습니다. 서비스를 등록할 때 설정한 레지스트리 정보가 자동으로 사용되며, 값을 변경하려면 서비스 상세 페이지의 Registry 설정에서 수정하세요.
Step 6: 자동 배포 옵션 (선택)
빌드 모달의 자동 배포 토글을 켜면 빌드 성공 직후 지정한 서버로 곧바로 배포가 이어집니다. 토글을 켜면 배포 서버를 선택하는 드롭다운이 활성화되며, 끄면 빌드만 수행됩니다.
Step 7: 빌드 옵션 (선택)
수동 빌드 시 다음 옵션을 추가로 지정할 수 있습니다.
- 빌드 프로필: 빌드 Pod에 할당할 리소스 크기를 선택합니다.
auto(기본),small,medium,large,extra-large,2x-large,4x-large중 선택할 수 있으며, 빌드가 OOM으로 실패하거나 너무 오래 걸린다면 한 단계 위 프로필로 올려보세요. - No Cache: 활성화하면 BuildKit 캐시를 무시하고 모든 레이어를 새로 빌드합니다. 의존성 변경 후에도 캐시가 잘못 재사용되는 의심 상황에서 사용하세요.
빌드 실행하기
설정을 완료했다면 이제 실제로 빌드를 실행해 봅시다.
Step 1: 빌드 브랜치 확인
- 서비스 상세 페이지에서 빌드 단계를 클릭합니다.
- 빌드는 서비스에 등록된 브랜치로 수행됩니다. 빌드 모달에는 브랜치를 선택하는 드롭다운이 없으며, 다른 브랜치로 빌드하려면 [서비스 관리] 목록에서 그 서비스의 [설정] 을 열어(「빌드/배포 사전 설정」 창) GitLab 저장소 인증 구역의 브랜치를 먼저 바꾸세요. 자세한 내용은 스캔 대상 설정을 참고하세요.
잘못된 브랜치를 빌드하면 의도치 않은 코드가 배포될 수 있습니다. 빌드 전 서비스에 등록된 브랜치를 다시 한번 확인하세요.
Step 2: 빌드 시작
- 빌드 실행 버튼을 클릭합니다.
- 빌드가 큐에 등록되고 순서대로 실행됩니다.
Step 3: 빌드 로그 확인
실시간으로 빌드 진행 상황을 확인할 수 있습니다. BuildKit 로그는 단계별로 #번호가 부여되며, DONE/CACHED/ERROR 마커로 결과를 표시합니다.
BuildKit 로그 예시:
#1 [internal] load build definition from Dockerfile
#1 DONE 0.1s
#2 [internal] load .dockerignore
#2 DONE 0.0s
#3 [builder 1/4] FROM docker.io/library/node:20-alpine
#3 DONE 1.3s
#4 [builder 2/4] COPY package*.json ./
#4 CACHED
#5 [builder 3/4] RUN npm ci
#5 DONE 24.8s
#6 [builder 4/4] RUN npm run build
#6 DONE 12.1s
#7 exporting to image
#7 pushing layers 4.2s done
#7 DONE 5.1s
빌드 실패 시 로그에서 어느 단계에서 오류가 발생했는지 확인하세요. BuildKit 로그는 #<번호> 형식으로 단계가 표기되며 ERROR로 시작하는 줄이 실패 원인을 알려 줍니다. CACHED 표시는 해당 단계가 캐시에서 즉시 처리되었음을 의미합니다.
Step 4: 빌드 완료 확인
빌드가 완료되면 다음 정보를 확인할 수 있습니다:
- 빌드 상태: 성공 또는 실패
- 이미지 태그: 생성된 이미지의 전체 경로
- 이미지 크기: 빌드된 이미지 용량
- 빌드 소요 시간: 빌드 시작부터 완료까지 시간
빌드 최적화
빌드 시간을 단축하고 이미지 크기를 줄이는 방법을 알아봅니다.
캐시 활용으로 빌드 속도 향상
KIOPS는 다음 캐시 계층을 활용하여 빌드 속도를 최적화합니다:
- 레이어 캐시: 변경이 없는 Docker 레이어를 재사용합니다. 의존성 설치 시간을 대폭 단축하는 효과가 있습니다.
- 레지스트리 캐시: 기존 이미지 레이어를 활용합니다. 네트워크 전송량을 감소시키는 효과가 있습니다.
- 캐시 마운트 (BuildKit 전용):
RUN --mount=type=cache,...구문을 사용하면 npm/yarn/pip/maven 등의 패키지 캐시 디렉터리를 빌드 간 재사용할 수 있어 첫 빌드 이후에도 의존성 설치를 가속할 수 있습니다.
첫 빌드는 모든 레이어를 새로 생성해야 하므로 오래 걸립니다. 두 번째 빌드부터는 캐시를 활용하여 빠르게 완료됩니다. 소스 코드만 변경된 경우, 의존성 설치 단계는 캐시에서 가져옵니다.
Dockerfile 최적화 팁
빌드 캐시를 효과적으로 활용하려면 Dockerfile 작성 순서가 중요합니다.
1. 변경이 적은 레이어를 앞에 배치
# 좋은 예 - 의존성 먼저, 소스 코드는 나중에
COPY package*.json ./
RUN npm ci
COPY . .
# 나쁜 예 - 소스 코드 변경 시 의존성도 다시 설치
COPY . .
RUN npm ci
2. 멀티스테이지 빌드로 이미지 크기 최소화
# 빌드 단계: 빌드 도구 포함 (큰 이미지)
FROM node:20 AS builder
WORKDIR /app
COPY . .
RUN npm ci && npm run build
# 프로덕션 단계: 실행에 필요한 것만 (작은 이미지)
FROM node:20-alpine AS production
WORKDIR /app
COPY /app/dist ./dist
CMD ["node", "dist/main.js"]
3. .dockerignore로 불필요한 파일 제외
node_modules
.git
.env
*.log
.DS_Store
.dockerignore가 없으면 node_modules나 .git 폴더가 이미지에 포함되어 빌드 시간이 길어지고 이미지 크기가 커집니다. 반드시 .dockerignore 파일을 작성하세요.
빌드 이력 조회
과거 빌드 기록은 빌드 통계 탭에서 확인합니다.
- 서비스 상세 페이지의 빌드 단계를 클릭합니다.
- 빌드 통계 탭의 빌드 로그 영역에서 최근 빌드 목록을 확인합니다. 각 항목은 파이프라인 번호(#번호)와 상태 배지로 표시됩니다.
- 항목을 클릭하면 해당 빌드의 로그, 상태, 빌드 시각, 소요 시간을 볼 수 있습니다.
상단 요약에는 총 빌드 수, 성공/실패 수, 성공률, 평균 소요 시간이, '빌드된 이미지' 영역에는 성공한 빌드의 이미지 태그가 표시됩니다.
실패한 빌드의 로그를 확인하여 문제를 파악하거나, 성공한 빌드의 이미지 태그를 복사하여 배포에 사용할 수 있습니다.
문제 해결
빌드 중 자주 발생하는 문제와 해결 방법입니다.
Dockerfile을 찾을 수 없음
- 경로 오류: 빌드 설정에서 Dockerfile 경로가 정확한지 확인합니다.
- 파일명 대소문자:
Dockerfile이 정확한 대소문자인지 확인합니다 (dockerfile은 인식되지 않음) - Git 권한 부족: GitLab 토큰에
read_repository권한이 있는지 확인합니다.
빌드 실패
npm ERR!: 의존성 설치 실패입니다.package.json과package-lock.json을 확인하세요.COPY failed: 파일 경로 오류입니다. 경로를 확인하고.dockerignore를 검토하세요.Permission denied: 파일 권한 문제입니다. 파일 권한을 수정하거나RUN chmod를 추가하세요.Out of memory: 메모리 부족입니다. 관리자에게 빌드 Pod 리소스 증가를 요청하세요.
이미지 푸시 실패
- 인증 실패: 서비스 설정에서 Registry 자격증명(사용자명/비밀번호)을 재확인합니다.
- 권한 부족: Registry 프로젝트에 쓰기 권한이 있는지 확인합니다.
- 용량 초과: 멀티스테이지 빌드로 이미지 크기를 최적화합니다.
위 방법으로 해결되지 않으면 빌드 로그 전체를 확인하고, 필요시 관리자에게 문의하세요.
관련 가이드
- Build Wizard - Dockerfile이 없을 때 자동 생성
- Auto CI 설정 - 코드 푸시 시 자동 빌드
- K8s 배포 - 빌드된 이미지를 Kubernetes에 배포