Tutorial di Terraform

Questo tutorial mostra come eseguire il deployment di una funzione HTTP caricando un file ZIP del codice sorgente della funzione in un bucket Cloud Storage e utilizzando Terraform per il provisioning delle risorse. Terraform è uno strumento open source che consente di eseguire il provisioning delle risorse Google Cloud con file di configurazione dichiarativi.

Questo tutorial utilizza una funzione HTTP Node.js come esempio, ma è valido anche per le funzioni HTTP Python, Go e Java. Le istruzioni sono le stesse indipendentemente dal runtime utilizzato.

Quando esegui il deployment con Terraform, devi caricare il file ZIP del codice sorgente della funzione in un bucket Cloud Storage (source_archive_bucket) e devi anche specificare il nome dell'oggetto Cloud Storage (source_archive_object) nella configurazione Terraform. Per saperne di più, consulta la guida alle specifiche di Terraform.

Cloud Run Functions copia il file del codice sorgente che carichi in source_archive_bucket in un bucket del tuo progetto con un nome bucket nel formato gcf-v2-sources-PROJECT_NUMBER-REGION(Cloud Run Functions) o gcf-sources-PROJECT_NUMBER-REGION Cloud Run Functions (1ª gen.). Questa configurazione varia a seconda della dipendenza CMEK.

Obiettivi

• Scopri come utilizzare Terraform per eseguire il deployment di una funzione HTTP.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

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

For details, see Cloud Run functions pricing.

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova gratuita.

Prima di iniziare

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 utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo 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 utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Se hai già installato gcloud CLI, aggiornala eseguendo questo comando:

gcloud components update

1. Prepara l'ambiente di sviluppo.
   

   Vai alla guida alla configurazione di Node.js

Ruoli obbligatori

• Gli utenti che eseguono il deployment delle funzioni devono disporre del ruolo IAM Cloud Functions Developer (roles/cloudfunctions.developer) o di un ruolo che includa le stesse autorizzazioni. Consulta anche Configurazione aggiuntiva per il deployment.

• Per ottenere le autorizzazioni per accedere al bucket Cloud Storage, chiedi all'amministratore di concedere all'identità IAM che esegue il deployment della funzione il ruolo Storage Admin (roles/storage.admin). Per maggiori dettagli su ruoli e autorizzazioni di Cloud Storage, consulta IAM per Cloud Storage.

Configurazione dell'ambiente

In questo tutorial, esegui i comandi in Cloud Shell. Cloud Shell è un ambiente shell con Google Cloud CLI già inclusa e installata e con valori già impostati per il progetto corrente. L'inizializzazione di Cloud Shell può richiedere diversi minuti:

Apri Cloud Shell

Preparazione dell'applicazione

In Cloud Shell, segui questi passaggi:

1. Clona il repository dell'app di esempio nell'istanza di Cloud Shell:

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

2. Passa alla directory che contiene gli esempi di codice campione di Cloud Run Functions:

   cd terraform-docs-samples/functions/basic

   L'esempio Node.js utilizzato in questo tutorial è una semplice funzione HTTP "Hello World". Ecco il file 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
   }

Inizializza Terraform

Nella directory terraform-docs-samples/functions/basic contenente il file main.tf, esegui questo comando per aggiungere i plug-in necessari e creare la directory .terraform:

terraform init

Applica la configurazione Terraform

Nella stessa directory terraform-docs-samples/functions/basic contenente il file main.tf, esegui il deployment della funzione applicando la configurazione. Quando richiesto, inserisci yes:

terraform apply

Testa la funzione

1. Al termine del deployment della funzione, annota la proprietà URI o cercala utilizzando il seguente comando:

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

2. Invia una richiesta a questo URL per visualizzare il messaggio "Hello World" della tua funzione. Tieni presente che il deployment della funzione richiede l'autenticazione. Pertanto, devi fornire le credenziali nella richiesta:

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

Nota: per motivi di sicurezza, è consigliabile richiedere l'autenticazione per la chiamata della funzione HTTP. Se necessario, puoi abilitare la chiamata non autenticata dopo il deployment della funzione.

Esegui la pulizia

Al termine del tutorial, puoi eliminare tutto ciò che hai creato per non incorrere in ulteriori costi.

Terraform ti consente di rimuovere tutte le risorse definite nel file di configurazione eseguendo il comando terraform destroy nella directory terraform-docs-samples/functions/basic contenente il file main.tf:

terraform destroy

Inserisci yes per consentire a Terraform di eliminare le risorse.