Ativar buckets do Cloud Storage como volumes persistentes

Este guia mostra como usar volumes permanentes do Kubernetes apoiados por seus buckets do Cloud Storage para gerenciar recursos de armazenamento dos pods do Kubernetes no Google Kubernetes Engine (GKE). Considere usar essa opção de armazenamento se você já tiver familiaridade com PersistentVolumes e quiser 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 permanentes do Kubernetes, consulte Montar buckets do Cloud Storage como volumes efêmeros do CSI.

Antes de começar

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

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 apoiado por um bucket do Cloud Storage envolve estas operações:

  1. Definição de armazenamento: você define um PersistentVolume no cluster do GKE, 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 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.

  2. 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.

  3. 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 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.

  4. Reconexão: se o pod for reiniciado ou reprogramado para outro nó, o driver CSI remontará o mesmo bucket no novo nó, garantindo a acessibilidade dos dados.

Criar um PersistentVolume

  1. Crie um manifesto do 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 exemplo de manifesto 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 em uma string separada por vírgulas, sem espaços.
    • 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.

  2. Aplique o manifesto ao cluster:

    kubectl apply -f PV_FILE_PATH

    Substitua PV_FILE_PATH pelo caminho para o arquivo YAML.

Criar um PersistentVolumeClaim

  1. 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:

    • Os campos spec.storageClassName nos manifestos PersistentVolume e PersistentVolumeClaim precisam corresponder. O storageClassName não precisa se referir a um objeto StorageClass. Para vincular a declaração a um volume, use o nome que quiser, mas ele não pode ficar em branco.
    • Os campos spec.accessModes nos manifestos PersistentVolume e PersistentVolumeClaim precisam corresponder.
    • 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.

  2. 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

  1. Crie um manifesto de 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:

    O manifesto de exemplo mostra estas configurações obrigatórias:

    Se quiser, ajuste estas variáveis:

    • spec.containers[n].volumeMonts[n].readOnly: especifique "true" se apenas ativações de volume específicas forem somente leitura.
    • spec.volumes[n].persistentVolumeClaim.readOnly: especifique "true" se todas as ativações de volumes forem somente leitura.

  2. Aplique o manifesto ao cluster:

    kubectl apply -f POD_FILE_PATH

    Substitua POD_FILE_PATH pelo caminho para o arquivo YAML.

(Opcional) Faça a montagem do mesmo bucket do Cloud Storage com diferentes volumes permanentes {:#mount-same-bucket-different-pv}. Disponível a partir da versão 1.33.0-gke.1932000 do GKE.

Para montar o mesmo bucket do Cloud Storage usando vários volumes permanentes diferentes, use um volumeHandle exclusivo para cada volume permanente. No objeto PersistentVolume, use o formato BUCKET_NAME:UNIQUE_SUFFIX para o campo volumeHandle. Substitua BUCKET_NAME pelo nome do seu bucket e UNIQUE_SUFFIX por qualquer identificador exclusivo que você quiser. Exemplo: myBucket:xyz123.

Um exemplo de caso de uso seria montar o mesmo bucket do Cloud Storage no mesmo nó várias vezes, cada uma com um conjunto distinto de opções de montagem.

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 rastreamento.

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

A seguir