본문으로 건너뛰기

서비스 등록

Git 저장소의 소스 코드를 KIWI에 연동하면, 코드 변경부터 배포까지 모든 과정을 자동화할 수 있습니다. 이 가이드에서는 서비스를 등록하고 첫 빌드까지 완료하는 방법을 안내합니다.

왜 서비스 등록이 필요한가요?​

KIWI에 서비스를 등록하면 다음과 같은 이점이 있습니다:

수동 작업과 KIWI 사용 비교
  • 빌드: 수동으로는 로컬에서 docker build를 실행해야 하지만, KIWI에서는 버튼 클릭 또는 자동 트리거로 빌드됩니다.
  • 배포: 수동으로는 kubectl/docker 명령어를 직접 실행해야 하지만, KIWI에서는 원클릭으로 배포됩니다.
  • 보안 스캔: 수동으로는 별도 도구 설치와 실행이 필요하지만, KIWI에서는 빌드 시 자동으로 실행됩니다.
  • 롤백: 수동으로는 이전 이미지를 찾아서 직접 배포해야 하지만, KIWI에서는 배포 이력에서 클릭만 하면 됩니다.

사전 준비사항​

서비스 등록 전 다음을 준비하세요:

  • Git 저장소 URL: GitLab, GitHub 등의 저장소 주소
  • 저장소 접근 토큰: Personal Access Token (아래에서 생성 방법 안내)
  • 런타임 환경: 배포할 Kubernetes 또는 Docker가 **[런타임 환경]**에 등록되어 있어야 합니다 .
권한 안내

이 기능에 접근할 수 없다면 기관 관리자에게 service 권한을 요청하세요.

Git 저장소 연동하기​

회사의 Git 저장소를 KIWI에 연동합니다. 한 번 연동하면 이후 모든 빌드/배포에 자동으로 사용됩니다.

Step 1: 서비스 등록 시작​

좌측 메뉴에서 **[서비스 관리]**를 클릭하고, 우측 상단의 서비스 등록 버튼을 클릭합니다.

서비스 관리 페이지

서비스 등록 모달

Step 2: Git 저장소 정보 입력​

서비스 등록 마법사에서 저장소 정보를 입력합니다:

  • 서비스명: 팀 내에서 쉽게 식별할 수 있는 이름입니다. (예: user-api, payment-service)
  • Git URL: 저장소의 클론 URL입니다. (예: https://gitlab.com/company/project.git)
  • 브랜치: 기본으로 빌드할 브랜치입니다. (예: main, develop)
  • 인증 방식: Personal Access Token 사용을 권장합니다.

Step 3: GitLab Personal Access Token 생성​

KIWI가 저장소에 접근하려면 토큰이 필요합니다.

GitLab 토큰 생성 방법
  1. GitLab에 로그인 → 우측 상단 프로필 아이콘 클릭
  2. Settings → Access Tokens 메뉴 선택
  3. 토큰 이름 입력 (예: KIWI-access)
  4. 만료일 설정 (보안을 위해 1년 이내 권장)
  5. 권한 선택: read_repository, read_api 체크
  6. Create personal access token 클릭
  7. 생성된 토큰을 복사하여 KIWI에 입력

주의: 토큰은 생성 직후에만 확인 가능합니다. 안전한 곳에 보관하세요.

Step 4: 저장소 연결 확인​

연결 테스트 버튼을 클릭합니다. 연결이 성공하면 브랜치 목록이 드롭다운에 표시됩니다.

연결 실패 시 확인사항
  • Git URL이 정확한지 확인 (.git으로 끝나야 함)
  • 토큰에 read_repository 권한이 있는지 확인
  • 토큰이 만료되지 않았는지 확인

빌드 설정하기​

등록한 서비스의 Docker 이미지를 빌드하도록 설정합니다. 이 설정은 한 번만 하면 이후 빌드에 자동으로 적용됩니다.

Step 1: 빌드 탭 이동​

서비스 목록에서 등록한 서비스를 클릭 → 상단 탭에서 빌드 탭을 클릭합니다.

빌드 탭

Step 2: Dockerfile 설정​

프로젝트에 맞는 Dockerfile 구성 방식을 선택합니다:

  • 자동 감지: 저장소 내 Dockerfile을 자동으로 찾습니다. Dockerfile이 루트에 있는 경우에 권장합니다.
  • 경로 지정: Dockerfile 경로를 직접 입력합니다. 여러 Dockerfile이 있거나 하위 폴더에 있는 경우에 사용합니다.
  • 빌드 마법사: KIWI가 Dockerfile을 자동 생성합니다. Dockerfile이 없는 경우에 사용하세요.
Dockerfile이 없어도 괜찮아요

빌드 마법사를 사용하면 프로젝트 언어(Node.js, Python, Java, Go 등)와 프레임워크를 선택하기만 하면 최적화된 Dockerfile이 자동으로 생성됩니다.

Step 3: 이미지 레지스트리 설정​

빌드된 이미지를 저장할 레지스트리 정보를 입력합니다:

  • 레지스트리 URL: Harbor 또는 DockerHub 주소 (예: harbor.company.com)
  • 이미지 이름: 이미지 경로 (예: library/my-web-app)
  • 태그 규칙: 버전 태깅 방식 (예: ${BRANCH}-${SHORT_SHA})

Step 4: 빌드 런타임 선택 및 첫 빌드 실행​

등록된 Kubernetes 클러스터 중 빌드를 실행할 환경을 선택하고, 빌드 시작 버튼을 클릭합니다.

Kaniko 빌드

KIWI는 Kaniko를 사용하여 Kubernetes 클러스터 내에서 안전하게 이미지를 빌드합니다. Docker 데몬이 필요 없어 보안성이 높습니다.

빌드 로그를 실시간으로 확인할 수 있습니다. 첫 빌드는 의존성 다운로드로 인해 시간이 좀 더 걸릴 수 있습니다.

배포 환경 설정하기​

빌드된 이미지를 실제 서버에 배포하도록 설정합니다.

Step 1: 배포 탭 선택​

상단 탭에서 배포 탭을 클릭합니다.

배포 탭

Step 2: 배포 대상 선택​

등록된 런타임 환경 중 배포할 클러스터를 선택합니다. 환경 구분도 함께 선택합니다:

  • Development: 개발/테스트 환경입니다. 레플리카 1개, 낮은 리소스로 설정합니다.
  • Staging: QA/검증 환경입니다. 운영과 유사하게 설정합니다.
  • Production: 실제 서비스 환경입니다. 레플리카 2개 이상, 충분한 리소스를 할당합니다.

Step 3: 배포 설정 입력​

배포에 필요한 설정을 입력합니다:

  • 네임스페이스: Kubernetes 네임스페이스 (예: production)
  • 레플리카 수: Pod 복제본 개수 (가용성을 위해 2개 이상 권장)
  • 리소스 제한: CPU/메모리 요청 및 제한값
  • 환경 변수: 데이터베이스 연결 정보, API 키 등

Step 4: 첫 배포 실행​

배포 버튼을 클릭합니다. 배포 상태를 실시간으로 모니터링할 수 있습니다.

배포 성공 확인 방법

배포가 완료되면 [런타임 환경] 페이지에서 Pod 상태가 Running인지 확인하세요. 서비스 URL로 접속하여 정상 동작을 확인하는 것도 좋습니다.

자주 묻는 질문​

Git 연결이 실패합니다​

증상별 해결 방법:

  • "Authentication failed": 토큰이 만료되지 않았는지, read_repository 권한이 있는지 확인하세요.
  • "Repository not found": URL이 .git으로 끝나는지, 오타가 없는지 확인하세요.
  • "Connection timeout": 방화벽 설정과 GitLab 서버 상태를 확인하세요.

빌드가 실패합니다​

빌드 로그에서 오류 메시지를 확인하세요. 자주 발생하는 원인:

  • Dockerfile 문법 오류 (대소문자, 공백)
  • 베이스 이미지 접근 불가 (네트워크, 인증)
  • 의존성 설치 실패 (버전 충돌, 삭제된 패키지)

이미지 푸시가 실패합니다​

레지스트리 인증 정보가 올바른지 확인하세요. 서비스 설정에서 레지스트리 연결 상태를 테스트할 수 있습니다.

배포 후 Pod가 시작되지 않습니다​

Pod 이벤트 로그를 확인하세요:

  • ImagePullBackOff: 이미지 경로/인증 확인
  • CrashLoopBackOff: 애플리케이션 로그에서 시작 오류 확인
  • Pending: 리소스 부족, 노드 선택 조건 확인

다음 단계​

서비스 등록이 완료되면 다음 기능을 활용해 보세요:

추천 다음 단계
  1. 보안 스캔 설정 - 빌드 시 자동으로 취약점을 검사합니다 .
  2. 빌드/배포 상세 설정 - 자동 빌드 트리거, 배포 전략 등 고급 설정
  3. Auto CI 설정 - 코드 푸시 시 자동 빌드/배포