Prepare o ambiente

Antes de criar um pipeline do Image Builder, prepare seu ambiente Cloud de Confiance . Para preparar o ambiente, conclua as seguintes tarefas:

Antes de começar

  • Configure a autenticação, caso ainda não tenha feito isso. Com isso, você confirma sua identidade para acesso a serviços e APIs do Cloud de Confiance by S3NS . Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine selecionando uma das seguintes opções:

    Selecione a guia para como planeja usar as amostras nesta página:

    Console

    Quando você usa o console Cloud de Confiance para acessar serviços Cloud de Confiance by S3NS e APIs, não é necessário configurar a autenticação.

    gcloud

    1. Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada. Depois de fazer login, inicialize a Google Cloud CLI executando o seguinte comando: 

      gcloud init
  • Defina uma região e uma zona padrão.

    • REST

    Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

      Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada.

    Saiba mais em Autenticar para usar REST na documentação de autenticação do Cloud de Confiance .

Funções exigidas

Para receber as permissões necessárias para preparar seu ambiente, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Solicitação de integração

O Image Builder está disponível para todos os usuários com uma lista de permissões. Para integrar seu projeto Cloud de Confiance ao pipeline de personalização de imagens, envie o formulário de solicitação de acesso ou entre em contato com a equipe da sua conta Cloud de Confiance .

Contas de serviço cobertas pela lista de permissões

A lista de permissões concede acesso ao seu projeto pelo número dele. Como resultado, a lista de permissões abrange apenas as contas de serviço, que incluem o seguinte:

  • Contas de serviço gerenciado pelo usuário que você cria no seu projeto.
  • Contas de serviço padrão que o Cloud de Confiance cria no seu projeto, como a conta de serviço padrão do Compute Engine (PROJECT_NUMBER-compute@developer.s3ns-system.iam.gserviceaccount.com).

A lista de permissões não abrange contas de serviço do Google porque o Cloud de Confiance cria essas contas em projetos do Google em vez de no seu projeto. As contas de serviço do Google incluem o seguinte:

  • Agentes de serviço, como service-PROJECT_NUMBER@gcp-sa-SERVICE.s3ns-system.iam.gserviceaccount.com.
  • A conta de serviço legada do Cloud Build (PROJECT_NUMBER@cloudbuild.s3ns-system.iam.gserviceaccount.com), que é de propriedade e gerenciada pelo Google.

Para mais informações sobre esses tipos de conta de serviço, consulte Tipos de contas de serviço.

Se um build for executado como uma conta de serviço do Google, ele não poderá ler as imagens de contêiner do orquestrador do Image Builder no Artifact Registry. Como resultado, o pipeline falha com um erro de permissão negada. Para evitar essa falha, execute seus pipelines como uma conta de serviço gerenciado pelo usuário criada no projeto e especifique essa conta ao enviar um build. Para mais informações, consulte Configurar a conta de serviço do Image Builder e Conta de serviço padrão do Cloud Build.

Ativar APIs

O Image Builder exige que você ative as APIs Compute Engine, Cloud Build, Artifact Registry, Service Usage e Resource Manager. Para ativar as APIs usando o console Cloud de Confiance ou a Google Cloud CLI, selecione uma das seguintes guias:

Console

Ative as APIs Compute Engine, Cloud Build, Artifact Registry, Service Usage e Cloud Resource Manager.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

gcloud

Ative as APIs Compute Engine, Cloud Build, Artifact Registry, Service Usage e Cloud Resource Manager:

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis. 

gcloud services enable compute.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com serviceusage.googleapis.com cloudresourcemanager.googleapis.com

Configurar a conta de serviço do Image Builder

O orquestrador do Image Builder é executado usando uma conta serviço gerenciado pelo usuário. Quando você executa um pipeline de build de imagem, o Cloud Build anexa essa conta de serviço a instâncias temporárias de VM de worker e de teste para realizar ações de personalização e validação. Essa conta de serviço precisa ter os seguintes papéis:

  • Administrador do Compute (roles/compute.admin): gerencia instâncias de VM, discos permanentes e imagens do SO convidado.
  • Usuário da conta de serviço (roles/iam.serviceAccountUser): permite que o Cloud Build anexe a conta de serviço ao worker efêmero e teste instâncias de VM.
  • Administrador do Storage (roles/storage.admin): lê e grava artefatos e registros de build temporários no bucket de preparo workdir do Cloud Storage.
  • Gravador de registros do Logging (roles/logging.logWriter): grava registros de execução no Cloud Logging.
  • Leitor do Service Usage (roles/serviceusage.serviceUsageViewer): verifica os estados do serviço do projeto durante a execução do pipeline.
  • Editor do Cloud Build (roles/cloudbuild.builds.editor): aciona e executa jobs do Cloud Build e exporta imagens.
  • (Opcional) Administrador do Artifact Registry (roles/artifactregistry.admin): envia por upload os arquivos tar de imagem do SO gerados para o Artifact Registry.

É possível usar uma conta de serviço atual ou criar uma dedicada para seu pipeline de build. Use uma conta de serviço que esteja no seu projeto. Não execute seus pipelines como uma conta de serviço do Google, como a conta de serviço legada do Cloud Build, porque a lista de permissões do Image Builder não abrange essas contas. Para mais informações, consulte Contas de serviço cobertas pela lista de permissões e Conta de serviço padrão do Cloud Build.

Para criar uma conta de serviço dedicada e conceder os papéis necessários usando o console Cloud de Confiance ou a CLI gcloud, selecione uma das seguintes guias:

Console

    Verifique se você tem o papel do IAM de criação de contas de serviço (roles/iam.serviceAccountCreator) e o papel de administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin). Saiba como conceder papéis.

  1. No console Cloud de Confiance , acesse a página Criar conta de serviço.

    Acesse "Criar conta de serviço"
  2. Selecione o projeto.

  3. No campo Nome da conta de serviço, insira um nome. O console Cloud de Confiance preenche o campo ID da conta de serviço com base nesse nome.

    No campo Descrição da conta de serviço, insira uma descrição. Por exemplo, Service account for quickstart.

  4. Clique em Criar e continuar.

  5. Conceda os seguintes papéis à conta de serviço: Compute Engine > Administrador do Compute, Contas de serviço > Usuário da conta de serviço, Cloud Storage > Administrador do Storage, Cloud Logging > Gravador de registros, Service Usage > Leitor de uso do serviço, Cloud Build > Editor do Cloud Build, Artifact Registry > Administrador do Artifact Registry.

    Para conceder um papel, encontre a lista Selecionar um papel e escolha uma opção.

    Para conceder outros papéis, clique em Adicionar outro papel e adicione cada papel adicional.

  6. Clique em Continuar.

  7. No campo Papel de usuários da conta de serviço, insira o identificador do principal que vai anexar a conta de serviço a outros recursos, como instâncias do Compute Engine.

    Normalmente, é o identificador de um usuário em um pool de identidades de força de trabalho. Para mais detalhes, consulte Representar usuários do pool de força de trabalho nas políticas do IAM.

  8. Clique em Concluído para terminar a criação da conta de serviço.

gcloud

  1. Crie uma conta de serviço para seu pipeline de build:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --display-name="Image Builder Service Account"

  2. Conceda os papéis necessários (roles/compute.admin, roles/iam.serviceAccountUser, roles/storage.admin, roles/logging.logWriter, roles/serviceusage.serviceUsageViewer e roles/cloudbuild.builds.editor) à sua conta de serviço:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/compute.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/logging.logWriter"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/serviceusage.serviceUsageViewer"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/cloudbuild.builds.editor"

  3. Opcional: conceda o papel opcional (roles/artifactregistry.admin) à sua conta de serviço:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/artifactregistry.admin"

Substitua:

  • SERVICE_ACCOUNT_NAME: o nome da conta de serviço de build a ser criada. Por exemplo, custom-builder-sa.
  • PROJECT_ID: o ID do projeto Cloud de Confiance .
  • SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da sua conta de serviço de build.

Configurar a política da organização de imagens confiáveis

Como o Image Builder usa internamente as ferramentas padrão de importação e exportação de imagens do Compute Engine durante a execução da build, a política de imagens confiáveis (compute.trustedImageProjects) do projeto precisa permitir explicitamente imagens do seguinte projeto:

  • projects/compute-image-import

Se a política da organização restringir esse projeto, a fase de exportação da imagem vai falhar.

Para atualizar a política da organização:

  1. Na política da organização para a restrição compute.trustedImageProjects, adicione projects/compute-image-import à sua lista de publishers permitidos.
  2. Para instruções detalhadas sobre como configurar restrições de política da organização, consulte Configurar políticas de imagem confiáveis e Exportar uma imagem personalizada para o Cloud Storage.

Configurar a rede VPC e os requisitos de acesso

Durante as fases de build e validação, o Image Builder provisiona VMs de worker e de teste temporárias no seu projeto Cloud de Confiance . Por padrão, o Image Builder conecta instâncias à sua rede VPC default e atribui endereços IP externo efêmeros.

Se você especificar um network ou subnetwork personalizado ou configurar externalIP: none no arquivo de receita imagebuilder.yaml:

  • Acesso privado do Google e Cloud NAT:se as VMs de trabalho ou de teste forem configuradas com externalIP: none (sem IP externo), a sub-rede da VPC precisará ter o Acesso privado do Google ativado para que as instâncias possam acessar as APIs e os serviços do Google, como o Cloud Storage e o Artifact Registry. Se as etapas de personalização baixarem pacotes do SO ou dependências de repositórios externos da Internet, também será necessário configurar o Cloud NAT na sub-rede.
  • Regras de firewall:verifique se as regras de firewall da VPC permitem o tráfego de saída para as APIs do Google e os repositórios de software necessários. Se você planeja se conectar a VMs de worker ativas para depuração interativa (debug: true), verifique se as regras de firewall permitem a entrada na porta TCP 22. Se as instâncias de VM não tiverem um IP externo, permita a entrada do intervalo de IP do Identity-Aware Proxy (IAP) 35.235.240.0/20 para encaminhamento de TCP.

Configurar o Artifact Registry

Para armazenar e gerenciar suas imagens de SO personalizadas, metadados de segurança e atestados de procedência do build SLSA, configure um repositório genérico no Artifact Registry. Ao armazenar suas imagens no Artifact Registry, você mantém um registro seguro e imutável de imagens publicadas.

Ao configurar um destino do Artifact Registry, o Image Builder executa as seguintes etapas:

  • Exporta o disco de inicialização da VM finalizada como um arquivo tar padrão (.tar.gz).
  • Faz upload do arquivo tar para seu repositório genérico no Artifact Registry.
  • Gera e assina atestados de procedência do build do SLSA para o artefato e o vincula aos metadados de origem.
  • Registra a imagem do Compute Engine pronta para produção com o Compute Engine usando o URI do arquivo tar do Artifact Registry como a origem do modelo.

Para configurar um Artifact Registry genérico, conclua as seguintes tarefas:

  1. Verifique se a conta de serviço usada para executar o pipeline do Image Builder tem o papel Administrador do Artifact Registry (roles/artifactregistry.admin) no nível do repositório ou do projeto. Para instruções detalhadas, consulte Configurar a conta de serviço do Image Builder.

  2. Crie um repositório de formato generic. Para criar o repositório, execute o comando gcloud artifacts repositories create:

    gcloud artifacts repositories create REPOSITORY_NAME \
    --repository-format=generic \
    --location=REPOSITORY_LOCATION

    Substitua os seguintes marcadores de posição:

    • REPOSITORY_NAME: um nome para o repositório genérico. Por exemplo, custom-os-images.
    • REPOSITORY_LOCATION: uma região compatível. Por exemplo, us-central1.

A seguir