Contrat d'exécution du conteneur

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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.

Les listes de manifestes utilisées pour les images multi-architectures ne sont pas acceptées.

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

Pour les services Cloud Run, le conteneur 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. Dans les instances de conteneur Cloud Run, la valeur de la variable d'environnement PORT correspond toujours au port auquel les requêtes sont envoyées. Sa valeur par défaut est 8080.

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 de conteneur 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 de conteneur. Sinon, la requête est abandonnée et une erreur 504 est renvoyée.

Environment variables

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 aux conteneurs en cours d'exécution :

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 Pour chaque tâche, la valeur définie sera une valeur unique comprise entre 0 et le nombre de tâches moins 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 votre conteneur 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 de conteneur.
  • Les données écrites dans le système de fichiers ne persistent pas lorsque l'instance de conteneur est arrêtée.

Cycle de vie de l'instance de conteneur

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

Pour les services Cloud Run, en réponse aux requêtes entrantes, un service subit automatiquement un scaling horizontal à hauteur d'un certain nombre d'instances de conteneurs, chacune exécutant l'image de conteneur déployée.

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

Démarrage

Pour les services Cloud Run, vos instances de conteneur doivent écouter les requêtes dans les quatre minutes suivant leur démarrage. Pendant ce temps de démarrage, le processeur est alloué aux instances de conteneur. 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 de conteneur et ainsi de réduire la latence de démarrage.

Les requêtes seront envoyées à l'instance de conteneur dès qu'elle écoute sur le port configuré.

Une requête en attente du démarrage d'une instance de conteneur est conservée dans une file d'attente pendant 10 secondes au maximum.

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.

Traiter une requête

Pour les services Cloud Run, le processeur est toujours alloué lorsque l'instance de conteneur traite au moins une requête.

Inactif

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

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

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

Arrêt

Pour les services Cloud Run, une instance de conteneur 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 de conteneur 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.

Avant d'arrêter une instance de conteneur, Cloud Run envoie un signal SIGTERM qui indique 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 de conteneur se voit attribuer un ou plusieurs processeurs et est facturée. Si l'instance de conteneur n'intercepte 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é

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.

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. Si l'instance de conteneur n'intercepte 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é

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.

Ressources d'instance de conteneur

Processeur

Chaque instance de conteneur Cloud Run se voit attribuer par défaut le processeur virtuel qui a été configuré (1 par défaut).

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.

L'instance de conteneur peut être exécutée 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 de conteneur 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 de conteneur et ainsi de réduire la latence de démarrage.

Memory

Chaque instance de conteneur Cloud Run reçoit par défaut la mémoire configurée (512 Mio par défaut).

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

Simultanéité (services)

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

Bac à sable d'instance de conteneur

Si vous utilisez l'environnement d'exécution de première génération, les instances de conteneur Cloud Run sont exécutées 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.

Serveur de métadonnées d'instance de conteneur

Les instances de conteneur Cloud Run exposent un serveur de métadonnées que vous pouvez utiliser pour récupérer des informations sur votre instance de conteneur, telles que l'ID de projet, la région, l'ID d'instance ou les comptes de service. Il permet également de générer des jetons pour le compte de service d'environnement d'exécution.

Vous pouvez accéder à ces données à partir du serveur de métadonnées en utilisant de simples requêtes HTTP vers le 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 de conteneur (également disponible dans les journaux).
/computeMetadata/v1/instance/service-accounts/default/email Adresse e-mail du compte de service d'exécution de cette tâche 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 de conteneur 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 utilisés dans le conteneur doivent être compatibles avec UTF-8 : il peut s'agir d'un fichier UTF-8 ou d'un fichier pouvant être converti automatiquement en toute sécurité en UTF-8. Sinon, l'image de conteneur risque de ne pas être déployée. Cette restriction ne s'applique qu'aux noms de fichiers : il n'y a aucune restriction sur l'encodage des caractères utilisé dans le contenu des fichiers.

Si vous utilisez des noms de fichiers avec d'autres encodages, vous devez convertir ces noms de fichiers au format UTF-8 avant d'essayer de les déployer.

Délais avant expiration des requêtes sortantes

Pour les services Cloud Run, il existe un délai avant expiration des requêtes émises par votre conteneur vers un VPC, correspondant à 10 minutes d'inactivité. Pour les requêtes provenant de votre conteneur vers Internet, le délai avant expiration est écoulé après 20 minutes d'inactivité.