Definir uma configuração de vários projetos

Configurar o projeto do implantador

O projeto do implantador gerencia os clusters do Google Kubernetes Engine (GKE), onde você implanta imagens, e a política de autorização binária aplicada pela autorização binária no momento da implantação. É possível ter mais de um projeto do implantador, dependendo do tamanho, da complexidade e de outros requisitos do ambiente.

Para configurar o projeto do implantador:

1. Crie o projeto e ative o faturamento no Console do Google Cloud, se ainda não tiver feito isso.

2. Observação do Identity and Access Management: o projeto do implantador contém o cluster do GKE. A configuração do Gerenciamento de Identidade e Acesso deste projeto refletirá isso.

3. Defina variáveis de ambiente para armazenar o número e o projeto do Google Cloud:

   DEPLOYER_PROJECT_ID=DEPLOYER_PROJECT_ID
   

   Substitua DEPLOYER_PROJECT_ID pelo ID do projeto do Google Cloud.

   DEPLOYER_PROJECT_NUMBER=$(gcloud projects describe "${DEPLOYER_PROJECT_ID}" \
       --format="value(projectNumber)")
   

4. Ative APIs:

   Container Registry

   gcloud --project=${DEPLOYER_PROJECT_ID} \
     services enable\
     container.googleapis.com\
     containerregistry.googleapis.com\
     binaryauthorization.googleapis.com
   

   Artifact Registry

   gcloud --project=${DEPLOYER_PROJECT_ID} \
     services enable\
     container.googleapis.com\
     artifactregistry.googleapis.com\
     binaryauthorization.googleapis.com
   

5. Consiga o nome da conta de serviço do projeto do implantador:

   DEPLOYER_SERVICE_ACCOUNT="service-${DEPLOYER_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
   

   Use o nome da conta de serviço em uma etapa posterior ao configurar permissões na nota do Artifact Analysis associada ao atestador.

Configurar o projeto do atestador

Um projeto de atestador armazena os atestadores que podem verificar se uma imagem está pronta para implantação. Muitas vezes, você tem um único projeto de atestador que atua como um repositório centralizado para informações sobre partes confiáveis no processo de autorização. Isso permite que você gerencie de maneira centralizada as chaves de segurança necessárias para verificar a identidade dos atestadores e restringir o acesso apenas às partes que os administram.

Para configurar o projeto de atestador:

1. Crie o projeto e ative o faturamento no Console do Google Cloud, se ainda não tiver feito isso.

2. Observação do Identity and Access Management: como este projeto contém seus atestadores, somente a equipe de segurança pode ter acesso de gravação.

3. Defina variáveis de ambiente para armazenar o nome e o número do projeto:

   ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID
   

   Substitua ATTESTOR_PROJECT_ID pelo ID do projeto do atestador.

   ATTESTOR_PROJECT_NUMBER=$(gcloud projects describe "${ATTESTOR_PROJECT_ID}" \
       --format="value(projectNumber)")
   

4. Ative as APIs do Artifact Analysis e de autorização binária:

   gcloud services --project=${ATTESTOR_PROJECT_ID} \
       enable containeranalysis.googleapis.com \
       binaryauthorization.googleapis.com
   

5. Consiga o nome da conta de serviço do projeto do atestador:

   ATTESTOR_SERVICE_ACCOUNT="service-${ATTESTOR_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
   

   Use o nome da conta de serviço em uma etapa posterior ao configurar permissões na nota do Artifact Analysis associada ao atestador.

Configurar o projeto de atestados

Um projeto de atestado é aquele que armazena atestados que os atestadores fazem quando verificam uma imagem. Um projeto de atestado separado permite que você organize e inspecione instruções sobre prontidão de software com mais facilidade.

1. Crie o projeto e ative o faturamento no Console do Google Cloud, se ainda não tiver feito isso.

2. Observação do Identity and Access Management: todos os papéis envolvidos na autorização binária precisam ter acesso de leitura às notas e ocorrências do Artifact Analysis neste projeto, mas apenas os gerenciadores de atestado precisam ter acesso de gravação.

3. Defina uma variável de ambiente para armazenar o nome do projeto:

   ATTESTATION_PROJECT_ID=ATTESTATION_PROJECT_ID
   

   Substitua ATTESTATION_PROJECT_ID pelo ID do projeto de atestado.

4. Ative as APIs do Artifact Analysis e de autorização binária:

   gcloud services --project=${ATTESTATION_PROJECT_ID} \
       enable containeranalysis.googleapis.com \
       binaryauthorization.googleapis.com
   

Crie um cluster

Agora você pode criar um cluster do GKE no projeto do implantador. Esse é o cluster em que você quer que as imagens de contêiner implantadas sejam geradas. Ao criar o cluster, você passa a sinalização --binauthz-evaluation-mode=PROJECT_SINGLETON_POLICY_ENFORCE para o comando gcloud container clusters create.

Para criar o cluster:

gcloud --project=${DEPLOYER_PROJECT_ID} \
    container clusters create \
    --binauthz-evaluation-mode=PROJECT_SINGLETON_POLICY_ENFORCE \
    --zone us-central1-a \
    test-cluster

Aqui, você cria um cluster chamado test-cluster na zona us-central1-a do GKE.

Também é necessário atualizar o arquivo kubeconfig local para a instalação do kubectl. Isso fornece as credenciais e as informações de endpoint necessárias para acessar o cluster no GKE.

Para atualizar o arquivo local kubeconfig:

gcloud --project=${DEPLOYER_PROJECT_ID} \
    container clusters get-credentials \
    --zone us-central1-a \
    test-cluster

Crie um atestador

Um atestador é uma parte responsável por verificar se um processo necessário foi concluído antes que uma imagem de contêiner possa ser implantada. Essa parte pode ser um usuário humano ou, mais frequentemente, um processo de máquina como um sistema de criação e teste ou seus pipelines de integração contínua (CI) e de implantação (CD). Você cria atestadores no seu projeto de atestador.

Para criar um atestador, você precisa:

• Crie uma nota no Artifact Analysis para armazenar metadados confiáveis usados no processo de autorização
• Crie o próprio atestador no projeto do atestador e associe a nota que você criou
• Adicione uma vinculação de papel do IAM para a conta de serviço do projeto do implantador ao atestador
• Definir permissões na nota do Artifact Analysis

Para este tutorial, você tem um atestador chamado test-attestor e uma nota do Container Analysis chamada test-attestor-note. Em um cenário real, é possível ter qualquer número de atestadores, cada um representando uma parte que participa do processo de autorização da imagem.

Criar a nota do Artifact Analysis

1. Defina variáveis que armazenam o nome do atestador e da nota do Artifact Analysis:

   ATTESTOR_NAME=test-attestor
   NOTE_ID=test-attestor-note
   

   Substitua:

   • test-attestor: nome do atestador de sua escolha.
   • test-attestor-note: nome da nota do atestador de sua escolha.

2. Crie um arquivo JSON em /tmp/note_payload.json que descreva a nota do Container Analysis:

   cat > /tmp/note_payload.json << EOM
   {
     "name": "projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}",
     "attestation": {
       "hint": {
         "human_readable_name": "Attestor Note"
       }
     }
   }
   EOM
   

3. Envie uma solicitação HTTP para a API REST do Artifact Analysis para criar a nota:

   curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
       --data-binary @/tmp/note_payload.json  \
       "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/?noteId=${NOTE_ID}"
   

4. Verifique se a nota foi criada:

   curl \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}"
   

Crie o atestador

Agora, você pode criar o atestador:

1. Crie o atestador na autorização binária:

   gcloud --project=${ATTESTOR_PROJECT_ID} \
       container binauthz attestors create ${ATTESTOR_NAME} \
       --attestation-authority-note=${NOTE_ID} \
       --attestation-authority-note-project=${ATTESTOR_PROJECT_ID}
   

