Configurar o driver CSI do Cloud Storage FUSE para GKE

Autopilot Standard

Neste documento, mostramos como configurar o driver CSI do Cloud Storage FUSE para acessar buckets do Cloud Storage no Google Kubernetes Engine (GKE).

Com o driver CSI do Cloud Storage FUSE, suas cargas de trabalho do GKE podem acessar buckets do Cloud Storage como um sistema de arquivos local. O driver CSI integra o Cloud Storage ao GKE e simplifica a interação dos aplicativos conteinerizados com grandes conjuntos de dados armazenados em buckets. O driver CSI fornece uma interface padrão para o armazenamento do GKE. Neste documento, você prepara seu ambiente e conecta seus clusters do GKE a buckets do Cloud Storage usando o driver CSI do Cloud Storage FUSE.

Este documento é destinado a desenvolvedores, administradores e especialistas em armazenamento que integram cargas de trabalho do GKE ao repositório de objetos. Para saber mais sobre papéis comuns e exemplos de tarefas que mencionamos no conteúdo do Google Cloud , consulte Funções e tarefas comuns do usuário do GKE.

Criar o bucket do Cloud Storage

Se ainda não tiver feito isso, crie seus buckets do Cloud Storage. Você vai montar esses buckets como volumes no cluster do GKE. Para melhorar o desempenho, defina o Tipo de local como Região e selecione uma região que corresponda ao cluster do GKE.

Dica: os buckets do Cloud Storage e os clusters do GKE podem estar em projetos diferentes Google Cloud ou no mesmo projeto.

Ativar o driver CSI do Cloud Storage FUSE

Siga estas etapas, dependendo se você está usando clusters do GKE Autopilot ou Standard. Recomendamos que você use um cluster do Autopilot para ter uma experiência totalmente gerenciada do Kubernetes. Para escolher o modo mais adequado para suas cargas de trabalho, consulte Escolher um modo de operação do GKE.

Piloto automático

O driver CSI do Cloud Storage FUSE é ativado por padrão para clusters do Autopilot. Você pode pular para Configurar o acesso a buckets do Cloud Storage.

Padrão

Se o cluster Standard tiver o driver CSI do Cloud Storage FUSE ativado, pule para Configurar o acesso a buckets do Cloud Storage.

O driver CSI do Cloud Storage FUSE não é ativado por padrão em clusters padrão. Para criar um cluster Standard com o driver CSI do Cloud Storage FUSE ativado, use o comando gcloud container clusters create:

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 ou zona do Compute Engine do 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

Para verificar se o driver CSI do Cloud Storage FUSE está ativado no cluster, execute o seguinte comando:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --format="value(addonsConfig.gcsFuseCsiDriverConfig.enabled)"

Configurar o acesso a buckets do Cloud Storage

O driver CSI do Cloud Storage FUSE usa a Federação de Identidade da Carga de Trabalho para GKE (em inglês) para que você possa definir permissões refinadas sobre como os pods do GKE podem acessar dados armazenados no Cloud Storage.

Para tornar os buckets do Cloud Storage acessíveis pelo cluster do GKE, faça a autenticação usando a Federação de Identidade da Carga de Trabalho para GKE com o bucket do Cloud Storage que você quer montar na especificação do pod:

1. Se você não tiver a federação de identidade da carga de trabalho para GKE ativada, siga estas etapas para ativar. Se quiser usar um pool de nós atual, ative manualmente a Federação de Identidade da Carga de Trabalho para GKE no pool de nós depois de ativar a Federação de Identidade da Carga de Trabalho para GKE no cluster.

2. 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 ou zona do Compute Engine do cluster.

3. 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 pelo nome do namespace do Kubernetes para a conta de serviço do Kubernetes.

   Importante: sua carga de trabalho precisa ser executada no mesmo namespace.

4. 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 pelo nome da sua ServiceAccount do Kubernetes.

5. Conceda um dos papéis do IAM para o Cloud Storage à conta de serviço do Kubernetes. Siga estas etapas, dependendo se você está concedendo à conta de serviço do Kubernetes acesso a um bucket específico do Cloud Storage ou acesso global a todos os buckets do projeto.

   Acesso a um bucket específico

   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 de objetos do Storage (roles/storage.objectUser).

   Acesso global ao bucket

   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 de objetos do Storage (roles/storage.objectUser).

Configurar o acesso para pods com rede de host

Para versões do cluster do GKE anteriores a 1.33.3-gke.1226000, o driver CSI do Cloud Storage FUSE não é compatível com pods em execução na rede do host (hostNetwork: true) devido a restrições da Federação de Identidade da Carga de Trabalho para GKE. No entanto, para versões mais recentes do GKE, é possível configurar a autenticação segura para pods ativados com hostNetwork ao usar o driver CSI do Cloud Storage FUSE para montar buckets do Cloud Storage. O suporte à rede de host está disponível apenas em clusters padrão do GKE.

Verifique se o cluster do GKE atende aos seguintes requisitos:

• O plano de controle e os pools de nós no cluster do GKE Standard precisam ter a versão 1.33.3-gke.1226000 ou mais recente.
• Ative a Identidade da carga de trabalho no cluster.
• Conceda as permissões do IAM necessárias à conta de serviço do Kubernetes que o pod ativado para hostNetwork usa para acessar seu bucket do Cloud Storage. Para mais informações, consulte Autenticar no Cloud Storage FUSE.

Especifique o atributo de volume hostNetworkPodKSA: "true" na definição do pod ou do PersistentVolume para que os pods do HostNetwork acessem os volumes do Cloud Storage. A configuração exata varia de acordo com a forma como você gerencia o contêiner secundário do Cloud Storage FUSE.

Sidecars gerenciados

Esta seção se aplica se o GKE injetar e gerenciar automaticamente o contêiner secundário do Cloud Storage FUSE nos pods. Essa opção é a configuração padrão e recomendada para o driver CSI do Cloud Storage FUSE.

Volume temporário

O manifesto de pod a seguir configura um volume temporário para um pod HostNetwork acessar um bucket do Cloud Storage.

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: ns1
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  serviceAccountName: test-ksa-ns1
  hostNetwork: true
  containers:
  - image: busybox
    name: busybox
    command:
      - sleep
      - "3600"
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: test-bucket
        hostNetworkPodKSA: "true"

Volume permanente

O manifesto de PV a seguir configura um PV para um pod HostNetwork acessar um bucket do Cloud Storage.

apiVersion: v1
kind: PersistentVolume
metadata:
name: gcp-cloud-storage-csi-pv
spec:
accessModes:
- ReadWriteMany
capacity:
  storage: 5Gi
persistentVolumeReclaimPolicy: Retain
# storageClassName does not need to refer to an existing StorageClass object.
storageClassName: test-storage-class
mountOptions:
  - uid=1001
  - gid=3003
csi:
  driver: gcsfuse.csi.storage.gke.io
  volumeHandle: test-wi-host-network-2
  volumeAttributes:
    hostNetworkPodKSA: "true"

Sidecars particulares

Esta seção se aplica se você gerencia manualmente o contêiner secundário do Cloud Storage FUSE nos pods ou usa uma imagem secundária personalizada.

Verifique se a imagem sidecar é baseada na versão v1.17.2 ou mais recente do driver CSI do Cloud Storage FUSE.

Volume temporário

O manifesto de pod a seguir configura um volume temporário para um pod HostNetwork acessar um bucket do Cloud Storage.

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: ns1
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  serviceAccountName: test-ksa-ns1
  hostNetwork: true
  containers:
  - image: busybox
    name: busybox
    command:
      - sleep
      - "3600"
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: test-bucket
        hostNetworkPodKSA: "true"
        identityProvider: "https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME"

No campo identityProvider, substitua o seguinte:

• PROJECT_ID: o ID do projeto Google Cloud .
• LOCATION: o local do cluster.
• CLUSTER_NAME: o nome do cluster do GKE Standard.

Volume permanente

O manifesto de PV a seguir configura um PV para um pod HostNetwork acessar um bucket do Cloud Storage.

apiVersion: v1
kind: PersistentVolume
metadata:
name: gcp-cloud-storage-csi-pv
spec:
accessModes:
- ReadWriteMany
capacity:
  storage: 5Gi
persistentVolumeReclaimPolicy: Retain
# storageClassName does not need to refer to an existing StorageClass object.
storageClassName: test-storage-class
mountOptions:
  - uid=1001
  - gid=3003
csi:
  driver: gcsfuse.csi.storage.gke.io
  volumeHandle: test-wi-host-network-2
  volumeAttributes:
    hostNetworkPodKSA: "true"
    identityProvider: "https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME"

No campo identityProvider, substitua o seguinte:

• PROJECT_ID: o ID do projeto Google Cloud .
• LOCATION: o local do cluster.
• CLUSTER_NAME: o nome do cluster do GKE Standard.

A seguir

• Resolver problemas do Cloud Storage FUSE
• Saiba como montar buckets do Cloud Storage especificando os buckets de acordo com a especificação do pod.
• Aprenda a montar buckets do Cloud Storage usando um recurso PersistentVolume.
• Saiba como configurar aplicativos para usar a Federação de Identidade da Carga de Trabalho para GKE.
• Otimize o desempenho automaticamente com os perfis do Cloud Storage FUSE.
• Otimizar manualmente o desempenho do Cloud Storage FUSE.