Usa el controlador de CSI de Persistent Disk de Compute Engine

Autopilot Estándar

---

Google Kubernetes Engine (GKE) proporciona una forma sencilla de implementar y administrar de forma automática el controlador de interfaz de almacenamiento de contenedores (CSI) del disco persistente de Compute Engine en tus clústeres. El controlador de CSI de disco persistente de Compute Engine siempre está habilitado en los clústeres de Autopilot y no se puede inhabilitar ni editar. En los clústeres de Standard, debes habilitar el controlador CSI del disco persistente de Compute Engine.

La versión del controlador de CSI del disco persistente de Compute Engine está vinculada a los números de la versión de GKE. La versión del controlador de CSI del disco persistente de Compute Engine suele ser el controlador más reciente disponible en el momento en que se lanza la versión de GKE. Los controladores se actualizan de forma automática cuando el clúster se actualiza al último parche de GKE.

Nota: Debido a que el controlador de CSI del disco persistente de Compute Engine y otros componentes de CSI asociados se implementan como contenedores independientes, generan uso de recursos (CPU de la VM, memoria y disco de arranque) en los nodos de Kubernetes. El uso de CPU de la VM suele ser de decenas de millicores y el uso de la memoria, de decenas de MB. Por lo general, el uso del disco de arranque se debe a los registros del controlador de CSI y de otros contenedores del sistema en la implementación.

Ventajas

El uso del controlador de CSI del disco persistente de Compute Engine proporciona los siguientes beneficios:

• Esto permite la implementación y la administración automáticas del controlador del disco persistente sin tener que configurarlo de forma manual.
• Puedes usar claves de encriptación administradas por el cliente (CMEK). Estas se usan para encriptar las claves de encriptación de datos que encriptan tus datos. Para obtener más información sobre CMEK en GKE, consulta Usa CMEK.
• Puedes usar instantáneas de volumen con el controlador de CSI del disco persistente de Compute Engine. Las instantáneas de volumen te permiten crear una copia del volumen en un momento específico. Puedes usar esta copia para hacer que un volumen vuelva a su estado anterior o con el fin de aprovisionar un volumen nuevo.
• Puedes usar la clonación de volúmenes con el controlador de CSI del disco persistente de Compute Engine en clústeres que ejecutan la versión 1.22 de GKE y, luego, la clonación de volúmenes posterior te permite crear un duplicado de tu volumen en un momento determinado, aprovisionado con todos los datos del volumen de origen.
• La corrección de errores y la actualización de funciones se lanzan de forma independiente de las actualizaciones secundarias de Kubernetes. Por lo general, este programa de lanzamiento da como resultado una cadencia de actualización más rápida.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

• Habilita la API de Kubernetes Engine de Google.
Habilitar la API de Kubernetes Engine de Google
• Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste gcloud CLI, ejecuta gcloud components update para obtener la versión más reciente.
  Nota: Para las instalaciones de gcloud CLI existentes, asegúrate de configurar las propiedades compute/region y compute/zone. Cuando configuras las ubicaciones predeterminadas, puedes evitar errores en gcloud CLI como el siguiente: One of [--zone, --region] must be supplied: Please specify location.

Requisitos

Para usar el controlador de CSI de disco persistente de Compute Engine, los clústeres deben tener las siguientes versiones:

• Clústeres de Linux: GKE versión 1.14 o superior.
• Clústeres de Windows: GKE versión 1.18 o superior.

En la versión 1.22 y en las posteriores, la Migración de CSI está habilitada. En cambio, los volúmenes existentes que usan el proveedor gce-pd se migran para comunicarse a través de controladores de CSI. No se requieren cambios en ninguna StorageClass. El proveedor de gce-pd aún no admite funciones como las instantáneas o los volúmenes de CMEK. Debes usar el proveedor de pd.csi.storage.gke.io en la StorageClass para habilitar estas funciones.

Si quieres usar el controlador de CSI de disco persistente de Compute Engine con la federación de identidades para cargas de trabajo para GKE, los clústeres de Standard deben usar las siguientes versiones:

• Clústeres de Linux: GKE versión 1.16 o superior.
• Clústeres de Windows: GKE versión 1.20.8-gke.900 o superior.

