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 Manifest V2 de imagen de Docker, Schema 1, Schema 2 y formatos de imagen OCI. Cloud Run también acepta imágenes de contenedores comprimidos con Zstd.
Si implementas una imagen de varias arquitecturas, la lista de manifiestos debe incluir linux/amd64.
En el caso de las funciones implementadas con Cloud Run, puedes usar una de las imágenes base del entorno de ejecución de Cloud Run que publican los paquetes de compilación de Google Cloud para recibir actualizaciones automáticas de seguridad y mantenimiento. Consulta el programa de asistencia para el entorno de ejecución para conocer los entornos de ejecución compatibles.
Escucha solicitudes en el puerto correcto (servicios)
Un servicio de Cloud Run inicia instancias de Cloud Run para controlar las solicitudes entrantes. Una instancia de Cloud Run siempre tiene un solo contenedor de entrada que escucha las solicitudes y, de forma opcional, uno o más contenedores de sidecar. Los siguientes detalles de configuración de puertos solo se aplican al contenedor de entrada, no a los sidecars.
El contenedor de entrada dentro de una instancia 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 de entrada.
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 de forma directa. Cloud Run finaliza TLS para HTTPS y gRPC; luego, las solicitudes se envían a través de 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, el 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 del contenedor. De lo contrario, se completa la solicitud y se muestra un error 504.
Almacenamiento en caché de respuestas y cookies
Si la respuesta de tu servicio de Cloud Run contiene un encabezado Set-Cookie, Cloud Run establece el encabezado Cache-Control en private para que la respuesta no se almacenen en caché. Esto evita que otros usuarios recuperen la cookie.
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 todos los contenedores en ejecución, excepto PORT. La variable PORT solo se agrega al contenedor de entrada:
| Nombre | 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:
| Nombre | 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 |
El índice de esta tarea. Comienza en 0 para la primera tarea y se incrementa en 1 para cada tarea sucesiva, hasta la cantidad máxima de tareas menos 1. Si estableces --parallelism en más de 1, es posible que las tareas no sigan el orden del índice. Por ejemplo, sería posible que la tarea 2 comience antes de la tarea 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 en cada uno de tus contenedores 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.
- Los datos escritos en el sistema de archivos no persisten cuando se detiene la instancia.
Ten en cuenta que no puedes especificar un límite de tamaño para este sistema de archivos, por lo que puedes usar toda la memoria asignada a tu instancia si escribes en el sistema de archivos en la memoria, lo que hará que falle la instancia. Puedes evitar este problema si usas un volumen en memoria dedicado con un límite de tamaño.
Ciclo de vida de la instancia
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
Un servicio de Cloud Run escala de forma automática a la cantidad de instancias necesarias para controlar todas las solicitudes entrantes, los eventos o el uso de CPU.
Cada instancia ejecuta una cantidad fija de contenedores: un contenedor de entrada y, de forma opcional, uno o más contenedores de sidecar.
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 deben escuchar las solicitudes en un plazo de 4 minutos después de su inicio y todos los contenedores dentro de la instancia deben estar en buen estado. 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 para reducir la latencia de inicio.
Las solicitudes se enviarán al contenedor de entrada en cuanto esté escuchando en el puerto configurado.
Una solicitud que espera a que se inicie una instancia se mantendrá pendiente en una cola de la siguiente manera:
- Si se inician instancias nuevas, como durante un escalamiento horizontal, las solicitudes admitirán al menos el tiempo de inicio promedio de las instancias de contenedor de este servicio. Esto incluye el momento en que la solicitud inicia un escalamiento horizontal, como cuando escalas desde cero.
- Si el tiempo de inicio es inferior a 10 segundos, las solicitudes permanecerán hasta 10 segundos.
- Si no hay instancias en el proceso de inicio y la solicitud no inicia un escalamiento horizontal, las solicitudes se almacenarán hasta por 10 segundos.
Puedes configurar un sondeo de inicio para determinar si el contenedor se inició y está listo para entregar solicitudes.
Para un servicio de Cloud Run que consiste en instancias de varios contenedores, puedes especificar la secuencia en la que se inician los contenedores dentro de la instancia a través de la configuración del orden de inicio del contenedor.
Procesa una solicitud
Para los servicios de Cloud Run, la CPU siempre se asigna a todos los contenedores, incluidos los sidecars dentro de una instancia, siempre y cuando la revisión de Cloud Run procese al menos una solicitud
Inactivo
Para los servicios de Cloud Run, una instancia inactiva es aquella que no procesa ninguna solicitud.
La CPU asignada a todos los contenedores en una instancia inactiva depende de la asignación de CPU configurada.
A menos que una instancia deba mantenerse inactiva debido a la configuración de la cantidad mínima de instancias, no se mantendrá inactiva por más de 15 minutos.
Apagar
En el caso de los servicios de Cloud Run, una instancia inactiva se puede cerrar en cualquier momento, incluidas las instancias que se mantienen preparadas con una cantidad mínima de instancias. Si una instancia 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. En casos excepcionales, es posible que Cloud Run inicie un cierre y envíe una señal SIGTERM a un contenedor que aún esté procesando solicitudes.
Antes de cerrar una instancia, Cloud Run envía una señal SIGTERM a todos los contenedores de una instancia, lo que indica el inicio de un período de 10 segundos antes de que se produzca el cierre real, momento en el 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.
En los servicios que usan el entorno de ejecución de primera generación, si la instancia 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
Si uno o más contenedores de Cloud Run superan el límite total de memoria del contenedor, la instancia se finaliza. 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.
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.
Consulta la muestra de código SIGTERM si deseas obtener información para capturar la señal SIGTERM.
Recursos de instancias de contenedor
CPU
De forma predeterminada, cada contenedor de Cloud Run en una instancia recibe la CPU virtual que se ha configurado (1 de forma predeterminada). Es posible configurar los límites de CPU en cada contenedor por separado.
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.
El contenedor puede ejecutarse 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 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 para reducir la latencia de inicio.
Memoria
De forma predeterminada, a cada contenedor de Cloud Run se le asigna la memoria configurada (512 MiB de forma predeterminada). Es posible configurar los límites de memoria en cada contenedor por separado.
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
- Volúmenes en memoria compartida
GPU
Puedes configurar un contenedor en una instancia de Cloud Run para acceder a una GPU. Si el servicio de Cloud Run se implementa con contenedores secundarios, solo un contenedor de la implementación puede acceder a la GPU. Consulta Configura la GPU para conocer los requisitos y los detalles.
Bibliotecas de NVIDIA
De forma predeterminada, se activan todas las bibliotecas de controladores de NIVIDIA L4 en /usr/local/nvidia/lib64.
Si tu servicio no puede encontrar las bibliotecas proporcionadas, actualiza la ruta de búsqueda del vinculador dinámico. Para ello, agrega la línea ENV LD_LIBRARY_PATH /usr/local/nvidia/lib64:${LD_LIBRARY_PATH} a tu Dockerfile.
Ten en cuenta que también puedes configurar LD_LIBRARY_PATH como una variable de entorno para el servicio de Cloud Run si tienes una imagen existente y no deseas volver a compilarla con un Dockerfile actualizado.
Si quieres usar una versión de CUDA superior a 12.2, la forma más fácil es depender de una imagen base de NVIDIA más reciente con paquetes de retrocompatibilidad ya instalados. Otra opción es instalar manualmente los paquetes de compatibilidad con versiones anteriores de NVIDIA y agregarlos a LD_LIBRARY_PATH. Consulta la matriz de compatibilidad de NVIDIA para determinar qué versiones de CUDA son retrocompatibles con la versión del controlador de NVIDIA proporcionada (535.129.03).
Simultaneidad (servicios)
Para los servicios de Cloud Run, de forma predeterminada, cada instancia de Cloud Run está configurada en varias solicitudes simultáneas, en las que el contenedor de entrada puede recibir más de una solicitud al mismo tiempo. Puedes cambiar este comportamiento si configuras la simultaneidad.
Zona de pruebas del contenedor
Si usas el entorno de ejecución de primera generación, las instancias de contenedor de Cloud Run se colocan en 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 compatibilidad total 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.
El entorno de ejecución de segunda generación ejecuta el código de servicio en un espacio de nombres de procesos independiente, por lo que comienza como el proceso init del contenedor que tiene una semántica de proceso especial. En el entorno de ejecución de primera generación, el código de servicio no se ejecuta como el proceso init del contenedor.
Servidor de metadatos de la instancia
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 puedes usar el servidor de metadatos para generar tokens para la identidad del servicio.
Para acceder a los datos del servidor de metadatos, usa solicitudes HTTP 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 identidad del servicio 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 usas en los contenedores deben ser compatibles, ya sea UTF-8 o algún formato que se pueda convertir automáticamente de forma segura en UTF-8. Si los nombres de tus archivos usan diferentes codificaciones, ejecuta la compilación de Docker en una máquina con nombres de archivos compatibles con UTF-8 y evita copiar archivos en un contenedor que contenga nombres UTF-8 no compatibles.
La implementación del contenedor falla si los nombres de los archivos no son compatibles con UTF-8. Ten en cuenta que no hay restricciones en la codificación de caracteres que usas dentro de un archivo.
Conexiones salientes
Tiempos de espera de solicitud saliente
Para los servicios y trabajos de Cloud Run, hay un tiempo de espera después de 10 minutos de tiempo de inactividad de las solicitudes de tu contenedor a VPC. Para las solicitudes de tu contenedor a Internet, hay un tiempo de espera después de 20 minutos de tiempo de inactividad.
Se restablece la conexión saliente
Las transmisiones de conexión de tu contenedor a Internet y VPC pueden finalizarse y reemplazarse de forma ocasional cuando se reinicia o actualiza la infraestructura subyacente. Si tu aplicación vuelve a usar conexiones de larga duración, te recomendamos entonces que configures tu aplicación para restablecer las conexiones para evitar la reutilización de una conexión inactiva.