Harbor 2.15와 EKS Hybrid Nodes 통합 가이드

📅2025-08-20 작성·🔄2026-08-25 수정·⏱8분 읽기

개요

이 가이드는 Harbor 2.15와 EKS Hybrid Nodes (Kubernetes 1.33)를 통합하는 단계별 구성 방법을 제공합니다. 2024년 12월 정식 출시된 EKS Hybrid Nodes는 온프레미스 인프라와 AWS EKS를 통합 관리할 수 있게 해주며, Harbor 2.15는 향상된 보안 기능과 AI 모델 관리 기능을 제공합니다.

Part 1: Harbor Private Repository 설치 및 구성

Step 1: Harbor 2.15 설치 준비

시스템 요구사항 확인

• Docker Engine 20.10.10+
• Docker Compose 2.0+
• 최소 하드웨어: 2 CPU cores, 4GB RAM
• 지원 OS: Ubuntu 22.04/24.04, RHEL 8/9

Harbor 2.15.x 다운로드

# Harbor 2.15.x 다운로드 (현재 안정 버전)
wget https://github.com/goharbor/harbor/releases/download/v2.15.1/harbor-offline-installer-v2.15.1.tgz

# 압축 해제
tar xvf harbor-offline-installer-v2.15.1.tgz
cd harbor

Step 2: SSL/TLS 인증서 구성

자체 서명 인증서 생성

# 1. CA 인증서 생성
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -sha512 -days 3650 \
  -key ca.key \
  -out ca.crt \
  -subj "/C=US/ST=Washington/L=Seattle/O=MyOrganization/CN=Harbor-CA"

# 2. 서버 인증서 생성
openssl genrsa -out harbor.key 4096
openssl req -new -sha512 \
  -key harbor.key \
  -out harbor.csr \
  -subj "/C=US/ST=Washington/L=Seattle/O=MyOrganization/CN=harbor.yourdomain.com"

# 3. v3.ext 파일 생성 (SAN 설정)
cat > v3.ext <<EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1=harbor.yourdomain.com
DNS.2=yourdomain.com
IP.1=192.168.1.100
EOF

# 4. 인증서 서명
openssl x509 -req -sha512 -days 3650 \
  -extfile v3.ext \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -in harbor.csr \
  -out harbor.crt

# 5. 인증서 디렉토리 생성 및 복사
mkdir -p /data/cert
cp harbor.crt /data/cert/
cp harbor.key /data/cert/

Step 3: Harbor 구성 파일 설정

harbor.yml 수정

# harbor.yml 파일 복사 및 편집
cp harbor.yml.tmpl harbor.yml
vi harbor.yml

주요 설정 내용:

# 호스트명 설정
hostname: harbor.yourdomain.com

# HTTPS 구성
https:
  port: 443
  certificate: /data/cert/harbor.crt
  private_key: /data/cert/harbor.key

# Harbor 관리자 비밀번호 (배포 후 즉시 변경 필요)
harbor_admin_password: CHANGE_ME_AFTER_INSTALL

# 데이터베이스 설정 (강력한 비밀번호로 변경 + 정기 로테이션)
database:
  password: CHANGE_DB_PASSWORD
  max_idle_conns: 100
  max_open_conns: 900
  conn_max_lifetime: 5m
  conn_max_idle_time: 0

# 데이터 저장 경로
data_volume: /data

# 로그 설정
log:
  level: info
  local:
    rotate_count: 50
    rotate_size: 200M
    location: /var/log/harbor

# Trivy 취약점 스캐너 설정
trivy:
  ignore_unfixed: false
  skip_update: false
  offline_scan: false
  insecure: false

# 메트릭 설정
metric:
  enabled: true
  port: 9090
  path: /metrics

Step 4: Harbor 설치 실행

# 설치 준비 스크립트 실행
sudo ./prepare

# Harbor 설치 (Trivy 포함)
sudo ./install.sh --with-trivy

# 설치 확인
docker-compose ps

Step 5: Harbor 사용자 인증 구성

LDAP 인증 설정 (선택사항)

