Container-Images mithilfe von Image-Streaming abrufen

Autopilot Standard

Auf dieser Seite wird beschrieben, wie Sie mit Image-Streaming in Google Kubernetes Engine (GKE) Container-Images abrufen. Dazu streamen Sie die Image-Daten je nach Bedarf Ihrer Anwendungen.

Neue Autopilot-Cluster, auf denen die GKE-Version 1.25.5-gke.1000 oder höher ausgeführt wird, verwenden automatisch Image-Streaming, um zulässige Images abzurufen. Die Anleitung auf dieser Seite gilt nur für Standardcluster.

Überblick

Image-Streaming ist eine Methode zum Abrufen von Container-Images, bei der GKE Daten, die von Ihren Anwendungen angefordert werden, aus zulässigen Images streamt. Mit Image-Streaming können Sie Arbeitslasten initialisieren, ohne auf das Herunterladen des gesamten Images zu warten. Dies führt zu erheblichen Verbesserungen bei den Initialisierungszeiten. Die verkürzte Abrufzeit bietet folgende Vorteile:

Schnelleres Autoscaling
Geringere Latenzzeit beim Abrufen großer Images
Schnellerer Pod-Start

Beim Image-Streaming verwendet GKE ein Remote-Dateisystem als Root-Dateisystem für alle Container, die zulässige Container-Images verwenden. GKE streamt nach Bedarf von Ihren Arbeitslasten Bilddaten aus dem Remote-Dateisystem. Ohne Image-Streaming lädt GKE das gesamte Container-Image auf jeden Knoten herunter und verwendet es als Root-Dateisystem für Ihre Arbeitslasten.

Während das Image hochgeladen wird, lädt GKE das gesamte Container-Image auf das lokale Laufwerk im Hintergrund herunter und speichert es im Cache. GKE verarbeitet dann zukünftige Datenleseanfragen aus dem im Cache gespeicherten Bild.

Wenn Sie Arbeitslasten bereitstellen, die bestimmte Dateien im Container-Image lesen müssen, stellt das Image-Streaming-Backend nur die angeforderten Dateien bereit.

Voraussetzungen

Sie müssen folgende Anforderungen erfüllen, um Image-Streaming in GKE Autopilot- und Standardclustern zu verwenden:

Sie müssen die Container File System API aktivieren.

Container File System API aktivieren
Neue Autopilot-Cluster müssen die GKE-Version 1.25.5-gke.1000 oder höher ausführen, damit das Image-Streaming automatisch aktiviert wird. Eine Anleitung finden Sie unter Version und Release-Version eines neuen Autopilot-Clusters bestimmen.
Neue und vorhandene GKE-Standardcluster müssen Version 1.18.6-gke.4801 oder höher ausführen.
Sie müssen das Container-Optimized OS mit containerd-Knoten-Image verwenden. Autopilot-Knoten verwenden immer dieses Knoten-Image.
Ihre Container-Images müssen in Artifact Registry gespeichert sein.
Wenn Sie private Cluster verwenden, müssen Sie im Subnetz den privaten Google-Zugriff aktivieren, damit Ihre Knoten auf den Image-Streaming-Dienst zugreifen können.
Wenn VPC Service Controls Ihre Container-Images schützt und Sie Image-Streaming verwenden, müssen Sie auch die Image-Streaming-API (containerfilesystem.googleapis.com) in den Dienstperimeter aufnehmen.
Wenn die GKE-Knoten im Cluster nicht das Standarddienstkonto verwenden, müssen Sie dafür sorgen, dass Ihr benutzerdefiniertes Dienstkonto die IAM-Rolle Service Usage-Nutzer (roles/serviceusage.serviceUsageConsumer) in dem Projekt hat, in dem das Container-Image gehostet wird.

Beschränkungen

