Contrato de entorno de ejecución del contenedor

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

En esta página, se enumeran los requisitos y comportamientos clave de los contenedores en Cloud Run. Existen algunas diferencias entre los servicios de Cloud Run y los trabajos de Cloud Run: estos se llaman cuando corresponda.

Imágenes y lenguajes compatibles

Tu imagen de contenedor puede ejecutar código escrito en el lenguaje de programación que elijas y usar cualquier imagen base, siempre que cumpla con las restricciones enumeradas en esta página.

Los ejecutables en la imagen del contenedor deben compilarse para Linux de 64 bits. Cloud Run admite de forma específica el formato ABI x86_64 de Linux.

Cloud Run acepta imágenes de contenedor en el manifiesto de imágenes de Docker V2, Schema 1, Schema 2 y formatos de imagen OCI.

No se admiten las listas de manifiestos que se usan para imágenes de varias arquitecturas.

Escucha solicitudes en el puerto correcto (servicios)

Para los servicios de Cloud Run, el contenedor debe escuchar las solicitudes en 0.0.0.0 en el puerto al que se envían las solicitudes. De forma predeterminada, las solicitudes se envían a 8080, pero puedes configurar Cloud Run para enviar solicitudes al puerto que elijas. Cloud Run inserta la variable de entorno PORT en el contenedor. Dentro de las instancias de contenedor de Cloud Run, el valor de la variable de entorno PORT siempre refleja el puerto al que se envían las solicitudes. El valor predeterminado es 8080.

El contenedor que se ejecuta en una ejecución de trabajo debe salir de la finalización.

En los trabajos de Cloud Run, el contenedor debe salir con el código de salida 0 cuando el trabajo se completó de forma correcta y salir con un código de salida que no sea cero cuando el trabajo falló.

Debido a que los trabajos no deben entregar solicitudes, el contenedor no debe escuchar en un puerto ni iniciar un servidor web.

Encriptación de la capa de transporte (TLS)

El contenedor no debe implementar ninguna seguridad de la capa de transporte directamente. Cloud Run finaliza TLS para HTTPS y gRPC; luego, las solicitudes se envían mediante proxy como HTTP/1 o gRPC al contenedor sin TLS.

Si configuras un servicio de Cloud Run para usar HTTP/2 de extremo a extremo, el contenedor debe manejar las solicitudes en formato de texto simple HTTP/2 (h2c), ya que Cloud Run aún finaliza automáticamente TLS.

Respuestas (servicios)

Para los servicios de Cloud Run, la instancia de contenedor debe enviar una respuesta dentro del tiempo especificado en la configuración de tiempo de espera de la solicitud después de recibir una solicitud, incluido el tiempo de inicio de la instancia del contenedor. De lo contrario, se completa la solicitud y se muestra un error 504.

Variables de entorno

Hay diferentes conjuntos de variables de entorno disponibles para los servicios y trabajos de Cloud Run.

Variables de entorno para servicios

Las siguientes variables de entorno se agregan de forma automática a los contenedores en ejecución:

Name Descripción Ejemplo
PORT El puerto en el que debe escuchar el servidor HTTP. 8080
K_SERVICE El nombre del servicio de Cloud Run que se ejecuta. hello-world
K_REVISION El nombre de la revisión de Cloud Run que se ejecuta. hello-world.1
K_CONFIGURATION El nombre de la configuración de Cloud Run que creó la revisión. hello-world

Variables de entorno para trabajos

En los trabajos de Cloud Run, se configuran las siguientes variables de entorno:

Name Descripción Ejemplo
CLOUD_RUN_JOB El nombre del trabajo de Cloud Run que se ejecuta. hello-world
CLOUD_RUN_EXECUTION El nombre de la ejecución de Cloud Run que se ejecuta. hello-world-abc
CLOUD_RUN_TASK_INDEX Para cada tarea, se establecerá en un valor único entre 0 y la cantidad de tareas menos 1. 0
CLOUD_RUN_TASK_ATTEMPT La cantidad de veces que se reintentó esta tarea. Comienza en 0 para el primer intento y aumenta 1 por cada reintento sucesivo, hasta el valor máximo de reintentos. 0
CLOUD_RUN_TASK_COUNT Es la cantidad de tareas definidas en el parámetro --tasks. 1

Requisitos del encabezado de solicitud y respuesta (servicios)

En los servicios de Cloud Run, los nombres de encabezado están restringidos a ASCII que no se pueden almacenar en blanco y no pueden contener dos puntos. Los valores de encabezado están restringidos a caracteres ASCII visibles más espacio y tabulación horizontal según IETF RFC 7230

Acceso al sistema de archivos

El sistema de archivos de tu contenedor admite escritura y está sujeto al siguiente comportamiento:

  • Este es un sistema de archivos en la memoria, por lo que para escribir en él, se usa la memoria de la instancia del contenedor.
  • Los datos escritos en el sistema de archivos no persisten cuando se detiene la instancia de contenedor.

