Implementa funciones en Cloud Run

En esta página, se describe cómo implementar y modificar funciones en Cloud Run. Para ver una explicación de ejemplo de cómo implementar una función de Hello World, consulta Implementa una función de muestra.

En segundo plano, las implementaciones de funciones de Cloud Run usan los paquetes de compilación y Cloud Build de Google Cloud para compilar automáticamente imágenes de contenedor a partir del código fuente de tu función sin tener que instalar Docker en tu máquina ni configurar los paquetes de compilación o Cloud Build.

Las implementaciones de funciones de Cloud Run también usan Artifact Registry para almacenar artefactos y administrar imágenes de contenedores. Artifact Registry crea automáticamente el repositorio cloud-run-source-deploy de Artifact Registry si tu proyecto aún no creó uno con este nombre.

Antes de comenzar

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

  2. Habilita las APIs de Artifact Registry, Cloud Build, Cloud Run Admin y Cloud Logging:

     gcloud services enable artifactregistry.googleapis.com \
     cloudbuild.googleapis.com \
     run.googleapis.com \
     logging.googleapis.com

    De manera opcional, habilita la API de Eventarc para usar activadores de eventos:

     gcloud services enable eventarc.googleapis.com

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

Roles obligatorios

Tú o tu administrador deben otorgar a la cuenta del implementador y a la cuenta de servicio 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:

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 recurso de Cloud Run, a menos que anules este comportamiento. Para que Cloud Build compile tus fuentes, pídele a tu administrador que otorgue Creador 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 Google Cloud número de proyecto y PROJECT_ID por el Google Cloud ID del proyecto. 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 creador de Cloud Run a la cuenta de servicio predeterminada de Compute Engine tarda un par de minutos en propagarse.

Haz clic para ver los roles necesarios para la cuenta de servicio si usas Eventarc

De manera opcional, si usas Eventarc, otorga los siguientes roles a tu cuenta de servicio:

Para obtener más información sobre cómo otorgar roles específicos a tus activadores de Eventarc, consulta Roles y permisos para destinos de Cloud Run.

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 las APIs deGoogle Cloud , 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 permisos de implementación y administra el acceso.

Crea e implementa una función

Puedes implementar una función con la consola de Google Cloud o la CLI de gcloud. Haz clic en la pestaña para obtener instrucciones sobre el uso de la herramienta que elijas.

