Cloud-Native Application Platform

cnapcloud/harbor는 공식 Harbor를 포크하여 arm64/amd64 멀티아키텍처 이미지 빌드를 지원하도록 수정한 프로젝트입니다. 공식 Harbor는 amd64 전용 이미지만 제공하지만, 이 포크에서는 두 아키텍처에 대한 이미지를 미리 빌드하여 제공합니다.

이 포스트에서는 해당 저장소의 prebuilt 이미지를 사용하여 docker-compose로 Harbor를 실행하는 방법을 정리합니다. 이미지 빌드 방법 등 자세한 내용은 make/README.md를 참고하세요.

1. 설정 파일 수정 (Configuration)

make/harbor.yml에서 호스트명과 인증서 경로를 환경에 맞게 수정합니다.

vi make/harbor.yml

HTTPS를 사용하는 경우 인증서 경로를 미리 지정합니다.

# make/harbor.yml
https:
  port: 443
  certificate: /path/to/fullchain.pem
  private_key: /path/to/privkey.pem

인증서가 없는 경우 Let’s Encrypt 또는 자체 서명 인증서를 생성하여 사용할 수 있습니다. 자체 서명 인증서 생성 방법은 사설 Harbor TLS 인증 오류 해결 방안 포스트를 참고하세요.

자체 서명 인증서를 직접 생성하려면 아래 명령을 사용합니다.

cd make/cert
HARBOR_HOST=harbor.cnap.dev
openssl req -x509 -nodes -days 365 -newkey rsa:4096 \
  -keyout privkey.pem -out fullchain.pem \
  -subj "/CN=${HARBOR_HOST}" \
  -addext "subjectAltName=DNS:${HARBOR_HOST}"

2. docker-compose.yml 생성 (Prepare)

make prepare 명령을 실행하면 현재 머신의 아키텍처를 감지하여 docker-compose.yml이 자동 생성됩니다.

# TRIVYFLAG=true 없으면 trivy-adapter 서비스가 제외됩니다
make prepare \
  VERSIONTAG=v2.15.0 \
  IMAGENAMESPACE=cnapcloud \
  TRIVYFLAG=true

생성된 docker-compose.yml에는 모든 서비스에 현재 머신의 플랫폼이 자동으로 명시됩니다.

services:
  core:
    image: cnapcloud/harbor-core:v2.15.0
    platform: linux/arm64   # 또는 linux/amd64
    ...

make/harbor.yml을 수정한 경우 반드시 make prepare를 재실행해야 변경 사항이 docker-compose.yml에 반영됩니다.

3. Harbor 시작 및 중지 (Start / Stop)

make/common/config/ 하위 설정 파일이 root 소유로 생성되므로 실행 시 root 권한이 필요합니다.

Harbor 시작

sudo make start

Harbor 중지

sudo make down

Harbor가 시작되면 브라우저에서 아래 주소로 접속합니다.

https://harbor.cnap.dev

기본 관리자 계정은 admin / Harbor12345입니다. 최초 로그인 후 반드시 비밀번호를 변경하세요.

4. 이미지 Push (Image Push)

Harbor가 정상 구동된 후 이미지를 push하는 예시입니다.

로그인

docker login harbor.cnap.dev

이미지 태깅 및 Push

docker pull nginx:latest
docker tag nginx:latest harbor.cnap.dev/library/nginx:latest
docker push harbor.cnap.dev/library/nginx:latest

5. 자체 서명 인증서 오류 해결 (Self-Signed Certificate)

자체 서명 인증서를 사용하는 경우 docker login 또는 docker push 시 아래와 같은 오류가 발생할 수 있습니다.

x509: certificate signed by unknown authority

Harbor CA 인증서를 OS 신뢰 저장소에 등록하면 해결됩니다.

Linux:

sudo cp make/cert/fullchain.pem /usr/local/share/ca-certificates/harbor-ca.crt
sudo update-ca-certificates
sudo systemctl restart docker

macOS:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain make/cert/fullchain.pem

macOS에서는 키체인 등록 후 Docker Desktop을 재시작합니다.

docker-compose로 멀티아키텍처 Harbor 실행하기

1. 설정 파일 수정 (Configuration)

2. docker-compose.yml 생성 (Prepare)

3. Harbor 시작 및 중지 (Start / Stop)

4. 이미지 Push (Image Push)

5. 자체 서명 인증서 오류 해결 (Self-Signed Certificate)