Configurar o driver CSI do Cloud Storage FUSE para GKE

Nesta página, descrevemos como configurar e se preparar para usar o driver CSI do Cloud Storage FUSE para o GKE.

Para usar o driver CSI do Cloud Storage FUSE, siga estas etapas:

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.

Google Cloud

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 padrão 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 FUSE CSI do Cloud Storage 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. Assim, é possível 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 o 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 o GKE no pool de nós depois de ativar a federação de identidade da carga de trabalho para o 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 para o cluster.

  3. Crie um namespace para usar com 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.

  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 específico ao bucket

    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 do objeto 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 do objeto 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, em versões mais recentes do GKE, é possível configurar a autenticação segura para pods com hostNetwork ativado ao usar o driver CSI do Cloud Storage FUSE para montar buckets do Cloud Storage. O suporte à rede do host está disponível apenas em clusters padrão do GKE.

Verifique se o cluster do GKE atende aos seguintes requisitos:

Especifique o atributo de volume hostNetworkPodKSA: "true" na definição do 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.

Sidecars 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 efêmero 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ê gerenciar manualmente o contêiner secundário do Cloud Storage FUSE nos seus pods ou usar uma imagem secundária personalizada.

Verifique se a imagem do 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 efêmero 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 padrão do GKE.

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 padrão do GKE.

A seguir