쿠버네티스 Private 컨테이너 레지스트리 구축 방법

쿠버네티스 환경에서 안전하고 효율적인 Private 컨테이너 레지스트리를 구축하는 방법을 소개합니다.

2025년 07월 02일

1. Private Container Registry 구축 방안

쿠버네티스 기반 MSA 환경에서는 컨테이너 이미지를 내부 또는 외부 레지스트리에 안전하고, 확장 가능하게 저장하고 배포하는 것이 매우 중요합니다.

먼저 Private Registry를 선택할 때는 다음과 같은 구조적 요소를 중심으로 확보하시는 것이 핵심입니다.

스토리지 안정성
레지스트리 저장소(예: /var/lib/registry)는 Pod 재시작이나 노드 이동에도 흔들림 없이 유지되어야 합니다. 따라서 NFS, Ceph, GlusterFS 같은 영속 볼륨이나 클라우드 기반 Block / Object Storage와 연결하여 볼륨 문제를 해결해야 합니다.
TLS 기반 보안 통신
HTTPS를 통해 레지스트리와 쿠버네티스 간 통신을 암호화하고, CA 서명된 인증서로 신뢰성을 보장하는 것이 필수입니다. 자체 서명(Self‑Signed)보다 CA 서명 인증서가 운영 환경에서는 더 권장됩니다 .
접근 제어 및 권한 최소화
레지스트리 접근에 사용할 계정은 반드시 “이미지 Pull 전용” 권한을 적용해야 하며, 관리자 권한은 별도로 관리하도록 설계해야 합니다.
버전 관리 및 태깅 정책
‘latest’ 태그 사용은 지양하고, Semantic Versioning(v1.0.0) 또는 커밋 해시 기반 명명 규칙을 도입해서 이미지별 버전 추적이 명확하게 이뤄져야 합니다.
이미지 스캔 및 콘텐츠 무결성
이미지 Push 시 취약점 스캔(Vulnerabilities Scan)을 자동화하고, 컨텐츠 트러스트(Content Trust)로 이미지가 변조되지 않았음을 보장하는 정책을 포함해야 안정성을 높일 수 있습니다.
Geo‑Replication 및 네트워크 중계
여러 리전 또는 AZ 환경에서는 내부 네트워크 지연을 줄이기 위해 레지스트리의 지리적 복제(Geo‑Replication) 기능 또는 캐시 전략을 적용하는 것이 좋습니다.
스토리지 최적화 (CAS & 레이어중복)
CAS(Content-Addressable Storage) 기반 저장소로 설정하면 이미지 레이어 중복 저장을 방지하고 스토리지 효율성을 높이는 효과가 있습니다 .

2. 컨테이너 Base 이미지 관리 방안

필요한 컨테이너 이미지 종류

프라이빗 레지스트리 구축을 위해서는 다음과 같은 핵심 컨테이너 이미지들이 필요합니다.

Harbor 관련 이미지: Harbor Core, Registry, Redis, PostgreSQL, Portal, JobService, ChartMuseum 등의 컴포넌트 이미지가 필요합니다. 이는 컨테이너 레지스트리의 핵심 기능을 제공합니다.
보안 스캔 이미지: Trivy, Clair와 같은 취약점 스캐닝 도구 이미지를 통해 컨테이너 보안을 강화할 수 있습니다.
모니터링 이미지: Prometheus, Grafana 등의 모니터링 도구 이미지로 레지스트리의 상태와 성능을 추적합니다.

Base 이미지 선택 조건

Base 이미지를 선택할 때는 다음과 같은 주요 조건들을 고려해야 합니다:

보안성: 알려진 취약점이 패치된 최신 버전의 이미지를 선택하며, 정기적인 보안 업데이트가 제공되는 공식 이미지를 우선적으로 고려합니다.
경량화: Alpine Linux나 distroless 이미지와 같이 최소한의 구성요소만 포함된 이미지를 선택하여 보안 표면적을 줄이고 성능을 최적화합니다.
안정성: 커뮤니티에서 검증된 LTS(Long Term Support) 버전의 이미지를 선택하여 장기적인 운영 안정성을 확보합니다.
호환성: 사용 중인 쿠버네티스 버전 및 컨테이너 런타임과의 호환성이 검증된 이미지를 선택합니다.

