Aceder ao GitHub a partir de uma compilação através de chaves SSH

Este tutorial demonstra como usar o Secret Manager com o Cloud Build para aceder a repositórios GitHub privados a partir de uma compilação. O Secret Manager é um Google Cloud serviço que armazena em segurança chaves de API, palavras-passe e outros dados confidenciais.

Nota: tem de usar o Secret Manager para se ligar a repositórios privados do GitHub apenas quando executar compilações manuais. Quando executa compilações com acionadores do Cloud Build, pode ligar-se automaticamente a qualquer repositório privado que possua sem armazenar as suas credenciais no Secret Manager. Para obter informações sobre como criar acionadores, consulte o artigo Criar e gerir acionadores de compilação.

Objetivos

• Configure uma chave SSH do GitHub.
• Adicione a chave pública de SSH às chaves de implementação de um repositório privado.
• Armazene a chave SSH privada no Secret Manager.
• Envie uma compilação que aceda à chave do Gestor Secreto e a use para aceder ao repositório privado.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Secret Manager
• Cloud Build

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build and Secret Manager APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build and Secret Manager APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

1. Opcional. Conclua o início rápido do Gestor Secreto para se familiarizar com este produto.

Crie uma chave SSH

1. Abra uma janela de terminal.

2. Crie um novo diretório denominado workingdir e navegue para o mesmo:

   mkdir workingdir
   cd workingdir
   

3. Crie uma nova chave SSH do GitHub, em que github-email é o seu endereço de email do GitHub:

   ssh-keygen -t rsa -b 4096 -N '' -f id_github -C github-email
   

   Este comando cria uma nova chave SSH workingdir/id_github sem uma frase de acesso para a sua chave SSH. O Cloud Build não pode usar a sua chave SSH se estiver protegida com uma frase secreta.

Armazene a chave SSH privada no Secret Manager

Quando cria uma chave SSH, é criado um ficheiro id_github no seu ambiente. Uma vez que qualquer pessoa pode autenticar-se na sua conta com este ficheiro, tem de armazená-lo no Secret Manager antes de o usar numa compilação.

Para armazenar a sua chave SSH no Secret Manager, faça o seguinte:

1. Aceda à página Secret Manager na Google Cloud consola:

   Aceda à página Secret Manager

2. Na página Secret Manager, clique em Create Secret.

3. Na página Criar segredo, em Nome, introduza um nome para o segredo.

4. No campo Valor secreto, clique em Carregar e carregue o ficheiro workingdir/id_github.

5. Não altere a secção Regiões.

6. Clique no botão Criar segredo.

Esta ação carrega o ficheiro id_github para o Secret Manager.

Adicione a chave SSH pública às chaves de implementação do repositório privado

1. Inicie sessão no GitHub.

2. No canto superior direito, clique na sua foto do perfil e, de seguida, clique em O seu perfil.

3. Na página do seu perfil, clique em Repositórios e, de seguida, clique no nome do seu repositório.

4. No repositório, clique em Definições.

5. Na barra lateral, clique em Deploy Keys e, de seguida, em Add deploy key.

6. Indique um título e cole a sua chave SSH pública de workingdir/id_github.pub.

7. Selecione Permitir acesso de escrita se quiser que esta chave tenha acesso de escrita ao repositório. Uma chave de implementação com acesso de escrita permite que uma implementação seja enviada para o repositório.

8. Clique em Adicionar chave.

9. Elimine a chave SSH do disco:

   rm id_github*
   

Conceder autorizações

Tem de conceder autorização para aceder ao Secret Manager à conta de serviço que está a usar para a compilação.

1. Na Google Cloud consola, aceda à página Autorizações do Cloud Build:

   Aceda a Autorizações

2. Na lista pendente, selecione a conta de serviço cujas funções quer alterar.

3. Defina o estado da função Secret Manager Secret Accessor como Ativar.

Adicione a chave pública de SSH aos anfitriões conhecidos

A maioria das máquinas contém um ficheiro denominado known_hosts, que contém chaves conhecidas para anfitriões remotos. As chaves são frequentemente recolhidas dos anfitriões remotos quando se ligam aos mesmos pela primeira vez, mas também podem ser adicionadas manualmente. As chaves neste ficheiro são usadas para validar a identidade do anfitrião remoto e proteger contra roubo de identidade.

Para que o Cloud Build se ligue ao GitHub, tem de adicionar a chave SSH pública ao ficheiro known_hosts no ambiente de compilação do Cloud Build. Pode fazê-lo adicionando a chave a um ficheiro known_hosts.github temporário e, em seguida, copiando o conteúdo de known_hosts.github para o ficheiro known_hosts no ambiente de compilação do Cloud Build.

No diretório workingdir, crie um ficheiro denominado known_hosts.github e adicione a chave SSH pública a este ficheiro:

ssh-keyscan -t rsa github.com > known_hosts.github

Na secção seguinte, quando configurar a compilação, vai adicionar instruções no ficheiro de configuração do Cloud Build para copiar o conteúdo de known_hosts.github para o ficheiro known_hosts no ambiente de compilação do Cloud Build.

