Mount a static OSS persistent volume by using ossfs 2.0 in an ACK cluster - Container Service for Kubernetes: Central de Documentação do Alibaba Cloud

Como funciona

A montagem de um bucket do OSS como volume provisionado estaticamente em um cluster do Container Service for Kubernetes (ACK) envolve quatro etapas:

Escolha um método de autenticação. Em produção, utilize RAM Roles for Service Accounts (RRSA), pois fornece credenciais temporárias com rotação automática e isolamento de permissões no nível do Pod. Reserve o uso de AccessKey apenas para testes, já que depende de uma chave estática de longo prazo.
Crie um PV. Defina um PV para registrar seu bucket do OSS existente no cluster, especificando nome do bucket, endpoint, subdiretório e detalhes de autenticação.
Crie um PVC. Crie um Persistent Volume Claim (PVC) vinculado ao PV definido.
Implante uma aplicação. Referencie o PVC no manifesto da carga de trabalho para montar o bucket do OSS no contêiner.

Observações de uso

Cargas de trabalho suportadas: O ossfs 2.0 suporta operações de somente leitura e escrita sequencial com acréscimo. Para escritas aleatórias ou concorrentes, não há garantia de consistência dos dados — utilize o ossfs 1.0 nesses casos.
Segurança dos dados: Alterações em arquivos no ponto de montagem — seja dentro do Pod ou no nó host — são sincronizadas imediatamente com o bucket do OSS. Ative o versionamento no bucket para proteger contra exclusões acidentais.
Verificações de integridade: Configure um liveness probe nos Pods que utilizam volumes OSS para confirmar a acessibilidade do ponto de montagem. Caso a verificação falhe, o Kubernetes reinicia automaticamente o Pod e aciona uma nova montagem.
Uploads multipart: O ossfs utiliza automaticamente upload multipart para arquivos maiores que 10 MB. Se houver interrupção, partes incompletas permanecerão no bucket. Exclua essas partes manualmente ou configure uma regra de ciclo de vida para limpá-las automaticamente.

Método 1: Autenticar usando RRSA (recomendado)

O RRSA autentica Pods usando credenciais temporárias com rotação automática por meio de OpenID Connect (OIDC) e Security Token Service (STS), além de suportar isolamento de permissões no nível do PV. Para mais informações, consulte Usar RRSA para autorizar diferentes pods a acessar diferentes serviços de nuvem.

Pré-requisitos

Antes de começar, certifique-se de ter:

Um cluster ACK executando Kubernetes 1.26 ou posterior. Atualize o cluster se necessário.
Plugin CSI versão 1.33.1 ou posterior. Para atualizar, consulte Atualizar csi-plugin e csi-provisioner.

Se sua versão do CSI for anterior à 1.30.4 e você planeja usar RRSA, consulte [\[Alterações do Produto\] Atualização de versão e otimização do processo de montagem do ossfs no CSI](https://www.alibabacloud.com/help/en/document_detail/2842828.html) para configurar a autorização de função RAM antes de prosseguir.
Um bucket do OSS na mesma conta Alibaba Cloud do cluster.

Para montar um bucket do OSS entre contas, use o método de autenticação RRSA. Consulte FAQ sobre volumes ossfs 2.0 para obter detalhes.

Etapa 1: Criar uma função RAM

Ignore esta etapa se você já montou um volume OSS no cluster usando RRSA.

Ative o recurso RRSA no console ACK.

Crie uma função RAM para um provedor de identidade OIDC. A tabela a seguir lista os principais parâmetros para a função de exemplo demo-role-for-rrsa.

Parâmetro	Valor
Identity provider type	Selecione OIDC.
Identity provider	Selecione o provedor associado ao seu cluster, por exemplo, `ack-rrsa-<cluster_id>`.
oidc:iss	Mantenha o valor padrão.
oidc:aud	Mantenha o valor padrão.
oidc:sub	Adicione uma condição: Key = `oidc:sub`, Operator = `StringEquals`, Value = `system:serviceaccount:ack-csi-fuse:csi-fuse-ossfs`. `ack-csi-fuse` é o namespace onde o cliente ossfs executa e não pode ser alterado. `csi-fuse-ossfs` é o nome do ServiceAccount e pode ser personalizado.
Role name	`demo-role-for-rrsa`

Para alterar o nome do ServiceAccount, consulte FAQ sobre volumes ossfs 2.0 .

Etapa 2: Conceder permissões à função RAM

Crie uma política personalizada para conceder acesso ao OSS. Para detalhes, consulte Criar políticas personalizadas. Substitua mybucket pelo nome real do seu bucket.

Política de somente leitura

{
    "Statement": [
        {
            "Action": [
                "oss:Get*",
                "oss:List*"
            ],
            "Effect": "Allow",
            "Resource": [
                "acs:oss:*:*:mybucket",
                "acs:oss:*:*:mybucket/*"
            ]
        }
    ],
    "Version": "1"
}

Política de leitura e escrita

{
    "Statement": [
        {
            "Action": "oss:*",
            "Effect": "Allow",
            "Resource": [
                "acs:oss:*:*:mybucket",
                "acs:oss:*:*:mybucket/*"
            ]
        }
    ],
    "Version": "1"
}

(Opcional) Se os objetos no bucket estiverem criptografados com uma chave mestra do cliente (CMK) no Key Management Service (KMS), conceda permissões de acesso ao KMS. Consulte Criptografia para obter detalhes.
Anexe a política à função demo-role-for-rrsa. Consulte Conceder permissões a uma função RAM.

Para usar uma função RAM existente que já tenha acesso ao OSS, modifique sua política de confiança. Consulte Usar uma função RAM existente .

Etapa 3: Criar um PV

Crie o arquivo ossfs2-pv.yaml com o seguinte conteúdo.

O PV a seguir monta o bucket do OSS cnfs-oss-test como um sistema de arquivos de somente leitura de 20 GiB.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-ossfs2                          # PV name
spec:
  capacity:
    storage: 20Gi                          # Used for PVC matching only; does not cap OSS capacity
  accessModes:
    - ReadOnlyMany
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: ossplugin.csi.alibabacloud.com
    volumeHandle: pv-ossfs2                # Must match metadata.name exactly
    volumeAttributes:
      fuseType: ossfs2                     # Required: specifies the ossfs 2.0 client
      bucket: cnfs-oss-test                # OSS bucket name
      path: /subpath                       # Subdirectory to mount; leave blank to mount the root
      url: oss-cn-hangzhou-internal.aliyuncs.com  # Internal endpoint (same region); use public endpoint for cross-region
      otherOpts: "-o close_to_open=false"  # false (default): cache metadata for better small-file read performance
                                           # true: fetch fresh metadata on every file open (higher latency, useful when another system frequently updates objects)
      authType: "rrsa"                     # Authentication method
      roleName: "demo-role-for-rrsa"       # RAM role created in Step 1

Principais parâmetros em volumeAttributes:

Parâmetro	Obrigatório	Descrição
`fuseType`	Sim	Deve ser `ossfs2` para usar o cliente ossfs 2.0.
`bucket`	Sim	Nome do bucket do OSS a ser montado.
`path`	Não	Subdiretório dentro do bucket. O padrão é a raiz se deixado em branco.
`url`	Sim	Endpoint do OSS. Use um endpoint interno quando o cluster e o bucket estiverem na mesma região (ou conectados via Virtual Private Cloud (VPC)); use um endpoint público para acesso entre regiões. Formato interno: `http(s)://oss-{region}-internal.aliyuncs.com`. Formato público: `http(s)://oss-{region}.aliyuncs.com`. O formato de endpoint interno `vpc100-oss-{region}.aliyuncs.com` foi descontinuado — migre para o novo formato.
`otherOpts`	Não	Opções adicionais de montagem no formato `-o <option> -o <option>`. Para todas as opções disponíveis, consulte opções de montagem do ossfs 2.0.
`authType`	Sim	Defina como `rrsa`.
`roleName`	Sim	Nome da função RAM. Para atribuir permissões diferentes a PVs distintos, crie uma função RAM separada para cada um e referencie-a aqui.

Para usar ARNs específicos ou um ServiceAccount personalizado com RRSA, consulte Como uso ARNs específicos ou um ServiceAccount com o método de autenticação RRSA?

Aplique o manifesto.
```
kubectl create -f ossfs2-pv.yaml
```

Verifique se o PV está disponível.

kubectl get pv pv-ossfs2

Saída esperada:

NAME        CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS   VOLUMEATTRIBUTESCLASS   REASON   AGE
pv-ossfs2   20Gi       ROX            Retain           Available                          <unset>                          15s

Etapa 4: Criar um PVC

Crie o arquivo ossfs2-pvc-static.yaml com o seguinte conteúdo.

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: pvc-ossfs2       # PVC name
  namespace: default
spec:
  accessModes:
    - ReadOnlyMany        # Must match the PV
  resources:
    requests:
      storage: 20Gi       # Must match the PV
  volumeName: pv-ossfs2   # Bind to this specific PV

Crie o PVC.

kubectl create -f ossfs2-pvc-static.yaml

Verifique se o PVC está vinculado.

kubectl get pvc pvc-ossfs2

Saída esperada:

NAME         STATUS   VOLUME      CAPACITY   ACCESS MODES   STORAGECLASS   VOLUMEATTRIBUTESCLASS   AGE
pvc-ossfs2   Bound    pv-ossfs2   20Gi       ROX                           <unset>                 6s

Etapa 5: Implantar uma aplicação

Crie o arquivo ossfs2-test.yaml para definir um StatefulSet que monta o PVC em /data.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: ossfs2-test
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ossfs2-test
  template:
    metadata:
      labels:
        app: ossfs2-test
    spec:
      containers:
      - name: nginx
        image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
        ports:
        - containerPort: 80
        volumeMounts:
        - name: pvc-ossfs2
          mountPath: /data
      volumes:
        - name: pvc-ossfs2
          persistentVolumeClaim:
            claimName: pvc-ossfs2

Implante a aplicação.
```
kubectl create -f ossfs2-test.yaml
```

Aguarde até que o Pod esteja em execução.

kubectl get pod -l app=ossfs2-test

Saída esperada:

NAME            READY   STATUS    RESTARTS   AGE
ossfs2-test-0   1/1     Running   0          12m

Verifique se o bucket do OSS está montado.
```
kubectl exec -it ossfs2-test-0 -- ls /data
```
A saída deve mostrar os dados no caminho de montagem do OSS.

Método 2: Autenticar usando um AccessKey

Armazene um par de AccessKey em um Secret do Kubernetes e referencie-o no PV. Essa abordagem é simples de configurar, mas utiliza uma chave estática de longo prazo.

Importante

Se o AccessKey for revogado ou suas permissões forem alteradas, todos os Pods que usam o volume perderão o acesso imediatamente. Para restaurar o acesso, atualize o Secret com novas credenciais e reinicie os Pods afetados — isso causa uma breve interrupção do serviço. Em ambientes de produção, utilize o Método 1: Autenticar usando RRSA para evitar essa sobrecarga operacional.

Pré-requisitos

Antes de começar, certifique-se de ter:

Um cluster ACK com o plugin CSI versão 1.33.1 ou posterior. Para atualizar, consulte Atualizar csi-plugin e csi-provisioner.
Um bucket do OSS na mesma conta Alibaba Cloud do cluster.

Para montar um bucket do OSS entre contas, use RRSA. Consulte FAQ sobre volumes ossfs 2.0 .

Etapa 1: Criar um usuário RAM e armazenar o AccessKey

Crie um usuário RAM. Se você já tiver um, ignore esta etapa. Consulte Criar um usuário RAM.

Crie uma política personalizada para conceder acesso ao OSS. Consulte Criar políticas personalizadas. Substitua mybucket pelo nome real do seu bucket.

Política de somente leitura

{
    "Statement": [
        {
            "Action": [
                "oss:Get*",
                "oss:List*"
            ],
            "Effect": "Allow",
            "Resource": [
                "acs:oss:*:*:mybucket",
                "acs:oss:*:*:mybucket/*"
            ]
        }
    ],
    "Version": "1"
}

Política de leitura e escrita

{
    "Statement": [
        {
            "Action": "oss:*",
            "Effect": "Allow",
            "Resource": [
                "acs:oss:*:*:mybucket",
                "acs:oss:*:*:mybucket/*"
            ]
        }
    ],
    "Version": "1"
}

(Opcional) Se os objetos no bucket estiverem criptografados com uma CMK no KMS, conceda acesso ao KMS. Consulte Criptografia.
Anexe a política ao usuário RAM. Consulte Conceder permissões a um usuário RAM.
Crie um par de AccessKey para o usuário RAM. Consulte Criar um par de AccessKey.

Armazene o par de AccessKey como um Secret do Kubernetes. Substitua xxxxxx pelos valores reais.

kubectl create -n default secret generic oss-secret \
  --from-literal='akId=xxxxxx' \
  --from-literal='akSecret=xxxxxx'

Etapa 2: Criar um PV

Crie o arquivo ossfs2-pv-ak.yaml com o seguinte conteúdo.

O PV a seguir monta o bucket do OSS cnfs-oss-test como um sistema de arquivos de somente leitura de 20 GiB.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-ossfs2                          # PV name
spec:
  capacity:
    storage: 20Gi                          # Used for PVC matching only
  accessModes:
    - ReadOnlyMany
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: ossplugin.csi.alibabacloud.com
    volumeHandle: pv-ossfs2                # Must match metadata.name exactly
    nodePublishSecretRef:
      name: oss-secret                     # Secret created in Step 1
      namespace: default
    volumeAttributes:
      fuseType: ossfs2                     # Required: specifies the ossfs 2.0 client
      bucket: cnfs-oss-test                # OSS bucket name
      path: /subpath                       # Subdirectory to mount; leave blank to mount the root
      url: oss-cn-hangzhou-internal.aliyuncs.com  # Internal endpoint (same region); use public endpoint for cross-region
      otherOpts: "-o close_to_open=false"  # false (default): cache metadata for better small-file read performance
                                           # true: fetch fresh metadata on every file open (higher latency)

Parâmetros em nodePublishSecretRef:

Parâmetro	Obrigatório	Descrição
`name`	Sim	Nome do Secret que armazena o par de AccessKey.
`namespace`	Sim	Namespace onde o Secret está localizado.

Parâmetros em volumeAttributes: iguais aos do Método 1, Etapa 3, exceto que authType e roleName não são usados.

Aplique o manifesto.
```
kubectl create -f ossfs2-pv-ak.yaml
```

Verifique se o PV está disponível.

kubectl get pv pv-ossfs2

Saída esperada:

NAME        CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS   VOLUMEATTRIBUTESCLASS   REASON   AGE
pv-ossfs2   20Gi       ROX            Retain           Available                          <unset>                          15s

Etapa 3: Criar um PVC

Crie o arquivo ossfs2-pvc-static.yaml.

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: pvc-ossfs2
  namespace: default
spec:
  accessModes:
    - ReadOnlyMany
  resources:
    requests:
      storage: 20Gi
  volumeName: pv-ossfs2

Crie o PVC.

kubectl create -f ossfs2-pvc-static.yaml

Verifique se o PVC está vinculado.

kubectl get pvc pvc-ossfs2

Saída esperada:

NAME         STATUS   VOLUME      CAPACITY   ACCESS MODES   STORAGECLASS   VOLUMEATTRIBUTESCLASS   AGE
pvc-ossfs2   Bound    pv-ossfs2   20Gi       ROX                           <unset>                 6s

Etapa 4: Implantar uma aplicação

Siga as mesmas etapas do Método 1, Etapa 5.

Aplicação em produção

Categoria	Recomendação
Segurança	Utilize RRSA para todas as cargas de trabalho de produção. Ele fornece credenciais temporárias com rotação automática via OIDC e STS, permitindo isolamento granular de permissões no nível do Pod.
Menor privilégio	Conceda apenas as permissões necessárias à aplicação — somente leitura ou leitura e escrita — restritas ao bucket específico.
Endpoint	Prefira um endpoint interno quando o cluster e o bucket estiverem na mesma região para evitar custos de transferência de dados pela rede pública e reduzir a latência.
Opções de montagem	Utilize `-o close_to_open=false` (padrão) para armazenar metadados em cache e reduzir a latência na leitura de arquivos pequenos. Mude para `-o close_to_open=true` apenas quando os Pods precisarem visualizar atualizações de outro gravador imediatamente.
Adequação da carga	O ossfs 2.0 é adequado para treinamento de IA, inferência, processamento de big data e direção autônoma. Não é recomendado para cargas que exigem escritas aleatórias, como bancos de dados ou ferramentas de edição colaborativa.
Uploads incompletos	Configure uma regra de ciclo de vida no bucket para excluir automaticamente partes incompletas de uploads multipart, evitando custos desnecessários de armazenamento.
Verificações de integridade	Configure um liveness probe em cada Pod para verificar a disponibilidade do ponto de montagem. Se a montagem falhar, o Kubernetes reinicia o Pod e aciona uma nova montagem.
Monitoramento	Utilize o monitoramento de armazenamento de contêineres para acompanhar o desempenho do volume e configurar alertas para identificar problemas antecipadamente.

Container Service for Kubernetes:Mount a static OSS persistent volume by using ossfs 2.0 in an ACK cluster

Como funciona

Observações de uso

Método 1: Autenticar usando RRSA (recomendado)

Pré-requisitos

Etapa 1: Criar uma função RAM

Etapa 2: Conceder permissões à função RAM

Etapa 3: Criar um PV

Etapa 4: Criar um PVC

Etapa 5: Implantar uma aplicação

Método 2: Autenticar usando um AccessKey

Pré-requisitos

Etapa 1: Criar um usuário RAM e armazenar o AccessKey

Etapa 2: Criar um PV

Etapa 3: Criar um PVC

Etapa 4: Implantar uma aplicação

Aplicação em produção

FAQ

Referências