Acessar buckets do Cloud Storage com o driver FUSE CSI do Cloud Storage

O sistema de arquivos no espaço do usuário (FUSE, na sigla em inglês) é uma interface usada para exportar um sistema de arquivos para o kernel do Linux. O Cloud Storage FUSE permite ativar buckets do Cloud Storage como um sistema de arquivos para que os aplicativos possam acessar os objetos em um bucket usando operações comuns de E/S de arquivo (por exemplo, abrir, ler, gravar e fechar) em vez de usar APIs específicas da nuvem.

O driver FUSE CSI do Cloud Storage permite usar a API Kubernetes para consumir buckets pré-existentes do Cloud Storage como volumes. Seus aplicativos podem fazer upload e download de objetos usando a semântica do sistema de arquivos do Cloud Storage FUSE. O driver FUSE CSI do Cloud Storage fornece uma experiência totalmente gerenciada com a tecnologia de código aberto do driver FUSE CSI do Google Cloud Storage.

O driver é compatível nativamente com as seguintes maneiras de configurar seus volumes compatíveis com o Cloud Storage:

É possível usar o driver CSI do Cloud Storage FUSE com armazenamento em cache de arquivos para melhorar o desempenho de leitura de aplicativos que processam arquivos pequenos de buckets do Cloud Storage. O recurso de cache de arquivos do Cloud Storage FUSE é um cache de leitura baseado em cliente que permite que leituras repetidas de arquivos sejam veiculadas mais rapidamente a partir do armazenamento em cache de sua escolha. Escolha entre uma variedade de opções de armazenamento para o cache de leitura, incluindo SSDs locais e armazenamento baseado em disco permanente, de acordo com suas necessidades de preço-desempenho. É necessário ativar a ativação do armazenamento em cache de arquivos com o driver CSI do Cloud Storage FUSE. Para saber mais sobre as práticas recomendadas de armazenamento em cache, consulte Desempenho e práticas recomendadas do Cloud Storage FUSE.

Benefícios

  • O driver FUSE CSI do Cloud Storage no cluster ativa a implantação e o gerenciamento automáticos do driver. O driver funciona em clusters Standard e Autopilot.
  • O driver FUSE CSI do Cloud Storage não precisa de acesso privilegiado, que normalmente é exigido pelos clientes do FUSE. Isso melhora a postura de segurança.
  • O suporte a volumes temporários CSI simplifica a configuração e o gerenciamento de volumes, eliminando a necessidade de objetos PersistentVolumeClaim e PersistentVolume.
  • O driver CSI do Cloud Storage FUSE é compatível com os modos de acesso ReadWriteMany, ReadOnlyMany e ReadWriteOnce.
  • É possível usar a federação de identidade da carga de trabalho do GKE para gerenciar a autenticação e ter controle granular sobre como os pods acessam objetos do Cloud Storage.
  • Se você estiver executando cargas de trabalho de treinamento e disponibilização de ML com frameworks como Ray, PyTorch, Spark e TensorFlow, a portabilidade e a simplicidade fornecidas pelo driver CSI do Cloud Storage FUSE permitem que você execute suas cargas de trabalho diretamente nos clusters do GKE sem alterações adicionais no código.
  • Leia objetos do Cloud Storage com armazenamento em cache de arquivos ativado para melhorar o desempenho de leitura. Para saber mais sobre os benefícios do armazenamento em cache de arquivos, consulte a documentação do Cloud Storage FUSE.
  • É possível consumir os volumes do Cloud Storage FUSE em contêineres init.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

  • Ativar a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.
  • Crie seus buckets do Cloud Storage. Para melhorar o desempenho, defina o campo Location type como Region e selecione uma região em que o cluster do GKE está em execução.

Limitações

Requisitos

Para usar o driver FUSE CSI do Cloud Storage, os clusters precisam atender aos seguintes requisitos:

Ativar o driver CSI do Cloud Storage FUSE

Para criar um cluster Standard com o driver CSI do Cloud Storage FUSE ativado, use a gcloud CLI:

gcloud container clusters create CLUSTER_NAME \
    --addons GcsFuseCsiDriver \
    --cluster-version=VERSION \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog

Substitua:

  • CLUSTER_NAME: o nome do cluster.
  • VERSION: o número da versão do GKE. Selecione 1.24 ou posterior.
  • LOCATION: a região do Compute Engine para o cluster.
  • PROJECT_ID: o ID do projeto.

Para ativar o driver em um cluster padrão, use o comando gcloud container clusters update:

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=ENABLED \
    --location=LOCATION

Substitua:

Depois de ativar o driver CSI do Cloud Storage FUSE, use o driver em volumes do Kubernetes especificando o nome do provisionador e do driver: gcsfuse.csi.storage.gke.io.

Configurar o acesso aos buckets do Cloud Storage usando a federação de identidade da carga de trabalho do GKE

Para tornar os buckets do Cloud Storage acessíveis pelo cluster do GKE usando a federação de identidade da carga de trabalho do GKE, siga estas etapas. Para mais informações, consulte Configurar aplicativos para usar a federação de identidade da carga de trabalho do GKE.

  1. Receba as credenciais do cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION

    Substitua:

    • CLUSTER_NAME: o nome do cluster com a federação de identidade da carga de trabalho para o GKE ativada.
    • LOCATION: a região do Compute Engine para o cluster.

  2. Crie o namespace que será usado para a conta de serviço do Kubernetes. Também é possível usar o namespace default ou qualquer namespace existente.

    kubectl create namespace NAMESPACE

    Substitua:

    • NAMESPACE: o nome do namespace do Kubernetes da ServiceAccount.

  3. Crie uma conta de serviço do Kubernetes para o aplicativo usar. Também é possível usar qualquer Kubernetes ServiceAccount atual em qualquer namespace, incluindo a default do Kubernetes ServiceAccount.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Substitua:

    • KSA_NAME: o nome da ServiceAccount do Kubernetes.
    • NAMESPACE: o nome do namespace do Kubernetes da ServiceAccount.

  4. Conceda um dos papéis do IAM para o Cloud Storage à conta de serviço do Kubernetes.

    É possível conceder o papel à sua conta de serviço do Kubernetes para acessar apenas um bucket específico do Cloud Storage usando o seguinte comando:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    Substitua:

    • BUCKET_NAME: seu nome do bucket do Cloud Storage
    • PROJECT_NUMBER: o número do projeto numérico do seu cluster do GKE. Para encontrar o número do projeto, consulte Identificar projetos.
    • PROJECT_ID: o ID do projeto do cluster do GKE.
    • NAMESPACE: o nome do namespace do Kubernetes da ServiceAccount.
    • KSA_NAME: o nome da ServiceAccount do Kubernetes.
    • ROLE_NAME: o papel do IAM a ser atribuído à sua conta de serviço do Kubernetes.
      • Para cargas de trabalho somente leitura, use o papel Leitor de objetos do Storage (roles/storage.objectViewer).
      • Para cargas de trabalho de leitura e gravação, use o papel de usuário do objeto do Storage (roles/storage.objectUser).

    Outra opção é conceder o papel à sua conta de serviço do Kubernetes para acessar todos os buckets do Cloud Storage no projeto usando o seguinte comando:

    gcloud projects add-iam-policy-binding GCS_PROJECT \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    Substitua:

    • GCS_PROJECT: o ID do projeto dos buckets do Cloud Storage.
    • PROJECT_NUMBER: o número do projeto numérico do seu cluster do GKE. Para encontrar o número do projeto, consulte Identificar projetos.
    • PROJECT_ID: o ID do projeto do cluster do GKE.
    • NAMESPACE: o nome do namespace do Kubernetes da ServiceAccount.
    • KSA_NAME: o nome da ServiceAccount do Kubernetes.
    • ROLE_NAME: o papel do IAM a ser atribuído à sua conta de serviço do Kubernetes.
      • Para cargas de trabalho somente leitura, use o papel Leitor de objetos do Storage (roles/storage.objectViewer).
      • Para cargas de trabalho de leitura e gravação, use o papel de usuário do objeto do Storage (roles/storage.objectUser).