Nota: por motivos de segurança, valide as impressões digitais do anfitrião no ficheiro known_hosts em comparação com as impressões digitais da chave do anfitrião SSH publicadas pelo GitHub.

Configure a compilação

Para configurar a compilação:

1. Crie um ficheiro de configuração de compilação denominado cloudbuild.yaml com dois passos: o primeiro passo gcloud acede à chave SSH no Secret Manager e guarda-a como id_rsa num volume denominado ssh, juntamente com uma cópia do known_hosts.github. O volume é usado para persistir ficheiros nos passos de compilação. O segundo passo git usa a chave em id_rsa para estabelecer ligação ao repositório em [e-mail]:git-username/git-repository.

   # Access the id_github file from Secret Manager, and setup SSH
   steps:
   - name: 'gcr.io/cloud-builders/git'
     secretEnv: ['SSH_KEY']
     entrypoint: 'bash'
     args:
     - -c
     - |
       echo "$$SSH_KEY" >> /root/.ssh/id_rsa
       chmod 400 /root/.ssh/id_rsa
       cp known_hosts.github /root/.ssh/known_hosts
     volumes:
     - name: 'ssh'
       path: /root/.ssh
   
   # Clone the repository
   - name: 'gcr.io/cloud-builders/git'
     args:
     - clone
     - --recurse-submodules
     - [e-mail]:GIT_USERNAME/GIT_REPOSITORY
     volumes:
     - name: 'ssh'
       path: /root/.ssh
   
   availableSecrets:
     secretManager:
     - versionName: projects/PROJECT_ID/secrets/SECRET_NAME/versions/latest
       env: 'SSH_KEY'
   

Substitua os valores dos marcadores de posição nos comandos acima pelo seguinte:

• GIT_USERNAME: o nome de utilizador do GitHub do proprietário do repositório.
• GIT_REPOSITORY: o nome do repositório do GitHub ao qual quer aceder.
• PROJECT_ID: O ID do Google Cloud projeto onde armazenou os seus segredos.
• SECRET_NAME: o nome do segredo que criou no Secret Manager.

Para saber mais sobre as strings multilinha YAML usadas no fragmento acima, consulte o artigo YAML multilinha.

Envie a compilação

Para enviar a compilação, execute o seguinte comando:

gcloud builds submit --config=cloudbuild.yaml .

O resultado é semelhante ao seguinte:

Creating temporary tarball archive of 3 file(s) totalling 4.1 KiB before compression.
Uploading tarball of [.] to [gs://[PROJECT-ID]_cloudbuild/source/1504288639.02---.tgz]
Created [https://cloudbuild.googleapis.com/v1/projects/[PROJECT-ID]/builds/871b68bc---].
Logs are available at [https://console.cloud.google.com/cloud-build/builds/871b68bc---?project=[PROJECT-ID]].
----------------------------- REMOTE BUILD OUTPUT ------------------------------
starting build "871b68bc-cefc-4411-856c-2a2b7c7d2487"

FETCHSOURCE
Fetching storage object: gs://[PROJECT-ID]_cloudbuild/source/1504288639.02---.tgz#1504288640827178
Copying gs://[PROJECT-ID]_cloudbuild/source/1504288639.02---.tgz#1504288640827178...
/ [1 files][  3.9 KiB/  3.9 KiB]
Operation completed over 1 objects/3.9 KiB.
BUILD
Step #0: Already have image (with digest): gcr.io/cloud-builders/gcloud
Starting Step #0
Finished Step #0
Step #1: Already have image (with digest): gcr.io/cloud-builders/git
Starting Step #1
Step #1: # github.com SSH-2.0-libssh_0.7.0
Finished Step #1
Step #2: Already have image (with digest): gcr.io/cloud-builders/git
Starting Step #2
Step #2: Cloning into '[REPOSITORY-NAME]'...
Step #2: Warning: Permanently added the RSA host key for IP address 'XXX.XXX.XXX.XXX' to the list of known hosts.
Finished Step #2
PUSH
DONE
-----------------------------------------------------------------------------------------------------------------

ID                                    CREATE_TIME                DURATION  SOURCE                                                                              IMAGES  STATUS
871b68bc-cefc-4411-856c-2a2b7c7d2487  XXXX-XX-XXT17:57:21+00:00  13S       gs://[PROJECT-ID]_cloudbuild/source/1504288639.02---.tgz  -                                 SUCCESS

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Elimine o projeto

A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.

Para eliminar o projeto:

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Elimine a chave de implementação do seu repositório

1. No GitHub, navegue para a página principal do repositório.

2. Abaixo do nome do repositório, clique em Definições.

3. Na barra lateral esquerda, clique em Chaves de implementação.

4. Na página Implementar chaves, procure as chaves de implementação associadas ao seu repositório e clique em Eliminar.

O que se segue?

• Saiba como criar acionadores do GitHub.
• Saiba mais sobre a utilização de recursos encriptados no Cloud Build.
• Saiba mais sobre o Secret Manager.