Como usar discos permanentes preexistentes como PersistentVolumes

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.

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.

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.

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.

  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.

    2. Aplique a configuração:

      kubectl apply -f FILE_PATH

      Substitua FILE_PATH pelo caminho para o arquivo YAML.

A seguir