Configure o contentor auxiliar do controlador CSI FUSE do Cloud Storage para o GKE

Este guia mostra como configurar recursos para o contentor auxiliar do controlador CSI do FUSE do Cloud Storage, incluindo a configuração de uma imagem privada, um buffer de escrita personalizado e um volume de cache de leitura personalizado. Normalmente, não precisa de alterar estas definições.

O controlador CSI FUSE do Cloud Storage usa um contentor sidecar personalizável para montar e aceder de forma eficiente a contentores do Cloud Storage. Ao configurar o sidecar, pode otimizar o desempenho da aplicação e a utilização de recursos, o que pode levar a um acesso mais rápido aos dados, tempos de processamento mais rápidos e, potencialmente, um consumo de recursos geral mais baixo para a sua aplicação.

Este guia destina-se a programadores, administradores e arquitetos que querem otimizar o desempenho, a segurança e a eficiência das respetivas aplicações que interagem com o GKE.

Antes de ler esta página, certifique-se de que conhece os conceitos básicos do Cloud Storage, do Kubernetes e da contentorização.

Como funciona o contentor auxiliar

O controlador CSI FUSE do Cloud Storage usa um contentor sidecar para montar contentores do Cloud Storage de modo a torná-los acessíveis como sistemas de ficheiros locais para aplicações Kubernetes. Este contentor auxiliar, denominado gke-gcsfuse-sidecar, é executado juntamente com o contentor de carga de trabalho no mesmo pod. Quando o controlador deteta a anotação gke-gcsfuse/volumes: "true" numa especificação de pod, injeta automaticamente o contentor sidecar. Esta abordagem de contentor auxiliar ajuda a garantir a segurança e a gerir os recursos de forma eficaz.

O contentor sidecar processa as complexidades da montagem dos contentores do Cloud Storage e fornece acesso ao sistema de ficheiros às aplicações sem que tenha de gerir diretamente o tempo de execução do FUSE do Cloud Storage. Pode configurar limites de recursos para o contentor sidecar através de anotações como gke-gcsfuse/cpu-limit e gke-gcsfuse/memory-limit. O modelo de contentor auxiliar também garante que a instância do FUSE do Cloud Storage está associada ao ciclo de vida da carga de trabalho, o que impede o consumo desnecessário de recursos. Isto significa que o contentor auxiliar termina automaticamente quando os contentores de carga de trabalho são fechados, especialmente em cargas de trabalho de tarefas ou pods com um RestartPolicy de Never.

Compatibilidade com o Istio

O contentor auxiliar do controlador CSI FUSE do Cloud Storage e o Istio podem coexistir e ser executados em simultâneo no seu pod. O proxy sidecar do Istio gere o tráfego de rede, enquanto o sidecar do CSI otimiza o acesso ao armazenamento, o que permite que as suas aplicações interajam de forma eficiente com o Google Cloud Storage com um desempenho e uma observabilidade melhorados.

Configure um buffer de gravação personalizado

O Cloud Storage FUSE organiza as escritas num diretório local e, em seguida, carrega-as para o Cloud Storage em operações close ou fsync.

Esta secção descreve como configurar um volume de buffer personalizado para o armazenamento em buffer de escrita do FUSE do Cloud Storage. Este cenário pode aplicar-se se precisar de substituir o volume emptyDir predefinido do FUSE do Cloud Storage para preparar os ficheiros em operações de escrita. Isto é útil se precisar de escrever ficheiros com mais de 10 GiB em clusters do Autopilot.

Pode especificar qualquer tipo de armazenamento suportado pelo controlador CSI FUSE do Cloud Storage para o armazenamento em cache de ficheiros, como um SSD local, armazenamento baseado em disco persistente e disco RAM (memória). O GKE usa o volume especificado para o armazenamento em buffer de escrita de ficheiros. Para saber mais sobre estas opções, consulte o artigo Selecione o armazenamento para fazer uma cópia de segurança da cache de ficheiros.

Para usar o volume de buffer personalizado, tem de especificar um valor fsGroup diferente de zero.

O exemplo seguinte mostra como pode 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 o seguinte:

  • FS_GROUP: o ID fsGroup.
  • BUFFER_VOLUME_PVC: o nome do PVC predefinido.

Configure um volume de cache de leitura personalizado

Esta secção descreve como configurar um volume de cache personalizado para a colocação em cache de leitura do FUSE do Cloud Storage.

Este cenário pode aplicar-se se precisar de substituir o volume emptyDir predefinido para o FUSE do Cloud Storage para colocar os ficheiros em cache nas operações de leitura. Pode especificar qualquer tipo de armazenamento suportado pelo GKE, como um PersistentVolumeClaim, e o GKE usa o volume especificado para o armazenamento em cache de ficheiros. Isto é útil se precisar de colocar em cache ficheiros com mais de 10 GiB em clusters do Autopilot. Para usar o volume de cache personalizado, tem de especificar um valor fsGroup diferente de zero.

