Automatizar o ajuste de desempenho com perfis do Cloud Storage FUSE

Neste documento, descrevemos como ajustar automaticamente a performance do driver CSI do Cloud Storage FUSE e acelerar o acesso a dados das cargas de trabalho de IA/ML usando os perfis do Cloud Storage FUSE no Google Kubernetes Engine (GKE).

Os perfis do Cloud Storage FUSE automatizam o processo essencial de ajuste de desempenho. Em vez de ajustar as configurações manualmente, aplique perfis predefinidos que configuram o driver CSI para você. Para seus aplicativos de IA/ML, usar esses perfis pode levar a tempos de treinamento e inferência mais rápidos com redução do overhead operacional.

Este documento é destinado a desenvolvedores de aplicativos e engenheiros de machine learning (ML) que querem melhorar o desempenho dos aplicativos sem ter muita experiência em ajuste de armazenamento. Para saber mais sobre papéis comuns, consulte Funções e tarefas de usuário comuns do GKE.

Antes de ler este documento, familiarize-se com os conceitos básicos do Cloud Storage, do Kubernetes e do driver CSI do Cloud Storage FUSE. Além disso, confira os requisitos para usar o driver CSI do Cloud Storage FUSE.

Benefícios de usar perfis do Cloud Storage FUSE

Para automatizar o ajuste de performance de cargas de trabalho de IA/ML, os perfis do Cloud Storage FUSE usam configurações predefinidas do Cloud Storage FUSE e aplicam outras configurações específicas do GKE. Essas configurações são baseadas nas práticas recomendadas de ajuste de desempenho do Cloud Storage FUSE. Usar perfis predefinidos oferece os seguintes benefícios:

  • Ajuste de desempenho simplificado: use perfis predefinidos do Cloud Storage FUSE para aplicar as configurações otimizadas a cargas de trabalho comuns de IA/ML, como treinamento, disponibilização e checkpoint.
  • Otimização dinâmica e com reconhecimento de recursos: o uso dos perfis do Cloud Storage FUSE permite que o driver CSI ajuste automaticamente os tamanhos do cache e selecione a mídia de cache ideal, como RAM ou SSD local, com base nas características do bucket ou subdiretório, como tamanho, contagem de objetos e tipo de local, limites de sidecar e recursos disponíveis do nó.
  • Performance de leitura acelerada: quando você usa o perfil gcsfusecsi-serving, o GKE ativa automaticamente o Rapid Cache para melhorar a performance de leitura das suas cargas de trabalho de serviço.
  • Insights de ajuste de performance: você recebe insights sobre as decisões de ajuste automatizado com registros estruturados que detalham os indicadores de entrada do seu ambiente e as configurações resultantes aplicadas pelo driver. Para mais informações, consulte Conferir insights de recomendações.

À medida que as práticas recomendadas do Cloud Storage FUSE evoluem, os perfis são atualizados ao longo do tempo com novas versões do GKE.

Limitações

Requisitos

Custos

Além dos custos padrão do GKE e do Cloud Storage associados ao driver CSI do Cloud Storage FUSE, o uso de perfis do Cloud Storage FUSE gera os seguintes custos.

Custos de verificação de bucket

Os perfis do Cloud Storage FUSE fazem uma verificação em segundo plano do seu bucket ou subdiretório. Por padrão, essa verificação ocorre a cada sete dias. A verificação de buckets gera custos de operação de classe A do Cloud Storage para listar objetos.

Custos do Rapid Cache

O perfil gcsfusecsi-serving ativa automaticamente o Rapid Cache, que é cobrado de acordo com os preços do Rapid Cache do Cloud Storage. Para evitar cobranças por instâncias de cache quando elas não forem mais necessárias, consulte Controles de custos.

Antes de começar

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

  • Ative a API Cloud Storage e a API Google Kubernetes Engine.
    • Ativar APIs
  • 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 o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.
  • Escolha uma Cloud de Confiance by S3NS região adequada às suas necessidades. Embora recomendemos criar o cluster do GKE e o bucket do Cloud Storage na mesma região para otimizar o desempenho e o custo, isso é obrigatório ao usar o perfil gcsfusecsi-serving ou planejar ativar o Rapid Cache.
  • Verifique se você tem um bucket do Cloud Storage com o conjunto de dados, o modelo ou os checkpoints da sua carga de trabalho de IA/ML. Se você precisar criar um bucket, consulte Criar um bucket.

