En esta página se enumeran los requisitos y comportamientos clave de los contenedores en Cloud Run. Hay algunas diferencias entre los servicios de Cloud Run y los trabajos de Cloud Run, que se indican cuando es necesario.
Idiomas e imágenes admitidos
Tu imagen de contenedor puede ejecutar código escrito en el lenguaje de programación que elijas y usar cualquier imagen base, siempre que respete las restricciones que se indican en esta página.
Los ejecutables de la imagen del contenedor deben compilarse para Linux de 64 bits. Cloud Run admite específicamente el formato ABI de Linux x86_64.
Cloud Run acepta imágenes de contenedor en los formatos de imagen Docker Image Manifest V2, Schema 1, Schema 2 y OCI. Cloud Run también acepta imágenes de contenedor comprimidas con Zstd.
Si vas a implementar una imagen de varias arquitecturas, la lista de manifiestos debe incluir linux/amd64.
En el caso de las funciones desplegadas con Cloud Run, puedes usar una de las imágenes base del tiempo 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 la programación de asistencia de tiempo de ejecución para ver los tiempos de ejecución compatibles.
Escuchar las solicitudes en el puerto correcto (servicios)
Un servicio de Cloud Run inicia instancias de Cloud Run para gestionar las solicitudes entrantes. Una instancia de Cloud Run siempre tiene un solo contenedor de entrada que escucha las solicitudes y, opcionalmente, uno o varios contenedores sidecar. Los siguientes detalles de configuración de puertos solo se aplican al contenedor de entrada, no a los sidecars.
El contenedor de entrada de una instancia debe recibir solicitudes en 0.0.0.0 en el puerto al que se envían las solicitudes.
En concreto, el contenedor de entrada no debe escuchar en 127.0.0.1.
De forma predeterminada, las solicitudes se envían a 8080, pero puedes configurar Cloud Run
para que envíe 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 al finalizar
En el caso de las tareas de Cloud Run, el contenedor debe salir con el código de salida 0 cuando la tarea se haya completado correctamente y con un código de salida distinto de cero cuando la tarea haya fallado.
Como los trabajos no deben atender solicitudes, el contenedor no debe escuchar en un puerto ni iniciar un servidor web.
Cifrado 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. Después, las solicitudes se envían como proxy a HTTP/1 o gRPC al contenedor sin TLS.
Si configuras un servicio de Cloud Run para usar HTTP/2 de extremo a extremo, tu contenedor debe gestionar las solicitudes en formato de texto sin cifrar HTTP/2 (h2c), ya que Cloud Run sigue terminando TLS automáticamente.
Respuestas (servicios)
En el caso de los servicios de Cloud Run, el contenedor debe enviar una respuesta en el plazo especificado en el ajuste de tiempo de espera de la solicitud después de recibir una solicitud, incluido el tiempo de inicio del contenedor. De lo contrario, la solicitud se finaliza y se devuelve 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 define el encabezado Cache-Control como private para que la respuesta no se almacene en caché. De esta forma, se evita que otros usuarios recuperen la cookie.
Variables de entorno
Hay distintos conjuntos de variables de entorno disponibles para los servicios y los trabajos de Cloud Run.
Variables de entorno de los servicios
Las siguientes variables de entorno se añaden automáticamente a todos los contenedores en ejecución, excepto PORT. La variable PORT solo se añade al contenedor de entrada:
| Nombre | Descripción | Ejemplo |
|---|---|---|
PORT |
Puerto en el que debe escuchar tu servidor HTTP. | 8080 |
K_SERVICE |
Nombre del servicio de Cloud Run que se está ejecutando. | hello-world |
K_REVISION |
Nombre de la revisión de Cloud Run que se está ejecutando. | hello-world.1 |
K_CONFIGURATION |
Nombre de la configuración de Cloud Run que ha creado la revisión. | hello-world |
Variables de entorno de los trabajos
En el caso de los trabajos de Cloud Run, se definen las siguientes variables de entorno:
| Nombre | Descripción | Ejemplo |
|---|---|---|
CLOUD_RUN_JOB |
Nombre del trabajo de Cloud Run que se está ejecutando. | hello-world |
CLOUD_RUN_EXECUTION |
Nombre de la ejecución de Cloud Run que se está ejecutando. | hello-world-abc |
CLOUD_RUN_TASK_INDEX |
Índice de esta tarea. Empieza en 0 para la primera tarea y aumenta en 1 por cada tarea sucesiva, hasta el número máximo de tareas menos 1. Si asignas a --parallelism un valor superior a 1, es posible que las tareas no sigan el orden del índice. Por ejemplo, la tarea 2 podría empezar antes que la tarea 1. |
0 |
CLOUD_RUN_TASK_ATTEMPT |
El número de veces que se ha intentado la ejecución de esta tarea. Empieza en 0 en el primer intento y aumenta en 1 en cada reintento sucesivo hasta alcanzar el valor máximo de reintentos. | 0 |
CLOUD_RUN_TASK_COUNT |
Número de tareas definidas en el parámetro --tasks. |
1 |
Requisitos de los encabezados de solicitud y respuesta (servicios)
En el caso de los servicios de Cloud Run, los nombres de los encabezados solo pueden incluir caracteres ASCII imprimibles que no sean espacios en blanco y no pueden contener dos puntos. Los valores de los encabezados solo pueden contener caracteres ASCII visibles, espacios y tabulaciones horizontales, tal como se indica en el RFC 7230 del IETF.
Acceso al sistema de archivos
El sistema de archivos de cada uno de tus contenedores se puede escribir y está sujeto al siguiente comportamiento:
- Se trata de un sistema de archivos en memoria, por lo que escribir en él usa la memoria de la instancia.
- Los datos escritos en el sistema de archivos no se conservan 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 agotar toda la memoria asignada a tu instancia escribiendo en el sistema de archivos en memoria, lo que provocará que la instancia falle. Puedes evitar este problema si usas un volumen en memoria específico con un límite de tamaño.
Ciclo de vida de la instancia
Las características del ciclo de vida de los trabajos y servicios de Cloud Run son diferentes, por lo que se describen por separado en las siguientes subsecciones.
Para servicios
Las siguientes condiciones se aplican únicamente a los servicios.
Escalado de servicios
De forma predeterminada, un servicio de Cloud Run se escala automáticamente al número de instancias necesarias para gestionar todas las solicitudes, eventos o uso de CPU entrantes. Si necesitas tener más control sobre el comportamiento del escalado, puedes usar el escalado manual.
Cada instancia ejecuta un número fijo de contenedores: un contenedor de entrada y, opcionalmente, uno o varios contenedores sidecar.
Cuando una revisión no recibe tráfico, se reduce al número mínimo de instancias configurado (cero de forma predeterminada).
Startup
En el caso de los servicios de Cloud Run, las instancias deben escuchar las solicitudes en un plazo de 4 minutos después de iniciarse y todos los contenedores de la instancia deben estar en buen estado. Durante este tiempo de inicio, se asigna CPU a las instancias. Puedes habilitar el aumento de la CPU al inicio para aumentar temporalmente la asignación de CPU durante el inicio de la instancia y, de este modo, 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 espere una instancia se mantendrá pendiente en una cola de la siguiente manera:
Las solicitudes se quedarán pendientes hasta 3, 5 veces el tiempo medio de inicio de las instancias de contenedor de este servicio o 10 segundos, lo que sea mayor.
Puedes configurar una prueba de inicio para determinar si el contenedor se ha iniciado y está listo para atender solicitudes.
En el caso de un servicio de Cloud Run que conste de instancias de varios contenedores, puedes especificar la secuencia en la que se inician los contenedores dentro de la instancia configurando el orden de inicio de los contenedores.
Procesar una solicitud
En los servicios de Cloud Run, la CPU siempre se asigna a todos los contenedores, incluidos los sidecars de una instancia, siempre que la revisión de Cloud Run esté procesando al menos una solicitud.
Inactivo
En el caso de los servicios de Cloud Run, una instancia inactiva es aquella que no está procesando ninguna solicitud.
La CPU asignada a todos los contenedores de una instancia inactiva depende de la configuración de facturación.
A menos que una instancia deba permanecer inactiva debido a la configuración del número mínimo de instancias, no permanecerá inactiva durante 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 activas debido a un número mínimo de instancias configurado. Si es necesario apagar una instancia que está procesando solicitudes, se les da tiempo a las solicitudes que ya se están procesando para que se completen y las nuevas solicitudes entrantes se dirigen a otras instancias. En casos excepcionales, Cloud Run puede iniciar un cierre y enviar una señal SIGTERM a un contenedor que aún esté procesando solicitudes.
Antes de apagar una instancia, Cloud Run envía una señal SIGTERM a todos los contenedores de la instancia, lo que indica el inicio de un periodo de 10 segundos antes de que se produzca el apagado real, momento en el que Cloud Run envía una señal SIGKILL.
Durante este periodo, se asigna CPU a la instancia y se factura.
En los servicios que usan el entorno de ejecución de primera generación, si la instancia no intercepta la señal SIGTERM, se cierra inmediatamente. En los servicios que usan el entorno de ejecución de segunda generación, te recomendamos que instales un controlador SIGTERM en tu contenedor para recibir una advertencia cuando Cloud Run esté a punto de cerrar una instancia.
Cancelación forzada
Si uno o varios contenedores de Cloud Run superan el límite de memoria total del contenedor, se terminará la instancia. Todas las solicitudes que aún se estén procesando en la instancia
terminarán con un error HTTP 500.
Para empleos
En el caso de los trabajos de Cloud Run, las instancias de contenedor se ejecutan hasta que se cierran, hasta que se alcanza el tiempo de espera de la tarea o hasta que el contenedor falla.
Códigos de salida
Puedes usar los códigos de salida de los trabajos para ver si se han completado correctamente o si se ha producido algún error. Los códigos de salida son valores numéricos que se asignan a la finalización correcta o a tipos específicos de errores.
En la siguiente tabla se especifican los códigos de salida habituales y sus definiciones:
| Código de salida | Señal | Descripción |
|---|---|---|
| 0 | La tarea se ha completado correctamente. | |
| 4 | SIGILL |
La tarea ha intentado acceder a la memoria en una dirección incorrecta. |
| 7 | SIGBUS |
La tarea ha intentado acceder a la memoria fuera de los límites asignados. |
| 9 | SIGKILL |
La tarea se finaliza de forma forzada, ya sea por acción del usuario o por intervención manual. |
| 11 | SIGSEGV |
La tarea ha intentado acceder a una memoria no autorizada. |
| 15 | SIGTERM |
Cuando una tarea supera el tiempo de espera configurado, recibe una señal SIGTERM. El servidor de aplicaciones envía la señal SIGTERM para que se cierre la instancia de contenedor. Si la instancia no se cierra sola en unos segundos después de recibir SIGTERM, Cloud Run envía una señal SIGKILL para forzar la finalización. Si la instancia se cierra correctamente con SIGTERM, puede devolver un código de error diferente. De lo contrario, devuelve SIGTERM. |
Cancelación forzada
Se termina una instancia de contenedor de Cloud Run que supera el límite de memoria permitido. Todas las solicitudes que aún se están procesando en la instancia de contenedor
terminan con un error HTTP 500.
Si una tarea supera el tiempo de espera de la tarea,
Cloud Run envía una señal "SIGTERM" que indica el inicio de un periodo de 10 segundos antes de que se produzca el cierre real, momento en el que Cloud Run envía una señal SIGKILL, que cierra la instancia de contenedor.
Durante este periodo, se asigna CPU a las instancias de contenedor durante todo su ciclo de vida y se facturan.
Consulta el código de muestra de SIGTERM
para saber cómo interceptar la señal SIGTERM.
Recursos de instancias de contenedor
En las siguientes secciones se describen los recursos de tu instancia de contenedor:
CPU
De forma predeterminada, a cada contenedor de Cloud Run de una instancia se le asigna la vCPU que se haya configurado (1 de forma predeterminada). Es posible configurar los límites de CPU de cada contenedor por separado.
Una vCPU se implementa como una abstracción del hardware subyacente para proporcionar el tiempo de CPU aproximado equivalente a un hiperhilo de hardware único en plataformas de CPU variables. 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 ningún detalle adicional sobre la plataforma de CPU.
El contenedor se puede ejecutar en varios núcleos simultáneamente.
En el caso de los servicios de Cloud Run, la asignación de CPU depende de la facturación seleccionada.
Si seleccionas la facturación basada en instancias, la CPU se asigna durante la vida útil de la instancia. Si selecciona la facturación basada en solicitudes (opción predeterminada), la CPU se asigna cuando las instancias procesan solicitudes. Para obtener más información, consulta la configuración de facturación.
Si has configurado un número de instancias mínimas, debes usar la facturación basada en instancias para que la CPU se asigne fuera de las solicitudes.
Puedes habilitar el aumento de la CPU al inicio para aumentar temporalmente la asignación de CPU durante el inicio de la instancia y, de este modo, reducir la latencia de inicio.
Memoria
De forma predeterminada, a cada contenedor de Cloud Run se le asigna la memoria que se haya configurado (512 MiB de forma predeterminada). Es posible configurar los límites de memoria de cada contenedor por separado.
Entre los usos habituales de la memoria se incluyen los siguientes:
- Código cargado en la memoria para ejecutar el servicio.
- Escribir 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 OpCache de PHP
- Uso de memoria por solicitud
- Volúmenes compartidos en memoria
GPU
Puedes configurar un contenedor en una instancia de Cloud Run para que acceda a una GPU. Si el servicio de Cloud Run se despliega con contenedores sidecar, solo un contenedor del despliegue puede acceder a la GPU. Consulta los requisitos y los detalles para configurar la GPU.
Bibliotecas de NVIDIA
De forma predeterminada, todas las bibliotecas de controladores de NVIDIA L4 se montan en /usr/local/nvidia/lib64. Cloud Run añade automáticamente esta ruta a la variable de entorno LD_LIBRARY_PATH (es decir, ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64) del contenedor con la GPU. Esto permite que el enlazador dinámico encuentre las bibliotecas de controladores de NVIDIA. El enlazador busca y resuelve las rutas
en el orden en que se indican en la variable de entorno LD_LIBRARY_PATH. Los valores que especifiques en esta variable tendrán prioridad sobre la ruta predeterminada de las bibliotecas del controlador de Cloud Run /usr/local/nvidia/lib64.
Si quieres usar una versión de CUDA superior a 12.2, la forma más sencilla es depender de una imagen base de NVIDIA más reciente
con paquetes de compatibilidad con versiones posteriores ya instalados. Otra opción es instalar manualmente los paquetes de compatibilidad con versiones anteriores de NVIDIA y añadirlos a LD_LIBRARY_PATH. Consulta la matriz de compatibilidad de NVIDIA para determinar qué versiones de CUDA son compatibles con la versión del controlador de NVIDIA proporcionada (535.216.03).
Simultaneidad (servicios)
En el caso de los servicios de Cloud Run, cada instancia de Cloud Run tiene asignada de forma predeterminada una concurrencia múltiple, por lo que el contenedor de entrada puede recibir más de una solicitud al mismo tiempo. Puedes cambiarlo configurando la simultaneidad.
Entorno aislado de contenedores
Si usas el entorno de ejecución de primera generación, los contenedores de Cloud Run se ejecutan en un espacio aislado mediante el espacio aislado del entorno de ejecución de contenedores gVisor. Como se indica en la referencia de compatibilidad de llamadas al sistema de gVisor, es posible que este sandbox de contenedores 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.
En el entorno de ejecución de segunda generación, /sys/class/dmi/id/product_name se define como Google Compute Engine.
El entorno de ejecución de segunda generación ejecuta el código de tu servicio en un espacio de nombres de proceso independiente, por lo que se inicia 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 tu servicio no se ejecuta como proceso init del contenedor.
Límites de descriptores de archivos
Los entornos de primera y segunda generación de Cloud Run limitan a 25.000 el número de descriptores de archivo que puede abrir un proceso. Esto se aplica al contenedor y a cualquier proceso secundario que cree (forks). Este es un límite estricto. Si superas el límite, es posible que tu instancia se quede sin descriptores de archivos o sockets.
Límites en el entorno de segunda generación
Los límites del entorno de segunda generación son los límites estándar de Linux.
Por ejemplo, los límites del número de descriptores de archivos que se pueden abrir (como se indica en /proc/sys/fs/file-max) usan el valor predeterminado de aproximadamente el 10% de la memoria. Consulta más información sobre file-max y file-nr en la documentación del kernel.
Del mismo modo, max_map_count (como se muestra en /proc/sys/vm/max_map_count),
que define el número de áreas de memoria que puede tener un proceso, usa el valor predeterminado
65535. Consulta los detalles en la max-map-count
de la documentación del kernel.
Contenedores con privilegios y binarios setuid
Cloud Run no admite contenedores con privilegios. Por lo tanto, Cloud Run no admite archivos binarios que usen marcas setuid para usuarios que no sean root, como gcsfuse o sudo, y puede que se produzca un error debido a que no hay permisos suficientes.
Otra alternativa es ejecutar estos archivos binarios como usuario root y, a continuación, usar el comando su para cambiar a otro usuario en tiempo de ejecución.
Por ejemplo, en tu archivo Dockerfile, elimina la instrucción USER y, en tu secuencia de comandos de punto de entrada, usa la siguiente secuencia:
gcsfuse ... # Run gcsfuse as root
su myuser -c "/yourapp.sh" # Switch to 'myuser' and run 'yourapp.sh'
Usuario que ejecuta
Si el nombre de usuario no existe, Cloud Run ejecuta el contenedor como usuario root (uid=0).
Servidor de metadatos de instancias
Las instancias de Cloud Run exponen un servidor de metadatos que puedes usar para obtener detalles sobre tus contenedores, 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 de servicio.
Para acceder a los datos del servidor de metadatos, usa solicitudes HTTP al endpoint http://metadata.google.internal/ con el encabezado Metadata-Flavor: Google. No se necesitan bibliotecas de cliente. Para obtener más información, consulta Obtener metadatos.
En la siguiente tabla se muestra información del servidor de metadatos disponibles:
| Ruta | Descripción |
|---|---|
/computeMetadata/v1/project/project-id |
ID del proyecto al que pertenece el servicio o el trabajo de Cloud Run |
/computeMetadata/v1/project/numeric-project-id |
Número del proyecto al que pertenece el servicio o el trabajo de Cloud Run |
/computeMetadata/v1/instance/region |
Región de este servicio o trabajo de Cloud Run. Devuelve projects/PROJECT-NUMBER/regions/REGION. |
/computeMetadata/v1/instance/id |
Identificador único de la instancia (también disponible en los registros). |
/computeMetadata/v1/instance/service-accounts/default/email |
Correo de la identidad de servicio de este servicio o trabajo de Cloud Run. |
/computeMetadata/v1/instance/service-accounts/default/token |
Genera un token de acceso OAuth2 para la cuenta de servicio de este servicio o trabajo de Cloud Run. El agente de servicio de Cloud Run se usa para obtener un token. Este endpoint devolverá una respuesta JSON con un atributo access_token. 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 Google Cloud zona en la que se ejecutan las instancias. Por lo tanto, el atributo de metadatos /computeMetadata/v1/instance/zone
siempre devuelve projects/PROJECT-NUMBER/zones/REGION-1.
Nombres de archivo
Los nombres de los archivos que utilices en los contenedores deben ser compatibles con UTF-8, es decir, deben estar en formato UTF-8 o en un formato que se pueda convertir automáticamente a UTF-8 sin problemas. Si los nombres de tus archivos usan codificaciones diferentes, ejecuta la compilación de Docker en una máquina con nombres de archivo compatibles con UTF-8 y evita copiar archivos en un contenedor que contenga nombres UTF-8 incompatibles.
La implementación del contenedor falla si los nombres de los archivos no son compatibles con UTF-8. Ten en cuenta que no hay ninguna restricción en la codificación de caracteres que utilices en un archivo.
Tiempos de espera de solicitudes salientes
En el caso de los servicios y los trabajos de Cloud Run, hay un tiempo de espera de 10 minutos después de que las solicitudes de tu contenedor a la VPC estén inactivas. En el caso de las solicitudes de tu contenedor a Internet, hay un tiempo de espera de 20 minutos de inactividad.
Restablecimientos de conexiones salientes
Las secuencias de conexión de tu contenedor a la VPC y a Internet se pueden terminar y sustituir ocasionalmente cuando se reinicia o se actualiza la infraestructura subyacente. Si tu aplicación reutiliza conexiones de larga duración, te recomendamos que la configures para que restablezca las conexiones y así evitar que se reutilice una conexión inactiva.