# API를 통한 LDAP 구성
curl -X PUT "https://harbor.yourdomain.com/api/v2.0/configurations" \
  -H "Content-Type: application/json" \
  -u "admin:YOUR_ADMIN_PASSWORD" \
  -d '{
    "auth_mode": "ldap_auth",
    "ldap_url": "ldap://ldap.company.com:389",
    "ldap_base_dn": "ou=users,dc=company,dc=com",
    "ldap_filter": "(objectClass=person)",
    "ldap_uid": "uid",
    "ldap_scope": 2,
    "ldap_search_dn": "cn=admin,dc=company,dc=com",
    "ldap_search_password": "admin_password",
    "ldap_verify_cert": false
  }'

Robot Account 생성 (Kubernetes 연동용)

# Harbor UI에서 생성하거나 API 사용
curl -X POST "https://harbor.yourdomain.com/api/v2.0/robots" \
  -H "Content-Type: application/json" \
  -u "admin:YOUR_ADMIN_PASSWORD" \
  -d '{
    "name": "k8s-robot",
    "duration": 365,
    "description": "Robot account for Kubernetes",
    "disable": false,
    "level": "system",
    "permissions": [
      {
        "namespace": "*",
        "kind": "project",
        "access": [
          {
            "resource": "repository",
            "action": "pull"
          }
        ]
      }
    ]
  }'

Part 2: EKS Hybrid Nodes 구성

Step 6: nodeadm 설치 및 준비

nodeadm 바이너리를 다운로드하고 Kubernetes 1.33 지원 컴포넌트를 설치합니다. 자격 증명 공급자는 SSM(Systems Manager) 또는 IAM Roles Anywhere를 선택할 수 있습니다. nodeadm 설치 절차와 자격 증명 공급자 선택 기준은 EKS Hybrid Nodes 개념과 동작 원리와 노드 인증 방식을 참조합니다.

Step 7: NodeConfig 파일 생성

Harbor 통합을 위한 NodeConfig 작성

