Kubernetes 환경에서 Nexus Docker Proxy로 외부 이미지 Pull 구성하기

보안 정책상 클러스터 노드가 인터넷에 직접 접근하지 못하는 환경에서, Nexus Repository Manager를 Docker Proxy로 구성하여 외부 이미지(Docker Hub, ECR Public)를 안전하게 Pull하는 방법을 정리합니다.

아키텍처 개요

[개발자 / EKS 노드]
        │
        ▼
[docker-group]  nexus-docker.example.com:443
        │
        ├── [docker-proxy-ecr-public] ──→ public.ecr.aws
        └── [docker-proxy-dockerhub]  ──→ registry-1.docker.io (Docker Hub)

• • 노드/개발자는 Nexus 단일 엔드포인트만 사용
• • Nexus가 upstream registry로 요청 전달 및 캐싱
• • 노드 직접 인터넷 접근 불가 환경에서도 외부 이미지 수신 가능

STEP 7. Nexus Docker Proxy 설정

Nexus UI에 접속하여 아래 순서로 Docker Proxy repository를 구성합니다.

7-1. Docker Bearer Token Realm 활성화

Administration → Security → Realms에서 Docker Bearer Token Realm을 Active로 이동한 후 Save합니다.

⚠️ 이 설정이 없으면 docker pull 시 인증 오류가 발생합니다.

7-2. docker-proxy-ecr-public 생성

Administration → Repository → Repositories → Create → docker (proxy)

항목	설정값
Name	docker-proxy-ecr-public
Allow anonymous docker pull	✅ 체크
Remote Storage	https://public.ecr.aws
Docker Index	Custom → https://public.ecr.aws

7-3. docker-proxy-dockerhub 생성

Administration → Repository → Repositories → Create → docker (proxy)

항목	설정값
Name	docker-proxy-dockerhub
Allow anonymous docker pull	✅ 체크
Remote Storage	https://registry-1.docker.io
Docker Index	Use Docker Hub

7-4. docker-group 생성

Administration → Repository → Repositories → Create → docker (group)

항목	설정값
Name	docker-group
HTTP Port	8082
Allow anonymous docker pull	✅ 체크
Member Repositories	docker-proxy-ecr-public, docker-proxy-dockerhub

💡 Member Repositories 순서가 탐색 우선순위가 됩니다. ECR Public을 먼저 두면 ECR 이미지를 우선 탐색합니다.

7-5. Anonymous Access 활성화

Administration → Security → Anonymous Access → Allow anonymous users to access the server 활성화

⚠️ 프로덕션 환경에서는 Anonymous Access를 비활성화하고 인증 기반 pull을 구성하는 것을 권장합니다.

STEP 8. Kubernetes Ingress 및 DNS 구성

Nexus Helm chart에서 Docker Registry용 Ingress를 별도로 추가합니다. 일반 Nexus UI와 Docker Registry는 포트가 달라 별도의 Ingress가 필요합니다.

8-1. Helm values 추가

# nexus-repository-manager Helm values
nexus:
  docker:
    enabled: true
    registries:
      - host: nexus-docker.example.com   # Docker Registry 전용 도메인
        port: 8082
        annotations:
          alb.ingress.kubernetes.io/healthcheck-path: /v2/
          alb.ingress.kubernetes.io/success-codes: "200,401"

위 설정을 적용하면 다음 리소스가 생성됩니다:

• • Service: NodePort 8082 (Docker group 포트)
• • Ingress: Docker Registry 전용 ALB 생성

8-2. Route 53 DNS 등록

Record	Type	Value
nexus-docker.example.com	CNAME	<생성된 ALB DNS>

와일드카드 ACM 인증서(*.example.com)가 있다면 HTTPS 443 포트로 자동 커버됩니다.

STEP 9. ALB Health Check 오류 해결

문제 상황

Ingress 생성 후 ALB Target Group의 모든 대상이 unhealthy 상태가 되는 현상이 발생합니다.

# ALB Target Group Health Check 결과
Target.ResponseCodeMismatch → unhealthy

원인 분석

Docker Registry의 /v2/ 엔드포인트는 항상 401 Unauthorized를 반환합니다.
ALB Health Check의 기본 경로(/)와 기대 응답 코드(200)가 맞지 않아 unhealthy 판정됩니다.

해결 방법

Ingress annotation에 healthcheck 경로와 허용 응답 코드를 명시합니다.

annotations:
  alb.ingress.kubernetes.io/healthcheck-path: /v2/
  alb.ingress.kubernetes.io/success-codes: "200,401"   # 401도 정상으로 허용

✅ 적용 후 모든 Target이 healthy로 전환됩니다.

동작 검증

설정 완료 후 아래 명령으로 각 upstream registry 경유 동작을 확인할 수 있습니다.

# ECR Public 이미지 — docker-proxy-ecr-public 경유
docker pull nexus-docker.example.com/amazonlinux/amazonlinux:latest

# Docker Hub 이미지 (nginx 등) — docker-proxy-dockerhub 경유
docker pull nexus-docker.example.com/library/nginx:latest

✅ 검증 결과

Nexus Docker Proxy를 통해 ECR Public 및 Docker Hub 이미지를 모두 정상적으로 Pull할 수 있음을 확인했습니다. 노드가 인터넷에 직접 접근하지 않아도 Nexus 단일 엔드포인트를 통해 외부 이미지를 수신할 수 있습니다.

프로덕션 적용 시 고려사항

• • 보안: Anonymous Access 비활성화 후 pull secret 기반 인증 구성 검토
• • ECR 권한: 클러스터 노드 IAM Role에 ECR pull 권한 사전 부여 필요
• • Rate Limit: Docker Hub rate limit 회피를 위해 Docker Hub 계정 인증 추가 권장
• • 스토리지: Nexus 캐시 용량 확보 필요 (EFS 또는 EBS 동적 프로비저닝)
• • HA: Nexus는 기본적으로 싱글 인스턴스 — 장애 시 이미지 Pull 전체 차단 가능성 고려