Harbor 프라이빗 레지스트리 구축 및 데이터 마이그레이션

개요

Harbor는 컨테이너 이미지를 안전하게 저장하고 관리할 수 있는 오픈소스 레지스트리 솔루션입니다. 본 문서에서는 Harbor 설치부터 기존 레지스트리 마이그레이션까지 전체 과정을 다룹니다.

사전 준비: Docker 설치

Harbor는 컨테이너 기반으로 동작하므로 Docker 엔진이 필수입니다. 아직 설치되지 않은 경우 공식 문서를 참고하여 먼저 구성하세요.

Harbor 서버 구축

설치 패키지 다운로드

GitHub 릴리즈 페이지에서 오프라인 설치 파일을 확보합니다. 네트워크 환경에 따라 적절한 버전을 선택하세요.

# 최신 안정 버전 확인 후 다운로드
curl -LO https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz

# 또는 미러 사이트 활용
wget https://storage.googleapis.com/harbor-releases/release-2.11.0/harbor-offline-installer-v2.11.0.tgz

압축 해제 및 경로 설정

tar xvzf harbor-offline-installer-*.tgz
sudo mkdir -p /opt/registry
sudo mv harbor /opt/registry/

환경 설정 파일 구성

템플릿을 복사하여 실제 설정 파일을 생성합니다.

cd /opt/registry/harbor
cp harbor.yml.tmpl harbor.yml

핵심 설정 항목을 수정합니다:

hostname: 서버의 실제 IP 주소 또는 도메인
http.port: 서비스 포트 (기본값 80)
https: 내부망 사용 시 주석 처리, 외부 공개 시 인증서 설정
harbor_admin_password: 관리자 계정 비밀번호 변경

# harbor.yml 예시
hostname: 10.0.0.50

http:
  port: 8080

# https 섹션 전체 주석 처리
# https:
#   port: 443
#   certificate: /path/to/cert
#   private_key: /path/to/key

harbor_admin_password: SecurePass123!

설치 스크립트 실행

sudo ./install.sh

설치 완료 후 docker-compose.yml 파일이 자동 생성됩니다. 포트 변경이 필요한 경우 이 파일의 서비스 매핑을 조정한 후 Docker 데몬을 재시작합니다.

서비스 운영

# Harbor 시작
sudo docker compose up -d

# 상태 확인
sudo docker compose ps

# 로그 확인
sudo docker compose logs -f

Systemd 서비스 등록

OS 부팅 시 자동 시작을 위해 systemd 유닛 파일을 생성합니다.

sudo tee /etc/systemd/system/harbor.service > /dev/null <<'EOF'
[Unit]
Description=Harbor Container Registry
After=docker.service network.target
Requires=docker.service

[Service]
Type=simple
Restart=always
WorkingDirectory=/opt/registry/harbor
ExecStart=/usr/bin/docker compose -f /opt/registry/harbor/docker-compose.yml up
ExecStop=/usr/bin/docker compose -f /opt/registry/harbor/docker-compose.yml down

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable harbor --now
sudo systemctl status harbor

클이언트 환경 구성

Docker 데몬 설정

자체 서명 인증서를 사용하거나 HTTP로 운영하는 경우, 클라이언트에 비보안 레지스트리를 등록해야 합니다.

sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
  "insecure-registries": ["10.0.0.50:8080"]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

Harbor 사용 방법

웹 콘솔 접속

브라우저에서 http://10.0.0.50:8080 접속 후 관리자 계정으로 로그인합니다.

사용자명: admin
비밀번호: 설정 파일의 harbor_admin_password 값

프로젝트 생성

좌측 메뉴의 프로젝트 → 새 프로젝트를 통해 이미지 저장소를 생성합니다. 접근 권한은 Public(익명 풀 가능) 또는 Private(인증 필요) 중 선택합니다.

이미지 태깅 및 업로드

로컬 이미지를 Harbor 형식에 맞게 재태깅합니다.

# 이미지 정보 확인
docker images | grep nginx

# 태그 변경: 레지스트리주소/프로젝트명/이미지명:태그
docker tag nginx:alpine 10.0.0.50:8080/library/nginx:v1.0

# 레지스트리 인증
docker login 10.0.0.50:8080 -u admin -p SecurePass123!

# 이미지 푸시
docker push 10.0.0.50:8080/library/nginx:v1.0

이미지 다운로드

docker pull 10.0.0.50:8080/library/nginx:v1.0

레지스트리 마이그레이션

기존 Harbor 인스턴스에서 새로운 인스턴스로 데이터를 이전하는 방법을 설명합니다.

원격 레지스트리 등록

대상 Harbor의 웹 콘솔에서 시스템 관리 → 레지스트리 메뉴로 이동합니다.

새 엔드포인트 클릭
제공자: Harbor 선택
이름: 식별용 별칭 입력 (예: legacy-registry)
엔드포인트 URL: 원본 Harbor 주소 (http://192.168.1.100:5000)
액세스 ID/비밀번호: 원본 Harbor의 관리자 또는 서비스 계정
연결 테스트 후 저장

복제 규칙 구성

시스템 관리 → 복제 메뉴에서 마이그레이션 작업을 정의합니다.

설정 항목	설명
이름	작업 식별자 (예: migrate-from-legacy)
복제 모드	Pull-based (원격 → 로컬)
원본 레지스트리	앞서 등록한 레지스트리 선택
소스 필터	프로젝트/리포지토리/태그 패턴 지정 (비워두면 전체)
대상 임스페이스	선택 시 해당 프로젝트로 통합, 미선택 시 원본 구조 유지

마이그레이션 실행

생성된 복제 규칙의 복제 버튼을 클릭하여 즉시 실행하거나, 스케줄을 설정하여 주기적으로 동기화할 수 있습니다.

실행 후 작업 로그에서 진행 상황 및 결과를 모니터링합니다.

대안: CLI 기반 수동 마이그레이션

복제 기능을 사용하지 않는 경우, 스크립트로 직접 이전할 수도 있습니다.

#!/bin/bash
SRC_REG="192.168.1.100:5000"
DST_REG="10.0.0.50:8080"
PROJECT="production"

# 원본 레지스트리 인증
docker login $SRC_REG -u admin -p OldPassword123

# 이미지 목록 조회 (Harbor API 활용)
IMAGES=$(curl -s -u admin:OldPassword123 \
  "http://$SRC_REG/api/v2.0/projects/$PROJECT/repositories" | jq -r '.[].name')

for img in $IMAGES; do
  # 태그 목록 조회
  TAGS=$(curl -s -u admin:OldPassword123 \
    "http://$SRC_REG/api/v2.0/projects/$PROJECT/repositories/$img/artifacts" | jq -r '.[].tags[].name')
  
  for tag in $TAGS; do
    # 풀-태그-푸시
    docker pull $SRC_REG/$PROJECT/$img:$tag
    docker tag $SRC_REG/$PROJECT/$img:$tag $DST_REG/$PROJECT/$img:$tag
    docker push $DST_REG/$PROJECT/$img:$tag
    docker rmi $SRC_REG/$PROJECT/$img:$tag $DST_REG/$PROJECT/$img:$tag
  done
done

태그: Harbor docker Container Registry DevOps Image Migration

7월 15일 18:33에 게시됨

괴물 클럽