Configurar o contêiner secundário do driver CSI do Cloud Storage FUSE para o GKE

Este guia mostra como configurar recursos para o contêiner secundário do driver CSI do Cloud Storage FUSE, incluindo a configuração de uma imagem particular, um buffer de gravação personalizado e um volume de cache de leitura personalizado. Normalmente, não é necessário mudar essas configurações.

O driver CSI do Cloud Storage FUSE usa um contêiner secundário personalizável para montar e acessar buckets do Cloud Storage de maneira eficiente. Ao configurar o sidecar, é possível ajustar o desempenho do aplicativo e o uso de recursos, o que pode resultar em acesso mais rápido aos dados, tempos de processamento mais rápidos e, possivelmente, menor consumo geral de recursos para o aplicativo.

Este guia é destinado a desenvolvedores, administradores e arquitetos que querem otimizar o desempenho, a segurança e a eficiência dos aplicativos que interagem com o GKE.

Antes de ler esta página, confira se você conhece os conceitos básicos do Cloud Storage, do Kubernetes e da contêinerização.

Como o contêiner sidecar funciona

O driver CSI do Cloud Storage FUSE usa um contêiner secundário para ativar buckets do Cloud Storage e torná-los acessíveis como sistemas de arquivos locais para aplicativos do Kubernetes. Esse contêiner de arquivo secundário, chamado gke-gcsfuse-sidecar, é executado junto com o contêiner de carga de trabalho no mesmo pod. Quando o driver detecta a anotação gke-gcsfuse/volumes: "true" em uma especificação de pod, ele injetará automaticamente o contêiner de arquivo secundário. Essa abordagem de contêiner secundário ajuda a garantir a segurança e gerenciar recursos de maneira eficaz.

O contêiner secundário processa as complexidades da ativação dos buckets do Cloud Storage e fornece acesso ao sistema de arquivos para os aplicativos sem exigir que você gerencie o tempo de execução do Cloud Storage FUSE diretamente. É possível configurar limites de recursos para o contêiner de arquivo secundário usando anotações como gke-gcsfuse/cpu-limit e gke-gcsfuse/memory-limit. O modelo de contêiner secundário também garante que a instância do Cloud Storage FUSE esteja vinculada ao ciclo de vida da carga de trabalho, evitando que ela consuma recursos desnecessariamente. Isso significa que o contêiner secundário será encerrado automaticamente quando os contêineres de carga de trabalho forem encerrados, especialmente em cargas de trabalho de job ou pods com um RestartPolicy de Never.

Compatibilidade com o Istio

O contêiner secundário do driver CSI do Cloud Storage FUSE e o Istio podem coexistir e ser executados simultaneamente no seu pod. O proxy sidecar do Istio gerencia o tráfego de rede, enquanto o sidecar do CSI otimiza o acesso ao armazenamento, permitindo que seus aplicativos interajam de maneira eficiente com o Google Cloud Storage com melhor desempenho e capacidade de observação.

Configurar um buffer de gravação personalizado

O Cloud Storage FUSE prepara gravações em um diretório local e faz upload para o Cloud Storage em operações close ou fsync.

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. Isso é útil se você precisar gravar arquivos maiores que 10 GiB nos clusters do Autopilot.

É possível especificar qualquer tipo de armazenamento compatível com o driver CSI do Cloud Storage FUSE para armazenamento em cache de arquivos, como um SSD local, armazenamento baseado em Persistent Disk e disco RAM (memória). O GKE vai usar o volume especificado para armazenamento em buffer de gravação de arquivo. Para saber mais sobre essas opções, consulte Selecionar o armazenamento para fazer backup do cache de arquivos.

Para usar o volume de buffer personalizado, especifique um fsGroup diferente de zero.

O exemplo a seguir mostra como usar um PersistentVolumeClaim 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

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 armazenar em cache os arquivos em operações de leitura. É 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 cache de arquivos. Isso é útil se você precisar armazenar em cache arquivos maiores que 10 GiB em clusters do Autopilot. Para usar o volume de cache personalizado, especifique um fsGroup diferente de zero.

O exemplo a seguir mostra como usar um PersistentVolumeClaim predefinido como o volume de cache:

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 predefinido do PersistentVolumeClaim.

Configurar uma imagem particular para o contêiner sidecar

Nesta seção, descrevemos como usar a imagem do contêiner secundário quando você a hospeda em um registro de contêiner particular. Esse cenário será aplicável se você precisar usar nós particulares para fins de segurança.

Para configurar e consumir a imagem do contêiner secundário particular, siga estas etapas:

  1. Consulte esta tabela de compatibilidade do GKE para encontrar uma imagem de contêiner secundário 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 de imagem. O GKE usará a imagem do contêiner secundário 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 secundário particular.

Configurar recursos do contêiner de arquivo secundário

Por padrão, o contêiner gke-gcsfuse-sidecar é configurado com as seguintes solicitações e limites de recursos para clusters Standard e Autopilot:

Solicitações:

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

Limites (GKE versão 1.29.1-gke.1670000 e mais recente):

  • CPU ilimitada
  • memória ilimitada
  • armazenamento temporário ilimitado

Limites (antes da versão 1.29.1-gke.1670000 do GKE):

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

Por padrão, o contêiner gke-gcsfuse-metadata-prefetch é configurado com as seguintes solicitações e limites de recursos para clusters Standard e Autopilot:

Solicitações:

  • 10m CPU
  • 10 MiB de memória
  • Armazenamento temporário de 10 MiB

Limites:

  • 50m CPU
  • 250 MiB de memória
  • armazenamento temporário ilimitado

Nos clusters Standard e do Autopilot, é possível substituir os valores padrão. A maneira como o GKE processa os recursos de contêiner depende do modo de operação do cluster:

  • Clusters padrão: se um dos valores de solicitação ou limite for definido e outro não, os limites e solicitações de recursos dos pods serão definidos como iguais. Se as solicitações e os limites forem definidos, os pods usarão as solicitações e os limites de recursos exatos especificados. Se você não definir nenhum valor, os recursos padrão (descritos acima) serão aplicados diretamente.
  • Clusters do Autopilot: se uma das solicitações ou limites for definida e outra não, os limites e solicitações de recursos dos pods serão definidos como iguais. Consulte Como definir limites de recursos no Autopilot para entender como as substituições de recursos e os valores padrão definidos afetam o comportamento do pod.

Para substituir os valores padrão do contêiner gke-gcsfuse-sidecar, é 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:

Para substituir os valores padrão do contêiner gke-gcsfuse-metadata-prefetch (a partir da versão 1.32.3-gke.1717000 do GKE e posteriores), é possível especificar a anotação gke-gcsfuse/[metadata-prefetch-cpu-limit|metadata-prefetch-memory-limit|metadata-prefetch-ephemeral-storage-limit|metadata-prefetch-cpu-request|metadata-prefetch-memory-request|metadata-prefetch-ephemeral-storage-request], conforme mostrado no exemplo a seguir:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"

    # gke-gcsfuse-sidecar overrides
    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

    # gke-gcsfuse-metadata-prefetch overrides
    gke-gcsfuse/metadata-prefetch-cpu-limit: "10"
    gke-gcsfuse/metadata-prefetch-memory-limit: 10Gi
    gke-gcsfuse/metadata-prefetch-ephemeral-storage-limit: 1Ti
    gke-gcsfuse/metadata-prefetch-cpu-request: 500m
    gke-gcsfuse/metadata-prefetch-memory-request: 1Gi
    gke-gcsfuse/metadata-prefetch-ephemeral-storage-request: 50Gi

É possível usar o valor "0" para cancelar a definição de limites ou solicitações de recursos, mas observe que o contêiner gke-gcsfuse-sidecar já tem todos os limites (cpu-limit, memory-limit e ephemeral-storage-limit) cancelados, e o contêiner gke-gcsfuse-metadata-prefetch já tem ephemeral-storage-limit cancelado. Portanto, definir esses limites como "0" em um cluster com a versão 1.32.3-gke.1717000 ou mais recente do GKE não teria efeito.

Por exemplo, definir gke-gcsfuse/metadata-prefetch-memory-limit: "0" indica que você quer que o limite de memória do contêiner gke-gcsfuse-metadata-prefetch não seja definido. Isso é útil quando não é possível decidir a quantidade de recursos que o recurso de pré-busca de metadados precisa para as cargas de trabalho, e você quer permitir que a pré-busca de metadados consuma todos os recursos disponíveis em um nó.

Configurar o detalhamento da geração de registros

Por padrão, o contêiner gke-gcsfuse-sidecar gera registros nos níveis info e error. No entanto, para depuração ou análise mais detalhada, talvez seja necessário ajustar o nível de detalhe do registro. Esta seção descreve como aumentar ou diminuir o nível de geração de registros.

É possível usar opções de montagem para configurar o nível de detalhe da geração de registros ou usar a capacidade do driver CSI de traduzir valores de atributo de volume nas configurações necessárias do gcsfuse.

No manifesto do pod de destino, inclua as seguintes configurações:

      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        gcsfuseLoggingSeverity:  LOGGING_SEVERITY

Para usar as opções de montagem, inclua a seguinte configuração no manifesto do pod de destino:

  mountOptions: "logging:severity:LOGGING_SEVERITY"

Substitua:

  • BUCKET_NAME: seu nome do bucket do Cloud Storage
  • LOGGING_SEVERITY: um dos seguintes valores, com base nos seus requisitos:
    • trace
    • debug
    • info
    • warning
    • error

Depois que o pod é implantado, o driver CSI inicia o gcsfuse com o nível de registro recém-configurado.

Use o filtro a seguir para verificar se a gravidade do registro está sendo aplicada:

resource.labels.container_name="gke-gcsfuse-sidecar"
resource.type="k8s_container"
resource.labels.pod_name="POD_NAME"
"severity:"

A seguir