수동 빌드

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 단계 클릭

파이프라인에서 Build 단계를 클릭합니다.
빌드 설정 모달이 열립니다.

Step 3: Dockerfile 설정

Dockerfile을 지정하는 세 가지 방법이 있습니다:

자동 감지: 저장소에서 Dockerfile을 자동으로 탐지합니다. 표준 구조의 프로젝트에 적합합니다.
경로 지정: Dockerfile 경로를 직접 입력합니다. 다중 Dockerfile이 있거나 비표준 위치에 있는 경우 사용합니다.
Build Wizard: Dockerfile이 없으면 자동으로 생성합니다. Dockerfile이 없는 프로젝트에 적합합니다.

Dockerfile 경로 예시:

./Dockerfile                    # 루트의 기본 Dockerfile (가장 일반적)
./docker/Dockerfile.prod        # 특정 환경용 Dockerfile
./services/api/Dockerfile       # 모노레포의 서비스별 Dockerfile

모범 사례

프로젝트 루트에 Dockerfile을 두는 것이 가장 일반적이고 권장됩니다. 특별한 이유가 없다면 자동 감지를 사용하세요.

Step 4: 빌드 대상 서비스 확인 (모노레포)

서비스가 모노레포 구조라면 빌드 모달이 저장소를 분석하여 빌드 가능한 서브 프로젝트 목록을 자동으로 감지합니다. 감지된 목록에서 빌드할 대상 서비스를 선택할 수 있으며, 단일 프로젝트 구조라면 이 단계는 생략됩니다.

빌드 인자(ARG)와 타겟 스테이지

BuildModal에는 빌드 경로, 빌드 인자(ARG), 타겟 스테이지를 직접 입력하는 UI 필드가 제공되지 않습니다. 해당 값은 Dockerfile 내부에서 ARG 선언과 멀티스테이지 구문(FROM ... AS <stage>)으로 직접 정의하세요.

Step 5: 이미지 레지스트리 정보 확인

레지스트리 정보는 별도 입력하지 않습니다. 서비스 등록 시 미리 설정한 registry_config 가 자동으로 사용되며, 값을 변경하려면 서비스 상세 페이지의 Registry 설정에서 수정하세요.

Step 6: 자동 배포 옵션 (선택)

빌드 모달의 자동 배포 토글을 켜면 빌드 성공 직후 지정한 서버로 곧바로 배포가 이어집니다. 토글을 켜면 배포 서버를 선택하는 드롭다운이 활성화되며, 끄면 빌드만 수행됩니다.

Step 7: 빌드 옵션 (선택)

수동 빌드 시 다음 옵션을 추가로 지정할 수 있습니다.

빌드 프로필: 빌드 Pod에 할당할 리소스 크기를 선택합니다. auto(기본), small, medium, large, extra-large, 2x-large, 4x-large 중 선택할 수 있으며, 빌드가 OOM으로 실패하거나 너무 오래 걸린다면 한 단계 위 프로필로 올려보세요.
No Cache: 활성화하면 BuildKit 캐시를 무시하고 모든 레이어를 새로 빌드합니다. 의존성 변경 후에도 캐시가 잘못 재사용되는 의심 상황에서 사용하세요.

Step 8: 설정 저장

저장 버튼을 클릭합니다.
"빌드 설정이 저장되었습니다" 메시지를 확인합니다.

빌드 실행하기

설정을 완료했다면 이제 실제로 빌드를 실행해 봅시다.

Step 1: 빌드할 브랜치 선택

서비스 상세 페이지에서 Build 단계를 클릭합니다.
브랜치 선택 드롭다운에서 빌드할 브랜치를 선택합니다.

브랜치 확인

잘못된 브랜치를 빌드하면 의도치 않은 코드가 배포될 수 있습니다. 빌드 전 브랜치를 다시 한번 확인하세요.

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 등의 패키지 캐시 디렉토리를 빌드 간 재사용할 수 있어 첫 빌드 이후에도 의존성 설치를 가속할 수 있습니다.

첫 빌드 vs 이후 빌드

첫 빌드는 모든 레이어를 새로 생성해야 하므로 오래 걸립니다. 두 번째 빌드부터는 캐시를 활용하여 빠르게 완료됩니다. 소스 코드만 변경된 경우, 의존성 설치 단계는 캐시에서 가져옵니다.

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 --from=builder /app/dist ./dist
CMD ["node", "dist/main.js"]

3. .dockerignore로 불필요한 파일 제외

node_modules
.git
.env
*.log
.DS_Store

.dockerignore가 없으면

node_modules나 .git 폴더가 이미지에 포함되어 빌드 시간이 길어지고 이미지 크기가 커집니다. 반드시 .dockerignore 파일을 작성하세요.

빌드 이력

과거 빌드 기록을 조회하고 관리할 수 있습니다.

이력 조회 방법

서비스 상세 페이지의 Build 단계를 클릭합니다.
빌드 이력 탭을 선택합니다.

이력에서 확인할 수 있는 정보

빌드 번호: 순차적으로 부여된 빌드 식별 번호
브랜치: 빌드에 사용된 Git 브랜치
커밋: 빌드 시점의 커밋 해시 (클릭 시 GitLab으로 이동)
상태: 성공 / 실패 / 진행중 / 취소됨
소요 시간: 빌드에 걸린 시간
이미지 태그: 생성된 이미지의 전체 태그

빌드 이력 활용

실패한 빌드의 로그를 확인하여 문제를 파악하거나, 성공한 빌드의 이미지 태그를 복사하여 배포에 사용할 수 있습니다.

문제 해결

빌드 중 자주 발생하는 문제와 해결 방법입니다.

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 프로젝트에 쓰기 권한이 있는지 확인합니다.
용량 초과: 멀티스테이지 빌드로 이미지 크기를 최적화합니다.

해결되지 않는 문제

위 방법으로 해결되지 않으면 빌드 로그 전체를 확인하고, 필요시 관리자에게 문의하세요.

빌드 개요​

빌드 설정하기​

Step 1: 서비스 상세 페이지로 이동​

Step 2: Build 단계 클릭​

Step 3: Dockerfile 설정​

Step 4: 빌드 대상 서비스 확인 (모노레포)​

Step 5: 이미지 레지스트리 정보 확인​

Step 6: 자동 배포 옵션 (선택)​

Step 7: 빌드 옵션 (선택)​

Step 8: 설정 저장​

빌드 실행하기​

Step 1: 빌드할 브랜치 선택​

Step 2: 빌드 시작​

Step 3: 빌드 로그 확인​

Step 4: 빌드 완료 확인​

빌드 최적화​

캐시 활용으로 빌드 속도 향상​

Dockerfile 최적화 팁​

빌드 이력​

이력 조회 방법​

이력에서 확인할 수 있는 정보​

문제 해결​

Dockerfile을 찾을 수 없음​

빌드 실패​

이미지 푸시 실패​

관련 가이드​