containerd-Konfiguration in GKE-Knoten anpassen

Auf dieser Seite wird beschrieben, wie Sie die Konfiguration der containerd-Containerlaufzeit auf Ihren GKE-Knoten (Google Kubernetes Engine) anpassen. Bevor Sie dieses Dokument lesen, sollten Sie mit dem Konzept der Containerlaufzeit vertraut sein und wissen, warum es hilfreich sein kann, sie anzupassen.

containerd-Konfiguration in GKE

Sie können eine Reihe von Optionen in der containerd-Laufzeit manuell auf GKE-Knoten konfigurieren, auf denen ein Betriebssystem wie Container-Optimized OS ausgeführt wird. Wenn Sie die Laufzeit anpassen, können Sie spezielle Anforderungen wie den Zugriff auf private Image-Registries konfigurieren. Zum Festlegen dieser Optionen erstellen Sie eine YAML-Datei mit der Bezeichnung Laufzeitkonfigurationsdatei und übergeben die Datei beim Erstellen oder Aktualisieren eines Clusters oder Knotenpools an GKE.

Mit dieser Methode zur Anpassung von containerd können Sie die Bereitstellung privilegierter DaemonSets vermeiden, die ein Sicherheitsrisiko darstellen. Wenn Sie GKE eine Laufzeitkonfigurationsdatei bereitstellen, erstellt GKE Ihre Knoten neu und aktualisiert die containerd-Datei config.toml auf jedem Knoten mit Ihrer Konfiguration. Die Konfiguration bleibt über die Beendigung, Upgrades und Neuerstellungen von Knoten bestehen.

Sie können containerd-Einstellungen auf Cluster- oder Knotenpoolebene konfigurieren. Eine Konfiguration auf Knotenpoolebene überschreibt eine Konfiguration auf Clusterebene für diese Optionen. Wenn Sie eine containerd-Konfigurationsoption auf Clusterebene aktualisieren (z. B. registryHosts oder writableCgroups), aktualisiert und erstellt GKE die Knoten nur in Knotenpools neu, die keine eigenen Einstellungen auf Knotenpoolebene für diese Optionen haben. Knotenpools mit eigenen Konfigurationen auf Knotenpoolebene für die Option werden nicht aktualisiert oder neu erstellt und verwenden weiterhin ihre eigenen Einstellungen.

Mit der Laufzeitkonfigurationsdatei können Sie nur Optionen in containerd konfigurieren. GKE unterstützt auch die Konfiguration bestimmter kubelet-Optionen und Low-Level-Linux-Kernel-Optionen. Dazu wird eine separate Datei verwendet, die als Knotensystemkonfigurationsdatei bezeichnet wird. Weitere Informationen finden Sie unter Knotensystemkonfiguration anpassen.

Beschränkungen

Sie können eine Laufzeitkonfigurationsdatei nicht verwenden, um containerd-Einstellungen in Windows-Knoten-Images zu ändern.

Verfügbare containerd-Konfigurationsoptionen

In den folgenden Abschnitten werden die Optionen beschrieben, die Sie mit einer Laufzeitkonfigurationsdatei konfigurieren können.

privateRegistryAccessConfig

Greifen Sie auf private Image-Registrys mit privaten Anmeldedaten zu, die Sie in Secret Manager speichern.

Diese Option ist für Container-Optimized OS-Knoten-Images ab GKE-Version 1.27.3-gke.1700 und für Ubuntu-Knoten-Images ab Version 1.33 verfügbar.

Eine Anleitung finden Sie unter Auf private Registrys mit privaten CA-Zertifikaten zugreifen.

privateRegistryAccessConfig:
  enabled: true
  certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
    secretURI: "SECRET_LOCATION"
  fqdns:
  - "FQDN1"
  - "FQDN2"