# nodeconfig.yaml
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name: my-hybrid-cluster
    region: us-west-2

  # SSM을 사용한 하이브리드 노드 구성
  hybrid:
    ssm:
      activationCode: "YOUR-ACTIVATION-CODE"
      activationId: "YOUR-ACTIVATION-ID"

  # Containerd 구성 (Harbor 레지스트리 설정)
  containerd:
    config: |
      version = 2

      [plugins."io.containerd.grpc.v1.cri"]
        [plugins."io.containerd.grpc.v1.cri".registry]
          config_path = "/etc/containerd/certs.d:/etc/docker/certs.d"

        [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
          [plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.yourdomain.com"]
            endpoint = ["https://harbor.yourdomain.com"]

        [plugins."io.containerd.grpc.v1.cri".registry.configs]
          [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.yourdomain.com"]
            [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.yourdomain.com".auth]
              username = "robot$k8s-robot"
              password = "YOUR-ROBOT-TOKEN"

            [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.yourdomain.com".tls]
              ca_file = "/etc/ssl/certs/harbor-ca.crt"
              insecure_skip_verify = false

  # Kubelet 설정
  kubelet:
    config:
      shutdownGracePeriod: 30s
      maxPods: 110
    flags:
      - --node-labels=node-type=hybrid,registry=harbor

Step 8: 인증서 설치

Harbor CA 인증서를 노드에 설치

# CA 인증서를 시스템 신뢰 저장소에 추가
sudo cp ca.crt /usr/local/share/ca-certificates/harbor-ca.crt
sudo update-ca-certificates

# Containerd용 인증서 디렉토리 생성
sudo mkdir -p /etc/containerd/certs.d/harbor.yourdomain.com

# 인증서 복사
sudo cp ca.crt /etc/containerd/certs.d/harbor.yourdomain.com/ca.crt

# Containerd 재시작
sudo systemctl restart containerd

Step 9: 노드 초기화

# NodeConfig를 사용하여 노드 초기화
sudo nodeadm init --config-source file://nodeconfig.yaml

# 노드 상태 확인
kubectl get nodes

Part 3: Harbor와 EKS 통합

Step 10: 네트워크 구성

보안 그룹 설정

# Harbor 보안 그룹에 EKS 노드 액세스 허용
aws ec2 authorize-security-group-ingress \
  --group-id sg-harbor-xxxxx \
  --protocol tcp \
  --port 443 \
  --source-group sg-eks-nodes-xxxxx \
  --region us-west-2

DNS 구성

# CoreDNS ConfigMap 수정
kubectl edit configmap coredns -n kube-system

# 다음 내용 추가
data:
  Corefile: |
    .:53 {
        errors
        health
        kubernetes cluster.local in-addr.arpa ip6.arpa {
          pods insecure
          fallthrough in-addr.arpa ip6.arpa
        }
        # Harbor DNS 추가
        hosts {
          192.168.1.100 harbor.yourdomain.com
          fallthrough
        }
        prometheus :9153
        forward . /etc/resolv.conf
        cache 30
        loop
        reload
        loadbalance
    }

Step 11: Kubernetes Secret 생성

Harbor 인증 정보 Secret 생성

# Docker 로그인 테스트
docker login harbor.yourdomain.com
Username: robot$k8s-robot
Password: YOUR-ROBOT-TOKEN

# Kubernetes Secret 생성
kubectl create secret docker-registry harbor-registry \
  --docker-server=harbor.yourdomain.com \
  --docker-username='robot$k8s-robot' \
  --docker-password='YOUR-ROBOT-TOKEN' \
  --docker-email=admin@yourdomain.com

# 모든 네임스페이스에 Secret 복사 (선택사항)
for ns in $(kubectl get ns -o jsonpath='{.items[*].metadata.name}'); do
  kubectl get secret harbor-registry -o yaml | \
    sed "s/namespace: default/namespace: $ns/" | \
    kubectl apply -f -
done

ServiceAccount에 ImagePullSecret 추가

# 기본 ServiceAccount 수정
kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "harbor-registry"}]}'

# 또는 YAML로 정의
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-sa
  namespace: default
imagePullSecrets:
- name: harbor-registry
EOF

Step 12: 테스트 및 검증

연결 테스트

# 1. 네트워크 연결 확인
curl -k https://harbor.yourdomain.com/api/v2.0/health

# 2. 노드에서 직접 이미지 풀 테스트
sudo crictl pull harbor.yourdomain.com/library/nginx:latest

# 3. Kubernetes Pod 배포 테스트
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: harbor-test
spec:
  containers:
  - name: nginx
    image: harbor.yourdomain.com/library/nginx:latest
  imagePullSecrets:
  - name: harbor-registry
EOF

# 4. Pod 상태 확인
kubectl get pod harbor-test
kubectl describe pod harbor-test

Step 13: 문제 해결

일반적인 문제와 해결 방법

1. ImagePullBackOff 오류

# 문제 진단
kubectl describe pod <pod-name>
kubectl get events --field-selector involvedObject.name=<pod-name>

# Secret 확인
kubectl get secret harbor-registry -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d

# 해결 방법
# - Secret 재생성
# - 이미지 이름 및 태그 확인
# - Harbor 프로젝트 접근 권한 확인

2. 인증서 오류 (x509: certificate signed by unknown authority)

# 모든 노드에 CA 인증서 설치
cat <<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: harbor-ca-installer
  namespace: kube-system
spec:
  selector:
    matchLabels:
      name: harbor-ca-installer
  template:
    metadata:
      labels:
        name: harbor-ca-installer
    spec:
      hostNetwork: true
      hostPID: true
      containers:
      - name: installer
        image: busybox
        command: ['sh', '-c']
        args:
        - |
          echo "Installing Harbor CA certificate..."
          cp /ca-cert/ca.crt /host/usr/local/share/ca-certificates/harbor-ca.crt
          chroot /host update-ca-certificates
          chroot /host systemctl restart containerd
          sleep 3600
        volumeMounts:
        - name: ca-cert
          mountPath: /ca-cert
        - name: host
          mountPath: /host
        securityContext:
          privileged: true
      volumes:
      - name: ca-cert
        configMap:
          name: harbor-ca
      - name: host
        hostPath:
          path: /
EOF

3. DNS 해결 실패

# DNS 테스트
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup harbor.yourdomain.com

# CoreDNS 로그 확인
kubectl logs -n kube-system -l k8s-app=kube-dns

# 해결 방법: CoreDNS 재시작
kubectl rollout restart deployment coredns -n kube-system

Part 4: 운영 및 유지보수

Step 14: 보안 강화

Harbor 보안 정책 설정

# 취약점 스캔 자동화 활성화
curl -X PUT "https://harbor.yourdomain.com/api/v2.0/projects/1" \
  -H "Content-Type: application/json" \
  -u "admin:YOUR_ADMIN_PASSWORD" \
  -d '{
    "metadata": {
      "auto_scan": "true",
      "prevent_vul": "true",
      "severity": "high"
    }
  }'

# 이미지 서명 정책 구성 (Notary)
export DOCKER_CONTENT_TRUST=1
export DOCKER_CONTENT_TRUST_SERVER=https://harbor.yourdomain.com:4443

Step 15: 백업 및 복구

Harbor 백업 스크립트

#!/bin/bash
# harbor-backup.sh

BACKUP_DIR="/backup/harbor-$(date +%Y%m%d-%H%M%S)"
mkdir -p $BACKUP_DIR

# 1. Harbor 구성 백업
cp -r /data/harbor $BACKUP_DIR/

# 2. 데이터베이스 백업
docker exec harbor-db pg_dump -U postgres registry > $BACKUP_DIR/registry.sql

# 3. 레지스트리 데이터 백업 (선택사항 - 크기가 클 수 있음)
tar -czf $BACKUP_DIR/registry-data.tar.gz /data/registry

echo "Backup completed: $BACKUP_DIR"

Step 16: 모니터링

Prometheus 메트릭 수집

# prometheus-scrape-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: prometheus-config
data:
  prometheus.yml: |
    global:
      scrape_interval: 15s
    scrape_configs:
    - job_name: 'harbor'
      static_configs:
      - targets: ['harbor.yourdomain.com:9090']
      metrics_path: '/metrics'

주요 모니터링 지표

• Registry 요청 비율
• 인증 실패 횟수
• 스토리지 사용량
• 데이터베이스 연결 수
• API 응답 시간

결론

이 가이드는 Harbor 2.15와 EKS Hybrid Nodes (Kubernetes 1.33)의 통합 구성을 단계별로 설명했습니다. 주요 성공 요인은:

1. 적절한 인증서 관리: 자체 서명 인증서 사용 시 모든 노드에 CA 인증서 설치
2. 네트워크 구성: Harbor와 EKS 노드 간 안전한 통신 경로 확보
3. 인증 설정: Robot Account를 통한 자동화된 인증 구성
4. 지속적인 검증: 각 단계별 테스트를 통한 구성 검증

Harbor 2.15의 향상된 기능과 EKS Hybrid Nodes의 유연성을 활용하면, 온프레미스와 클라우드를 아우르는 통합 컨테이너 관리 환경을 구축할 수 있습니다.

참고 자료

공식 문서

• Harbor Documentation — Harbor 프라이빗 레지스트리 공식 문서
• Harbor GitHub Repository — Harbor 오픈소스 프로젝트 저장소
• Amazon EKS Hybrid Nodes — EKS Hybrid Nodes 공식 사용자 가이드
• Trivy Vulnerability Scanner — Harbor 통합 취약점 스캐너

관련 문서 (내부)

• EKS Hybrid Nodes 개념과 동작 원리 — Hybrid Nodes 아키텍처 및 nodeadm 구성 요소
• 노드 인증 방식 — SSM 및 IAM Roles Anywhere 자격 증명 공급자 선택 기준
• 방화벽과 네트워크 연결성 — FQDN 제한 환경에서 프라이빗 레지스트리 사전 등록 전략
• 파일 스토리지 — EKS Hybrid Nodes 스토리지 옵션