Sie können kein Secret verwenden, um Container-Images vor der Version 1.23.5-gke.1900 abzurufen.
Container-Images, die das V2 Image Manifest, Schemaversion 1 verwenden, sind nicht geeignet.
Container-Images, die mit vom Kunden verwalteten Verschlüsselungsschlüsseln (CMEK) verschlüsselt sind, sind für Image-Streaming in GKE ab Version 1.25.3-gke.1000 geeignet. In früheren Versionen lädt GKE diese Images herunter, ohne die Daten zu streamen. Sie können weiterhin CMEKs verwenden, um angehängte nichtflüchtige Speicher und benutzerdefinierte Bootlaufwerke in Clustern zu schützen, die Image-Streaming verwenden.
Container-Images mit doppelten Ebenen sind nur für Image-Streaming in GKE-Version 1.28 oder höher geeignet. In früheren Versionen lädt GKE diese Images herunter, ohne die Daten zu streamen. Prüfen Sie das Container-Image auf leere oder doppelte Ebenen.
Das Artifact Registry-Repository muss sich in derselben Region befinden wie Ihre GKE-Knoten oder in einer Multi-Region, die der Region entspricht, in der Ihre Knoten ausgeführt werden. Beispiel:
- Wenn sich Ihre Knoten in us-east1 befinden, ist Image-Streaming für Repositories in der Region us-east1 oder der Multi-Region us verfügbar, da sowohl GKE als auch Artifact Registry in Rechenzentren in den Vereinigten Staaten ausgeführt werden.
- Wenn sich Ihre Knoten in der Region northamerica-northeast1 befinden, werden die Knoten in Kanada ausgeführt. In diesem Fall ist Image-Streaming nur für Repositories in derselben Region verfügbar.
Wenn Ihre Arbeitslasten während der Initialisierung viele Dateien in einem Image lesen, kann es aufgrund der durch die Remote-Dateilesevorgänge verursachten Latenz zu einer erhöhten Initialisierungszeit kommen.
Möglicherweise bemerken Sie die Vorteile des Image-Streamings beim ersten Abrufen eines zulässigen Images nicht. Aber nachdem das Image-Streaming das Image im Cache gespeichert hat, profitieren künftige Image-Abrufe für einen Cluster vom Image-Streaming.
GKE-Standardcluster verwenden die Konfiguration auf Clusterebene, um zu bestimmen, ob das Image-Streaming für neue Knotenpools aktiviert werden soll, die per automatischer Knotenbereitstellung erstellt wurden. Sie können jedoch keine Arbeitslasttrennung verwenden, um Knotenpools mit aktiviertem Image-Streaming zu erstellen, wenn das Image-Streaming auf Clusterebene deaktiviert ist.
Linux-Dateifunktionen wie CAP_NET_RAW werden beim Image-Streaming in GKE-Version 1.22.6-gke.300 und höher unterstützt. Bei früheren GKE-Versionen sind diese Funktionen nicht verfügbar, wenn die Image-Datei gestreamt oder das Image auf dem lokalen Laufwerk gespeichert wird. Verwenden Sie Image-Streaming für Container mit diesen Funktionen in GKE-Versionen vor 1.22.6-gke.300, um potenzielle Störungen zu vermeiden. Wenn Ihr Container Linux-Dateifunktionen benötigt, wird er möglicherweise nicht gestartet, wenn er bei aktiviertem Image-Streaming ausgeführt werden soll, und es werden Fehler des Typs „Berechtigung verweigert“ angezeigt.

Hinweis

Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen:

Aktivieren Sie die Google Kubernetes Engine API.

Google Kubernetes Engine API aktivieren

Wenn Sie die Google Cloud CLI für diese Aufgabe verwenden möchten, müssen Sie die gcloud CLI installieren und dann initialisieren. Wenn Sie die gcloud CLI bereits installiert haben, rufen Sie die neueste Version mit gcloud components update ab.
Hinweis: Legen Sie für vorhandene Installationen der gcloud CLI die compute/region- und compute/zone-Attribute fest. Durch das Festlegen von Standardspeicherorten können Sie in der gcloud CLI Fehler wie One of [--zone, --region] must be supplied: Please specify location vermeiden.

Aktivieren Sie die Container File System API.

Container File System API aktivieren

Image-Streaming in Clustern aktivieren

Sie können Image-Streaming in neuen oder vorhandenen Standard-Clustern mit der gcloud CLI und dem Flag --enable-image-streaming oder über die Google Cloud Console aktivieren. Standardmäßig übernehmen Knotenpools im Cluster die Image-Streaming-Einstellung auf Clusterebene. Um dieses Verhalten zu ändern, können Sie das Image-Streaming in Knotenpools im Cluster aktivieren oder deaktivieren.

Alle neuen Autopilot-Cluster, auf denen die GKE-Version 1.25.5-gke.1000 oder höher ausgeführt wird, verwenden das Image-Streaming, um zulässige Images abzurufen. Eine Anleitung finden Sie unter Version und Release-Version eines neuen Autopilot-Clusters bestimmen. Die folgende Anleitung gilt nur für GKE Standard-Cluster.

In einem neuen Cluster

Sie können Image-Streaming in neuen Clustern mit der gcloud CLI oder der Google Cloud Console aktivieren.

gcloud

Führen Sie den folgenden Befehl aus, um einen neuen Cluster zu erstellen, in dem Image-Streaming aktiviert ist:

gcloud container clusters create CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming

Dabei gilt:

CLUSTER_NAME: Der Name des neuen Clusters.
COMPUTE_ZONE: Die Compute Engine-Zone für Ihren neuen Cluster. Verwenden Sie für regionale Cluster stattdessen das Flag --region=COMPUTE_REGION. Achten Sie darauf, dass die Zone oder Region dieselbe Region ist oder sich in derselben Mehrfachregion befindet wie das Artifact Registry-Repository, das das Image enthält.

Console

Rufen Sie in der Google Cloud Console die Seite Google Kubernetes Engine auf.

Zur Seite „Google Kubernetes Engine“
Klicken Sie auf Erstellen.
Klicken Sie unter GKE Standard auf Konfigurieren.
Klicken Sie im Navigationsbereich unter Cluster auf Features.
Wählen Sie im Abschnitt Sonstige das Kästchen Image-Streaming aus.
Konfigurieren Sie den Cluster nach Bedarf und klicken Sie dann auf Erstellen.

In einem vorhandenen Cluster

Sie können Image-Streaming in vorhandenen Clustern, die die Anforderungen erfüllen, mit der gcloud CLI oder der Google Cloud Console aktivieren.

gcloud

Führen Sie den folgenden Befehl mit der gcloud CLI aus, um einen vorhandenen Cluster für die Verwendung von Image-Streaming zu aktualisieren:

gcloud container clusters update CLUSTER_NAME \
    --enable-image-streaming

Console

Rufen Sie in der Google Cloud Console die Seite Google Kubernetes Engine auf.

Zur Seite "Google Kubernetes Engine"
Klicken Sie auf den Namen des Clusters, den Sie ändern möchten.
Klicken Sie auf der Seite Cluster im Abschnitt Features neben auf Image-Streaming.
Wählen Sie im Dialogfeld Image-Streaming bearbeiten das Kästchen Image-Streaming aktivieren aus.
Klicken Sie auf Änderungen speichern.

Nachdem Sie den Cluster geändert haben, aktiviert GKE standardmäßig das Image-Streaming für Ihre vorhandenen Knotenpools. Wenn Sie Image-Streaming für einzelne Knotenpools explizit aktiviert oder deaktiviert haben, übernehmen diese Knotenpools Änderungen der Einstellung auf Clusterebene nicht mehr.

Prüfen, ob Image-Streaming für Cluster aktiviert ist

Sie können prüfen, ob Image-Streaming auf Clusterebene mit der gcloud CLI oder der Google Cloud Console aktiviert ist.

gcloud

Führen Sie dazu diesen Befehl aus:

gcloud container clusters describe CLUSTER_NAME \
    --flatten "nodePoolDefaults.nodeConfigDefaults"

Die Einstellung ist aktiviert, wenn die Ausgabe in etwa so aussieht:

gcfsConfig:
  enabled: true
...

Die Einstellung ist deaktiviert, wenn die Ausgabe in etwa so aussieht:

gcfsConfig: {}
...

Console

Rufen Sie in der Google Cloud Console die Seite Google Kubernetes Engine auf.

Zur Seite "Google Kubernetes Engine"
Klicken Sie auf den Namen des Clusters, den Sie prüfen möchten.
Auf der Seite Cluster im Abschnitt Features wird neben Image-Streaming angezeigt, ob die Einstellung aktiviert ist.

