Container Service for Kubernetes:ossfs 2.0 persistent volume FAQ

# Check pod events for mount errors
kubectl describe pod <pod-name> -n <namespace>

# Check whether the ossfs 2.0 pod exists and is running
kubectl -n ack-csi-fuse get pod -l csi.alibabacloud.com/volume-id=<pv-name> -owide

El pod no se inicia con FailedMount debido a permisos de AccessKey

El pod reporta FailedMount porque la AccessKey carece de los permisos obligatorios.

Para resolverlo:

1. Compruebe que la directiva de acceso del usuario de RAM cumple con los requisitos para montar OSS. Consulte Use a statically provisioned ossfs 2.0 volume.

2. Confirme que la AccessKey no esté deshabilitada ni rotada.

El pod en un nodo virtual falla con "secrets is forbidden"

El evento del pod contiene:

failed to get secret secrets "xxx" is forbidden: User "serverless-xxx" cannot get resource "secrets" in API group "" in the namespace "xxx"

En nodos virtuales (pods de Container Compute Service), el Secret al que hace referencia nodePublishSecretRef debe encontrarse en el mismo namespace que el PersistentVolumeClaim (PVC).

Cree el Secret en el namespace del PVC. En el PV, establezca nodePublishSecretRef para hacer referencia a este Secret. Consulte Authenticate using a RAM user's AccessKey.

El pod falla con "mounter.sock: connect: no such file or directory"

El evento del pod contiene:

FailedMount /run/fuse.ossfs/xxxxxx/mounter.sock: connect: no such file or directory

El pod de ossfs 2.0 no se inició correctamente o se eliminó de forma inesperada.

1. Compruebe si existe el pod de ossfs 2.0 en el nodo donde está programado el pod de la aplicación:

   • Si el pod existe pero no está en estado Running, solucione el problema. Una vez que alcance el estado Running, reinicie el pod de la aplicación para activar un nuevo montaje.

   • Si el pod no existe, continúe con el siguiente paso.

      kubectl -n ack-csi-fuse get pod -l csi.alibabacloud.com/volume-id=<PV_NAME> -owide | grep <NODE_NAME>

2. (Opcional) Revise los registros de auditoría para detectar eliminaciones inesperadas del pod. Las causas comunes incluyen scripts de limpieza, drenados de nodos y autorrecuperación. Ajuste la configuración para evitar que se repita.

3. Verifique si quedan recursos VolumeAttachment pendientes:

      kubectl get volumeattachment | grep <PV_NAME> | grep <NODE_NAME>

4. Reinicie el pod de la aplicación para activar un nuevo montaje y compruebe que se crea un nuevo pod de ossfs 2.0.

El montaje falla porque el bucket utiliza back-to-origin basado en espejo

Si el bucket de OSS utiliza back-to-origin basado en espejo y el directorio de montaje no está sincronizado desde el origen, el montaje fallará.

Sincronice los datos desde el origen antes de realizar el montaje. Consulte Back-to-origin overview.

El montaje falla porque el bucket tiene habilitado el hosting de sitios web estáticos

Cuando el hosting de sitios web estáticos está habilitado, las comprobaciones de directorio de ossfs 2.0 redirigen a archivos como index.html, lo que provoca un error en el montaje.

Deshabilite o ajuste el hosting de sitios web estáticos antes de montar. Consulte Static website hosting.

Montar un solo archivo desde un bucket de OSS

ossfs 2.0 monta una ruta de bucket de OSS como sistema de archivos, por lo que no puede montar un solo archivo. Para acceder a un archivo específico, monte el directorio padre y utilice subPath en volumeMounts.

Por ejemplo, para montar a.txt y b.txt desde bucket:/subpath hacia diferentes pods en /path/to/file/:

Configuración del PV: monte el directorio padre:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-oss
spec:
  capacity:
    storage: 5Gi
  accessModes:
    - ReadOnlyMany
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: ossplugin.csi.alibabacloud.com
    volumeHandle: pv-oss
    volumeAttributes:
      bucket: bucket
      path: subpath              # Parent path containing a.txt and b.txt
      url: "oss-cn-hangzhou.aliyuncs.com"
      fuseType: ossfs2

volumeMounts del Pod: use subPath para seleccionar el archivo:

  volumeMounts:
    - mountPath: /path/to/file   # Maps to bucket:/subpath
      name: oss-pvc              # Must match the volume name
      subPath: a.txt             # Relative path within bucket:/subpath

Después del montaje, /path/to/file/a.txt en el pod corresponde a bucket:/subpath/a.txt.

Consulte Use a statically provisioned ossfs 2.0 volume.

Montar un bucket de OSS desde otra cuenta

Utilice RRSA (RAM Roles for Service Accounts) para montar un bucket entre distintas cuentas.

Compruebe que las versiones de su clúster y del componente CSI cumplen los requisitos de RRSA.

El siguiente procedimiento monta un bucket de la Cuenta B en un clúster de la Cuenta A.

En la Cuenta B (donde reside el bucket):

1. Cree un rol de RAM llamado roleB que confíe en la Cuenta A. Consulte Create a RAM role for a trusted Alibaba Cloud account.

2. Otorgue a roleB permisos para acceder al bucket de OSS de destino.

3. En la consola de RAM, abra la página de detalles de roleB y copie su ARN. Ejemplo: acs:ram::130xxxxxxxx:role/roleB.

