Configurar montagens de volumes do Cloud Storage para jobs

Nesta página, você aprende a montar um bucket do Cloud Storage como um volume de armazenamento usando as montagens de volumes do Cloud Run.

Montar o bucket como um volume no Cloud Run apresenta o bucket conteúdo como arquivos no sistema de arquivos do contêiner. Depois de ativar o bucket, como um volume, você acessa o bucket como se fosse um diretório no arquivo local do sistema de arquivos, usando as operações e bibliotecas do sistema de arquivos da sua linguagem de programação em vez das bibliotecas de cliente das APIs do Google.

Requisitos de memória

As montagens de volume do Cloud Storage usam a memória do contêiner do Cloud Run para as seguintes atividades:

Para todo o armazenamento em cache do Cloud Storage FUSE, o Cloud Run usa a configuração de cache de estatísticas com um Time to live (TTL) de 60 segundos por padrão. O tamanho máximo padrão do cache de estatísticas é 32 MB, e o tamanho máximo padrão do cache de tipo é 4 MB.
Durante a leitura, o Cloud Storage FUSE também consome memórias diferentes de caches de estatística e tipo, por exemplo, uma matriz de 1 MiB para cada arquivo que está sendo lido e para goroutines.
Ao gravar no Cloud Storage, o arquivo inteiro é preparado na memória do Cloud Run antes de ser gravado no Cloud Storage.

Limitações

Como o Cloud Run usa o Cloud Storage FUSE para essa montagem de volume, há algumas coisas a serem lembradas ao montar um bucket do Cloud Storage como um volume:

O Cloud Storage FUSE não oferece controle de simultaneidade para várias gravações (bloqueio de arquivo) no mesmo arquivo. Quando várias gravações tentam substituir um arquivo, a última é bem-sucedida e todas as anteriores são perdidas.
O Cloud Storage FUSE não é um sistema de arquivos totalmente compatível com POSIX. Para mais detalhes, consulte a documentação do Cloud Storage FUSE.

Caminhos não permitidos

O Cloud Run não permite montar um volume em /dev, /proc e /sys ou nos subdiretórios deles.

Antes de começar

Você precisa de um bucket do Cloud Storage para montar como o volume.

Para ter o melhor desempenho de leitura/gravação no Cloud Storage, consulte Como otimizar o desempenho da largura de banda de rede do Cloud Storage FUSE.

Funções exigidas

Para receber as permissões necessárias para configurar as montagens de volume do Cloud Storage, peça ao administrador para conceder a você os seguintes papéis do IAM:

Desenvolvedor do Cloud Run (roles/run.developer) no job do Cloud Run
Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço

Para receber as permissões de que a identidade de serviço precisa para acessar o arquivo e o bucket do Cloud Storage, peça ao administrador para conceder à identidade de serviço o seguinte papel do IAM:

Administrador do Storage (roles/storage.admin)

Para mais detalhes sobre papéis e permissões do Cloud Storage, consulte IAM para o Cloud Storage.

Para uma lista de papéis e permissões do IAM associados ao Cloud Run, consulte Papéis do IAM do Cloud Run e Permissões do IAM do Cloud Run. Se o job do Cloud Run interagir com APIs do Google Cloud, como bibliotecas de cliente do Cloud, consulte o guia de configuração de identidade de serviço. Para mais informações sobre como conceder papéis, consulte permissões de implantação e gerenciar acesso.

Montar um volume do Cloud Storage

É possível montar vários buckets em diferentes caminhos de montagem. Também é possível montar um volume em mais de um contêiner usando caminhos de montagem iguais ou diferentes nos contêineres.

Ao usar vários contêineres, primeiro especifique os volumes e, depois, as montagens de volume de cada contêiner.

Console

No console do Google Cloud, acesse a página de jobs do Cloud Run:

Acessar o Cloud Run
Clique em Implantar contêiner e selecione Job para preencher a página inicial de configurações do job. Se você estiver configurando um job, clique nele e em Editar.
Clique em Contêiner, variáveis e secrets, conexões e segurança para expandir a página de propriedades do job.
Clique na guia Volumes.
- Em Volumes:
  - Clique em Adicionar volume.
  - No menu suspenso Tipo de volume, selecione o bucket do Cloud Storage como o tipo.
  - No campo Nome do volume, digite o nome que você quer usar para o volume.
  - Procure e selecione o bucket que você quer usar para o volume.
  - Opcionalmente, marque a caixa de seleção Somente leitura para tornar o bucket somente leitura.
  - Clique em Concluído.
- Clique na guia "Contêiner" e abra o contêiner para que você está montando o volume para editar o contêiner.
- Clique na guia Montagens de volumes.
- Clique em Montar volume.
Clique em Criar ou Atualizar.

gcloud

Para adicionar um volume e montá-lo:
```
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
```
Substitua:
- JOB pelo nome do job.
- MOUNT_PATH pelo caminho relativo em que você está montando o volume, por exemplo, /mnt/my-volume.
- VOLUME_NAME pelo nome que você quiser para o volume. O valor VOLUME_NAME é usado para mapear o volume para a montagem associada.
- BUCKET_NAME pelo nome do bucket do Cloud Storage.

Para montar o volume como somente leitura:

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

Se você estiver usando vários contêineres, primeiro especifique os volumes e, em seguida, as ativações de volume para cada contêiner:

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

Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:
```
gcloud run jobs describe JOB_NAME --format export > job.yaml
```

Atualize MOUNT_PATH, VOLUME_NAME, BUCKET_NAME e IS_READ_ONLY conforme necessário.

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

Substituir

IMAGE_URL por uma referência à imagem de contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL tem o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
MOUNT_PATH pelo caminho relativo em que você está montando o volume, por exemplo, /mnt/my-volume.
VOLUME_NAME pelo nome que você quiser para o volume. O valor VOLUME_NAME é usado para mapear o volume para a montagem associada.
IS_READ_ONLY com True para tornar o volume somente leitura ou False para permitir gravações.
BUCKET_NAME pelo nome do bucket do Cloud Storage.

Crie ou atualize o serviço usando o seguinte comando:
```
gcloud run jobs replace job.yaml
```

Como ler e gravar em um volume

Se você usar o recurso de montagem de volume do Cloud Run, poderá acessar um volume usando as mesmas bibliotecas na linguagem de programação que você usa para ler e gravar arquivos no sistema de arquivos local.

Isso é especialmente útil se você estiver usando um contêiner existente em que espera os dados sejam armazenados no sistema de arquivos local e usa o sistema de arquivos para acessá-lo.

Os snippets a seguir pressupõem uma montagem de volume com mountPath definido como /mnt/my-volume.

Nodejs

Use o módulo Sistemas de arquivos para criar um novo arquivo ou adicionar ao final de um arquivo existente no volume, /mnt/my-volume:

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

Python

Grave em um arquivo no volume, /mnt/my-volume:

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

Go

Use o pacote os para criar um novo arquivo mantido no volume, /mnt/my-volume

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

Java

Use a classe Java.io.File para criar um arquivo de registro no volume, /mnt/my-volume:

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

Acessar configurações de montagem de volume

Console

No console do Google Cloud, acesse a página de jobs do Cloud Run:

Acessar jobs do Cloud Run
Clique no job em que você tem interesse para abrir a página Detalhes do job.
Clique na guia Volumes.
Localize a configuração de montagens de volume na página de detalhes dos volumes.

gcloud

Use o comando a seguir:
```
gcloud run jobs describe JOB_NAME
```
Localize a configuração de montagens de volume na configuração retornada.

Como otimizar o desempenho da largura de banda da rede do Cloud Storage FUSE

Para melhorar a performance de leitura e gravação, conecte seu job do Cloud Run a uma rede VPC usando a VPC direta e roteando todo o tráfego de saída pela rede VPC. Faça isso usando uma das opções a seguir:

Ative o Acesso privado do Google e defina o parâmetro vpc-egress como all-traffic.
Use uma das opções descritas na página de práticas recomendadas de rede no exemplo 2, Tráfego interno para uma API do Google.

Tempo de inicialização do contêiner e montagens do Cloud Storage FUSE

Usar o Cloud Storage FUSE pode aumentar um pouco o tempo de inicialização a frio do contêiner do Cloud Run porque a montagem do volume é iniciada antes de iniciar o(s) contêiner(es). Seu contêiner só será iniciado se o Cloud Storage FUSE for montado corretamente.

Observe que o Cloud Storage FUSE monta com sucesso um volume somente após estabelecer uma conexão com o Cloud Storage. Qualquer atraso na rede pode afetar o tempo de inicialização do contêiner. Da mesma forma, se a tentativa de conexão falhar, o Cloud Storage FUSE não será montado e o job do Cloud Run não será iniciado. Além disso, se o Cloud Storage FUSE levar mais de 30 segundos para ser montado, o job do Cloud Run não vai ser iniciado porque o Cloud Run tem um tempo limite total de 30 segundos para realizar todas as montagens.

Características de desempenho do Cloud Storage FUSE

Se você definir dois volumes, cada um apontando para um bucket diferente, dois processos do Cloud Storage FUSE serão iniciados. As montagens e os processos ocorrem em paralelo.

As operações que usam o Cloud Storage FUSE são afetadas pela largura de banda da rede porque o Cloud Storage FUSE se comunica com o Cloud Storage usando a API Cloud Storage. Algumas operações, como listar o conteúdo de um bucket, podem ficar lentas se a largura de banda da rede estiver baixa. Da mesma forma, a leitura de um arquivo grande pode levar tempo, já que também é limitada pela largura de banda da rede.

Quando você grava em um bucket, o Cloud Storage FUSE organiza totalmente o objeto na memória. Isso significa que a gravação de arquivos grandes é limitada pela quantidade de memória disponível para a instância do contêiner (o limite máximo de memória do contêiner é de 32 GiB).

A gravação é transferida para o bucket somente quando você executa um close ou um fsync: o objeto completo é enviado/reenviado ao bucket. A única exceção para um objeto que é totalmente reenviado para o bucket é no caso de um arquivo com conteúdo anexado quando o arquivo tem 2 MiB ou mais.

Para saber mais, acesse os recursos a seguir: