En esta página se describe cómo desplegar un nuevo servicio o una revisión de un servicio en Cloud Run directamente desde el código fuente mediante un solo comando de CLI de gcloud,
gcloud run deploy con la marca --source. Para ver un ejemplo de cómo desplegar un servicio Hello World, consulta las guías de inicio rápido de despliegue desde el código fuente.
- Desplegar desde el origen con compilación (opción predeterminada):
esta opción usa los paquetes de compilación de Google Cloud y Cloud Build para compilar automáticamente imágenes de contenedor a partir de tu código fuente sin tener que instalar Docker en tu máquina ni configurar paquetes de compilación o Cloud Build. De forma predeterminada, Cloud Run usa el tipo de máquina predeterminado que proporciona Cloud Build.
Al ejecutar
gcloud run deploy --source, tampoco es necesario ejecutar el comandogcloud builds submit. - Desplegar desde el origen sin compilación (vista previa): esta opción despliega artefactos directamente en Cloud Run, sin pasar por el paso de Cloud Build. Esto permite que los tiempos de implementación sean rápidos.
Ten en cuenta que las implementaciones de origen usan Artifact Registry para almacenar los contenedores compilados. Si tu proyecto aún no tiene un repositorio de Artifact Registry con el nombre cloud-run-source-deploy en la región en la que vas a implementar, esta función crea automáticamente un repositorio de Artifact Registry con el nombre cloud-run-source-deploy.
Si hay un Dockerfile en el directorio del código fuente, el código fuente subido se compila con ese Dockerfile. Si no hay ningún Dockerfile en el directorio del código fuente, los buildpacks de Google Cloud detectan automáticamente el lenguaje que estás usando y obtienen las dependencias del código para crear una imagen de contenedor lista para producción con una imagen base segura gestionada por Google.
De forma predeterminada, las correcciones de seguridad solo se aplican cuando se despliega el servicio de Cloud Run. Cuando habilitas las actualizaciones de seguridad automáticas de un servicio, este recibe parches automáticamente sin tiempo de inactividad. Consulta más información sobre cómo configurar las actualizaciones de seguridad.Antes de empezar
- Asegúrate de haber configurado un proyecto para Cloud Run como se describe en la página de configuración.
Si tu proyecto está sujeto a una política de organización de restricción de dominio que restringe las invocaciones no autenticadas, tendrás que acceder al servicio desplegado tal como se describe en la sección Probar servicios privados.
-
Enable the Cloud Run Admin API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.Una vez que se haya habilitado la API Admin de Cloud Run, se creará automáticamente la cuenta de servicio predeterminada de Compute Engine.
Roles obligatorios
Para implementar desde la fuente, tú o tu administrador debéis conceder los siguientes roles de gestión de identidades y accesos a la cuenta de implementación.
Haz clic para ver los roles necesarios de la cuenta de implementación
Para obtener los permisos que necesitas para compilar e implementar desde la fuente, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:
- Desarrollador de fuentes de Cloud Run (
roles/run.sourceDeveloper) en tu proyecto - Consumidor de Uso de Servicio (
roles/serviceusage.serviceUsageConsumer) en tu proyecto - Usuario de cuenta de servicio (
roles/iam.serviceAccountUser) en la identidad de servicio de Cloud Run
Para ver una lista de los roles y permisos de gestión de identidades y accesos asociados a Cloud Run, consulta los artículos Roles de gestión de identidades y accesos de Cloud Run y Permisos de gestión de identidades y accesos de Cloud Run. Si tu servicio de Cloud Run interactúa con APIs, como las bibliotecas de cliente de Cloud, consulta la guía de configuración de la identidad del servicio.Google Cloud Para obtener más información sobre cómo conceder roles, consulta los permisos de implementación y el artículo sobre cómo gestionar el acceso.
Idiomas disponibles
Además de las fuentes con un Dockerfile, la implementación desde la fuente admite los siguientes lenguajes mediante los paquetes de compilación de Google Cloud:
| Tiempo de ejecución | Despliegue de origen | Configuración de buildpack |
|---|---|---|
| Go | Desplegar un servicio de Go | Configurar buildpacks de Go |
| Node.js | Desplegar un servicio de Node.js | Configurar buildpacks de Node.js |
| Python | Desplegar un servicio de Python | Configurar buildpacks de Python |
| Java (incluye Kotlin, Groovy y Scala) |
Desplegar un servicio Java | Configurar buildpacks de Java |
| .NET | Desplegar un servicio .NET | Configurar paquetes de compilación de .NET |
| Ruby | Desplegar un servicio de Ruby | Configurar buildpacks de Ruby |
| PHP | Desplegar un servicio PHP | Configurar buildpacks de PHP |
Consulta más información sobre las versiones de idiomas admitidas.
Desplegar desde el origen con compilación
En esta sección se describe cómo usar los paquetes de compilación de Google Cloud y Cloud Build para crear automáticamente imágenes de contenedor a partir de tu código fuente sin tener que instalar Docker en tu máquina ni configurar paquetes de compilación o Cloud Build.
Limitaciones
- La implementación desde el código fuente usa Artifact Registry y Cloud Build, por lo que esta función solo está disponible en las regiones admitidas por Artifact Registry y Cloud Build.
- La implementación desde el código fuente es una función práctica que no permite personalizar completamente la compilación. Para tener más control, crea la imagen de contenedor con Cloud Build, por ejemplo, con
gcloud builds submit, y luego despliega la imagen de contenedor congcloud run deploy --image, por ejemplo. - Al implementar desde una fuente con los buildpacks de Google Cloud, la fecha de última modificación de los archivos de origen se establece en el 1 de enero de 1980. Este es el comportamiento predeterminado de los buildpacks y se ha diseñado para admitir compilaciones reproducibles. En función de tu framework de lenguaje, esto puede afectar al almacenamiento en caché del lado del navegador de los archivos estáticos. Si tu aplicación se ve afectada por este problema, Google recomienda inhabilitar los encabezados HTTP
etagyLast-Modifieden tu aplicación. - Al desplegar desde una fuente con los buildpacks de Google Cloud, siempre se usa
gcr.io/buildpacks/builder:latest. Si el idioma o la configuración del SO que prefieres no están disponibles enlatest, usa un compilador específico para crear una imagen de aplicación con el compilador que prefieras. Puedes desplegar tu servicio desde la fuente con Kotlin y otros lenguajes de JVM, como Java. El idioma que utilices debe cumplir las siguientes reglas:
- Puedes compilar la aplicación con Maven o Gradle.
- El archivo de compilación contiene todos los complementos necesarios para las clases de producto.
Antes de implementar con compilación
Antes de implementar desde la fuente con compilación:
Sigue los pasos que se indican en la sección Antes de empezar.
-
Enable the Cloud Build API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.
Roles obligatorios
Para implementar desde una fuente con compilación, tú o tu administrador debéis conceder los siguientes roles de gestión de identidades y accesos a la cuenta de servicio de Cloud Build.
Haz clic para ver los roles necesarios de la cuenta de servicio de Cloud Build
Cloud Build usa automáticamente la cuenta de servicio predeterminada de Compute Engine como cuenta de servicio predeterminada de Cloud Build para compilar tu código fuente y tu recurso de Cloud Run, a menos que anules este comportamiento. Para que Cloud Build compile tus fuentes, pide a tu administrador que conceda el rol Compilador de Cloud Run (roles/run.builder) a la cuenta de servicio predeterminada de Compute Engine de tu proyecto:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \ --role=roles/run.builder
Sustituye PROJECT_NUMBER por el número de tu proyecto Google Cloud
y PROJECT_ID por el ID de tu proyecto Google Cloud. Para obtener instrucciones detalladas sobre cómo encontrar el ID y el número de tu proyecto, consulta el artículo Crear y gestionar proyectos.
La concesión del rol de compilador de Cloud Run a la cuenta de servicio predeterminada de Compute Engine tarda un par de minutos en propagarse.
Para ver una lista de los roles y permisos de gestión de identidades y accesos asociados a Cloud Run, consulta los artículos Roles de gestión de identidades y accesos de Cloud Run y Permisos de gestión de identidades y accesos de Cloud Run. Si tu servicio de Cloud Run interactúa con APIs, como las bibliotecas de cliente de Cloud, consulta la guía de configuración de la identidad del servicio.Google Cloud Para obtener más información sobre cómo conceder roles, consulta los permisos de implementación y el artículo sobre cómo gestionar el acceso.
Desplegar con compilación
Para implementar desde el código fuente, haga clic en la pestaña correspondiente a las instrucciones para usar la herramienta que prefiera.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Cambia al directorio de origen. El directorio de origen usa un Dockerfile si está presente, aunque no es obligatorio.
Compila y despliega el servicio:
gcloud run deploy SERVICE --source .
Sustituye
SERVICEpor el nombre que quieras darle al servicio.Responde a las peticiones para instalar las APIs necesarias con
ycuando se te solicite. Solo tienes que hacerlo una vez por proyecto. Responde a otras peticiones proporcionando la plataforma y la región, si no has definido valores predeterminados para estos elementos tal como se describe en la página de configuración.Espera a que se complete la compilación y la implementación. Cuando termine, Cloud Run mostrará un mensaje de confirmación.
Instala la última versión de Gemini CLI en uno de los siguientes entornos de desarrollo:
- Terminal
- Cloud Shell
- VS Code con el modo agente de Gemini Code Assist (consulta la pestaña "VS Code")
Instala la extensión Cloud Run:
gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp
Inicia sesión en Google Cloud CLI:
gcloud auth login
Configura las credenciales predeterminadas de la aplicación:
gcloud auth application-default login
Cambia al directorio de tu código fuente.
Inicia Gemini CLI:
gemini
Compila y despliega el servicio:
/deploy
- Si se te pide que proporciones el Google Cloud proyecto, introduce el nombre del proyecto.
- Si se te pide que selecciones una herramienta, elige
deploy_local_folder.
Espera a que se complete la compilación y la implementación. Cuando termine, Cloud Run mostrará un mensaje de confirmación.
Cambia al directorio de origen. El directorio de origen usa un Dockerfile si está presente, aunque no es obligatorio.
En el directorio de tu proyecto, crea un archivo
compose.yamlcon tus definiciones de servicio.services: web: build: . ports: - "8080:8080"
También puedes especificar más opciones de configuración, como variables de entorno, secretos y montajes de volúmenes.
Para desplegar los servicios, ejecuta el comando
gcloud beta run compose up:gcloud beta run compose up compose.yamlResponde
ya las peticiones para instalar los componentes necesarios o habilitar las APIs.Opcional: Haz público tu servicio si quieres permitir el acceso sin autenticación al servicio.
Después del despliegue, esta revisión del servicio recibe el 100 % del tráfico.
Cloud Code
Para desplegar desde el código fuente con Cloud Code, consulta las guías de IntelliJ y Visual Studio Code.
Gemini CLI
Usa el comando /deploy en la herramienta Gemini CLI para desplegar un servicio de Cloud Run desde el código fuente.
Para usar la CLI de Gemini con la extensión de Cloud Run, sigue estos pasos:
MCP
Para desplegar un servicio de Cloud Run desde el código fuente de un cliente de Model Context Protocol (MCP), instala el servidor de Model Context Protocol (MCP) de Cloud Run.
Las instrucciones de instalación varían en función del cliente de MCP. A menudo, requieren que se añadan las siguientes líneas al archivo JSON de configuración:
"mcpServers":{ "cloud-run": { "command": "npx", "args": ["-y", "@google-cloud/cloud-run-mcp"] } }
Redactar
Puedes almacenar tu especificación de Compose en un archivo YAML y, a continuación, desplegarlo desde el código fuente como un servicio de Cloud Run con un solo comando de gcloud.
Después de la implementación, se muestra la URL del servicio de Cloud Run. Copia esta URL y pégala en el navegador para ver el contenedor en ejecución. Puedes inhabilitar la autenticación predeterminada desde la consola Google Cloud .
Desplegar desde el origen sin compilación
Puedes desplegar artefactos de origen directamente en Cloud Run, sin tener que pasar por el paso de Cloud Build. En lugar de crear una imagen de contenedor a partir del código fuente, puedes subir un archivo preempaquetado de tu aplicación directamente a un segmento de Cloud Storage. Cloud Run toma este archivo y lo ejecuta directamente en una imagen base. Este enfoque permite reducir drásticamente los tiempos de implementación.
Limitaciones
La opción de implementar en la fuente sin compilación solo admite lo siguiente:
- Servicios de Cloud Run.
- Entornos de ejecución compatibles (no se admite Dockerfile).
- El archivo de origen (.tar.gz) no debe superar los 250 MiB.
- El archivo binario (por ejemplo, un archivo binario de Go) o la secuencia de comandos (por ejemplo, una secuencia de comandos de Python) deben ser compatibles con la arquitectura x86.
- La fuente debe ser autónoma y tener todas las dependencias empaquetadas. La imagen base del tiempo de ejecución solo contiene el sistema operativo mínimo y algunas bibliotecas de idiomas.
Antes de implementar sin compilación
Para usar la función "Implementar sin compilación", sigue estos pasos:
- Asegúrate de que has seguido los pasos de la sección Antes de empezar.
Habilita las APIs Cloud Run y Cloud Storage:
gcloud services enable run.googleapis.com \ storage.googleapis.com
Debes instalar las dependencias de la aplicación de forma local antes de desplegarla, ya que no se instalarán (no se compilará).
Implementar sin compilación
En esta sección se describe cómo desplegar tu artefacto directamente en Cloud Run sin usar la compilación.
gcloud
Para desplegar un directorio de origen local, usa la marca --no-build para indicar al comando deploy que omita el paso de Cloud Build:
gcloud beta run deploy SERVICE_NAME \ --source APPLICATION_PATH \ --no-build \ --base-image=BASE_IMAGE \ --command=COMMAND \ --args=ARG
Haz los cambios siguientes:
SERVICE_NAME: el nombre de tu servicio de Cloud Run.APPLICATION_PATH: la ubicación de tu aplicación en el sistema de archivos local.BASE_IMAGE: la imagen base del tiempo de ejecución que quieras usar en tu aplicación. Por ejemplo,us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24.COMMAND: el comando con el que se inicia el contenedor.ARG: un argumento que envías al comando container. Si usas varios argumentos, especifica cada uno en una línea distinta.
YAML
Puedes almacenar la especificación del servicio en un archivo YAML y, a continuación, desplegarlo con la CLI de gcloud o el editor de la consola Google Cloud service.yaml.
Crea un segmento de almacenamiento para alojar tu aplicación:
gcloud storage buckets create gs://BUCKET_NAME --location=BUCKET_LOCATION
Haz los cambios siguientes:
BUCKET_NAME: el nombre que quieras asignar al segmento, sujeto a los requisitos de nomenclatura. Por ejemplo,my-bucket.BUCKET_LOCATION: la ubicación de tu segmento. Por ejemplo,US.
Crea un archivo con el origen de tu aplicación usando zip o tar. Por ejemplo:
tar -cvzf ARCHIVE_NAME APPLICATION_PATH
Haz los cambios siguientes:
ARCHIVE_NAME: el nombre del archivo que se va a crear. Por ejemplo,app.tar.gz.APPLICATION_PATH: la ubicación de tu aplicación en el sistema de archivos local. Por ejemplo,~/my-application. Para archivar el directorio de trabajo actual, asigna el valor*.
Sube el archivo de tu aplicación a Cloud Storage:
gcloud storage cp ARCHIVE_NAME gs://BUCKET_NAME
Haz los cambios siguientes:
ARCHIVE_NAME: la ruta local al archivo que has creado anteriormente. Por ejemplo,app.tar.gz.BUCKET_NAME: el nombre del segmento que has creado anteriormente. Por ejemplo,my-bucket.
Crea un archivo
service.yamlcon el siguiente contenido:apiVersion: serving.knative.dev/v2 kind: Service metadata: name: SERVICE_NAME spec: template: metadata: annotations: run.googleapis.com/sources: '{"": "gs://BUCKET_NAME/ARCHIVE_NAME"}' run.googleapis.com/base-images: '{"": "BASE_IMAGE"}' spec: containers: - image: scratch command: - COMMAND args: - ARG1 - ARG-N runtimeClassName: run.googleapis.com/linux-base-image-updateHaz los cambios siguientes:
SERVICE_NAME: el nombre de tu servicio de Cloud Run. Los nombres de servicio deben tener 49 caracteres como máximo y ser únicos por región y proyecto.BUCKET_NAME: el nombre del segmento que has creado anteriormente. Por ejemplo,my-bucket.ARCHIVE_NAME: la ruta local al archivo que has creado anteriormente. Por ejemplo,app.tar.gz.BASE_IMAGE: la imagen base del tiempo de ejecución que quieras usar en tu aplicación. Por ejemplo,us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24.COMMAND: el comando con el que se va a iniciar el contenedor.ARG1: el argumento que envías al comando del contenedor. Si usas varios argumentos, especifica cada uno en su propia línea, como se muestra en el ejemploARG-N.
Despliega el nuevo servicio:
gcloud run services replace service.yaml
API REST
API REST:
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-d '{"template": {"containers": [{"command": ["npm"], "args": ["start"], "image": "scratch", "baseImageUri": "google-22/nodejs22", "sourceCode": {"cloudStorageSource": {"bucket": "'GCS_BUCKET_NAME", "object":"ARCHIVE"}}}]}}' \
https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services?serviceId=SERVICE_NAME
Ejemplos de despliegue desde el código fuente sin compilación
En esta sección se muestran ejemplos de cómo implementar desde la fuente sin usar compilaciones.
Node.js
Crea un servicio de Node.js:
Crea un directorio llamado
helloworldy cambia al directorio:mkdir helloworld cd helloworld
Crea un archivo
package.jsoncon el siguiente contenido:En el mismo directorio, crea un archivo
index.jsy copia las siguientes líneas en él:Este código crea un servidor web básico que escucha el puerto definido por la variable de entorno
PORT.En el directorio
helloworld, ejecuta el siguiente comando para instalar las dependencias del servicio de forma local:npm install
En el directorio
helloworld, despliega el servicio con la marca--no-build, que indica al comandodeployque omita el paso de Cloud Build:gcloud beta run deploy helloworld \ --source . \ --region=REGION \ --no-build \ --base-image=nodejs24 \ --command=node \ --args=index.js
Haz los cambios siguientes:
REGION: la región en la que se ha implementado tu servicio.
Python
Crea un servicio de Python:
Crea un directorio llamado
helloworldy cambia al directorio:mkdir helloworld cd helloworldCrea un archivo llamado
main.pyy pega el siguiente código en él:Este código responde a las solicitudes con nuestro saludo "Hola, mundo". El contenedor gestiona HTTP con un servidor web Gunicorn. Cuando se invoca directamente para usarse de forma local, este código crea un servidor web básico que escucha el puerto definido por la variable de entorno
PORT.Crea un archivo llamado
requirements.txty pega el siguiente código en él:Este código añade los paquetes que necesita el ejemplo.
Incluye las dependencias:
pip3 install -r requirements.txt --target=./vendor
Despliega el servicio con la CLI de gcloud. La marca
--no-buildindica al comandodeployque omita el paso de Cloud Build:gcloud beta run deploy helloworld \ --source . \ --region=REGION \ --no-build \ --base-image=python313 \ --command=python \ --args=main.py \ --set-env-vars PYTHONPATH=./vendor
Sustituye REGION por la región en la que se ha desplegado tu servicio.
Solución de problemas
En esta sección se ofrecen algunos consejos para solucionar problemas de implementación desde la fuente sin usar la compilación.
Desarrollo local
El despliegue desde el código fuente sin usar compilación funciona de forma similar a montar el código o el ejecutable en la imagen base.
Por ejemplo:
Hacer una copia de todo el contenido:
cp -R python/hello-world/ workspace
Ejecuta la imagen base como usuario raíz con la fuente montada. También puedes incluir
-p 8080:8080si necesitas usar curl desde un equipo host.docker run -it -v "LOCAL_PATH" -u 0 us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/python313 /bin/bash`
Sustituye LOCAL_PATH por la ubicación de tus archivos de origen locales.
Ejecuta el servidor:
python main.py
Registro de ejecución
El registro de ejecución es útil para depurar fallos de implementación. En la Google Cloud consola, ve a Observabilidad > Registros.
Permiso denegado para acceder a Cloud Storage
Si tu servicio de Cloud Run recibe errores de "Permiso denegado" al intentar acceder a objetos de Cloud Storage, debes asignar el rol roles/storage.objectViewer a la cuenta de servicio de Cloud Run:
gcloud projects add-iam-policy-binding PROJECT \ --member="SERVICE_ACCOUNT" \ --role="roles/storage.objectViewer"
Haz los cambios siguientes:
- PROJECT: tu ID de proyecto Google Cloud .
- SERVICE_ACCOUNT: tu cuenta de servicio de Cloud Run.
Por ejemplo,
service-123@serverless-robot-staging.iam.gserviceaccount.com.
Automatizar la compilación a partir del código fuente
Para evitar cambios sin control de versiones en el código fuente local, Google recomienda que despliegues automáticamente cuando se inserten cambios en tu repositorio de Git. Para que te resulte más fácil, puedes conectar y configurar la implementación continua en tu servicio de Cloud Run. Si conectas tus repositorios de GitHub a Cloud Run, puedes configurar compilaciones y desplegar tus repositorios sin escribir Dockerfiles ni archivos de compilación.
Para configurar las compilaciones automatizadas, configure la automatización tal como se describe en la página de compilaciones continuas. Asegúrese de elegir la opción para compilar la fuente con buildpacks.Siguientes pasos
Después de desplegar un servicio de Cloud Run, puedes hacer lo siguiente:
- Lanzamientos graduales, restauraciones de revisiones y migración de tráfico
- Ver registros de servicio
- Monitorizar el rendimiento de los servicios
- Definir límites de memoria
- Definir variables de entorno
- Cambiar la simultaneidad del servicio
- Gestionar el servicio
- Gestionar revisiones de servicios
Consulta información sobre las configuraciones de implementación de origen:
- Actualizaciones automáticas de la imagen base
- Variables de entorno de compilación
- Cuenta de servicio de compilación
- Grupos de trabajadores de Cloud Build
Puedes automatizar las compilaciones y los despliegues de tus servicios de Cloud Run con activadores de Cloud Build: