Dieses Dokument wurde mithilfe automatisierter maschineller Übersetzungstechnologie übersetzt. Wir bemühen uns um korrekte Übersetzungen, übernehmen jedoch keine Gewähr für die Vollständigkeit, Richtigkeit oder Zuverlässigkeit der übersetzten Inhalte. Im Falle von Abweichungen ist die englische Originalversion maßgebend und stellt den verbindlichen Text dar.

Private Registry-Konfiguration

Containerd kann so konfiguriert werden, dass es sich mit privaten Registries verbindet und diese verwendet, um Bilder nach Bedarf vom Kubelet abzurufen.

Beim Start überprüft K3s, ob /etc/rancher/k3s/registries.yaml existiert. Falls ja, wird die in dieser Datei enthaltene Registry-Konfiguration verwendet, wenn die Containerd-Konfiguration generiert wird.

  • Wenn Sie eine private Registry als Spiegel für eine öffentliche Registry wie docker.io verwenden möchten, müssen Sie registries.yaml auf jedem Knoten konfigurieren, der den Spiegel verwenden soll.

  • Wenn Ihre private Registry eine Authentifizierung erfordert, benutzerdefinierte TLS-Zertifikate verwendet oder kein TLS verwendet, müssen Sie registries.yaml auf jedem Knoten konfigurieren, der Bilder von Ihrer Registry abrufen wird.

Beachten Sie, dass Serverknoten standardmäßig planbar sind. Wenn Sie die Serverknoten nicht getaintet haben und Workloads auf ihnen ausführen werden, stellen Sie bitte sicher, dass Sie auch die registries.yaml-Datei auf jedem Server erstellen.

Standard-Endpunkt-Fallback

Containerd hat einen impliziten "Standard-Endpunkt" für alle Registries. Der Standard-Endpunkt wird immer als letzte Möglichkeit versucht, selbst wenn andere Endpunkte für diese Registry in registries.yaml aufgeführt sind. Umschreibungen werden nicht auf Abrufe gegen den Standard-Endpunkt angewendet. Zum Beispiel, wenn registry.example.com:5000/rancher/mirrored-pause:3.6 abgerufen wird, verwendet Containerd einen Standard-Endpunkt von https://registry.example.com:5000/v2.

  • Der Standard-Endpunkt für docker.io ist https://index.docker.io/v2.

  • Der Standard-Endpunkt für alle anderen Registries ist https://<REGISTRY>/v2, wobei <REGISTRY> der Hostname der Registry und der optionale Port ist.

Um als Registry erkannt zu werden, muss die erste Komponente des Bildnamens mindestens einen Punkt oder Doppelpunkt enthalten. Aus historischen Gründen werden Bilder, bei denen keine Registry in ihrem Namen angegeben ist, implizit als von docker.io stammend identifiziert.

Versionssperre

Die --disable-default-registry-endpoint Option ist ab den Veröffentlichungen von Januar 2024 verfügbar: v1.26.13+k3s1, v1.27.10+k3s1, v1.28.6+k3s1, v1.29.1+k3s1

Knoten können mit der --disable-default-registry-endpoint Option gestartet werden. Wenn dies eingestellt ist, wird containerd nicht auf den Standard-Registry-Endpunkt zurückgreifen und nur von konfigurierten Mirror-Endpunkten abrufen, zusammen mit der verteilten Registry, wenn sie aktiviert ist.

Dies kann gewünscht sein, wenn Ihr Cluster in einer echten Air-Gapped-Umgebung ist, in der die Upstream-Registry nicht verfügbar ist, oder wenn Sie möchten, dass nur einige Knoten von der Upstream-Registry abrufen.

Das Deaktivieren des Standard-Registry-Endpunkts gilt nur für Registries, die über registries.yaml konfiguriert sind. Wenn die Registry nicht ausdrücklich über den Mirror-Eintrag in registries.yaml konfiguriert ist, wird das Standard-Fallback-Verhalten weiterhin verwendet.

Registries-Konfigurationsdatei

Die Datei besteht aus zwei obersten Schlüsseln, mit Unterkeys für jede Registry:

mirrors:
  <REGISTRY>:
    endpoint:
      - https://<REGISTRY>/v2
configs:
  <REGISTRY>:
    auth:
      username: <BASIC AUTH USERNAME>
      password: <BASIC AUTH PASSWORD>
      token: <BEARER TOKEN>
    tls:
      ca_file: <PATH TO SERVER CA>
      cert_file: <PATH TO CLIENT CERT>
      key_file: <PATH TO CLIENT KEY>
      insecure_skip_verify: <SKIP TLS CERT VERIFICATION BOOLEAN>

Spiegel

Der Abschnitt Spiegel definiert die Namen und Endpunkte von Registries, zum Beispiel:

mirrors:
  registry.example.com:
    endpoint:
      - "https://registry.example.com:5000"