Preparar-se para ativar buckets do Cloud Storage FUSE

Nesta seção, você saberá como se preparar para ativar buckets do FUSE do Cloud Storage nos clusters.

Especificar anotações de pod

O driver CSI depende das anotações de pod para identificar se o pod usa volumes compatíveis com o Cloud Storage. Se o driver detectar as anotações necessárias, ele injetará um contêiner de arquivo secundário chamado gke-gcsfuse-sidecar no pod da carga de trabalho. As instâncias do Cloud Storage FUSE são executadas dentro do contêiner do arquivo secundário e ativam os buckets do Cloud Storage para sua carga de trabalho.

Para ativar o driver CSI para ativar os buckets do Cloud Storage, especifique a anotação gke-gcsfuse/volumes: "true" na especificação do pod, no campo metadata. Se você quiser que seus volumes compatíveis com o Cloud Storage sejam consumidos por outros tipos de carga de trabalho do Kubernetes (por exemplo, Job, Implantação ou StatefulSet), configure as anotações no campo spec.template.metadata.annotations.

Configurar recursos para o contêiner de arquivo secundário

Por padrão, o contêiner do arquivo secundário é configurado com as seguintes solicitações de recursos, com os limites não definidos:

  • 250m CPU
  • 256 MiB de memória
  • Armazenamento temporário de 5 GiB

Para substituir esses valores, é possível especificar a anotação gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request], conforme mostrado no exemplo a seguir:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/cpu-limit: "10"
    gke-gcsfuse/memory-limit: 10Gi
    gke-gcsfuse/ephemeral-storage-limit: 1Ti
    gke-gcsfuse/cpu-request: 500m
    gke-gcsfuse/memory-request: 1Gi
    gke-gcsfuse/ephemeral-storage-request: 50Gi

Use as seguintes considerações ao decidir a quantidade de recursos para alocar:

  • Se você definir apenas uma das solicitações de recurso ou anotações de limite, o GKE aplicará os mesmos valores para a solicitação e o limite de recursos.
  • Se o pod da carga de trabalho consumir vários volumes do Cloud Storage, os recursos do contêiner de arquivo secundário serão compartilhados por várias instâncias do FUSE do Cloud Storage. Se isso se aplicar a você, considere aumentar a alocação de recursos para vários volumes do Cloud Storage.
  • Aloque mais CPU para o contêiner de arquivo secundário se as cargas de trabalho precisarem de maior capacidade de processamento. CPU insuficiente causará limitação do Cloud Storage FUSE.
  • Se as cargas de trabalho precisarem processar um grande número de arquivos e o armazenamento em cache de metadados do Cloud Storage FUSE estiver ativado, aumente a alocação de memória do contêiner de arquivos secundários. O consumo de memória do Cloud Storage FUSE para armazenamento em cache de metadados é proporcional ao número de arquivos, mas não ao tamanho deles. Memória insuficiente causará erros de falta de memória do Cloud Storage FUSE e travará o aplicativo da carga de trabalho.
  • Por padrão, para armazenamento em cache de arquivos, o Cloud Storage FUSE armazena os arquivos em um diretório temporário local. Estime quanto espaço livre sua carga de trabalho precisa para armazenamento em cache de arquivos e aumente o limite de armazenamento temporário adequadamente. Para saber mais, consulte Atributos de volume.
  • Para operações de gravação, o FUSE do Cloud Storage prepara por padrão os arquivos em um diretório temporário local antes que os arquivos sejam enviados para o bucket do Cloud Storage. Estime quanto espaço livre a carga de trabalho precisa para se preparar ao gravar arquivos grandes e aumente o limite de armazenamento temporário de acordo. Para saber mais, consulte Semântica de leitura/gravação na documentação do GitHub do Cloud Storage FUSE.
  • É possível usar o valor "0" para cancelar a definição de limites ou solicitações de recursos nos clusters padrão. Por exemplo, a anotação gke-gcsfuse/memory-limit: "0" deixa o limite de memória do contêiner do arquivo secundário vazio com a solicitação de memória padrão. Isso é útil quando não é possível decidir a quantidade de recursos que o Cloud Storage FUSE precisa para as cargas de trabalho, e você quer permitir que o Cloud Storage FUSE consuma todos os recursos disponíveis em um nó. Depois de calcular os requisitos de recursos para o Cloud Storage FUSE com base nas métricas da carga de trabalho, é possível definir os limites apropriados.

