로컬에서 쿠버네티스 + GitLab CI/CD 구축하기 (1)

나근민·2025년 4월 8일

로컬에서 쿠버네티스 + GitLab으로 CI/CD 환경 구축하기

쿠버네티스 CI/CD

안녕하세요! 오늘은 로컬 환경에서 쿠버네티스와 GitLab으로 CI/CD 환경을 구축하는 방법을 공유하려고 합니다. 클라우드에서 쿠버네티스 구축하면 비용이 만만치 않잖아요. 그래서 로컬에서 가볍게 테스트용으로 구축하는 방법을 정리해봤어요. 생각보다 설정이 간단하니 따라와보세요!

📑 목차

Minikube와 Helm 개념 살펴보기
Minikube 설치하기
Helm 설치하기
GitLab Runner 설정하기
쿠버네티스에 GitLab Runner 설치하기
마무리 & 후기

1. Minikube와 Helm 개념 살펴보기

Minikube란?

Minikube는 간단히 말해 '내 노트북에서 쿠버네티스 놀이터를 만들어주는 도구'예요. 쿠버네티스가 여러 대 서버로 구성된 거대한 놀이공원이라면, Minikube는 그 축소판을 여러분 노트북에 만들어주는 거죠.

집에서 혼자 개발할 때 쿠버네티스처럼 복잡한 녀석을 어떻게 테스트하냐고요? 바로 이 Minikube가 그 해답이에요!

쉽게 비유하자면,

쿠버네티스: 빌딩 크기의 오락실이라고 생각해보세요
Minikube: 그 오락실의 미니어처를 내 책상 위에 놓는 것과 같죠!

Minikube의 핵심 기능
1. 내 컴퓨터에 작은 가상환경 하나 만들어서 쿠버네티스가 돌아갈 공간 확보
2. 진짜 쿠버네티스랑 거의 똑같이 동작하니까 개발/테스트할 때 완벽한 연습 상대
3. kubectl 명령어도 그대로 사용 가능

Helm이란?

Helm은 '쿠버네티스용 앱스토어' 같은 존재예요. 쿠버네티스에 뭔가 설치하려면 YAML 파일 몇십 개 작성해야 할 수도 있는데, Helm을 쓰면 그런 고통에서 벗어날 수 있어요.

제가 겪었던 경험을 말씀드리면, 데이터베이스 하나 설치하는데 YAML만 15개 넘게 작성했던 적이 있었어요. Helm을 알았더라면 명령어 한 줄로 끝났을 텐데 말이죠... 🥲

쉽게 비유하자면,

쿠버네티스에 앱 설치하기: 가구를 부품부터 조립하는 것과 같아요
Helm으로 설치하기: 완성된 가구를 배달시키는 것과 같죠!

Helm의 핵심 기능
1. 복잡한 앱(GitLab 같은)을 명령어 한 줄로 설치 가능
2. 설정값을 쉽게 바꿔가며 재사용 가능한 템플릿 제공
3. 버전 업그레이드/롤백도 간단하게 할 수 있어요

2. Minikube 설치하기

이제 Minikube를 설치해볼게요. 저는 Windows 환경을 기준으로 설명할게요. Mac이나 Linux 사용자분들은 Minikube 공식 문서를 참고해주세요!

2.1 PowerShell에서 Minikube 설치

먼저 관리자 권한으로 PowerShell을 실행해야 해요. 시작 메뉴에서 PowerShell을 검색한 후 마우스 오른쪽 버튼으로 클릭하고 "관리자 권한으로 실행"을 선택하세요.

그런 다음 다음 명령어를 실행해 주세요.

# 설치 폴더 만들고 Minikube 다운로드하기
New-Item -Path 'c:\' -Name 'minikube' -ItemType Directory -Force
Invoke-WebRequest -OutFile 'c:\minikube\minikube.exe' -Uri 'https://github.com/kubernetes/minikube/releases/latest/download/minikube-windows-amd64.exe' -UseBasicParsing

# 환경 변수 설정하기 (cmd에서도 minikube 명령어를 쓸 수 있게 해줘요)
$oldPath = [Environment]::GetEnvironmentVariable('Path', [EnvironmentVariableTarget]::Machine)
if ($oldPath.Split(';') -inotcontains 'C:\minikube'){
  [Environment]::SetEnvironmentVariable('Path', $('{0};C:\minikube' -f $oldPath), [EnvironmentVariableTarget]::Machine)
}

⚠️ 주의하세요!: 관리자 권한 없이 실행하면 "요청한 레지스트리에 액세스할 수 없습니다"라는 오류가 나올 수 있어요. 이건 환경 변수를 수정할 권한이 없어서 그래요.