Jeder Mirror muss einen Namen und eine Reihe von Endpunkten haben. Beim Abrufen eines Images von einer Registry wird containerd versuchen, diese Endpunkt-URLs sowie den Standard-Endpunkt zu verwenden und den ersten funktionierenden zu nutzen.

Umleitungen

Wenn die private Registry als Mirror für eine andere Registry verwendet wird, wie zum Beispiel bei der Konfiguration eines Pull-Through-Cache, werden die Image-Zugriffe transparent auf die aufgeführten Endpunkte umgeleitet. Der ursprüngliche Registrierungsname wird über den ns Abfrageparameter an den Mirror-Endpunkt übergeben.

Zum Beispiel, wenn Sie einen Mirror für docker.io konfiguriert haben:

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"

Beim Abrufen von docker.io/rancher/mirrored-pause:3.6 wird das Image transparent als registry.example.com:5000/rancher/mirrored-pause:3.6 abgerufen.

Umschreibungen

Jeder Mirror kann eine Reihe von Umschreibungen haben, die reguläre Ausdrücke verwenden, um den Namen eines Images abzugleichen und zu transformieren, wenn er von einem Mirror abgerufen wird. Dies ist nützlich, wenn die Organisations-/Projektstruktur in der privaten Registry anders ist als die Registry, die sie spiegelt. Umschreibungen passen und transformieren nur den Bildnamen, NICHT das Tag.

Zum Beispiel würde die folgende Konfiguration das Bild docker.io/rancher/mirrored-pause:3.6 als registry.example.com:5000/mirrorproject/rancher-images/mirrored-pause:3.6 transparent abrufen:

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
    rewrite:
      "^rancher/(.*)": "mirrorproject/rancher-images/$1"
Versionssperre

Umschreibungen werden ab den Veröffentlichungen im Januar 2024 nicht mehr auf den Standard-Endpunkt angewendet: v1.26.13+k3s1, v1.27.10+k3s1, v1.28.6+k3s1, v1.29.1+k3s1. Vor diesen Veröffentlichungen wurden Umschreibungen auch auf den Standard-Endpunkt angewendet, was verhinderte, dass K3s von der Upstream-Registry abruft, wenn das Bild nicht von einem Mirror-Endpunkt abgerufen werden konnte und das Bild unter dem modifizierten Namen in der Upstream-Registry nicht verfügbar war.

Wenn Sie Umschreibungen anwenden möchten, wenn Sie direkt von einer Registry abrufen – wenn sie nicht als Mirror für eine andere Upstream-Registry verwendet wird – müssen Sie einen Mirror-Endpunkt angeben, der nicht mit dem Standard-Endpunkt übereinstimmt. Mirror-Endpunkte in registries.yaml, die mit dem Standard-Endpunkt übereinstimmen, werden ignoriert; der Standard-Endpunkt wird immer zuletzt ohne Umschreibungen versucht, wenn der Fallback nicht deaktiviert wurde.

Zum Beispiel, wenn Sie eine Registry unter https://registry.example.com/ haben und Umschreibungen anwenden möchten, wenn Sie explizit registry.example.com/rancher/mirrored-pause:3.6 abrufen, können Sie einen Mirror-Endpunkt mit dem angegebenen Port hinzufügen. Da der Mirror-Endpunkt nicht mit dem Standard-Endpunkt übereinstimmt - "https://registry.example.com:443/v2" != "https://registry.example.com/v2" - wird der Endpunkt als Mirror akzeptiert und Umschreibungen werden angewendet, obwohl er effektiv derselbe wie der Standard-Endpunkt ist.

mirrors:
 registry.example.com
   endpoint:
     - "https://registry.example.com:443"
   rewrite:
     "^rancher/(.*)": "mirrorproject/rancher-images/$1"

Beachten Sie, dass Bilder beim Verwenden von Mirrors und Umschreibungen weiterhin unter dem ursprünglichen Namen gespeichert werden. Zum Beispiel wird crictl image ls docker.io/rancher/mirrored-pause:3.6 als auf dem Knoten verfügbar anzeigen, selbst wenn das Bild von einem Mirror mit einem anderen Namen abgerufen wurde.

Konfigurationen

Der configs Abschnitt definiert die Konfiguration der TLS- und Anmeldeinformationen für jeden Mirror. Für jeden Mirror können Sie auth und/oder tls definieren.

Der tls Teil besteht aus:

Direktive Beschreibung

cert_file

Der Pfad des Client-Zertifikats, der zur Authentifizierung bei der Registry verwendet wird.

key_file

Der Pfad des Client-Schlüssels, der zur Authentifizierung bei der Registry verwendet wird.

ca_file

Definiert den Pfad des CA-Zertifikats, das verwendet wird, um die Serverzertifikatdatei der Registry zu überprüfen.

insecure_skip_verify

Ein boolescher Datentyp, der definiert, ob die TLS-Überprüfung für die Registry übersprungen werden soll.

Der auth Teil besteht entweder aus Benutzername/Passwort oder Authentifizierungs-Token:

Direktive Beschreibung

username

Benutzername der privaten Registry-Basisauthentifizierung

password

Benutzerpasswort der privaten Registry-Basisauthentifizierung

auth

Authentifizierungs-Token der privaten Registry-Basisauthentifizierung

Nachfolgend finden Sie einfache Beispiele für die Verwendung privater Registry in verschiedenen Modi:

Wildcard-Unterstützung

Versionssperre

Die Wildcard-Unterstützung ist ab den Veröffentlichungen im März 2024 verfügbar: v1.26.15+k3s1, v1.27.12+k3s1, v1.28.8+k3s1, v1.29.3+k3s1

Der "*" Wildcard-Eintrag kann in den Abschnitten mirrors und configs verwendet werden, um eine Standardkonfiguration für alle Registries bereitzustellen. Die Standardkonfiguration wird nur verwendet, wenn es keinen spezifischen Eintrag für diese Registry gibt. Beachten Sie, dass das Sternchen in Anführungszeichen gesetzt werden muss.

Im folgenden Beispiel wird ein lokaler Registry-Mirror für alle Registries verwendet. Die TLS-Überprüfung wird für alle Registries deaktiviert, außer für docker.io.

mirrors:
  "*":
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "docker.io":
  "*":
    tls:
      insecure_skip_verify: true

Mit TLS

Im Folgenden finden Sie Beispiele, die zeigen, wie Sie /etc/rancher/k3s/registries.yaml auf jedem Knoten konfigurieren können, wenn Sie TLS verwenden.

  • Mit Authentifizierung

  • Ohne Authentifizierung

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    auth:
      username: xxxxxx # this is the registry username
      password: xxxxxx # this is the registry password
    tls:
      cert_file: # path to the cert file used in the registry
      key_file:  # path to the key file used in the registry
      ca_file:   # path to the ca file used in the registry
mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    tls:
      cert_file: # path to the cert file used in the registry
      key_file:  # path to the key file used in the registry
      ca_file:   # path to the ca file used in the registry

Ohne TLS

Im Folgenden finden Sie Beispiele, die zeigen, wie Sie /etc/rancher/k3s/registries.yaml auf jedem Knoten konfigurieren können, wenn nicht TLS verwendet wird.

  • Mit Authentifizierung

  • Ohne Authentifizierung

mirrors:
  docker.io:
    endpoint:
      - "http://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    auth:
      username: xxxxxx # this is the registry username
      password: xxxxxx # this is the registry password
mirrors:
  docker.io:
    endpoint:
      - "http://registry.example.com:5000"

Im Falle einer Kommunikation ohne TLS müssen Sie http:// für die Endpunkte angeben, andernfalls wird standardmäßig https verwendet.

Damit die Änderungen an der Registry wirksam werden, müssen Sie K3s auf jedem Knoten neu starten.

Fehlerbehebung bei Image-Pulls

Wenn Kubernetes Probleme hat, ein Image zu ziehen, spiegelt der Fehler, der vom Kubelet angezeigt wird, möglicherweise nur den terminalen Fehler wider, der durch den Pull-Versuch gegen den Standard-Endpunkt zurückgegeben wird, wodurch es so aussieht, als würden die konfigurierten Endpunkte nicht verwendet.

Überprüfen Sie das containerd-Protokoll auf dem Knoten unter /var/lib/rancher/k3s/agent/containerd/containerd.log für detaillierte Informationen zur Ursache des Fehlers. Beachten Sie, dass Sie die Protokolle auf dem Knoten einsehen müssen, auf dem dem Pod geplant ist. Sie können überprüfen, auf welchem Knoten Ihrem Pod geplant ist, indem Sie kubectl get pod -o wide -n NAMESPACE POD ausführen und die Spalte NODE überprüfen.

Bilder zur privaten Registry hinzufügen

Das Spiegeln von Bildern in eine private Registry erfordert einen Host mit Docker oder anderen Drittanbieter-Tools, die in der Lage sind, Bilder zu ziehen und zu pushen.
Die folgenden Schritte setzen voraus, dass Sie einen Host mit dockerd und den Docker-CLI-Tools haben und Zugriff auf sowohl docker.io als auch Ihre private Registry haben.

  1. Erhalten Sie die k3s-images.txt-Datei von GitHub für die Version, mit der Sie arbeiten.

  2. Ziehen Sie jedes der K3s-Bilder, die in der Datei k3s-images.txt aufgeführt sind, von docker.io.
    Beispiel: docker pull docker.io/rancher/mirrored-pause:3.6

  3. Taggen Sie die Bilder für die private Registry um.
    Beispiel: docker tag docker.io/rancher/mirrored-pause:3.6 registry.example.com:5000/rancher/mirrored-pause:3.6

  4. Pushen Sie die Bilder in die private Registry.
    Beispiel: docker push registry.example.com:5000/rancher/mirrored-pause:3.6