Configurar uma imagem particular para o contêiner sidecar

Nesta seção, descrevemos como usar a imagem do contêiner sidecar quando você a hospeda em um registro de contêiner particular. Esse cenário será aplicável se você precisar usar clusters particulares para fins de segurança ou se o cluster tiver acesso limitado à Internet pública. Para configurar e consumir a imagem do contêiner sidecar particular, siga estas etapas:

  1. Consulte esta página para procurar uma imagem de contêiner sidecar público compatível.

  2. Extraia-a para o ambiente local e envie para o registro de contêiner particular.

  3. No manifesto, especifique um contêiner chamado gke-gcsfuse-sidecar apenas com o campo image. O GKE usará a imagem do contêiner sidecar especificada para se preparar para a injeção desse contêiner. Veja um exemplo:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: gke-gcsfuse-sidecar
    image: PRIVATE_REGISTRY/gcs-fuse-csi-driver-sidecar-mounter:PRIVATE_IMAGE_TAG
  - name: main # your main workload container.

Substitua:

  • PRIVATE_REGISTRY: o registro de contêiner particular.
  • PRIVATE_IMAGE_TAG: a tag de imagem do contêiner sidecar particular.

Configurar um volume de gravação de buffer personalizado para o contêiner sidecar

Nesta seção, descrevemos como configurar um volume de buffer personalizado para o armazenamento em buffer de gravação do Cloud Storage FUSE. Este cenário pode ser aplicável se você precisar substituir o volume emptyDir padrão do Cloud Storage FUSE para preparar os arquivos em operações de gravação. É possível especificar qualquer tipo de armazenamento compatível com o GKE, como um PersistentVolumeClaim, e o GKE usará o volume especificado para armazenamento em buffer de gravação de arquivo. Isso é útil se você precisar gravar arquivos maiores que 10 GiB nos clusters do Autopilot. Para usar o volume de buffer personalizado, é necessário especificar um fsGroup diferente de zero. O exemplo a seguir mostra como usar um PVC predefinido como o volume de buffer:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-buffer
    persistentVolumeClaim:
      claimName: BUFFER_VOLUME_PVC

Substitua:

  • FS_GROUP: o ID do fsGroup.
  • BUFFER_VOLUME_PVC: o nome da PVC predefinida.

Configurar um volume de cache de leitura personalizado para o contêiner de arquivo secundário

Nesta seção, descrevemos como configurar um volume de cache personalizado para o armazenamento em cache de leitura do Cloud Storage FUSE. Este cenário pode ser aplicável se você precisar substituir o volume emptyDir padrão do Cloud Storage FUSE para preparar os arquivos em operações de gravação. É possível especificar qualquer tipo de armazenamento compatível com o GKE, como um PersistentVolumeClaim, e o GKE usará o volume especificado para armazenamento em buffer de gravação de arquivo. Isso é útil se você precisar gravar arquivos maiores que 10 GiB nos clusters do Autopilot. Para usar o volume de buffer personalizado, é necessário especificar um fsGroup diferente de zero. O exemplo a seguir mostra como usar um PVC predefinido como o volume de buffer:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-cache
    persistentVolumeClaim:
      claimName: CACHE_VOLUME_PVC

Substitua:

  • FS_GROUP: o ID do fsGroup.
  • CACHE_VOLUME_PVC: o nome da PVC predefinida.

Provisionar seu volume como um volume temporário de CSI

Os volumes temporários de CSI compatíveis com os buckets do Cloud Storage estão vinculados ao ciclo de vida do pod. Com essa abordagem de provisionamento, você não precisa manter os objetos PersistentVolume e PersistentVolumeClaim associados aos buckets do Cloud Storage após o encerramento do pod.

.