2.2 Minikube 시작하기

Minikube 설치했으면 이제 시작해볼까요? 저는 Docker Desktop이 이미 설치되어 있어서 Docker를 하이퍼바이저로 사용할 거예요. VirtualBox나 Hyper-V도 사용 가능하니 본인 환경에 맞게 선택하세요.

minikube start --memory=4096 --cpus=2 --driver=docker

이 명령어는 "4GB 메모리, CPU 2개 사용해서 Docker 기반으로 미니큐브 시작해줘~"라는 의미예요. 개발용이라 적당한 사양으로 잡았어요.

처음 실행하면 필요한 이미지를 다운로드해서 조금 시간이 걸릴 수 있어요. 끝나면 위 스크린샷처럼 "성공적으로 시작했어요!" 메시지가 나와요.

💡 Tip: Docker를 드라이버로 사용할 때는 Docker Desktop이 실행 중이어야 해요! 만약 설치가 안 되어 있다면 Docker Desktop 사이트에서 설치해주세요.

2.3 Minikube 상태 확인

제대로 실행됐는지 확인해볼까요? 다음 명령어로 Minikube 상태를 체크할 수 있어요

minikube status

아래처럼 나오면 성공입니다! 🎉

minikube
type: Control Plane
host: Running
kubelet: Running
apiserver: Running
kubeconfig: Configured

모든 항목이 Running이나 Configured로 나오면 정상적으로 동작하고 있는 거예요. 이제 자기 맘대로 쿠버네티스 놀이터가 내 컴퓨터에 생겼네요!

혹시 오류가 발생한다면 대부분은 Docker가 실행 중이 아니거나, 메모리가 부족한 경우예요. Docker Desktop이 실행 중인지, 그리고 사용하지 않는 프로그램을 좀 꺼보세요.

3. Helm 설치하기

이제 쿠버네티스 패키지 관리자인 Helm을 설치해볼게요. Helm이 있으면 쿠버네티스에 앱 설치하는 게 훨씬 쉬워져요.

3.1 Chocolatey를 이용한 Helm 설치

Windows에서는 Chocolatey라는 패키지 관리자를 통해 Helm을 쉽게 설치할 수 있어요. 다음 명령어를 관리자 권한 PowerShell에서 실행해주세요:

choco install kubernetes-helm

이 명령이 실행되면 Helm이 자동으로 다운로드되고 설치됩니다. 설치가 끝나면 바로 helm 명령어를 사용할 수 있어요.

🔍 참고: Chocolatey가 없다면? Chocolatey 공식 사이트에서 간단하게 설치할 수 있어요. Windows용 패키지 관리자라고 생각하시면 돼요. 맥이라면 brew, 우분투라면 apt 같은 역할이죠.

설치 잘 됐는지 확인하려면 다음 명령어를 입력해보세요.

helm version

버전 정보가 출력되면 설치가 성공한 거예요!

4. GitLab Runner 설정하기

이제 GitLab CI/CD를 위한 Runner를 설정해볼게요. Runner는 CI/CD 작업을 실행해주는 녀석이에요. GitLab.com에 등록하고 토큰을 받아서 쿠버네티스에 설치할 거예요.

4.1 GitLab에서 Runner 토큰 가져오기

GitLab.com에 로그인합니다.
여러분의 프로젝트로 이동해요 (저는 vue-login 프로젝트를 예로 들게요).
왼쪽 메뉴에서 설정 → CI/CD → Runners 섹션으로 이동합니다.

"New project runner" 버튼을 클릭합니다.
Runner 태그와 설정을 입력할 수 있는 화면이 나와요. 저는 태그를 'vue-login'으로 지정했어요. 태그는 나중에 .gitlab-ci.yml 파일에서 특정 Runner를 지정할 때 사용돼요.

설정을 마치고 Runner를 생성하면 등록 명령어와 토큰이 표시됩니다. 이 토큰은 한 번만 보여주니 잘 복사해두세요!

Runner가 생성되면 프로젝트의 Runners 목록에서 확인할 수 있어요.

토큰을 텍스트 파일에 복사해두세요. 이 토큰은 다음 단계에서 쿠버네티스에 GitLab Runner를 설치할 때 사용할 거예요.

5. 쿠버네티스에 GitLab Runner 설치하기

이제 진짜 핵심이에요! 앞서 복사한 토큰을 이용해 쿠버네티스에 GitLab Runner를 설치해볼게요. Helm 차트를 이용하면 정말 간단해요.

5.1 Helm 저장소 추가

먼저 GitLab Helm 저장소를 시스템에 추가해야 해요.

