Contrat d'exécution du conteneur

Cette page répertorie les exigences et les comportements clés des conteneurs dans Cloud Run. Il existe quelques différences entre les services Cloud Run et les tâches Cloud Run : ces dernières sont appelées le cas échéant.

Langages et images acceptés

Votre image de conteneur peut exécuter du code écrit dans le langage de programmation de votre choix et utiliser n'importe quelle image de base, à condition de respecter les contraintes présentées sur cette page.

Les fichiers exécutables dans l'image de conteneur doivent être compilés pour Linux 64 bits. Cloud Run est spécifiquement compatible avec le format ABI de Linux x86_64.

Cloud Run accepte les images de conteneur aux formats d'image Docker Image Manifest V2, Schéma 1, Schéma 2 et OCI. Cloud Run accepte également les images de conteneurs compressées Zstd.

Si vous déployez une image multi-architecture, la liste de fichiers manifestes doit inclure linux/amd64.

Pour les fonctions déployées avec Cloud Run, vous pouvez utiliser l'une des images de base de l'environnement d'exécution Cloud Run publiées par les buildpacks de Google Cloud pour recevoir des mises à jour de sécurité et de maintenance automatiques. Consultez le calendrier de compatibilité des environnements d'exécution pour connaître les environnements d'exécution compatibles.

Écouter les requêtes sur le port approprié (services)

Un service Cloud Run démarre des instances Cloud Run pour gérer les requêtes entrantes. Une instance Cloud Run comporte toujours un seul conteneur d'entrée qui écoute les requêtes et éventuellement un ou plusieurs conteneurs side-car. Les informations de configuration de port suivantes ne s'appliquent qu'au conteneur d'entrée, et non aux side-cars.

Le conteneur d'entrée dans une instance doit écouter les requêtes envoyées à l'adresse 0.0.0.0, sur le port auquel ces requêtes sont envoyées. Par défaut, les requêtes sont envoyées à 8080, mais vous pouvez configurer Cloud Run pour envoyer des requêtes au port de votre choix. Cloud Run injecte la variable d'environnement PORT dans le conteneur d'entrée.

Le conteneur s'exécutant dans le cadre d'une tâche doit se fermer une fois l'opération terminée

Pour les tâches Cloud Run, le conteneur doit se fermer avec le code de sortie "0" si la tâche s'est terminée correctement et avec un code de sortie différent de zéro en cas d'échec de la tâche.

Étant donné que les tâches ne doivent pas publier de requêtes, le conteneur ne doit pas écouter sur un port ni démarrer de serveur Web.

Chiffrement de la couche de transport (TLS)

Le conteneur ne doit pas mettre en œuvre directement de sécurité de la couche de transport. TLS est interrompu par Cloud Run dans le cas de HTTPS et gRPC, puis les requêtes sont transmises par proxy via HTTP/1 ou gRPC au conteneur sans TLS.

Si vous configurez un service Cloud Run pour qu'il utilise HTTP/2 de bout en bout, votre conteneur doit gérer les requêtes au format texte clair HTTP/2 (h2c), car TLS est toujours arrêté automatiquement par Cloud Run.

Réponses (services)

Pour les services Cloud Run, votre instance doit envoyer une réponse dans le délai spécifié par le paramètre de délai avant expiration de la requête après la réception d'une requête, y compris le délai de démarrage de l'instance. Sinon, la requête est abandonnée et une erreur 504 est renvoyée.

Mise en cache des réponses et cookies

Si la réponse de votre service Cloud Run contient un en-tête Set-Cookie, Cloud Run définit l'en-tête Cache-Control sur private afin que la réponse ne soit pas mise en cache. Cela empêche les autres utilisateurs de récupérer le cookie.

Variables d'environnement

Différents ensembles de variables d'environnement sont disponibles pour les services et les tâches Cloud Run.

Variables d'environnement pour les services

Les variables d'environnement suivantes sont automatiquement ajoutées à tous les conteneurs en cours d'exécution, à l'exception de PORT. La variable PORT n'est ajoutée qu'au conteneur d'entrée :