Console

  1. En la consola de Google Cloud, ve a la página Cloud Run:

    Ir a Cloud Run

  2. Haz clic en Escribe una función.

  3. En el campo Nombre del servicio, ingresa un nombre para describir tu función. Los nombres de servicios solo deben comenzar con una letra y contener hasta 49 caracteres o menos, incluidas letras, números o guiones. Los nombres de los servicios no pueden terminar con guiones y deben ser únicos por región y proyecto. Un nombre de servicio no se puede cambiar más adelante y es visible de forma pública.

  4. En la lista Región, usa el valor predeterminado o selecciona la región en la que quieres implementar la función.

  5. En la lista Entorno de ejecución, usa el valor predeterminado o selecciona una versión de entorno de ejecución.

  6. De manera opcional, en la sección Activador, haz clic en Agregar activador y selecciona una opción. Se abrirá el panel Activador de Eventarc, en el que podrás modificar los siguientes detalles del activador:

    1. En el campo Nombre del activador, ingresa un nombre para el activador o usa el nombre predeterminado.

    2. Selecciona un tipo de activador de la lista para especificar uno de los siguientes tipos de activador:

      • Fuentes de Google para especificar activadores para Pub/Sub, Cloud Storage, Firestore y otros proveedores de eventos de Google.

      • Personalizado para producir y consumir eventos desde el código de la aplicación. Sigue las instrucciones del panel Activador de Eventarc para crear un canal. Un canal es un recurso que se usa como una canalización para entregar eventos personalizados de los productores a los consumidores. Los eventos personalizados se publican en un canal y un activador de Eventarc se suscribe a esos eventos.

      • Terceros para integrarse a proveedores externos a Google que ofrecen una fuente de Eventarc. Para obtener más información, consulta Eventos de terceros en Eventarc.

    3. Selecciona un Proveedor de eventos de la lista para elegir un producto que proporcione el tipo de evento para activar tu función. Para ver la lista de proveedores de eventos, consulta Proveedores y destinos de eventos.

    4. Selecciona un Tipo de evento de la lista. La configuración del activador varía según el tipo de evento compatible. Para obtener más información, consulta Tipos de eventos.

    5. En el campo Región, selecciona una ubicación para el activador de Eventarc. En general, la ubicación de un activador de Eventarc debe coincidir con la ubicación del recurso de Google Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu función en la misma región. Consulta Información sobre las ubicaciones de Eventarc para obtener más detalles sobre las ubicaciones de activadores de Eventarc.

    6. En el campo Cuenta de servicio, selecciona una cuenta de servicio. Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca la función. La cuenta de servicio del activador de Eventarc debe tener el permiso para invocar tu función. De forma predeterminada, Cloud Run usa la cuenta de servicio predeterminada de Compute Engine.

    7. De manera opcional, especifica la ruta de URL del servicio a la que se enviará la solicitud entrante. Esta es la ruta de acceso relativa en el servicio de destino al que se deben enviar los eventos del activador. Por ejemplo, /, /route, route y route/subroute.

    8. Una vez que hayas completado los campos obligatorios, haz clic en Guardar activador.

  7. En Autenticación, configura lo siguiente:

    • Si creas una función HTTP pública, por ejemplo, un webhook, selecciona Permitir invocaciones no autenticadas. Si seleccionas esta opción, se asigna la función de invocador de IAM al identificador especial allUser. Puedes usar IAM para editar esta configuración más adelante una vez que hayas creado el servicio. Si no tienes permisos (rol de administrador de Cloud Run) para seleccionar esta opción, el servicio se implementará y requerirá autenticación.

    • Si creas una función activada por eventos, selecciona Solicitar autenticación.

  8. De manera opcional, actualiza la siguiente configuración adicional para tus funciones:

    1. Establece Facturación según sea necesario.

    2. En Ajuste de escala automático del servicio, especifica las instancias mínimas según sea necesario.

    3. Establece la configuración de Control de entrada según sea necesario.

    4. Expande la sección Contenedores, volúmenes, herramientas de redes y seguridad para establecer otra configuración opcional en las pestañas correspondientes:

  9. Haz clic en Crear y espera a que Cloud Run cree el servicio con una revisión de marcador de posición.

  10. La consola te redireccionará a la pestaña Fuente, en la que puedes ver el código fuente de tu función. Haz clic en Guardar y volver a implementar.

  11. En la pestaña Fuente, puedes hacer clic de manera opcional en Mostrar carga útil para ver una carga útil de ejemplo de los eventos entrantes.

  12. Después de la implementación, haz clic en el botón Probar para probar la función creada.

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. Actualiza los componentes de gcloud a la versión más reciente:

    gcloud components update

  3. Ejecuta el siguiente comando en el directorio que contiene el código de muestra:

    gcloud beta run deploy FUNCTION \
       --source . \
       --function FUNCTION_ENTRYPOINT \
       --base-image BASE_IMAGE \
       --region REGION

    Reemplaza lo siguiente:

    • Reemplaza FUNCTION por el nombre de la función que implementas. Puedes omitir este parámetro por completo, pero se te solicitará el nombre si lo haces.

    • FUNCTION_ENTRYPOINT por el punto de entrada a tu función en tu código fuente. Este es el código que ejecuta Cloud Run cuando se ejecuta tu función. El valor de esta marca debe ser un nombre de función o un nombre de clase completamente calificado que exista en tu código fuente.

    • BASE_IMAGE por el entorno de la imagen base de tu función. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base de los entornos de ejecución.

    • REGION con la Google Cloud región en la que deseas implementar tu función. Por ejemplo, us-central1.

    Opcional:

    • Si creas una función de HTTP pública, por ejemplo, un webhook, especifica la marca --allow-unauthenticated. Esta marca asigna el rol de invocador de IAM de Cloud Run al identificador especial allUser. Puedes usar IAM para editar esta configuración más adelante una vez que hayas creado el servicio. Si creas una función activada por eventos o un servicio autenticado, puedes omitir esta marca.

De manera opcional, después de implementar la función, puedes agregar activadores de Eventarc a ella. Para agregar un activador, ejecuta el siguiente comando:

  gcloud eventarc triggers create EVENTARC_TRIGGER_NAME \
      --location=EVENTARC_TRIGGER_LOCATION \
      --destination-run-service=FUNCTION \
      --destination-run-region=REGION \
      --event-filters="type=EVENTARC_FILTER_TYPE" \
      --event-filters="EVENTARC_EVENT_FILTER" \
      --service-account=EVENTARC_TRIGGER_SERVICE_ACCOUNT

Reemplaza lo siguiente:

  • EVENTARC_TRIGGER_NAME por el nombre del activador de Eventarc.

  • EVENTARC_TRIGGER_LOCATION por la ubicación del activador de Eventarc. En general, la ubicación de un activador de Eventarc debe coincidir con la ubicación del recurso de Google Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu función en la misma región. Consulta Información sobre las ubicaciones de Eventarc para obtener más detalles sobre las ubicaciones de activadores de Eventarc.

  • FUNCTION por el nombre de la función implementada.

  • REGION por la región de Cloud Run de la función.

  • EVENTARC_FILTER_TYPE con los filtros de eventos que supervisa el activador. Un evento que coincida con todos los filtros --event-filters activa llamadas a tu función. Cada activador debe tener un tipo de evento compatible con el formato --event-filters="type=EVENTARC_FILTER_TYPE". Este tipo de evento no se puede cambiar después de la creación. Para cambiar EVENT_FILTER_TYPE, crea un activador nuevo y borra el anterior. De manera opcional, puedes repetir la marca --event-filters con un filtro compatible en el formato ATTRIBUTE=VALUE para agregar más filtros.

  • EVENTARC_TRIGGER_SERVICE_ACCOUNT con una cuenta de servicio. Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca la función. La cuenta de servicio del activador de Eventarc debe tener el permiso para invocar tu función. De forma predeterminada, Cloud Run usa la cuenta de servicio de procesamiento predeterminada.

Terraform

Para administrar funciones con Terraform, debes compilar el código de tu función en una imagen de contenedor y, luego, definir tu servicio de Cloud Run en una configuración de Terraform con el recurso google_cloud_run_v2_service del proveedor de Google Cloud Platform.

  1. Sigue las instrucciones para compilar una función desde cero para crear una imagen de contenedor compatible con las actualizaciones de seguridad automáticas. Copia la ruta de acceso completa de la imagen del contenedor para la variable IMAGE_URL que se usará en el siguiente paso.

  2. Crea un archivo main.tf nuevo con este contenido:

    provider "google" {
  project = "PROJECT-ID"
}

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE"
  location = "REGION"
  client   = "terraform"
  template {
    containers {
      name = "SERVICE"
      image = "IMAGE_URL"
      base_image_uri = "BASE_IMAGE"
    }
  }
}
build_config{
  function_target = "FUNCTION_TARGET"
  image_uri = "IMAGE_URL"
  base_image = "BASE_IMAGE"
  enable_automatic_updates = true
}
resource "google_cloud_run_v2_service_iam_member" "noauth" {
  location = google_cloud_run_v2_service.default.location
  name     = google_cloud_run_v2_service.default.name
  role     = "roles/run.invoker"
  member   = "allUsers"
}

    Reemplaza lo siguiente:

    • PROJECT-ID por el Google Cloud ID del proyecto.
    • REGION con la región Google Cloud .
    • SERVICE por el nombre del servicio de Cloud Run Los nombres de servicios deben tener 49 caracteres o menos, y deben ser únicos por región y proyecto.
    • IMAGE_URL por una referencia a la imagen del contenedor, como us-docker.pkg.dev/cloudrun/container/hello:latest Si usas Artifact Registry, el repositorio REPO_NAME debe estar creado. La URL tiene el formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • BASE_IMAGE por una referencia a la imagen base, por ejemplo, us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/nodejs22:public-image-current. Consulta Imágenes base del entorno de ejecución para obtener la lista de entornos de ejecución compatibles y sus imágenes base.
    • FUNCTION_TARGET con el nombre de la función que deseas usar como punto de entrada.

    Esta configuración permite el acceso público (el equivalente a --allow-unauthenticated). Para que el servicio sea privado, quita la estrofa google_cloud_run_v2_service_iam_member.

  3. Inicializa Terraform mediante este comando:

    terraform init

  4. Aplica la configuración de Terraform:

    terraform apply

    Ingresa yes para confirmar que deseas aplicar las acciones descritas.

Ubicaciones de Cloud Run

Cloud Run es regional, lo que significa que la infraestructura que ejecuta los servicios se ubica en una región específica, y Google la administra para que esté disponible de manera redundante en todas las zonas de esa región.

