Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Harbor 레지스트리 인스턴스 만들기

Google Distributed Cloud(GDC) 에어 갭 관리형 Harbor 서비스(MHS)를 사용하여 각 프로젝트에 Harbor 레지스트리 인스턴스를 만듭니다. Harbor 레지스트리 인스턴스는 클라우드 네이티브 환경에서 컨테이너 이미지를 저장하고 관리하는 중앙 저장소 역할을 합니다. 오픈소스 Docker 배포의 기능을 확장합니다. 다음 제한사항이 적용됩니다.

프로젝트당 최대 1개의 인스턴스를 만들 수 있습니다.
인스턴스는 격리되어 있으며 데이터나 컴퓨팅 리소스를 공유하지 않습니다.

시작하기 전에

Harbor 레지스트리 인스턴스를 만드는 경우 IAM 프로젝트 관리자에게 연락하여 Harbor 인스턴스 관리자(harbor-instance-admin) 역할을 요청하세요. 이 역할을 사용하면 프로젝트 네임스페이스 내에서 Harbor 인스턴스, 백업 저장소, 백업 계획, 백업, 복원을 가져오고, 나열하고, 감시하고, 만들고, 업데이트하고, 패치하고, 삭제할 수 있습니다. 이 역할에는 새 Harbor 인스턴스를 프로비저닝하는 데 필요한 권한이 포함되어 있습니다.

Harbor 레지스트리 인스턴스 만들기

GDC 콘솔 또는 gdcloud CLI에서 Harbor 레지스트리 인스턴스를 만듭니다.

콘솔

GDC 콘솔에서 다음 단계를 따르세요.

탐색 메뉴의 CI/CD 섹션에서 Harbor Container Registry를 클릭합니다.
인스턴스 만들기를 클릭합니다.
인스턴스 이름 필드에 인스턴스의 이름을 입력합니다.
선택사항: 프로젝트 섹션에서 이 Harbor 인스턴스의 기본 프로젝트를 만들려면 이 인스턴스를 만들 때 기본 프로젝트 만들기 전환 버튼을 사용 설정 위치로 클릭한 후 다음을 수행합니다.
1. 프로젝트 이름 필드에 프로젝트 이름을 입력합니다.
Harbor 관리형 서비스 약관을 읽고 약관에 동의하면 체크박스를 선택합니다.
만들기를 클릭합니다. 상태는 진행 중으로 표시되고 이름에는 새로 만든 Harbor 인스턴스의 이름이 포함된 외부 링크가 표시됩니다.
인스턴스가 생성되고 상태에 준비가 표시되면 페이지의 외부 링크를 클릭하여 Harbor 인스턴스의 웹 UI를 방문합니다.

gdcloud

Harbor 레지스트리 인스턴스를 만듭니다.

gdcloud harbor instances create INSTANCE \
  --project=PROJECT

다음을 바꿉니다.

INSTANCE: 인스턴스 이름입니다.
PROJECT: 인스턴스를 만들 GDC 프로젝트의 이름

Harbor 레지스트리 인스턴스의 클러스터 노드 신뢰

Harbor 레지스트리 인스턴스가 준비되면 GDC는 조직의 신뢰할 수 있는 루트 인증 기관(CA)에서 발급한 인스턴스의 TLS 인증서를 신뢰하도록 조직의 공유 및 표준 Kubernetes 클러스터 노드를 자동으로 구성합니다. 인스턴스에서 이미지를 가져오려면 루트 CA를 설치하거나 클러스터 노드에서 컨테이너 런타임 구성을 변경할 필요가 없습니다.

자동 구성의 동작은 다음과 같습니다.

노드 업데이트 타이밍: GDC는 각 클러스터의 비공개 레지스트리 구성에 인스턴스를 추가한 후 클러스터의 모든 노드를 업데이트합니다. 노드는 해당 노드에서 업데이트가 완료된 후에만 인스턴스에서 이미지를 가져올 수 있으며, 모든 노드에서 최대 60분이 걸릴 수 있습니다.
새 클러스터 및 교차 영역 클러스터: GDC는 인스턴스가 준비된 후 만드는 클러스터와 조직의 다른 영역에 있는 클러스터도 구성합니다.
신뢰할 수 있는 호스트 이름: 노드는 인스턴스 호스트 이름만 신뢰합니다. 이는 https:// 프리픽스가 없는 인스턴스 URL입니다(예: harbor-1-my-project.org-1.zone1.google.gdc.test). 인스턴스 URL은 GDC 콘솔 인스턴스 링크 또는 gdcloud harbor instances describe 명령어 출력의 status.url 필드에서 찾을 수 있습니다. 이미지 참조에서 인스턴스 호스트 이름을 사용합니다(예: INSTANCE_HOSTNAME/HARBOR_PROJECT/IMAGE:TAG). 여기서 HARBOR_PROJECT는 이미지를 저장하는 Harbor 프로젝트입니다.
워크스테이션 Docker 클라이언트: 자동 신뢰는 클러스터 노드에만 적용됩니다. 워크스테이션에서 Docker로 이미지를 내보내거나 가져오려면 루트 CA를 신뢰하도록 로컬 Docker 클라이언트를 구성해야 합니다. 자세한 내용은 Harbor 루트 CA를 신뢰하도록 Docker 구성을 참조하세요.

클러스터 노드가 인스턴스를 신뢰하지 않는 경우 이미지를 가져올 때 인증서 오류 문제 해결을 참조하세요.

이미지를 가져올 때 인증서 오류 문제 해결

클러스터 노드가 이미지 참조의 호스트 이름에 대한 인증서를 신뢰하지 않으면 포드가 이미지를 가져올 수 없습니다. 포드에 ErrImagePull 또는 ImagePullBackOff 상태가 표시되고 포드 이벤트에 다음과 유사한 오류가 표시됩니다.

failed to pull and unpack image "INSTANCE_HOSTNAME/HARBOR_PROJECT/IMAGE:TAG": ... x509: certificate signed by unknown authority

인증서 오류를 해결하려면 다음이 필요합니다.

인스턴스가 포함된 GDC 프로젝트의 Harbor 인스턴스 뷰어(harbor-instance-viewer) 또는 Harbor 인스턴스 관리자(harbor-instance-admin) 역할
영향을 받는 클러스터에서 포드 이벤트를 보고 포드를 삭제할 수 있는 역할:
- 공유 클러스터의 경우 워크로드의 프로젝트 네임스페이스에 있는 네임스페이스 관리자(namespace-admin) 역할
- 표준 클러스터의 경우 클러스터가 포함된 프로젝트의 클러스터 개발자(cluster-developer) 역할
영향을 받는 Kubernetes 클러스터의 kubeconfig 파일:
- 공유 클러스터의 경우 로그인을 참조하세요.
- 표준 클러스터의 경우 표준 클러스터에 대한 액세스 관리를 참조하세요.

이 문제를 해결하려면 다음 단계를 완료하시기 바랍니다.

포드 이벤트와 포드를 실행하는 노드를 확인합니다.
```
kubectl --kubeconfig CLUSTER_KUBECONFIG \
  -n NAMESPACE describe pod POD_NAME
```
다음을 바꿉니다.
- CLUSTER_KUBECONFIG: 영향을 받는 Kubernetes 클러스터의 kubeconfig 파일 경로입니다.
- NAMESPACE: 포드의 네임스페이스입니다. 공유 클러스터의 경우 프로젝트 네임스페이스입니다.
- POD_NAME: 포드의 이름입니다.
출력에서 Node 필드는 포드를 실행하는 노드를 표시하고 Events 섹션은 오류 메시지와 이미지 참조를 표시합니다.
인스턴스가 준비되었고 오류 코드가 없는지 확인합니다.
- GDC 콘솔에서 인스턴스의 상태가 준비됨으로 표시되는지 확인합니다. 상태가 준비로 표시되더라도 gdcloud CLI를 사용하여 오류 코드를 확인합니다.
- gdcloud CLI를 사용하여 인스턴스 상태와 오류 코드를 확인합니다.
```
gdcloud harbor instances describe INSTANCE \
  --project=PROJECT
```
  다음을 바꿉니다.
  - INSTANCE: Harbor 레지스트리 인스턴스의 이름입니다.
  - PROJECT: 인스턴스가 포함된 GDC 프로젝트의 이름입니다.
  출력에서 status.conditions 목록에 type: Ready가 있는 조건에 status: "True"가 있는지 확인합니다. 출력은 다음과 비슷합니다.
```
# Several lines of code are omitted here.
status:
  conditions:
  - message: HarborInstance reconciled
    reason: Reconciled
    status: "True"
    type: Ready
  # Several lines of code are omitted here.
  url: https://harbor-1-my-project.org-1.zone1.google.gdc.test
```
상태가 진행 중으로 유지되거나 알 수 없음 또는 오류가 표시되거나 Ready 조건에 status: "True"가 없으면 인프라 운영자(IO)에게 문의하세요. gdcloud harbor instances describe 출력의 status 섹션에 HAAS0008와 같은 오류 코드가 있는 errorStatus 필드가 포함된 경우 Ready 조건이 True이더라도 IO에 문의하세요. 오류 코드와 메시지를 포함합니다.
워크로드의 이미지 참조가 https:// 프리픽스 없이 인스턴스 URL에 표시된 대로 인스턴스 호스트 이름을 정확하게 사용하는지 확인합니다. 노드는 IP 주소와 같은 인스턴스의 다른 이름을 신뢰하지 않습니다. 이미지 참조에서 다른 이름을 사용하는 경우 인스턴스 호스트 이름을 사용하도록 참조를 업데이트한 후 워크로드를 다시 배포합니다.
인스턴스가 준비 상태를 표시한 후 또는 클러스터를 만든 후(둘 중 더 늦은 시간) 60분이 지나지 않은 경우 GDC가 클러스터 노드 업데이트를 완료할 때까지 기다립니다.
- 부분 노드 업데이트: 일부 노드에서 이미지 가져오기가 성공하고 다른 노드에서 실패하면 업데이트가 계속 진행 중입니다.
- 백업 및 복원: 인스턴스의 백업 또는 복원이 진행되는 동안 노드 업데이트가 대기합니다. 백업 또는 복원이 완료된 후 60분 동안 시작합니다.
- 새 클러스터 또는 교차 영역 클러스터: 인스턴스가 준비된 후 만드는 클러스터와 인스턴스와 다른 영역에 있는 클러스터의 경우 인스턴스의 준비 상태는 클러스터 노드가 업데이트되었는지 여부를 표시하지 않습니다.
노드 업데이트가 완료되면 워크로드가 이미지를 가져올 수 있는지 확인합니다. Kubernetes는 실패한 이미지 가져오기를 자동으로 다시 시도합니다. 즉시 다시 시도하려면 실패한 포드를 삭제하여 Deployment와 같은 컨트롤러가 포드를 다시 만들도록 합니다.
```
kubectl --kubeconfig CLUSTER_KUBECONFIG \
  -n NAMESPACE delete pod POD_NAME
```
포드를 관리하는 컨트롤러가 없으면 포드를 다시 만듭니다. 문제가 해결되었는지 확인하려면 새 포드에 ErrImagePull 또는 ImagePullBackOff 대신 Running 상태가 표시되는지 확인합니다.
```
kubectl --kubeconfig CLUSTER_KUBECONFIG \
  -n NAMESPACE get pods
```
인스턴스가 준비 상태를 표시한 후 또는 클러스터를 만든 후(둘 중 더 늦은 시점) 60분 넘게 오류가 계속되면 IO에 문의하세요. 다음 정보를 제공합니다.
- 인스턴스 및 영향을 받는 클러스터의 조직 및 영역
- 인스턴스 이름 및 인스턴스가 포함된 GDC 프로젝트
- 영향을 받는 Kubernetes 클러스터의 이름, 공유 클러스터인지 표준 클러스터인지 여부, 표준 클러스터의 경우 클러스터가 포함된 프로젝트
- 포드 이벤트의 전체 이미지 참조 및 전체 오류 메시지
- 이미지 가져오기가 실패한 노드의 이름과 다른 노드에서 이미지 가져오기가 성공했는지 여부
- 인스턴스가 준비 상태를 표시한 시점, 클러스터를 만든 시점, 인스턴스의 백업 또는 복원이 진행 중인지 여부
- errorStatus 오류 코드를 포함한 gdcloud harbor instances describe 출력의 status 섹션

다음 단계

Harbor 레지스트리 인스턴스가 준비되면 프로젝트를 만들어 이미지 컬렉션을 호스팅하거나 기존 인스턴스를 관리할 수 있습니다.

달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.

최종 업데이트: 2026-11-03(UTC)