helm repo add gitlab https://charts.gitlab.io/
helm repo update

첫 번째 명령어는 "GitLab이 제공하는 Helm 차트 저장소를 등록할게~"라는 의미고, 두 번째는 "저장소 목록을 최신 정보로 업데이트할게~"라는 의미예요. apt update 같은 역할이죠.

5.2 GitLab Runner용 네임스페이스 생성

쿠버네티스에서는 리소스들을 네임스페이스라는 논리적 영역으로 구분해요. GitLab Runner를 위한 전용 네임스페이스를 만들어볼게요.

kubectl create namespace gitlab-runner

이러면 gitlab-runner라는 네임스페이스가 생성돼요. 이제 이 안에 runner를 설치할 거예요.

5.3 GitLab Runner 설치

이제 Helm을 사용해 GitLab Runner를 설치해봅시다! 아까 복사해둔 Runner 토큰을 사용할 시간이에요.

helm install --namespace gitlab-runner gitlab-runner gitlab/gitlab-runner `
  --set gitlabUrl=https://gitlab.com `
  --set runnerRegistrationToken=여기에_복사한_토큰_붙여넣기

명령어가 좀 길죠? 분해해서 보면,

helm install: Helm으로 뭔가 설치할게~
--namespace gitlab-runner: gitlab-runner 네임스페이스에 설치할게~
gitlab-runner: 설치할 리소스의 이름은 gitlab-runner로 할게~
gitlab/gitlab-runner: gitlab 저장소에서 gitlab-runner 차트를 사용할게~
--set: 설정값을 지정할게~

⚠️ 중요!: gitlabUrl에는 GitLab 인스턴스 주소만 입력해야 해요(예: https://gitlab.com). 프로젝트 URL(https://gitlab.com/유저명/프로젝트)을 입력하면 안 돼요! 제가 처음에 이거 때문에 한참 삽질했어요...

설치가 완료되면 다음 명령어로 Runner가 정상적으로 실행 중인지 확인해볼 수 있어요:

kubectl get pods -n gitlab-runner

이런 식으로 출력되면 성공입니다:

NAME                             READY   STATUS    RESTARTS   AGE
gitlab-runner-7d6876b4c4-v9x8l   1/1     Running   0          2m

6. 마무리 & 후기

야호! 🎉 이제 로컬 쿠버네티스 환경에 GitLab Runner까지 설치 완료했어요. 이제 프로젝트에 CI/CD 파이프라인을 추가할 수 있는 환경이 준비됐어요.

다음에 해볼 것들:

.gitlab-ci.yml 파일 작성하기: 프로젝트 루트에 이 파일을 만들어서 CI/CD 파이프라인을 정의해보세요. 예를 들면,

stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  tags:
    - vue-login  # 아까 설정한 Runner 태그
  script:
    - echo "Building the app..."
    - npm install
    - npm run build

test_job:
  stage: test
  tags:
    - vue-login
  script:
    - echo "Running tests..."
    - npm run test

deploy_job:
  stage: deploy
  tags:
    - vue-login
  script:
    - echo "Deploying to kubernetes..."
    - kubectl apply -f k8s-deployment.yaml
  only:
    - main

쿠버네티스 배포 YAML 파일 작성하기: 애플리케이션을 쿠버네티스에 배포하는 YAML 파일도 필요해요.
Git에 커밋하고 푸시하기: 변경사항을 커밋하고 GitLab에 푸시하면 자동으로 CI/CD 파이프라인이 실행될 거예요!

이 환경의 장점

로컬에서 전체 개발 흐름 테스트 가능: 클라우드로 나가기 전에 로컬에서 모든 것을 검증할 수 있어요.
비용 절약: 학습 목적이라면 클라우드 쿠버네티스를 쓸 필요 없이 로컬에서 다 해결할 수 있어요.
CI/CD 경험: GitLab CI/CD의 강력한 기능을 경험할 수 있어요.

주의할 점

Minikube는 학습과 개발 목적으로만 사용하는 것이 좋아요. 실제 프로덕션에는 적합하지 않아요.
컴퓨터를 재시작하면 minikube start 명령어로 다시 시작해야 해요.
로컬 환경이라 네트워크 제약이 있을 수 있어요.

CI/CD 파이프라인 구축에 관한 더 자세한 내용은 다음 글에서 다룰게요! 궁금한 점이나 문제가 생기면 댓글로 남겨주세요. 😄

참고 자료

나근민

개발 공부중인 학생입니다~

이전 포스트

스프링 부트에서 음성 캡차 구현하기: Google TTS API 활용 🔊

다음 포스트