Selecione um perfil de performance

Escolha um perfil que melhor corresponda à sua carga de trabalho. Cada perfil corresponde a uma StorageClass pré-instalada no cluster. Para definições detalhadas dos perfis do Cloud Storage FUSE, consulte a referência de configuração do StorageClass correspondente.

Perfil Nome do StorageClass Otimizado para Principais recursos
Treinamento gcsfusecsi-training Leituras de alta capacidade de processamento Otimiza a latência de dados para GPUs e TPUs durante o treinamento em grandes conjuntos de dados.
Como estabelecer pontos de verificação gcsfusecsi-checkpointing Gravações de alta capacidade de processamento Minimiza o tempo necessário para salvar checkpoints grandes, reduzindo as pausas no treinamento.
Disponibilização gcsfusecsi-serving Acesso e armazenamento em cache de dados Ativa o Rapid Cache por padrão para acelerar as operações de leitura.

Para verificar as StorageClasses instaladas no cluster, execute o seguinte comando:

kubectl get sc -l gke-gcsfuse/profile=true

configure as permissões do IAM

Conceda as permissões do agente de serviço do GKE para analisar seu bucket do Cloud Storage e gerenciar o cache rápido.

Substitua os seguintes marcadores ao executar os comandos nesta seção:

  • GCS_PROJECT: o ID do projeto que contém seu bucket do Cloud Storage.
  • PROJECT_NUMBER: o número do projeto do seu projeto de cluster do GKE.
  • BUCKET_NAME: o nome do bucket do Cloud Storage.

Escolha uma das opções a seguir que corresponda ao seu perfil e às suas necessidades de uso.

Opção A: função personalizada (recomendada)

Essa opção é obrigatória para o perfil de veiculação ou se o Rapid Cache for usado. Se você usa o perfil de veiculação ou planeja ativar manualmente o cache rápido para outros perfis, é necessário conceder permissões para gerenciar esse cache.

  1. Crie um papel personalizado do IAM que permita verificar objetos e criar caches do Rapid Cache:

    gcloud iam roles create gke.gcsfuse.profileUser \
  --project=GCS_PROJECT \
  --title="GKE GCSFuse Profile User" \
  --description="Allows scanning Cloud Storage buckets for objects, retrieving bucket metadata, and creating caches." \
  --permissions="storage.objects.list,storage.buckets.get,storage.anywhereCaches.create,storage.anywhereCaches.get,storage.anywhereCaches.list,storage.anywhereCaches.update"

  2. Vincule o papel personalizado ao agente de serviço do GKE para seu bucket específico:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
  --project=GCS_PROJECT \
  --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com" \
  --role="projects/GCS_PROJECT/roles/gke.gcsfuse.profileUser"

Opção B: função padrão para perfis de treinamento e checkpoint

Se você estiver usando apenas os perfis de treinamento ou checkpoint e não planeja usar o Rapid Cache, execute o seguinte comando:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --project=GCS_PROJECT \
    --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/storage.legacyBucketReader"

Implantar uma carga de trabalho com um perfil do Cloud Storage FUSE

Siga estas etapas para implantar uma carga de trabalho com um perfil do Cloud Storage FUSE.

  1. Crie um manifesto do PersistentVolume (PV) que faça referência a uma das StorageClasses de perfil do Cloud Storage FUSE:

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  mountOptions:
    - only-dir=BUCKET_DIR_PATH # Optional
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

    Substitua:

    • STORAGECLASS_NAME: o nome do StorageClass do perfil que você quer usar. O valor precisa ser gcsfusecsi-training, gcsfusecsi-checkpointing ou gcsfusecsi-serving.
    • BUCKET_DIR_PATH: (opcional) o caminho no bucket do Cloud Storage, se você estiver montando um diretório específico. Se especificado, o GKE vai verificar esse caminho para otimização. Se omitido, o GKE vai verificar todo o bucket.
    • BUCKET_NAME: o nome do bucket do Cloud Storage que você especificou ao configurar o acesso aos buckets do Cloud Storage.

  2. Crie um PersistentVolumeClaim (PVC) que solicite a mesma StorageClass do seu PV:

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
  namespace: NAMESPACE
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: my-pv
  storageClassName: STORAGECLASS_NAME

    Substitua:

    • NAMESPACE: o namespace em que você quer implantar o pod.
    • STORAGECLASS_NAME: o nome do StorageClass listado no PV.

  3. Use o PVC na implantação:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  namespace: NAMESPACE
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: my-container
        image: busybox
        volumeMounts:
        - name: my-gcs-volume
          mountPath: "/data"
      volumes:
      - name: my-gcs-volume
        persistentVolumeClaim:
          claimName: my-pvc

    Substitua:

Depois de implantado, o driver CSI calcula automaticamente os tamanhos ideais de cache e as opções de montagem com base nos recursos do nó, como GPUs ou TPUs, memória, SSD local, o tamanho do bucket ou subdiretório e os limites de recursos do sidecar.

Verificar a otimização automática

Os processos em segundo plano do GKE analisam automaticamente seu bucket e sincronizam o Rapid Cache (se estiver em uso).

Verificar o status da verificação do bucket e do cache

Depois de criar a PV, siga estas etapas para verificar o status da verificação do bucket e do cache. Não é necessário esperar que o pod seja implantado.

  1. Verifique o status do PV:

    kubectl describe pv my-pv

  2. Na saída, verifique se o evento ScanOperationSucceeded aparece. A resposta será semelhante a:

    Normal  ScanOperationSucceeded  gke-gcsfuse-scanner  Bucket scan completed successfully for bucket "my-bucket", directory "my-dir": "526893" objects, "57690897566" bytes

  3. Se você usa o perfil gcsfusecsi-serving, verifique se o evento AnywhereCacheSyncSucceeded aparece depois que a camada de cache estiver pronta. O resultado será o seguinte:

    Normal  AnywhereCacheSyncSucceeded  gke-gcsfuse-scanner  Anywhere Cache sync succeeded for PV "my-pv": us-central1-c:running

  4. Verifique se as anotações do PV foram atualizadas com o resultado da verificação:

    gke-gcsfuse/bucket-scan-status: completed
gke-gcsfuse/bucket-scan-num-objects: 526893
gke-gcsfuse/bucket-scan-total-size-bytes: 57690897566
gke-gcsfuse/bucket-scan-location-type: multi-region
gke-gcsfuse/bucket-scan-hns-enabled: true
gke-gcsfuse/bucket-scan-last-updated-time: 2025-12-10T22:48:38Z

Verificar o status do pod

Depois de implantar o pod, execute o seguinte comando:

kubectl get pods -n NAMESPACE

Substitua NAMESPACE pelo namespace em que você implantou os pods.

Seus pods agora devem estar no status RUNNING, com as práticas recomendadas de performance aplicadas automaticamente. Se os pods mostrarem o status SchedulingGated, isso indica que o GKE ainda está verificando seu bucket ou subdiretório. Os pods permanecem nesse estado até que o controlador do CSI conclua a verificação e atualize o PV.

Para entender as decisões específicas de ajuste registradas pelo driver depois que o pod é iniciado, consulte Ver insights de recomendação.

Se você encontrar erros, consulte a seção Solução de problemas.

Referência de configuração do StorageClass

Esta seção fornece os manifestos do StorageClass para os perfis pré-instalados do Cloud Storage FUSE e uma referência detalhada para as opções de montagem e os parâmetros usados pelos perfis. Essas configurações permitem que o driver gcsfuse.csi.storage.gke.io automatize o ajuste de desempenho e o gerenciamento de recursos para suas cargas de trabalho de IA/ML.

Treinamento

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-training
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-training
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Como estabelecer pontos de verificação

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-checkpointing
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-checkpointing
  - read_ahead_kb=1024
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Disponibilização

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-serving
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-serving
  - read_ahead_kb=131072
  - file-cache:max-size-mb:0
  - read:enable-buffered-read:true
  - read:global-max-blocks:80
parameters:
  anywhereCacheZones: "*"
  anywhereCacheAdmissionPolicy: "admit-on-first-miss"
  anywhereCacheTTL: "1h"
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Os perfis usam as seguintes opções de montagem e parâmetros para o driver gcsfuse.csi.storage.gke.io:

  • mountOptions:
    • profile: aplica um conjunto predefinido de otimizações do Cloud Storage FUSE adaptadas para cargas de trabalho de IA/ML. Os valores válidos para os perfis pré-instalados são aiml-training, aiml-checkpointing e aiml-serving.
    • read_ahead_kb: especifica o tamanho do buffer de leitura antecipada em kilobytes (KB). Essa opção permite que o Cloud Storage FUSE faça pré-busca de dados do Cloud Storage, o que pode melhorar o desempenho de leitura para padrões de acesso sequenciais.
    • file-cache:max-size-mb: para o perfil de veiculação, especifica o tamanho máximo em mebibytes (MiB) do cache de arquivos. Em cargas de trabalho de serviço, em que os modelos geralmente são carregados na memória da GPU ou TPU apenas uma vez, esse parâmetro é definido como 0 para desativar o cache de arquivos local do Cloud Storage FUSE, o que ajuda a evitar E/S de disco redundante e economiza armazenamento local.
    • read:enable-buffered-read: para o perfil de serviço, permite que o Cloud Storage FUSE gerencie os próprios buffers internos, o que ajuda a reduzir o número de pequenas e caras chamadas de sistema entre o aplicativo e o kernel.
    • read:global-max-blocks: para o perfil de veiculação, limita o número total de blocos de memória simultâneos usados para leituras em buffer. Essa opção ajuda a evitar que o processo do FUSE consuma toda a RAM disponível ao atender várias solicitações.
  • parameters:
    • skipCSIBucketAccessCheck: quando definido como "true", faz com que o driver CSI pule a verificação inicial de acesso ao bucket. Esse parâmetro ajuda a reduzir as chamadas ao Serviço de token de segurança para evitar possíveis problemas de cota.
    • gcsfuseMetadataPrefetchOnMount: quando definido como "true", direciona o driver CSI para iniciar o prefetching de metadados de objetos do Cloud Storage para o cache local assim que o volume é montado. Esse parâmetro pode acelerar o primeiro acesso aos arquivos.
    • fuseFileCacheMediumPriority: define a ordem de prioridade para a mídia de armazenamento usada pelo cache de arquivos do Cloud Storage FUSE. Ele permite especificar preferências diferentes para nós com GPUs, TPUs ou de uso geral. As opções de mídia incluem ram e lssd (SSD local, se disponível e ativado).
    • fuseMemoryAllocatableFactor: especifica em formato de string uma fração que limita a memória máxima que os caches do Cloud Storage FUSE podem consumir, em relação à memória total alocável do nó e ao limite de memória do sidecar.
    • fuseEphemeralStorageAllocatableFactor: limita o uso do cache do Cloud Storage FUSE do armazenamento temporário no nó (como SSD local para cache de arquivos), em relação ao armazenamento temporário alocável do nó ou ao armazenamento temporário do sidecar limitado para armazenamento em cache.
    • bucketScanResyncPeriod: define o intervalo de tempo em que o PV é novamente verificado para detectar mudanças feitas no bucket do Cloud Storage.
    • bucketScanTimeout: a duração máxima permitida para uma única operação de verificação de bucket. Se a verificação exceder esse tempo, resultados parciais poderão ser usados.
    • anywhereCacheZones: especifica uma lista separada por vírgulas de zonas compatíveis em que os caches do Rapid Cache são criados, por exemplo, "us-central1-a,us-central1-b". Para usar todas as zonas disponíveis para o cluster, use "*" como valor. Definir como "none" ou deixar sem especificação desativa o Rapid Cache.
    • anywhereCacheTTL: o tempo de vida (TTL) dos dados armazenados no cache rápido, medido desde o último acesso. Se você mudar esse valor, as instâncias atuais do Rapid Cache serão atualizadas com o novo TTL.
    • anywhereCacheAdmissionPolicy: determina quando admitir dados no cache rápido após uma falha de leitura (quando os dados solicitados não são encontrados no cache). As opções incluem "admit-on-first-miss", que aceita dados na primeira falha de leitura, ou "admit-on-second-miss", que aceita dados apenas em uma segunda falha de leitura para o mesmo objeto. Se você mudar esse valor, as instâncias atuais do Rapid Cache serão atualizadas com a nova política.

Opcional: ajuste as configurações de perfil

É possível personalizar configurações específicas em um perfil e ainda aproveitar a configuração básica dele. Use as opções a seguir para ajustar um perfil sem criar um novo StorageClass.

Substituir opções e parâmetros de montagem

Para modificar comportamentos específicos, adicione opções de montagem ao campo spec.mountOptions ou parâmetros de CSI ao campo spec.csi.volumeAttributes no PV. O GKE aplica suas configurações manuais sobre os padrões do perfil.

O exemplo a seguir mostra como substituir a opção de montagem read_ahead_kb e desativa o parâmetro gcsfuseMetadataPrefetchOnMount no perfil de serviço.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: gcsfusecsi-serving
  mountOptions:
  - read_ahead_kb=2048 # Overrides the profile's default.
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: my-gcs-bucket
    volumeAttributes:
      gcsfuseMetadataPrefetchOnMount: "false" # Overrides the profile's default.

Os casos de uso comuns incluem:

  • Para ativar o Rapid Cache em um perfil de treinamento, adicione o parâmetro anywhereCacheZones diretamente à especificação de PV.
  • Para ajustar comportamentos específicos do FUSE do Cloud Storage, como aumentar o tamanho do read_ahead_kb, para atender aos requisitos exclusivos de uma carga de trabalho específica.

Ao configurar manualmente os tamanhos de cache, considere o seguinte:

  • Especificar um tamanho de cache manual substitui o dimensionamento dinâmico automático apenas para esse componente específico. O dimensionamento dinâmico continua para todos os outros componentes da melhor maneira possível dentro do orçamento de recursos restante.
  • Definir uma opção metadata-cache ou file-cache, como metadata-cache:stat-cache-max-size-mb, não desativa o cálculo automático para outros tipos de cache.
  • Se você especificar file-cache:max-size-mb manualmente, também precisará configurar um volume de cache de leitura personalizado. Isso ajuda a garantir que um meio de armazenamento com capacidade suficiente seja definido explicitamente para o tamanho do cache personalizado.

Ignorar a verificação de buckets com anotações

Você pode ignorar o processo automático de verificação de intervalos fornecendo suas próprias métricas de contagem e tamanho de objetos usando anotações. O driver CSI usa esses valores para calcular configurações de performance ideais sem verificar o bucket.

O exemplo a seguir mostra como adicionar a anotação gke-gcsfuse/bucket-scan-status: "override" ao PV, junto com as anotações de métrica específicas.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
  annotations:
    gke-gcsfuse/bucket-scan-status: "override"
    gke-gcsfuse/bucket-scan-num-objects: 19238
    gke-gcsfuse/bucket-scan-total-size-bytes: 94837465
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

Os casos de uso comuns incluem:

  • Se você já conhece o tamanho e a contagem de objetos do bucket, principalmente para cargas de trabalho de inferência em que os dados raramente mudam, é possível ignorar o tempo de verificação na inicialização.
  • Se a API Cloud Storage estiver temporariamente indisponível, essas anotações poderão ajudar você a manter o desempenho enquanto os serviços subjacentes são corrigidos.

Solução de problemas

Use as informações a seguir para monitorar o status dos perfis do Cloud Storage FUSE e resolver problemas comuns encontrados durante a verificação de buckets e a sincronização de cache.

Parâmetro de configuração inválido (InvalidArgument)

As tarefas de otimização em segundo plano não foram iniciadas porque um ou mais parâmetros fornecidos no manifesto eram inválidos.

Sintoma

A PV mostra um evento ScanOperationStartError ou AnywhereCacheSyncError com uma mensagem que contém rpc error: code = InvalidArgument. Por exemplo:

  • Bucket scan timeout configuration error: rpc error: code = InvalidArgument desc = invalid duration format for "INVALID_DURATION".
  • Anywhere Cache sync failed for PV "PV_NAME": rpc error: code = InvalidArgument desc = failed to get anywhere cache "CACHE_NAME" ... invalid anywhere cache "CACHE_NAME" provided.

Causa

Um ou mais parâmetros no campo spec.csi.volumeAttributes das suas PVs estão formatados incorretamente ou contêm valores que o sistema não consegue analisar.

Resolução

Corrija os valores de parâmetro inválidos no manifesto do PV e reimplante o PV. Verifique se todos os valores de duração (como bucketScanTimeout) usam o formato correto (por exemplo, 2m ou 10m) e se todas as configurações específicas do perfil correspondem aos valores válidos aceitos.

Permissão negada ao verificar o bucket do Cloud Storage

O GKE não consegue acessar o bucket do Cloud Storage especificado para realizar a análise de desempenho necessária.

Sintoma

A PV mostra um evento ScanOperationStartError com uma mensagem Error 403: Forbidden indicando que o autor da chamada não tem acesso storage.buckets.get.

Causa

O agente de serviço do GKE não tem as permissões necessárias do IAM ou o nome do bucket está incorreto.

Resolução

  • Verifique se o nome do bucket no campo volumeHandle da PV está correto e se o bucket existe.
  • Verifique se as permissões do agente de serviço do GKE foram concedidas à identidade service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com para o bucket específico. Para mais informações, consulte Configurar permissões do IAM.

Incompatibilidade de local do Rapid Cache

Não foi possível criar o cache do Rapid Cache porque a zona solicitada não é compatível com o local do bucket.

Sintoma

A PV mostra um evento AnywhereCacheSyncWarning com a mensagem: Invalid zone. Rapid Cache isn't available in the requested zone.

Causa

Os caches do Rapid Cache precisam ser criados em zonas que residem no local regional do bucket. Esse erro geralmente ocorre quando o cluster do GKE e o bucket do Cloud Storage estão em regiões diferentes.

Resolução

Mova o bucket do Cloud Storage para uma região que corresponda ao local do cluster do GKE e reimplante o PV.

A verificação do bucket expirou

A análise do bucket do Cloud Storage levou mais tempo do que o tempo limite configurado, resultando em resultados de otimização parciais.

Sintoma

A visualização de página mostra um evento ScanOperationTimedOut. A PV é anotada com resultados parciais para a contagem de objetos e o tamanho total.

Causa

O bucket contém um número excepcionalmente grande de objetos (normalmente vários milhões) que não podem ser totalmente listados dentro do tempo limite padrão de dois minutos.

Resolução

  • Defina um valor maior para o campo bucketScanTimeout na seção spec.csi.volumeAttributes do PV. Por exemplo, 10m.
  • Se o tamanho do bucket for estático, ignore a verificação fornecendo manualmente a contagem e o tamanho do objeto.

Cache de metadados limitado pelo orçamento de memória

O driver limitou o tamanho do cache de metadados para se ajustar aos recursos disponíveis do nó, o que pode reduzir a performance.

Sintoma

Os registros contêm uma mensagem informando que o tamanho do cache de estatísticas de metadados necessário foi limitado ao orçamento de memória disponível do Cloud Storage FUSE.

Causa

O cache de metadados para o número de objetos no bucket excede a memória alocada para o sidecar do Cloud Storage FUSE ou a memória disponível do nó.

Resolução

  • Use a opção de montagem only-dir para limitar o volume a um subdiretório menor com menos objetos.
  • Aumente o limite de memória do contêiner sidecar do Cloud Storage FUSE.
    • Se os limites de sidecar já forem suficientes, use um tipo de nó com mais memória alocável.

Cache de arquivos desativado devido a limites de recursos

O GKE desativou o cache de arquivos local porque não foi possível encontrar um meio de armazenamento adequado com espaço suficiente.

Sintoma

Os registros mostram o aviso: No suitable file cache medium found or requirement exceeded limits for all options.

Causa

O tamanho calculado do cache de arquivos excede a RAM disponível do nó e o armazenamento disponível do SSD local.

Resolução

  • Use a opção de montagem only-dir para limitar o volume a um subdiretório menor com menos objetos.
  • Aumente os limites de recursos do sidecar do Cloud Storage FUSE.
  • Use um tipo de nó com mais memória ou ative os SSDs locais no pool de nós.

Monitorar o status usando eventos do PersistentVolume

O GKE registra eventos e erros de configuração importantes no PV. Para verificar esses eventos, execute o seguinte comando:

kubectl describe pv PV_NAME

Depois que a verificação do bucket for concluída, você vai ver um evento ScanOperationSucceeded. Se você usar o perfil gcsfusecsi-serving, vai ver um evento AnywhereCacheSyncSucceeded depois que a camada de cache estiver operacional.

Monitorar o status usando registros de driver CSI

O driver CSI do Cloud Storage FUSE registra decisões de configuração detalhadas e insights de desempenho. Para conferir esses registros no Cloud Logging, use a seguinte consulta:

resource.type="k8s_container"
resource.labels.pod_name=~"gcsfusecsi-node-.*"

Ver insights de recomendação

Para entender os indicadores de entrada e as decisões específicas tomadas pela lógica de ajuste automático, pesquise nos registros do driver CSI a string GCSFuseCSIRecommendation. O payload JSON resultante fornece métricas detalhadas, incluindo o seguinte:

  • inputSignals: a contagem de objetos do bucket, o tamanho total dos dados e os recursos de nó disponíveis (RAM e armazenamento efêmero).
  • decision: os tamanhos finais calculados do cache e o meio de armazenamento selecionado (ram ou lssd).
{
  "insertId": "INSERT_ID",
  "jsonPayload": {
    "decision": {
      "fileCacheBytes": 300000000,
      "fileCacheMedium": "lssd",
      "metadataStatCacheBytes": 4500,
    },
    "target": {
      "nodeName": "NODE_NAME",
      "pvName": "PV_NAME",
      "podName": "POD_NAME"
    },
    "message": "GCSFuseCSIRecommendation: Recommended cache configs for PV PV_NAME and Pod POD_NAME: FileCache: 287MiB (lssd) | MetadataStatCache: 1MiB | Expand for full details",
    "inputSignals": {
      "requiredFileCacheBytes": 300000000,
      "fuseBudgetMemoryBytes": 187904819,
      "sidecarLimitMemoryBytes": 268435456,
      "nodeType": "gpu",
      "bucketTotalObjects": 3,
      "nodeAllocatableMemoryBytes": 191291998208,
      "bucketTotalDataSizeBytes": 300000000,
      "bucketLocationType": "multi-region",
      "bucketHNSEnabled": true,
      "sidecarLimitEphemeralStorageBytes": 0,
      "requiredMetadataStatCacheBytes": 4500,
      "nodeAllocatableEphemeralStorageBytes": 1317908854882,
      "nodeHasEphemeralStorageLSSD": true,
      "fuseBudgetEphemeralStorageBytes": 1120222526649
    }
  },
  ...
}

Limpar

Para evitar cobranças na sua conta do Cloud de Confiance by S3NS pelos recursos criados neste guia, siga estas etapas:

  1. Exclua a implantação:

    kubectl delete deployment my-deployment -n NAMESPACE

    Substitua NAMESPACE pelo namespace do Kubernetes em que você criou o Deployment.

  2. Exclua o PersistentVolumeClaim:

    kubectl delete pvc my-pvc -n NAMESPACE

    Substitua NAMESPACE pelo namespace do Kubernetes em que você criou a PVC.

  3. Exclua o PersistentVolume:

    kubectl delete pv my-pv

  4. Se você usou o perfil gcsfusecsi-serving ou ativou manualmente o Rapid Cache, siga as instruções para desativar um cache e evitar cobranças por instâncias de cache.

A seguir