El cumplimiento de los requisitos de latencia, disponibilidad o durabilidad es el factor principal para seleccionar la región en la que se ejecutan los servicios de Cloud Run. Por lo general, puedes seleccionar la región más cercana a los usuarios, pero debes considerar la ubicación de los otros productos Google Cloud que usa tu servicio de Cloud Run. Si usas Google Cloud productos en varias ubicaciones, la latencia y el costo del servicio pueden verse afectados.

Cloud Run está disponible en las siguientes regiones:

Sujetas a los Precios del nivel 1

Sujetas a los Precios del nivel 2

  • africa-south1 (Johannesburgo)
  • asia-east2 (Hong Kong)
  • asia-northeast3 (Seúl, Corea del Sur)
  • asia-southeast1 (Singapur)
  • asia-southeast2 (Yakarta)
  • asia-south2 Delhi (India)
  • australia-southeast1 (Sídney)
  • australia-southeast2 (Melbourne)
  • europe-central2 (Varsovia, Polonia)
  • europe-west10 (Berlín) ícono de hoja Bajo nivel de CO2
  • europe-west12 (Turín)
  • europe-west2 (Londres, Reino Unido) ícono de hoja Bajo nivel de CO2
  • europe-west3 (Fráncfort, Alemania) ícono de hoja Bajo nivel de CO2
  • europe-west6 (Zúrich, Suiza) ícono de hoja Bajo nivel de CO2
  • me-central1 (Doha)
  • me-central2 (Dammam)
  • northamerica-northeast1 (Montreal) ícono de hoja Bajo nivel de CO2
  • northamerica-northeast2 (Toronto) ícono de hoja Bajo nivel de CO2
  • southamerica-east1 (São Paulo, Brasil) ícono de hoja Bajo nivel de CO2
  • southamerica-west1 (Santiago, Chile) ícono de hoja Bajo nivel de CO2
  • us-west2 (Los Ángeles)
  • us-west3 (Salt Lake City)
  • us-west4 (Las Vegas)

Si ya creaste un servicio de Cloud Run, puedes ver la región en el panel de Cloud Run en la consola de Google Cloud.

Habilita los reintentos de eventos

Eventarc usa Pub/Sub como su capa de transporte y tiene una política de reintento predeterminada que podría no funcionar bien para tu función.

Después de crear un activador de Eventarc, te recomendamos actualizar la política de reintento en Eventarc y configurar el tema de buzón de destino en Pub/Sub.

Especifica un repositorio de imágenes

Las implementaciones de funciones de Cloud Run usan Artifact Registry para almacenar artefactos y administrar imágenes de contenedores. Artifact Registry crea automáticamente el repositorio REGION-docker.pkg.dev/PROJECT_ID/cloud-run-source-deploy de Artifact Registry si tu proyecto aún no creó uno con este nombre.

Para especificar un repositorio de Artifact Registry creado por ti, usa el siguiente comando:

gcloud 

gcloud beta run deploy FUNCTION \
  --source . \
  --function FUNCTION_ENTRYPOINT \
  --base-image BASE_IMAGE \
  --region REGION \
  --image IMAGE_URL

Reemplaza lo siguiente:

  • Reemplaza FUNCTION por el nombre de la función que implementas. Puedes omitir este parámetro por completo, pero se te solicitará el nombre si lo haces.

  • FUNCTION_ENTRYPOINT por el punto de entrada a tu función en tu código fuente. Este es el código que ejecuta Cloud Run cuando se ejecuta tu función. El valor de esta marca debe ser un nombre de función o un nombre de clase completamente calificado que exista en tu código fuente.

  • BASE_IMAGE por el entorno de la imagen base de tu función. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base de los entornos de ejecución.

  • REGION con la Google Cloud región en la que deseas implementar tu función. Por ejemplo, us-central1.

  • IMAGE_URL con una referencia a la ruta de acceso de la imagen usando el repositorio de imágenes de Artifact Registry que elijas, por ejemplo, projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/FUNCTION. El nombre de la imagen debe coincidir con el nombre de la función que deseas crear. Si solo se proporciona la ruta de acceso del repositorio, la imagen se creará con el nombre de la función FUNCTiON.

Cuando especifiques un repositorio de Artifact Registry ubicado en un proyecto o una región diferente, debes tener en cuenta lo siguiente:

Configuraciones de IAM:

  • Asegúrate de haber configurado los permisos de IAM para implementar imágenes de otros Google Cloud proyectos.
  • Además, asegúrate de que la cuenta de servicio de compilación tenga acceso autorizado para leer y escribir en REPOSITORY.

Parámetros de configuración de red:

  • Asegúrate de que se pueda acceder al REPOSITORY de destino desde la configuración del proyecto actual.

Parámetros de configuración de los Controles del servicio de VPC:

  • Asegúrate de que la cuenta de servicio de compilación pueda llegar al REPOSITORY de destino dentro del perímetro de VPC-SC.

Restricciones de residencia de datos:

  • Ten en cuenta que especificar un REPOSITORY en una región diferente de la región en la que se encuentra tu función provocará la transferencia de datos entre regiones.

Modifica una función existente

Puedes modificar la configuración o el código de tu función:

Modifica la configuración

Para modificar los parámetros de configuración, como las opciones de facturación, la memoria y la conectividad de la VPC, sigue las instrucciones en la pestaña correspondiente:

Console

  1. En la consola de Google Cloud, ve a la página Cloud Run:

    Ir a Cloud Run

  2. Identifica el servicio que deseas actualizar en la lista de servicios y hazle clic para abrir los detalles.

  3. Haz clic en Editar e implementar una revisión nueva para mostrar el formulario de implementación de revisión.

  4. Modificar cualquier parámetro de configuración

  5. Haz clic en Implementar y espera a que finalice la implementación.

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. Para actualizar uno o más parámetros de configuración del servicio, usa el comando gcloud beta run services update SERVICE con las marcas de línea de comandos de la configuración que deseas actualizar. Reemplaza SERVICE por el nombre del servicio.

Vuelve a implementar el código fuente nuevo

Puedes modificar la imagen base, el entorno de ejecución y el código fuente de tu función con la consola de Google Cloud o gcloud CLI.

Haz clic en la pestaña para obtener instrucciones de la herramienta que elijas.

Console

  1. En la consola de Google Cloud, ve a la página Cloud Run:

    Ir a Cloud Run

  2. Busca la función que deseas actualizar en la lista Servicios y haz clic en ella para abrir los detalles.

  3. Navega a la pestaña Fuente y haz clic en Editar fuente.

  4. Haz clic en Editar actualizaciones de entorno de ejecución y seguridad junto a Imagen base y selecciona un Entorno de ejecución o Entorno diferente de la lista según sea necesario. Luego, haz clic en Guardar.

  5. Modifica el Punto de entrada de la función según sea necesario.

  6. En la sección Archivos, selecciona Agregar archivo para crear uno nuevo, Cambiar nombre de archivo para cambiar el nombre de un archivo o Borrar archivo para borrar uno.

  7. En la sección Código, modifica el código fuente según sea necesario.

  8. Haz clic en Guardar y volver a implementar y espera a que finalice la implementación.

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. Ejecuta el siguiente comando en el directorio que contiene el código fuente de la función:

    gcloud beta run deploy FUNCTION \
       --source . \
       --function FUNCTION_ENTRYPOINT \
       --base-image BASE_IMAGE \
       --region REGION

    Reemplaza lo siguiente:

    • FUNCTION por el nombre de la función que deseas modificar.

    • FUNCTION_ENTRYPOINT por el punto de entrada a tu función en tu código fuente.

    • BASE_IMAGE por el entorno de la imagen base de tu función. En la mayoría de los casos, puedes especificar el ID del entorno de ejecución, por ejemplo, nodejs22.

      Como alternativa, si deseas usar un paquete de sistema específico en la pila o especificar la región desde la que se descarga la imagen base, puedes especificar una de las siguientes opciones:

      • Es la ruta de acceso completa de la imagen base, como us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/nodejs22. Esta opción te permite especificar la imagen base, un paquete de sistema específico en la pila y la región desde la que se descarga la imagen base.
      • Es el alias de la ruta de acceso completa de la imagen base, como google-22/nodejs22 o google-22-full/nodejs22. Esta opción de alias más corta te permite especificar la imagen base y un paquete de sistema específico en la pila.

      Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base del entorno de ejecución.

    • REGION con la Google Cloud región en la que deseas implementar tu función. Por ejemplo, us-central1.

    Marcas opcionales

    Puedes configurar las siguientes marcas opcionales mientras modificas tu función:

¿Qué sigue?

Después de implementar una función nueva, puedes hacer lo siguiente: