Tutorial do Terraform

Este tutorial demonstra como implementar uma função HTTP carregando um ficheiro ZIP do código fonte da função para um contentor do Cloud Storage, usando o Terraform para aprovisionar os recursos. O Terraform é uma ferramenta de código aberto que lhe permite aprovisionar recursos com ficheiros de configuração declarativos. Google Cloud

Este tutorial usa uma função HTTP do Node.js como exemplo, mas também funciona com funções HTTP do Python, Go e Java. As instruções são as mesmas, independentemente de qual destes tempos de execução estiver a usar.

Quando implementa com o Terraform, tem de carregar o ficheiro de origem comprimido da sua função para um contentor do Cloud Storage (source_archive_bucket) e também especificar o nome do objeto do Cloud Storage (source_archive_object) na configuração do Terraform. Para mais informações, consulte o guia de especificação do Terraform.

As funções do Cloud Run copiam o ficheiro de origem que carrega para um contentor no seu projeto com um nome de contentor que segue o formato gcf-v2-sources-PROJECT_NUMBER-REGION(funções do Cloud Run) ou gcf-sources-PROJECT_NUMBER-REGION funções do Cloud Run (1.ª geração).source_archive_bucket Esta configuração varia consoante a dependência da CMEK.

Objetivos

• Saiba como usar o Terraform para implementar uma função HTTP.

Custos

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

• Cloud Run functions
• Cloud Build
• Cloud Storage
• Artifact Registry

For details, see Cloud Run functions pricing.

Para gerar uma estimativa de custos com base na sua utilização projetada, 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 (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 Functions, Cloud Run, Cloud Build, Artifact Registry, and Cloud Storage 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 (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 Functions, Cloud Run, Cloud Build, Artifact Registry, and Cloud Storage 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

Se já tiver a CLI gcloud instalada, atualize-a executando o seguinte comando:

gcloud components update

1. Prepare o seu ambiente de desenvolvimento.
   

   Aceda ao guia de configuração do Node.js

Funções necessárias

• Os utilizadores que implementam funções têm de ter a função do IAM Cloud Functions Developer (roles/cloudfunctions.developer) ou uma função que inclua as mesmas autorizações. Consulte também a secção Configuração adicional para implementação.

• Para receber as autorizações de acesso ao contentor do Cloud Storage, peça ao seu administrador para conceder à identidade do IAM que implementa a função a função de administrador de armazenamento (roles/storage.admin). Para mais detalhes sobre as funções e as autorizações do Cloud Storage, consulte o artigo IAM para o Cloud Storage.

Configurar o seu ambiente

Neste tutorial, executa comandos no Cloud Shell. O Cloud Shell é um ambiente de shell com a CLI do Google Cloud já instalada, incluindo a CLI do Google Cloud, e com valores já definidos para o seu projeto atual. O Cloud Shell pode demorar vários minutos a inicializar:

Abra o Cloud Shell

A preparar a aplicação

No Cloud Shell, siga estes passos:

1. Clone o repositório da app de exemplo para a sua instância do Cloud Shell:

   git clone https://github.com/terraform-google-modules/terraform-docs-samples.git

2. Altere para o diretório que contém os exemplos de código do exemplo de funções do Cloud Run:

   cd terraform-docs-samples/functions/basic

   O exemplo de Node.JS usado neste tutorial é uma função HTTP "Hello World" básica. Aqui está o ficheiro main.tf:

   terraform {
     required_providers {
       google = {
         source  = "hashicorp/google"
         version = ">= 4.34.0"
       }
     }
   }
   
   resource "random_id" "default" {
     byte_length = 8
   }
   
   resource "google_storage_bucket" "default" {
     name                        = "${random_id.default.hex}-gcf-source" # Every bucket name must be globally unique
     location                    = "US"
     uniform_bucket_level_access = true
   }
   
   data "archive_file" "default" {
     type        = "zip"
     output_path = "/tmp/function-source.zip"
     source_dir  = "functions/hello-world/"
   }
   resource "google_storage_bucket_object" "object" {
     name   = "function-source.zip"
     bucket = google_storage_bucket.default.name
     source = data.archive_file.default.output_path # Add path to the zipped function source code
   }
   
   resource "google_cloudfunctions2_function" "default" {
     name        = "function-v2"
     location    = "us-central1"
     description = "a new function"
   
     build_config {
       runtime     = "nodejs22"
       entry_point = "helloHttp" # Set the entry point
       source {
         storage_source {
           bucket = google_storage_bucket.default.name
           object = google_storage_bucket_object.object.name
         }
       }
     }
   
     service_config {
       max_instance_count = 1
       available_memory   = "256M"
       timeout_seconds    = 60
     }
   }
   
   resource "google_cloud_run_service_iam_member" "member" {
     location = google_cloudfunctions2_function.default.location
     service  = google_cloudfunctions2_function.default.name
     role     = "roles/run.invoker"
     member   = "allUsers"
   }
   
   output "function_uri" {
     value = google_cloudfunctions2_function.default.service_config[0].uri
   }

Inicialize o Terraform

No diretório terraform-docs-samples/functions/basic que contém o ficheiro main.tf, execute este comando para adicionar os plug-ins necessários e criar o diretório .terraform:

terraform init

Aplique a configuração do Terraform

No mesmo diretório terraform-docs-samples/functions/basic que contém o ficheiro main.tf, implemente a função aplicando a configuração. Quando lhe for pedido, introduza yes:

terraform apply

Teste a função

1. Quando a implementação da função terminar, tome nota da propriedade URI ou encontre-a através do seguinte comando:

   gcloud functions describe function-v2 --gen2 --region=us-central1 --format="value(serviceConfig.uri)"
   

2. Faça um pedido a este URL para ver a mensagem "Olá, mundo" da sua função. Tenha em atenção que a função é implementada com autenticação obrigatória. Por conseguinte, tem de fornecer credenciais no seu pedido:

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" YOUR_FUNCTION_URL

Nota: por motivos de segurança, é uma prática recomendada exigir autenticação para a invocação de funções HTTP. Se necessário, pode ativar a invocação não autenticada após a implementação da função.

Limpar

Depois de concluir o tutorial, pode eliminar tudo o que criou para não incorrer em custos adicionais.

O Terraform permite-lhe remover todos os recursos definidos no ficheiro de configuração executando o comando terraform destroy no diretório terraform-docs-samples/functions/basic que contém o ficheiro main.tf:

terraform destroy

Introduza yes para permitir que o Terraform elimine os seus recursos.