Harbor-Registry-Instanzen erstellen

Verwenden Sie den Managed Harbor Service (MHS) von Google Distributed Cloud (GDC) mit Air Gap, um in jedem Projekt eine Harbor-Registry-Instanz zu erstellen. Eine Harbor-Registry-Instanz dient als zentrales Repository zum Speichern und Verwalten von Container-Images in einer cloudnativen Umgebung. Sie erweitert die Funktionen der Open-Source-Docker-Distribution. Folgende Einschränkungen gelten:

• Sie können maximal eine Instanz pro Projekt erstellen.
• Instanzen sind isoliert und teilen keine Daten oder Rechenressourcen.

Hinweis

Wenn Sie für das Erstellen von Harbor-Registry-Instanzen verantwortlich sind, wenden Sie sich an Ihren IAM-Projektadministrator, um die Rolle Harbor Instance Admin (harbor-instance-admin) anzufordern. Mit dieser Rolle können Sie Harbor-Instanzen, Backup-Repositories, Sicherungspläne, Sicherungen und Wiederherstellungen in einem Projekt-Namespace abrufen, auflisten, beobachten, erstellen, aktualisieren, patchen und löschen. Diese Rolle enthält die erforderlichen Berechtigungen zum Bereitstellen neuer Harbor-Instanzen.

Harbor-Registry-Instanz erstellen

Erstellen Sie eine Harbor-Registry-Instanz in der GDC-Konsole oder der gdcloud CLI.

Console

Führen Sie in der GDC-Konsole die folgenden Schritte aus:

1. Klicken Sie im Navigationsmenü im Abschnitt CI/CD auf Harbor Container Registry.
2. Klicken Sie auf Instanz erstellen.
3. Geben Sie im Feld Instanzname einen Namen für die Instanz ein.
4. Optional: Wenn Sie im Abschnitt Projekte ein Standardprojekt für diese Harbor-Instanz erstellen möchten, aktivieren Sie die Option Beim Erstellen dieser Instanz ein Standardprojekt erstellen und gehen Sie dann so vor:
   1. Geben Sie im Feld Projektname einen Projektnamen ein.
5. Lesen Sie die Nutzungsbedingungen für verwaltete Harbor-Instanzen und klicken Sie das Kästchen an, wenn Sie die Bedingungen akzeptieren.
6. Klicken Sie auf Erstellen. Der Status lautet In Bearbeitung und der Name enthält einen externen Link mit dem Namen Ihrer neu erstellten Harbor-Instanz.
7. Nachdem die Instanz erstellt wurde und der Status Bereit lautet, klicken Sie auf den externen Link auf der Seite, um die Web-UI der Harbor-Instanz aufzurufen.

gdcloud

Erstellen Sie die Harbor-Registry-Instanz:

gdcloud harbor instances create INSTANCE \
  --project=PROJECT

Ersetzen Sie Folgendes:

• INSTANCE den Namen der Instanz
• PROJECT: der Name des GDC-Projekts, in dem die Instanz erstellt werden soll

Clusternotenknoten-Trust für Harbor-Registry-Instanzen

Wenn eine Harbor-Registry-Instanz bereit ist, konfiguriert GDC automatisch die Knoten von freigegebenen und Standard-Kubernetes-Clustern in Ihrer Organisation so, dass sie dem TLS-Zertifikat der Instanz vertrauen, das von der vertrauenswürdigen Root-Zertifizierungsstelle (CA) Ihrer Organisation ausgestellt wird. Wenn Sie Images aus der Instanz abrufen möchten, müssen Sie die Stamm-CA nicht installieren oder die Containerlaufzeitkonfiguration auf Clusterknoten ändern.

Die automatische Konfiguration hat das folgende Verhalten:

• Zeitpunkt der Knotenaktualisierung: GDC fügt die Instanz der Konfiguration der privaten Registry jedes Clusters hinzu und aktualisiert dann jeden Knoten im Cluster. Ein Knoten kann erst dann Images aus der Instanz abrufen, wenn die Aktualisierung auf diesem Knoten abgeschlossen ist. Dies kann auf allen Knoten bis zu 60 Minuten dauern.
• Neue und zonenübergreifende Cluster: GDC konfiguriert auch Cluster, die Sie erstellen, nachdem die Instanz bereit ist, und Cluster in anderen Zonen Ihrer Organisation.
• Vertrauenswürdiger Hostname: Knoten vertrauen nur dem Instanzhostnamen, d. h. der Instanz-URL ohne das Präfix https://, z. B. harbor-1-my-project.org-1.zone1.google.gdc.test. Sie finden die Instanz-URL im Instanzlink der GDC-Konsole oder im Feld status.url der Ausgabe des Befehls gdcloud harbor instances describe. Verwenden Sie den Instanzhostnamen in Ihren Image-Referenzen, z. B. INSTANCE_HOSTNAME/HARBOR_PROJECT/IMAGE:TAG, wobei HARBOR_PROJECT das Harbor-Projekt ist, in dem das Image gespeichert ist.
• Workstation-Docker-Client: Die automatische Vertrauensstellung gilt nur für Clusterknoten. Wenn Sie Images mit Docker von Ihrer Workstation übertragen oder abrufen möchten, müssen Sie Ihren lokalen Docker-Client so konfigurieren, dass er der Stamm-CA vertraut. Weitere Informationen finden Sie unter Docker so konfigurieren, dass der Harbor-Root-CA vertraut wird.

