Esta página foi traduzida pela API Cloud Translation.

Ativar buckets do Cloud Storage como volumes temporários do CSI

Autopilot Standard

Este guia mostra como usar volumes temporários do CSI com suporte dos buckets do Cloud Storage para gerenciar automaticamente os recursos de armazenamento dos pods ou jobs do Kubernetes no Google Kubernetes Engine (GKE). Os volumes temporários CSI estão vinculados ao ciclo de vida do pod ou do job, e não é necessário gerenciar manualmente os objetos PersistentVolume e PersistentVolumeClaim.

Este guia é destinado a administradores e operadores de plataformas que querem simplificar o gerenciamento de armazenamento dos aplicativos do GKE.

Antes de ler esta página, confira se você conhece os volumes temporários do CSI, os pods e jobs do Kubernetes e os buckets do Cloud Storage.

Se você já conhece os PersistentVolumes e quer consistência nas implantações que dependem desse tipo de recurso, consulte Montar buckets do Cloud Storage como volumes permanentes.

Antes de começar

Verifique se você concluiu estes pré-requisitos:

Entenda os requisitos e as limitações do driver CSI do Cloud Storage FUSE.
Crie o bucket do Cloud Storage
Ativar o driver CSI do Cloud Storage FUSE
Configurar o acesso a buckets do Cloud Storage

Como o armazenamento temporário do CSI para buckets do Cloud Storage funciona

Os volumes temporários do CSI simplificam o gerenciamento de armazenamento para seus aplicativos no GKE. Você define volumes temporários do CSI diretamente na especificação do pod ou do job. O uso de volumes temporários do CSI elimina a necessidade de objetos PersistentVolume e PersistentVolumeClaim separados.

O uso de um volume temporário CSI envolve estas operações:

Definição de armazenamento: especifique o armazenamento no arquivo YAML do pod ou job, incluindo o driver CSI a ser usado e todos os parâmetros necessários. Para o driver CSI do Cloud Storage FUSE, especifique o nome do bucket e outros detalhes relevantes.

Se quiser, ajuste o desempenho do driver CSI usando o recurso de armazenamento em cache de arquivos. O armazenamento em cache de arquivos pode melhorar o desempenho do app do GKE armazenando em cache os arquivos do Cloud Storage acessados com frequência em um disco mais rápido.

Além disso, é possível usar o recurso de download paralelo para acelerar a leitura de arquivos grandes do Cloud Storage para downloads multithread. Esse recurso pode ser usado para melhorar os tempos de carregamento de modelos, principalmente para leituras com mais de 1 GB.

Dica: para saber outras maneiras de ajustar o desempenho do driver CSI, consulte Otimizar o desempenho do driver CSI do FUSE do Cloud Storage.
Invocação de driver: quando você cria o pod ou job, o GKE detecta a solicitação de volume temporário e chama o driver CSI do Cloud Storage FUSE.
Montagem e anexo de volume: o driver CSI monta o volume temporário CSI (que aponta para o bucket do Cloud Storage) e o disponibiliza para o pod ou job, tornando-o acessível ao aplicativo. Para ajustar como os buckets são montados no sistema de arquivos, use as opções de montagem. Também é possível usar atributos de volume para configurar o comportamento específico do driver CSI do Cloud Storage FUSE.
Gerenciamento de ciclo de vida: o volume temporário existe durante a vida útil do pod ou job. Quando o pod é excluído ou o job é concluído, o driver CSI processa automaticamente a limpeza e a desmontagem do volume.

Anexar o volume temporário do CSI

Siga estas instruções, dependendo se você quer anexar o volume temporário do CSI a um pod ou job.

Pod

Para anexar o volume temporário CSI a um pod, siga estas etapas:

Crie um manifesto YAML do pod com a seguinte especificação:
```
apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral 
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true" 
spec:
  terminationGracePeriodSeconds: 60
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"] 
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      readOnly: true
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs" 
```
Substitua os seguintes valores:
- NAMESPACE: o namespace do Kubernetes em que você quer implantar o pod.
- KSA_NAME: o nome da conta de serviço do Kubernetes que você especificou ao configurar o acesso aos buckets do Cloud Storage.
- BUCKET_NAME: o nome do bucket do Cloud Storage especificado ao configurar o acesso aos buckets do Cloud Storage. É possível especificar um sublinhado (_) para ativar todos os buckets que a conta de serviço do Kubernetes pode acessar. Para saber mais, consulte Ativação dinâmica na documentação do FUSE do Cloud Storage.
O exemplo de manifesto mostra estas configurações obrigatórias:
- metadata.annotations: a anotação gke-gcsfuse/volumes: "true" é obrigatória. Consulte Configurar o contêiner de arquivo secundário para ver anotações opcionais.
- spec.volumes[n].csi.driver: use gcsfuse.csi.storage.gke.io como o nome do driver CSI.
Também é possível ajustar estas variáveis:
- spec.terminationGracePeriodSeconds: por padrão, esse valor é definido como 30. Se você precisar gravar arquivos grandes no bucket do Cloud Storage, aumente esse valor para garantir que o Cloud Storage FUSE tenha tempo suficiente para esvaziar os dados após o encerramento do aplicativo. Para saber mais, consulte Práticas recomendadas do Kubernetes: encerrar com carência.
- spec.volumes[n].csi.volumeAttributes.mountOptions: transmita opções de montagem para o Cloud Storage FUSE. Especifique as flags em uma string separada por vírgulas, sem espaços.
- spec.volumes[n].csi.volumeAttributes: transmita outros atributos de volume para o Cloud Storage FUSE.
- spec.volumes[n].csi.readOnly: especifique "true" se todas as montagens de volume forem somente leitura.
- spec.containers[n].volumeMounts[m].readOnly: especifique "true" se apenas uma montagem de volume específica for somente leitura.
Execute o comando a seguir para aplicar o manifesto ao cluster:
```
kubectl apply -f FILE_PATH
```
Substitua FILE_PATH pelo caminho para o arquivo YAML.

Pod (armazenamento em cache de arquivos)

Para anexar o volume temporário CSI com armazenamento em cache de arquivos em um pod, siga estas etapas:

Crie um cluster ou pool de nós com armazenamento temporário com suporte de SSD local seguindo as etapas em Criar um cluster ou pool de nós com armazenamento temporário com suporte de SSD local.

Observação: se você quiser ajustar o tipo de armazenamento do cache de arquivos (por exemplo, se estiver usando uma VM TPU e quiser usar a RAM para um processamento mais rápido), consulte Selecionar o armazenamento para fazer backup do cache de arquivos.

Crie um manifesto YAML do pod com a seguinte especificação:

apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-file-cache-example 
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
spec:
  nodeSelector:
    cloud.google.com/gke-ephemeral-storage-local-ssd: "true"
  restartPolicy: Never
  initContainers:
  - name: data-loader
    image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
    resources:
      limits:
        cpu: 500m
        memory: 1Gi
      requests:
        cpu: 500m
        memory: 1Gi
    command:
      - "/bin/sh"
      - "-c"
      - |
        mkdir -p /test_files
        for i in $(seq 1 1000); do dd if=/dev/zero of=/test_files/file_$i.txt bs=1024 count=64; done
        gcloud storage cp /test_files gs://BUCKET_NAME --recursive
  containers:
  - name: data-validator
    image: busybox
    resources:
      limits:
        cpu: 500m
        memory: 512Mi
      requests:
        cpu: 500m
        memory: 512Mi
    command:
      - "/bin/sh"
      - "-c"
      - |
        echo "first read with cache miss"
        time cat /data/test_files/file_* > /dev/null

        echo "second read from local cache"
        time cat /data/test_files/file_* > /dev/null 
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs,file-cache:max-size-mb:-1"

Substitua os seguintes valores:

NAMESPACE: o namespace do Kubernetes em que você quer implantar o pod.
KSA_NAME: o nome da conta de serviço do Kubernetes que você especificou ao configurar o acesso aos buckets do Cloud Storage.
BUCKET_NAME: o nome do bucket do Cloud Storage especificado ao configurar o acesso aos buckets do Cloud Storage. É possível especificar um sublinhado (_) para ativar todos os buckets que a conta de serviço do Kubernetes pode acessar. Para saber mais, consulte Ativação dinâmica na documentação do FUSE do Cloud Storage.

No exemplo de manifesto, o data-loader do contêiner inicial gera 1.000 arquivos com 64 KiB e faz upload dos arquivos para um bucket do Cloud Storage. O contêiner principal data-validator lê todos os arquivos do bucket duas vezes e registra a duração.

Execute o comando a seguir para aplicar o manifesto ao cluster:
```
kubectl apply -f FILE_PATH
```
Substitua FILE_PATH pelo caminho para o arquivo YAML.
Para ver a resposta, execute o seguinte comando:
```
kubectl logs -n NAMESPACE gcs-fuse-csi-file-cache-example -c data-validator
```
Substitua NAMESPACE pelo namespace da carga de trabalho.

A saída será parecida com esta:
```
first read with cache miss
real    0m 54.68s
...
second read from local cache
real    0m 0.38s
...
```
A saída mostra que a segunda leitura com cache local é muito mais rápida que a primeira leitura com ausência no cache.

Pod (download paralelo)

Para anexar o volume temporário do CSI com download paralelo em um pod, siga estas etapas:

Crie um manifesto YAML do pod com a seguinte especificação:

apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral 
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
spec:
  containers:
  ...
  volumes:
  - name: gcs-fuse-csi-ephemeral 
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs,file-cache:enable-parallel-downloads:true,file-cache:max-size-mb:-1"
        fileCacheCapacity: "-1"

Substitua os seguintes valores:

NAMESPACE: o namespace do Kubernetes em que você quer implantar o pod.
BUCKET_NAME: o nome do bucket do Cloud Storage especificado ao configurar o acesso aos buckets do Cloud Storage. É possível especificar um sublinhado (_) para ativar todos os buckets que a conta de serviço do Kubernetes pode acessar. Para saber mais, consulte Ativação dinâmica na documentação do FUSE do Cloud Storage.

Execute o comando a seguir para aplicar o manifesto ao cluster:
```
kubectl apply -f FILE_PATH
```
Substitua FILE_PATH pelo caminho para o arquivo YAML.

Job

Para anexar o volume temporário do CSI em um job, siga estas etapas:

Crie um manifesto YAML de job com a seguinte especificação:
```
apiVersion: batch/v1
kind: Job
metadata:
  name: gcs-fuse-csi-job-example 
  namespace: NAMESPACE 
spec:
  template:
    metadata: 
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME 
      containers:
      - name: writer
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - touch /data/test && echo $(date) >> /data/test && sleep 10
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
      - name: reader
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - sleep 10 && cat /data/test 
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
          readOnly: true
      volumes:
      - name: gcs-fuse-csi-ephemeral
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: BUCKET_NAME
      restartPolicy: Never 
  backoffLimit: 1
```
Substitua os seguintes valores:
- NAMESPACE: o namespace do Kubernetes em que você implanta o pod.
- KSA_NAME: o nome da conta de serviço do Kubernetes que você especificou ao configurar o acesso aos buckets do Cloud Storage.
- BUCKET_NAME: o nome do bucket do Cloud Storage especificado ao configurar o acesso aos buckets do Cloud Storage. É possível especificar um sublinhado (_) para ativar todos os buckets que a conta de serviço do Kubernetes pode acessar. Para saber mais, consulte Ativação dinâmica na documentação do FUSE do Cloud Storage.
O exemplo de manifesto mostra estas configurações obrigatórias:
- metadata.annotations: a anotação gke-gcsfuse/volumes: "true" é obrigatória. Consulte Configurar o contêiner de arquivo secundário para ver anotações opcionais.
- spec.volumes[n].csi.driver: use gcsfuse.csi.storage.gke.io como o nome do driver CSI.
Também é possível ajustar estas variáveis:
- spec.volumes[n].csi.volumeAttributes.mountOptions: transmita opções de montagem para o Cloud Storage FUSE. Especifique as flags em uma string separada por vírgulas, sem espaços.
- spec.volumes[n].csi.volumeAttributes: transmita outros atributos de volume para o Cloud Storage FUSE.
- spec.volumes[n].csi.readOnly: especifique "true" se todas as ativações de volume forem somente leitura.
- spec.containers[n].volumeMounts[m].readOnly: especifique "true" se apenas uma montagem de volume específica for somente leitura.
Execute o comando a seguir para aplicar o manifesto ao cluster:
```
kubectl apply -f FILE_PATH
```
Substitua FILE_PATH pelo caminho para o arquivo YAML.

Resolver problemas

Se você precisar resolver problemas do Cloud Storage FUSE, defina a flag log-severity como TRACE. Defina a flag na seção args da especificação do contêiner do driver no YAML de implantação. Isso faz com que o atributo de volume gcsfuseLoggingSeverity seja definido automaticamente como trace.

Para mais dicas de solução de problemas, consulte o Guia de solução de problemas na documentação do projeto do GitHub.