[Jenkins] Docker로 띄운 Jenkins, 데이터 그대로 Kubernetes로 이관하기

오랫동안 단일 Docker 컨테이너로 띄워 묵묵히 일해오던 Jenkins. 인프라 환경을 K3s (Lightweight Kubernetes)로 고도화하면서, 이 젠킨스도 쿠버네티스 클러스터 안으로 이사를 시켜야 할 때가 왔다.

가장 큰 고민은 “데이터”였다. 수많은 빌드 히스토리, 꼼꼼하게 설정해 둔 Job 설정, 그리고 사용자 계정들… 단순히 새 젠킨스를 띄우는 게 아니라, “데이터까지 그대로” 옮기는 것이 이번 마이그레이션의 핵심 목표였다.

성공적으로 이관을 마친 과정을 회고 차원에서 기록해 둔다.

1. 이관 전략: 데이터는 $JENKINS_HOME에 있다

Jenkins는 구조가 단순해서 다행이다. 거의 모든 설정과 데이터가 파일 시스템($JENKINS_HOME)에 저장된다. 즉, 전략은 간단하다.

1. Old: Docker 볼륨의 데이터를 백업한다.
2. New: K3s에 PVC(Claim)를 생성하여 실제 저장 공간인 PV를 할당받는다.
3. Move: 할당받은 PV에 데이터를 밀어 넣고, Helm으로 젠킨스를 띄운다.

2. 작업 과정 (Step-by-Step)

Step 1. 호스트 데이터 백업 (Docker)

먼저 기존 젠킨스 컨테이너가 마운트하고 있는 호스트 경로를 확인하고 압축했다. SSH 키나 기타 설정도 다 여기 들어있다.

# 호스트 경로 확인 (Source 부분 확인)
docker inspect jenkins | grep Source 

# 데이터 압축 (호스트 서버에서 수행)
# /var/jenkins_home 전체를 jenkins_backup.tar.gz로 압축
sudo tar -czvf jenkins_backup.tar.gz -C /var/jenkins_home .

Step 2. K3s PVC 생성

데이터가 저장될 실제 공간(PV)을 동적으로 할당받기 위해, 먼저 PVC(jenkins-pvc)를 작성했다.
(accessModes는 ReadWriteOnce로, 용량은 기존 데이터보다 넉넉하게 잡았다.)

이 PVC가 생성되면 K3s의 스토리지 클래스가 자동으로 적절한 PV를 프로비저닝하고 바인딩해준다.

Step 3. 데이터 전송과 “권한” 문제 (Key Point) 🔑

PV에 데이터를 넣으려면, 해당 스토리지에 접근할 수 있는 수단이 필요하다. PVC를 마운트한 임시 파드(Helper Pod)를 하나 띄워서, 파드를 통해 실제 PV 공간에 접근했다.

# 로컬의 백업 파일을 임시 파드(PV가 마운트된 경로)로 전송
kubectl cp ./jenkins_backup.tar.gz default/helper-pod:/data/jenkins_backup.tar.gz

여기서 가장 중요한 포인트! 압축을 풀면 파일 소유권이 root로 되어 있을 수 있다. 하지만 Jenkins 컨테이너 내부 프로세스는 UID 1000을 사용한다. PV 내의 파일 소유권을 맞춰주지 않으면 젠킨스가 켜지자마자 “Permission denied”를 뱉으며 죽는다.

# 임시 파드 내부에서 반드시 수행
chown -R 1000:1000 /data

Step 4. Helm Chart 배포 (values.yaml)

이제 공식 Jenkins Helm Chart를 사용해 배포했다. values.yaml에서 existingClaim 옵션을 사용하여, 우리가 데이터를 채워 넣은 그 PVC를 바라보도록 설정했다.

[values.yaml 설정]

persistence:
  enabled: true
  existingClaim: jenkins-pvc # 데이터가 준비된 PVC(와 바인딩된 PV)를 사용

controller:
  ingress:
    enabled: true
    ingressClassName: traefik
    hostName: jenkins.jay-gemini.com

[common-values.yaml 설정]

YAML

controller:
  admin:
    username: "newuser" # 새로운 관리자 계정 명시
    password: "password"
  installPlugins:
    - kubernetes
    - git
    # ... 기타 플러그인

3. 결과 및 기술적 인사이트: “두 명의 관리자?”

배포 후 설레는 마음으로 접속했다. 결과는 대성공! 🎉 기존 Job 리스트와 빌드 번호가 그대로 유지되었다.

그런데 한 가지 흥미로운 현상을 발견했다. 로그인을 시도해 보니, 기존 Docker 시절에 쓰던 계정으로도 로그인이 되고, 이번에 values.yaml에 새로 적어넣은 newuser 계정으로도 로그인이 되는 것이다.

🤔 왜 계정이 섞여서 나올까?

1. Persistence (유지): PV에 저장된 기존 /users 폴더의 XML 데이터가 그대로 로드되었기 때문에 옛날 계정이 살아있다.
2. JCasC / Init Script (추가): Helm Chart가 배포될 때, values.yaml에 정의된 admin 정보를 바탕으로 초기화 스크립트가 돌면서 newuser 계정을 “없으면 생성(Create)” 했기 때문이다.

결국 [기존 데이터 파일] + [새로운 Helm 설정]이 완벽하게 Merge(병합) 되었다는 증거다. 데이터가 덮어씌워져 날아가지 않았다는 뜻이라 오히려 안심이 되었다.

4. 마무리

Docker에서 Kubernetes로의 이관은 데이터 이관의 부담이 있어서 한동안 가만히 두었었다.
그러나, 간단한 Jenkins 내부의 폴더 구조 및 PVC 및 PV의 개념을 확실히 가지고 가고 있으면 데이터를 안전하게 이관할 수 있음을 알게 되었다.

이제 K3s 위에서 더 유연하게 CI/CD 파이프라인을 굴려볼 예정이다.

---

끝.