📦 Docker Hub 제한 탈출 — 온프레미스 Nexus Registry 구축기

Docker Hub의 Free 플랜에서는 Private Repository를 1개만 생성할 수 있다. 서비스가 하나일 때는 문제가 없지만, backend와 frontend처럼 이미지가 2개 이상 필요해지면 유료 플랜을 고려하거나, 자체 Registry를 운영해야 한다.

이 글에서는 온프레미스 Kubernetes 클러스터에 Nexus Repository Manager를 배포하고, 기존 Docker Hub 기반 CI/CD 파이프라인을 Nexus로 전환한 과정을 정리한다.

기존 구조와 문제점

기존에는 Jenkins(Kaniko)가 Docker Hub에 이미지를 push하고, 클러스터가 Docker Hub에서 pull하는 구조였다.

이 구조의 문제:

• Private Repository 1개 제한 (Free 플랜): backend, frontend 두 이미지를 private으로 관리할 수 없음
• Pull Rate Limit: 익명 100 pulls/6h, 인증 200 pulls/6h
• 외부 의존성: Docker Hub 장애 시 배포 불가

왜 Nexus인가

자체 Docker Registry를 운영하는 선택지는 여러 가지가 있다.

개인 인프라 규모에서는 단일 인스턴스로 운영 가능하고, Docker 외 다른 패키지 저장소도 겸할 수 있는 Nexus가 적합하다고 판단했다.

클러스터에 Nexus 배포하기

ArgoCD + Helm 배포 구성

기존 인프라가 ArgoCD의 App of Apps 패턴으로 관리되고 있으므로, Nexus도 동일하게 구성했다.

디렉토리 구조:

argocd-cluster/
├── nexus/
│   ├── values.yaml              # Helm values
│   └── manifests/
│       └── pvc.yaml             # PVC (별도 관리)
├── argocd/addons/apps/
│   └── nexus.yaml               # ArgoCD Application
└── routes/nexus/
    ├── httproute-nexus.yaml     # nexus.minseoky.me (Web UI)
    ├── httproute-registry.yaml  # registry.minseoky.me (Docker API)
    └── ...

ArgoCD Application 정의

Jenkins와 동일한 multi-source 패턴을 사용했다. Helm chart + values.yaml 참조 + 추가 매니페스트(PVC)를 3개의 source로 구성한다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nexus
  namespace: argocd
spec:
  project: default
  destination:
    server: https://kubernetes.default.svc
    namespace: nexus
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
  sources:
    - repoURL: https://sonatype.github.io/helm3-charts/
      chart: nexus-repository-manager
      targetRevision: 64.2.0
      helm:
        releaseName: nexus
        valueFiles:
          - $values/nexus/values.yaml
    - repoURL: https://github.com/minseoky/argocd-cluster.git
      targetRevision: prod
      ref: values
    - repoURL: https://github.com/minseoky/argocd-cluster.git
      targetRevision: prod
      path: nexus/manifests

Helm Values

image:
  repository: sonatype/nexus3
  tag: "3.89.1"

nexus:
  docker:
    enabled: true
    registries:
      - host: null
        port: 5000

  env:
    - name: INSTALL4J_ADD_VM_PARAMS
      value: "-Xms1g -Xmx2g -XX:MaxDirectMemorySize=2g"

resources:
  requests:
    cpu: "500m"
    memory: "2Gi"
  limits:
    cpu: "2"
    memory: "4Gi"

persistence:
  enabled: true
  existingClaim: nexus-data

deploymentStrategy: Recreate

핵심 포인트:

• 이미지 버전: 3.89.1 사용. 구 버전(3.64.0)은 보안 취약점 경고가 표시되며, 3.68.0 이전 버전에서 생성된 OrientDB 데이터는 최신 버전과 호환되지 않는다.
• Docker registry 포트: 5000번으로 설정. Helm 차트가 자동으로 별도 Service를 생성해준다.
• existingClaim: Helm 차트가 PVC annotation을 지원하지 않아, PVC를 별도 매니페스트로 분리했다.
• Recreate 전략: Nexus는 단일 인스턴스이므로 RollingUpdate 불가.

PVC와 NFS 스토리지

클러스터는 NFS 동적 프로비저닝(nfs-client StorageClass)을 사용한다. PVC를 별도로 생성하고 existingClaim으로 참조하는 이유는, Helm 차트가 PVC에 커스텀 annotation을 넣는 것을 지원하지 않기 때문이다.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: nexus-data
  namespace: nexus
  annotations:
    nfs.io/storage-path: "nexus-data"
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: nfs-client
  resources:
    requests:
      storage: 50Gi

NFS 특성상 PVC에 설정한 용량(50Gi)은 논리적 선언일 뿐, 실제로는 NAS 전체 볼륨이 마운트된다. Nexus UI에서도 Blob Store 용량이 NAS 전체 용량으로 표시된다.

데이터 안전성 측면에서는 StorageClass의 reclaimPolicy: Retain + archiveOnDelete: true 설정 덕분에, PVC를 삭제해도 NAS 디렉토리가 archived- 접두사로 보존된다.

