Como usar secrets e credenciais

Nesta página, explicamos como incluir informações confidenciais, como senhas e chaves de API, no Cloud Build.

Antes de incluir informações confidenciais nas suas versões, é necessário armazená-las no Gerenciador de secrets ou criptografá-las usando o Cloud Key Management Service e incluir apenas as informações criptografadas no Cloud Build. O Gerenciador de secrets é a técnica recomendada para gerenciar dados confidenciais com o Cloud Build. Para projetos existentes, você pode continuar usando o Cloud KMS, mas para novos projetos, use o Gerenciador de secrets.

Antes de começar

Para executar os comandos gcloud descritos nesta página, instale a ferramenta de linha de comando gcloud.

• Se você já instalou o SDK do Cloud anteriormente, verifique se tem a versão mais recente disponível executando gcloud components update.

Como usar o Gerenciador de secrets

O Gerenciador de secrets é um serviço do Google Cloud que armazena com segurança chaves de API, senhas e outros dados confidenciais.

Para armazenar dados no Gerenciador de secrets e usá-los no Cloud Build:

1. Ative a API Secret Manager:

   Ative a API Secret Manager

2. Conceda o papel Secret Accessor do IAM à conta de serviço do Cloud Build:

   1. Abra a página do IAM no Console do Cloud.

      Abra a página do IAM

   2. Selecione o projeto e clique em Abrir.

   3. Na tabela de permissões, localize o e-mail que termina com @cloudbuild.gserviceaccount.com e clique no ícone de lápis.

   4. Adicione o papel Secret Manager Secret Accessor

   5. Clique em Save.

3. Armazene dados no Gerenciador de secrets:

   1. Acesse a página "Gerenciador de secrets" no Console do Cloud:

      Acessar a página "Gerenciador de secrets"

   2. Na página Gerenciador de secrets, clique em Criar secret.

   3. Na página Criar secret, em Nome, digite secret-name.

   4. No campo Valor do secret, insira seus dados.

   5. Deixe a seção Regiões inalterada.

   6. Clique no botão Criar secret.

   Para instruções sobre como usar o Gerenciador de secrets usando a ferramenta de linha de comando gcloud, consulte o Guia de início rápido do Gerenciador de secrets. Para instruções sobre como conceder acesso a um secret específico, consulte como gerenciar o acesso a secrets.

4. No arquivo de configuração da versão, adicione uma etapa de versão para acessar a versão secreta no Gerenciador de secrets e armazená-la em um arquivo. A etapa de versão a seguir acessa secret-name e a armazena em um arquivo chamado decrypted-data.txt:

   YAML

   steps:
   - name: gcr.io/cloud-builders/gcloud
     entrypoint: 'bash'
     args: [ '-c', "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > decrypted-data.txt" ]
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/gcloud",
       "entrypoint": "bash",
       "args": [
         "-c",
         "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > decrypted-data.txt"
       ]
     }
     ]
   }
   

5. Use o arquivo com os dados descriptografados em uma etapa de versão. O snippet de código a seguir usa decrypted-data.txt para fazer login em um registro particular do Docker:

   YAML

   steps:
   - name: gcr.io/cloud-builders/gcloud
     entrypoint: 'bash'
     args: [ '-c', "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > decrypted-data.txt" ]
   - name: gcr.io/cloud-builders/docker
     entrypoint: 'bash'
     args: [ '-c', 'docker login --username=my-user --password-stdin < decrypted-data.txt']
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/gcloud",
       "entrypoint": "bash",
       "args": [
         "-c",
         "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > password.txt"
        ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=my-user --password-stdin < decrypted-data.txt"
        ]
     }
     ]
   }
   

Observação: para usar o secret em uma variável de ambiente, você precisa prefixar o nome da variável com um sublinhado "_" e inserir escape com o valor usando "\('. Por exemplo: _VARIABLE_NAME=$(cat password.txt) && echo -n \)_VARIABLE_NAME.

1. Use o arquivo de configuração de build para iniciar manualmente um build ou para automatizar builds usando acionadores.

Aviso: os usuários que não têm permissão para acessar secrets no Gerenciador de secrets, mas que têm permissão para executar versões, podem executar uma versão que usa informações no Gerenciador de secrets usando o acesso da conta de serviço do Cloud Build. Isso significa que, se a conta de serviço do Cloud Build tiver acesso ao Gerenciador de secrets, qualquer usuário que tenha acesso para criar versões poderá acessar secrets armazenadas no Gerenciador de secrets. Esse acesso é registrado nohistórico da versão do projeto.

Como usar o Cloud KMS

O Cloud KMS é um serviço do Google Cloud que permite gerenciar e usar chaves criptográficas.

Para criptografar dados confidenciais usando o Cloud KMS e usar esses dados em um arquivo de configuração de versão:

1. Ative a API Cloud KMS:

   Ativar a API Cloud KMS.

2. Conceda o papel Cloud KMS CryptoKey Decrypter do IAM à conta de serviço do Cloud Build:

   1. No Console do Cloud, acesse a página "Configurações" do Cloud Build:

      Abrir a página Configurações

   2. Localize a linha com o papel Descriptografador de CryptoKey do Cloud KMS e defina o Status como ENABLED.

3. Abra uma janela de terminal.

4. Crie um novo Cloud KMS key-ring com o nome keyring-name:

     gcloud kms keyrings create keyring-name --location global
   

5. Crie um novo Cloud KMS key key-name para o key-ring keyring-name:

     gcloud kms keys create key-name \
         --location global --keyring keyring-name \
         --purpose encryption
   

6. Configure o Cloud Build para usar dados criptografados:

   • Para usar variáveis criptografadas:

     1. Criptografe secret-name usando key-name e keyring-name. O valor criptografado é uma string codificada em base64. Não inclua caracteres externos, como espaços ou novas linhas em secret-name. A sinalização -n instrui echo a não incluir uma nova linha de encerramento:

         echo -n secret-name | gcloud kms encrypt --plaintext-file=- \
             --ciphertext-file=- --location=global --keyring=keyring-name \
             --key=key-name | base64
        

     2. No arquivo de configuração da versão, adicione um campo secrets para especificar o valor criptografado e o CryptoKey a ser usado para descriptografá-lo. Em seguida, na etapa de versão em que você quer usar a variável criptografada, adicione um campo secretEnv para especificar a variável como uma variável de ambiente. Inclua o nome da variável no campo secretEnv. Se você especificar o valor da variável ou uma variável de ambiente não secreta com o mesmo nome, o Cloud Build emitirá um erro.

        YAML

         steps:
         - name: 'gcr.io/cloud-builders/docker'
           entrypoint: 'bash'
           args: ['-c', 'docker login --username=user-name --password=$$PASSWORD']
           secretEnv: ['PASSWORD']
         - name: 'gcr.io/cloud-builders/docker'
           args: ['push', 'user-name/myubuntu']
         secrets:
         - kmsKeyName: projects/project-id/locations/global/keyRings/keyring-name/cryptoKeys/key-name
           secretEnv:
             PASSWORD: 'encrypted-password'
        

        JSON

         {
           "steps": [
            {
              "name": "gcr.io/cloud-builders/docker",
              "entrypoint": "bash",
              "args": [
                "-c",
                "docker login --username=user-name --password=$$PASSWORD"
               ],
               "secretEnv": [
                 "PASSWORD"
                ]
            },
            {
              "name": "gcr.io/cloud-builders/docker",
              "args": [
                "push",
                "user-name/myubuntu"
               ]
            }
            ],
            "secrets": [
             {
               "kmsKeyName": "projects/project-id/locations/global/keyRings/keyring-name/cryptoKeys/key-name",
               "secretEnv": {
                 "PASSWORD": "encrypted-password"
                }
             }
             ]
         }
        

     Observação: os campos kmsKeyName e secretEnv não são compatíveis com variáveis de substituição. Se o ID do projeto que hospeda a chave for alterado, o conteúdo criptografado nesse projeto também sofrerá mudanças.

   • Para usar arquivos criptografados:

     1. Criptografe o arquivo chamado secrets.json usando keyring-name e keyring-name. Isso produz um arquivo criptografado chamado secrets.json.enc. secrets.json não pode ser maior que 64 KiB.

         gcloud kms encrypt --plaintext-file=secrets.json \
             --ciphertext-file=secrets.json.enc \
             --location=global --keyring=keyring-name\
             --key=key-name
        

     2. No arquivo de configuração da versão, antes de qualquer etapa de versão que interaja com o arquivo secrets.json descriptografado, adicione uma etapa de versão que chame o gcloud Cloud Build para descriptografar secrets.json.enc usando a chave de criptografia. Essa etapa da criação é semelhante aos comandos usados para criptografar o arquivo.

        YAML

         steps:
         - name: gcr.io/cloud-builders/gcloud
           args:
           - kms
           - decrypt
           - --ciphertext-file=secrets.json.enc
           - --plaintext-file=secrets.json
           - --location=global
           - --keyring=keyring-name
           - --key=key-name
           # more steps here
        

        JSON

         {
           "steps": [
            {
              "name": "gcr.io/cloud-builders/gcloud",
              "args": [
                "kms",
                "decrypt",
                "--ciphertext-file=secrets.json.enc",
                "--plaintext-file=secrets.json",
                "--location=global",
                "--keyring=keyring-name",
                "--key=key-name"
              ]
            }
            ]
         }
        

        Após a conclusão desta etapa, todas as etapas subsequentes poderão usar o arquivo secrets.json descriptografado. Por exemplo, use os secrets neste arquivo para buscar dependências externas ou para incluir tokens de secret em imagens de contêiner do Docker que você criar.

7. Use o arquivo de configuração de build para iniciar manualmente um build ou para automatizar builds usando acionadores.

Aviso: os usuários que não têm permissão para usar a chave para descriptografar, mas que têm permissão para executar versões, podem executar uma versão que usa a chave para descriptografar usando o acesso da conta de serviço do Cloud Build. Isso significa que, se a conta de serviço do Cloud Build tiver acesso a uma chave, qualquer usuário que tenha acesso para criar versões poderá acessar a chave. Esse acesso é registrado nohistórico da versão do projeto.

A seguir

• Saiba mais sobre dados autenticados adicionais.
• Saiba mais sobre a hierarquia de objetos do Cloud KMS.