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, as 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 maneira como os aplicativos em contêiner interagem 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 os clusters do GKE aos 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 armazenamento de objetos. Para saber mais sobre os papéis comuns e os exemplos de tarefas mencionados em Google Cloud content, 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 ativar 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 Google Cloud projetos diferentes ou no mesmo projeto.

Ativar o driver CSI do Cloud Storage FUSE

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

Autopilot

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 Standard. Para criar um cluster Standard com o driver CSI do Cloud Storage FUSE ativado, use o gcloud container clusters create comando:

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 gcloud container clusters update comando:

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 Federação de Identidade da Carga de Trabalho para GKE para que você possa definir permissões detalhadas 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, autentique usando a Federação de Identidade da Carga de Trabalho para GKE com o bucket do Cloud Storage que você quer ativar 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 ativá-la. Se você 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 atual.

   kubectl create namespace NAMESPACE
   

   Substitua NAMESPACE pelo nome do namespace do Kubernetes da ServiceAccount.

   Importante: a 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 Kubernetes ServiceAccount.

   kubectl create serviceaccount KSA_NAME \
       --namespace NAMESPACE
   

   Substitua KSA_NAME pelo nome da 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 buckets específicos

   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 a buckets

   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 de cluster do GKE anteriores a 1.33.3-gke.1226000, o driver CSI do Cloud Storage FUSE não oferece suporte a pods em execução na rede de 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 por hostNetwork ao usar o driver CSI do Cloud Storage FUSE para ativar 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 padrão do GKE 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 por hostNetwork usa para acessar o bucket do Cloud Storage. Para mais informações, consulte Autenticar no Cloud Storage FUSE.

Especifique o atributo de volume hostNetworkPodKSA: "true" na definição de pod ou PersistentVolume para permitir que os pods HostNetwork acessem 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.

Contêineres secundários gerenciados

Esta seção se aplica se o GKE injetar e gerenciar automaticamente o contêiner secundário do Cloud Storage FUSE nos seus 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"

Contêineres secundários particulares

Esta seção se aplica se você gerenciar manualmente o contêiner secundário do Cloud Storage FUSE nos seus pods ou usar uma imagem de contêiner secundário personalizada.

Verifique se a imagem do contêiner secundário é 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:

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

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:

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

A seguir

• Solução de problemas do Cloud Storage FUSE
• Saiba como ativar buckets do Cloud Storage especificando seus buckets em linha com a especificação do pod.
• Saiba como ativar buckets do Cloud Storage usando um recurso PersistentVolume.
• Saiba mais sobre como configurar aplicativos para usar a Federação de Identidade da Carga de Trabalho para GKE.
• Otimize automaticamente o desempenho com perfis do Cloud Storage FUSE.
• Otimize manualmente o Cloud Storage FUSE para desempenho.