3. 컨테이너 이미지 백업 방안

컨테이너 레지스트리의 백업은 단순히 저장된 이미지 파일만을 대상으로 하는 것이 아니라, 이미지의 메타데이터(사용자 정보, 프로젝트 정보, 태그, 정책 등)까지 포함하는 전체 시스템의 보호를 목표로 해야 합니다.

아래에서 제시한 네 가지 방식은 엔터프라이즈 수준에서 안정성과 복구 능력을 확보하기 위한 필수 구성 요소들입니다. 각 항목을 좀 더 구체적으로 설명드리겠습니다.

1. Harbor + Distributed MinIO 구성

Harbor는 기업용으로 널리 사용되는 OCI(컨테이너 이미지) 레지스트리로, 보안, 사용자 관리, 정책 제어 기능이 강화된 레지스트리입니다. 이 때 이미지 저장소와 메타데이터 저장소를 분리하여 구성하는 것이 핵심입니다.

이미지 데이터 저장: Harbor는 기본적으로 이미지를 로컬 파일 시스템에 저장할 수 있으나, 분산 오브젝트 스토리지인 MinIO를 연동하면 고가용성(HA)과 확장성을 확보할 수 있습니다. 예를 들어 3~4개의 MinIO 노드를 구성하여 EC(Erasure Coding) 방식으로 데이터 중복을 최소화하고 내구성을 높입니다.
메타데이터 저장: 사용자 정보, 프로젝트 설정, 레지스트리 설정 등은 PostgreSQL DB에 저장됩니다. 이 부분은 이미지 자체와 달리 데이터베이스 백업을 통해 보호해야 합니다.
장점: 구성 요소가 분리되어 있으므로, 이미지 복원과 메타데이터 복원을 독립적으로 수행할 수 있어 장애 대응이 유연합니다. 실제로 LINE 엔지니어링 사례에서도 이 구조가 채택되었으며, 실무 적용 사례가 검증되어 신뢰할 수 있습니다.

🔗 LINE Engineering Harbor 구성 사례 보기

2. Velero + 오브젝트 스토리지 기반 백업

Velero는 Kubernetes 리소스 및 Persistent Volume에 대한 백업/복원 기능을 제공하는 오픈소스 도구입니다.

백업 대상:
- 레지스트리가 위치한 네임스페이스 전체 (Deployment, ConfigMap, Secret, PVC 등)
- 실제 이미지 파일이 저장되는 Persistent Volume (PV)
백업 방식:
- PV는 Restic 또는 CSI(CSI Snapshotter)를 사용해 S3 호환 스토리지(MinIO, AWS S3 등)로 백업
- 쿠버네티스 리소스는 YAML 형태로 백업되어 구성 복원이 용이
장점: 클러스터 전환 혹은 장애 시에도 복원이 빠르고, GitOps나 IaC와 조합하여 운영 일관성을 유지할 수 있습니다.

🔗 Red Hat의 Velero 기반 백업 가이드

3. 백업 일정 및 보관 정책

레지스트리의 안정성을 높이기 위해서는 단순한 백업을 넘어 정기성과 정책 기반 관리가 필요합니다.

스케줄 예시:
- 매일 오전 7시: 전체 스냅샷 (Restic full backup)
- 매주 일요일: 전체 백업 + 메타데이터 dump (PostgreSQL 백업)
- 매월 1일: 장기 보관용 사본 생성 (예: Glacier, Tape 등으로 오프라인 백업)
보안 및 감사 기능 강화:
- 랜섬웨어 대응: 오브젝트 락 설정, MinIO WORM(Write Once Read Many) 활성화
- IAM 로그 추적: 누가, 언제 이미지를 삭제했는지 추적 가능하도록 audit log 및 API access log 활성화 필요

4. 정기 복원 테스트 수행

백업만 해두고 복원을 검증하지 않으면 무용지물입니다. 복원 테스트는 백업 전략의 필수 절차입니다.