Diese Konfiguration enthält die folgenden Felder:

  • enabled: Ein boolescher Wert zum Aktivieren der Konfiguration einer privaten Registry. Wenn Sie enabled: false festlegen, löschen Sie alle anderen Felder im Element privateRegistryAccessConfig.
  • certificateAuthorityDomainConfig: Enthält bis zu fünf Zertifikat- und FQDN-Definitionen.
  • gcpSecretManagerCertificateConfig: Enthält ein in Secret Manager gespeichertes Zertifikat und ein Array von FQDNs.
  • secretURI: Der Speicherort des Zertifikats im Secret Manager. privateRegistryAccessConfig unterstützt globale Secrets nur in secretURI.
  • fqdns: Eine Liste vollständig qualifizierter Domainnamen privater Registries. Sie können auch IPv4-Adressen verwenden. Wir empfehlen jedoch die Verwendung des FQDN.

registryHosts

Konfigurieren Sie erweiterte Einstellungen für containerd-Registries, z. B. Funktionen, benutzerdefinierte Header und Zertifikate. Dies entspricht der hosts.toml von containerd.

Diese Option ist für GKE-Versionen 1.34.1-gke.2980000 oder höher verfügbar.

registryHosts:
- server: "REGISTRY_SERVER_FQDN"
  hosts:
  - host: "MIRROR_FQDN"
    capabilities:
    - "HOST_CAPABILITY_PULL"
    - "HOST_CAPABILITY_RESOLVE"
    - "HOST_CAPABILITY_PUSH"
    overridePath: false
    dialTimeout: "30s"
    header:
    - key: "HEADER_KEY"
      value:
      - "HEADER_VALUE_1"
      - "HEADER_VALUE_2"
    ca:
    - gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CA_SECRET/versions/VERSION"
    client:
    - cert:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_CERT_SECRET/versions/VERSION"
      key:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_KEY_SECRET/versions/VERSION"

Diese Konfiguration enthält die folgenden Felder:

  • server: Der Hostname des Registrierungsservers, z. B. example.com. Damit wird die Konfigurationsdatei auf dem Knoten benannt. Dies sollte ein voll qualifizierter Domainname oder eine IP-Adresse ohne Schema, Port oder Pfad sein.
  • hosts: Eine Liste hostspezifischer Konfigurationen für den server.
  • host: Der Hostname eines Registry-Spiegels, z. B. https://mirror.example.com:8000/1234 oder 1.2.3.4:80. Dies sollten vollständig qualifizierte Domainnamen oder IP-Adressen sein. Schema, Port und Pfad werden unterstützt. Das Schema kann nur http oder https sein.
  • capabilities: Eine Liste von Funktionen, die angibt, welche Vorgänge ein Host ausführen kann. Unterstützte Werte sind:
    • HOST_CAPABILITY_PULL: stellt die Möglichkeit dar, Manifeste und Blobs nach Digest abzurufen.
    • HOST_CAPABILITY_RESOLVE: steht für die Möglichkeit, Manifeste anhand des Namens abzurufen.
    • HOST_CAPABILITY_PUSH: steht für die Fähigkeit, Blobs und Manifeste zu übertragen.
    Wenn nicht angegeben, sind alle Funktionen aktiviert.
  • overridePath: Boolescher Wert. Wenn true, wird der API-Stammendpunkt des Hosts im URL-Pfad und nicht durch die API-Spezifikation definiert. Dies kann mit nicht konformen OCI-Registries verwendet werden, bei denen das Präfix /v2 fehlt. Die Standardeinstellung ist false.
  • dialTimeout: Ein Dauerstring (z. B. "30s"), der die maximal zulässige Dauer für einen Verbindungsversuch angibt. Der maximal zulässige Wert beträgt "180s". Wenn nichts festgelegt ist, wird von containerd der Standardwert "30s" verwendet. Der Wert muss eine Dezimalzahl in Sekunden mit dem Suffix s sein.
  • header: Eine Liste benutzerdefinierter HTTP-Header, die an den Registry-Host gesendet werden sollen.
    • key: Der Headerschlüssel.
    • value: Eine Liste von Headerwerten.
  • ca: Eine Liste der Zertifikatskonfigurationen für die Zertifizierungsstelle (Certificate Authority, CA) des Registry-Hosts. Eine Anleitung zum Erstellen von Secrets für Zertifikate und zum Konfigurieren der erforderlichen Berechtigungen finden Sie unter Öffentliche CA-Schlüssel in Secret Manager speichern.
    • gcpSecretManagerSecretUri: Der URI eines Secrets im Secret Manager, das das CA-Zertifikat enthält. Es unterstützt sowohl globale als auch regionale Secrets. Die Formate für die jeweiligen geheimen Typen sind:
      • Format für globales Secret: projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION.
      • Format des regionalen Secrets: projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION.
  • client: Eine Liste von Clientzertifikats- und Schlüsselpaaren für die Authentifizierung beim Registry-Host. Eine Anleitung zum Erstellen von Secrets für Zertifikate und zum Konfigurieren der erforderlichen Berechtigungen finden Sie unter Öffentliche CA-Schlüssel in Secret Manager speichern.
    • cert: Die Clientzertifikatkonfiguration.
      • gcpSecretManagerSecretUri: Der URI eines Secrets im Secret Manager, das das Clientzertifikat enthält. Es unterstützt sowohl globale als auch regionale Secrets.
    • key: Die Konfiguration des privaten Schlüssels des Clients.
      • gcpSecretManagerSecretUri: Der URI eines Secrets im Secret Manager, das den Clientschlüssel enthält. Es unterstützt sowohl globale als auch regionale Secrets.