Wenn Clusterknoten Ihrer Instanz nicht vertrauen, lesen Sie den Abschnitt Zertifikatsfehler beim Abrufen von Images beheben.

Zertifikatsfehler beim Abrufen von Images beheben

Wenn die Clusterknoten dem Zertifikat für den Hostnamen in einer Image-Referenz nicht vertrauen, können Pods das Image nicht abrufen. Die Pods haben den Status ErrImagePull oder ImagePullBackOff und die Pod-Ereignisse zeigen einen Fehler ähnlich dem folgenden an:

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

Achtung: GDC verwaltet die Vertrauensstellung von Clusterknoten automatisch. Verwenden Sie keine manuellen Problemumgehungen, um x509-Fehler zu umgehen, da nicht unterstützte Änderungen die TLS-Prüfung schwächen und durch Knotenupdates überschrieben werden. Wenn ein Pod beispielsweise ein Image nicht abrufen kann, sollten Sie nicht die Containerlaufzeit des Knotens ändern, CA-Zertifikate mit DaemonSet-Arbeitslasten oder privilegierten Pods installieren, eine unsichere Registry konfigurieren oder Images über eine IP-Adresse oder über HTTP abrufen.

Zur Behebung von Zertifikatsfehlern benötigen Sie Folgendes:

• Die Rolle Harbor Instance Viewer (harbor-instance-viewer) oder Harbor Instance Admin (harbor-instance-admin) im GDC-Projekt, das die Instanz enthält.
• Eine Rolle, mit der Sie Pod-Ereignisse aufrufen und Pods im betroffenen Cluster löschen können:
  • Für einen freigegebenen Cluster die Rolle Namespace-Administrator (namespace-admin) im Projekt-Namespace der Arbeitslast.
  • Für einen Standardcluster die Rolle Cluster Developer (cluster-developer) in dem Projekt, das den Cluster enthält.
• Eine kubeconfig-Datei für den betroffenen Kubernetes-Cluster:
  • Informationen zu einem freigegebenen Cluster finden Sie unter Anmelden.
  • Informationen zu Standardclustern finden Sie unter Zugriff auf Standardcluster verwalten.

So beheben Sie das Problem:

1. Sehen Sie sich die Pod-Ereignisse und den Knoten an, auf dem der Pod ausgeführt wird:

   kubectl --kubeconfig CLUSTER_KUBECONFIG \
     -n NAMESPACE describe pod POD_NAME
   

   Ersetzen Sie Folgendes:

   • CLUSTER_KUBECONFIG: der Pfad zur kubeconfig-Datei des betroffenen Kubernetes-Clusters.
   • NAMESPACE: der Namespace des Pods. Bei einem freigegebenen Cluster ist dies ein Projekt-Namespace.
   • POD_NAME: der Name des Pods.

   In der Ausgabe wird im Feld Node der Knoten angezeigt, auf dem der Pod ausgeführt wird. Im Abschnitt Events werden die Fehlermeldung und die Image-Referenz angezeigt.

2. Prüfen Sie, ob die Instanz bereit ist und keine Fehlercodes enthält:

   • Prüfen Sie in der GDC-Konsole, ob der Status der Instanz Bereit lautet. Auch wenn der Status Bereit lautet, sollten Sie die gdcloud CLI verwenden, um nach Fehlercodes zu suchen.

   • Prüfen Sie mit der gdcloud CLI den Instanzstatus und alle Fehlercodes:

     gdcloud harbor instances describe INSTANCE \
       --project=PROJECT
     

     Ersetzen Sie Folgendes:

     • INSTANCE: der Name der Harbor-Registry-Instanz.
     • PROJECT: der Name des GDC-Projekts, das die Instanz enthält.

     Prüfen Sie in der Ausgabe, ob die Bedingung mit type: Ready in der Liste status.conditions den Wert status: "True" hat. Die Ausgabe sieht in etwa so aus:

     # 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
     

   Wenn der Status weiterhin In Bearbeitung ist oder Unbekannt oder Fehler angezeigt wird oder die Bedingung Ready nicht status: "True" hat, wenden Sie sich an Ihren Infrastrukturbetreiber (IO). Wenn der Abschnitt status der Ausgabe von gdcloud harbor instances describe ein Feld errorStatus mit Fehlercodes wie HAAS0008 enthält, wenden Sie sich an Ihren IO, auch wenn die Bedingung Ready den Wert True hat. Geben Sie die Fehlercodes und ‑meldungen an.

