Como usar o driver CSI do disco permanente do Compute Engine

Autopilot Standard

---

O Google Kubernetes Engine (GKE) fornece uma maneira simples de implantar e gerenciar automaticamente o Driver da interface de armazenamento do contêiner (CSI, na sigla em inglês) do disco permanente do Compute Engine nos clusters. O driver CSI do disco permanente do Compute Engine está sempre ativado nos clusters do Autopilot e não pode ser desativado ou editado. Em clusters padrão, é necessário ativar o driver CSI do disco permanente do Compute Engine.

A versão do driver CSI do disco permanente do Compute Engine está vinculada aos números da versão do GKE. Normalmente, a versão do driver CSI do disco permanente do Compute Engine é o mais recente disponível no momento em que a versão do GKE é lançada. Os drivers são atualizados automaticamente quando o cluster é atualizado para o patch do GKE mais recente.

Observação: como o driver CSI do disco permanente do Compute Engine e alguns dos outros componentes CSI associados são implantados como contêineres separados, eles incorrem no uso de recursos (memória, disco de inicialização e CPU da VM) nos nós do Kubernetes. Em geral, o uso de CPU da VM é de dezenas de milésimos. O uso da memória, por sua vez, é de dezenas de MB. O uso do disco de inicialização é incorrido principalmente pelos registros do driver CSI e outros contêineres do sistema na Implantação.

Benefícios

Usar o driver CSI do disco permanente do Compute Engine oferece os seguintes benefícios:

• Isso permite a implantação e o gerenciamento automáticos do driver de disco permanente sem ter que configurá-lo manualmente.
• É possível usar chaves de criptografia gerenciadas pelo cliente (CMEKs, na sigla em inglês). Essas chaves são usadas para criptografar as chaves que criptografam seus dados. Para saber mais sobre a CMEK no GKE, consulte Como usar CMEKs.
• Use snapshots de volume com o driver CSI de disco permanente do Compute Engine. Eles permitem criar uma cópia do seu volume em um momento específico. Use essa cópia para trazer um volume de volta a um estado anterior ou para provisionar um novo volume.
• É possível usar a clonagem de volume com o driver CSI do disco permanente do Compute Engine em clusters que executam o GKE versão 1.22 e mais recentes. A clonagem de volume permite criar uma cópia do seu volume em um local específico no momento, provisionado com todos os dados do volume de origem.
• Correções de bugs e atualizações de recursos são lançadas independentemente das versões secundárias do Kubernetes. Essa programação de lançamento geralmente resulta em uma cadência de lançamento mais rápida.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

• Ativar a API Google Kubernetes Engine.
Ativar a API Google Kubernetes Engine
• Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.
  Observação: para instalações atuais da CLI gcloud, defina as propriedades compute/region e compute/zone. Ao definir locais padrão, é possível evitar erros na CLI gcloud, como: One of [--zone, --region] must be supplied: Please specify location.

Requisitos

Para usar o driver CSI de disco permanente do Compute Engine, os clusters precisam usar as seguintes versões:

• Clusters Linux: GKE versão 1.14 ou posterior.
• Clusters do Windows: GKE versão 1.18 ou posterior.

Na versão 1.22 e mais recentes, a migração do CSI fica ativada. Os volumes atuais que usam o provedor gce-pd são migrados para se comunicar por drivers CSI. Nenhuma alteração é necessária para qualquer StorageClass. O provedor gce-pd continua não compatível com recursos como CMEK ou snapshots de volume. Use o provedor pd.csi.storage.gke.io no StorageClass para ativar esses recursos.

Para usar o driver CSI do disco permanente do Compute Engine com a federação de identidade da carga de trabalho do GKE, é necessário que os clusters padrão tenham as seguintes versões:

• Clusters Linux: GKE versão 1.16 ou posterior.
• Clusters do Windows: GKE versão 1.20.8-gke.900 ou posterior.