Image-Streaming für Knotenpools aktivieren

Standardmäßig übernehmen Knotenpools die Image-Streaming-Einstellung auf Clusterebene. Mit der gcloud CLI können Sie Image-Streaming für bestimmte Knotenpools aktivieren oder deaktivieren.

Für einen neuen Knotenpool

Führen Sie den folgenden Befehl aus, um einen neuen Knotenpool zu erstellen, für den Image-Streaming aktiviert ist:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming

Dabei gilt:

NODE_POOL_NAME ist der Name des neuen Knotenpools.
CLUSTER_NAME ist der Name des Clusters für den Knotenpool.
COMPUTE_ZONE ist die Compute Engine-Zone Ihres Clusters. Verwenden Sie für regionale Cluster stattdessen das Flag --region=COMPUTE_REGION.

Für einen vorhandenen Knotenpool

Sie können Image-Streaming auf vorhandenen Knotenpools aktivieren, die die Anforderungen erfüllen.

Führen Sie den folgenden Befehl aus, um einen vorhandenen Knotenpool für die Verwendung von Image-Streaming zu aktualisieren:

gcloud container node-pools update POOL_NAME \
    --cluster=CLUSTER_NAME \
    --enable-image-streaming

Prüfen, ob Image-Streaming für Knotenpool aktiviert ist

Prüfen Sie, ob Image-Streaming für einen Knotenpool aktiviert ist:

gcloud container node-pools describe POOL_NAME \
    --cluster=CLUSTER_NAME \

Die Einstellung ist aktiviert, wenn die Ausgabe in etwa so aussieht:

gcfsConfig:
  enabled: true
...

Die Einstellung ist deaktiviert, wenn die Ausgabe in etwa so aussieht:

gcfsConfig: {}
...

Arbeitslast mit Image-Streaming planen

Nachdem Sie Image-Streaming in Ihrem Cluster aktiviert haben, wird es von GKE automatisch verwendet, um zulässige Container-Images aus Artifact Registry abzurufen. Dafür ist keine weitere Konfiguration erforderlich.

GKE fügt Knoten in Knotenpools mit aktiviertem Image-Streaming das Label cloud.google.com/gke-image-streaming: "true" hinzu. Wenn Sie bei GKE Standard das Image-Streaming für bestimmte Knotenpools aktivieren oder deaktivieren, damit Ihr Cluster eine Mischung aus Knoten enthält, die Image-Streaming verwenden, und Knoten, die das nicht tun, können Sie Knotenselektoren in Ihren Deployments nutzen, um zu steuern, ob GKE Ihre Arbeitslasten auf Knoten plant, die Image-Streaming verwenden.

Im folgenden Beispiel planen Sie ein Deployment, das ein großes Container-Image auf einem Cluster mit aktiviertem Image-Streaming verwendet. Sie können dann optional die Leistung mit einem Image-Pull ohne aktiviertes Image-Streaming vergleichen.

Erstellen Sie einen neuen Cluster mit aktiviertem Image-Streaming:

gcloud container clusters create CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --enable-image-streaming \
    --image-type="COS_CONTAINERD"

Rufen Sie Anmeldedaten für den Cluster ab:

gcloud container clusters get-credentials CLUSTER_NAME \
    --zone=COMPUTE_ZONE

Speichern Sie das folgende Manifest als frontend-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  replicas: 1
  selector:
    matchLabels:
      app: guestbook
      tier: frontend
  template:
    metadata:
      labels:
        app: guestbook
        tier: frontend
    spec:
      containers:
      - name: php-redis
        image: us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5
        env:
        - name: GET_HOSTS_FROM
          value: "dns"
        resources:
          requests:
            cpu: 100m
            memory: 100Mi
        ports:
        - containerPort: 80

Das Container-Image gb-frontend ist 327 MB groß.

Wenden Sie das Manifest auf Ihren Cluster an:
```
kubectl apply -f frontend-deployment.yaml
```

Prüfen Sie, ob GKE das Deployment erstellt hat:

kubectl get pods -l app=guestbook

Die entsprechende Ausgabe sieht etwa so aus:

NAMESPACE    NAME                          READY    STATUS       RESTARTS    AGE
default      frontend-64bcc69c4b-pgzgm     1/1      Completed    0           3s

Rufen Sie das Kubernetes-Ereignislog ab, um Ereignisse zum Abrufen von Images zu sehen:
```
kubectl get events --all-namespaces
```
Die entsprechende Ausgabe sieht etwa so aus:
```
NAMESPACE  LAST SEEN  TYPE    REASON          OBJECT                                                 MESSAGE
default    11m        Normal  Pulling         pod/frontend-64bcc69c4b-pgzgm                          Pulling image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5"
default    11m        Normal  Pulled          pod/frontend-64bcc69c4b-pgzgm                          Successfully pulled image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" in 1.536908032s
default    11m        Normal  ImageStreaming  node/gke-riptide-cluster-default-pool-f1552ec4-0pjv    Image us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5 is backed by image streaming.
...
```
In dieser Ausgabe gilt:
- Das Ereignis Pulled zeigt die Zeit an, die für das Image-Streaming zum Abrufen des Images benötigt wurde.
- Das Ereignis ImageStreaming zeigt, dass der Knoten Image-Streaming verwendet, um das Container-Image bereitzustellen.
  
  Hinweis: Im Feld Reason wird BackedByGCFS anstelle von ImageStreaming in Clustern mit GKE-Versionen vor 1.20.9-gke.1000 angezeigt. BackedByGCFS gibt auch an, dass das Image Image-Streaming verwendet.
  Hinweis: Wenn Sie eine Arbeitslast ausführen, die dasselbe Image auf demselben Knoten verwendet, nutzt GKE den lokalen Cache des Images, anstatt das Image zu streamen. Der Wert Container image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" already present on machine wird im Feld Message wird für das Pod-Ereignis Pulled angezeigt. Wenn Sie die Leistung des Image-Streamings noch einmal testen möchten, löschen Sie den Knoten und erstellen Sie einen neuen.

Leistung mit Standardvorgängen zum Abrufen von Images vergleichen

In diesem optionalen Beispiel erstellen Sie einen neuen Cluster mit deaktiviertem Image-Streaming und stellen das Deployment frontend bereit, um die Leistung mit Image-Streaming zu vergleichen.

Erstellen Sie einen neuen Cluster mit deaktiviertem Image-Streaming:
```
gcloud container clusters create CLUSTER2_NAME\
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD"
```
Hinweis: Standardmäßig erstellt GKE Cluster mit deaktiviertem Image-Streaming.

Rufen Sie Anmeldedaten für den Cluster ab:

gcloud container clusters get-credentials CLUSTER2_NAME \
    --zone=COMPUTE_ZONE

Stellen Sie das frontend-Deployment aus dem vorherigen Beispiel bereit:
```
kubectl apply -f frontend-deployment.yaml
```
Rufen Sie das Kubernetes-Ereignislog ab:
```
kubectl get events --all-namespaces
```
Die entsprechende Ausgabe sieht etwa so aus:
```
 NAMESPACE  LAST SEEN  TYPE    REASON     OBJECT                             MESSAGE
 default    87s        Normal  Pulled     pod/frontend-64bcc69c4b-qwmfp      Successfully pulled image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" in 23.929723476s
```
Beachten Sie die Zeit, die GKE zum Abrufen des gesamten Images benötigt hat. In dieser Beispielausgabe benötigte GKE fast 24 Sekunden. Wenn Image-Streaming aktiviert ist, benötigt GKE nur 1,5 Sekunden zum Abrufen der Image-Daten, die die Arbeitslast zum Starten benötigte.

Bereinigen

Löschen Sie die in den vorherigen Beispielen erstellten Cluster, um Gebühren zu vermeiden:

gcloud container clusters delete CLUSTER_NAME CLUSTER2_NAME

Image-Streaming deaktivieren

Wenn Sie GKE Autopilot verwenden, können Sie das Image-Streaming nicht für einzelne Cluster deaktivieren. Sie können die Container File System API deaktivieren, was das Image-Streaming für das gesamte Projekt deaktiviert.

Wenn Sie GKE-Standardcluster verwenden, können Sie das Image-Streaming für einzelne Cluster oder bestimmte Knotenpools deaktivieren, wie in folgenden Abschnitten beschrieben.

