Key Management Service:Quick access from ACK

Etapa 1: Crie um namespace e uma conta de serviço (opcional)

Um namespace particiona o seu cluster do ACK em espaços virtuais logicamente isolados para diferentes ambientes, como desenvolvimento, testes e produção. Por padrão, as aplicações em namespaces diferentes não acessam os recursos umas das outras. Se você já tiver um namespace e uma conta de serviço para a sua aplicação, pule esta etapa.

1. Crie um namespace.

   1. Crie um namespace usando um arquivo YAML. O exemplo a seguir usa app1-namespace.yaml para criar um namespace chamado app1-dev:

      apiVersion: v1
      kind: Namespace
      metadata:
        name: app1-dev

   2. Execute o seguinte comando para criar o namespace:

      kubectl apply -f app1-namespace.yaml

   3. Verifique se o namespace foi criado. Se a saída incluir app1-dev, a criação do namespace foi bem-sucedida.

      kubectl get namespaces

2. Crie uma conta de serviço.

   1. Crie uma conta de serviço usando um arquivo YAML. O exemplo a seguir usa app1-serviceaccount.yaml para criar uma conta de serviço chamada app1-service no namespace app1-dev que você criou na etapa anterior:

      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: app1-service
        namespace: app1-dev

   2. Execute o seguinte comando para criar a conta de serviço:

      kubectl apply -f app1-serviceaccount.yaml

   3. Verifique se a conta de serviço foi criada. Se a saída incluir app1-service, a criação da conta de serviço foi bem-sucedida.

      kubectl get serviceaccount -n app1-dev

Etapa 2: Configure as permissões

O acesso cloud-native do KMS suporta os dois métodos de autenticação a seguir.

Etapa 3: Instale o ack-kms-agent-webhook-injector

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

2. Na página Clusters, clique no nome do cluster de destino para acessar a página de detalhes.

3. No painel de navegação à esquerda da página de detalhes, escolha Applications > Helm.

4. Na página Helm, clique em Deploy. Configure a seção Basic Information e, em seguida, clique em Next.

   Parâmetro	Descrição
   Application Name	Use o nome padrão da aplicação ack-kms-agent-webhook-injector.
   Namespace	Use o namespace padrão do chart kube-system. Instale em apenas um namespace por cluster do ACK; evite instalar várias vezes.
   Source	Padrão: Marketplace. Este parâmetro não pode ser modificado.
   Chart	Pesquise e selecione ack-kms-agent-webhook-injector.

5. Quando a caixa de diálogo de confirmação for exibida, verifique as informações e clique em Yes.

6. Na página Parameters, configure os parâmetros com base no método de autenticação selecionado na Etapa 2.

   • OIDC (ACK): Mantenha a configuração padrão.

   • Função do RAM: Deixe agent.auth.roleArn vazio e defina agent.auth.roleArnMapping como <Namespace>:<ServiceAccountName>:<RAM Role ARN>. O exemplo a seguir usa os dados criados na Etapa 2:

     Nota

     O Namespace e o ServiceAccountName correspondem ao namespace and service account do pod que executa a carga de trabalho. O RAM Role ARN está disponível na página de detalhes da função do RAM.

     agent:
       auth:
         roleArn:
         roleArnMapping:
           app1-dev:app1-service: acs:ram::190325303126****:role/app1-rrsa

7. Após concluir a configuração, clique em OK. O sistema redireciona você para a página de detalhes da aplicação.

Etapa 4: Injete o Sidecar do Agent

1. Adicione uma anotação de pod: Defina a chave da anotação como kms-agent-webhook-injector/inject e o valor como true.

   1. No painel de navegação à esquerda da página de detalhes do cluster, escolha Workloads > Deployments.

   2. Alterne para o namespace onde a sua carga de trabalho é executada e adicione a anotação de pod ao Deployment.

      Importante

      Para o método de autenticação de função do RAM, modifique a configuração YAML do Deployment e defina o parâmetro ServiceAccountName como o service account name do pod que executa a carga de trabalho (por exemplo, app1-service). Para o método de autenticação OIDC (ACK), não é necessária nenhuma modificação.

      • Crie um novo Deployment

        Create from Image

        1. Clique em Create from Image acima da lista de Deployments e configure os parâmetros.

        2. Ao configurar Advanced, vá para a seção Labels and Annotations e adicione a anotação de pod: insira kms-agent-webhook-injector/inject na coluna Name e true na coluna Value.

        3. Clique em Create para concluir.

        Create from YAML

        1. Clique em Create from YAML acima da lista de Deployments.

        2. Edite o arquivo YAML e adicione kms-agent-webhook-injector/inject: "true" em spec.template.metadata.annotations (crie esta seção se ela não existir).

        3. Clique em Create para concluir.

      • Modifique um Deployment existente

        1. Encontre a carga de trabalho de destino e clique em Actions > Details.

        2. Na página de detalhes, clique em Edit YAML no canto superior direito.

        3. Adicione kms-agent-webhook-injector/inject: "true" em spec.template.metadata.annotations (crie esta seção se ela não existir).

        4. Clique em Update e aguarde até que a carga de trabalho esteja pronta.

