Implementa servicios desde el código fuente

En esta página, se describe cómo implementar un servicio nuevo o una revisión del servicio en Cloud Run directamente desde el código fuente con un solo comando de gcloud CLI, gcloud run deploy, con la marca --source. Para ver una explicación de ejemplo de cómo implementar un servicio de Hello World, consulta Implementa desde guías de inicio rápido de origen.

Existen dos maneras diferentes de usar esta función:

Ten en cuenta que las implementaciones de origen usan Artifact Registry para almacenar 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 realizas la implementación, esta función crea de forma automática 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 paquetes de compilación de Google Cloud detectan automáticamente el idioma que estás usando y recuperan las dependencias del código para crear una imagen de contenedor lista para la producción con una imagen base segura administrada por Google.

De forma predeterminada, las correcciones de seguridad solo se aplican cuando se implementa el servicio de Cloud Run. Cuando habilitas las actualizaciones de seguridad automáticas para un servicio, este recibe parches automáticamente sin tiempo de inactividad. Obtén más información para configurar las actualizaciones de seguridad.

Antes de comenzar

  • Asegúrate de haber configurado un proyecto nuevo para Cloud Run, como se describe en la página de configuración.

  • Si estás bajo una política de la organización de restricción de dominios que restringe las invocaciones no autenticadas para tu proyecto, deberás acceder al servicio implementado como se describe en Prueba 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

    Después de habilitar la API de Cloud Run Admin, se crea automáticamente la cuenta de servicio predeterminada de Compute Engine.

Roles obligatorios

Para implementar desde la fuente, tú o tu administrador deben otorgar a la cuenta del implementador los siguientes roles de IAM.

Haz clic para ver los roles necesarios para la cuenta del implementador

Para obtener los permisos que necesitas para compilar e implementar desde la fuente, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Para obtener una lista de los roles y los permisos de IAM asociados con Cloud Run, consulta los roles de IAM de Cloud Run y los permisos de IAM de Cloud Run. Si tu servicio de Cloud Run interactúa con lasGoogle Cloud APIs, como las bibliotecas cliente de Cloud, consulta la guía de configuración de identidades del servicio. Para obtener más información sobre cómo otorgar roles, consulta los permisos de implementación y cómo administrar el acceso.

Idiomas compatibles

Además de las fuentes con un Dockerfile, la implementación desde el origen admite los siguientes lenguajes con los paquetes de compilación de Google Cloud:

Entorno de ejecución Implementación de la fuente Configuración del paquete de compilación
Go Implementa un servicio de Go Cómo configurar buildpacks de Go
Node.js Implementa un servicio de Node.js Configura paquetes de compilación de Node.js
Python Implementa un servicio de Python Configura buildpacks de Python
Java
(incluye Kotlin, Groovy y Scala)		 Implementa un servicio de Java Configura buildpacks de Java
.NET Implementa un servicio de .NET Configura los buildpacks de .NET
Ruby Implementa un servicio de Ruby Cómo configurar buildpacks de Ruby
PHP Implementa un servicio de PHP Configura buildpacks de PHP

Obtén más información sobre las versiones de lenguajes compatibles.

Implementa desde la fuente con compilación

En esta sección, se describe cómo usar 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 los paquetes de compilación o Cloud Build.

Limitaciones

  • La implementación desde la fuente usa Artifact Registry y Cloud Build, por lo que esta función solo está disponible en las regiones compatibles con Artifact Registry y Cloud Build.
  • La implementación desde el código fuente es una función práctica y no permite la personalización completa de la compilación. Para obtener más control, compila la imagen del contenedor con Cloud Build, por ejemplo, con gcloud builds submit y, luego, implementa la imagen del contenedor con, por ejemplo, gcloud run deploy --image.
  • La implementación desde la fuente con los paquetes de compilación de Google Cloud establece la última fecha de modificación de los archivos de origen en el 1 de enero de 1980. Este es el comportamiento predeterminado de los paquetes de compilación y está diseñado para admitir compilaciones reproducibles. Según el framework del idioma, esto puede afectar el almacenamiento en caché del archivo estático del navegador. Si tu aplicación se ve afectada, Google recomienda inhabilitar los encabezados HTTP etag y Last-Modified en tu aplicación.
  • La implementación desde el origen con los paquetes de compilación de Google Cloud siempre usa gcr.io/buildpacks/builder:latest. Si tu lenguaje o configuración del SO preferido no están disponibles en latest, usa un compilador específico para crear una imagen de la aplicación con tu compilador preferido.

  • Puedes implementar tu servicio desde la fuente con Kotlin y otros lenguajes de JVM, como Java. El idioma que uses debe cumplir con las siguientes reglas:

    • Puedes compilar la aplicación a través de Maven o Gradle.
    • El archivo de compilación contiene todos los complementos necesarios para las clases de productos.

Antes de realizar la implementación con compilación

Antes de realizar la implementación desde la fuente con compilación, haz lo siguiente:

  • Sigue los pasos que se indican en Antes de comenzar.

  • 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 realizar la implementación desde la fuente con compilación, tú o tu administrador deben otorgar a la cuenta de servicio de Cloud Build los siguientes roles de IAM.

Haz clic para ver los roles necesarios para la cuenta de servicio de Cloud Build

Cloud Build usa automáticamente la cuenta de servicio predeterminada de Compute Engine como la cuenta de servicio predeterminada de Cloud Build para compilar tu código fuente y el recurso de Cloud Run, a menos que anules este comportamiento. Para que Cloud Build pueda compilar tus fuentes, pídele a tu administrador que otorgue el rol de Compilador de Cloud Run (roles/run.builder) a la cuenta de servicio predeterminada de Compute Engine en tu proyecto:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --role=roles/run.builder

Reemplaza PROJECT_NUMBER por el número de tu proyecto de Google Cloudy PROJECT_ID por el ID del proyecto de Google Cloud. Para obtener instrucciones detalladas sobre cómo encontrar el ID y el número de tu proyecto, consulta Crea y administra proyectos.

El otorgamiento del rol de compilador de Cloud Run a la cuenta de servicio predeterminada de Compute Engine tarda un par de minutos en propagarse.

Para obtener una lista de los roles y los permisos de IAM asociados con Cloud Run, consulta los roles de IAM de Cloud Run y los permisos de IAM de Cloud Run. Si tu servicio de Cloud Run interactúa con lasGoogle Cloud APIs, como las bibliotecas cliente de Cloud, consulta la guía de configuración de identidades del servicio. Para obtener más información sobre cómo otorgar roles, consulta los permisos de implementación y cómo administrar el acceso.

Implementa con la compilación

Para realizar la implementación desde el código fuente, haz clic en la pestaña para obtener instrucciones sobre cómo usar la herramienta que elijas.

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 del código fuente. El directorio del código fuente usa un Dockerfile si está presente, aunque no es obligatorio.

  3. Compila e implementa tu servicio:

    gcloud run deploy SERVICE --source .

    Reemplaza SERVICE por el nombre que deseas usar para el servicio.

  4. Responde a cualquier solicitud para instalar las API obligatorias. Para ello, responde y cuando se te solicite. Solo debes hacer esto una vez en un proyecto. Para responder a otras solicitudes, suministra la plataforma y la región si no configuraste los valores predeterminados de estas como se describe en la página de configuración.

  5. Espera a que se completen la compilación y la implementación. Cuando finalice, Cloud Run mostrará un mensaje de éxito.

    6. Después de la implementación, esta revisión del servicio entrega el 100% del tráfico.

    Cloud Code

    Para realizar la implementación desde la fuente con Cloud Code, consulta las guías de IntelliJ y Visual Studio Code.

    CLI de Gemini

    Usa el comando /deploy en la herramienta de Gemini CLI para implementar un servicio de Cloud Run desde el código fuente.

    Para usar Gemini CLI con la extensión de Cloud Run, sigue estos pasos:

    1. Instala la versión más reciente de la Gemini CLI en uno de los siguientes entornos de desarrollo:

      • Terminal
      • Cloud Shell
      • VS Code con el modo de agente de Gemini Code Assist (consulta la pestaña "VS Code")

    2. Instala la extensión de Cloud Run:

      gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp

    3. Accede a Google Cloud CLI:

      gcloud auth login

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

      gcloud auth application-default login

    5. Cambia al directorio del código fuente.

    6. Inicia Gemini CLI:

      gemini

    7. Compila e implementa tu servicio:

      /deploy
      • Si se te solicita que proporciones el proyecto Google Cloud , ingresa el nombre de tu proyecto.
      • Si se te solicita que selecciones una herramienta, elige deploy_local_folder.

    8. Espera a que se completen la compilación y la implementación. Cuando finalice, Cloud Run mostrará un mensaje de éxito.

    MCP

    Para implementar un servicio de Cloud Run desde el código fuente de un cliente del Protocolo de contexto del modelo (MCP), instala el servidor del Protocolo de contexto del modelo (MCP) de Cloud Run.

    Las instrucciones de instalación varían según el cliente de MCP. A menudo, requieren que se agreguen 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, luego, implementarla desde el código fuente como un servicio de Cloud Run con un solo comando de gcloud.

    1. Cambia al directorio del código fuente. El directorio del código fuente usa un Dockerfile si está presente, aunque no es obligatorio.

    2. En el directorio de tu proyecto, crea un archivo compose.yaml con las definiciones de tu servicio.

      services:
  web:
    build: .
    ports:
      - "8080:8080"

      También puedes especificar más opciones de configuración, como variables de entorno, secretos y activaciones de volúmenes.

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

      gcloud beta run compose up compose.yaml

    4. Responde y a cualquier solicitud para instalar los componentes obligatorios o habilitar las APIs.

    5. Opcional: Haz que tu servicio sea público si deseas permitir el acceso sin autenticación.

    Después de la implementación, se muestra la URL del servicio de Cloud Run. Copia esta URL y pégala en tu navegador para ver el contenedor en ejecución. Puedes inhabilitar la autenticación predeterminada desde la consola de Google Cloud .

Implementa desde la fuente sin compilar

Puedes implementar artefactos de código fuente directamente en Cloud Run, sin pasar por el paso de Cloud Build. En lugar de compilar una imagen de contenedor a partir del código fuente, puedes subir un archivo preempaquetado de tu aplicación directamente a un bucket de Cloud Storage. Luego, Cloud Run toma este archivo y lo ejecuta directamente en una imagen base. Este enfoque genera tiempos de implementación mucho más rápidos.

Limitaciones

La implementación 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 fuente (.tar.gz) debe ser menor o igual a 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.
  • El código fuente debe ser independiente y tener todas las dependencias empaquetadas. La imagen base del entorno de ejecución solo contiene el sistema operativo mínimo y algunas bibliotecas de lenguaje.

Antes de realizar la implementación sin compilación

Para usar la función "Deploy without build", sigue estos pasos:

  • Asegúrate de haber seguido los pasos que se indican en Antes de comenzar.

  • Habilita las APIs de 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 la implementación, ya que no se instalarán (no hay compilación).

Implementar sin compilar

En esta sección, se describe cómo implementar tu artefacto directamente en Cloud Run sin usar la compilación.

gcloud

Para implementar un directorio del código fuente local, usa la marca --no-build para indicarle 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

Reemplaza lo siguiente:

  • SERVICE_NAME: el nombre de tu servicio de Cloud Run.
  • APPLICATION_PATH: Es la ubicación de tu aplicación en el sistema de archivos local.
  • BASE_IMAGE: Es la imagen base del entorno de ejecución que deseas usar para tu aplicación. Por ejemplo, us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24.
  • COMMAND: Es el comando con el que se inicia el contenedor.
  • ARG: Es un argumento que envías al comando del contenedor. Si usas varios argumentos, especifica cada uno en su propia línea.

YAML

Puedes almacenar la especificación de servicio en un archivo YAML y, luego, implementarla con gcloud CLI o el editor de la consola de Google Cloud service.yaml.

  1. Crea un bucket de almacenamiento para contener tu aplicación:

    gcloud storage buckets create gs://BUCKET_NAME --location=BUCKET_LOCATION

    Reemplaza lo siguiente:

    • BUCKET_NAME: Es el nombre que quieres asignar a tu bucket, sujeto a los requisitos de nomenclatura. Por ejemplo, my-bucket.
    • BUCKET_LOCATION: La ubicación de tu bucket. Por ejemplo, US.

  2. Crea un archivo con el código fuente de tu aplicación usando zip o tar, por ejemplo:

    tar -cvzf ARCHIVE_NAME APPLICATION_PATH

    Reemplaza lo siguiente:

    • ARCHIVE_NAME: Es el nombre del archivo que se creará. Por ejemplo, app.tar.gz
    • APPLICATION_PATH: Es la ubicación de tu aplicación en el sistema de archivos local. Por ejemplo, ~/my-application Para archivar el directorio de trabajo actual, establece este valor en *.

  3. Sube el archivo de tu aplicación a Cloud Storage:

    gcloud storage cp ARCHIVE_NAME gs://BUCKET_NAME

    Reemplaza lo siguiente:

    • ARCHIVE_NAME: Es la ruta de acceso local al archivo que creaste anteriormente. Por ejemplo, app.tar.gz
    • BUCKET_NAME: Es el nombre del bucket que creaste anteriormente. Por ejemplo, my-bucket

  4. Crea un archivo nuevo 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

    Reemplaza lo siguiente:

    • SERVICE_NAME: el nombre de tu servicio de Cloud Run. Los nombres de servicios deben tener 49 caracteres o menos, y deben ser únicos por región y proyecto.
    • BUCKET_NAME: Es el nombre del bucket que creaste anteriormente. Por ejemplo, my-bucket
    • ARCHIVE_NAME: Es la ruta de acceso local al archivo que creaste anteriormente. Por ejemplo, app.tar.gz.
    • BASE_IMAGE: Es la imagen base del tiempo de ejecución que deseas usar para tu aplicación. Por ejemplo, us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24
    • COMMAND: Es el comando con el que se iniciará el contenedor.
    • ARG1: Es el argumento que envías al comando del contenedor. Si usas varios argumentos, especifica cada uno en su propia línea, por ejemplo, como se muestra, ARG-N.

  5. Implementa el servicio nuevo:

    gcloud run services replace service.yaml

API de REST

API de 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 implementación desde la fuente sin compilación

En esta sección, se muestran ejemplos de cómo realizar la implementación desde el código fuente sin usar la compilación.

Node.js

Crea un servicio de Node.js:

  1. Crea un directorio nuevo llamado helloworld y usa el comando de cambio de directorio en él:

    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}`);
});

    Con este código, se crea un servidor web básico que escucha en el puerto definido por la variable de entorno PORT.

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

    npm install

  5. En tu directorio helloworld, implementa el servicio con la marca --no-build, que le 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

    Reemplaza lo siguiente:

    • REGION: Es la región en la que se implementa tu servicio.

Python

Crea un servicio de Python:

  1. Crea un directorio nuevo llamado helloworld y usa el comando de cambio de directorio en él:

    mkdir helloworld
cd helloworld

  2. Crea un archivo llamado main.py y pega el código siguiente 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 “Hello World”. El control de HTTP lo realiza un servidor web de Gunicorn en el contenedor. Cuando se invoca directamente para uso local, este código crea un servidor web básico que escucha en el puerto definido por la variable de entorno PORT.

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

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

    Este código agrega los paquetes que necesita la muestra.

  4. Incluye las dependencias del proveedor:

    pip3 install -r requirements.txt --target=./vendor

  5. Implementa el servicio con gcloud CLI. La marca --no-build le 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

Reemplaza REGION por la región en la que se implementó tu servicio.

Soluciona problemas

En esta sección, se proporcionan algunas sugerencias para solucionar problemas de la implementación desde la fuente sin usar la compilación.

Desarrollo local

La implementación desde el código fuente sin usar la compilación funciona de manera similar a la instalación de tu código o ejecutable en la imagen base.

Por ejemplo:

  1. Crea una copia de todo el contenido:

    cp -R python/hello-world/ workspace

  2. Ejecuta la imagen base como usuario raíz con la fuente activada. De manera opcional, puedes incluir -p 8080:8080 si necesitas usar curl desde una máquina anfitrión.

    docker run -it -v "LOCAL_PATH" -u 0 us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/python313 /bin/bash`

    Reemplaza LOCAL_PATH por la ubicación de tus archivos fuente locales.

  3. Ejecuta el servidor:

    python main.py

Registro de ejecución

El registro de ejecución es útil para depurar errores de implementación. En la consola deGoogle Cloud , ve a Observabilidad > Registros.

Se denegó el permiso de acceso a Cloud Storage

Si tu servicio de Cloud Run encuentra errores de "Permiso denegado" cuando intenta acceder a objetos de Cloud Storage, debes otorgar el rol roles/storage.objectViewer a tu cuenta de servicio de Cloud Run:

gcloud projects add-iam-policy-binding PROJECT \
  --member="SERVICE_ACCOUNT" \
  --role="roles/storage.objectViewer"

Reemplaza lo siguiente:

  • PROJECT: El ID de tu proyecto Google Cloud .
  • SERVICE_ACCOUNT: Tu cuenta de servicio de Cloud Run. Por ejemplo, service-123@serverless-robot-staging.iam.gserviceaccount.com

Automatiza la compilación a partir del código fuente

Para evitar cambios sin versión en una fuente local, Google recomienda que implementes automáticamente cuando los cambios se envíen a tu repositorio de Git. Para facilitar esto, puedes conectar la implementación continua a tu servicio de Cloud Run y configurarla. Si conectas tus repositorios de GitHub a Cloud Run, puedes configurar compilaciones y, luego, implementar tus repositorios sin tener que escribir Dockerfiles o archivos de compilación.

Para configurar compilaciones automatizadas, configura la automatización como se describe en la página de compilaciones continuas, y asegúrate de elegir la opción para compilar fuentes con buildpacks.

¿Qué sigue?

Después de implementar un servicio de Cloud Run, puedes hacer lo siguiente:

Obtén más información sobre las opciones de configuración de la implementación de origen:

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