Todos os produtos
Search

Este produto

    Container Service for Kubernetes:Import KMS service credentials with csi-secrets-store-provider-alibabacloud

    Central de documentação

    Container Service for Kubernetes:Import KMS service credentials with csi-secrets-store-provider-alibabacloud

    Última atualização: Sep 21, 2026

    O add-on csi-secrets-store-provider-alibabacloud oferece uma maneira segura de consumir credenciais do Key Management Service (KMS) em cargas de trabalho do Kubernetes. Permite montar secrets diretamente como volumes inline do CSI ou sincronizá-los como Secrets nativos do Kubernetes. Além disso, suporta a rotação automática de secrets para minimizar a exposição de credenciais e simplifica a integração entre suas aplicações e o KMS Secrets Manager.

    image

    Considerações de segurança

    Por padrão, cargas de trabalho que leem secrets diretamente do sistema de arquivos podem enfrentar problemas de compatibilidade ao interagir com o KMS Secrets Manager. O csi-secrets-store-provider-alibabacloud resolve esses problemas de compatibilidade e permite sincronizar secrets como objetos Secret do Kubernetes para injeção de variáveis de ambiente. Avalie os seguintes riscos de segurança antes de prosseguir:

    • Travessia do sistema de arquivos: Secrets montados por meio do sistema de arquivos podem ficar expostos se aplicações vulneráveis forem exploradas em ataques de travessia de diretórios.

    • Exposição em depuração e logs: Breakpoints de depuração mal configurados ou acesso a logs com permissões excessivas podem causar o vazamento de Secrets. Referenciar Secrets por meio de variáveis de ambiente é inseguro e não é recomendado.

    • Permissões excessivas: Aplique o princípio do menor privilégio ao conceder acesso ao KMS para o ack-secret-manager.

    Se sua aplicação não precisar persistir secrets localmente, conceda permissões mínimas aos pods usando RRSA e chame GetSecretValue diretamente da aplicação. Essa abordagem evita completamente a exposição de secrets no sistema de arquivos do pod ou em Secrets do Kubernetes.

    Pré-requisitos

    Etapa 1: configure a autenticação do add-on

    configure a autenticação para o csi-secrets-store-provider-alibabacloud e conceda permissão para recuperar secrets do KMS. Caso contrário, o add-on não poderá importar ou sincronizar credenciais para o cluster. escolha um dos seguintes métodos de autorização com base no tipo do seu cluster:

    Autorizar usando RRSA

    Em comparação com outros métodos, o RRSA fornece isolamento de permissões no nível do pod e evita o risco de vazamento de credenciais causado pelo hardcoding de AccessKey IDs e AccessKey secrets.

    1. Enable the RRSA feature for your cluster no ACK console. O RRSA usa as informações do provedor de identidade especificadas durante a criação do cluster .

    2. Create a RAM role with an OIDC identity provider as the trusted entity. configure os parâmetros com base na tabela a seguir:

      Parâmetro

      Descrição

      IdP Type

      selecione OIDC.

      Identity Provider

      selecione ack-rrsa-<cluster_id>. Substitua <cluster_id> pelo ID do seu cluster.

      Condition

      • oidc:iss: Mantenha o valor padrão.

      • oidc:aud: Mantenha o valor padrão.

      • oidc:sub: Adicione esta condição manualmente.

        • Key: selecione oidc:sub.

        • Operator: selecione StringEquals.

        • Value: Insira system:serviceaccount:<namespace>:<serviceAccountName>. Substitua <namespace> pelo namespace da aplicação e <serviceAccountName> pelo nome da conta de serviço. Para este tópico, use system:serviceaccount:kube-system:csi-secrets-store-provider-alibabacloud.

          Nota

          Recomendamos que você instale o add-on no namespace padrão kube-system. Se a instalação ocorrer em um namespace diferente, substitua kube-system pelo seu namespace de destino.

    3. crie uma política personalizada e anexe-a à função RAM criada na etapa anterior.

      1. Create a custom policy para que o csi-secrets-store-provider-alibabacloud importe credenciais do KMS. Conteúdo da política:

        {
    "Action": [
       "kms:GetSecretValue",
       "kms:Decrypt"
    ],
    "Resource": [
        "*"
    ],
    "Effect": "Allow"
}

      2. Anexe a política à função RAM da etapa anterior. Consulte Manage permissions for a RAM role.

    4. crie um Kubernetes Secret chamado alibaba-credentials no cluster.

      1. crie um arquivo chamado secretstore-rrsa.yaml com o seguinte conteúdo. Substitua os marcadores de posição pelos seus valores reais.

        • {rolearn}: ARN codificado em Base64 da função RAM criada em step 2.

        • {oidcproviderarn}: ARN codificado em Base64 do provedor OIDC gerado após a ativação do RRSA.

        apiVersion: v1