Image-Streaming in einem GKE Standard-Cluster deaktivieren

Sie können Image-Streaming in vorhandenen GKE-Standardclustern mit der gcloud CLI oder der Google Cloud Console deaktivieren.

gcloud

Führen Sie den folgenden Befehl aus, um Image-Streaming in einem vorhandenen Cluster zu deaktivieren:

gcloud container clusters update CLUSTER_NAME \
    --no-enable-image-streaming

Console

Rufen Sie in der Google Cloud Console die Seite Google Kubernetes Engine auf.

Zur Seite "Google Kubernetes Engine"
Klicken Sie auf den Namen des Clusters, den Sie ändern möchten.
Klicken Sie auf der Seite Cluster unter Features neben Image-Streaming auf .
Deaktivieren Sie im Dialogfeld Image-Streaming bearbeiten das Kästchen Image-Streaming aktivieren.
Klicken Sie auf Änderungen speichern.

Für einen neuen Knotenpool

Wenn Sie Image-Streaming beim Erstellen eines neuen Knotenpools deaktivieren möchten, geben Sie das Flag --no-enable-image-streaming wie im folgenden Befehl an:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --no-enable-image-streaming

Für einen vorhandenen Knotenpool

Führen Sie den folgenden Befehl aus, um Image-Streaming für einen vorhandenen Knotenpool zu deaktivieren:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --no-enable-image-streaming

Arbeitsspeicherreservierung für Image-Streaming

GKE reserviert zusätzlich zum Arbeitsspeicher, der für die Ausführung von Knotensystemkomponenten reserviert ist, Arbeitsspeicherressourcen für das Image-Streaming. GKE reserviert keine zusätzlichen CPU-Ressourcen für Image-Streaming. In GKE Standard-Clustern ändert diese Reservierung die Arbeitsspeicherressourcen, die Sie in Ihren Pods anfordern können. In GKE Autopilot verwaltet GKE Systemzuweisungen, damit es keine Auswirkungen auf die Planung Ihrer Arbeitslasten hat.

Weitere Informationen zu den von GKE für Knotenkomponenten erstellten Arbeitsspeicherreservierungen finden Sie unter Standardclusterarchitektur.

In Knoten, die Image-Streaming verwenden, nimmt GKE die folgenden zusätzlichen Arbeitsspeicherreservierungen für neue Reservierungen vor:

Kein zusätzlicher Arbeitsspeicher für Maschinen mit weniger als 1 GiB Arbeitsspeicher
1 % der ersten 4 GiB Arbeitsspeicher
0,8 % der nächsten 4 GiB Arbeitsspeicher (bis zu 8 GiB)
0,8 % der nächsten 8 GiB Arbeitsspeicher (bis zu 16 GiB)
0,24 % der nächsten 112 GiB Arbeitsspeicher (bis zu 128 GiB)
0,08 % sämtlichen Speichers oberhalb von 128 GiB

Fehlerbehebung

GKE verwendet nicht das Image-Streaming-Dateisystem

Wenn Ihr GKE-Ereignislog keine Image-Streaming-Ereignisse anzeigt, wird Ihr Image nicht vom Remote-Dateisystem unterstützt. Wenn GKE das Image zuvor auf dem Knoten abgerufen hat, ist dies das erwartete Verhalten, da GKE den lokalen Cache des Images für nachfolgende Pulls anstelle von Image-Streaming verwendet. Um dies zu prüfen suchen Sie im Feld Message für das Pod-Ereignis Pulled nach Container image IMAGE_NAME already present on machine.

Wenn Sie das Image-Streaming-Ereignis beim ersten Abruf des Images auf dem Knoten nicht sehen, prüfen Sie, ob Sie die Anforderungen für das Image-Streaming erfüllen. Wenn Sie die Anforderungen erfüllen, können Sie das Problem diagnostizieren. Prüfen Sie dazu die Logs des Image-Streamingdienstes namens gcfsd:

Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.