Ciclo de vida de las instancias de contenedor

Las características del ciclo de vida difieren en los trabajos y servicios de Cloud Run, por lo que se describen por separado en las siguientes subsecciones.

Para servicios

Lo siguiente se aplica solo a los servicios.

Escalamiento de servicios

En el caso de los servicios de Cloud Run, en respuesta a las solicitudes entrantes, un servicio se escala automáticamente a una cierta cantidad de instancias de contenedores, cada una de las cuales ejecuta la imagen de contenedor implementada.

Cuando una revisión no recibe tráfico, la escala se ajusta a la cantidad mínima de instancias de contenedor configuradas (cero de forma predeterminada).

Inicio

En el caso de los servicios de Cloud Run, las instancias de contenedor deben detectar solicitudes dentro de los 4 minutos posteriores al inicio. Durante este tiempo de inicio, las instancias de contenedor reciben la CPU asignada. Puedes habilitar el aumento de CPU de inicio para aumentar de forma temporal la asignación de CPU durante el inicio de la instancia del contenedor a fin de reducir la latencia de inicio.

Las solicitudes se enviarán a la instancia de contenedor en cuanto esté escuchando en el puerto configurado.

Una solicitud que espera a que se inicie una instancia de contenedor se mantendrá en una cola durante un máximo de 10 segundos.

Puedes configurar un sondeo de inicio a fin de determinar si el contenedor se inició y está listo para entregar solicitudes.

Procesa una solicitud

Para los servicios de Cloud Run, la CPU siempre se asigna cuando la instancia de contenedor procesa al menos una solicitud.

Inactivo

Para los servicios de Cloud Run, una instancia de contenedor inactiva es aquella que no procesa ninguna solicitud.

La CPU asignada a una instancia de contenedor inactiva depende de la asignación de CPU configurada.

A menos que una instancia de contenedor deba mantenerse inactiva debido a la configuración de la cantidad mínima de instancias de contenedor, no se mantendrá inactiva por más de 15 minutos.

Cierre

En el caso de los servicios de Cloud Run, una instancia de contenedor inactiva se puede cerrar en cualquier momento, incluidas las instancias que se mantienen preparadas con una cantidad mínima de instancias. Si una instancia de contenedor que procesa solicitudes se debe cerrar, las nuevas solicitudes entrantes se enrutan a otras instancias y las solicitudes que se están procesando tienen tiempo para completarse.

Antes de cerrar una instancia de contenedor, Cloud Run envía una señal SIGTERM, lo que indica el inicio de un período de 10 segundos antes de que se produzca el cierre real, en el momento en que Cloud Run envía una señal SIGKILL. Durante este período, la instancia de contenedor se asigna a la CPU y se factura. Si la instancia de contenedor no captura la señal SIGTERM, se cierra de inmediato. (Consulta las muestras de código para obtener información sobre cómo capturar la señal SIGTERM).

Terminación forzada

Se finaliza una instancia de contenedor de Cloud Run que supera el límite de memoria permitido. Todas las solicitudes que aún se procesan en la instancia de contenedor terminan con un error HTTP 500.

Para trabajos

En los trabajos de Cloud Run, las instancias de contenedor se ejecutan hasta que la instancia del contenedor se cierra, o hasta que se alcanza el tiempo de espera de la tarea o hasta que el contenedor falla. Si la instancia de contenedor no captura la señal SIGTERM, se cierra de inmediato. (Consulta las muestras de código para obtener información sobre cómo capturar la señal SIGTERM).

Terminación forzada

Se finaliza una instancia de contenedor de Cloud Run que supera el límite de memoria permitido. Todas las solicitudes que aún se procesan en la instancia de contenedor terminan con un error HTTP 500.

Si una tarea excede el tiempo de espera de la tarea, Cloud Run envía una señal “SIGTERM”, que indica el inicio de un período de 10 segundos antes de que ocurra el cierre real. En ese momento Cloud Run envía una señal SIGKILL y cierra la instancia de contenedor.

Durante este período, las instancias de contenedor se asignan a la CPU durante todo el ciclo de vida y se facturan.

Recursos de instancias de contenedor

CPU

De forma predeterminada, cada instancia de contenedor de Cloud Run obtiene la CPU virtual que se ha configurado (1 de forma predeterminada).

Una CPU virtual se implementa como una abstracción del hardware subyacente para proporcionar el tiempo de CPU equivalente aproximado de un subproceso de hardware único en plataformas variables de CPU. Todas las plataformas de CPU que usa Cloud Run admiten el conjunto de instrucciones AVX2. Ten en cuenta que el contrato de contenedor no contiene detalles adicionales de la plataforma de CPU.

La instancia de contenedor se puede ejecutar en varios núcleos de forma simultánea.

Para los servicios de Cloud Run, puedes especificar que la CPU se asigne siempre durante la vida útil de la instancia o que solo se asigne durante el inicio de la instancia del contenedor y el procesamiento de solicitudes. Consulta Asignación de CPU para obtener más información.

Si configuraste una cantidad de instancias mínimas, estas también están sujetas a la configuración de asignación de CPU.

Puedes habilitar el aumento de CPU de inicio para aumentar de forma temporal la asignación de CPU durante el inicio de la instancia del contenedor a fin de reducir la latencia de inicio.

Memoria

De forma predeterminada, a cada instancia de contenedor de Cloud Run se le asigna la memoria configurada (512 MiB de forma predeterminada).

Entre los usos típicos de la memoria, se incluyen los siguientes:

  • Código cargado en la memoria para ejecutar el servicio
  • Escribe en el sistema de archivos
  • Procesos adicionales que se ejecutan en el contenedor, como un servidor nginx
  • Sistemas de almacenamiento en caché en memoria, como la OpCache de PHP
  • Uso de memoria por solicitud

Simultaneidad (servicios)

Para los servicios de Cloud Run, de forma predeterminada, cada instancia de contenedor de Cloud Run está configurada en varias solicitudes simultáneas, en las que cada instancia de contenedor puede recibir más de una solicitud al mismo tiempo. Puedes cambiar este comportamiento si configuras la simultaneidad.

Zona de pruebas de la instancia del contenedor

Si usas el entorno de ejecución de primera generación, las instancias de contenedor de Cloud Run se colocan en zonas de pruebas mediante la zona de pruebas del entorno de ejecución del contenedor gVisor. Como se documenta en la referencia de compatibilidad de llamadas del sistema gVisor, es posible que esta zona de pruebas del contenedor no admita algunas llamadas al sistema.

Si usas el entorno de ejecución de segunda generación, tienes plena compatibilidad con Linux. Los trabajos de Cloud Run siempre usan el entorno de ejecución de segunda generación. Dentro del entorno de ejecución de segunda generación, /sys/class/dmi/id/product_name se establece en Google Compute Engine.

Servidor de metadatos de la instancia del contenedor

Las instancias de contenedor de Cloud Run exponen un servidor de metadatos que puedes usar para recuperar detalles sobre la instancia de contenedor, como el ID del proyecto, la región, el ID de la instancia o las cuentas de servicio. También se puede usar a fin de generar tokens para la cuenta de servicio del entorno de ejecución.

Puedes acceder a estos datos desde el servidor de metadatos mediante solicitudes HTTP simples al extremo http://metadata.google.internal/ con el encabezado Metadata-Flavor: Google: no se necesitan bibliotecas cliente. Para obtener más información, consulta Obtén metadatos.

En la siguiente tabla, se enumeran algunos de los datos del servidor de metadatos disponibles:

Ruta Descripción
/computeMetadata/v1/project/project-id ID del proyecto al que pertenece el servicio o trabajo de Cloud Run
/computeMetadata/v1/project/numeric-project-id Número del proyecto al que pertenece el servicio o trabajo de Cloud Run
/computeMetadata/v1/instance/region Región de este servicio o trabajo de Cloud Run, muestra projects/PROJECT-NUMBER/regions/REGION
/computeMetadata/v1/instance/id Identificador único de la instancia de contenedor (también disponible en registros).
/computeMetadata/v1/instance/service-accounts/default/email Correo electrónico de la cuenta de servicio del entorno de ejecución de este trabajo o servicio de Cloud Run.
/computeMetadata/v1/instance/service-accounts/default/token Genera un token de acceso de OAuth2 para la cuenta de servicio de este servicio o trabajo de Cloud Run. El agente de servicio de Cloud Run se usa para recuperar un token. Este extremo mostrará una respuesta JSON con un atributo access_token. Obtén más información sobre cómo extraer y usar este token de acceso.

Ten en cuenta que Cloud Run no proporciona detalles sobre la zona de Google Cloud en la que se ejecutan las instancias de contenedor. Como consecuencia, el atributo de metadatos /computeMetadata/v1/instance/zone siempre muestra projects/PROJECT-NUMBER/zones/REGION-1.

Nombres del archivo

Los nombres del archivo que se usan en el contenedor deben ser compatibles con UTF-8: ya sea UTF-8 o algo que se pueda convertir automáticamente de forma segura a UTF-8. De lo contrario, la imagen del contenedor puede fallar. Esta restricción solo se aplica a los nombres del archivo: no hay restricciones en la codificación de caracteres que se usa en el contenido del archivo.

Si usas nombres del archivo con otras codificaciones, debes convertir esos nombres de archivos en UTF-8 antes de intentar la implementación.

Tiempos de espera de solicitud saliente

En los servicios de Cloud Run, para las solicitudes de tu contenedor a VPC, hay un tiempo de espera después de 2 minutos de tiempo de inactividad. Para las solicitudes de tu contenedor a Internet, hay un tiempo de espera después de 20 minutos de tiempo de inactividad.