Nom	Description	Exemple
`PORT`	Port sur lequel le serveur HTTP doit écouter.	`8080`
`K_SERVICE`	Nom du service Cloud Run en cours d'exécution.	`hello-world`
`K_REVISION`	Nom de la révision Cloud Run en cours d'exécution.	`hello-world.1`
`K_CONFIGURATION`	Nom de la configuration Cloud Run ayant créé la révision.	`hello-world`

Variables d'environnement pour les tâches

Pour les tâches Cloud Run, les variables d'environnement suivantes sont définies :

Nom	Description	Exemple
`CLOUD_RUN_JOB`	Nom de la tâche Cloud Run en cours d'exécution.	`hello-world`
`CLOUD_RUN_EXECUTION`	Nom de l'exécution Cloud Run en cours d'exécution.	`hello-world-abc`
`CLOUD_RUN_TASK_INDEX`	Index de cette tâche. Démarre à 0 pour la première tâche, puis incrémente de 1 pour chaque nouvelle tâche, jusqu'à atteindre le nombre maximal de tâches moins 1. Si vous définissez `--parallelism` sur une valeur supérieure à 1, les tâches risquent de ne pas suivre l'ordre des index. Par exemple, il est possible que la tâche 2 démarre avant la tâche 1.	`0`
`CLOUD_RUN_TASK_ATTEMPT`	Nombre de fois où une tâche a fait l'objet de nouvelles tentatives d'exécution. Démarre à 0 pour la première tentative, puis incrémente de 1 pour chaque nouvelle tentative, jusqu'à atteindre le nombre maximal de tentatives.	`0`
`CLOUD_RUN_TASK_COUNT`	Nombre de tâches définies dans le paramètre `--tasks`.	`1`

Exigences relatives aux en-têtes de requête et de réponse (services)

Pour les services Cloud Run, les noms d'en-tête sont limités aux caractères ASCII imprimables, sans espace blanc, et ne peuvent pas contenir de signes deux-points. Valeurs limitées aux caractères ASCII visibles, espace et tabulation horizontale conformément à la norme IETF RFC 7230

Accès au système de fichiers

Le système de fichiers de chacun de vos conteneurs est accessible en écriture et obéit au comportement suivant :

Il s'agit d'un système de fichiers en mémoire. Par conséquent, les opérations d'écriture sur ce système de fichiers utilisent la mémoire de l'instance.
Les données écrites dans le système de fichiers ne persistent pas lorsque l'instance est arrêtée.

Notez que vous ne pouvez pas spécifier de limite de taille pour ce système de fichiers. Vous pouvez donc potentiellement utiliser toute la mémoire allouée à votre instance en écrivant dans le système de fichiers en mémoire, ce qui entraînerait le plantage de l'instance. Vous pouvez éviter ce problème si vous utilisez un volume en mémoire dédié avec une limite de taille.

Cycle de vie de l'instance

Les caractéristiques du cycle de vie diffèrent pour les tâches et les services Cloud Run. Elles sont donc décrites individuellement dans les sous-sections suivantes.

Pour les services

Les éléments suivants s'appliquent uniquement aux services.

Scaling de services

Un service Cloud Run est automatiquement adapté au nombre d'instances nécessaires pour gérer toutes les requêtes entrantes, tous les événements ou l'utilisation du processeur.

Chaque instance exécute un nombre fixe de conteneurs : un conteneur d'entrée et éventuellement un ou plusieurs conteneurs side-car.

Lorsqu'une révision ne reçoit aucun trafic, elle subit un scaling vertical à hauteur du nombre minimal d'instances configurées (zéro par défaut).

Démarrage

Pour les services Cloud Run, vos instances doivent écouter les requêtes dans les quatre minutes suivant leur démarrage et tous les conteneurs de l'instance doivent être opérationnels. Pendant ce temps de démarrage, le processeur est alloué aux instances. Vous pouvez activer l'optimisation du processeur au démarrage afin d'augmenter temporairement l'allocation de processeur lors du démarrage de l'instance et ainsi de réduire la latence de démarrage.

Les requêtes seront envoyées au conteneur d'entrée dès qu'il écoute sur le port configuré.