2. Verifique a injeção

   1. Volte para Workloads > Deployments e clique no nome do Deployment de destino para acessar a página de detalhes.

   2. Na aba Pods, verifique a coluna Image. O KMS Agent aparece injetado no pod como um Sidecar.

      Nota

      Um pod pode receber a injeção do KMS Agent duas vezes. Isso acontece porque o sistema usa um contêiner de inicialização (init container). O contêiner de inicialização é finalizado (Terminated) após a conclusão do processo e não impacta negativamente a aplicação nem consome recursos de computação continuamente.

Integração da aplicação

Depois que o seu Deployment recebe a injeção do KMS Agent, o contêiner da aplicação pode recuperar credenciais do KMS por meio de requisições HTTP para o KMS Agent. Não é necessário configurar nenhuma AccessKey no seu código. Os exemplos a seguir demonstram como recuperar credenciais. Substitua <SecretId> pelo nome real da sua credencial.

Importante

• O KMS Agent escuta apenas em 127.0.0.1, ou seja, apenas aplicações ou processos na mesma máquina podem se comunicar com ele. Dispositivos de rede externos não conseguem se conectar. O endereço de acesso suporta apenas localhost ou 127.0.0.1, e não o IP local da aplicação. Os exemplos a seguir usam localhost.

• Além do método de acesso do KMS Agent, o KMS também suporta acesso via SDK. Para operações específicas, consulte Secrets Manager Client.

OIDC (ACK)

Usando curl

• Execute o seguinte comando para recuperar uma credencial:

  # Read token from file, specify AapArn
  curl -v -H "X-KMS-Token:$(</var/run/kmstoken/token)"
  -H "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

• A sintaxe $(<file) tem suporte apenas em shells como bash e zsh. Se a imagem base do seu Pod usar Alpine (cujo shell padrão é o BusyBox ash) ou qualquer outra imagem cujo shell padrão não ofereça suporte a esta sintaxe, use o seguinte comando:

  # Read token from file, specify AapArn (Alpine/BusyBox compatible)
  curl -v -H "X-KMS-Token:$(cat /var/run/kmstoken/token)"
  -H "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

Usando wget

• Execute o seguinte comando para recuperar uma credencial:

  # Read token from file, specify AapArn
  wget -q -O - --header "X-KMS-Token:$(</var/run/kmstoken/token)" --header "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

• A sintaxe $(<file) tem suporte apenas em shells como bash e zsh. Se a imagem base do seu Pod usar Alpine (cujo shell padrão é o ash) ou qualquer outra imagem cujo shell padrão não ofereça suporte a esta sintaxe, use o seguinte comando:

  # Read token from file, specify AapArn (Alpine compatible)
  wget -q -O - --header "X-KMS-Token:$(cat /var/run/kmstoken/token)" --header "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

Exemplo de código Go

O exemplo a seguir demonstra como recuperar uma credencial usando Go:

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {

    // You can specify versionStage or versionId to retrieve a specific credential version.
    // The following example retrieves a credential by versionId:
    // url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s&versionId=%s", "agent-test", "version-id")
    aapArn := "acs:kms:cn-hangzhou:19*********224:applicationaccesspoint/****"
    url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test")

    token, err := ioutil.ReadFile("/var/run/kmstoken/token")
    if err != nil {
        fmt.Printf("error reading token file: %v\n", err)
    }

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        fmt.Printf("error creating request: %v\n", err)
    }

    req.Header.Add("X-KMS-Token", string(token))
    req.Header.Add("AapArn", aapArn)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("error sending request: %v \n", err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Printf("status code %d - %s \n", resp.StatusCode, string(body))
}

Função do RAM

Usando curl

• Execute o seguinte comando para recuperar uma credencial:

  # Read token from file
  curl -v -H "X-KMS-Token:$(</var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
  
  # Or write the token directly
  curl -v -H "X-KMS-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

• A sintaxe $(<file) tem suporte apenas em shells como bash e zsh. Se a imagem base do seu Pod usar Alpine (cujo shell padrão é o BusyBox ash) ou qualquer outra imagem cujo shell padrão não ofereça suporte a esta sintaxe, use o seguinte comando:

  # Read token from file (Alpine/BusyBox compatible)
  curl -v -H "X-KMS-Token:$(cat /var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