En la Cuenta A (donde reside el clúster):

1. Cree un rol de RAM llamado roleA para RRSA. Establezca el tipo de entidad de confianza como OIDC IdP.

2. Otorgue a roleA permiso para asumir roleB. roleA no necesita ninguna directiva de acceso a OSS; asocie una directiva con la acción sts:AssumeRole, como AliyunSTSAssumeRoleAccess. Consulte Enable RRSA in a cluster (volúmenes estáticos) o Use a dynamically provisioned ossfs 1.0 volume (volúmenes dinámicos).

Configure el volumen: establezca assumeRoleArn con el ARN de roleB:

• Volumen aprovisionado estáticamente (PV): Agregue lo siguiente a volumeAttributes:

    assumeRoleArn: <ARN of roleB>

• Volumen aprovisionado dinámicamente (StorageClass): Agregue lo siguiente a parameters:

    assumeRoleArn: <ARN of roleB>

Uso de CoreDNS para resolver endpoints de acceso a OSS

Para resolver endpoints de OSS mediante un dominio interno del clúster, configure una directiva de DNS para que el pod de ossfs priorice CoreDNS durante el montaje.

Se requiere el componente CSI v1.34.2 o posterior. Para actualizar, consulte Manage CSI components.

• Volumen estático (PV): Agregue dnsPolicy a spec.csi.volumeAttributes.

  dnsPolicy: ClusterFirstWithHostNet

• Volúmenes dinámicos (StorageClass): Agregue dnsPolicy a parameters.

  dnsPolicy: ClusterFirstWithHostNet

Uso de un ARN o ServiceAccount personalizado para RRSA

De forma predeterminada, al establecer roleName en el PV, CSI recupera automáticamente el ARN del rol y el ARN del proveedor OIDC. Para tener mayor control, como usar un IdP OIDC de terceros o un ServiceAccount no predeterminado, especifique directamente roleArn y oidcProviderArn.

roleArn y oidcProviderArn deben configurarse juntos. Cuando se establecen, anulan roleName .

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-oss
spec:
  capacity:
    storage: 5Gi
  accessModes:
    - ReadOnlyMany
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: ossplugin.csi.alibabacloud.com
    volumeHandle: pv-oss               # Must match the PV name
    volumeAttributes:
      bucket: "oss"
      url: "oss-cn-hangzhou.aliyuncs.com"
      authType: "rrsa"
      fuseType: "ossfs2"
      oidcProviderArn: "<oidc-provider-arn>"
      roleArn: "<role-arn>"
      # roleName: "<role-name>"        # Ignored when roleArn and oidcProviderArn are set
      serviceAccountName: "csi-fuse-<service-account-name>"

Superación de la capacidad configurada del volumen

OSS no aplica límites de capacidad en buckets o subdirectorios. Los valores de .spec.capacity (PV) y .spec.resources.requests.storage (PVC) se ignoran; asegúrese de que coincidan entre el PV y el PVC vinculados.

Si el uso real supera la capacidad configurada, el volumen funciona con normalidad. No es necesario escalar.

Reiniciar el proceso de ossfs 2.0

Después de modificar las credenciales o la versión de ossfs 2.0, el proceso en ejecución no aplica los cambios automáticamente. Para aplicarlos, debe reiniciar tanto el pod de ossfs 2.0 (csi-fuse-ossfs2-* en ack-csi-fuse) como todos los pods de aplicaciones que usen el volumen, lo cual causa una interrupción del servicio.

Procedimiento:

1. Identifique el pod de ossfs 2.0 objetivo. Reemplace <pv-name> y <node-name>:

      kubectl -n ack-csi-fuse get pod -l csi.alibabacloud.com/volume-id=<pv-name> -owide | grep <node-name>

2. Identifique todos los pods de aplicaciones que usan este volumen. Reemplace <ns> y <pvc-name>. El campo Used By enumera los pods:

      kubectl -n <ns> describe pvc <pvc-name>

      Used By:       oss-static-94849f647-4****
                     oss-static-94849f647-6****
                     oss-static-94849f647-h****

3. Encuentre los pods de aplicaciones en el mismo nodo que el pod de ossfs 2.0:

      kubectl -n <ns> get pod -owide | grep <node-name>

4. Elimine todos los pods de aplicaciones simultáneamente. Use kubectl scale o un comando equivalente. Cuando ningún pod haga referencia al montaje, CSI recuperará el pod csi-fuse-ossfs2-*. Una vez restauradas las réplicas, el volumen se volverá a montar con la configuración actualizada.

Enfoque alternativo: si no es posible la eliminación simultánea (por ejemplo, si un Deployment, StatefulSet o DaemonSet recrea inmediatamente los pods eliminados), o si la aplicación tolera fallos temporales de lectura/escritura en OSS:

1. Busque el VolumeAttachment correspondiente al volumen. Salida esperada:

      kubectl get volumeattachment | grep <pv-name> | grep <node-name>

      csi-bd463c719189f858c2394608da7feb5af8f181704b77a46bbc219b**********   ossplugin.csi.alibabacloud.com   <pv-name>   <node-name>   true   12m

2. Elimine el VolumeAttachment. Los pods de aplicaciones devolverán un disconnected error en las operaciones de OSS.

3. Reinicie los pods de aplicaciones uno por uno. Cada uno se conectará a un nuevo pod csi-fuse-ossfs2-* con la configuración actualizada.