writableCgroups

Stellen Sie das /sys/fs/cgroup-Dateisystem im Lese-/Schreibmodus bereit, damit Arbeitslasten die Ressourcen ihrer untergeordneten Prozesse verwalten können.

Diese Option ist für GKE-Versionen 1.34.1-gke.2541000 oder höher verfügbar.

Weitere Informationen finden Sie unter Schreibbare Cgroups für Container konfigurieren.

writableCgroups:
  enabled: true

containerd-Konfiguration auf neue Cluster anwenden

In diesem Abschnitt erfahren Sie, wie Sie eine containerd-Konfigurationsdatei anwenden, wenn Sie einen neuen GKE-Cluster erstellen.

Führen Sie den folgenden Befehl aus, um Autopilot-Cluster zu erstellen:

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Ersetzen Sie Folgendes:

  • CLUSTER_NAME: Der Name des neuen Clusters.
  • LOCATION: Der Compute Engine-Standort für Ihren neuen Cluster.
  • PATH_TO_CONFIG_FILE: Der Pfad zur von Ihnen erstellten Konfigurationsdatei, z. B. ~/containerd-configuration.yaml.

Sie können die containerd-Konfiguration für neue Standardcluster aktivieren. Führen Sie dazu den Befehl gcloud container clusters create mit denselben Optionen aus. Sofern Sie keine andere containerd-Konfiguration angeben, übernehmen neue Knotenpools, die im Cluster erstellt werden, die Standard-containerd-Konfiguration auf Clusterebene.

containerd-Konfiguration auf neue Knotenpools anwenden

Mit dem folgenden Befehl können Sie die containerd-Konfiguration auf einen neuen GKE-Knotenpool anwenden:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Ersetzen Sie Folgendes:

  • NODE_POOL_NAME ist der Name des neuen Knotenpools.
  • CLUSTER_NAME den Namen des vorhandenen Clusters.
  • LOCATION: Der Compute Engine-Standort für Ihren neuen Knotenpool.
  • PATH_TO_CONFIG_FILE: Der Pfad zur von Ihnen erstellten Konfigurationsdatei, z. B. ~/containerd-configuration.yaml.

containerd-Konfiguration auf vorhandene Cluster anwenden

In diesem Abschnitt erfahren Sie, wie Sie eine containerd-Konfiguration auf vorhandene Cluster und Knoten anwenden.

Das Aktualisieren der containerd-Konfiguration auf Clusterebene gilt nur für Knotenpools, für die keine eigenen Einstellungen auf Knotenpoolebene definiert sind (z. B. registryHosts oder writableCgroups). GKE erstellt die Knoten in diesen Knotenpools neu, um die neue Konfiguration anzuwenden. Für Knotenpools mit Einstellungen auf Knotenpoolebene wird weiterhin die eigene Konfiguration verwendet und die Knoten werden nicht neu erstellt. Beim Aktualisieren eines Clusters oder Knotenpools mit einer containerd-Konfiguration werden die Knoten neu erstellt, um die Konfiguration anzuwenden. Dies kann zu vorübergehenden Unterbrechungen bei der Ausführung von Arbeitslasten führen. GKE erstellt Knoten nur dann neu, wenn automatische Upgrades aktiviert sind. Bei dieser Neuerstellung werden alle von Ihnen festgelegten Wartungsfenster berücksichtigt. In Standardclustern, für die keine automatischen Upgrades aktiviert sind, müssen Sie Ihre Knoten manuell neu erstellen, um die Konfiguration anzuwenden.