Consumir o volume de armazenamento temporário do CSI em um pod

  1. Salve o seguinte manifesto YAML:

    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"
        gcsfuseLoggingSeverity: warning

    O exemplo anterior mostra como especificar o bucket do Cloud Storage inline no manifesto do pod. O exemplo inclui os seguintes campos:

    • metadata.annotations: a anotação gke-gcsfuse/volumes: "true" é obrigatória. Consulte Configurar recursos para o contêiner de arquivo secundário para anotações opcionais.
    • spec.terminationGracePeriodSeconds: opcional. Por padrão, essa opção é definida 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.serviceAccountName: use a mesma conta de serviço do Kubernetes da etapa Configurar o acesso aos buckets do Cloud Storage usando a federação de identidade da carga de trabalho do GKE.
    • spec.volumes[n].csi.driver: use gcsfuse.csi.storage.gke.io como o nome do driver CSI.
    • spec.volumes[n].csi.volumeAttributes.bucketName: especifique o nome do bucket do Cloud Storage FUSE. É 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.
    • spec.volumes[n].csi.volumeAttributes.mountOptions: opcional. Transmita opções de suporte para o Cloud Storage FUSE. Especifique as sinalizações em uma string separada por vírgulas, sem espaços.
    • spec.volumes[n].csi.volumeAttributes: opcional. Transmita outros atributos de volume para o Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly: opcional. Especifique true se todas as ativações de volumes forem somente leitura.
    • spec.containers[n].volumeMounts[m].readOnly: opcional. Especifique true se somente uma ativação de volume específica for somente leitura.

  2. Aplique o manifesto ao cluster:

    kubectl apply -f FILE_PATH

    Substitua FILE_PATH pelo caminho para o arquivo YAML.

Consumir o volume de armazenamento temporário do CSI em uma carga de trabalho do job

  1. Salve o seguinte manifesto YAML:

    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:

    O manifesto implanta um job que consome um bucket do FUSE do Cloud Storage por meio de um volume temporário do CSI.

  2. Aplique o manifesto ao cluster:

    kubectl apply -f FILE_PATH

    Substitua FILE_PATH pelo caminho para o arquivo YAML.

Se você estiver usando o driver CSI em uma carga de trabalho Job ou se o pod RestartPolicy for Never, o contêiner de arquivo secundário será encerrado automaticamente depois que todos os outros contêineres de carga de trabalho forem encerrados.

Para conferir mais exemplos, consulte Exemplos de aplicativos na documentação do projeto do GitHub.

Provisionar seu volume usando o provisionamento estático

Com o provisionamento estático, você cria um ou mais objetos PersistentVolume (PV) contendo os detalhes do sistema de armazenamento subjacente. Os pods nos clusters podem consumir o armazenamento por meio de PersistentVolumeClaims (PVCs, na sigla em inglês).

.

Criar um PersistentVolume

  1. Salve o seguinte manifesto YAML:

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class
  claimRef:
    namespace: NAMESPACE
    name: gcs-fuse-csi-static-pvc
  mountOptions:
    - implicit-dirs
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
    volumeAttributes:
      gcsfuseLoggingSeverity: warning

    O manifesto de exemplo mostra como definir um PersistentVolume para buckets do Cloud Storage. O exemplo inclui os seguintes campos:

    • spec.claimRef.namespace: especifique o namespace PersistentVolumeClaim.
    • spec.claimRef.name: especifique o nome do PersistentVolumeClaim.
    • spec.csi.driver: use gcsfuse.csi.storage.gke.io como o nome do driver CSI.
    • spec.csi.volumeHandle: especifique o nome do bucket do Cloud Storage. É possível transmitir um sublinhado (_) para ativar todos os buckets aos quais a conta de serviço está configurada para ter acesso. Para saber mais, consulte Ativação dinâmica na documentação do FUSE do Cloud Storage.
    • spec.mountOptions: opcional. Transmita opções de suporte para o Cloud Storage FUSE.
    • spec.csi.volumeAttributes: opcional. Transmita os atributos de volume para o Cloud Storage FUSE.

  2. Aplique o manifesto ao cluster:

    kubectl apply -f FILE_PATH

    Substitua FILE_PATH pelo caminho para o arquivo YAML.