Nota: En Autopilot, el controlador de CSI del disco persistente de Compute Engine está habilitado de forma predeterminada y no se puede inhabilitar ni editar. Para usar el controlador, avanza a Usa el controlador de CSI del disco persistente de Compute Engine para clústeres de Linux.

Habilita el controlador de CSI de disco persistente de Compute Engine en un clúster nuevo

Nota: El controlador de CSI de disco persistente de Compute Engine está habilitado de forma predeterminada en los clústeres creados recientemente para las siguientes versiones:

Clústeres de Linux: GKE versión 1.18.10-gke.2100 o superior, o 1.19.3-gke.2100 o superior.

Clústeres de Windows: GKE versión 1.22.6-gke.300 o posterior, o 1.23.2-gke.300 o posterior.

Para los clústeres Autopilot, el controlador de CSI de disco persistente de Compute Engine está habilitado de forma predeterminada y no se puede inhabilitar o editar.

Para crear un clúster Standard con una versión en la que el controlador de CSI de disco persistente de Compute Engine no esté habilitada de forma automática, puedes usar Google Cloud CLI o la consola de Google Cloud.

Para habilitar el controlador en la creación del clúster, completa los siguientes pasos:

gcloud

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

Reemplaza lo siguiente:

• CLUSTER-NAME: El nombre de tu clúster.
• VERSION: el número de versión de GKE. Debes seleccionar la versión 1.14 o una versión posterior para usar esta característica.

Para ver la lista completa de marcas, consulta la documentación de gcloud container clusters create.

Console

1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

   Ir a Google Kubernetes Engine

2. Haz clic en Crear.

3. En la sección Estándar, haz clic en Configurar.

4. Configura el clúster como quieras.

5. En el panel de navegación, en Clúster, haz clic en Funciones.

6. Selecciona la casilla de verificación Habilita el controlador de CSI de Persistent Disk para Compute Engine.

7. Haga clic en Crear.

Después de habilitar el controlador CSI del disco persistente de Compute Engine, puedes usarlo en volúmenes de Kubernetes con el nombre de controlador y aprovisionador: pd.csi.storage.gke.io.

Habilita el controlador de CSI de disco persistente de Compute Engine en un clúster existente

Para habilitar el controlador de CSI de disco persistente de Compute Engine en clústeres estándar existentes, usa Google Cloud CLI o la consola de Google Cloud.

Para habilitar el controlador en un clúster existente, completa los siguientes pasos:

gcloud

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

Reemplaza CLUSTER-NAME por el nombre del clúster existente.

Console

1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

   Ir a Google Kubernetes Engine

2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

3. En Funciones junto al campo Controlador de CSI del disco persistente de Compute Engine, haz clic en Edita el controlador de CSI de Compute Engine.

4. Selecciona la casilla de verificación Habilitar el controlador de CSI de Persistent Disk de Compute Engine.

5. Haz clic en Save Changes.

Inhabilita el controlador de CSI de disco persistente de Compute Engine

Puedes inhabilitar el controlador de CSI del disco persistente de Compute Engine para clústeres estándar mediante Google Cloud CLI o la consola de Google Cloud.

Si inhabilitas el controlador, no se finalizarán los Pods que usen PersistentVolumes pertenecientes al controlador. Además, fallará el inicio de todos los Pods nuevos que intenten usar esos PersistentVolumes.

Nota: A medida que el tipo de volumen gcePersistentDisk se migra al controlador de CSI del disco persistente de Compute Engine en la versión 1.22 y posteriores, si inhabilitas el controlador de CSI del disco persistente, el tipo de volumen gcePersistentDisk también deja de funcionar.

Advertencia: Hay un problema conocido en GKE 1.21 y antes si usas el controlador de disco persistente en el árbol y deseas borrar los discos regionales. Un disco regional de Compute Engine puede filtrarse cuando se borra su recurso PersistentVolume relacionado. Este problema se puede detectar cuando falla la llamada a la API para borrar el disco regional y muestra un código de error que no es NotFound. Para obtener más información, consulta este problema de GitHub.

Para inhabilitar el controlador en un clúster Estándar existente, completa los siguientes pasos:

gcloud

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

Reemplaza CLUSTER-NAME por el nombre del clúster existente.

Console

1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

   Ir a Google Kubernetes Engine

2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

3. En Funciones junto al campo Controlador de CSI del disco persistente de Compute Engine, haz clic en Edita el controlador de CSI de Compute Engine.

4. Selecciona la casilla de verificación Habilita el controlador de CSI de disco persistente de Compute Engine.

5. Haz clic en Save Changes.

Usa el controlador de CSI de disco persistente de Compute Engine para clústeres de Linux

En las siguientes secciones, se describe el proceso típico para usar un volumen de Kubernetes respaldado por un controlador de CSI en GKE. Estas secciones son específicas para clústeres que usan Linux.

Crea un StorageClass

Después de habilitar el controlador CSI del disco persistente de Compute Engine, GKE instala de forma automática las siguientes StorageClasses:

• standard-rwo, con disco persistente balanceado
• premium-rwo, con disco persistente SSD

Para los clústeres Autopilot, la StorageClass predeterminada es standard-rwo, que usa el controlador de CSI del disco persistente de Compute Engine. Para los clústeres estándar, la StorageClass predeterminada usa el complemento de volumen gcePersistentDisk en árbol de Kubernetes.

Para encontrar el nombre de la StorageClass instalada, ejecuta el siguiente comando:

kubectl get sc

También puedes instalar una StorageClass diferente que use el controlador de CSI del disco persistente de Compute Engine. Para ello, agrega pd.csi.storage.gke.io en el campo del aprovisionador.

Por ejemplo, puedes crear un StorageClass mediante el siguiente archivo llamado 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

Puedes especificar los siguientes tipos de disco persistente en el parámetro type:

• pd-balanced
• pd-ssd
• pd-standard
• pd-extreme (compatible con la versión 1.26 de GKE y versiones posteriores)

Si usas pd-standard o pd-extreme, consulta los tipos de máquinas no compatibles para conocer las restricciones adicionales de uso.

Cuando usas la opción pd-extreme, también debes agregar el campo provisioned-iops-on-create a tu manifiesto. Este campo debe configurarse con el mismo valor que el valor de IOPS aprovisionado que especificaste cuando creaste el disco persistente.

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'

Después de crear el archivo pd-example-class.yaml, ejecuta el siguiente comando:

kubectl create -f pd-example-class.yaml

Crea una PersistentVolumeClaim

Puedes crear una PersistentVolumeClaim que haga referencia a la StorageClass del controlador de CSI del disco persistente de Compute Engine.

En el siguiente archivo, llamado pvc-example.yaml, se usa la clase de almacenamiento standard-rwo instalada previamente:

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

Después de crear el manifiesto de PersistentVolumeClaim, ejecuta el siguiente comando:

kubectl create -f pvc-example.yaml

En la StorageClass instalada previamente (standard-rwo), volumeBindingMode se configura como WaitForFirstConsumer. Cuando volumeBindingMode se establece como WaitForFirstConsumer, el PersistentVolume no se aprovisiona hasta que se programa un Pod que haga referencia a la PersistentVolumeClaim. Si volumeBindingMode en la StorageClass se configura como Immediate (o se omite), se aprovisiona un PersistentVolume respaldado por un disco persistente luego de que se crea la PersistentVolumeClaim.

Crea un Pod que consuma el volumen

Cuando uses Pods con PersistentVolumes, te recomendamos usar un controlador de carga de trabajo (como Deployment o StatefulSet). Si bien no se suele usar un Pod independiente, en el siguiente ejemplo, se usa uno para mayor simplicidad.

En el siguiente ejemplo, se consume el volumen que creaste en la sección 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

Usa el controlador de CSI de disco persistente de Compute Engine para clústeres de Windows

En las siguientes secciones, se describe el proceso típico para usar un volumen de Kubernetes respaldado por un controlador de CSI en GKE. Estas secciones son específicas para clústeres que usan Windows.

Asegúrate de que se cumplan estas condiciones:

• La versión del clúster es 1.19.7-gke.2000, 1.20.2-gke.2000 o superior.
• Las versiones de nodo son 1.18.12-gke.1203, 1.19.6-gke.800 o superiores.

Crea un StorageClass

