Esta página explica como usar recursos criptografados em suas solicitações de versão. Use recursos criptografados, como arquivos ou variáveis, para passar informações confidenciais, como tokens de autorização, nas etapas de versão.
Criptografe e descriptografar recursos usando CryptoKeys do Cloud Key Management Service (Cloud KMS), que permitem gerenciar de maneira flexível e fácil o acesso e a rotação de chaves de criptografia. As CryptoKeys são armazenadas em KeyRings, que são agrupamentos de CryptoKeys para fins organizacionais.
Acesse o Guia de início rápido do Cloud KMS para se familiarizar com o Cloud KMS e ativar a Cloud KMS API.
Como criar KeyRing e CryptoKey do Cloud KMS
Crie KeyRings e CryptoKeys usando os comandos gcloud kms keyrings create e gcloud kms keys create.
Para criar um KeyRing, execute o seguinte comando no shell ou na janela do terminal:
gcloud kms keyrings create [KEYRING-NAME] \
--location=global
Para criar um CryptoKey:
gcloud kms keys create [KEY-NAME] \
--location=global \
--keyring=[KEYRING-NAME] \
--purpose=encryption
em que:
[KEYRING-NAME]é o nome do KeyRing a ser criado;[KEY-NAME]é o nome da CryptoKey a ser criada.
Conceder permissão para que a conta de serviço do Cloud Build acesse a CryptoKey
Para descriptografar seu recurso durante a versão, é necessário conceder à conta de serviço do Cloud Build permissão para acessar sua CryptoKey. Se for necessário apenas descriptografar o arquivo, você só precisa conceder permissão de descriptografia.
Para conceder permissão:
Console
- Visite o menu do IAM no console do GCP.
- Copie o endereço de e-mail da conta de serviço do Cloud Build que termina com
@cloudbuild.gserviceaccount.com. - Visite o menu de chaves de criptografia no console do GCP.
- Selecione seu KeyRing na lista e clique em Permissão.
- Insira o endereço de e-mail da conta de serviço no campo Adicionar membros.
- No menu suspenso Papéis, escolha descriptografia da CryptoKey do Cloud KMS.
- Clique em Adicionar.
gcloud
Execute os seguintes comandos no shell ou na janela do terminal:
gcloud kms keys add-iam-policy-binding \
[KEY-NAME] --location=global --keyring=[KEYRING-NAME] \
--member=serviceAccount:[PROJECT_NUMBER]@cloudbuild.gserviceaccount.com \
--role=roles/cloudkms.cryptoKeyDecrypter
Para saber mais sobre este comando, consulte a documentação do gcloud kms keys.
Se você não souber o endereço de e-mail da conta de serviço do Cloud Build, visite o menu do IAM no console do Google Cloud Platform.
O endereço de e-mail da conta de serviço contém @cloudbuild.gserviceaccount.com.
Para saber mais sobre como conceder acesso a chaves, consulte Como usar o IAM com o Cloud KMS na documentação do Cloud KMS.
Como criptografar um arquivo usando uma CryptoKey
Para criptografar um arquivo, execute o seguinte comando no shell ou na janela do terminal:
gcloud kms encrypt \
--plaintext-file=secrets.json \
--ciphertext-file=secrets.json.enc \
--location=global \
--keyring=[KEYRING-NAME] \
--key=[KEY-NAME]
Essa etapa produz um arquivo criptografado chamado secrets.json.enc, que apresenta o conteúdo de secrets.json.
Como armazenar o arquivo criptografado
Depois de criptografar seu arquivo, armazene-o no mesmo local que o código-fonte, como em um Cloud Source Repository ou em um repositório conectado do GitHub ou Bitbucket.
Por exemplo, para adicionar e confirmar o arquivo criptografado no seu repositório Git:
git add secrets.json.enc
git commit -am "Add encrypted secrets.json.enc"
git push
Para evitar a confirmação do arquivo de texto simples secrets.json no seu repositório, adicione o nome do arquivo ao arquivo .gitignore do seu repositório.
echo "secrets.json" >> .gitignore
git commit -am "Add secrets.json to .gitignore"
git push
Como descriptografar o arquivo durante sua versão
Agora que seu arquivo está criptografado com uma chave de criptografia que pode ser acessada pela conta de serviço do Buider, adicione uma etapa de versão para descriptografar o conteúdo do arquivo criptografado.
Na sua solicitação de versão, antes de qualquer etapa de versão que interaja com o arquivo secrets.json descriptografado, adicione uma etapa de versão que chama o Builder gcloud para descriptografar secrets.json.enc usando a chave de criptografia. Essa etapa de versão é semelhante aos comandos usados para criptografar o arquivo.
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
Depois que essa etapa for concluída, qualquer etapa seguinte pode usar o arquivo secrets.json descriptografado no diretório do espaço de trabalho.
Por exemplo, use os segredos neste arquivo para buscar dependências externas ou para incluir tokens secretos em imagens de contêiner Docker que você criar.
Como criptografar uma variável de ambiente usando CryptoKeys
Para criptografar uma variável de ambiente, execute o seguinte comando no shell ou na janela do terminal:
echo -n $MY_SECRET | gcloud kms encrypt \
--plaintext-file=- \ # - reads from stdin
--ciphertext-file=- \ # - writes to stdout
--location=global \
--keyring=[KEYRING-NAME] \
--key=[KEY-NAME] | base64
Esse comando criptografa o valor da variável de ambiente $MY_SECRET usando CryptoKeys. O valor criptografado é uma string codificada em base64 para que você inclua facilmente o valor em sua solicitação de versão.
Como usar a variável criptografada em solicitações de versão
Na sua solicitação de versão, inclua um campo secrets, que especifica o valor criptografado e a CryptoKey a ser usada para descriptografá-lo:
secrets:
- kmsKeyName: projects/[PROJECT-ID]/locations/global/keyRings/[KEYRING-NAME]/cryptoKeys/[KEY-NAME]
secretEnv:
MY_SECRET: <base64-encoded encrypted secret>
Nas etapas de versão, especifique se o valor descriptografado estará disponível como uma variável de ambiente:
steps:
- name: 'my-builder-image'
args: ['my', 'args']
env: ['FOO=foo', 'BAR=bar']
secretEnv: ['MY_SECRET']
Exemplo de solicitação de versão usando uma variável criptografada
A solicitação de versão de exemplo a seguir envia uma imagem do Docker para o Dockerhub usando uma senha Dockerhub criptografada:
steps:
# Pull a public image from Dockerhub.
- name: 'gcr.io/cloud-builders/docker'
args: ['pull', 'ubuntu']
# Retag the image into a user's repository.
- name: 'gcr.io/cloud-builders/docker'
args: ['tag', 'ubuntu', '[MY-USER]/myubuntu']
# Login to provide credentials for the push.
# PASSWORD is decrypted before this step runs.
# Note: You need a shell to resolve environment variables with $$
- name: 'gcr.io/cloud-builders/docker'
entrypoint: 'bash'
args: ['-c', 'docker login --username=[MY-USER] --password=$$PASSWORD']
secretEnv: ['PASSWORD']
# Push the image to Dockerhub.
- name: 'gcr.io/cloud-builders/docker'
args: ['push', '[MY-USER]/myubuntu']
secrets:
- kmsKeyName: projects/[PROJECT-ID]/locations/global/keyRings/[KEYRING-NAME]/cryptoKeys/[KEY-NAME]
secretEnv:
PASSWORD: <base64-encoded encrypted Dockerhub password>
Nesse exemplo, a etapa docker login faz login no Dockerhub usando o nome de usuário especificado e a senha do Dockerhub decodificada, de modo que a próxima etapa possa realizar docker push na imagem do repositório do usuário para o Dockerhub usando essas credenciais.