Cold-standby 테스트:
- 비운영 환경에 Harbor + MinIO 구성 후 백업 이미지 복원
- PostgreSQL 메타데이터 dump 파일로 프로젝트, 사용자 등 복원 확인
- 실제 이미지 docker pull 가능 여부 확인
운영 환경 DR Simulation:
- 실제 클러스터의 테스트 네임스페이스를 대상으로 복원
- 예상 장애 시나리오(예: 메타데이터 유실, 이미지 삭제 등)를 구성하고 대응책 검증
테스트 주기: 분기 1회 또는 운영정책상 중요한 릴리즈 후에 필수 수행

이러한 백업 전략은 단순히 재해복구(DR)를 위한 목적이 아니라, 운영 안정성과 감사 추적성, 그리고 보안 규정 준수를 동시에 만족시키기 위한 필수 전략입니다. 특히 공공기관, 금융사, 또는 민감한 데이터를 다루는 조직의 경우 이 백업 구조를 정례화하여 DevSecOps 체계에 통합하는 것이 바람직합니다.

4. 컨테이너 버전 관리 및 태깅 정책

컨테이너 이미지에 대한 버전 관리 및 태깅 정책은 단순한 버전 명명 이상의 의미를 갖습니다. 이는 소프트웨어의 배포 일관성, 안정성, 추적 가능성을 확보하는 핵심 전략이며, 특히 쿠버네티스 기반의 MSA 환경에서 재현 가능한 빌드 및 롤백 시나리오를 보장하는 중요한 요소입니다.

아래에서는 각 정책 항목에 대해 보다 깊이 있고 실무적인 관점에서 상세히 설명드리겠습니다.

1. Semantic Versioning 기반 태깅 `(vMAJOR.MINOR.PATCH)`

의미 명확한 변경점 구분

컨테이너 이미지의 태그를 SemVer(시맨틱 버저닝) 기준으로 관리하는 이유는 API 호환성과 변경의 성격을 명확히 전달하기 위함입니다.

MAJOR 버전은 호환되지 않는 API 변경이 포함된 경우
MINOR 버전은 하위 호환이 가능한 기능 추가
PATCH 버전은 버그 수정 수준의 변경

예시:

v1.3.0 # 신규 기능 추가

v1.3.1 # 패치 버전 (버그 수정)

v2.0.0 # Breaking Change 포함

이러한 구조는 운영 중인 시스템에서 안정성을 확보하며, 버전 간 영향 범위를 명확하게 커뮤니케이션할 수 있습니다.

2. 빌드 트래킹을 위한 추가 태깅`(v1.2.3-20250615-abcdef0)`

CI/CD 파이프라인과 연계된 태그

이미지의 실질적인 빌드 이력을 추적하기 위해 아래와 같은 방식의 복합 태깅을 도입합니다.

날짜 또는 CI 빌드번호: 20250615, build-3124
Git Commit Hash: abcdef0

예시:

v1.2.3-20250615-abcdef0

이 태그는 릴리즈된 이미지가 어떤 Git 커밋에서 비롯되었는지를 정확히 식별할 수 있게 하며, 추후 디버깅이나 롤백 시 필수적인 정보로 작용합니다.

3. `latest` 태그 금지 정책

비결정성(Non-determinism) 제거

많은 개발자가 습관적으로 사용하는 latest 태그는 빌드 및 배포 과정에서 아래와 같은 문제를 유발합니다.

같은 latest 태그라도 시점에 따라 이미지가 달라질 수 있음
CI/CD 자동화 배포 시 예기치 않은 버전 배포 가능성

이러한 리스크를 방지하기 위해 다음과 같은 방법으로 정책화합니다.

CI/CD 파이프라인 내에서 latest 사용을 금지
Gatekeeper나 Kyverno 등의 정책 엔진을 활용하여 쿠버네티스 레벨에서 latest 태그 사용 차단

4. 이미지 Digest 기반 고정 `(image@sha256:...)`

완전 불변(Immutable) 이미지 참조

시맨틱 버전이나 커밋 해시 기반의 태그도 이미지의 불변성을 보장하지는 못합니다. 운영 환경에서 완벽한 일관성을 확보하려면 Digest 고정 참조 방식이 필요합니다.

예시:

containers:

– name: app

