Como usar discos permanentes preexistentes como PersistentVolumes

Autopilot Standard

Nesta página, explicamos como criar um PersistentVolume usando discos permanentes atuais preenchidos com dados e como usar o PersistentVolume em um pod.

Visão geral

Há dois cenários comuns que usam um disco permanente preexistente.

• Criar manualmente de um PersistentVolumeClaim e um PersistentVolume, vinculando-os e referindo-se ao PersistentVolumeClaim em uma especificação de pod.
• Usar um StatefulSet para gerar automaticamente PersistentVolumeClaims vinculados a PersistentVolumes gerados manualmente correspondentes a uma série de discos permanentes preexistentes.

Os exemplos nesta página usam discos permanentes do Compute Engine.

Se ext4 for o tipo de sistema de arquivos padrão, será possível usar um disco permanente preexistente com o sistema de arquivos xfs, desde que a imagem de nó seja compatível. Para usar um disco xfs, mude spec.csi.fsType para xfs no manifesto do PersistentVolume.

O Windows não é compatível com o tipo de sistema de arquivos ext4. Use o sistema de arquivos NTFS para pools de nós do Windows Server. Para usar um disco NTFS, mude spec.csi.fsType para NTFS no manifesto do PersistentVolume.

Observação: se o tipo de sistema de arquivos do disco permanente usado não corresponder ao fsType especificado no manifesto do PersistentVolume, os pods criados que consumirem os volumes não serão iniciados e serão exibidos erros na descrição do pod. Da mesma forma, os volumes da CSI do Persistent Disk oferecem suporte a uma única partição. Os volumes criados fora do GKE com várias partições não podem ser usados com essa técnica.

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.

• Verifique se você tem discos permanentes. Para provisionar um disco, consulte Como provisionar discos permanentes regionais.
• Verifique se o cluster usa o driver CSI de disco permanente do Compute Engine.

Como usar um PersistentVolumeClaim vinculado ao PersistentVolume

Para que um contêiner acesse o disco permanente preexistente, é necessário fazer o seguinte:

1. Provisione o disco permanente atual como um PersistentVolume.
2. Vincule o PersistentVolume a um PersistentVolumeClaim.
3. Conceda aos contêineres no pod acesso ao PersistentVolume.

Criar o PersistentVolume e o PersistentVolumeClaim

Há várias maneiras de vincular um PersistentVolumeClaim a um PersistentVolume específico. Por exemplo, o manifesto YAML a seguir cria um novo PersistentVolume e PersistentVolumeClaim e, em seguida, vincula o volume à declaração usando o claimRef definido no PersistentVolume.

Para vincular um PersistentVolume a um PersistentVolumeClaim, o storageClassName dos dois recursos precisa corresponder, bem como capacity, accessModes e volumeMode. É possível omitir storageClassName, mas é necessário especificar "" para impedir que o Kubernetes use o StorageClass padrão.

O storageClassName não precisa se referir a um objeto StorageClass existente. Se basta vincular a declaração a um volume, use o nome que quiser. No entanto, se você precisar de uma funcionalidade extra configurada por um StorageClass, como um redimensionamento de volume, storageClassName precisará se referir a um objeto StorageClass existente.

Para saber mais, consulte a documentação do Kubernetes sobre PersistentVolumes.

Observação: o disco permanente tem que estar na mesma zona que os nós do cluster.

1. Salve o seguinte manifesto YAML:

   apiVersion: v1
   kind: PersistentVolume
   metadata:
     name: PV_NAME
   spec:
     storageClassName: "STORAGE_CLASS_NAME"
     capacity:
       storage: DISK_SIZE
     accessModes:
       - ReadWriteOnce
     claimRef:
       name: PV_CLAIM_NAME
       namespace: default
     csi:
       driver: pd.csi.storage.gke.io
       volumeHandle: DISK_ID
       fsType: FS_TYPE
   ---
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     namespace: default
     name: PV_CLAIM_NAME
   spec:
     storageClassName: "STORAGE_CLASS_NAME"
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         storage: DISK_SIZE
   

   Substitua:

   • PV_NAME: o nome do novo PersistentVolume.
   • STORAGE_CLASS_NAME: o nome do novo StorageClass.
   • DISK_SIZE: o tamanho do disco permanente preexistente. Por exemplo, 500G.
   • PV_CLAIM_NAME: o nome do novo PersistentVolumeClaim.
   • DISK_ID: o identificador do disco permanente preexistente. O formato é projects/{project_id}/zones/{zone_name}/disks/{disk_name} para discos permanentes zonais ou projects/{project_id}/regions/{region_name}/disks/{disk_name} para discos permanentes regionais.
   • FS_TYPE: o tipo de sistema de arquivos. Você pode deixar como padrão (ext4) ou usar xfs. Se os clusters usarem um pool de nós do Windows Server, altere esse valor para NTFS.

2. Para aplicar a configuração e criar os recursos PersistentVolume e PersistentVolumeClaim, execute o seguinte comando:

   kubectl apply -f FILE_PATH
   

   Substitua FILE_PATH pelo caminho para o arquivo YAML.

Usar o PersistentVolume em um pod

Depois de criar e vincular o PersistentVolume e o PersistentVolumeClaim, é possível conceder aos contêineres do pod acesso ao volume especificando os valores no campo volumeMounts.

A seguinte configuração YAML cria um novo pod e um contêiner que executa uma imagem nginx e ativa o PersistentVolume no pod:

kind: Pod
apiVersion: v1
metadata:
  name: POD_NAME
spec:
  volumes:
    - name: VOLUME_NAME
      persistentVolumeClaim:
        claimName: PV_CLAIM_NAME
  containers:
    - name: CONTAINER_NAME
      image: nginx
      ports:
        - containerPort: 80
          name: "http-server"
      volumeMounts:
        - mountPath: "/usr/share/nginx/html"
          name: VOLUME_NAME

Substitua:

• POD_NAME: o nome do novo pod.
• VOLUME_NAME: o nome do volume.
• PV_CLAIM_NAME: o nome do PersistentVolumeClaim que você criou na etapa anterior.
• CONTAINER_NAME: o nome do novo contêiner;

Aplique a configuração:

kubectl apply -f FILE_PATH

Substitua FILE_PATH pelo caminho para o arquivo YAML.

Para verificar se o volume foi ativado, execute o seguinte comando:

kubectl describe pods POD_NAME

Na saída, verifique se o PersistentVolumeClaim foi ativado:

...
Volumes:
  VOLUME_NAME:
    Type:       PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
    ClaimName:  PV_CLAIM_NAME
    ReadOnly:   false
Events:
  Type    Reason                  Age   From                     Message
  ----    ------                  ----  ----                     -------
  Normal  Scheduled               29s   default-scheduler        Successfully assigned default/POD_NAME to gke-cluster-1-default-pool-d5cde866-o4g4
  Normal  SuccessfulAttachVolume  21s   attachdetach-controller  AttachVolume.Attach succeeded for volume "PV_NAME"
  Normal  Pulling                 19s   kubelet                  Pulling image "nginx"
  Normal  Pulled                  19s   kubelet                  Successfully pulled image "nginx"
  Normal  Created                 18s   kubelet                  Created container CONTAINER_NAME
  Normal  Started                 18s   kubelet                  Started container CONTAINER_NAME

Como usar um disco preexistente em um StatefulSet

É possível usar discos permanentes preexistentes do Compute Engine em um StatefulSet usando PersistentVolumes. O StatefulSet gera automaticamente um PersistentVolumeClaim para cada réplica. É possível prever os nomes dos PersistentVolumeClaims gerados e vinculá-los aos PersistentVolumes usando claimRef.

No exemplo a seguir, você usa dois discos permanentes preexistentes, cria PersistentVolumes para usar os discos e ativa os volumes em um StatefulSet com duas réplicas no namespace padrão.

1. Escolha um nome para o novo StatefulSet, um nome para o modelo PersistentVolumeClaim e o número de réplicas no StatefulSet.

