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

O pod não inicia com FailedMount devido a permissões de AccessKey

O pod relata FailedMount porque o AccessKey não tem as permissões necessárias.

Para resolver:

1. Verifique se a política de acesso do usuário RAM atende aos requisitos de montagem do OSS. Consulte Usar um volume ossfs 2.0 provisionado estaticamente.

2. Confirme se o AccessKey não está desativado ou rotacionado.

Pod em nó virtual falha com "secrets is forbidden"

O evento do pod contém:

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

Em nós virtuais (pods do Container Compute Service), o Secret referenciado por nodePublishSecretRef deve estar no mesmo namespace da PersistentVolumeClaim (PVC).

Crie o Secret no namespace da PVC. No PV, defina nodePublishSecretRef para referenciar esse Secret. Consulte Autenticar usando o AccessKey de um usuário RAM.

O pod falha com "mounter.sock: connect: no such file or directory"

O evento do pod contém:

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

O pod do ossfs 2.0 não iniciou corretamente ou foi excluído inesperadamente.

1. Verifique se o pod do ossfs 2.0 existe no nó onde o pod da aplicação está agendado:

   • Se o pod existir, mas não estiver no estado Running, solucione o problema. Após ele atingir o estado Running, reinicie o pod da aplicação para acionar uma nova montagem.

   • Caso o pod não exista, prossiga para a próxima etapa.

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

2. (Opcional) Verifique os logs de auditoria para identificar exclusões inesperadas de pods. Causas comuns incluem scripts de limpeza, drenagem de nós e autorrecuperação. Ajuste as configurações para evitar reincidência.

3. Verifique se existem recursos VolumeAttachment remanescentes:

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

4. Reinicie o pod da aplicação para acionar uma nova montagem e verifique se um novo pod do ossfs 2.0 foi criado.

A montagem falha porque o bucket usa back-to-origin baseado em espelhamento

Se o bucket OSS usar back-to-origin baseado em espelhamento e o diretório de montagem não estiver sincronizado com a origem, a montagem falhará.

Sincronize os dados da origem antes de montar. Consulte Visão geral do back-to-origin.

A montagem falha porque o bucket tem hospedagem de site estático ativada

Com a hospedagem de site estático ativada, as verificações de diretório do ossfs 2.0 redirecionam para arquivos como index.html, causando falha na montagem.

Desative ou ajuste a hospedagem de site estático antes de montar. Consulte Hospedagem de site estático.

Montar um único arquivo de um bucket OSS

O ossfs 2.0 monta um caminho de bucket OSS como sistema de arquivos; portanto, não é possível montar um único arquivo isoladamente. Para acessar um arquivo específico, monte o diretório pai e use subPath em volumeMounts.

Por exemplo, para montar a.txt e b.txt de bucket:/subpath em pods diferentes no caminho /path/to/file/:

Configuração do PV -- monte o diretório pai:

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 do Pod -- use subPath para selecionar o arquivo:

  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

Após a montagem, /path/to/file/a.txt no pod corresponderá a bucket:/subpath/a.txt.

Consulte Usar um volume ossfs 2.0 provisionado estaticamente.

Montar um bucket OSS de uma conta diferente

Use RRSA (RAM Roles for Service Accounts) para montar um bucket entre contas.

Verifique se as versões do cluster e do componente CSI atendem aos requisitos do RRSA.

O procedimento a seguir monta um bucket da Conta B em um cluster da Conta A.

Na Conta B (onde o bucket reside):

1. Crie uma função RAM chamada roleB que confie na Conta A. Consulte Criar uma função RAM para uma conta Alibaba Cloud confiável.

2. Conceda à roleB permissões para acessar o bucket OSS de destino.

3. No RAM console, abra a página de detalhes da roleB e copie seu ARN. Exemplo: acs:ram::130xxxxxxxx:role/roleB.

Na Conta A (onde o cluster reside):

1. Crie uma função RAM chamada roleA para RRSA. Defina o tipo de entidade confiável como OIDC IdP.

2. Conceda à roleA permissão para assumir a roleB. A roleA não precisa de política de acesso ao OSS -- anexe uma política com a ação sts:AssumeRole, como AliyunSTSAssumeRoleAccess. Consulte Ativar RRSA em um cluster (volumes estáticos) ou Usar um volume ossfs 1.0 provisionado dinamicamente (volumes dinâmicos).

Configure o volume -- defina assumeRoleArn como o ARN da roleB:

• Volume provisionado estaticamente (PV): Adicione em volumeAttributes:

    assumeRoleArn: <ARN of roleB>

• Volume provisionado dinamicamente (StorageClass): Adicione em parameters:

    assumeRoleArn: <ARN of roleB>

Usar o CoreDNS para resolver endpoints de acesso ao OSS

Para resolver endpoints do OSS por meio de um domínio interno do cluster, configure uma política de DNS para o pod do ossfs priorizar o CoreDNS durante a montagem.

Requer o componente CSI v1.34.2 ou posterior. Para atualizar, consulte Gerenciar componentes CSI.

• Volume estático (PV): Adicione dnsPolicy em spec.csi.volumeAttributes.

  dnsPolicy: ClusterFirstWithHostNet

• Volumes dinâmicos (StorageClass): Adicione dnsPolicy em parameters.

  dnsPolicy: ClusterFirstWithHostNet

Usar um ARN ou ServiceAccount personalizado para RRSA

Por padrão, definir roleName no PV permite que o CSI recupere automaticamente o Role ARN e o OIDC Provider ARN. Para maior controle — como usar um OIDC IdP de terceiros ou um ServiceAccount não padrão — especifique roleArn e oidcProviderArn diretamente.

roleArn e oidcProviderArn devem ser configurados juntos. Quando definidos, substituem 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>"

Excedendo a capacidade configurada do volume

O OSS não impõe limites de capacidade em buckets ou subdiretórios. Os valores de .spec.capacity (PV) e .spec.resources.requests.storage (PVC) são ignorados — garanta que correspondam entre o PV e a PVC vinculados.

Se o uso real exceder a capacidade configurada, o volume operará normalmente. Nenhum dimensionamento é necessário.

Reiniciar o processo do ossfs 2.0

Após modificar credenciais ou a versão do ossfs 2.0, o processo em execução não aplica as alterações automaticamente. Aplicar mudanças exige reiniciar tanto o pod do ossfs 2.0 (csi-fuse-ossfs2-* em ack-csi-fuse) quanto todos os pods da aplicação que utilizam o volume, o que causa interrupção do serviço.

Procedimento:

1. Identifique o pod do ossfs 2.0 de destino. Substitua <pv-name> e <node-name>:

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

2. Identifique todos os pods da aplicação que usam este volume. Substitua <ns> e <pvc-name>. O campo Used By lista os pods:

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

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

3. Encontre os pods da aplicação no mesmo nó que o pod do ossfs 2.0:

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

4. Exclua todos os pods da aplicação simultaneamente. Use kubectl scale ou equivalente. Quando nenhum pod referenciar a montagem, o CSI recuperará o pod csi-fuse-ossfs2-*. Após a restauração das réplicas, o volume será remontado com a configuração atualizada.

Abordagem alternativa -- se a exclusão simultânea não for possível (por exemplo, um Deployment, StatefulSet ou DaemonSet recria imediatamente os pods excluídos) ou se a aplicação tolerar falhas temporárias de leitura/gravação no OSS:

1. Encontre o VolumeAttachment do volume. Saída esperada:

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

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

2. Exclua o VolumeAttachment. Os pods da aplicação retornarão um disconnected error nas operações do OSS.

3. Reinicie os pods da aplicação individualmente. Cada um se conectará a um novo pod csi-fuse-ossfs2-* com a configuração atualizada.