Usando wget

• Execute o seguinte comando para recuperar uma credencial:

  # Read token from file
  wget -q -O - --header "X-KMS-Token:$(</var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
  
  # Or write the token directly
  wget -q -O - --header "X-KMS-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

• A sintaxe $(<file) tem suporte apenas em shells como bash e zsh. Se a imagem base do seu Pod usar Alpine (cujo shell padrão é o ash) ou qualquer outra imagem cujo shell padrão não ofereça suporte a esta sintaxe, use o seguinte comando:

  # Read token from file (Alpine compatible)
  wget -q -O - --header "X-KMS-Token:$(cat /var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

Exemplo de código Go

O exemplo a seguir demonstra como recuperar uma credencial usando Go:

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {

    // You can specify versionStage or versionId to retrieve a specific credential version.
    // The following example retrieves a credential by versionId:
    // url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s&versionId=%s", "agent-test", "version-id")
    url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test")

    token, err := ioutil.ReadFile("/var/run/kmstoken/token")
    if err != nil {
        fmt.Printf("error reading token file: %v\n", err)
    }

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        fmt.Printf("error creating request: %v\n", err)
    }

    req.Header.Add("X-KMS-Token", string(token))

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("error sending request: %v \n", err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Printf("status code %d - %s \n", resp.StatusCode, string(body))
}

Faturamento

• Custos do lado do KMS:

  • Assinatura: Adquira uma instância do KMS antes de usar o KMS Agent. O próprio KMS Agent não incorre em cobranças adicionais. Para mais informações, consulte Subscription.

  • Pagamento conforme o uso: Além das cobranças já incorridas, há cobrança adicional de QPS quando o KMS Agent recupera credenciais por meio de chamadas de API. Para mais informações, consulte Pay-as-you-go.

• Custos do lado do ACK:

  O componente ack-kms-agent-webhook-injector é gratuito. Podem ocorrer custos adicionais com recursos de computação consumidos pelas cargas de trabalho de Sidecar e Webhook injetadas.

  • Após instalar o componente ack-kms-agent-webhook-injector, o sistema gera uma carga de trabalho de serviço Webhook, que consome recursos de computação e gera custos. Limite o uso de CPU e memória dessa carga de trabalho no arquivo de configuração.

  • Quando você cria ou atualiza uma carga de trabalho qualificada, o ack-kms-agent-webhook-injector injeta o KMS Agent como um Sidecar no contêiner. O KMS Agent consome recursos de computação e gera custos.

Solução de problemas

Se você encontrar problemas ao instalar ou usar o KMS Agent, consulte os problemas comuns a seguir para solucioná-los.

Causa	Solução
Falha ao instalar o Agent	Execute kubectl get nodes para verificar se o cluster está no estado Running. Verifique as permissões do KMS do usuário do RAM.
Rede inacessível ou tempo limite esgotado	Certifique-se de que o cluster do ACK alcança o serviço KMS. Se você acessar o KMS por meio de uma VPC, certifique-se de que a VPC onde reside o cluster do ACK está conectada à rede da instância do KMS.
O KMS Agent falha ao obter credenciais temporárias do STS por meio de AssumeRoleWithOIDC.	Solucione o problema da seguinte forma: Verifique se as políticas de saída do cluster do ACK permitem o acesso ao endpoint real do serviço STS ( sts-intl.aliyuncs.com). Teste a acessibilidade ao endpoint de dentro do pod da aplicação. Verifique os logs do contêiner do KMS Agent em busca de falhas ou tempos limite relacionados a AssumeRoleWithOIDC. Nota: Uma leitura bem-sucedida de um valor de segredo em cache não garante que a cadeia de credenciais da função do RAM está íntegra. Verifique os logs para confirmar que AssumeRoleWithOIDC teve êxito.
Permissões insuficientes	Verifique as seguintes configurações: OIDC (ACK): Verifique o namespace e a conta de serviço, e confirme se um filtro PodNamePrefix está configurado. Função do RAM: Verifique se a função do RAM está corretamente anexada ao provedor de identidade e se a política inclui as permissões kms:GetSecretValue e kms:Decrypt.
Falha ao injetar o Agent	Verifique se o componente ack-kms-agent-webhook-injector está instalado corretamente e em execução normal. Confirme se a anotação de pod kms-agent-webhook-injector/inject: "true" está configurada corretamente.
O RRSA não está ativado	O método de autenticação OIDC (ACK) requer o recurso RRSA (RAM Roles for Service Accounts). No console do ACK, acesse o módulo de segurança e auditoria do cluster para ativar o RRSA. Para etapas detalhadas, consulte a configuração do provedor de identidade na aba de função do RAM da Etapa 2.