Une requête en attente d'une instance est conservée dans une file d'attente comme suit :

Si les nouvelles instances démarrent, par exemple lors d'une évolutivité horizontale, les requêtes seront mises en attente pendant au moins le temps de démarrage moyen des instances de conteneur de ce service. Cela inclut le moment où la requête lance un scaling horizontal, par exemple lors d'un scaling à partir de zéro.
Si le temps de démarrage est inférieur à 10 secondes, les requêtes sont mises en attente pendant une durée maximale de 10 secondes.
Si aucune instance n'est en cours de démarrage et que la requête n'initie pas de scaling horizontal, les requêtes seront mises en attente pendant une durée maximale de 10 secondes.

Vous pouvez configurer une vérification de démarrage pour déterminer si le conteneur a démarré et est prêt à diffuser des requêtes.

Pour un service Cloud Run composé d'instances multiconteneurs, vous pouvez spécifier la séquence dans laquelle les conteneurs sont démarrés dans l'instance en configurant l'ordre de démarrage des conteneurs.

Traiter une requête

Pour les services Cloud Run, le processeur est toujours alloué à tous les conteneurs, y compris aux side-cars d'une instance, tant que la révision Cloud Run traite au moins une requête.

Inactif

Pour les services Cloud Run, une instance inactive est une instance qui ne traite aucune requête.

Le processeur alloué à tous les conteneurs d'une instance inactive dépend de l'allocation du processeur configurée.

À moins qu'une instance ne soit désactivée en raison du paramètre de nombre minimal d'instances défini, elle ne restera pas inactive pendant plus de 15 minutes.

Arrêt

Pour les services Cloud Run, une instance inactive peut être arrêtée à tout moment, y compris les instances maintenues en veille via le paramètre "nombre minimal d'instances". Si une instance qui traite des requêtes doit être arrêtée, les nouvelles requêtes entrantes sont acheminées vers d'autres instances et les requêtes en cours de traitement bénéficient d'un temps suffisant pour se terminer. Dans des cas exceptionnels, Cloud Run peut déclencher un arrêt et envoyer un signal SIGTERM à un conteneur qui traite toujours des requêtes.

Avant d'arrêter une instance, Cloud Run envoie un signal SIGTERM à tous les conteneurs d'une instance, indiquant le début de la période de 10 secondes avant l'arrêt réel marqué par l'envoi d'un signal SIGKILL par Cloud Run. Au cours de cette période, l'instance se voit attribuer un ou plusieurs processeurs et est facturée. Dans les services qui utilisent l'environnement d'exécution de première génération, si l'instance ne capture pas le signal SIGTERM, elle est immédiatement arrêtée. (Consultez les exemples de code pour apprendre à intercepter le signal SIGTERM.)

Arrêt forcé

Si un ou plusieurs conteneurs Cloud Run dépassent la limite de mémoire totale des conteneurs, l'instance est arrêtée. Toutes les requêtes en cours de traitement sur l'instance se terminent avec une erreur HTTP 500.

Pour les tâches

Pour les tâches Cloud Run, les instances de conteneur s'exécutent jusqu'à leur fermeture, ou jusqu'à ce que le délai avant expiration de la tâche soit atteint ou jusqu'au plantage du conteneur.

Arrêt forcé

Une instance de conteneur Cloud Run dépassant la limite de mémoire autorisée est arrêtée. Toutes les requêtes en cours de traitement sur l'instance de conteneur se terminent avec une erreur HTTP 500.

Si une tâche dépasse le délai avant expiration de la tâche, Cloud Run envoie un signal "SIGTERM" indiquant le début d'une période de 10 secondes avant l'arrêt réel, moment où Cloud Run envoie un signal SIGKILL provoquant l'arrêt de l'instance de conteneur.

Au cours de cette période, les instances de conteneur sont affectées à des processeurs pour tout leur cycle de vie et sont facturées.

Consultez l'exemple de code SIGTERM pour apprendre à intercepter le signal SIGTERM.

Ressources d'instance de conteneur

Processeur