Crear una StorageClass para Windows es muy similar a hacerlo en Linux. Debes tener en cuenta que la StorageClass instalada de forma predeterminada no funcionará para Windows porque el tipo de sistema de archivos es diferente. El controlador de CSI de disco persistente de Compute Engine para Windows requiere NTFS como tipo de sistema de archivos.

Por ejemplo, puedes crear una StorageClass mediante el siguiente archivo llamado pd- windows-class.yaml. Asegúrate de agregar csi.storage.k8s.io/fstype: NTFS a la 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

Crea una PersistentVolumeClaim

Después de crear una StorageClass para Windows, puedes crear un PersistentVolumeClaim que haga referencia a esa StorageClass:

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

Crea un Pod que consuma el volumen

En el siguiente ejemplo, se consume el volumen que creaste en la tarea 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

Usa el controlador de CSI de disco persistente de Compute Engine con tipos de sistema de archivos no predeterminados

El tipo de sistema de archivos predeterminado para los discos persistentes de Compute Engine en GKE es ext4. También puedes usar el tipo de almacenamiento xfs siempre que la imagen de tu nodo lo admita. Consulta Compatibilidad de controladores de almacenamiento para obtener una lista de controladores compatibles por imagen de nodo.

En el siguiente ejemplo, se muestra cómo usar xfs como el tipo de sistema de archivos predeterminado en lugar de ext4 con el controlador de CSI del disco persistente de Compute Engine.

Crea un StorageClass

1. Guarda el siguiente manifiesto YAML como un archivo llamado 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. Aplica el manifiesto

   kubectl apply -f pd-xfs-class.yaml
   

Crea una PersistentVolumeClaim

1. Guarda el siguiente manifiesto como pd-xfs-pvc.yaml:

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

2. Aplica el manifiesto

   kubectl apply -f pd-xfs-pvc.yaml
   

Crea un Pod que consuma el volumen

1. Guarda el siguiente manifiesto 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. Aplica el manifiesto

   kubectl apply -f pd-xfs-pod.yaml
   

Verifica que el volumen se haya activado de forma correcta

1. Abre una sesión de shell en el Pod:

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

2. Busca particiones xfs:

   df -aTh --type=xfs
   

   El resultado debería ser similar al ejemplo siguiente:

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

Visualiza los registros del controlador de CSI de Persistent Disk para Compute Engine

Puedes usar Cloud Logging para ver eventos relacionados con el controlador de CSI de Persistent Disk para Compute Engine. Los registros pueden ayudarte a solucionar problemas.

Para obtener más información sobre Cloud Logging, consulta Visualiza los registros de GKE.

Para ver los registros del controlador de CSI de Persistent Disk para Compute Engine, completa los siguientes pasos:

1. Ve a la página Cloud Logging en la consola de Google Cloud.

   Ir a Cloud Logging

2. Ejecute la siguiente 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"
   

   Reemplaza lo siguiente:

   • PROJECT_ID: nombre del proyecto.
   • LOCATION: la región o zona de Compute Engine del clúster.
   • CLUSTER_NAME: El nombre de tu clúster.

Problemas conocidos

Tipos de máquinas no compatibles

Si usas la familia de máquinas de la serie C3, el tipo de disco persistente pd-standard no es compatible.

Si intentas ejecutar un Pod en una máquina y el Pod usa un tipo de disco persistente no compatible, verás un mensaje de advertencia como el siguiente que se emite en el 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.

Si tu clúster tiene varios grupos de nodos con diferentes familias de máquinas, puedes usar taints de nodos y afinidad de nodos para limitar las cargas de trabajo se puede programar. Por ejemplo, puedes usar este método para restringir la ejecución de una carga de trabajo con pd-standard en una familia de máquinas no compatible.

Si usas el tipo de disco persistente pd-extreme, debes asegurarte de que el disco esté conectado a una instancia de VM con una forma de máquina adecuada. Para obtener más información, consulta Compatibilidad con formas de máquinas.

¿Qué sigue?

• Obtén más información sobre cómo usar la expansión de volúmenes.
• Obtén información sobre cómo usar las instantáneas de volumen.
• Obtén más información para usar la clonación de volúmenes.
• Obtén más información sobre el controlador en GitHub.