Zum Log-Explorer
Geben Sie im Feld Abfrage die folgende Abfrage ein:
```
logName="projects/PROJECT_ID/logs/gcfsd"
resource.labels.cluster_name="CLUSTER_NAME"
```
Dabei gilt:
- PROJECT_ID ist der Name Ihres Projekts.
- CLUSTER_NAME ist der Name Ihres Clusters.
Klicken Sie auf Abfrage ausführen.

Sie können die gcfsd-Logs auch mit dem Log-Explorer prüfen:

Rufen Sie in der Google Cloud Console den Log-Explorer auf.

Zum Log-Explorer
Geben Sie im Feld Abfrage die folgende Abfrage ein:
```
logName="projects/PROJECT_ID/logs/gcfsd"
```
Ersetzen Sie PROJECT_ID durch Ihre Google Cloud-Projekt-ID.

PermissionDenied

Wenn in den gcfsd-Logs eine Fehlermeldung wie die folgende angezeigt wird, hat der Knoten nicht den richtigen API-Bereich. GKE ruft Container-Images für Arbeitslasten ohne Image-Streaming ab.

level=fatal msg="Failed to create a Container File System client: rpc error:
code = PermissionDenied desc = failed to probe endpoint: rpc error: code = PermissionDenied
desc = Request had insufficient authentication scopes."

Sie können dies beheben, indem Sie dem Knoten den richtigen Bereich zuweisen, damit er Image-Streaming verwenden kann. Fügen Sie dem Cluster oder Knotenpool den Bereich devstorage.read_only hinzu, ähnlich dem folgenden Befehl:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming \
    --scope="https://www.googleapis.com/auth/devstorage.read_only"

FailedPrecondition

Wenn Sie eine Fehlermeldung mit code = FailedPrecondition sehen, wurde das Image nicht in das Remote-Dateisystem des Image-Streamings importiert.

Dieser Fehler kann auftreten, wenn Sie versuchen, Image-Streaming mit einem vorhandenen Knotenpool zu verwenden. Wenn ein Knoten im Knotenpool bereits das Container-Image auf dem Laufwerk hat, verwendet GKE das lokale Image anstelle von Image-Streaming, um das Image abzurufen.

Versuchen Sie Folgendes, um das Problem zu beheben:

Warten Sie einige Minuten und versuchen Sie dann noch einmal, die Arbeitslast bereitzustellen.
Fügen Sie neue Knoten oder einen neuen Knotenpool hinzu und planen Sie die Arbeitslast auf diesen Knoten.

InvalidArgument

Wenn Sie eine Fehlermeldung mit code=InvalidArgument sehen, ist das von Ihrer Arbeitslast verwendete Container-Image nicht für das Image-Streaming geeignet. Das Image muss die Anforderungen erfüllen. Wenn sich Ihr Image nicht in Artifact Registry befindet, versuchen Sie, zu Artifact Registry zu migrieren.

`backend.FileContent failed`

Der folgende Fehler kann auftreten, wenn Containerdateien mit aktiviertem Image-Streaming gelesen werden:

level=error msg="backend.FileContent failed" error="rpc error: code = ResourceExhausted desc = Quota exceeded for quota metric 'Content requests per project per region' and limit 'Content requests per project per region per minute per region' of service 'containerfilesystem.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'." layer_id="sha256:1234567890" module=gcfs_backend offset=0 path=etc/passwd size=4096

Dieser Fehler gibt an, dass das Projekt das Kontingent überschritten hat, das zum Lesen von Dateien aus dem Remote-Container-Dateisystemdienst erforderlich ist. Erhöhen Sie die folgenden Kontingente, um dieses Problem zu beheben:

Inhaltsanfragen pro Projekt pro Region und Minute pro Region
Inhaltsanfragen pro Projekt und Region

GKE lädt das Image herunter, ohne die Daten zu streamen

Container-Images mit vom Kunden verwalteten Verschlüsselungsschlüsseln (CMEK) sind nur für Image-Streaming in GKE-Version 1.25.3-gke.1000 oder höher geeignet. Container-Images mit doppelten Ebenen sind nur für Image-Streaming in GKE-Version 1.28 oder höher geeignet. Weitere Informationen finden Sie unter Einschränkungen.

Nach leeren Ebenen oder doppelten Ebenen suchen

