Hello Cloud Run with Python (FastAPI)

1. Introducción

Cloud Run es una plataforma de procesamiento administrada que te permite ejecutar contenedores sin estado que se pueden invocar a través de solicitudes HTTP. Se compila en el proyecto de código abierto Knative, lo que permite trasladar cargas de trabajo entre plataformas. Cloud Run es una plataforma sin servidores que simplifica la administración de la infraestructura para que puedas enfocarte en lo que más importa: crear aplicaciones extraordinarias.

El objetivo de este instructivo es crear una aplicación web sencilla de FastAPI y, luego, implementarla en Cloud Run.

Qué aprenderás

• Cómo crear una aplicación de FastAPI "Hello World".
• Cómo probar la aplicación ejecutando el servidor de FastAPI en modo dev.
• Los Cloud Buildpacks y cómo la presencia de fastapi y uvicorn en un requirements.txt permiten que no se necesite un Dockerfile.
• Cómo implementar la aplicación de FastAPI en Cloud Run.

2. Configuración y requisitos

Configuración del entorno a su propio ritmo

1. Accede a la Google Cloud Console y crea un proyecto nuevo o reutiliza uno existente. Si aún no tienes una cuenta de Gmail o de Google Workspace, debes crear una.

• El Nombre del proyecto es el nombre visible de los participantes de este proyecto. Es una cadena de caracteres que no se utiliza en las APIs de Google. Puedes actualizarla cuando quieras.
• El ID del proyecto es único en todos los proyectos de Google Cloud y es inmutable (no se puede cambiar después de configurarlo). La consola de Cloud genera automáticamente una cadena única. Por lo general, no importa cuál sea. En la mayoría de los codelabs, deberás hacer referencia al ID de tu proyecto (suele identificarse como PROJECT_ID). Si no te gusta el ID que se generó, podrías generar otro aleatorio. También puedes probar uno propio y ver si está disponible. No se puede cambiar después de este paso y se usa el mismo durante todo el proyecto.
• Recuerda que hay un tercer valor, un número de proyecto, que usan algunas APIs. Obtén más información sobre estos tres valores en la documentación.

Precaución: El ID del proyecto es único a nivel global y no lo puede usar nadie más después de que lo hayas seleccionado. Eres el único usuario de ese ID. Incluso si se borra un proyecto, no se puede volver a usar el ID.

Nota: Si usas una cuenta de Gmail, puedes dejar la ubicación predeterminada como Sin organización. Si usas una cuenta de Google Workspace, elige una ubicación adecuada para tu organización.

2. A continuación, deberás habilitar la facturación en la consola de Cloud para usar las APIs o los recursos de Cloud. Ejecutar este codelab no costará mucho, tal vez nada. Para cerrar recursos y evitar que se generen cobros más allá de este instructivo, puedes borrar los recursos que creaste o borrar el proyecto. Los usuarios nuevos de Google Cloud son aptos para participar en el programa Prueba gratuita de$300.

Iniciar Cloud Shell

Si bien Google Cloud se puede operar de manera remota desde tu laptop, en este instructivo usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.

Activar Cloud Shell

1. En la consola de Cloud, haz clic en Activar Cloud Shell

Si es la primera vez que inicias Cloud Shell, aparecerá una pantalla intermedia en la que se describirá qué es. Si se te mostró una pantalla intermedia, haz clic en Continuar.

El aprovisionamiento y la conexión a Cloud Shell solo tomará unos minutos.

Esta máquina virtual está cargada con todas las herramientas de desarrollo necesarias. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Gran parte de tu trabajo en este codelab, si no todo, se puede hacer con un navegador.

Una vez que te conectes a Cloud Shell, deberías ver que ya te autenticaste y que el proyecto ya se configuró con el ID de tu proyecto.

2. En Cloud Shell, ejecuta el siguiente comando para confirmar que tienes la autenticación:

gcloud auth list

Resultado del comando

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Nota: gcloud es la herramienta de línea de comandos potente y unificada de Google Cloud. Ya está preinstalada en Cloud Shell. Notarás su compatibilidad con la finalización con tabulación. Es posible que se te pida que te autentiques la primera vez que ejecutas un comando. Para obtener más información, consulta la descripción general de la herramienta de línea de comandos de gcloud.

3. En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.

gcloud config list project

Resultado del comando

[core]
project = <PROJECT_ID>

De lo contrario, puede configurarlo con este comando:

gcloud config set project <PROJECT_ID>

Resultado del comando

Updated property [core/project].

Nota: Si completas este instructivo fuera de Cloud Shell, sigue Configura las credenciales predeterminadas de la aplicación.

3. Habilita las APIs

En Cloud Shell, habilita las APIs de Artifact Registry, Cloud Build y Cloud Run:

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

Se mostrará un mensaje de éxito similar a este:

Operation "operations/..." finished successfully.

En segundo plano, para implementar tu aplicación, Cloud Run se vincula con el ecosistema de contenedores:

• Cloud Build compila automáticamente una imagen de contenedor a partir de tu código fuente y la envía a Artifact Registry.
• Artifact Registry administra tu imagen de contenedor.

Ahora, ya puedes comenzar a trabajar y escribir tu aplicación.

4. Escribe la aplicación

En este paso, compilarás una aplicación de FastAPI Python "Hello World" que responde a solicitudes HTTP.

Directorio de trabajo

Usa Cloud Shell para crear un directorio de trabajo llamado helloworld-fastapi y cambiar a él:

mkdir ~/helloworld-fastapi && cd ~/helloworld-fastapi

main.py

Crea un archivo llamado main.py:

touch main.py

Edita el archivo con tu editor de línea de comandos preferido (nano, vim o emacs) o haciendo clic en el botón Editor de Cloud Shell:

Para editar el archivo directamente con el Editor de Cloud Shell, usa este comando:

cloudshell edit main.py

main.py

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def hello(name: str = "World"):
    """Return a friendly HTTP greeting."""
    return {
        "message": f"Hello {name}!"
    }

Con este código, se crea un servicio web básico que responde a solicitudes HTTP GET con un mensaje amigable.

requirements.txt

Vuelve a abrir la terminal y agrega un archivo llamado requirements.txt para definir las dependencias:

touch requirements.txt

Para editar el archivo directamente con el Editor de Cloud Shell, usa este comando:

cloudshell edit requirements.txt

requirements.txt

# https://pypi.org/project/fastapi
fastapi[standard]==0.116.1

# https://pypi.org/project/uvicorn
uvicorn==0.35.0

Hay más lenguajes documentados para comenzar a usar Cloud Run. Puedes encontrar instrucciones para las secuencias de comandos de shell, Go, Node.js, Java, C#, C++, PHP y Ruby, entre otras, aquí: https://cloud.google.com/run/docs/quickstarts/build-and-deploy

La aplicación de FastAPI está lista para implementarse, pero primero es hora de probarla.

5. Prueba la aplicación

Para probar la aplicación, usa uv (el administrador de proyectos y paquetes extremadamente rápido de Python), que viene preinstalado en Cloud Shell.

Para probar la aplicación, crea un entorno virtual:

uv venv

Instala las dependencias:

uv pip install -r requirements.txt

Inicia la aplicación en modo dev:

uv run fastapi dev main.py --port=8080

Los registros muestran que estás en modo de desarrollo:

FastAPI   Starting development server 🚀

          Searching for package file structure from directories with __init__.py files
          Importing from /home/user/code/helloworld-fastapi

  module  🐍 main.py

    code  Importing the FastAPI app object from the module with the following code:

          from main import app

     app  Using import string: main:app

  server   Server started at http://127.0.0.1:8080
  server   Documentation at http://127.0.0.1:8080/docs

     tip   Running in development mode, for production use: fastapi run

           Logs:

    INFO   Will watch for changes in these directories: ['/home/user/code/helloworld-fastapi']
    INFO   Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
    INFO   Started reloader process [19627] using WatchFiles
    INFO   Started server process [19629]
    INFO   Waiting for application startup.
    INFO   Application startup complete.

En la ventana de Cloud Shell, haz clic en el ícono Web Preview y selecciona Preview on port 8080:

Debería abrirse una ventana del navegador con el mensaje Hello World!.

También puedes abrir otra sesión de Cloud Shell (una pestaña nueva de la terminal) haciendo clic en el ícono + y enviando una solicitud web a la aplicación que se ejecuta de forma local:

curl localhost:8080

Deberías recibir la siguiente respuesta:

{"message": "Hello World!"}

Cuando termines, vuelve a la sesión principal de Cloud Shell y detén el servidor de desarrollo de FastAPI con CTRL+C.

La aplicación funciona como se esperaba: es hora de implementarla.

6. Implementa en Cloud Run

Cloud Run es regional, lo que significa que la infraestructura que ejecuta tus 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. Define la región que usarás para tu implementación, por ejemplo:

REGION=europe-west4

Para obtener la lista completa de regiones admitidas, consulta Ubicaciones de Cloud Run (completamente administrado).

Asegúrate de que aún estés en el directorio de trabajo:

ls

Deberían aparecer los siguientes archivos:

main.py  requirements.txt

Antes de la implementación, crea un archivo .gcloudignore con .venv/ en él. Esto impide que la implementación de Cloud Run incluya el entorno virtual que se creó a partir de uv durante las pruebas locales.

Crea el archivo .gcloudignore con el siguiente comando:

echo ".venv/" > .gcloudignore

Implementa la aplicación en Cloud Run:

gcloud run deploy helloworld-fastapi \
  --source . \
  --region $REGION \
  --allow-unauthenticated

• La opción --allow-unauthenticated hace que el servicio esté disponible de forma pública. Para evitar solicitudes no autenticadas, usa --no-allow-unauthenticated en su lugar.

Para verificar todas las opciones, usa gcloud run deploy --help.

La primera vez, se te solicitará que crees un repositorio de Artifact Registry. Presiona Enter para validar:

Deploying from source requires an Artifact Registry Docker repository to store
built containers. A repository named [cloud-run-source-deploy] in region [REGION]
will be created.

Do you want to continue (Y/n)?

Se iniciará la carga de tu código fuente al repositorio de Artifact Registry y la compilación de tu imagen de contenedor:

Building using Buildpacks and deploying container ...
* Building and deploying new service... Building Container.           
  OK Creating Container Repository...
  OK Uploading sources...
  * Building Container... Logs are available at ...

Cloud Build usa Buildpacks, que detecta automáticamente el lenguaje de tu código fuente y crea una imagen de contenedor basada en la versión estable más reciente del intérprete de Python (Python 3.13 en el momento de la escritura).

Para usar Buildpacks con un servidor web ASGI como uvicorn que requiere FastAPI, la presencia de uvicorn debe estar en el archivo requirements.txt. De lo contrario, Buildpacks usará de forma predeterminada un servidor web WSGI con gunicorn, lo que generará errores con FastAPI.

Para obtener más detalles, consulta Compila una aplicación de Python.

Luego, espera un momento a que finalice la implementación. Si la operación es exitosa, la línea de comandos mostrará la URL de servicio:

...
OK Building and deploying new service... Done.
  OK Creating Container Repository...
  OK Uploading sources...
  OK Building Container... Logs are available at ...
  OK Creating Revision... Creating Service.
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [SERVICE]... has been deployed and is serving 100 percent of traffic.
Service URL: https://SERVICE-PROJECTHASH-REGIONID.a.run.app

Puedes obtener la URL de servicio con este comando:

SERVICE_URL=$( \
  gcloud run services describe helloworld-fastapi \
  --region $REGION \
  --format "value(status.address.url)" \
)
echo $SERVICE_URL

Debería aparecer algo como lo siguiente:

https://helloworld-fastapi-PROJECTHASH-REGIONID.a.run.app

Ahora puedes usar tu aplicación abriendo la URL de servicio en un navegador web:

También puedes llamar a la aplicación desde Cloud Shell:

curl $SERVICE_URL?name=me

Deberías recibir el saludo esperado:

{"message": "Hello me!"}

Si bien este breve lab se realizó con la línea de comandos de gcloud, Cloud Run también está disponible con la consola de Cloud ( console.cloud.google.com/run). Deberías ver tu servicio helloworld-fastapi en la lista:

También puedes usar la consola para implementar servicios de Cloud Run.

¡Felicitaciones! Acabas de implementar una aplicación en Cloud Run. Cloud Run escala la imagen del contenedor automáticamente y de forma horizontal para controlar las solicitudes que se reciben y, luego, reduce la escala verticalmente cuando disminuye la demanda. Solo debes pagar por la CPU, la memoria y las herramientas de redes que se utilicen durante la administración de la solicitud para este servicio de Cloud Run.

7. Limpia

Si bien Cloud Run no cobra cuando el servicio no se usa, es posible que se te cobre por el almacenamiento de la imagen de contenedor en Artifact Registry. Puedes borrar el repositorio o el proyecto de Cloud para evitar que se apliquen cargos. Si borras tu proyecto de Cloud, se dejan de facturar todos los recursos que usaste en ese proyecto.

Para borrar el repositorio de imágenes del contenedor, haz lo siguiente:

gcloud artifacts repositories delete cloud-run-source-deploy \
  --location $REGION

Para borrar el servicio de Cloud Run, haz lo siguiente:

gcloud run services delete helloworld-fastapi \
  --region $REGION

Para borrar tu proyecto de Google Cloud,

1. Recupera tu ID del proyecto actual:

PROJECT_ID=$(gcloud config get-value core/project)

2. Asegúrate de que este sea el proyecto que deseas borrar:

echo $PROJECT_ID

3. Borra el proyecto:

gcloud projects delete $PROJECT_ID

8. ¡Felicitaciones!

Creaste una aplicación web de FastAPI "Hello World" y la implementaste en Cloud Run.

Temas abordados

• Cómo crear una aplicación de FastAPI "Hello World".
• Cómo probar la aplicación ejecutando el servidor de FastAPI en modo dev.
• Los Cloud Buildpacks y cómo la presencia de fastapi y uvicorn en un requirements.txt permiten que no se necesite un Dockerfile.
• Cómo implementar la aplicación de FastAPI en Cloud Run.

Más información

• Consulta la documentación de Cloud Run.
• Completa Dev to Prod in Three Easy Steps with Cloud Run para explorar más opciones.
• Completa Django en Cloud Run para crear una base de datos de Cloud SQL, administrar credenciales con Secret Manager y, luego, implementar Django.
• Consulta más codelabs de Cloud Run.