3. Prüfen Sie, ob die Image-Referenz in Ihrer Arbeitslast den Hostnamen der Instanz genau so verwendet, wie er in der Instanz-URL angezeigt wird, ohne das Präfix https://. Knoten vertrauen anderen Namen für die Instanz, z. B. einer IP-Adresse, nicht. Wenn die Image-Referenz einen anderen Namen verwendet, aktualisieren Sie die Referenz, um den Hostnamen der Instanz zu verwenden, und stellen Sie die Arbeitslast dann noch einmal bereit.

4. Wenn seit dem Zeitpunkt, an dem die Instanz den Status Bereit angezeigt hat, oder seit dem Erstellen des Clusters (je nachdem, was später war) weniger als 60 Minuten vergangen sind, warten Sie, bis GDC die Aktualisierung der Clusterknoten abgeschlossen hat:

   • Teilweise Knotenaktualisierungen: Wenn Image-Abrufe auf einigen Knoten erfolgreich sind und auf anderen fehlschlagen, wird die Aktualisierung noch ausgeführt.
   • Sicherungen und Wiederherstellungen: Knotenaktualisierungen werden angehalten, während eine Sicherung oder Wiederherstellung der Instanz ausgeführt wird. Der 60-minütige Zeitraum beginnt, nachdem die Sicherung oder Wiederherstellung abgeschlossen ist.
   • Neue oder zonenübergreifende Cluster: Bei Clustern, die Sie nach der Bereitstellung der Instanz erstellen, und bei Clustern in einer anderen Zone als die Instanz wird im Status Bereit der Instanz nicht angezeigt, ob die Clusterknoten aktualisiert wurden.

5. Prüfen Sie nach Abschluss des Knotenupdates, ob Ihre Arbeitslast das Image abrufen kann. Kubernetes wiederholt fehlgeschlagene Image-Abrufe automatisch. Wenn Sie den Vorgang sofort wiederholen möchten, löschen Sie den fehlerhaften Pod, damit er von seinem Controller, z. B. einem Deployment, neu erstellt wird:

   kubectl --kubeconfig CLUSTER_KUBECONFIG \
     -n NAMESPACE delete pod POD_NAME
   

   Wenn der Pod von keinem Controller verwaltet wird, erstellen Sie ihn neu. Prüfen Sie, ob das Problem behoben ist. Der neue Pod sollte den Status Running anstelle von ErrImagePull oder ImagePullBackOff haben:

   kubectl --kubeconfig CLUSTER_KUBECONFIG \
     -n NAMESPACE get pods
   

6. Wenn der Fehler länger als 60 Minuten nach dem Status Bereit der Instanz oder nach dem Erstellen des Clusters auftritt, wenden Sie sich an Ihren IO. Geben Sie die folgenden Informationen an:

   • Die Organisation und die Zone der Instanz und des betroffenen Clusters
   • Der Instanzname und das GDC-Projekt, das die Instanz enthält
   • Der Name des betroffenen Kubernetes-Clusters, ob es sich um einen freigegebenen oder einen Standardcluster handelt, und bei einem Standardcluster das Projekt, das den Cluster enthält
   • Die vollständige Bildreferenz und die vollständige Fehlermeldung aus den Pod-Ereignissen
   • Die Namen der Knoten, auf denen das Abrufen von Images fehlschlägt, und ob das Abrufen von Images auf anderen Knoten erfolgreich ist
   • Wann die Instanz den Status Bereit hatte, wann Sie den Cluster erstellt haben und ob eine Sicherung oder Wiederherstellung der Instanz im Gange war
   • Der Abschnitt status der Ausgabe von gdcloud harbor instances describe, einschließlich aller errorStatus-Fehlercodes

Nächste Schritte

Sobald Ihre Harbor-Registry-Instanz bereit ist, können Sie Projekte zum Hosten Ihrer Image-Sammlungen erstellen oder Ihre vorhandenen Instanzen verwalten:

• Harbor-Projekte erstellen
• Harbor-Registry-Instanzen verwalten