Observação: no Autopilot, o driver CSI do disco permanente do Compute Engine é ativado por padrão e não pode ser desativado ou editado. Para utilizar o driver, pule para Usar o driver CSI do disco permanente do Compute Engine para clusters do Linux.

Como ativar o driver CSI do disco permanente do Compute Engine em um novo cluster

Observação: o driver CSI do disco permanente do Compute Engine é ativado por padrão nos clusters recém-criados para as seguintes versões:

Clusters do Linux: GKE versão 1.18.10-gke.2100 ou posterior ou 1.19.3-gke.2100 ou posterior.

Clusters do Windows: GKE versão 1.22.6-gke.300 ou posterior ou 1.23.2-gke.300 ou posterior.

Para clusters do Autopilot, o driver CSI do disco permanente do Compute Engine é ativado por padrão e não pode ser desativado ou editado.

Para criar um cluster padrão com uma versão em que o driver CSI do disco permanente do Compute Engine não esteja ativado automaticamente, use a Google Cloud CLI ou o Console do Google Cloud.

Para ativar o driver na criação do cluster, conclua as seguintes etapas:

gcloud

gcloud container clusters create CLUSTER-NAME \
    --addons=GcePersistentDiskCsiDriver \
    --cluster-version=VERSION

Substitua:

• CLUSTER-NAME: o nome do cluster.
• VERSION: o número da versão do GKE. Selecione uma versão 1.14 ou superior para usar esse recurso.

Para ver a lista completa de sinalizações, consulte a documentação gcloud container clusters create.

Console

1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

   Acessar o Google Kubernetes Engine

2. Clique em Criar.

3. Na seção Padrão, clique em Configurar.

4. Configure o cluster como quiser.

5. No painel de navegação, em Cluster, clique em Recursos.

6. Marque a caixa de seleção Ativar driver de CSI do disco permanente do Compute Engine.

7. Clique em Criar.

Depois de ativar o driver CSI do disco permanente do Compute Engine, será possível usar o driver nos volumes do Kubernetes usando o nome do provisionador e do driver: pd.csi.storage.gke.io.

Como ativar o driver CSI do disco permanente do Compute Engine em um cluster existente

Para ativar o driver CSI do disco permanente do Compute Engine em clusters padrão, use a Google Cloud CLI ou o Console do Google Cloud.

Para ativar o driver em um cluster existente, conclua as etapas a seguir:

gcloud

gcloud container clusters update CLUSTER-NAME \
   --update-addons=GcePersistentDiskCsiDriver=ENABLED

substitua CLUSTER-NAME pelo nome do cluster atual.

Console

1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

   Acessar o Google Kubernetes Engine

2. Na lista de clusters, clique no nome do cluster que você quer modificar.

3. Em Recursos, ao lado do campo Driver CSI do disco permanente do Compute Engine, clique em Editar driver CSI do Compute Engine.

4. Marque a caixa de seleção Ativar driver de CSI do disco permanente do Compute Engine.

5. Clique em Save Changes.

Como desativar o driver CSI do disco permanente do Compute Engine

É possível desativar o driver CSI do disco permanente do Compute Engine para clusters padrão usando a Google Cloud CLI ou o console do Google Cloud.

Se você desativar o driver, os pods pertencentes a ele que utilizam PersistentVolumes não serão encerrados. Além disso, também não será possível iniciar os novos pods que tentarem usar esses PersistentVolumes.

Observação: como o tipo de volume gcePersistentDisk é migrado para o driver CSI de disco permanente do Compute Engine na versão 1.22 e posterior, se você desativar o recurso driver do CSI de disco permanente, o tipo de volume gcePersistentDisk também para de funcionar.

Aviso: há um problema conhecido no GKE 1.21 e anterior, se você estiver usando o driver de disco permanente na árvore e quiser excluir discos regionais. Um disco regional do Compute Engine pode vazar quando o recurso PersistentVolume relacionado é excluído. Esse problema pode ser detectado quando a chamada de API para excluir o disco regional falha e retorna um código de erro diferente de NotFound. Para mais informações, veja este problema no GitHub.

Para desativar o driver em um cluster Standard existente, siga estas etapas:

gcloud

gcloud container clusters update CLUSTER-NAME \
    --update-addons=GcePersistentDiskCsiDriver=DISABLED

substitua CLUSTER-NAME pelo nome do cluster atual.

Console

1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

   Acessar o Google Kubernetes Engine

2. Na lista de clusters, clique no nome do cluster que você quer modificar.

3. Em Recursos, ao lado do campo Driver CSI do disco permanente do Compute Engine, clique em Editar driver CSI do Compute Engine.

4. Desmarque a caixa de seleção Ativar driver de CSI do disco permanente do Compute Engine.

5. Clique em Save Changes.

Como usar o driver CSI do disco permanente do Compute Engine para clusters do Linux

As seções a seguir descrevem o processo típico de uso de um volume do Kubernetes compatível com um driver CSI no GKE. Essas seções são específicas para clusters que usam o Linux.

Criar um StorageClass

Depois que você ativa o driver CSI do disco permanente do Compute Engine, o GKE instala automaticamente os seguintes StorageClasses:

• standard-rwo, usando o disco permanente balanceado
• premium-rwo, usando o disco permanente SSD

Para clusters do Autopilot, o StorageClass padrão é standard-rwo, que usa o driver CSI de disco permanente do Compute Engine. Para clusters Standard, o StorageClass padrão usa o plug-in de volume gcePersistentDisk na árvore do Kubernetes.

Encontre o nome do StorageClasses instalado executando o seguinte comando:

kubectl get sc

Também é possível instalar um StorageClass diferente que usa o driver CSI de disco permanente do Compute Engine adicionando pd.csi.storage.gke.io no campo do provisionador.

Por exemplo, é possível criar um StorageClass usando o seguinte arquivo chamado pd-example-class.yaml:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: pd-example
provisioner: pd.csi.storage.gke.io
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
  type: pd-balanced

É possível especificar os seguintes tipos de disco permanente no parâmetro type:

• pd-balanced
• pd-ssd
• pd-standard
• pd-extreme (compatível com o GKE versão 1.26 e posterior)

Se você estiver usando pd-standard ou pd-extreme, consulte Tipos de máquina não compatíveis para ver outras restrições de uso.

Ao usar a opção pd-extreme, você também precisa adicionar o campo provisioned-iops-on-create ao seu manifesto. Esse campo precisa ser definido como o mesmo valor do valor de IOPS provisionado que você especificou ao criar o disco permanente.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: pd-extreme-example
provisioner: pd.csi.storage.gke.io
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
  type: pd-extreme
  provisioned-iops-on-create: '10000'

Depois de criar o arquivo pd-example-class.yaml, execute o seguinte comando:

kubectl create -f pd-example-class.yaml

Criar um PersistentVolumeClaim

É possível criar um PersistentVolumeClaim que faz referência ao StorageClass do driver CSI do disco permanente do Compute Engine.

O arquivo a seguir, chamado pvc-example.yaml, usa a classe de armazenamento pré-instalada standard-rwo:

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc
spec:
  accessModes:
  - ReadWriteOnce
  storageClassName: standard-rwo
  resources:
    requests:
      storage: 6Gi

Depois de criar o manifesto PersistentVolumeClaim, execute o seguinte comando:

kubectl create -f pvc-example.yaml

No StorageClass pré-instalado (standard-rwo), volumeBindingMode é definido como WaitForFirstConsumer. Quando volumeBindingMode for definido como WaitForFirstConsumer, o PersistentVolume não será provisionado até que um pod referenciando PersistentVolumeClaim seja programado. Se, no StorageClass, volumeBindingMode estiver definido como Immediate (ou se estiver omitido), um PersistentVolume baseado em disco permanente será provisionado depois que o PersistentVolumeClaim for criado.

