Configura activaciones de volúmenes de Cloud Storage para trabajos

En esta página, se muestra cómo activar un bucket de Cloud Storage como un volumen de almacenamiento mediante el uso de activaciones de volúmenes de Cloud Run.

Activar el bucket como un volumen en Cloud Run presenta el contenido del bucket como archivos en el sistema de archivos del contenedor. Después de activar el bucket como un volumen, accedes al bucket como si fuera un directorio en tu sistema de archivos local, mediante las operaciones y bibliotecas del sistema de archivos de tu lenguaje de programación en lugar de usar las bibliotecas cliente de la API de Google.

Requisitos de la memoria

Las activaciones de volúmenes de Cloud Storage usan la memoria del contenedor de Cloud Run para las siguientes actividades:

Para todo el almacenamiento en caché de Cloud Storage FUSE, Cloud Run usa de forma predeterminada la configuración de caché de estadísticas con un tiempo de actividad (TTL) de 60 segundos. El tamaño máximo predeterminado de la caché de estadísticas es de 32 MB, el tamaño máximo predeterminado del tipo caché es 4 MB.
Cuando se realiza la lectura, Cloud Storage FUSE también consume memoria aparte de las cachés de estadísticas y tipos, por ejemplo, un array de 1 MiB por cada archivo que se lee y por goroutines.
Cuando se escribe en Cloud Storage, todo el archivo se almacena en etapa intermedia en la memoria de Cloud Run antes de que el archivo se escriba en Cloud Storage.

Limitaciones

Dado que Cloud Run usa Cloud Storage FUSE para esta activación de volumen, debes tener en cuenta lo siguiente cuando actives un bucket de Cloud Storage como un volumen:

Cloud Storage FUSE no proporciona control de simultaneidad para varias operaciones de escritura (bloqueo de archivos) en el mismo archivo. Cuando varias operaciones de escritura intentan reemplazar un archivo, la última escritura gana y todas las escrituras anteriores se pierden.
Cloud Storage FUSE no es un sistema de archivos compatible con POSIX. Si deseas obtener más información, consulta la documentación de Cloud Storage FUSE.

Rutas no permitidas

Cloud Run no te permite activar un volumen en /dev, /proc y /sys, ni en sus subdirectorios.

Antes de comenzar

Necesitas un bucket de Cloud Storage para activarlo como volumen.

Para obtener un rendimiento óptimo de lectura y escritura en Cloud Storage, consulta Cómo optimizar el rendimiento del ancho de banda de la red de Cloud Storage FUSE.

Roles obligatorios

Para obtener los permisos que necesitas para configurar activaciones de volúmenes de Cloud Storage, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Desarrollador de Cloud Run (roles/run.developer) en el trabajo de Cloud Run
Usuario de la cuenta de servicio (roles/iam.serviceAccountUser) en la identidad del servicio

A fin de obtener los permisos que tu identidad de servicio necesita para acceder al archivo y al bucket de Cloud Storage, pídele a tu administrador que otorgue a la identidad del servicio el siguiente rol de IAM:

Administrador de almacenamiento (roles/storage.admin)

Si deseas obtener más detalles sobre los roles y los permisos de Cloud Storage, consulta IAM para Cloud Storage.

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 trabajo de Cloud Run interactúa con las APIs de Google 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.

Activa un volumen de Cloud Storage

Puedes activar varios buckets en diferentes rutas de activación. También puedes activar un volumen en más de un contenedor con las mismas (o diferentes) rutas de activación en diferentes contenedores.

Si usas varios contenedores, primero especifica los volúmenes y, luego, especifica las activaciones de volúmenes de cada contenedor.

Console

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

Ir a Cloud Run
Haz clic en Implementar contenedor y selecciona Trabajo para completar la página de configuración de trabajo inicial. Si quieres configurar un trabajo existente, selecciona el trabajo y, luego, haz clic en Editar.
Haz clic en Contenedor, variables y secretos, conexiones y seguridad para expandir la página de propiedades del trabajo.
Haz clic en la pestaña Volúmenes.
- En Volúmenes, haz lo siguiente:
  - Haz clic en Agregar volumen.
  - En el menú desplegable Tipo de volumen, selecciona el bucket de Cloud Storage como el tipo de volumen.
  - En el campo Nombre del volumen, ingresa el nombre que deseas usar para el volumen.
  - Explora y selecciona el bucket que deseas usar para el volumen.
  - De manera opcional, selecciona la casilla de verificación Solo lectura para que el bucket sea de solo lectura.
  - Haz clic en Listo.
- Haz clic en la pestaña Contenedor y, luego, expande el contenedor en el que activas el volumen para editar el contenedor.
- Haz clic en la pestaña Activaciones de volúmenes.
- Haz clic en Volumen de activación.
Haz clic en Crear o Actualizar.

gcloud

Para agregar un volumen y activarlo, sigue estos pasos:
```
gcloud run jobs update JOB \
--add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH
```
Reemplaza lo siguiente:
- JOB por el nombre de tu trabajo.
- MOUNT_PATH por la ruta de acceso relativa en la que activarás el volumen, por ejemplo, /mnt/my-volume.
- VOLUME_NAME por el nombre que quieras para el volumen. El valor VOLUME_NAME se usa para asignar el volumen a la activación de volúmenes.
- BUCKET_NAME por el nombre del bucket de Cloud Storage.

Para activar el volumen como un volumen de solo lectura, sigue estos pasos:

--add-volume=name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,readonly=true

Si usas varios contenedores, primero especifica los volúmenes y, luego, especifica las activaciones de volumen de cada contenedor:

gcloud run jobs update JOB \
--add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
--container CONTAINER_1 \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH \
--container CONTAINER_2 \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH2

YAML

Si creas un trabajo nuevo, omite este paso. Si actualizas un trabajo existente, descarga su configuración de YAML:
```
gcloud run jobs describe JOB_NAME --format export > job.yaml
```

Actualiza MOUNT_PATH, VOLUME_NAME, BUCKET_NAME y IS_READ_ONLYsegún sea necesario.

apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB_NAME
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
    spec:
      template:
        spec:
          containers:
          - image: IMAGE_URL
            volumeMounts:
            - mountPath: MOUNT_PATH
              name: VOLUME_NAME
          volumes:
          - name: VOLUME_NAME
            csi:
              driver: gcsfuse.run.googleapis.com
              readOnly: IS_READ_ONLY
              volumeAttributes:
                bucketName: BUCKET_NAME

Reemplazar

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.
MOUNT_PATH por la ruta de acceso relativa en la que activarás el volumen, por ejemplo, /mnt/my-volume.
VOLUME_NAME por el nombre que quieras para el volumen. El valor VOLUME_NAME se usa para asignar el volumen a la activación de volúmenes.
IS_READ_ONLY por True para que el volumen sea de solo lectura o False para permitir escrituras.
BUCKET_NAME con el nombre del bucket de Cloud Storage.

Crea o actualiza el servicio con el siguiente comando:
```
gcloud run jobs replace job.yaml
```

Leer y escribir en un volumen

Si usas la función de activación de volúmenes de Cloud Run, accedes a un volumen activado con las mismas bibliotecas en tu lenguaje de programación que usas para leer y escribir archivos en tu sistema de archivos local.

Esto es muy útil si usas un contenedor existente que espera que los datos se almacenen en el sistema de archivos local y usa operaciones regulares del sistema de archivos para acceder a él.

En los siguientes fragmentos, se supone una activación de volumen con una mountPath configurada como /mnt/my-volume.

Nodejs

Usa el módulo del sistema de archivos para crear un archivo nuevo o agregarlo a uno existente en el volumen, /mnt/my-volume:

var fs = require('fs');
fs.appendFileSync('/mnt/my-volume/sample-logfile.txt', 'Hello logs!', { flag: 'a+' });

Python

Escribe en un archivo mantenido en el volumen, /mnt/my-volume:

f = open("/mnt/my-volume/sample-logfile.txt", "a")

Go

Usa el paquete os para crear un archivo nuevo mantenido en el volumen, /mnt/my-volume

f, err := os.Create("/mnt/my-volume/sample-logfile.txt")

Java

Usa la clase Java.io.File para crear un archivo de registro en el volumen, /mnt/my-volume:

import java.io.File;
File f = new File("/mnt/my-volume/sample-logfile.txt");

Visualiza la configuración de activaciones de volúmenes

Console

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

Ir a Trabajos de Cloud Run
Haz clic en el trabajo que te interesa para abrir la página Detalles del trabajo.
Haz clic en la pestaña Volúmenes.
Ubica la configuración de activaciones de volúmenes en la página de detalles de los volúmenes.

gcloud

Usa el siguiente comando:
```
gcloud run jobs describe JOB_NAME
```
Ubica la configuración de activaciones de volúmenes en la configuración que se muestra.

Cómo optimizar el rendimiento del ancho de banda de la red de Cloud Storage FUSE

Para obtener un mejor rendimiento de lectura y escritura, conecta tu trabajo de Cloud Run a una red de VPC con VPC directa y enruta todo el tráfico saliente a través de tu red de VPC. Puedes hacerlo mediante cualquiera de las siguientes opciones.

Habilita el Acceso privado a Google y asegúrate de establecer el parámetro vpc-egress en all-traffic.
Usa una de las opciones que se describen en la página de prácticas recomendadas de redes en el ejemplo 2, Tráfico interno a una API de Google.

Tiempo de inicio del contenedor y activaciones de Cloud Storage FUSE

El uso de Cloud Storage FUSE puede aumentar ligeramente el tiempo de inicio en frío de tu contenedor de Cloud Run, ya que la activación de volumen se inicia antes de iniciar los contenedores. Tu contenedor se iniciará solo si Cloud Storage FUSE se activa correctamente.

Ten en cuenta que Cloud Storage FUSE activa un volumen correctamente solo después de establecer una conexión con Cloud Storage. Cualquier retraso en la red puede afectar el tiempo de inicio del contenedor. Del mismo modo, si falla el intento de conexión, no se activará Cloud Storage FUSE ni se iniciará la tarea de Cloud Run. Además, si Cloud Storage FUSE tarda más de 30 segundos en activarse, el trabajo de Cloud Run no se iniciará porque tiene un tiempo de espera total de 30 segundos para realizar todas las activaciones.

Características de rendimiento de Cloud Storage FUSE

Si defines dos volúmenes, cada uno de los cuales apunta a un bucket diferente, se iniciarán dos procesos de Cloud Storage FUSE. Las activaciones y los procesos se realizan en paralelo.

Las operaciones que usan Cloud Storage FUSE se ven afectadas por el ancho de banda de la red, ya que Cloud Storage FUSE se comunica con Cloud Storage a través de la API de Cloud Storage. Algunas operaciones, como enumerar el contenido de un bucket, pueden ser lentas si el ancho de banda de la red es bajo. Del mismo modo, la lectura de un archivo grande puede llevar tiempo, ya que el ancho de banda de la red también lo limita.

Cuando escribes en un bucket, Cloud Storage FUSE coloca el objeto en etapa intermedia por completo en la memoria. Esto significa que la escritura de archivos grandes está limitada por la cantidad de memoria disponible para la instancia del contenedor (el límite máximo de memoria del contenedor es de 32 GiB).

La operación de escritura se borra en el bucket solo cuando realizas una close o una fsync: luego, el objeto completo se sube o se vuelve a subir al bucket. La única excepción a que un objeto se vuelva a subir por completo al bucket es en el caso de un archivo con contenido agregado cuando el archivo es de 2 MiB o más.

Para obtener más información, consulta los siguientes recursos: