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

Le pod ne démarre pas (FailedMount) en raison des permissions AccessKey

Le pod signale une erreur FailedMount car l'AccessKey ne dispose pas des autorisations requises.

Pour résoudre ce problème :

1. Vérifiez que la politique d'accès de l'utilisateur RAM respecte les exigences de montage OSS. Consultez Utiliser un volume ossfs 2.0 provisionné statiquement.

2. Confirmez que l'AccessKey n'est ni désactivée ni renouvelée.

Échec du pod sur un nœud virtuel avec l'erreur "secrets is forbidden"

L'événement du pod contient le message suivant :

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

Sur les nœuds virtuels (pods Container Compute Service), le Secret référencé par nodePublishSecretRef doit se trouver dans le même namespace que la PersistentVolumeClaim (PVC).

Créez le Secret dans le namespace de la PVC. Dans le PV, définissez nodePublishSecretRef pour qu'il référence ce Secret. Consultez S'authentifier à l'aide de l'AccessKey d'un utilisateur RAM.

Échec du pod avec l'erreur "mounter.sock: connect: no such file or directory"

L'événement du pod contient le message suivant :

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

Le pod ossfs 2.0 n'a pas démarré correctement ou a été supprimé de manière inattendue.

1. Vérifiez si le pod ossfs 2.0 existe sur le nœud où le pod applicatif est planifié :

   • Si le pod existe mais n'est pas dans l'état Running, effectuez son dépannage. Une fois qu'il atteint l'état Running, redémarrez le pod applicatif pour déclencher un remontage.

   • Si le pod n'existe pas, passez à l'étape suivante.

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

2. (Facultatif) Vérifiez les journaux d'audit pour identifier une suppression inattendue du pod. Les causes courantes incluent les scripts de nettoyage, les vidages de nœuds et la réparation automatique. Ajustez les configurations pour éviter que cela ne se reproduise.

3. Vérifiez s'il reste des ressources VolumeAttachment :

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

4. Redémarrez le pod applicatif pour déclencher un remontage et vérifiez qu'un nouveau pod ossfs 2.0 est créé.

Échec du montage car le bucket utilise la fonctionnalité de retour à la source par miroir

Si le bucket OSS utilise la fonctionnalité de retour à la source par miroir et que le répertoire de montage n'est pas synchronisé depuis la source, le montage échoue.

Synchronisez les données depuis la source avant le montage. Consultez Présentation du retour à la source.

Échec du montage car l'hébergement de site statique est activé sur le bucket

Lorsque l'hébergement de site statique est activé, les vérifications de répertoire d'ossfs 2.0 redirigent vers des fichiers tels que index.html, ce qui provoque l'échec du montage.

Désactivez ou ajustez l'hébergement de site statique avant le montage. Consultez Hébergement de site statique.

Monter un seul fichier depuis un bucket OSS

ossfs 2.0 monte un chemin de bucket OSS en tant que système de fichiers ; il ne peut pas monter un fichier unique. Pour accéder à un fichier spécifique, montez le répertoire parent et utilisez subPath dans volumeMounts.

Par exemple, pour monter a.txt et b.txt depuis bucket:/subpath vers différents pods à l'emplacement /path/to/file/ :

Configuration du PV -- montez le répertoire parent :

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 du pod -- utilisez subPath pour sélectionner le fichier :

  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

Après le montage, /path/to/file/a.txt dans le pod correspond à bucket:/subpath/a.txt.

Consultez Utiliser un volume ossfs 2.0 provisionné statiquement.

Monter un bucket OSS depuis un autre compte

Utilisez RRSA (RAM Roles for Service Accounts) pour monter un bucket entre différents comptes.

Vérifiez que les versions de votre cluster et du composant CSI satisfont aux exigences RRSA.

La procédure suivante permet de monter un bucket du Compte B sur un cluster du Compte A.

Dans le Compte B (où réside le bucket) :

1. Créez un rôle RAM nommé roleB qui fait confiance au Compte A. Consultez Créer un rôle RAM pour un compte Alibaba Cloud approuvé.

2. Accordez à roleB les autorisations nécessaires pour accéder au bucket OSS cible.

3. Dans la console RAM, ouvrez la page de détails de roleB et copiez son ARN. Exemple : acs:ram::130xxxxxxxx:role/roleB.

Dans le Compte A (où réside le cluster) :

1. Créez un rôle RAM nommé roleA pour RRSA. Définissez le type d'entité de confiance sur OIDC IdP.

2. Accordez à roleA l'autorisation d'assumer roleB. roleA n'a besoin d'aucune politique d'accès OSS ; attachez-lui une politique contenant l'action sts:AssumeRole, telle que AliyunSTSAssumeRoleAccess. Consultez Activer RRSA dans un cluster (volumes statiques) ou Utiliser un volume ossfs 1.0 provisionné dynamiquement (volumes dynamiques).

Configurer le volume -- définissez assumeRoleArn sur l'ARN de roleB :

• Volume provisionné statiquement (PV) : Ajoutez à volumeAttributes :

    assumeRoleArn: <ARN of roleB>

• Volume provisionné dynamiquement (StorageClass) : Ajoutez à parameters :

    assumeRoleArn: <ARN of roleB>

Utiliser CoreDNS pour résoudre les endpoints d'accès OSS

Pour résoudre les endpoints OSS via un domaine interne au cluster, configurez une stratégie DNS pour le pod ossfs afin de prioriser CoreDNS lors du montage.

Requiert la version v1.34.2 ou ultérieure du composant CSI. Pour effectuer la mise à niveau, consultez Gérer les composants CSI.

• Volume statique (PV) : Ajoutez dnsPolicy à spec.csi.volumeAttributes.

  dnsPolicy: ClusterFirstWithHostNet

• Volumes dynamiques (StorageClass) : Ajoutez dnsPolicy à parameters.

  dnsPolicy: ClusterFirstWithHostNet

Utiliser un ARN personnalisé ou un ServiceAccount pour RRSA

Par défaut, la définition de roleName dans le PV permet au CSI de récupérer automatiquement l'ARN du rôle et l'ARN du fournisseur OIDC. Pour un contrôle plus fin, comme l'utilisation d'un fournisseur d'identité OIDC tiers ou d'un ServiceAccount non par défaut, spécifiez directement roleArn et oidcProviderArn.

roleArn et oidcProviderArn doivent être configurés ensemble. Lorsqu'ils sont définis, ils remplacent 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>"

Dépassement de la capacité configurée du volume

OSS n'applique pas de limites de capacité sur les buckets ou les sous-répertoires. Les valeurs .spec.capacity (PV) et .spec.resources.requests.storage (PVC) sont ignorées ; assurez-vous qu'elles correspondent entre le PV et la PVC liés.

Si l'utilisation réelle dépasse la capacité configurée, le volume fonctionne normalement. Aucun ajustement de l'échelle n'est nécessaire.

Redémarrer le processus ossfs 2.0

Après avoir modifié les identifiants ou la version d'ossfs 2.0, le processus en cours d'exécution ne prend pas automatiquement en compte les changements. L'application des modifications nécessite le redémarrage du pod ossfs 2.0 (csi-fuse-ossfs2-* dans ack-csi-fuse) ainsi que de tous les pods applicatifs utilisant le volume, ce qui entraîne une interruption de service.

Procédure :

1. Identifiez le pod ossfs 2.0 cible. Remplacez <pv-name> et <node-name> :

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

2. Identifiez tous les pods applicatifs utilisant ce volume. Remplacez <ns> et <pvc-name>. Le champ Used By liste les pods :

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

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

3. Trouvez les pods applicatifs sur le même nœud que le pod ossfs 2.0 :

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

4. Supprimez tous les pods applicatifs simultanément. Utilisez kubectl scale ou une méthode équivalente. Lorsqu'aucun pod ne référence le montage, le CSI récupère le pod csi-fuse-ossfs2-*. Après la restauration des replicas, le volume est remonté avec la configuration mise à jour.

Approche alternative -- si la suppression simultanée n'est pas possible (par exemple, un Deployment, StatefulSet ou DaemonSet recrée immédiatement les pods supprimés), ou si l'application tolère des échecs temporaires de lecture/écriture OSS :

1. Trouvez la VolumeAttachment associée au volume. Sortie attendue :

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

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

2. Supprimez la VolumeAttachment. Les pods applicatifs renverront une erreur disconnected error lors des opérations OSS.

3. Redémarrez les pods applicatifs un par un. Chacun se connectera à un nouveau pod csi-fuse-ossfs2-* avec la configuration mise à jour.