Containerlaufzeitvertrag

Auf dieser Seite werden die wichtigsten Anforderungen und Verhaltensweisen von Containern in Cloud Run aufgeführt. Es gibt einige Unterschiede zwischen Cloud Run-Diensten und Cloud Run-Jobs. Diese werden bei Bedarf benannt.

Unterstützte Sprachen und Images

Ihr Container-Image kann Code in der Programmiersprache Ihrer Wahl ausführen und jedes Basis-Image verwenden, sofern die auf dieser Seite aufgeführten Einschränkungen berücksichtigt werden.

Ausführbare Dateien im Container-Image müssen für Linux 64-Bit kompiliert sein. Cloud Run unterstützt speziell das Linux x86_64-ABI-Format.

Cloud Run akzeptiert Container-Images in den Docker Image Manifest V2, Schema 1, Schema 2 und OCI-Bildformate. Cloud Run akzeptiert auch mit Zstd komprimierte Container-Images.

Wenn Sie ein Image mit mehreren Architekturen bereitstellen, muss die Manifestliste linux/amd64 enthalten.

Für mit Cloud Run bereitgestellte Funktionen können Sie eines der Cloud Run-Laufzeit-Basis-Images verwenden, die von den Buildpacks von Google Cloud veröffentlicht werden, um automatische Sicherheits- und Wartungsupdates zu erhalten. Informationen zu den unterstützten Laufzeiten finden Sie im Zeitplan für die Laufzeitunterstützung.

Anfragen auf dem richtigen Port überwachen (Dienste)

Ein Cloud Run-Dienst startet Cloud Run-Instanzen zur Verarbeitung eingehender Anfragen. Eine Cloud Run-Instanz hat immer einen einzelnen Ingress-Container, der Anfragen überwacht, und optional einen oder mehrere Sidecar-Container. Der folgende Port-Konfigurationsdetails gelten nur für den Container für eingehenden Traffic, nicht für Sidecars.

Der Ingress-Container innerhalb einer Instanz muss auf Anfragen unter 0.0.0.0 auf dem Port achten, an den Anfragen gesendet werden. Standardmäßig werden Anfragen an 8080 gesendet, aber Sie können Cloud Run so konfigurieren, dass Anfragen an den Port Ihrer Wahl gesendet werden. Cloud Run fügt die PORT-Umgebungsvariable in den Container ein.

Container, die in einer Jobausführung laufen, müssen nach Abschluss beendet werden

Bei Cloud Run-Jobs muss der Container mit dem Exit-Code 0 beendet werden, wenn der Job erfolgreich abgeschlossen wurde, und mit einem Exitcode ungleich Null beendet werden, wenn der Job fehlgeschlagen ist.

Da Jobs keine Anfragen verarbeiten sollen, sollte der Container weder einen Port überwachen noch einen Webserver starten.

Verschlüsselung auf Transportebene (TLS)

Der Container sollte die Sicherheit der Transportebene nicht direkt implementieren. TLS wird von Cloud Run für HTTPS und gRPC beendet und Anfragen werden dann als HTTP/1 oder gRPC ohne TLS an den Container weitergeleitet.

Wenn Sie einen Cloud Run-Dienst für die End-to-End-Verwendung von HTTP/2 konfigurieren, muss Ihr Container Anfragen im HTTP/2-Klartextformat (h2c) verarbeiten, da TLS weiterhin von Cloud Run automatisch beendet wird.

Antworten (Dienste)

Bei Cloud Run-Diensten muss Ihr Container innerhalb der in der Einstellung für das Zeitlimit für Anfragen angegebenen Zeit nach Erhalt einer Anfrage eine Antwort senden, wobei die Startzeit des Containers zu berücksichtigen ist. Andernfalls wird die Anfrage beendet und der Fehler 504 wird ausgegeben.

Antwort-Caching und Cookies

Wenn die Antwort Ihres Cloud Run-Dienstes einen Set-Cookie-Header enthält, legt Cloud Run den Cache-Control-Header auf private fest, damit die Antwort nicht im Cache gespeichert wird. Dadurch wird verhindert, dass andere Nutzer das Cookie abrufen.

Umgebungsvariablen

Für Cloud Run-Dienste und -Jobs stehen verschiedene Umgebungsvariablen zur Verfügung.

Umgebungsvariablen für Dienste

Die folgenden Umgebungsvariablen werden allen laufenden Containern automatisch hinzugefügt, außer PORT. Die Variable PORT wird nur dem Container für eingehenden Traffic hinzugefügt:

Name	Beschreibung	Beispiel
`PORT`	Der Port, den Ihr HTTP-Server beobachten soll.	`8080`
`K_SERVICE`	Der Name des ausgeführten Cloud Run-Dienstes.	`hello-world`
`K_REVISION`	Der Name der ausgeführten Cloud Run-Überarbeitung.	`hello-world.1`
`K_CONFIGURATION`	Der Name der Cloud Run-Konfiguration, mit der die Überarbeitung erstellt wurde.	`hello-world`

Umgebungsvariablen für Jobs

Für Cloud Run-Jobs werden folgende Umgebungsvariablen festgelegt:

Name	Beschreibung	Beispiel
`CLOUD_RUN_JOB`	Der Name des ausgeführten Cloud Run-Jobs.	`hello-world`
`CLOUD_RUN_EXECUTION`	Der Name der ausgeführten Cloud Run-Ausführung.	`hello-world-abc`
`CLOUD_RUN_TASK_INDEX`	Der Index dieser Aufgabe. Beginnt mit 0 für die erste Aufgabe und wird bei jeder nachfolgenden Aufgabe um 1 erhöht, bis zur maximalen Anzahl an Aufgaben minus 1. Wenn Sie `--parallelism` auf einen größeren Wert als 1 festlegen, folgen Aufgaben möglicherweise nicht der Indexreihenfolge. Zum Beispiel kann Aufgabe 2 vor Aufgabe 1 beginnen.	`0`
`CLOUD_RUN_TASK_ATTEMPT`	Die Anzahl der Ausführungsversuche für diese Aufgabe. Beginnt mit 0 für den ersten Versuch und wird bei jedem weiteren Wiederholungsversuch um 1 erhöht, bis zum maximalen Wiederholungswert.	`0`
`CLOUD_RUN_TASK_COUNT`	Die Zahl der Aufgaben, die im Parameter `--tasks` definiert sind.	`1`

Anforderungen an Anfrage- und Antwortheader (Dienste)

Bei Cloud Run-Diensten sind Headernamen auf druckbare ASCII-Zeichen außer Leerzeichen beschränkt und dürfen keine Doppelpunkte enthalten. Headerwerte sind gemäß IETF RFC 7230 auf sichtbare ASCII-Zeichen plus Leerzeichen und horizontaler Tabulator beschränkt.

Dateisystemzugriff

Das Dateisystem in jedem Ihrer Container ist beschreibbar und unterliegt dem folgenden Verhalten:

Da es sich um ein speicherinternes Dateisystem handelt, wird beim Schreiben der Arbeitsspeicher der Instanz verwendet.
In das Dateisystem geschriebene Daten gehen verloren, wenn die Instanz beendet wird.

Beachten Sie, dass Sie keine Größenbeschränkung für dieses Dateisystem festlegen können. Sie können also möglicherweise den gesamten Ihrer Instanz zugewiesenen Speicher nutzen, indem Sie in das speicherinterne Dateisystem schreiben. Dies führt zu einem Absturz der Instanz. Sie können dieses Problem vermeiden, indem Sie ein dediziertes In-Memory-Volume mit einer Größenbeschränkung verwenden.

Lebenszyklus von Instanzen

Die Lebenszykluseigenschaften für Cloud Run-Jobs und -Dienste unterscheiden sich. Entsprechend werden sie in den folgenden Unterabschnitten separat beschrieben.

Für Dienste

Folgendes gilt nur für Dienste.

Dienstskalierung

Ein Cloud Run-Dienst wird automatisch auf die Anzahl der Instanzen skaliert, die zum Verarbeiten aller eingehenden Anfragen, Ereignisse oder der CPU-Auslastung erforderlich sind.

Jede Instanz führt eine feste Anzahl an Containern aus: einen Ingress-Container und optional einen oder mehrere Sidecar-Container.

Wenn eine Überarbeitung keinen Traffic empfängt, wird sie auf die konfigurierte Mindestanzahl von Containerinstanzen herunterskaliert (standardmäßig null).

Starten

Bei Cloud Run-Diensten müssen Ihre Instanzen innerhalb von vier Minuten nach dem Start auf Anfragen überwachen und alle Container innerhalb der Instanz müssen fehlerfrei sein. Während dieser Startzeit wird den Instanzen CPU zugewiesen. Sie können den CPU-Boost beim Start aktivieren, um die CPU-Zuweisung während des Starts einer Instanz vorübergehend zu erhöhen und damit die Startlatenz zu reduzieren.

Anfragen werden an den Ingress-Container gesendet, sobald er den konfigurierten Port überwacht.

Eine Anfrage, die auf eine Instanz wartet, wird so in einer Warteschlange aufbewahrt:

Wenn neue Instanzen gestartet werden, z. B. während einer horizontalen Skalierung, bleiben Anfragen mindestens für die durchschnittliche Startzeit von Containerinstanzen dieses Dienstes ausstehend. Dies gilt auch, wenn die Anfrage ein Hochskalieren initiiert, z. B. bei einer Skalierung von null.
Wenn die Startzeit weniger als 10 Sekunden beträgt, bleiben Anfragen bis zu 10 Sekunden ausstehend.
Wenn keine Instanzen beim Start vorhanden sind und die Anfrage keine horizontale Skalierung initiiert, bleiben Anfragen bis zu 10 Sekunden lang ausstehend.

Sie können eine Startprüfung konfigurieren, um festzustellen, ob der Container gestartet wurde und bereit ist, Anfragen zu verarbeiten.

Bei einem Cloud Run-Dienst, der aus Multi-Container-Instanzen besteht, können Sie die Reihenfolge angeben, in der die Container innerhalb der Instanz gestartet werden. Dazu konfigurieren Sie die Containerstartreihenfolge.

Anfrage verarbeiten

Bei Cloud Run-Diensten wird die CPU immer allen Containern, einschließlich Sidecar-Dateien, innerhalb einer Instanz zugewiesen, solange die Cloud Run-Überarbeitung mindestens eine Anfrage verarbeitet.

Inaktiv

Bei Cloud Run-Diensten ist eine inaktive Instanz eine, die keine Anfragen verarbeitet.

Die CPU, die allen Containern in einer inaktiven Instanz zugewiesen wird, hängt von der konfigurierten CPU-Zuweisung ab.

Eine Instanz ist nicht länger als 15 Minuten inaktiv, es sei denn, sie muss aufgrund der Konfigurationseinstellung für die Mindestzahl von Instanzen inaktiv sein.

Herunterfahren

Bei Cloud Run-Diensten kann eine inaktive Instanz jederzeit heruntergefahren werden. Das gilt auch für Instanzen, die über eine Mindestanzahl an Instanzen einsatzbereit gehalten werden. Wenn eine Instanz, die Anfragen verarbeitet, heruntergefahren werden muss, werden neue eingehende Anfragen an andere Instanzen weitergeleitet und die derzeit verarbeiteten Anfragen erhalten Zeit, um abgeschlossen zu werden. In Ausnahmefällen kann Cloud Run ein Herunterfahren initiieren und ein SIGTERM-Signal an einen Container senden, der noch Anfragen verarbeitet.

Bevor Sie eine Instanz herunterfahren, sendet Cloud Run ein SIGTERM-Signal an alle Container in einer Instanz, das den Beginn eines Zeitraums von 10 Sekunden vor dem tatsächlichen Herunterfahren angibt. An diesem Punkt sendet Cloud Run ein SIGKILL-Signal In diesem Zeitraum wird der Instanz CPU zugewiesen und in Rechnung gestellt. Wenn die Instanz bei Diensten, die die Ausführungsumgebung der ersten Generation verwenden, das SIGTERM-Signal nicht einfängt, wird sie sofort heruntergefahren. (In den Codebeispielen erfahren Sie, wie Sie das SIGTERM-Signal einfangen.)

Erzwungene Beendigung

Wenn ein oder mehrere Cloud Run-Container das Speicherlimit für den gesamten Container überschreiten, wird die Instanz beendet. Alle Anfragen, die noch auf der Instanz verarbeitet werden, werden mit dem Fehler HTTP 500 beendet.

Für Jobs

Bei Cloud Run-Jobs werden Containerinstanzen so lange ausgeführt, bis die Containerinstanz beendet wird, das Zeitlimit für Aufgaben erreicht ist oder der Container abstürzt.

Erzwungene Beendigung

Eine Cloud Run-Containerinstanz, die das zulässige Arbeitsspeicherlimit überschreitet, wird beendet. Alle Anfragen, die noch auf der Containerinstanz verarbeitet werden, enden mit dem Fehler HTTP 500.

Wenn eine Aufgabe das Zeitlimit für Aufgaben überschreitet, sendet Cloud Run ein "SIGTERM"-Signal, das den Start eines 10-Sekunden-Zeitraums vor dem tatsächlichen Herunterfahren bedeutet. Cloud Run sendet dann ein SIGKILL-Signal, mit dem die Containerinstanz heruntergefahren wird.

Während dieses Zeitraums wird Containerinstanzen für ihren gesamten Lebenszyklus eine CPU zugewiesen, die auch in Rechnung gestellt wird.

Weitere Informationen zum Einfangen des SIGTERM-Signals finden Sie im SIGTERM-Codebeispiel.

Containerinstanzressourcen

CPU

Jedem Cloud Run-Container in einer Instanz wird standardmäßig die vCPU zugewiesen, die konfiguriert wurde (Standard: 1). CPU-Limits können für jeden Container separat konfiguriert werden.

Eine vCPU ist als Abstraktion einer zugrunde liegenden Hardware implementiert, um deren ungefähre CPU-Zeit für einen einzelnen Hardware-Hyper-Thread auf variablen CPU-Plattformen bereitzustellen. Alle von Cloud Run verwendeten CPU-Plattformen unterstützen den Befehl AVX2. Beachten Sie, dass der Containervertrag keine weiteren CPU-Plattformdetails enthält.

Der Container kann auf mehreren Kernen gleichzeitig ausgeführt werden.

Bei Cloud Run-Diensten können Sie festlegen, ob die CPU immer während der Lebensdauer der Instanz oder nur während des Starts und der Verarbeitung der Instanz zugewiesen wird. Weitere Informationen finden Sie unter CPU-Zuweisung.

Wenn Sie eine Reihe von Mindestinstanzen konfiguriert haben, unterliegen diese Instanzen auch der Konfiguration der CPU-Zuweisung.

Sie können den CPU-Boost beim Start aktivieren, um die CPU-Zuweisung während des Starts einer Instanz vorübergehend zu erhöhen und damit die Startlatenz zu reduzieren.

Speicher

Jeder Cloud Run-Container wird standardmäßig der konfigurierte Speicher zugewiesen (standardmäßig 512 MiB). Speicherlimits können für jeden Container separat konfiguriert werden.

Typische Einsatzmöglichkeiten des Speichers:

Code in Speicher laden, um den Dienst auszuführen
In das Dateisystem schreiben
Zusätzliche Containerprozesse ausführen, z. B. einen Nginx-Server
Speicherinterne Caching-Systeme wie OpCache
Speichernutzung pro Anfrage
Geteilte In-Memory-Volumes

GPU

Sie können einen Container in einer Cloud Run-Instanz so konfigurieren, dass er auf eine GPU zugreift. Wenn der Cloud Run-Dienst mit Sidecar-Containern bereitgestellt wird, kann nur ein Container in der Bereitstellung auf die GPU zugreifen. Anforderungen und Details finden Sie unter GPU konfigurieren.

NVIDIA-Bibliotheken

Standardmäßig werden alle NVIDIA L4-Treiberbibliotheken unter /usr/local/nvidia/lib64 bereitgestellt.

Wenn Ihr Dienst die bereitgestellten Bibliotheken nicht finden kann, aktualisieren Sie den Suchpfad für den dynamischen Linker, indem Sie der Dockerfile die Zeile ENV LD_LIBRARY_PATH /usr/local/nvidia/lib64:${LD_LIBRARY_PATH} hinzufügen.

Sie können LD_LIBRARY_PATH auch als Umgebungsvariable für den Cloud Run-Dienst festlegen, wenn Sie ein vorhandenes Image haben und es nicht mit einem aktualisierten Dockerfile neu erstellen möchten.

Wenn Sie eine CUDA-Version höher als 12.2 verwenden möchten, ist es am einfachsten, von einem neueren NVIDIA-Basis-Image abzuhängen, auf dem bereits Pakete für die Aufwärtskompatibilität installiert sind. Eine weitere Möglichkeit besteht darin, die NVIDIA-Pakete für die Aufwärtskompatibilität manuell zu installieren und sie zu LD_LIBRARY_PATH hinzuzufügen. Sehen Sie sich die Kompatibilitätsmatrix von NVIDIA an, um zu ermitteln, welche CUDA-Versionen mit der bereitgestellten NVIDIA-Treiberversion (535.129.03) aufwärtskompatibel sind.

Gleichzeitigkeit (Dienste)

Bei Cloud Run-Diensten ist jede Cloud Run-Instanz standardmäßig auf Gleichzeitigkeit festgelegt, wobei der Ingress-Container mehr als eine Anfrage gleichzeitig empfangen kann. Sie können dies ändern, indem Sie die Nebenläufigkeit festlegen.

Container-Sandbox

Wenn Sie die Ausführungsumgebung der ersten Generation verwenden, werden die Cloud Run-Container in der gVisor-Containerlaufzeit-Sandbox ausgeführt. Wie in der Referenz zur gVisor-syscall-Kompatibilität dokumentiert, werden einige Systemaufrufe möglicherweise von dieser Container-Sandbox nicht unterstützt.

Wenn Sie die Ausführungsumgebung der zweiten Generation verwenden, ist Ihre Linux-Kompatibilität vollständig. Cloud Run-Jobs verwenden immer die Ausführungsumgebung der zweiten Generation. In der Ausführungsumgebung der zweiten Generation ist /sys/class/dmi/id/product_name auf Google Compute Engine gesetzt.

Die Ausführungsumgebung der zweiten Generation führt Ihren Dienstcode in einem separaten Prozess-Namespace aus, sodass er mit dem Container-init-Prozess beginnt, der eine spezielle Prozesssemantik hat. In der Ausführungsumgebung der ersten Generation wird der Dienstcode nicht als Container-Initialisierungsvorgang ausgeführt.

Metadatenserver der Instanz

Cloud Run-Instanzen stellen einen Metadatenserver bereit, mit dem Sie Details zu Ihren Containern abrufen können, z. B. Projekt-ID, Region, Instanz-ID oder Dienstkonten. Sie können den Metadatenserver auch verwenden, um Tokens für die Dienstidentität zu generieren.

Für den Zugriff auf Metadatenserver-Daten verwenden Sie HTTP-Anfragen an den Endpunkt http://metadata.google.internal/ mit dem Header Metadata-Flavor: Google. Es sind keine Clientbibliotheken erforderlich. Weitere Informationen finden Sie unter Metadaten abrufen.

In der folgenden Tabelle sind einige der verfügbaren Metadatenserver-Informationen aufgeführt:

Pfad	Beschreibung
`/computeMetadata/v1/project/project-id`	Projekt-ID des Projekts, zu dem der Cloud Run-Dienst oder -Job gehört
`/computeMetadata/v1/project/numeric-project-id`	Projektnummer des Projekts, zu dem der Cloud Run-Dienst oder -Job gehört
`/computeMetadata/v1/instance/region`	Region dieses Cloud Run-Dienstes oder -Jobs, gibt `projects/PROJECT-NUMBER/regions/REGION` zurück
`/computeMetadata/v1/instance/id`	Eindeutige Kennung der Instanz (auch in Logs verfügbar).
`/computeMetadata/v1/instance/service-accounts/default/email`	E-Mail für die Dienstidentität dieses Cloud Run-Dienstes oder Jobs.
`/computeMetadata/v1/instance/service-accounts/default/token`	Generiert ein OAuth2-Zugriffstoken für das Dienstkonto dieses Cloud Run-Dienstes oder -Jobs. Der Cloud Run-Dienst-Agent wird zum Abrufen eines Tokens verwendet. Dieser Endpunkt gibt eine JSON-Antwort mit einem `access_token`-Attribut zurück. Weitere Informationen zum Extrahieren und Verwenden dieses Zugriffstokens

Cloud Run erteilt keine Informationen darüber, in welcher Google Cloud-Zone die Instanzen ausgeführt werden. Daher gibt das Metadatenattribut /computeMetadata/v1/instance/zone immer projects/PROJECT-NUMBER/zones/REGION-1 zurück.

Dateinamen

Die in Containern verwendeten Dateinamen müssen UTF-8-kompatibel sein; entweder UTF-8 oder ein Format, das sicher automatisch in UTF-8 konvertiert werden kann. Wenn Ihre Dateinamen unterschiedliche Codierungen verwenden, führen Sie den Docker-Build auf einem Computer mit UTF-8-kompatiblen Dateinamen aus. Vermeiden Sie das Kopieren von Dateien in einen Container, der inkompatible UTF-8-Namen enthält.

Die Container-Bereitstellung schlägt fehl, wenn Dateinamen nicht UTF-8-kompatibel sind. Beachten Sie, dass es keine Beschränkung für die Zeichencodierung gibt, die Sie in einer Datei verwenden.

Ausgehende Verbindungen

Zeitlimits für ausgehende Anfragen

Bei Cloud Run-Diensten und -Jobs tritt nach 10 Minuten Inaktivität Zeit für Anfragen von Ihrem Container an die VPC auf. Bei Anfragen von Ihrem Container an das Internet kommt es nach 20 Minuten Inaktivität zu einer Zeitüberschreitung.

Ausgehende Verbindungen werden zurückgesetzt

Verbindungsstreams von Ihrem Container zu VPC und dem Internet können gelegentlich beendet und ersetzt werden, wenn die zugrunde liegende Infrastruktur neu gestartet oder aktualisiert wird. Wenn Ihre Anwendung langlebige Verbindungen wiederverwendet, sollten Sie Ihre Anwendung so konfigurieren, dass Verbindungen wiederhergestellt werden, um eine Wiederverwendung einer inaktiven Verbindung zu vermeiden.