Chaque conteneur Cloud Run d'une instance se voit attribuer par défaut le vCPU qui a été configuré (1 par défaut). Il est possible de configurer les limites de processeur séparément sur chaque conteneur.

Un processeur virtuel est mis en œuvre sous la forme d'une abstraction de matériel sous-jacent pour fournir le temps CPU équivalent d'un seul hyper-thread matériel sur des plates-formes de processeur variables. Toutes les plates-formes de processeur utilisées par Cloud Run sont compatibles avec l'ensemble d'instructions AVX2. Notez que le contrat du conteneur ne contient aucune information supplémentaire sur la plate-forme de processeur.

Le conteneur peut être exécuté simultanément sur plusieurs cœurs.

Pour les services Cloud Run, vous pouvez spécifier que le processeur doit toujours être alloué pendant la durée de vie de l'instance ou qu'il ne doit être alloué qu'au démarrage de l'instance et lors du traitement des requêtes. Pour en savoir plus, consultez la section Allocation de processeur.

Si vous avez configuré un certain nombre d'instances minimales, ces instances sont également soumises à la configuration d'allocation de processeur.

Vous pouvez activer l'optimisation du processeur au démarrage afin d'augmenter temporairement l'allocation de processeur lors du démarrage de l'instance et ainsi de réduire la latence de démarrage.

Mémoire

Chaque instance Cloud Run reçoit par défaut la mémoire configurée (512 Mio par défaut). Il est possible de configurer les limites de mémoire séparément sur chaque conteneur.

Les utilisations types de la mémoire sont les suivantes :

Code chargé dans la mémoire pour exécuter le service
Écriture des données dans le système de fichiers
Processus supplémentaires exécutés dans le conteneur, tel qu'un serveur nginx
Systèmes de mise en cache en mémoire tels que l'OpCache PHP
Utilisation de mémoire par requête
Volumes en mémoire partagés

GPU

Vous pouvez configurer un conteneur dans une instance Cloud Run pour qu'il accède à un GPU. Si le service Cloud Run est déployé avec des conteneurs side-car, un seul conteneur du déploiement peut accéder au GPU. Pour connaître les exigences et obtenir plus d'informations, consultez la page Configurer le GPU.

Bibliothèques NVIDIA

Par défaut, toutes les bibliothèques de pilotes NVIDIA L4 sont montées sous /usr/local/nvidia/lib64.

Si votre service ne parvient pas à trouver les bibliothèques fournies, mettez à jour le chemin de recherche de l'éditeur de lien dynamique en ajoutant la ligne ENV LD_LIBRARY_PATH /usr/local/nvidia/lib64:${LD_LIBRARY_PATH} à votre fichier Dockerfile.

Notez que vous pouvez également définir LD_LIBRARY_PATH comme variable d'environnement pour le service Cloud Run si vous disposez d'une image existante et que vous ne souhaitez pas la recréer avec un fichier Dockerfile mis à jour.

Si vous souhaitez utiliser une version de CUDA supérieure à 12.2, le moyen le plus simple consiste à utiliser une image de base NVIDIA plus récente avec des packages de rétrocompatibilité déjà installés. Vous pouvez également installer manuellement les packages de compatibilité ascendante de NVIDIA et les ajouter à LD_LIBRARY_PATH. Consultez la matrice de compatibilité de NVIDIA pour déterminer quelles versions de CUDA sont compatibles avec la version du pilote NVIDIA fournie (535.129.03).

Simultanéité (services)

Pour les services Cloud Run, chaque instance Cloud Run est définie par défaut sur simultanéité multiple, où le conteneur d'entrée peut recevoir plusieurs requêtes en même temps. Vous pouvez modifier ce paramètre en définissant la simultanéité.

Bac à sable de conteneur

Si vous utilisez l'environnement d'exécution de première génération, les conteneurs Cloud Run sont exécutés dans le bac à sable d'exécution gVisor. Comme indiqué dans la documentation de référence sur la compatibilité des appels système gVisor, certains appels système peuvent ne pas être compatibles avec ce bac à sable de conteneur.

Si vous utilisez l'environnement d'exécution de deuxième génération, vous disposez d'une compatibilité Linux complète. Les tâches Cloud Run utilisent toujours l'environnement d'exécution de deuxième génération. Dans l'environnement d'exécution de deuxième génération, /sys/class/dmi/id/product_name est défini sur Google Compute Engine.

L'environnement d'exécution de deuxième génération exécute le code de votre service dans un espace de noms de processus distinct. Il commence donc par le processus d'initialisation du conteneur présentant une sémantique de processus spéciale. Dans l'environnement d'exécution de première génération, le code de votre service ne s'exécute pas en tant que processus d'initialisation du conteneur.

Serveur de métadonnées d'instance

Les instances Cloud Run exposent un serveur de métadonnées que vous pouvez utiliser pour récupérer des informations sur vos conteneurs, telles que l'ID de projet, la région, l'ID d'instance ou les comptes de service. Vous pouvez également utiliser le serveur de métadonnées pour générer des jetons pour l'identité du service.

Pour accéder aux données du serveur de métadonnées, envoyez des requêtes HTTP au point de terminaison http://metadata.google.internal/ avec l'en-tête Metadata-Flavor: Google : aucune bibliothèque cliente n'est requise. Pour en savoir plus, consultez la section Obtenir des métadonnées.

Le tableau suivant répertorie certaines des informations sur le serveur de métadonnées disponibles :

Chemin	Description
`/computeMetadata/v1/project/project-id`	ID du projet auquel appartient la tâche ou le service Cloud Run.
`/computeMetadata/v1/project/numeric-project-id`	Numéro du projet auquel appartient la tâche ou le service Cloud Run.
`/computeMetadata/v1/instance/region`	Région de cette tâche ou de ce service Cloud Run, renvoie `projects/PROJECT-NUMBER/regions/REGION`.
`/computeMetadata/v1/instance/id`	Identifiant unique de l'instance (également disponible dans les journaux).
`/computeMetadata/v1/instance/service-accounts/default/email`	Adresse e-mail de l'identité de service de ce job ou de ce service Cloud Run.
`/computeMetadata/v1/instance/service-accounts/default/token`	Génère un jeton d'accès OAuth2 pour le compte de service de cette tâche ou de ce service Cloud Run. L'agent de service Cloud Run est utilisé pour récupérer un jeton. Ce point de terminaison renverra une réponse JSON avec un attribut `access_token`. Obtenez davantage d'informations sur l'extraction et l'utilisation de ce jeton d'accès.

Notez que Cloud Run ne fournit pas de détails sur la zone Google Cloud dans laquelle les instances sont en cours d'exécution. Par conséquent, l'attribut de métadonnées /computeMetadata/v1/instance/zone renvoie toujours projects/PROJECT-NUMBER/zones/REGION-1.

Noms des fichiers

Les noms de fichiers que vous utilisez dans des conteneurs doivent être compatibles avec UTF-8, ou être convertis en UTF-8 en toute sécurité. Si vos noms de fichiers utilisent différents encodages, exécutez Docker Build sur une machine avec des noms de fichiers compatibles avec UTF-8 et évitez de copier des fichiers dans un conteneur contenant des noms UTF-8 incompatibles.

Le déploiement du conteneur échoue si les noms de fichiers ne sont pas compatibles avec UTF-8. Notez que le codage des caractères que vous utilisez dans un fichier n'est soumis à aucune limite.

Connexions sortantes

Délais avant expiration des requêtes sortantes

Pour les services et les jobs Cloud Run, un délai avant expiration s'applique après 10 minutes d'inactivité aux requêtes provenant de votre conteneur vers un VPC. Pour les requêtes provenant de votre conteneur vers Internet, le délai avant expiration est écoulé après 20 minutes d'inactivité.

Réinitialisation des connexions sortantes

Les flux de connexion de votre conteneur vers un VPC et Internet peuvent parfois être arrêtés et remplacés lorsque l'infrastructure sous-jacente est redémarrée ou mise à jour. Si votre application réutilise des connexions à longue durée de vie, nous vous recommandons de configurer votre application de manière à rétablir les connexions afin d'éviter la réutilisation d'une connexion interrompue.