Criar um pod que consuma o volume

Ao usar pods com PersistentVolumes, recomendamos usar um controlador de carga de trabalho (como uma implantação ou StatefulSet). Mesmo que você geralmente não use um pod independente, o exemplo a seguir usa um para simplificar.

O exemplo a seguir consome o volume que você criou na seção anterior:

apiVersion: v1
kind: Pod
metadata:
  name: web-server
spec:
  containers:
   - name: web-server
     image: nginx
     volumeMounts:
       - mountPath: /var/lib/www/html
         name: mypvc
  volumes:
   - name: mypvc
     persistentVolumeClaim:
       claimName: podpvc
       readOnly: false

Como usar o driver CSI do disco permanente do Compute Engine para clusters do Windows

As seções a seguir descrevem o processo típico de uso de um volume do Kubernetes compatível com um driver CSI no GKE. Essas seções são específicas para clusters que usam o Windows.

Certifique-se de que:

• A versão do cluster é 1.19.7-gke.2000, 1.20.2-gke.2000 ou posterior.
• As versões de nó são 1.18.12-gke.1203, 1.19.6-gke.800 ou posterior.

Criar um StorageClass

A criação de um StorageClass para Windows é muito semelhante ao Linux. Esteja ciente de que o StorageClass instalado por padrão não funcionará no Windows, porque o tipo de sistema de arquivos é diferente. O driver CSI do disco permanente do Compute Engine para Windows requer NTFS como o tipo de sistema de arquivos.

Por exemplo, é possível criar um StorageClass usando o seguinte arquivo chamado pd- windows-class.yaml. Adicione csi.storage.k8s.io/fstype: NTFS à lista de parâmetros:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: pd-sc-windows
provisioner: pd.csi.storage.gke.io
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
  type: pd-balanced
  csi.storage.k8s.io/fstype: NTFS

Criar um PersistentVolumeClaim

Depois de criar um StorageClass para Windows, agora é possível criar um PersistentVolumeClaim que faça referência a esse StorageClass:

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc-windows
spec:
  accessModes:
  - ReadWriteOnce
  storageClassName: pd-sc-windows
  resources:
    requests:
      storage: 6Gi

Criar um pod que consuma o volume

O exemplo a seguir consome o volume que você criou na tarefa anterior:

apiVersion: v1
kind: Pod
metadata:
  name: web-server
spec:
  nodeSelector:
    kubernetes.io/os: windows
  containers:
    - name: iis-server
      image: mcr.microsoft.com/windows/servercore/iis
      ports:
      - containerPort: 80
      volumeMounts:
      - mountPath: /var/lib/www/html
        name: mypvc
  volumes:
    - name: mypvc
      persistentVolumeClaim:
        claimName: podpvc-windows
        readOnly: false

Como usar o driver CSI do disco permanente do Compute Engine com tipos de sistema de arquivos não padrão

O tipo padrão de sistema de arquivos para discos permanentes do Compute Engine no GKE é ext4. Também é possível usar o tipo de armazenamento xfs, desde que a imagem de nó seja compatível. Consulte Suporte do driver de armazenamento para ver uma lista de drivers compatíveis por imagem de nó.

No exemplo a seguir, mostramos como usar xfs como o tipo de sistema de arquivos padrão em vez de ext4 com o driver CSI do disco permanente do Compute Engine.

Criar um StorageClass

1. Salve o seguinte manifesto como um arquivo chamado pd-xfs-class.yaml:

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: xfs-class
   provisioner: pd.csi.storage.gke.io
   parameters:
     type: pd-balanced
     csi.storage.k8s.io/fstype: xfs
   volumeBindingMode: WaitForFirstConsumer
   

2. Aplique o manifesto:

   kubectl apply -f pd-xfs-class.yaml
   

Criar um PersistentVolumeClaim

1. Salve o seguinte manifesto como pd-xfs-pvc.yaml:

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: xfs-pvc
   spec:
     storageClassName: xfs-class
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         storage: 10Gi
   

2. Aplique o manifesto:

   kubectl apply -f pd-xfs-pvc.yaml
   

Criar um pod que consuma o volume

1. Salve o seguinte manifesto como pd-xfs-pod.yaml:

   apiVersion: v1
   kind: Pod
   metadata:
     name: pd-xfs-pod
   spec:
     containers:
     - name: cloud-sdk
       image: google/cloud-sdk:slim
       args: ["sleep","3600"]
       volumeMounts:
       - mountPath: /xfs
         name: xfs-volume
     volumes:
     - name: xfs-volume
       persistentVolumeClaim:
         claimName: xfs-pvc
   

2. Aplique o manifesto:

   kubectl apply -f pd-xfs-pod.yaml
   

Verificar se o volume foi ativado corretamente

1. Abra uma sessão do shell no pod:

   kubectl exec -it pd-xfs-pod -- /bin/bash
   

2. Procure partições xfs:

   df -aTh --type=xfs
   

   A saída será semelhante a:

   Filesystem     Type  Size  Used Avail Use% Mounted on
   /dev/sdb       xfs    30G   63M   30G   1% /xfs
   

Visualizar registros para o driver CSI de disco permanente do Compute Engine

Use o Cloud Logging para ver eventos relacionados ao driver CSI do disco permanente do Compute Engine. Os registros podem ajudar você a resolver problemas.

Para mais informações sobre o Cloud Logging, consulte Como visualizar seus registros do GKE.

Para ver os registros do driver CSI do disco permanente do Compute Engine, siga estas etapas:

1. Acesse a página do Cloud Logging no console do Google Cloud.

   Acessar o Cloud Logging

2. Execute a seguinte consulta:

    resource.type="k8s_container"
    resource.labels.project_id="PROJECT_ID"
    resource.labels.location="LOCATION"
    resource.labels.cluster_name="CLUSTER_NAME"
    resource.labels.namespace_name="kube-system"
    resource.labels.container_name="gce-pd-driver"
   

   Substitua:

   • PROJECT_ID: o nome do projeto.
   • LOCATION: a região ou zona do Compute Engine do cluster.
   • CLUSTER_NAME: o nome do cluster.

Problemas conhecidos

Tipos de máquina não compatíveis

Se você estiver usando a família de máquinas da série C3, o tipo de disco permanente pd-standard não será compatível.

Se você tentar executar um pod em uma máquina e ele usar um tipo de disco permanente incompatível, será exibida uma mensagem de aviso como a seguinte emitida no pod:

AttachVolume.Attach failed for volume "pvc-d7397693-5097-4a70-9df0-b10204611053" : rpc error: code = Internal desc = unknown Attach error: failed when waiting for zonal op: operation operation-1681408439910-5f93b68c8803d-6606e4ed-b96be2e7 failed (UNSUPPORTED_OPERATION): [pd-standard] features are not compatible for creating instance.

Se o cluster tiver vários pools de nós com diferentes famílias de máquinas, será possível usar taints de nó e afinidade de nó para limitar onde as cargas de trabalho pode ser agendado. Por exemplo, use essa abordagem para restringir a execução de uma carga de trabalho usando pd-standard em uma família de máquinas não compatível.

Se você estiver usando o tipo de disco permanente pd-extreme, precisará garantir que o disco esteja conectado a uma instância de VM com um formato de máquina adequado. Para saber mais, consulte Suporte ao formato da máquina.

A seguir

• Saiba como usar a expansão de volume.
• Saiba como usar snapshots de volume.
• Saiba como usar a clonagem de volume.
• Leia mais sobre o driver no GitHub (em inglês).