2. Verifique se ele foi criado:

   gcloud --project=${ATTESTOR_PROJECT_ID} \
       container binauthz attestors list
   

O atestador que você criou ainda não pode ser usado sem um par de chaves PKIX associado, criado abaixo.

Adicione uma vinculação de papel do IAM para o projeto do implantador

Você precisa adicionar uma vinculação de papel do IAM para o projeto do implantador ao atestador. Isso é usado pela autorização binária quando avalia uma política para determinar se o projeto tem permissões para acessar os atestados associados.

Para adicionar a vinculação de papel do IAM:

gcloud --project ${ATTESTOR_PROJECT_ID} \
    container binauthz attestors add-iam-policy-binding \
    "projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}" \
    --member="serviceAccount:${DEPLOYER_SERVICE_ACCOUNT}" \
    --role=roles/binaryauthorization.attestorsVerifier

Definir permissões na nota do Artifact Analysis

Também é preciso definir permissões na nota do Artifact Analysis que você criou para que ela seja acessível ao projeto do implantador e ao do atestador. Para fazer isso, atualize a política do IAM da nota para atribuir acesso de Leitor às contas de serviço do projeto.

1. Gere um arquivo JSON que contenha as informações necessárias para definir a política do IAM na sua nota.

   cat > /tmp/iam_request.json << EOM
   {
     'resource': 'projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}',
     'policy': {
       'bindings': [
         {
           'role': 'roles/containeranalysis.notes.occurrences.viewer',
           'members': [
             'serviceAccount:${ATTESTOR_SERVICE_ACCOUNT}',
             'serviceAccount:${DEPLOYER_SERVICE_ACCOUNT}'
           ]
         }
       ]
     }
   }
   EOM
   

2. Adicione a conta de serviço e os papéis de acesso solicitados à política do IAM para a nota que você criou:

   curl -X POST  \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       --data-binary @/tmp/iam_request.json \
       "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}:setIamPolicy"
   

Configurar chaves PKIX

A autorização binária usa chaves criptográficas para verificar com segurança a identidade dos atestadores. Isso garante que somente as partes verificadas possam participar da autorização de uma imagem de contêiner. O par de chaves consiste em uma chave privada, que o atestador usa para assinar atestados digitalmente, e uma chave pública, que você adiciona ao atestador conforme armazenado pelo serviço de autorização binária.

Neste tutorial, você usa o Algoritmo de assinatura digital de curva elíptica (ECDSA, na sigla em inglês) recomendado para criar o par de chaves. Também é possível usar chaves RSA ou PGP para assinatura. Consulte Finalidades de chave e algoritmos para mais informações sobre algoritmos de assinatura.

As chaves assimétricas geradas e armazenadas pelo Cloud Key Management Service (Cloud KMS) são compatíveis com PKIX. Consulte Como criar atestadores usando a CLI para mais informações sobre como usar chaves PKIX e o Cloud KMS.

Gerar um par de chaves

Um par de chaves PKIX consiste em uma chave privada, que o signatário usa para assinar atestados digitalmente e uma chave pública, que você adiciona ao atestador. No momento da implantação, a autorização binária usa essa chave pública para verificar o atestado assinado pela chave privada.