Criar um PersistentVolumeClaim

  1. Salve o seguinte manifesto YAML:

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gcs-fuse-csi-static-pvc
  namespace: NAMESPACE
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: gcs-fuse-csi-pv
  storageClassName: example-storage-class

    O manifesto de exemplo mostra como definir um PersistentVolumeClaim para vincular o PersistentVolume. O exemplo inclui os seguintes campos:

    • metadata.namespace: especifique o namespace PersistentVolumeClaim que precisa ser consistente com o namespace da sua carga de trabalho.
    • spec.volumeName: especifique o nome do PersistentVolume.

    Para vincular um PersistentVolume a um PersistentVolumeClaim, siga estas diretrizes:

    • Os campos spec.storageClassName nos manifestos PV e PVC devem ser correspondentes. 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 PV e PVC devem ser correspondentes.
    • spec.capacity.storage no manifesto do PersistentVolume deve corresponder a 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 FILE_PATH

    Substitua FILE_PATH pelo caminho para o arquivo YAML.

Consumir o volume de um PersistentVolumeClaim

  1. Salve o seguinte manifesto YAML:

    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

    No exemplo, mostramos como definir um pod que consome um bucket do FUSE do Cloud Storage por meio de um PersistentVolumeClaim. O exemplo inclui os seguintes campos:

  2. Aplique o manifesto ao cluster:

    kubectl apply -f FILE_PATH

    Substitua FILE_PATH pelo caminho para o arquivo YAML.

Para conferir mais exemplos, consulte Exemplos de aplicativos na documentação do projeto do GitHub.

Consumir seus volumes com o armazenamento em cache de arquivos ativado

Por padrão, o recurso de armazenamento em cache de arquivos está desativado no GKE. Para ativar e controlar o armazenamento em cache de arquivos, use o atributo de volume fileCacheCapacity.

O GKE usa um volume emptyDir para armazenamento em cache de arquivos do Cloud Storage FUSE com suporte do disco de inicialização da VM do nó. Se você ativar o SSD local no nó, o GKE usará o SSD local para retornar o volume emptyDir.

É possível configurar um volume personalizado de cache de leitura para o contêiner de arquivo secundário para substituir o volume emptyDir padrão para armazenamento em cache de arquivos em operações de leitura. Para famílias de CPU e GPU de VM com suporte a SSD local, recomendamos o uso do armazenamento SSD local. Para famílias de TPU ou Autopilot, recomendamos o uso de Persistent Disk equilibrado ou disco permanente SSD.

Consumir um volume de armazenamento temporário do CSI com o armazenamento em cache de arquivos ativado

Para implantar um pod que consome um bucket do Cloud Storage FUSE por meio de um volume temporário CSI com armazenamento em cache de arquivos, siga estas etapas:

  1. Criar um cluster ou pool de nós com armazenamento temporário via SSD local

    Siga a documentação do GKE para criar um cluster ou pool de nós com armazenamento temporário com SSD local.

  2. Salve o seguinte manifesto YAML:

    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
        gsutil -m cp -r /test_files gs://BUCKET_NAME
  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"
        fileCacheCapacity: "10Gi"

    Substitua:

    O contêiner init data-loader 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.

  3. Aplique o manifesto ao cluster:

    kubectl apply -f FILE_PATH

    Substitua FILE_PATH pelo caminho para o arquivo YAML.

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

    O resultado será assim:

    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.

Configurar como os buckets do Cloud Storage FUSE são ativados

Nesta seção, descrevemos como configurar os volumes do Cloud Storage FUSE.

Opções de ativação

O driver FUSE CSI do Cloud Storage é compatível com opções de ativação para configurar como os buckets do Cloud Storage são ativados no sistema de arquivos local. Para conferir a lista completa de sinalizações de ativação compatíveis, consulte a documentação da CLI gcsfuse.

É possível especificar as sinalizações de ativação das seguintes maneiras:

  • No campo spec.mountOptions em um manifesto PersistentVolume, se você usar o provisionamento estático.
  • No campo spec.volumes[n].csi.volumeAttributes.mountOptions, se você usar volumes temporários de CSI.

