Configure montagens de volumes na memória para serviços

Nesta página, descrevemos como configurar um volume dedicado na memória que pode ser usado para leituras e gravações de arquivos com montagens de volumes do Cloud Run. Observe que este recurso é diferente do sistema de arquivos na memória integrado fornecido pelo Cloud Run.

Quando você monta o volume na memória no Cloud Run, ele aparece como arquivos no sistema de arquivos do contêiner. Depois de montar o volume na memória, você o acessa como se fosse um diretório no sistema de arquivos local usando as operações e bibliotecas do sistema de arquivos da sua linguagem de programação.

É possível usar volumes na memória para fazer o seguinte:

  • Limitar o tamanho do volume na memória. Quando você limita o tamanho de um volume, as gravações em um volume total falham. No entanto, isso é melhor do que o cenário em que o Cloud Run encerra as instâncias devido ao alto consumo de memória pelo volume.
  • Compartilhar um volume na memória entre diferentes contêineres em uma única instância do Cloud Run. Quando o Cloud Run faz o escalonamento horizontal para várias instâncias de um serviço, cada instância vai ter o próprio espaço volume compartilhado por todos os contêineres da instância. Este volume está disponível para todos os contêineres quando o Cloud Run faz o escalonamento horizontal para lidar com o tráfego.

Comportamento

Ao criar um volume na memória, recomendamos especificar um limite de tamanho. Se o volume atingir esse limite, outras gravações vão falhar com um erro de falta de memória. A instância pode lidar com esse erro e continuar em execução.

O limite de tamanho é apenas um limite: ele não aloca espaço extra para o volume na memória. Em vez disso, o volume na memória consome a memória configurada para os contêineres. Se você implantar vários contêineres, a memória usada por cada gravação no volume contará como uso da memória do contêiner que gravou os dados.

Se você não especificar um limite de tamanho, ele será definido automaticamente como metade do tamanho total de todos os contêineres no job ou serviço. Por exemplo, o tamanho do volume emptyDir = [Memória (Contêiner A) + Memória (Contêiner B) + Memória (Contêiner N)]/2. Esse comportamento padrão pode fazer com que o limite de tamanho do volume na memória seja maior do que a memória alocada para alguns dos contêineres. Isso pode levar a falhas inesperadas se um único contêiner exceder a memória alocada ao tentar gravar mais dados no volume, mesmo que o limite de tamanho do volume não tenha sido atingido.

Embora a definição de um limite de tamanho seja opcional, recomendamos realizá-la para proteger os contêineres contra a falta de memória e contra falhas.

Caminhos não permitidos

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

Funções exigidas

Para receber as permissões necessárias para configurar e implantar os serviços do Cloud Run, peça ao administrador para conceder a você os seguintes papéis do IAM:

Se você estiver implantando um serviço ou função do código-fonte, você também precisará ter outros papéis concedidos no projeto e na conta de serviço do Cloud Build.

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 serviço do Cloud Run interage com Google Cloud APIs, como as 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.

Configurar um volume na memória

Qualquer mudança na configuração leva à criação de uma nova revisão. As próximas revisões também recebem essa configuração de modo automático, a menos que você faça atualizações explícitas para alterar esse comportamento.

Depois de configurar um volume na memória para o serviço do Cloud Run, um volume vazio é criado para cada instância do Cloud Run iniciada e continua existindo enquanto a instância estiver em execução. Quando a execução da instância é interrompida, os dados no volume são excluídos permanentemente.

Console

  1. No Google Cloud console, acesse o Cloud Run:

    Acessar o Cloud Run

  2. Selecione Serviços no menu de navegação do Cloud Run e clique em Implantar contêiner para configurar um novo serviço. Se você estiver configurando um serviço atual, clique nele e em Editar e implantar nova revisão.

  3. Ao configurar um novo serviço, preencha a página inicial de configurações de serviço e clique em Contêineres, Rede, segurança para expandir essa página.

  4. Clique na guia Volumes.

    imagem

    • Clique em Montar volume.
    • Clique em Na memória como o tipo de volume.
    • No campo Caminho da ativação, insira o caminho em que você quer montar o volume.
    • No campo Nome do volume, insira o nome do volume.
    • Opcional: insira o Limite de tamanho e a Unidade de memória para especificar o limite de memória que você quer atribuir ao volume. Esse limite precisa ser menor que a memória total especificada para os contêineres. Os dados armazenados nesse volume consomem a memória reservada pelo contêiner que gravou os dados.
    • Clique em Salvar.

  5. Clique em Criar ou Implantar.

gcloud

  • Para montar um volume:

    gcloud beta run services update SERVICE \
  --add-volume mount-path=MOUNT_PATH,type=in-memory,size-limit=SIZE_LIMIT

    Substitua:

    • SERVICE: o nome do serviço.
    • MOUNT_PATH: o caminho relativo no sistema de arquivos do contêiner em que você quer montar esse volume, por exemplo, /mnt/my-volume.
    • SIZE_LIMIT: o limite de memória que você quer atribuir ao volume, em MiB ou GiB (especificado como Mi ou Gi), por exemplo, 500Mi. Esse limite precisa ser menor que a memória total especificada para os contêineres.

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

    gcloud run services update SERVICE \
  --add-volume=name= VOLUME_NAME,type=in-memory,size-limit=SIZE_LIMIT \
  --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

  1. 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 services describe SERVICE --format export > service.yaml

  2. Configure os atributos volumeMounts e volumes conforme mostrado abaixo:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE_NAME
spec:
  template:
    spec:
      containers:
      - image: IMAGE_URL
        volumeMounts:
        - mountPath: MOUNT_PATH
          name: VOLUME_NAME
      volumes:
      - name: VOLUME_NAME
        emptyDir:
          sizeLimit: SIZE_LIMIT
          medium: Memory

    Substitua:

    • IMAGE_URL: 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 segue o formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
    • VOLUME_NAME: qualquer nome que você queira para o volume. O valor VOLUME_NAME é usado para mapear o volume para a montagem associada.
    • MOUNT_PATH: o caminho relativo no sistema de arquivos do contêiner em que você quer montar esse volume, por exemplo, /mnt/my-volume.
    • SIZE_LIMIT: o limite de memória que você quer atribuir ao volume, em MiB ou GiB (especificado como Mi ou Gi), por exemplo, 500Mi. Esse limite precisa ser menor que a memória total especificada para os contêineres.

  3. Crie ou atualize o serviço usando o seguinte comando:

    gcloud run services replace service.yaml

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

Adicione o seguinte a um google_cloud_run_v2_service recurso na configuração do Terraform:
resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE_NAME"
  location = "REGION"

  template {
    containers {
      image = "IMAGE_URL"
      volume_mounts {
        name = "VOLUME_NAME"
        mount_path = "MOUNT_PATH"
      }
    }
    volumes {
      name = "VOLUME_NAME"
      empty_dir {
        medium = "MEMORY"
        size_limit = "SIZE_LIMIT"
      }
    }
  }
}

Substitua:

  • SERVICE_NAME: o nome do serviço do Cloud Run.
  • REGION: a Google Cloud região. Por exemplo, europe-west1.
  • IMAGE_URL: 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 segue o formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
  • VOLUME_NAME: qualquer nome que você queira para o volume. O valor VOLUME_NAME é usado para mapear o volume para a montagem associada.
  • MOUNT_PATH: o caminho relativo no sistema de arquivos do contêiner em que você quer montar esse volume, por exemplo, /mnt/my-volume.
  • SIZE_LIMIT: o limite de memória que você quer atribuir ao volume, em MiB ou GiB (especificado como Mi ou Gi), por exemplo, 500Mi. Esse limite precisa ser menor que a memória total especificada para os contêineres.

Escrever

Para especificar montagens de volume na memória no arquivo compose.yaml, use a extensão específica do Google x-google-cloudrun:volume-type: in-memory.

  services:
    web:
      image: IMAGE
      volumes:
        - VOLUME_NAME:MOUNT_PATH
  volumes:
    VOLUME_NAME:
      x-google-cloudrun:
        volume-type: in-memory

Substitua:

  • IMAGE: o URL da imagem do contêiner.
  • VOLUME_NAME: o nome do volume na memória.
  • MOUNT_PATH: o caminho em que você quer montar o volume, por exemplo, /mnt/my-volume.

Implantar os serviços

  1. Para implantar os serviços, execute o comando gcloud run compose up:

    gcloud run compose up compose.yaml

  2. Responda y a todas as solicitações para instalar os componentes necessários ou ativar as APIs.

  3. Opcional: torne seu serviço público se você quiser permitir o acesso não autenticado ao serviço.

Após a implantação, o URL do serviço do Cloud Run será exibido. Copie esse URL e cole-o no navegador para visualizar o contêiner em execução. É possível desativar a autenticação padrão no Google Cloud console do.

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 registros no volume, /mnt/my-volume: 

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

Limpar e remover volumes e montagens de volume

É possível limpar todos os volumes e montagens ou remover volumes individuais e montagens de volume.

Limpar todos os volumes e montagens de volume

Para limpar todos os volumes e montagens de volume do serviço de contêiner único, execute o seguinte comando:

gcloud run services update SERVICE \
    --clear-volumes
    --clear-volume-mounts

Se você tiver vários contêineres, siga as convenções da CLI de sidecars para limpar volumes e montagens de volume:

gcloud run services update SERVICE \
    --container=container1 \
    --clear-volumes
    -–clear-volume-mounts \
    --container=container2 \
    --clear-volumes \
    -–clear-volume-mounts

Remover volumes e montagens de volume individuais

Para remover um volume, também é necessário remover todas as montagens de volume que usam esse volume.

Para remover volumes ou montagens de volume individuais, use as remove-volume e remove-volume-mount flags:

gcloud run services update SERVICE \
    --remove-volume VOLUME_NAME \
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH