Visão geral do processo de build

Este guia mostra uma visão geral do processo de build para funções implantadas usando o comando gcloud functions. Para saber mais sobre o processo de build de funções implantadas usando o comando gcloud run, consulte:

• Criar o Cloud Run em contêineres
• Definir a conta de serviço de build
• Definir pools de workers de build

Quando você implanta o código-fonte da função usando o comando gcloud functions deploy, essa origem é armazenada em um bucket do Cloud Storage. Em seguida, o Cloud Build cria automaticamente seu código em uma imagem de contêiner e a envia para um registro de imagens.

O processo de criação da imagem é totalmente automático e você não precisa intervir nele. Todos os recursos usados no processo de compilação são executados no próprio projeto do usuário.

Executar o processo de compilação dentro do projeto significa que:

• você tem acesso direto a todos os registros do build;

• não há uma cota de tempo de compilação predefinida, embora o Cloud Build tenha uma cota de simultaneidade padrão própria;

• É possível ver a imagem do contêiner atual e a imagem do contêiner implantada anteriormente, que são armazenadas no Artifact Registry.

• O Cloud Storage é usado no projeto para armazenar o diretório de código-fonte das funções. Observe o seguinte:

  • Se você criar uma função usando a CLI do Google Cloud, um bucket de upload será criado para armazenar seu código-fonte. Esse bucket de upload pode ser chamado de gcf-v2-uploads-PROJECT_NUMBER-REGION.cloudfunctions.appspot.com.
  • Depois que o código é enviado, ele é armazenado em um bucket de origem separado:
    • Se você estiver usando a criptografia padrão, esse bucket será chamado de gcf-v2-sources-PROJECT_NUMBER-REGION.
    • Se você estiver protegendo seus dados com CMEK, o bucket será chamado de gcf-v2-sources-PROJECT_NUMBER-REGION-CMEK_KEY_HASH.
  • Os buckets de origem e de upload não têm período de retenção.

Características do processo de compilação

O processo de compilação tem as seguintes características:

• A API Cloud Build precisa estar ativada no projeto.

  Para ativar a API manualmente, clique no link anterior, selecione seu projeto no menu suspenso e siga as instruções para ativar a interface.

• Como todo o processo de compilação ocorre dentro do contexto do projeto, este está sujeito aos preços dos recursos incluídos:

  • Para preços do Cloud Build, consulte a página Preços. Esse processo usa o tamanho padrão da instância do Cloud Build, já que essas instâncias são pré-montadas e ficam disponíveis mais rapidamente. O Cloud Build oferece um nível gratuito: consulte o documento de preços para mais detalhes.

  • Para preços do Cloud Storage, consulte a página Preços. O Cloud Storage oferece um nível gratuito. Veja mais detalhes no documento de preços.

  • Para preços do Artifact Registry, consulte a página Preços.

• Como o processo de compilação está sujeito ao faturamento, o projeto precisa ter uma Conta de faturamento do Cloud anexada a ele.

Ver os registros de imagem do build

Um dos principais benefícios de ter o processo de imagem do build no projeto de usuário é o acesso aos registros do build. Use a CLI gcloud ou o console Google Cloud para acessar os registros, que estão disponíveis no Cloud Logging.

Registro de imagens

O Artifact Registry é usado para armazenar as imagens criadas com o código-fonte da função. As imagens são armazenadas em um repositório chamado REGION-docker.pkg.dev/PROJECT_ID/gcf-artifacts localizado no mesmo projeto em que a função é criada.

Para especificar um repositório autogerenciado do Artifact Registry, execute o seguinte comando:

gcloud functions deploy FUNCTION_NAME \
   --docker-repository=REPOSITORY \
   [FLAGS...]

Substitua:

• FUNCTION_NAME: o nome da função.
• REPOSITORY: o nome do repositório do Artifact Registry totalmente qualificado, no seguinte formato: projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY.

Ao especificar um repositório do Artifact Registry localizado em um projeto ou região diferente, talvez seja necessário considerar outras configurações:

Configurações do IAM:

• Configurações do IAM: verifique se a conta de serviço do build tem acesso autorizado para ler e gravar no REPOSITORY.
• Configurações de rede: verifique se o REPOSITORY de destino pode ser acessado pela configuração atual do projeto.
• Configurações do VPC Service Controls: verifique se a conta de serviço de build pode acessar o REPOSITORY de destino no perímetro do VPC-SC.
• Restrições de residência de dados: especificar um REPOSITORY em uma região diferente de onde a função está localizada vai levar à transferência de dados entre regiões.

Proteger o build com pools particulares

Para permitir que suas funções usem dependências (por exemplo, pacotes npm), o Cloud Build tem, por padrão, acesso ilimitado à Internet durante o processo de criação. Se você tiver configurado um perímetro do VPC Service Controls (VPC SC) e quiser limitar o acesso do build apenas às dependências armazenadas dentro do perímetro, use o recurso Pools de workers particulares do Cloud Build.

Em geral, siga estas etapas para configurar seu pool particular:

1. Crie seu pool de workers particulares. Consulte Criar e gerenciar pools particulares.

2. Configure seu perímetro de VPC Service Controls. Consulte Como usar o VPC Service Controls.

3. Se o pool de workers privados estiver em um projeto diferente da função, você precisará conceder a conta de serviço Agente de serviço (service-FUNCTION_PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com) do Cloud Functions cloudbuild.workerPoolUser para que o serviço do Cloud Build possa acessar o pool de workers.

   gcloud projects add-iam-policy-binding PRIVATE_POOL_PROJECT_ID \
       --member serviceAccount:service-FUNCTION_PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com
       --role roles/cloudbuild.workerPoolUser

   Substitua FUNCTION_PROJECT_NUMBER pelo número do projeto em que a função é executada e PRIVATE_POOL_PROJECT_ID pelo ID do projeto em que o worker pool está localizado. Consulte Como executar versões em um pool particular para mais informações.

4. Implante a função para criar usando um pool particular:

   gcloud functions deploy FUNCTION_NAME \
      --runtime RUNTIME \
      --build-worker-pool PRIVATE_POOL_NAME
      [FLAGS...]

   Substitua FUNCTION_NAME pelo nome da função, RUNTIME pelo ambiente de execução que você está usando e PRIVATE_POOL_NAME pelo nome do seu pool.

Para interromper o uso de um determinado pool particular e usar o pool padrão do Cloud Build, use a sinalização --clear-build-worker-pool ao reimplantar.

gcloud functions deploy FUNCTION_NAME \
   --runtime RUNTIME \
   --clear-build-worker-pool
   [FLAGS...]

Substitua FUNCTION_NAME pelo nome da função e RUNTIME pelo ambiente de execução que você está usando.

Proteger o build com uma conta de serviço personalizada

O código-fonte da função é enviado ao Cloud Build para ser conteinerizado. A função conteinerizada é armazenada no Artifact Registry e implantada no Cloud Run como um serviço. As funções do Cloud Run usam o Cloud Build ao criar e implantar sua função do Cloud Run. Por padrão, as funções do Cloud Run usam a conta de serviço padrão do Cloud Build como principal ao executar o build. A partir de julho de 2024, o Cloud Build mudou o comportamento padrão de como o Cloud Build usa contas de serviço em novos projetos. Como resultado dessa mudança, os novos projetos que implantam funções pela primeira vez podem estar usando uma conta de serviço padrão do Cloud Build com permissões insuficientes para criar uma função.

Para Google Cloud projetos criados antes de julho de 2024, o Cloud Build usa a conta de serviço legada do Cloud Build. Essa conta de serviço foi projetada para ajudar os usuários a executar uma ampla variedade de casos de uso que podem ser muito permissivos para as necessidades do seu projeto. Se você quiser mover seus projetos atuais para fora dessa conta de serviço, siga as etapas abaixo para aumentar a segurança do ambiente de build de funções:

• Impedir que a conta de serviço legada do Cloud Build seja usada para o build
• Impedir que a conta de serviço de computação padrão seja usada para o build
• Configure uma nova conta de serviço com permissões de escopo adequado para serem usadas no build

Impedir que a conta de serviço legada do Cloud Build seja usada para build

É possível verificar se o projeto está usando a conta de serviço herdada do Cloud Build inspecionando os detalhes do build da função. A conta de serviço de build padrão tem o seguinte formato:

PROJECT_NUMBER@cloudbuild.gserviceaccount.com.

É possível desativar o uso dessa conta de serviço definindo a restrição de política da organização cloudbuild.useBuildServiceAccount como Not Enforced. Como alternativa, remover todas as permissões de função vai limitar a capacidade de acessar recursos Google Cloud.

Impedir que a conta de serviço de computação padrão seja usada para build

A conta de serviço padrão do Compute tem o formato PROJECT_NUMBER-compute@developer.gserviceaccount.com. Para desativar o padrão usado para o build, defina a política da organização cloudbuild.useComputeServiceAccount como Not Enforced. Outra opção é desativar essa conta de serviço para que ela não seja usada para acessar Google Cloud recursos.

Fornecer uma conta de serviço para criar funções

Como parte da configuração de uma função, é possível especificar uma conta de serviço do build ao implantar a função. Quando a conta de serviço legada do Cloud Build e a conta de serviço de computação padrão não podem ser usadas para build, especifique uma conta de serviço de build para implantar uma função, conforme descrito nesta seção.

Se você for afetado pelas mudanças descritas em Alteração da conta de serviço do Cloud Build, faça o seguinte:

• Revise as orientações do Cloud Build sobre mudanças na conta de serviço padrão e desative essas mudanças.

• Adicione o papel da conta do Cloud Build (roles/cloudbuild.builds.builder) à conta de serviço padrão do Compute Engine.

• Crie uma conta de serviço personalizada do Cloud Build para implantações de função.

Aqui estão alguns cenários em que convém fornecer uma conta de serviço diferente para ser usada quando o Cloud Build cria sua função:

• Você quer mais controle sobre quais contas de serviço adicionar ao seu perímetro do VPC-SC.

• Você quer que o Cloud Build seja executado com permissões diferentes da conta de serviço padrão, sem precisar revogar cada permissão individualmente.

• Se você quer definir permissões granulares do Cloud Build especificamente para suas funções, não compartilhe uma conta de serviço do Cloud Build otimizada para outras finalidades.

• Sua organização desativou o uso da conta de serviço padrão.

As seções a seguir mostram como criar uma conta de serviço personalizada do Cloud Build para implantações de função.

Criar uma conta de serviço

Crie uma nova conta de serviço conforme descrito em Criar uma conta de serviço.

Conceder permissões

A conta de serviço que você usa precisará dos seguintes papéis:

• roles/logging.logWriter Necessário para criar registros do build no Cloud Logging.
• roles/artifactregistry.writer: necessário para armazenar imagens do build no Artifact Registry. Para o comportamento padrão, a conta de serviço precisa de acesso a repositórios com o nome "gcf-artifacts" e "cloud-run-source-deploy". O acesso aos repositórios pode ser definido na política do IAM do repositório. Como alternativa, é possível fornecer seu próprio repositório de artefatos pelo campo dockerRepository.
• roles/storage.objectViewer: necessária para recuperar a origem da função do bucket do Cloud Storage e armazenar imagens de build no Container Registry. Para o comportamento padrão, a conta de serviço precisa ter acesso aos buckets "run-sources-*", "gcf-v2-sources-*" e "gcf-v2-uploads-*". Isso pode ser feito adicionando uma condição do IAM à concessão de função, como: (resource.type == "storage.googleapis.com/Object" && (resource.name.startsWith("gcf-v2-sources-") || resource.name.startsWith("gcf-v2-uploads-") || resource.name.startsWith("run-sources-")))

Conceda os papéis a seguir usando a CLI do Google Cloud ou o consoleGoogle Cloud .

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

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
--role=roles/artifactregistry.writer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
--role=roles/storage.objectViewer

Substitua:

• PROJECT_ID: o ID do projetoGoogle Cloud .
• SA_EMAIL: o endereço de e-mail da sua conta de serviço.

Considerações sobre o VPC Service Controls

Se você tiver um perímetro do VPC Service Controls protegendo seu projeto e a API Cloud Run functions e estiver usando a conta de serviço padrão do Compute Engine como o papel de Conta de serviço do Cloud Build para as funções do Cloud Run, crie as seguintes regras de entrada:

• Permita a entrada da conta de serviço padrão do Compute Engine em todos os métodos das APIs Cloud Storage e Cloud Logging.
• Permita que a conta de serviço service-[PROJECT_NUMBER]@gcf-admin-robot.iam.gserviceaccount.com entre em todos os métodos nas APIs Cloud Storage e Cloud Logging.

Implantar uma função com uma conta de serviço personalizada

Para transmitir uma conta de serviço criada pelo usuário e que será usada pelo Cloud Build ao implantar a função, execute o comando gcloud a seguir:

• A flag --build-service-account especifica uma conta de serviço do IAM com credenciais que serão usadas para a etapa de criação. Se uma conta de serviço personalizada não for fornecida, a função usará a conta de serviço padrão do projeto para o Cloud Build.
• Também é possível usar um pool particular, especificado usando a flag --build-worker-pool.

gcloud functions deploy FUNCTION_NAME \
   --gen2 \
   --region=REGION \
   --project=PROJECT_ID \
   --runtime=RUNTIME \
   --entry-point=CODE_ENTRYPOINT \
   --build-service-account=projects/PROJECT_ID/serviceAccounts/SA_EMAIL \
   --memory=256Mi \
   --trigger-http \
   --source=.

Substitua:

• FUNCTION_NAME: o nome com que você implantou a função.
• REGION: o nome da regiãoGoogle Cloud em que você quer implantar a função (por exemplo, us-west1).
• PROJECT_ID: o ID do projetoGoogle Cloud .
• RUNTIME: o ID do ambiente de execução de uma versão compatível para executar sua função, por exemplo, nodejs18.
• CODE_ENTRYPOINT: o ponto de entrada da função no código-fonte. Este é o código que será executado quando a função for executada.
• SA_EMAIL: o endereço de e-mail da sua conta de serviço.