Atributos de volume

O driver CSI do Cloud Storage FUSE não permite especificar diretamente o arquivo de configuração do Cloud Storage FUSE. É possível definir alguns dos campos no arquivo de configuração usando os atributos de volume a seguir. Os valores são convertidos nos campos do arquivo de configuração.

  • gcsfuseLoggingSeverity

    • Descrição: é a gravidade dos registros que você quer que o Cloud Storage FUSE gere, expressa como um tipo enumerado. Se você já estiver usando as opções de montagem debug_fuse, debug_fs ou debug_gcs, essa nova configuração será definida automaticamente como trace. Esse atributo de volume é traduzido para o campo do arquivo de configuração logging:severity.

    • Valores válidos (ordenados da menor gravidade para a mais alta):

      • trace
      • debug
      • info
      • warning
      • error

    • Valor padrão: info

  • fileCacheCapacity

    • Descrição: o tamanho máximo que o cache de arquivos pode usar. Se um valor diferente de zero for apresentado, esse atributo de volume permitirá o armazenamento em cache de arquivos no Cloud Storage FUSE. Esse atributo de volume é traduzido para o campo do arquivo de configuração file-cache:max-size-mb.

    • Valores válidos:

      • Quantidade, por exemplo: 500Mi, 10Gi.
      • "-1": para usar toda a capacidade disponível do volume do cache.
      • "0": o cache de arquivos está desativado.

    • Valor padrão: "0"

  • fileCacheForRangeRead

    • Descrição: se o download completo do objeto precisa ser feito de modo assíncrono e armazenado no diretório de cache do Cloud Storage FUSE quando a primeira leitura for feita de um deslocamento diferente de zero. Defina como "true" se você planeja executar várias leituras aleatórias ou leituras parciais. Esse atributo de volume é traduzido para o campo do arquivo de configuração file-cache:cache-file-for-range-read.

    • Valores válidos:

      • Valores booleanos no formato de string: "true", "false".

    • Valor padrão: "false".

  • metadataStatCacheCapacity

    • Descrição: o tamanho máximo que o cache de estatísticas pode usar. O cache de estatísticas é sempre mantido por completo na memória. Se você já estiver usando a opção de montagem stat-cache-capacity, o valor ainda será honrado e será convertido adequadamente para essa nova configuração. Esse atributo de volume é traduzido para o campo do arquivo de configuração metadata-cache:stat-cache-max-size-mb.

    • Valores válidos:

      • Quantidade, por exemplo: 500Mi, 1Gi.
      • "-1": para permitir que o cache de estatísticas use tanta memória quanto for necessário.
      • "0": o cache de estatísticas está desativado.
      • Use o valor padrão 32Mi se a carga de trabalho envolver até 20.000 arquivos. Se a carga de trabalho for maior que 20.000 arquivos, aumente o tamanho em valores de 10 Mb para cada 6.000 arquivos adicionais, uma média de aproximadamente 1.500 bytes por arquivo.

    • Valor padrão: 32Mi

  • metadataTypeCacheCapacity

    • Descrição: o tamanho máximo por diretório que o cache de tipo pode usar. O cache de tipos é sempre totalmente mantido na memória. Esse atributo de volume é traduzido para o campo do arquivo de configuração metadata-cache:type-cache-max-size-mb.

    • Valores válidos:

      • Quantidade, por exemplo: 500Mi, 1Gi.
      • "-1": para permitir que o cache de tipos use tanta memória quanto for necessário.
      • "0": o cache de tipos está desativado.
      • Use o valor padrão 4Mi se o número máximo de arquivos em um único diretório do bucket que você está ativando contiver 20.000 arquivos ou menos. Se o número máximo de arquivos em um único diretório ativado tiver mais de 20.000 arquivos, aumente o tamanho em 1 Mb para cada 5.000 arquivos, uma média de aproximadamente 200 bytes por arquivo.

    • Valor padrão: 4Mi

  • metadataCacheTtlSeconds

    • Descrição: define o time to live (TTL), em segundos, das entradas de metadados armazenadas em cache. Se você já estiver usando as opções de montagem stat-cache-ttl ou type-cache-ttl, os valores ainda serão honrados e serão convertidos adequadamente para essa nova configuração. Esse atributo de volume é traduzido para o campo do arquivo de configuração metadata-cache:ttl-secs.

    • Valores válidos:

      • Valores inteiros no formato de string, por exemplo: "600".
      • "-1": ignora uma expiração de TTL e disponibiliza o arquivo a partir do cache sempre que ele está disponível.
      • "0": garante que o arquivo mais atualizado seja lido. O uso de um valor de 0 emite uma chamada de metadados Get para garantir que a geração do objeto para o arquivo no cache corresponda ao que está armazenado no Cloud Storage.

    • Valor padrão: "60"