Zugriffsbereiche prüfen

Wenn in Ihrer Konfigurationsdatei Secrets aus Secret Manager verwendet werden, muss Ihr Cluster oder Knotenpool den Zugriffsbereich cloud-platform haben. In diesem Abschnitt erfahren Sie, wie Sie Ihre Zugriffsbereiche prüfen und einen vorhandenen Cluster mit einer neuen oder geänderten Laufzeitkonfigurationsdatei aktualisieren.

Weitere Informationen zu den Standardzugriffsbereichen in neuen Clustern finden Sie unter Zugriffsbereiche in GKE.

Autopilot-Zugriffsbereiche prüfen

Führen Sie dazu diesen Befehl aus:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Wenn Sie Secrets aus Secret Manager verwenden und Ihr Cluster nicht den Zugriffsbereich https://www.googleapis.com/auth/cloud-platform hat, erstellen Sie einen neuen Cluster mit diesem Zugriffsbereich.

Standardzugriffsbereiche prüfen

Prüfen Sie die Zugriffsbereiche eines Standardclusters in einem Knotenpool:

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --format='value[delimiter="\\n"](config.oauthScopes)'

Ersetzen Sie NODE_POOL_NAME durch den Namen des Knotenpools.

Wenn Sie Secrets aus Secret Manager verwenden und Ihr Cluster nicht den Zugriffsbereich https://www.googleapis.com/auth/cloud-platform hat, erstellen Sie einen neuen Knotenpool mit dem Zugriffsbereich cloud-platform und löschen Sie den vorhandenen Knotenpool.

Cluster für die Verwendung der Konfigurationsdatei aktualisieren

Führen Sie dazu diesen Befehl aus:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Knotenpool für die Verwendung einer Konfigurationsdatei aktualisieren

Führen Sie den folgenden Befehl aus, um die containerd-Konfiguration für einen Knotenpool zu aktualisieren:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Ersetzen Sie Folgendes:

  • NODE_POOL_NAME ist der Name des Knotenpools, den Sie aktualisieren möchten.
  • CLUSTER_NAME den Namen des vorhandenen Clusters.
  • LOCATION: der Compute Engine-Standort des Clusters.
  • PATH_TO_CONFIG_FILE: Der Pfad zur von Ihnen erstellten Konfigurationsdatei, z. B. ~/containerd-configuration.yaml.

Knoten in Standardclustern neu erstellen

Wenn Ihr Standardcluster keine automatischen Upgrades verwendet, müssen Sie Ihre Knotenpools manuell neu erstellen, um die neue Konfiguration anzuwenden. Wenn Sie eine manuelle Knotenneuerstellung auslösen möchten, aktualisieren Sie Ihren Cluster auf die bereits verwendete GKE-Version.

gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --cluster-version=VERSION

Ersetzen Sie VERSION durch die GKE-Patchversion, die der Cluster bereits verwendet.

containerd-Konfigurationsoptionen deaktivieren

privateRegistryAccessConfig deaktivieren

  1. Aktualisieren Sie Ihre Konfigurationsdatei, um enabled: false in privateRegistryAccessConfig anzugeben, und löschen Sie alle anderen Felder im Element, wie im folgenden Beispiel:

    privateRegistryAccessConfig:
  enabled: false
  2. Wenden Sie die aktualisierte Konfigurationsdatei auf Ihren Cluster an. Eine Anleitung finden Sie unter containerd-Konfiguration auf vorhandene Cluster anwenden.

registryHosts deaktivieren

  1. Aktualisieren Sie Ihre Konfigurationsdatei, um ein leeres Array im registryHosts-Element anzugeben, wie im folgenden Beispiel:

    registryHosts: []
  2. Wenden Sie die aktualisierte Konfigurationsdatei auf Ihren Cluster an. Eine Anleitung finden Sie unter containerd-Konfiguration auf vorhandene Cluster anwenden.