Vista geral do processo de compilação

Este guia mostra a vista geral do processo de criação de funções implementadas com o comando gcloud functions. Para saber mais sobre o processo de compilação de funções implementadas através do comando gcloud run, consulte:

Quando implementa o código fonte da sua função através do comando gcloud functions deploy, esse código fonte é armazenado num contentor do Cloud Storage. O Cloud Build compila automaticamente o seu código numa imagem de contentor e envia essa imagem para um registo de imagens.

O processo de criação da imagem é totalmente automático e não requer qualquer introdução direta da sua parte. Todos os recursos usados no processo de compilação são executados no seu próprio projeto de utilizador.

A execução do processo de compilação no seu projeto significa que:

  • Tem acesso direto a todos os registos de compilação.

  • Não existe uma quota de tempo de compilação predefinida, embora o Cloud Build tenha a sua quota de simultaneidade predefinida.

  • Pode ver a imagem do contentor atual e as imagens do contentor implementadas anteriormente, que estão armazenadas no Artifact Registry.

  • O Cloud Storage é usado no seu projeto para armazenar o diretório do código fonte das suas funções. Tenha em conta o seguinte:

    • Se criar uma função através da Google Cloud CLI, é criado um contentor de carregamento para guardar o seu código fonte. Este contentor de carregamento tem o nome gcf-v2-uploads-PROJECT_NUMBER-REGION.cloudfunctions.appspot.com.
    • Depois de o código ser carregado, o código da função é armazenado num contentor de origem separado:
      • Se estiver a usar a encriptação predefinida, este contentor tem o nome gcf-v2-sources-PROJECT_NUMBER-REGION.
      • Se estiver a proteger os seus dados com a CMEK, o contentor tem o nome gcf-v2-sources-PROJECT_NUMBER-REGION-CMEK_KEY_HASH.
    • Os contentores de origem e de carregamento não têm um período de retenção.

Caraterísticas do processo de compilação

O processo de criação tem as seguintes caraterísticas:

  • A API Cloud Build tem de estar ativada para o seu projeto.

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

  • Uma vez que todo o processo de criação ocorre no contexto do seu projeto, o projeto está sujeito aos preços dos recursos incluídos:

    • Para ver os preços do Cloud Build, consulte a página de preços. Este processo usa o tamanho da instância predefinido do Cloud Build, uma vez que estas instâncias são pré-aquecidas e estão disponíveis mais rapidamente. O Cloud Build oferece um nível gratuito: reveja o documento de preços para obter mais detalhes.

    • Para ver os preços do Cloud Storage, consulte a página Preços. O Cloud Storage oferece um Nível gratuito: reveja o documento de preços para mais detalhes.

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

  • Uma vez que o processo de compilação está sujeito a faturação, o seu projeto tem de ter uma conta do Cloud Billing associada.

Veja os registos de imagens de compilação

Uma das principais vantagens de ter o processo de criação de imagens no seu projeto de utilizador é o acesso aos registos de criação. Pode usar a CLI gcloud ou a Google Cloud consola para aceder aos registos, que estão disponíveis através do Cloud Logging.

gcloud

  1. Implemente a sua função através do gcloud functions deploy comando.

  2. O URL dos registos é apresentado como parte da resposta na janela do terminal. Por exemplo:

    Deploying function (may take a while - up to 2 minutes)...⠹
**For Cloud Build Stackdriver Logs**, visit:
https://console.cloud.google.com/logs/viewer?project=&advancedFilter=resource.type%
3Dbuild%0Aresource.labels.build_id%3D38d5b662-2315-45dd-8aa2-
380d50d4f5e8%0AlogName%3Dprojects%2F%
2Flogs%2Fcloudbuild
Deploying function (may take a while - up to 2 minutes)...done.

Google Cloud consola

Para ver os registos de funções na página do Cloud Run:

  1. Aceda ao Cloud Run

  2. Clique na função escolhida na lista apresentada.

  3. Clique no separador REGISTOS para obter os registos de pedidos e contentores de todas as revisões desta função. Pode filtrar por nível de gravidade do registo.

Registo de imagens

O Artifact Registry é usado para armazenar as imagens criadas a partir do código fonte da sua função. As imagens são armazenadas num repositório denominado REGION-docker.pkg.dev/PROJECT_ID/gcf-artifacts localizado no mesmo projeto onde a sua função é criada.

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

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

Substitua o seguinte:

  • 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.

Quando especifica um repositório do Artifact Registry localizado num projeto ou numa região diferente, pode ter de considerar configurações adicionais:

Configurações da IAM:

  • Configurações do IAM: certifique-se de que a conta de serviço de compilação tem acesso autorizado para leitura e escrita no REPOSITORY.
  • Configurações de rede: certifique-se de que o REPOSITORY de destino está acessível a partir da configuração do projeto atual.
  • Configurações do VPC Service Controls: certifique-se de que a conta de serviço de compilação consegue alcançar o destino REPOSITORY dentro do perímetro do VPC-SC.
  • Restrições de residência dos dados: a especificação de um REPOSITORY numa região diferente da localização da sua função vai originar a transferência de dados entre regiões.

Proteja a sua compilação com pools privados

Para permitir que as suas funções usem dependências (por exemplo, pacotes npm), o Cloud Build tem, por predefinição, acesso ilimitado à Internet durante o processo de compilação. Se configurou um perímetro do VPC Service Controls (VPC SC) e quer limitar o acesso da compilação apenas a dependências armazenadas no interior do perímetro, pode usar a funcionalidade pools de trabalhadores privados do Cloud Build.

Em geral, siga estes passos para configurar o seu conjunto privado:

  1. Crie o seu pool de trabalhadores privado. Consulte o artigo Crie e faça a gestão de pools privados.

  2. Configure o perímetro do VPC Service Controls. Consulte o artigo Usar os VPC Service Controls.

  3. Se o seu conjunto de trabalhadores privado estiver num projeto diferente da sua função, tem de conceder à conta de serviço do agente de serviço do Cloud Functions (service-FUNCTION_PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com) a função cloudbuild.workerPoolUser para que o serviço do Cloud Build possa aceder ao conjunto de trabalhadores.

    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 onde a função é executada e PRIVATE_POOL_PROJECT_ID pelo ID do projeto no qual o conjunto de trabalhadores está localizado. Consulte o artigo Executar compilações num pool privado para mais informações.

  4. Implemente a sua função para compilar através de um pool privado:

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

    Substitua FUNCTION_NAME pelo nome da função, RUNTIME pelo tempo de execução que está a usar e PRIVATE_POOL_NAME pelo nome do seu conjunto.

Para parar de usar um determinado conjunto privado e, em alternativa, usar o conjunto do Cloud Build predefinido, use a flag --clear-build-worker-pool quando voltar a implementar.

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

Substitua FUNCTION_NAME pelo nome da função e RUNTIME pelo tempo de execução que está a usar.

Proteja a sua compilação com uma conta de serviço personalizada

O código-fonte da sua função é enviado para o Cloud Build para ser colocado num contentor. A função em contentor é armazenada no Artifact Registry e implementada no Cloud Run como um serviço. As funções do Cloud Run tiram partido do Cloud Build quando cria e implementa a sua função do Cloud Run. Por predefinição, as funções do Cloud Run usam a conta de serviço do Cloud Build predefinida como o principal quando executam a sua compilação. A partir de julho de 2024, o Cloud Build alterou o comportamento predefinido da forma como o Cloud Build usa as contas de serviço em novos projetos. Como resultado desta alteração, os novos projetos que implementam funções pela primeira vez podem estar a usar uma conta de serviço do Cloud Build predefinida com autorizaçõ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 do Cloud Build antiga. Esta conta de serviço foi concebida para ajudar os utilizadores a executar uma vasta gama de exemplos de utilização que podem ser demasiado permissivos para as necessidades do seu projeto. Se quiser mover os seus projetos existentes desta conta de serviço, pode seguir os passos seguintes para proteger ainda mais o ambiente de compilação das funções:

Impeça a utilização da conta de serviço do Cloud Build antiga para a compilação

Pode verificar se o seu projeto está a usar a conta de serviço do Cloud Build antigo inspecionando os detalhes da compilação da sua função. A conta de serviço de compilação predefinida tem o seguinte formato:

PROJECT_NUMBER@cloudbuild.gserviceaccount.com.

Pode desativar à força a utilização desta conta de serviço definindo a restrição da política organizacional cloudbuild.useBuildServiceAccount como Not Enforced. Em alternativa, a remoção de todas as atribuições de funções limita a capacidade de acesso aos recursos do Google Cloud.

Impeça a utilização da conta de serviço de computação predefinida para a compilação

A conta de serviço predefinida do Compute tem o formato PROJECT_NUMBER-compute@developer.gserviceaccount.com. Pode desativar a utilização desta funcionalidade como predefinição para a compilação definindo a política org cloudbuild.useComputeServiceAccount como Not Enforced. Em alternativa, a desativação desta conta de serviço impede a sua utilização para aceder Google Cloud a recursos.

Forneça uma conta de serviço para criar funções

Como parte da configuração de uma função, pode especificar uma conta de serviço de compilação quando implementar a função. Quando a conta de serviço do Cloud Build antiga e a conta de serviço do Compute predefinida não podem ser usadas para a compilação, tem de especificar uma conta de serviço de compilação para implementar uma função, conforme descrito nesta secção.

Se for afetado pelas alterações descritas no artigo Alteração da conta de serviço do Cloud Build, pode fazer uma das seguintes ações:

  • Reveja as orientações do Cloud Build sobre as alterações à conta de serviço predefinida e desative estas alterações.

  • Adicione a função de conta do Cloud Build (roles/cloudbuild.builds.builder) à conta de serviço predefinida do Compute Engine.

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

Seguem-se alguns cenários em que pode querer fornecer uma conta de serviço diferente para ser usada quando o Cloud Build compila a sua função:

  • Quer ter mais controlo sobre as contas de serviço a adicionar ao perímetro do VPC-SC.

  • Quer que o Cloud Build seja executado com autorizações diferentes das que a conta de serviço predefinida tem, sem ter de revogar cada autorização individualmente.

  • Quer definir autorizações detalhadas do Cloud Build especificamente para as suas funções e não partilhar uma conta de serviço do Cloud Build otimizada para outros fins.

  • A sua organização desativou a utilização da conta de serviço predefinida.

As secções seguintes mostram como criar uma conta de serviço do Cloud Build personalizada para implementações de funções.

Criar uma conta de serviço

Crie uma nova conta de serviço, conforme descrito no artigo Crie uma conta de serviço.

Conceder Permissões

A conta de serviço que usa precisa das seguintes funções:

  • roles/logging.logWriter— Necessário para armazenar registos de compilação no Cloud Logging.
  • roles/artifactregistry.writer: necessário para armazenar imagens de compilação no Artifact Registry. Para o comportamento predefinido, a conta de serviço precisa de acesso a repositórios denominados "gcf-artifacts" e "cloud-run-source-deploy". O acesso aos repositórios pode ser definido na política IAM do repositório. Em alternativa, pode fornecer o seu próprio repositório de artefactos através do campo dockerRepository.
  • roles/storage.objectViewer— Necessário para obter a origem da função do contentor do Cloud Storage e para armazenar imagens de compilação no Container Registry. Para o comportamento predefinido, a conta de serviço precisa de acesso a contentores denominados "run-sources-*", "gcf-v2-sources-*" e "gcf-v2-uploads-*". Isto pode ser feito adicionando uma condição de IAM à concessão de funções, como (resource.type == "storage.googleapis.com/Object" && (resource.name.startsWith("projects/_/buckets/gcf-v2-sources-") || resource.name.startsWith("projects/_/buckets/gcf-v2-uploads-") || resource.name.startsWith("projects/_/buckets/run-sources-")))

Conceda as seguintes funções através da CLI do Google Cloud ou use a Google Cloud consola.

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 o seguinte:

Considerações sobre os VPC Service Controls

Se tiver um perímetro dos VPC Service Controls a proteger o seu projeto e a API Cloud Run Functions, e se estiver a usar a conta de serviço predefinida do Compute Engine como a função Conta de serviço do Cloud Build para as Cloud Run Functions, tem de criar as seguintes regras de entrada:

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

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

Para transmitir uma conta de serviço criada pelo utilizador, a ser usada pelo Cloud Build, quando implementar a sua função, execute o seguinte comando gcloud:

  • A flag --build-service-account especifica uma conta de serviço da IAM cujas credenciais vão ser usadas para a etapa de compilação. Se não for fornecida uma conta de serviço personalizada, a função usa a conta de serviço predefinida do projeto para o Cloud Build.
  • Opcionalmente, pode usar um conjunto privado, que especifica através da 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 o seguinte:

Conceda à conta de serviço do Cloud Build acesso ao perímetro do VPC Service Controls

As funções do Cloud Run usam o Cloud Build para criar o seu código fonte num contentor executável. Para usar as funções do Cloud Run com os VPC Service Controls, tem de configurar a sua conta de serviço do Cloud Build (predefinida ou personalizada) para ter acesso ao seu perímetro de serviço.

Encontre o nome da conta de serviço

Se estiver a usar a conta de serviço predefinida do Cloud Build, pode encontrar o respetivo nome da seguinte forma:

  1. Use a página IAM na Google Cloud consola para encontrar a conta de serviço do Cloud Build.

    Abrir IAM

  2. Certifique-se de que o projeto correto é apresentado no menu pendente do projeto.

  3. Pesquise cloudbuild.gserviceaccount.com. O endereço de email no formulário PROJECT_NUMBER@cloudbuild.gserviceaccount.com é o nome da conta de serviço.

Se tiver uma conta de serviço do Cloud Build personalizada, use esse nome.

Conceda à conta de serviço acesso ao perímetro de serviço

Depois de ter o nome da conta de serviço, siga o guia em Limite o acesso por utilizador ou conta de serviço para criar um nível de acesso para a conta de serviço. Em seguida, siga as instruções em "Adicionar um nível de acesso a um perímetro existente" para adicionar o nível de acesso ao seu perímetro de serviço.