É possível especificar os atributos de volume das seguintes maneiras:

  • No campo spec.csi.volumeAttributes em um manifesto PersistentVolume, se você usar o provisionamento estático.
  • No campo spec.volumes[n].csi.volumeAttributes, se você usar volumes temporários de CSI.

Considerações

Use as seguintes considerações ao configurar ativações:

  • As flags a seguir não são permitidas: app-name, temp-dir, foreground, log-file, log-format, key-file, token-url e reuse-token-from-url.
  • O Cloud Storage FUSE não torna os diretórios implícitos visíveis por padrão. Para tornar esses diretórios visíveis, ative a sinalização de ativação implicit-dirs. Para saber mais, consulte Arquivos e diretórios na documentação do FUSE do Cloud Storage no GitHub.
  • Se você usa um Contexto de segurança para o pod ou contêiner, ou se a imagem do contêiner usa um usuário não raiz ou grupo, é necessário definir as flags de ativação uid e gid. Também é necessário usar as flags de montagem file-mode e dir-mode para definir as permissões do sistema de arquivos. Não é possível executar comandos chmod, chown ou chgrp em um sistema de arquivos Cloud Storage FUSE. Portanto, as flags de montagem uid, gid, file-mode e dir-mode são necessárias para fornecer acesso a um usuário ou grupo não raiz.
  • Se você só quiser ativar um diretório no bucket em vez de todo o bucket, passe o caminho relativo do diretório usando a sinalização only-dir=relative/path/to/the/bucket/root.
  • Para ajustar o comportamento de armazenamento em cache do Cloud Storage FUSE, configure os atributos de volume. Consulte a documentação Armazenamento em cache do Cloud Storage FUSE para mais detalhes.
  • Se o número de núcleos ou linhas de execução for maior que 100, mude max-conns-per-host para esse valor.
  • Se você precisar configurar as opções de ativação do kernel do Linux, poderá transmiti-las por meio da flag o. Por exemplo, se você não quiser permitir a execução direta de binários no sistema de arquivos montado, defina a flag o=noexec. Cada opção requer uma flag separada, por exemplo, o=noexec,o=noatime. Somente as seguintes opções são permitidas: exec, noexec, atime, noatime, sync, async e dirsync.
  • Se você precisar resolver problemas do Cloud Storage FUSE, defina as sinalizações debug_fuse, debug_fs e debug_gcs. Se qualquer uma das três opções for especificada, o atributo de volume gcsfuseLoggingSeverity será definido automaticamente como trace.
  • O driver CSI do Cloud Storage FUSE não permite modificar o campo cache-dir no arquivo de configuração do Cloud Storage FUSE. Use o atributo de volume fileCacheCapacity para ativar ou desativar o armazenamento em cache de arquivos. Para substituir o volume emptyDir padrão para armazenamento em cache de arquivos, configure um volume de cache personalizado para o contêiner de arquivo secundário.

Desativar o driver FUSE CSI do Cloud Storage

Não é possível desativar o driver FUSE CSI do Cloud Storage em clusters do Autopilot.

É possível desativar o driver FUSE CSI do Cloud Storage em um cluster Standard existente usando a Google Cloud CLI.

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=DISABLED

Substitua CLUSTER_NAME pelo nome do cluster.

Solução de problemas

Para resolver problemas ao usar o driver CSI do FUSE do Cloud Storage, consulte o Guia de solução de problemas na documentação do projeto do GitHub.

A seguir