image: registry.example.com/app@sha256:9c692f…

이 방식은 이미지가 태그만 바뀌거나 레지스트리에서 재빌드되더라도 해당 Digest가 변경되지 않는 이상 동일한 바이너리임을 보장합니다.

5. 태그 유지 정책 (Retention Policy)

스토리지 관리 및 품질 보존

모든 버전을 영구 저장하는 것은 스토리지 낭비 및 관리 복잡도를 초래합니다. 이에 따라 다음과 같은 유지 전략을 적용합니다.

주요 릴리즈(예: MAJOR 또는 stable, lts): 무기한 보존
마이너/패치 릴리즈: 최근 N개만 유지 (예: 최신 10개)
CI/CD 빌드 태그: 주기적 정리 스크립트 혹은 Harbor의 자동 정책 기능 활용

Harbor 기준 예시:

{
  "rule": {
    "repo": "project/app",
    "tag": "*",
    "retain_count": 10,
    "match_type": "regex"
  }
}

이 정책은 스토리지를 효율적으로 사용하고, 레지스트리의 탐색 및 관리 효율성을 높여줍니다.

종합정리

정책 항목	내용 요약	실무 적용 포인트
시맨틱 버저닝	의미 중심 버전 정의	Breaking Change 여부 구분
빌드 기반 태깅	커밋 해시 및 빌드번호 포함	릴리즈 추적 및 디버깅
latest 사용 금지	비결정성 제거	정책 엔진(Gatekeeper 등) 적용
Digest 고정 참조	환경별 이미지 불일치 방지	Kubernetes Manifest 내 적용

이와 같은 정책은 단순한 형식 규칙을 넘어서, 쿠버네티스 기반 배포의 신뢰성과 자동화 수준을 향상시키는 핵심 전략입니다.

특히 기업용 플랫폼에서는 이러한 정책을 표준화하고, 모든 팀에 공통으로 적용하도록 가이드와 문서화가 병행되어야 합니다.

5. 인증서 생성 및 설정 스크립트

프라이빗 레지스트리와 클러스터 간 통신은 TLS 기반 HTTPS로 설정해야 합니다.

인증서 자동 발급 및 갱신: cert-manager + ACME 기반으로 도메인 검증이 가능한 경우 Let’s Encrypt 또는 내부 CA 연동.
Self‑Signed 방식: 폐쇄망 환경에서는 OpenSSL 기반 Root CA 생성 및 중간 CA를 사용하며, 모든 쿠버네티스 노드 컨테이너 런타임(CRI: containerd/docker)에 CA bundle 배포 스크립트를 포함합니다.
스크립트 예시 (bash): generate-ca.sh, generate-server-cert.sh, 그리고 /etc/containerd/certs.d/registry.local:5000/ca.crt 등 복사 명령을 자동화해 재현성을 확보합니다.
쿠버네티스 Secret 및 imagePullSecret 구성: kubectl create secret tls registry-tls,kubectl create secret docker-registry regcred --from-file=.dockerconfigjson=~/.docker/config.json 같은 형태로 자동화 스크립트 포함
Ingress 및 서비스 설정: TLS 항목 포함된 Ingress 자원과 외부 접근이 필요한 경우 로드밸런서(ALB/NLB) 단계에서도 TLS 종료를 처리합니다.

마무리

쿠버네티스 환경에서 컨테이너 레지스트리 구축은 단순히 이미지 저장소를 설치하는 것을 넘어, 스토리지 안정성, 접근 보안, 버전/스캔 정책, TLS 보안, 권한 분리, 네트워크 최적화 등이 하나의 시스템으로 통합된 아키텍처적 구성입니다.

각 단계는 체계적인 산출물(설계서, 매뉴얼, 정책서, YAML 샘플, CI/CD 파이프라인 구성 문서, 운영 매트릭스 등)과 함께 제공되어야 전문가 관점에서 평가받을 수 있습니다.

이와 같은 구조로 문서를 작성하시면 MSA·클라우드 네이티브 전문가들이 내용을 보고 즉시 공감하고, 실제 프로젝트 진행 시 가이드와 기반 아키텍처로 활용하실 수 있습니다.