data:
  rolearn: {rolearn}
  oidcproviderarn: {oidcproviderarn}
kind: Secret
metadata:
  name: alibaba-credentials
  namespace: kube-system
type: Opaque

      2. Implante o Kubernetes Secret:

        kubectl apply -f secretstore-rrsa.yaml

    Conceder permissões à função RAM do worker

    1. Create a custom policy. Conteúdo da política:

      {
  "Action": [
    "kms:GetSecretValue",
    "kms:Decrypt"
  ],
  "Resource": [
    "*"
  ],
  "Effect": "Allow"
}

    2. Attach the custom policy to the worker RAM role.

    configure credenciais AccessKey

    1. Create a RAM role with its trusted entity set as your current Alibaba Cloud account.

      Nota

      Para a entidade de confiança, selecione Current Account.

    2. crie uma política personalizada e conceda permissões à função RAM criada na etapa anterior.

      1. Create a custom policy para acesso a credenciais do KMS. Conteúdo da política:

        {
  "Action": [
    "kms:GetSecretValue",
    "kms:Decrypt"
  ],
  "Resource": [
    "*"
  ],
  "Effect": "Allow"
}

      2. Conceda permissões à função RAM da etapa anterior. Consulte Manage permissions for a RAM role.

    3. crie uma política personalizada para assumir a função anterior e anexe-a a um usuário RAM.

      1. Create a custom policy para assumir a função. Conteúdo da política:

        {
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Resource": "acs:ram:*:<account-id>:role/<role-name>" 
        }
    ],
    "Version": "1"
}

        Nesta política personalizada, o elemento Resource especifica o role ARN, onde <ACCOUNT_ID> é o ID da conta Alibaba Cloud e <ROLE_NAME> é o nome da função RAM.

      2. Conceder a política personalizada a um usuário RAM permite que você especifique quais funções RAM ele pode assumir. Para mais informações, consulte Manage RAM user permissions.

    4. crie um Kubernetes Secret chamado alibaba-credentials no cluster.

      1. crie um arquivo chamado alibaba-credentials.yaml com o seguinte conteúdo. Substitua os marcadores de posição pelos seus valores reais.

        • {rolearn}: ARN codificado em Base64 da função RAM de step 1.

        • {ak}: AccessKey ID codificado em Base64 do usuário RAM.

        • {sk} : AccessKey secret codificado em Base64 do usuário RAM.

          apiVersion: v1
data:
  id: {ak}
  secret: {sk}
  rolearn: {rolearn}
kind: Secret
metadata:
  name: alibaba-credentials
  namespace: kube-system
type: Opaque

      2. Implante o Kubernetes Secret.

        kubectl apply -f alibaba-credentials.yaml

    Etapa 2: instale o csi-secrets-store-provider-alibabacloud

    1. Acesse o ACK console. No painel de navegação à esquerda, clique em Clusters.

    2. Na página Clusters, clique em nome do seu cluster. No painel de navegação à esquerda, clique em Applications > Helm.

    3. Na página Helm, clique em Deploy. Pesquise por csi-secrets-store-provider-alibabacloud e selecione-o. Mantenha as configurações padrão e clique em Next.

      Na caixa de diálogo, confirme a instalação do chart, que será instalado no namespace kube-system por padrão. Clique em Yes para prosseguir. Para usar um namespace personalizado, configure Application Name e Namespace na etapa Basic Information.

    4. selecione a Chart Version mais recente. Na seção Parameters, configure os parâmetros com base no método de autenticação de step 1. Em seguida, clique em OK.

      • Se você seguiu o procedimento em Authorize using RRSA, defina rrsa.enable como true.image

        Outros parâmetros:

        envVarsFromSecret:
#  ACCESS_KEY_ID:
#    secretKeyRef: alibaba-credentials
#    key: id
#  SECRET_ACCESS_KEY:
#    secretKeyRef: alibaba-credentials
#    key: secret
  ALICLOUD_ROLE_ARN:
    secretKeyRef: alibaba-credentials
    key: rolearn
#  ALICLOUD_ROLE_SESSION_NAME:
#    secretKeyRef: alibaba-credentials
#    key: rolesessionname
#  ALICLOUD_ROLE_SESSION_EXPIRATION:
#    secretKeyRef: alibaba-credentials
#   key: rolesessionexpiration
  ALICLOUD_OIDC_PROVIDER_ARN:
    secretKeyRef: alibaba-credentials
    key: oidcproviderarn

      • Se você seguiu o procedimento em Grant permissions to the worker RAM role, use as configurações padrão.

      • Se você seguiu o procedimento em Configure AccessKey credentials to assume a RAM role, configure os seguintes parâmetros:

        envVarsFromSecret:
  ACCESS_KEY_ID:
    secretKeyRef: alibaba-credentials
    key: id
  SECRET_ACCESS_KEY:
    secretKeyRef: alibaba-credentials
    key: secret
  ALICLOUD_ROLE_ARN:
    secretKeyRef: alibaba-credentials
    key: rolearn
#  ALICLOUD_ROLE_SESSION_NAME:
#    secretKeyRef: alibaba-credentials
#    key: rolesessionname
#  ALICLOUD_ROLE_SESSION_EXPIRATION:
#    secretKeyRef: alibaba-credentials
#    key: rolesessionexpiration
#  ALICLOUD_OIDC_PROVIDER_ARN:
#    secretKeyRef: alibaba-credentials
#    key: oidcproviderarn

      • ative a sincronização de Secrets para Secrets nativos do Kubernetes, defina syncSecret.enabled como true para implantar a Role e o RoleBinding do RBAC necessários.

        syncSecret:
  enabled: true

      • ative a rotação automática de secrets, configure os seguintes parâmetros:image

        • secrets-store-csi-driver.enableSecretRotation: ative a rotação automática de secrets. defina como true.

        • secrets-store-csi-driver.rotationPollInterval: Intervalo de sincronização de secrets. Exemplo: 120s sincroniza a cada dois minutos. Ajuste conforme necessário.

      Após a implantação, você será redirecionado para a página csi-secrets-store-provider-alibabacloud. verifique se todos os recursos foram criados. Na seção Resource, verifique se os seguintes recursos do Kubernetes foram criados:

      • ServiceAccount: secrets-store-csi-driver e csi-secrets-store-provider-alibabacloud

      • ClusterRole: secretproviderclasses-admin-role, secretproviderclasses-viewer-role e secretproviderclasses-role

      • ClusterRoleBinding: secretproviderclasses-rolebinding

      • DaemonSet: secrets-store-csi-driver e csi-secrets-store-provider-alibabacloud

      • CSIDriver: secrets-store.csi.k8s.io image.png

    Etapa 3: configure a sincronização de secrets

    Após configurar a autenticação, use uma SecretProviderClass para especificar as credenciais do KMS a serem importadas.

    Modelo

    apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: <NAME>