1. Gerar a chave privada:

   Para gerar um novo par de chaves PKIX assimétrica e armazená-lo em um arquivo:

   PKIX (Cloud KMS)

   Nesta etapa, mostramos como executar um atestado usando chaves geradas e armazenadas no Cloud Key Management Service.

   1. Configure variáveis de ambiente para armazenar informações sobre o par de chaves como gerenciado pelo Cloud KMS:

      Se você já tiver um par de chaves, poderá definir essas variáveis de ambiente e pular a próxima etapa.

      KMS_KEY_PROJECT_ID=KMS_KEY_PROJECT_ID
      KMS_KEY_LOCATION=KMS_KEY_LOCATION
      KMS_KEYRING_NAME=KMS_KEYRING_NAME
      KMS_KEY_NAME=KMS_KEY_NAME
      KMS_KEY_VERSION=KMS_KEY_VERSION
      

      Substitua:

      • KMS_KEY_PROJECT_ID: o ID do projeto em que as chaves são armazenadas;
      • KMS_KEY_LOCATION: a localização da chave;
      • KMS_KEYRING_NAME: o nome do keyring;
      • KMS_KEY_NAME: o nome da chave;
      • KMS_KEY_VERSION: a versão da chave.

   2. [Opcional] Configure uma chave KMS:

      1. Crie uma chave KMS cuja chave pública possa ser armazenada em um atestador. Esta etapa também configura as variáveis de ambiente que você usa abaixo.

         Para criar uma chave e configurar as variáveis de ambiente:

         KMS_KEY_PROJECT_ID=${PROJECT_ID}
         KMS_KEYRING_NAME=my-binauthz-keyring
         KMS_KEY_NAME=my-binauthz-kms-key-name
         KMS_KEY_LOCATION=global
         KMS_KEY_PURPOSE=asymmetric-signing
         KMS_KEY_ALGORITHM=ec-sign-p256-sha256
         KMS_PROTECTION_LEVEL=software
         KMS_KEY_VERSION=1
         

      2. Crie um keyring do KMS:

         gcloud kms keyrings create ${KMS_KEYRING_NAME} \
           --location ${KMS_KEY_LOCATION} \
           --project ${KMS_KEY_PROJECT_ID}
         

      3. Crie a chave:

         gcloud kms keys create ${KMS_KEY_NAME} \
           --location ${KMS_KEY_LOCATION} \
           --keyring ${KMS_KEYRING_NAME}  \
           --purpose ${KMS_KEY_PURPOSE} \
           --default-algorithm ${KMS_KEY_ALGORITHM} \
           --protection-level ${KMS_PROTECTION_LEVEL} \
           --project ${KMS_KEY_PROJECT_ID}
         

         Para mais informações sobre como criar chaves do KMS, consulte Criar uma chave assimétrica.

   3. Adicione a chave pública ao atestador:

      gcloud --project="${ATTESTOR_PROJECT_ID}" \
          container binauthz attestors public-keys add \
          --attestor="${ATTESTOR_NAME}" \
          --keyversion-project="${KMS_KEY_PROJECT_ID}" \
          --keyversion-location="${KMS_KEY_LOCATION}" \
          --keyversion-keyring="${KMS_KEYRING_NAME}" \
          --keyversion-key="${KMS_KEY_NAME}" \
          --keyversion="${KMS_KEY_VERSION}"
      

   PKIX (chave local)

   1. Para gerar a chave privada, execute os seguintes comandos:

      PRIVATE_KEY_FILE="/tmp/ec_private.pem"
      openssl ecparam -genkey -name prime256v1 -noout -out ${PRIVATE_KEY_FILE}
      

      PRIVATE_KEY_FILE é o nome do arquivo que contém a chave privada armazenada no atestador.

   2. Extraia a chave pública da chave privada e armazene-a em um arquivo:

      PUBLIC_KEY_FILE="/tmp/ec_public.pem"
      openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
      

      PUBLIC_KEY_FILE é o nome do arquivo que contém a chave pública armazenada no atestador.

   3. Para adicionar a chave pública exportada para o atestador, execute o código a seguir.

      gcloud --project="${ATTESTOR_PROJECT_ID}" \
        container binauthz attestors public-keys add \
        --attestor="${ATTESTOR_NAME}" \
        --pkix-public-key-file=${PUBLIC_KEY_FILE} \
        --pkix-public-key-algorithm=ecdsa-p256-sha256
      

      A autorização binária usa a chave pública no atestador para verificar o atestado.

Configurar a política

Agora, você pode configurar sua política no projeto do implantador. Nesta etapa, você exporta o arquivo YAML da política para o sistema local e modifica a regra padrão para que exija um atestado pelo atestador definido acima.

Para configurar a política:

1. Crie um novo arquivo de política que permita as imagens do sistema mantidas pelo Google, defina o evaluationMode como REQUIRE_ATTESTATION e adicione um nó chamado requireAttestationsBy que faz referência ao atestador que você criou:

   cat > /tmp/policy.yaml << EOM
       globalPolicyEvaluationMode: ENABLE
       defaultAdmissionRule:
         evaluationMode: REQUIRE_ATTESTATION
         enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
         requireAttestationsBy:
           - projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}
       name: projects/${DEPLOYER_PROJECT_ID}/policy
   EOM
   

2. Importe o arquivo YAML da política para a autorização binária:

   gcloud --project=${DEPLOYER_PROJECT_ID} \
       container binauthz policy import /tmp/policy.yaml
   

Para mais informações sobre como configurar uma política, consulte Como configurar uma política usando a CLI.

Testar a política

Neste tutorial, você criará um atestado, por exemplo, imagens "Hello World!" públicas pelo Container Registry e pelo Artifact Registry. Inicialmente, o aplicador impede que as imagens sejam implantadas porque o atestado necessário não existe.

Para tentar implantar a imagem:

kubectl run hello-server --image gcr.io/google-samples/hello-app:1.0 --port 8080

kubectl run hello-server --image us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0 --port 8080

Agora verifique se a implantação foi bloqueada pela autorização binária:

kubectl get pods

O comando imprime a seguinte mensagem, que indica que a imagem não foi implantada:

No resources found.

Veja mais detalhes sobre a implantação:

kubectl get event --template \
'{{range.items}}{{"\033[0;36m"}}{{.reason}}:{{"\033[0m"}}\{{.message}}{{"\n"}}{{end}}'

Você verá uma resposta semelhante a esta:

FailedCreate: Error creating: pods POD_NAME is forbidden: admission webhook "imagepolicywebhook.image-policy.k8s.io" denied the request: Image IMAGE_NAME denied by Binary Authorization default admission rule. Image IMAGE_NAME denied by attestor ATTESTOR_NAME: No attestations found

Nesta saída:

• POD_NAME: o nome do pod.
• IMAGE_NAME: o nome da imagem.
• ATTESTOR_NAME: o nome do atestador.

Exclua a implantação para seguir para a próxima etapa:

kubectl delete deployment hello-server

Criar um atestado

Um atestado é uma declaração de um atestador de que um processo obrigatório no pipeline foi concluído e que a imagem do contêiner em questão está autorizada para implantação. O próprio atestado é um registro assinado digitalmente que contém o caminho completo para uma versão da imagem conforme armazenado no registro de imagem do contêiner, bem como a identidade do atestador.

Neste tutorial, seu atestado simplesmente declara que você autoriza a imagem para implantação. Crie o atestado no projeto de atestado.

Para criar um atestado:

1. Defina variáveis que armazenem o caminho do registro e o resumo da imagem:

   Container Registry

   IMAGE_PATH="gcr.io/google-samples/hello-app"
   IMAGE_DIGEST="sha256:c62ead5b8c15c231f9e786250b07909daf6c266d0fcddd93fea882eb722c3be4"
   

   Artifact Registry

   IMAGE_PATH="us-docker.pkg.dev/google-samples/containers/gke/hello-app"
   IMAGE_DIGEST="sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567"
   IMAGE_TO_ATTEST=${IMAGE_PATH}@${IMAGE_DIGEST}
   

2. Criar o atestado

   PKIX (Cloud KMS)

   Para criar o atestado usando a chave do Cloud KMS, execute o seguinte comando:

   gcloud beta container binauthz attestations sign-and-create \
       --project="${PROJECT_ID}" \
       --artifact-url="${IMAGE_TO_ATTEST}" \
       --attestor="${ATTESTOR_NAME}" \
       --attestor-project="${PROJECT_ID}" \
       --keyversion-project="${KMS_KEY_PROJECT_ID}" \
       --keyversion-location="${KMS_KEY_LOCATION}" \
       --keyversion-keyring="${KMS_KEYRING_NAME}" \
       --keyversion-key="${KMS_KEY_NAME}" \
       --keyversion="${KMS_KEY_VERSION}"
   

   PKIX (chave local)

   Para criar o atestado usando uma chave local, faça o seguinte:

   1. Gere o payload do atestado:

      gcloud --project=${ATTESTATION_PROJECT_ID} \
        container binauthz create-signature-payload \
        --artifact-url=${IMAGE_TO_ATTEST} > /tmp/generated_payload.json
      

      O arquivo JSON de payload tem o seguinte conteúdo:

      Container Registry

      {
      "critical": {
        "identity": {
          "docker-reference": "gcr.io/google-samples/hello-app"
        },
        "image": {
          "docker-manifest-digest": "sha256:c62ead5b8c15c231f9e786250b07909daf6c266d0fcddd93fea
      882eb722c3be4"
        },
        "type": "Google cloud binauthz container signature"
      }
      }
      

      Artifact Registry

      {
      "critical": {
        "identity": {
          "docker-reference": "us-docker.pkg.dev/google-samples/containers/gke/hello-app"
        },
        "image": {
          "docker-manifest-digest": "sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567"
        },
        "type": "Google cloud binauthz container signature"
      }
      }
      

   2. Assine o payload.

      Se estiver usando arquivos PKIX locais, assine o payload com sua chave privada PKIX local e gere um arquivo de assinatura:

      openssl dgst -sha256 -sign ${PRIVATE_KEY_FILE} /tmp/generated_payload.json > /tmp/ec_signature
      

      O arquivo de saída é uma versão assinada do arquivo JSON do payload que você criou acima.

   3. Receba o ID da chave pública do atestador.

      É possível ver seu ID de chave pública a qualquer momento usando o comando: gcloud container binauthz attestors describe ATTESTOR_NAME.

      Para salvar o ID da chave pública em uma variável de ambiente, digite este comando:

      PUBLIC_KEY_ID=$(gcloud container binauthz attestors describe ${ATTESTOR_NAME} \
      --format='value(userOwnedGrafeasNote.publicKeys[0].id)' --project ${ATTESTOR_PROJECT_ID})
      

   4. Crie e valide o atestado:

      gcloud container binauthz attestations create \
        --project="${ATTESTATION_PROJECT_ID}" \
        --artifact-url="${IMAGE_TO_ATTEST}" \
        --attestor="projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}" \
        --signature-file=/tmp/ec_signature \
        --public-key-id="${PUBLIC_KEY_ID}" \
        --validate
      

      A sinalização validate verifica se o atestado pode ser verificado pelo atestador que você configurou na política.

3. Verifique se o atestado foi criado:

   gcloud --project=${ATTESTATION_PROJECT_ID} \
       container binauthz attestations list \
       --attestor=$ATTESTOR_NAME --attestor-project=$ATTESTOR_PROJECT_ID
   

Para mais informações sobre como criar atestados, consulte Como criar atestados.

Testar a política outra vez

Teste a política implantando uma imagem de contêiner de amostra no cluster. Desta vez, você precisa implantar a imagem usando o resumo em vez de uma tag, como 1.0 ou latest, já que a autorização binária usa o resumo para procurar atestados. Aqui, a autorização binária permite que a imagem seja implantada porque a imagem tem um atestado associado.

Para implantar a imagem:

kubectl run hello-server --image ${IMAGE_TO_ATTEST} --port 8080

Para verificar se a imagem foi implantada:

kubectl get pods

O comando imprime uma mensagem semelhante à seguinte, que indica que a implantação foi bem-sucedida:

NAME                            READY     STATUS    RESTARTS   AGE
hello-server-579859fb5b-h2k8s   1/1       Running   0          1m

Agora que você implantou com sucesso a imagem do contêiner e verificou se a configuração está funcionando, exclua o cluster criado no GKE:

gcloud --project=${DEPLOYER_PROJECT_ID} \
    container clusters delete \
    --zone=us-central1-a \
    test-cluster