Führen Sie folgenden Befehl aus, um das Container-Image auf leere Ebenen oder doppelte Ebenen zu prüfen:

docker inspect IMAGE_NAME

Ersetzen Sie IMAGE_NAME durch den Namen des Container-Image.

Prüfen Sie in der Ausgabe des Befehls die Einträge unter "Layers".

Wenn einer der Einträge genau mit der folgenden "sha256"-Ausgabe übereinstimmt, hat das Container-Image eine leere Ebene und ist nicht für das Image-Streaming geeignet.

"Layers": [
  ...
  "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4",
  ...
]

Wenn doppelte Einträge wie im folgenden Beispiel vorhanden sind, hat das Container-Image doppelte Ebenen und ist nicht für Image-Streaming geeignet.

"Layers": [
  "sha256:28699c71935fe3ffa56533db44ad93e5a30322639f7be70d5d614e06a1ae6d9b",
  ...
  "sha256:28699c71935fe3ffa56533db44ad93e5a30322639f7be70d5d614e06a1ae6d9b",
  ...
]

Der Befehl `mv` und `renameat2`-Systemaufrufe schlagen bei Symlink-Dateien fehl

Wenn bei GKE-Knoten ab Version 1.25 Image-Streaming aktiviert ist, kann der mv-Befehl und der renameat2-Systemaufruf bei Symlink-Dateien in Container-Images mit der Fehlermeldung „Keine derartigen Geräte oder Adressen“ fehlschlagen. Das Problem wird durch einen Rückgang der aktuellen Linux-Kernel verursacht.

Diese Systemaufrufe sind nicht üblich, sodass die meisten Images nicht von diesem Problem betroffen sind. Dieses Problem tritt normalerweise in Phasen der Containerinitialisierung auf, wenn eine Anwendung für die Ausführung und das Verschieben von Dateien vorbereitet wird. Da es nicht möglich ist, das Image lokal zu testen, empfiehlt GKE die Verwendung von Image-Streaming in Testumgebungen, um das Problem zu ermitteln, bevor das Image in der Produktion verwendet wird.

Die Korrektur ist in den folgenden GKE-Patchversionen verfügbar:

1.25: 1.25.14-gke.1351000 und höher
1.26: 1.26.9-gke.1345000 und höher
1.27: 1.27.6-gke.100und höher
1.28: 1.28.1-gke.1157000 und höher

Alternativ können Sie versuchen, den Code zu ersetzen, der zum Systemaufruf renameat2 führt, um dieses Problem für alle betroffenen Arbeitslasten zu beheben. Wenn Sie den Code nicht ändern können, müssen Sie im Knotenpool Image-Streaming deaktivieren, um das Problem zu beheben.

Container-Images mithilfe von Image-Streaming abrufen

Überblick

Voraussetzungen

Beschränkungen

Hinweis

Image-Streaming in Clustern aktivieren

In einem neuen Cluster

gcloud

Console

In einem vorhandenen Cluster

gcloud

Console

Prüfen, ob Image-Streaming für Cluster aktiviert ist

gcloud

Console

Image-Streaming für Knotenpools aktivieren

Für einen neuen Knotenpool

Für einen vorhandenen Knotenpool

Prüfen, ob Image-Streaming für Knotenpool aktiviert ist

Arbeitslast mit Image-Streaming planen

Leistung mit Standardvorgängen zum Abrufen von Images vergleichen

Bereinigen

Image-Streaming deaktivieren

Image-Streaming in einem GKE Standard-Cluster deaktivieren

gcloud

Console

Für einen neuen Knotenpool

Für einen vorhandenen Knotenpool

Arbeitsspeicherreservierung für Image-Streaming

Fehlerbehebung

GKE verwendet nicht das Image-Streaming-Dateisystem

PermissionDenied

FailedPrecondition

InvalidArgument

backend.FileContent failed

GKE lädt das Image herunter, ohne die Daten zu streamen

Nach leeren Ebenen oder doppelten Ebenen suchen

Der Befehl mv und renameat2-Systemaufrufe schlagen bei Symlink-Dateien fehl

`backend.FileContent failed`

Der Befehl `mv` und `renameat2`-Systemaufrufe schlagen bei Symlink-Dateien fehl