O exemplo seguinte mostra como pode 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 o seguinte:

  • FS_GROUP: o ID de fsGroup.
  • CACHE_VOLUME_PVC: o nome PersistentVolumeClaim predefinido.

Configure uma imagem privada para o contentor sidecar

Esta secção descreve como usar a imagem do contentor sidecar se a estiver a alojar num registo de contentores privado. Este cenário pode aplicar-se se precisar de usar nós privados para fins de segurança.

Para configurar e consumir a imagem do contentor sidecar privado, siga estes passos:

  1. Consulte esta tabela de compatibilidade do GKE para encontrar uma imagem de contentor sidecar público compatível.
  2. Extraia-o para o seu ambiente local e envie-o para o seu registo de contentores privado.

  3. No manifesto, especifique um contentor denominado gke-gcsfuse-sidecar com apenas o campo de imagem. O GKE usa a imagem do contentor auxiliar especificada para se preparar para a injeção do contentor auxiliar.

    Vejamos 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 o seguinte:

    • PRIVATE_REGISTRY: o seu registo de contentores privado. Por exemplo, us-central1-docker.pkg.dev/my-project/my-registry.
    • PRIVATE_IMAGE_TAG: a etiqueta de imagem do contentor sidecar privado. Por exemplo, v1.17.1-gke.1.

Configure os recursos do contentor auxiliar

Por predefinição, o contentor gke-gcsfuse-sidecar está configurado com os seguintes pedidos de recursos e limites para clusters Standard e Autopilot:

Pedidos:

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

Limites (versão 1.29.1-gke.1670000 do GKE e posteriores):

  • 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
  • 5 GiB de armazenamento temporário

Por predefinição, o contentor gke-gcsfuse-metadata-prefetch está configurado com os seguintes pedidos de recursos e limites para clusters Standard e Autopilot:

Pedidos:

  • CPU de 10 min
  • 10 MiB de memória
  • 10 MiB de armazenamento temporário

Limites:

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

Nos clusters padrão e do Autopilot, pode substituir os valores predefinidos. A forma como o GKE processa os recursos de contentores depende do modo de funcionamento do cluster:

  • Clusters padrão: se um dos pedidos ou limites for definido e outro não, os limites e os pedidos de recursos dos pods são definidos como iguais. Se o pedido e os limites estiverem definidos, os pods usam os pedidos e os limites de recursos exatos que especificar. Se não definir nenhum valor, os recursos predefinidos (descritos acima) são aplicados diretamente.
  • Clusters do Autopilot: se um dos pedidos ou limites for definido e outro não for definido, os limites e os pedidos de recursos dos pods são definidos como iguais. Consulte o artigo Definir limites de recursos no Autopilot para compreender como as substituições de recursos e os valores de recursos predefinidos afetam o comportamento do pod.

Para substituir os valores predefinidos do contentor gke-gcsfuse-sidecar, pode especificar opcionalmente a anotação gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request], conforme mostrado no exemplo seguinte:

Para substituir os valores predefinidos do contentor gke-gcsfuse-metadata-prefetch (a partir da versão 1.32.3-gke.1717000 do GKE e posterior), pode especificar opcionalmente 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 seguinte:

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

Pode usar o valor "0" para anular a definição de quaisquer limites ou pedidos de recursos, mas tenha em atenção que o contentor gke-gcsfuse-sidecar já tem todos os limites (cpu-limit, memory-limit e ephemeral-storage-limit) anulados, e o contentor gke-gcsfuse-metadata-prefetch já tem ephemeral-storage-limit anulado. Por isso, definir estes limites como "0" num cluster com a versão 1.32.3-gke.1717000 ou posterior do GKE não teria qualquer efeito.

Por exemplo, a definição gke-gcsfuse/metadata-prefetch-memory-limit: "0" indica que quer que o limite de memória do contentor gke-gcsfuse-metadata-prefetch não esteja definido. Isto é útil quando não consegue decidir a quantidade de recursos que a funcionalidade de pré-obtenção de metadados precisa para as suas cargas de trabalho e quer permitir que a pré-obtenção de metadados consuma todos os recursos disponíveis num nó.

Configure a verbosidade do registo

Por predefinição, o contentor gke-gcsfuse-sidecar gera registos nos níveis info e error. No entanto, para a depuração ou uma análise mais detalhada, pode ter de ajustar o nível de detalhe do registo. Esta secção descreve como aumentar ou diminuir o nível de registo.

Pode usar opções de montagem para configurar a verbosidade do registo ou usar a capacidade do controlador CSI para traduzir os valores do atributo de volume nas definições de configuração do gcsfuse necessárias.

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 o seguinte:

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

Após a implementação do pod, o controlador CSI inicia o gcsfuse com o nível de registo configurado recentemente.

Pode usar o seguinte filtro para verificar se a gravidade do registo está aplicada:

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

Resolver problemas

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

O que se segue?