Algumas ou todas as informações nesta página podem não se aplicar ao Cloud de Confiance da S3NS. Consulte Diferenças do Google Cloud para saber mais.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Ativar buckets do Cloud Storage como volumes permanentes

Autopilot Standard

Neste guia, mostramos como usar volumes permanentes do Kubernetes com suporte dos seus buckets do Cloud Storage para gerenciar recursos de armazenamento dos seus pods do Kubernetes no Google Kubernetes Engine (GKE). Use essa opção de armazenamento se você já conhece os PersistentVolumes e quer consistência com suas implantações atuais que dependem desse tipo de recurso.

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

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

Se você quiser uma interface simplificada baseada em pods que não exija experiência anterior com volumes persistentes do Kubernetes, consulte Montar buckets do Cloud Storage como volumes temporários do CSI.

Antes de começar

Verifique se você atende aos seguintes pré-requisitos:

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

Como os volumes permanentes para buckets do Cloud Storage funcionam

Com o provisionamento estático, você cria um ou mais objetos PersistentVolume contendo os detalhes do sistema de armazenamento subjacente. Os pods nos clusters podem consumir o armazenamento por meio de PersistentVolumeClaims.

Usar um volume permanente com suporte de um bucket do Cloud Storage envolve estas operações:

Definição de armazenamento: você define um PersistentVolume no cluster do GKE, incluindo o driver CSI a ser usado e 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 aumentar o desempenho do app do GKE armazenando em cache os arquivos do Cloud Storage acessados com frequência em um disco local 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. Use esse recurso para melhorar os tempos de carregamento de modelos, principalmente para leituras com mais de 1 GB.

Dica: para outras maneiras de ajustar o desempenho do driver CSI, consulte Otimizar o desempenho do driver CSI do Cloud Storage FUSE.
Invocação do driver: quando um PersistentVolumeClaim solicita armazenamento que corresponda à especificação do PersistentVolume, o GKE invoca o driver CSI do Cloud Storage FUSE.
Montagem de bucket: o driver CSI monta o bucket no nó em que o pod solicitante está programado. Isso torna o conteúdo do bucket acessível ao pod como um diretório no sistema de arquivos local do pod. 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.
Reanexação: se o pod for reiniciado ou reprogramado para outro nó, o driver CSI vai remontar o mesmo bucket no novo nó, garantindo a acessibilidade dos dados.

Criar um PersistentVolume

Crie um manifesto PersistentVolume com a seguinte especificação:
Pod
apiVersion: v1 kind: PersistentVolume metadata: name: gcs-fuse-csi-pv spec: accessModes: - ReadWriteMany capacity: storage: 5Gi storageClassName: example-storage-class mountOptions: - implicit-dirs csi: driver: gcsfuse.csi.storage.gke.io volumeHandle: BUCKET_NAME claimRef: name: gcs-fuse-csi-static-pvc namespace: NAMESPACE
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 Cloud Storage FUSE.
O manifesto de exemplo mostra estas configurações obrigatórias:
- spec.csi.driver: use gcsfuse.csi.storage.gke.io como o nome do driver CSI.
Se quiser, ajuste estas variáveis:
- spec.mountOptions: transmita opções de suporte para o Cloud Storage FUSE. Especifique as flags como uma lista. Para mais detalhes, consulte opções de montagem de volume permanente.
- spec.csi.volumeAttributes: transmita outros atributos de volume para o Cloud Storage FUSE.
Pod (armazenamento em cache de arquivos)
apiVersion: v1 kind: PersistentVolume metadata: name: gcs-fuse-csi-pv spec: accessModes: - ReadWriteMany capacity: storage: 5Gi storageClassName: example-storage-class mountOptions: - implicit-dirs - file-cache:max-size-mb:-1 csi: driver: gcsfuse.csi.storage.gke.io volumeHandle: BUCKET_NAME claimRef: name: gcs-fuse-csi-static-pvc namespace: NAMESPACE
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 Cloud Storage FUSE.
Pod (download paralelo)
apiVersion: v1 kind: PersistentVolume metadata: name: gcs-fuse-csi-pv spec: accessModes: - ReadWriteMany capacity: storage: 5Gi storageClassName: example-storage-class mountOptions: - implicit-dirs - file-cache:enable-parallel-downloads:true - file-cache:max-size-mb:-1 csi: driver: gcsfuse.csi.storage.gke.io volumeHandle: BUCKET_NAME claimRef: name: gcs-fuse-csi-static-pvc namespace: NAMESPACE
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 Cloud Storage FUSE.
Aplique o manifesto ao cluster:
```
kubectl apply -f PV_FILE_PATH
```
Substitua PV_FILE_PATH pelo caminho para o arquivo YAML.

Criar um PersistentVolumeClaim

Crie um manifesto PersistentVolumeClaim com a seguinte especificação:
```
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gcs-fuse-csi-static-pvc
  namespace: NAMESPACE
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  storageClassName: example-storage-class
```
Substitua NAMESPACE pelo namespace do Kubernetes em que você quer implantar o pod.

Para vincular seu PersistentVolume a um PersistentVolumeClaim, verifique estas configurações:
- spec.storageClassName: o storageClassName nos manifestos PersistentVolume e PersistentVolumeClaim precisa ser igual para que a declaração seja vinculada ao volume. O driver CSI do Cloud Storage FUSE não usa objetos StorageClass. Basta garantir que o campo storageClassName seja idêntico nos dois recursos. Você pode usar uma string vazia ou não vazia para esse campo. Ele não precisa se referir a um objeto StorageClass existente e serve apenas como um rótulo de vinculação entre o PV e o PVC.
- Os campos spec.accessModes nos manifestos PersistentVolume e PersistentVolumeClaim precisam ser correspondentes.
- O campo spec.capacity.storage no manifesto do PersistentVolume precisa corresponder ao spec.resources.requests.storage no manifesto do PersistentVolumeClaim. Como os buckets do Cloud Storage não têm limites de tamanho, é possível colocar qualquer número para a capacidade, mas ele não pode ficar vazio.
Aplique o manifesto ao cluster:
```
kubectl apply -f PVC_FILE_PATH
```
Substitua PVC_FILE_PATH pelo caminho para o arquivo YAML.

Consumir o volume em um pod

Crie um manifesto do pod com a seguinte especificação:
```
apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-static-pvc  
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"]
    volumeMounts:
    - name: gcs-fuse-csi-static
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-static
    persistentVolumeClaim:
      claimName: gcs-fuse-csi-static-pvc
      readOnly: true  
```
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ê criou ao configurar o acesso aos buckets do Cloud Storage.
O manifesto de exemplo mostra estas configurações obrigatórias:
- metadata.annotations: a anotação gke-gcsfuse/volumes: "true" é obrigatória. Consulte Configurar o contêiner secundário para anotações opcionais.
Se quiser, você pode ajustar estas variáveis:
- spec.containers[n].volumeMounts[n].readOnly: especifique "true" se somente ativações de volume específicas forem somente leitura.
- spec.volumes[n].persistentVolumeClaim.readOnly: especifique true se todas as montagens de volume forem somente leitura.
Aplique o manifesto ao cluster:
```
kubectl apply -f POD_FILE_PATH
```
Substitua POD_FILE_PATH pelo caminho para o arquivo YAML.

(Opcional) Montar o mesmo bucket do Cloud Storage com PersistentVolumes diferentes

A partir da versão 1.33.0-gke.1932000 do GKE, é possível usar vários PersistentVolumes com suporte do mesmo bucket do Cloud Storage. Em cada objeto PersistentVolume, use um volumeHandle exclusivo no formato BUCKET_NAME:UNIQUE_SUFFIX.

Um exemplo de caso de uso seria a montagem de diferentes PersistentVolumes com diferentes opções de montagem no mesmo pod, em que cada PersistentVolume se refere ao mesmo bucket do Cloud Storage.

Resolver problemas

Para mais informações sobre a solução de problemas do driver CSI do Cloud Storage FUSE, consulte o guia de solução de problemas na documentação do projeto do GitHub.