2. Trabalhe os nomes dos PersistentVolumeClaims gerados automaticamente. O StatefulSet usa o seguinte formato para nomes PersistentVolumeClaim:

   PVC_TEMPLATE_NAME-STATEFULSET_NAME-REPLICA_INDEX
   

   Substitua:

   • PVC_TEMPLATE_NAME: o nome do novo modelo do PersistentVolumeClaim.
   • STATEFULSET_NAME: o nome do novo StatefulSet;
   • REPLICA_INDEX: o índice da réplica do StatefulSet. Neste exemplo, use 0 e 1.

3. Crie os PersistentVolumes. Crie um PersistentVolume para cada réplica no StatefulSet.

   1. Salve o seguinte manifesto YAML:

      apiVersion: v1
      kind: PersistentVolume
      metadata:
        name: pv-ss-demo-0
      spec:
        storageClassName: "STORAGE_CLASS_NAME"
        capacity:
          storage: DISK1_SIZE
        accessModes:
          - ReadWriteOnce
        claimRef:
          namespace: default
          name: PVC_TEMPLATE_NAME-STATEFULSET_NAME-0
        csi:
          driver: pd.csi.storage.gke.io
          volumeHandle: DISK1_ID
          fsType: FS_TYPE
       ---
      apiVersion: v1
      kind: PersistentVolume
      metadata:
        name: pv-ss-demo-1
      spec:
        storageClassName: "STORAGE_CLASS_NAME"
        capacity:
          storage: DISK2_SIZE
        accessModes:
          - ReadWriteOnce
        claimRef:
          namespace: default
          name: PVC_TEMPLATE_NAME-STATEFULSET_NAME-1
        csi:
          driver: pd.csi.storage.gke.io
          volumeHandle: DISK2_ID
          fsType: FS_TYPE
      

      Substitua:

      • DISK1_SIZE and DISK2_SIZE: os tamanhos dos discos permanentes preexistentes;
      • DISK1_ID and DISK2_ID: os identificadores dos discos permanentes preexistentes.
      • PVC_TEMPLATE_NAME-STATEFULSET_NAME-0 and PVC_TEMPLATE_NAME-STATEFULSET_NAME-1: os nomes das PersistentVolumeClaims geradas automaticamente no formato definido na etapa anterior.
      • STORAGE_CLASS_NAME: o nome do StorageClass.

   2. Aplique a configuração:

      kubectl apply -f FILE_PATH
      

      Substitua FILE_PATH pelo caminho para o arquivo YAML.

4. Crie um StatefulSet usando os valores escolhidos na etapa 1. Verifique se o armazenamento especificado em volumeClaimTemplates é menor ou igual à capacidade total dos PersistentVolumes.

   1. Salve o seguinte manifesto YAML:

      apiVersion: apps/v1
      kind: StatefulSet
      metadata:
        name: STATEFULSET_NAME
      spec:
        selector:
          matchLabels:
            app: nginx
        serviceName: "nginx"
        replicas: 2
        template:
          metadata:
            labels:
              app: nginx
          spec:
            terminationGracePeriodSeconds: 10
            containers:
            - name: nginx
              image: registry.k8s.io/nginx-slim:0.8
              ports:
              - containerPort: 80
                name: web
              volumeMounts:
              - name: PVC_TEMPLATE_NAME
                mountPath: /usr/share/nginx/html
        volumeClaimTemplates:
        - metadata:
            name: PVC_TEMPLATE_NAME
          spec:
            accessModes: [ "ReadWriteOnce" ]
            storageClassName: "STORAGE_CLASS_NAME"
            resources:
              requests:
                storage: 100Gi
      

      Substitua:

      • STATEFULSET_NAME: o nome do novo StatefulSet;
      • PVC_TEMPLATE_NAME: o nome do novo modelo PersistentVolumeClaim.
      • STORAGE_CLASS_NAME: o nome do StorageClass.
      Observação: verifique se os nomes do StatefulSet e do PersistentVolumeClaim correspondem aos valores escolhidos na etapa 1.

   2. Aplique a configuração:

      kubectl apply -f FILE_PATH
      

      Substitua FILE_PATH pelo caminho para o arquivo YAML.

A seguir

• Saiba como implantar um aplicativo com estado.