Desplegar servicios desde el código fuente

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.

Hay dos formas diferentes de usar esta función:

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 the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    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:

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 con gcloud 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 etag y Last-Modified en 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 en latest, 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 the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

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

  1. In the Google Cloud console, activate Cloud Shell.

    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.

  2. Cambia al directorio de origen. El directorio de origen usa un Dockerfile si está presente, aunque no es obligatorio.

  3. Compila y despliega el servicio:

    gcloud run deploy SERVICE --source .

    Sustituye SERVICE por el nombre que quieras darle al servicio.

  4. Responde a las peticiones para instalar las APIs necesarias con y cuando 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.

  5. Espera a que se complete la compilación y la implementación. Cuando termine, Cloud Run mostrará un mensaje de confirmación.

  6. 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:

    1. 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")
    2. Instala la extensión Cloud Run:

      gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp
    3. Inicia sesión en Google Cloud CLI:

      gcloud auth login
    4. Configura las credenciales predeterminadas de la aplicación:

      gcloud auth application-default login
    5. Cambia al directorio de tu código fuente.

    6. Inicia Gemini CLI:

      gemini
    7. 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.
    8. Espera a que se complete la compilación y la implementación. Cuando termine, Cloud Run mostrará un mensaje de confirmación.

    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.

    1. Cambia al directorio de origen. El directorio de origen usa un Dockerfile si está presente, aunque no es obligatorio.

    2. En el directorio de tu proyecto, crea un archivo compose.yaml con 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.

    3. Para desplegar los servicios, ejecuta el comando gcloud beta run compose up:

      gcloud beta run compose up compose.yaml
    4. Responde y a las peticiones para instalar los componentes necesarios o habilitar las APIs.

    5. Opcional: Haz público tu servicio si quieres permitir el acceso sin autenticación al servicio.

    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.

  1. 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.
  2. 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 *.
  3. 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.
  4. Crea un archivo service.yaml con 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-update
    

    Haz 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 ejemplo ARG-N.
  5. 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:

  1. Crea un directorio llamado helloworld y cambia al directorio:

    mkdir helloworld
    cd helloworld
    
  2. Crea un archivo package.json con el siguiente contenido:

    {
      "name": "helloworld",
      "description": "Simple hello world sample in Node",
      "version": "1.0.0",
      "private": true,
      "main": "index.js",
      "type": "module",
      "scripts": {
        "start": "node index.js"
      },
      "engines": {
        "node": ">=16.0.0"
      },
      "author": "Google LLC",
      "license": "Apache-2.0",
      "dependencies": {
        "express": "^4.17.1"
      }
    }
    
  3. En el mismo directorio, crea un archivo index.js y copia las siguientes líneas en él:

    import express from 'express';
    const app = express();
    
    app.get('/', (req, res) => {
      const name = process.env.NAME || 'World';
      res.send(`Hello ${name}!`);
    });
    
    const port = parseInt(process.env.PORT) || 8080;
    app.listen(port, () => {
      console.log(`helloworld: listening on port ${port}`);
    });

    Este código crea un servidor web básico que escucha el puerto definido por la variable de entorno PORT.

  4. En el directorio helloworld, ejecuta el siguiente comando para instalar las dependencias del servicio de forma local:

    npm install
  5. En el directorio helloworld, despliega el servicio con la marca --no-build, que indica al comando deploy que 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:

  1. Crea un directorio llamado helloworld y cambia al directorio:

    mkdir helloworld
    cd helloworld
    
  2. Crea un archivo llamado main.py y pega el siguiente código en él:

    import os
    
    from flask import Flask
    
    app = Flask(__name__)
    
    
    @app.route("/")
    def hello_world():
        """Example Hello World route."""
        name = os.environ.get("NAME", "World")
        return f"Hello {name}!"
    
    
    if __name__ == "__main__":
        app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

    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.

  3. Crea un archivo llamado requirements.txt y pega el siguiente código en él:

    Flask==3.0.3
    gunicorn==23.0.0
    Werkzeug==3.0.3
    

    Este código añade los paquetes que necesita el ejemplo.

  4. Incluye las dependencias:

    pip3 install -r requirements.txt --target=./vendor
    
  5. Despliega el servicio con la CLI de gcloud. La marca --no-build indica al comando deploy que 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:

  1. Hacer una copia de todo el contenido:

    cp -R python/hello-world/ workspace
  2. Ejecuta la imagen base como usuario raíz con la fuente montada. También puedes incluir -p 8080:8080 si 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.

  3. 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:

Consulta información sobre las configuraciones de implementación de origen:

Puedes automatizar las compilaciones y los despliegues de tus servicios de Cloud Run con activadores de Cloud Build: