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 CLI do Google Cloud para essa tarefa, instale e inicialize a gcloud CLI. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.
  Observação: em instalações prévias da gcloud CLI, defina a propriedade compute/region. Se você usa principalmente clusters zonais, defina compute/zone. Ao definir um local padrão, é possível evitar erros na gcloud CLI como: One of [--zone, --region] must be supplied: Please specify location. Talvez seja necessário especificar o local em determinados comandos se o local do cluster for diferente do padrão definido.

Ativar o driver CSI do disco permanente do Compute Engine

Para ativar o driver CSI de disco permanente do Compute Engine em clusters padrão, use a Google Cloud CLI ou o console 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 do Google Kubernetes Engine no Google Cloud console.

   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 Salvar alterações.

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.

Desativar o driver CSI de 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 Google Cloud .

Se você desativar o driver, os pods que atualmente usam PersistentVolumes pertencentes ao driver 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 do Google Kubernetes Engine no Google Cloud console.

   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 Salvar alterações.

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
# Recommended setting. Delays the binding and provisioning of a PersistentVolume until a Pod that uses the
# PersistentVolumeClaim is created and scheduled on a node.
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:
       # The path in the container where the volume will be mounted.
       - mountPath: /var/lib/www/html
         # The name of the volume that is being defined in the "volumes" section.
         name: mypvc
  volumes:
   - name: mypvc
     persistentVolumeClaim:
       # References the PersistentVolumeClaim created earlier.
       claimName: podpvc
       readOnly: false

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:
  # Node selector to ensure the Pod runs on a Windows node.
  nodeSelector:
    kubernetes.io/os: windows
  containers:
    - name: iis-server
      # The container image to use.
      image: mcr.microsoft.com/windows/servercore/iis
      ports:
      - containerPort: 80
      volumeMounts:
      # The path in the container where the volume will be mounted.
      - mountPath: /var/lib/www/html
        name: mypvc
  volumes:
    - name: mypvc
      persistentVolumeClaim:
        # References the PersistentVolumeClaim created earlier.
        claimName: podpvc-windows
        readOnly: false

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:
     # The type of Compute Engine persistent disk to provision.
     type: pd-balanced
     # Specify "xfs" as the filesystem type.
     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:
     # References the StorageClass created earlier.
     storageClassName: xfs-class
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         # The amount of storage requested.
         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
       # Keep the container running for 1 hour.
       args: ["sleep","3600"]
       volumeMounts:
       # The path in the container where the volume will be mounted.
       - mountPath: /xfs
         name: xfs-volume
     # Define the volumes available to the containers in the Pod.
     volumes:
     - name: xfs-volume
       persistentVolumeClaim:
         # References the PersistentVolumeClaim created earlier.
         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 Cloud Logging no console Google Cloud .

   Acessar o Cloud Logging

2. Para filtrar as entradas de registro e mostrar apenas as relacionadas ao driver CSI em execução no seu namespace, execute a seguinte consulta do Cloud Logging:

    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.
• Saiba como criar discos permanentes regionais.
• Leia mais sobre o driver no GitHub (em inglês).