Nexus 데이터 영속성

Nexus의 모든 데이터(설정, 사용자, 비밀번호, Blob Store)는 /nexus-data/ 에 저장되며, 이 경로가 PVC에 마운트된다.

• admin 비밀번호: 최초 기동 시 /nexus-data/admin.password 파일로 생성. UI에서 변경하면 파일이 삭제되고 H2 DB에 저장됨.
• Pod 재시작: PVC가 유지되는 한 모든 설정이 보존된다.

Gateway와 HTTPRoute 구성

외부 접근을 위해 두 개의 서브도메인을 구성했다.

Web UI와 Docker Registry를 분리한 이유는, Docker 클라이언트가 전용 포트(5000)로 통신해야 하기 때문이다. 같은 도메인에 비표준 포트를 쓰는 것보다, 별도 서브도메인으로 분리하는 것이 기존 Gateway 와일드카드(*.minseoky.me) 리스너를 그대로 활용할 수 있어 깔끔하다.

# Docker Registry용 HTTPRoute
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: nexus-registry
  namespace: nexus
spec:
  parentRefs:
    - name: gw-public
      namespace: gateway
      sectionName: https
  hostnames:
    - registry.minseoky.me
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: nexus-nexus-repository-manager-docker-5000
          port: 5000

CI/CD 파이프라인 전환

변경 전 vs 변경 후

Jenkinsfile 변경

변경 포인트는 Build & Push 단계와 Deploy 단계 두 곳이다.

Build & Push — 인증 대상과 destination 변경:

// 변경 전
withCredentials([usernamePassword(
    credentialsId: 'docker-hub-credentials',
    usernameVariable: 'DOCKER_USER',
    passwordVariable: 'DOCKER_PASS'
)]) {
    sh '''
        echo '{"auths":{"https://index.docker.io/v1/":{"username":"..."}}}' \
            > /kaniko/.docker/config.json
        /kaniko/executor \
            --destination=$DOCKER_USER/pullab-backend:$VERSION
    '''
}

// 변경 후
withCredentials([usernamePassword(
    credentialsId: 'nexus-registry-credentials',
    usernameVariable: 'REGISTRY_USER',
    passwordVariable: 'REGISTRY_PASS'
)]) {
    sh '''
        echo '{"auths":{"registry.minseoky.me":{"username":"..."}}}' \
            > /kaniko/.docker/config.json
        /kaniko/executor \
            --destination=registry.minseoky.me/pullab-backend:$VERSION
    '''
}

Deploy — sed 패턴 변경:

// 변경 전
sed -i 's|image: minseoky/pullab-backend:.*|...|'

// 변경 후
sed -i 's|image: .*pullab-backend:.*|image: registry.minseoky.me/pullab-backend:'"$VERSION"'|'

sed 패턴을 .*pullab-backend로 변경하여, 이전 경로(minseoky/)든 새 경로(registry.minseoky.me/)든 모두 매칭되도록 했다.

Deployment 매니페스트 변경

이미지 경로 변경과 함께 imagePullSecrets를 추가해야 한다. Nexus는 인증이 필요한 private registry이기 때문이다.

spec:
  template:
    spec:
      imagePullSecrets:
        - name: nexus-pull-secret    # 각 네임스페이스에 수동 생성
      containers:
        - image: registry.minseoky.me/pullab-backend:0.1.58

pull secret은 이미지를 사용하는 각 네임스페이스마다 생성해야 한다:

kubectl create secret docker-registry nexus-pull-secret \
  -n <namespace> \
  --docker-server=registry.minseoky.me \
  --docker-username=admin \
  --docker-password=<password>

배포 과정에서 만난 이슈들

OrientDB 호환성 문제

Helm 차트 기본 버전(3.64.0)으로 최초 기동한 후, 보안 취약점 경고가 표시되어 3.89.1로 업그레이드했다. 그런데 Pod가 CrashLoopBackOff에 빠졌다.

This instance is using a legacy Orient database.
You must migrate to H2 or PostgreSQL before upgrading to this version.

3.64.0이 OrientDB로 초기화한 데이터가 PVC에 남아 있었고, 3.89.1은 OrientDB를 지원하지 않기 때문이다. 신규 설치였으므로 PVC 데이터를 정리하고 재시작하여 해결했다.

교훈: Nexus 버전을 올릴 때는 DB 마이그레이션 요구사항을 반드시 확인해야 한다.

Blob Store 초기화 누락

PVC 데이터 정리 시 blobs 디렉토리까지 삭제되어, Nexus 기동 후 기본 Blob Store(default)가 "not available" 상태가 됐다. Pod를 재시작하여 자동 복구되었다.

최종 구조

정리

Docker Hub의 제한을 해결하면서, 이미지가 내부 네트워크에서 전송되므로 pull 속도도 빨라졌다. 기존 ArgoCD + Helm 패턴을 그대로 활용하여 추가 운영 복잡도도 최소화할 수 있었다.