spec:
  provider: alibabacloud   # This value is fixed to 'alibabacloud'.
  parameters:
    objects: |
      - objectName: <KMS Encryption Parameter Name> # Name of the KMS credential.
        objectType: kms # Fixed to kms when synchronizing KMS credentials.

    O campo parameters aceita as seguintes configurações:

    Parâmetro

    Obrigatório

    Descrição

    objects

    Sim

    Especifica os secrets a serem montados como um array YAML. Exemplo:

    parameters:
  objects: |
    - objectName: "MySecret"
      objectType: "kms"

    O parâmetro objects contém os seguintes subcampos:

    • objectName (obrigatório): O SecretName no KMS Secrets Manager.

    • objectType (opcional): Tipo de service Alibaba Cloud. Valores válidos: kms e oos. Padrão: kms.

    • objectAlias (opcional): Nome do arquivo para a credencial montada no pod. O padrão é objectName.

    • objectVersion (opcional): Mapeia para o parâmetro VersionId no KMS Secrets Manager. Não há suporte para credenciais RDS, PolarDB, Redis/Tair, RAM e ECS.

    • objectVersionLabel (opcional): Mapeia para o parâmetro VersionStage no KMS Secrets Manager. Para credenciais RDS, PolarDB, Redis/Tair, RAM e ECS, apenas as versões ACSPrevious e ACSCurrent podem ser recuperadas.

    • jmesPath (opcional): Analisa pares chave-valor específicos de uma credencial formatada em JSON. Exemplo: a credencial test contém:

      {
        "username": "testuser",
        "password": "testpassword"
    }

      Para montar username e password como arquivos separados, use a seguinte configuração JMESPath. O campo jmesPath requer dois subcampos:

      • path (obrigatório): A expressão JMESPath para extrair o valor de destino.

      • objectAlias (obrigatório): Nome do arquivo para o par chave-valor montado.

    • kmsEndpoint (opcional): Endpoint de solicitação do KMS. O padrão é o endpoint padrão. Suporta gateways compartilhados ou dedicados, configuráveis por credencial. Consulte kmsEndpoint configuration.

    region

    Opcional

    A região do KMS Secrets Manager. O padrão é a região do nó, o que pode adicionar sobrecarga de desempenho em implantações em grande escala. Recomenda-se que você especifique uma região.

    pathTranslation

    Opcional

    • Se um secret no KMS Secrets Manager contiver separadores de caminho, o arquivo de secret montado no pod usará o caractere especificado por este parâmetro como separador. Por exemplo, My/Path/Secret no KMS Secrets Manager é montado como um arquivo de secret chamado My_Path_Secret.

    • Se este parâmetro não for especificado, um underscore (_) será usado como separador padrão.

    • Se este parâmetro for definido como False, nenhum separador será usado no nome do arquivo montado.

    Exemplo de uso

    Use uma SecretProviderClass para importar uma credencial do KMS chamada test da mesma região de um ACK managed cluster para uma carga de trabalho.

    1. crie um arquivo chamado secretstore.yaml com o seguinte conteúdo.

      apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: test-secrets
spec:
  provider: alibabacloud   # This value is fixed to alibabacloud.
  parameters:
    objects: | # objectType supports oos and kms. The default is kms.
      - objectName: "test-hangzhou"
        objectType: "kms"
        objectAlias: "hangzhou-public"
        kmsEndpoint:  "kms.{region}.aliyuncs.com"

    2. Implante a SecretProviderClass.

      kubectl apply -f secretstore.yaml

    3. crie um arquivo chamado deploy.yaml com o seguinte conteúdo.

      Este Deployment do NGINX monta credenciais da SecretProviderClass anterior usando um volume inline CSI em /mnt/secrets-store (Exemplos de Deployment).

      apiVersion: apps/v1  # For versions earlier than 1.8.0, use apps/v1beta1.
kind: Deployment
metadata:
  name: nginx-deployment-basic
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      volumes:
        - name: secrets-store-inline
          csi:
            driver: secrets-store.csi.k8s.io
            readOnly: true
            volumeAttributes:
              secretProviderClass: "test-secrets"
      containers:
        - name: nginx
          image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6 # Replace with your actual image.
          ports:
            - containerPort: 80
          resources:
            limits:
              cpu: "500m"
          volumeMounts:
            - name: secrets-store-inline
              mountPath: "/mnt/secrets-store"
              readOnly: true

    4. Implante a aplicação.

      kubectl apply -f deploy.yaml

    5. verifique se o secret foi montado corretamente.

      Acesse o pod e verifique se existe um arquivo correspondente ao nome do secret em /mnt/secrets-store cujo conteúdo corresponda à credencial do KMS.

    Sincronizar credenciais do KMS para Secrets do Kubernetes

    O Secrets Store CSI Driver permite a sincronização automática de secrets recuperados de services externos onde você gerencie secrets (como KMS e OOS) e os cria como Secrets nativos do Kubernetes no cluster. As aplicações podem usar esses secrets externos da maneira padrão do Kubernetes sem que você modifique o código.

    configure: SecretProviderClass

    Adicione o campo opcional secretObjects ao spec de um recurso SecretProviderClass para ativar essa funcionalidade.

    apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: <NAME>
spec:
  provider: alibabacloud   # This value is fixed to alibabacloud. Do not modify.
  parameters:
    objects: |
      - objectName: <KMS Encryption Parameter Name>  # Name of the KMS credential.
        objectType: kms     # Fixed to kms when synchronizing KMS credentials.
  secretObjects:
  - secretName: <Kubernetes Secret Name>            # Name of the Kubernetes Secret.
    type: <Kubernetes Secret Type>                  # Type of the Kubernetes Secret.
    data:
    - objectName: <parameters.objects.objectName>   # The name from parameters.objects.objectName. Use the alias if specified.
      key: <Kubernetes Secret Data Key>             # The key name in the Kubernetes Secret data.

    O secretObjects geralmente inclui os três parâmetros a seguir:

    Parâmetro

    Tipo

    Descrição

    secretName

    Obrigatório

    O nome do Kubernetes Secret a ser criado.

    type

    Obrigatório

    O tipo do Secret. Valores válidos: Opaque, kubernetes.io/basic-auth, bootstrap.kubernetes.io/token, kubernetes.io/dockerconfigjson , kubernetes.io/dockercfg, kubernetes.io/ssh-auth, kubernetes.io/service-account-token ou kubernetes.io/tls.

    data

    Obrigatório

    Define como mapear um secret externo para o campo data de um Secret. Seus subcampos incluem:

    • objectName: Obrigatório. O nome do secret (objectName) definido em parameters.objects. Caso um alias esteja definido, especifique o objectAlias correspondente.

    • key: Obrigatório. Especifica a chave para os dados do secret no campo data do Secret.

    Ciclo de vida da sincronização

    A sincronização e a limpeza de um objeto Secret são acionadas dinamicamente por um Pod que monta a SecretProviderClass correspondente:

    • Criação: O Kubernetes Secret é criado apenas quando o primeiro Pod que usa a SecretProviderClass é iniciado e monta o volume.

    • atualize: Quando secrets-store-csi-driver.enableSecretRotation é true, o Kubernetes Secret é atualizado periodicamente no intervalo secrets-store-csi-driver.rotationPollInterval. Caso contrário, não o atualize.

    • Exclusão: Quando o último Pod que usa a SecretProviderClass é excluído, o Kubernetes Secret correspondente também é excluído.

    Exemplo: Sincronizar e injetar credenciais

    Sincronize uma credencial do KMS para um Kubernetes Secret e injete-a como uma variável de ambiente em um pod NGINX.

    1. crie uma SecretProviderClass.

      crie um arquivo chamado syncSecret.yaml com o seguinte conteúdo.

      apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: alibabacloud-sync-secret
spec:
  provider: alibabacloud
  parameters:
    objects: |
      - objectName: test-kms
        objectAlias: secretalias
        objectType: kms
  secretObjects:
  - secretName: test-sync-secret  # Name of the generated Kubernetes Secret.
    type: Opaque
    data:
    - objectName: secretalias     # Corresponds to objectName or objectAlias.
      key: test                   # Populates the data key of the generated Kubernetes Secret.

    2. Implante a SecretProviderClass.

      kubectl apply -f syncSecret.yaml

    3. crie um pod de aplicação para acionar a sincronização.

      crie um arquivo pod-sync-secret.yaml com o seguinte conteúdo. Este pod monta a SecretProviderClass anterior e tenta usar secretKeyRef para referenciar o Secret chamado test-sync-secret a ser gerado.

      kind: Pod
apiVersion: v1
metadata:
  name: pod-sync-secret
spec:
  containers:
    - name: nginx
      image: nginx:latest
      volumeMounts:
      - name: secrets-store-inline
        mountPath: "/mnt/secrets-store"
        readOnly: true
      env:  
      - name: SECRET_TEST
        valueFrom:
          secretKeyRef:
            name: test-sync-secret
            key: test
  volumes:
    - name: secrets-store-inline
      csi:
        driver: secrets-store.csi.k8s.io
        readOnly: true
        volumeAttributes:
          secretProviderClass: "alibabacloud-sync-secret"

    4. Implante o pod para acionar a sincronização.

      kubectl apply -f pod-sync-secret.yaml

    5. verifique o resultado.

      1. verifique se o Kubernetes Secret foi criado.

        kubectl get secret test-sync-secret

        A saída exibe o Kubernetes Secret test-sync-secret.

      2. verifique se a variável de ambiente foi injetada no pod.

        kubectl exec -it $(kubectl get pods | awk '/pod-sync-secret/{print $1}' | head -1) -- env

        A saída inclui SECRET_TEST com um valor correspondente ao secret do KMS.

    configure o kmsEndpoint

    configure o endpoint do KMS para um gateway dedicado ou compartilhado (consulte Differences between shared and dedicated gateways).

    Endereços dos endpoints do KMS

    Tipo de gateway

    Tipo de domínio

    Endereço do endpoint

    Descrição

    Gateway dedicado

    KMS privado

    {kms-instance-id}.cryptoservice.kms.aliyuncs.com

    • A instância do KMS e o cluster devem estar na mesma região e VPC.

    • Substitua {kms-instance-id} pelo ID da instância do KMS que contém a credencial.

    • A instância do KMS deve ser da versão 3.0 ou posterior.

    Gateway compartilhado

    VPC

    kms-vpc.{region}.aliyuncs.com

    • A credencial do KMS e o cluster devem estar na mesma região.

    • Substitua {region} pela região onde a credencial do KMS está localizada.

    • Esta é a configuração padrão e não exige configurações adicionais.

    Gateway compartilhado

    Público

    kms.{region}.aliyuncs.com

    • Substitua {region} pela região onde a credencial do KMS está localizada.

    • O cluster deve ter acesso à rede pública.

    Exemplo de configuração do endpoint do KMS

    apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: test
spec:
  provider: alibabacloud # Fixed to 'alibabacloud'
  parameters:
    # Gateway usage examples:
    # hangzhou-public uses the public endpoint of a shared gateway. Replace {region} with the region where the KMS credential is located. This method allows you to access KMS credentials from a different region than the cluster.
    # hangzhou-vpc does not specify a kmsEndpoint field and uses the default VPC endpoint of a shared gateway.
    # hangzhou-cryptoservice uses a dedicated gateway. Replace {kms-instance-id} with the ID of the KMS instance.
    # london-public uses the public endpoint of a shared gateway. Replace {region} with the region where the KMS credential is located. This method allows you to access KMS credentials from a different region than the cluster.
    objects: |
      - objectName: "test-hangzhou"
        objectType: "kms"
        objectAlias: "hangzhou-public"
        kmsEndpoint:  "kms.{region}.aliyuncs.com"
      - objectName: "test-hangzhou"
        objectType: "kms"
        objectAlias: "hangzhou-vpc"
      - objectName: "test-hangzhou"
        objectType: "kms"
        objectAlias: "hangzhou-cryptoservice"
        kmsEndpoint:  "{kms-instance-id}.cryptoservice.kms.aliyuncs.com"
      - objectName: "test-london"
        objectAlias: "london-public"
        kmsEndpoint:  "kms.{region}.aliyuncs.com"

    Referências