Best practice per i moduli principali

Questo documento fornisce linee guida e consigli da prendere in considerazione quando si utilizzano i moduli principali.

Le configurazioni o i moduli principali sono le directory di lavoro da cui esegui l'interfaccia a riga di comando Terraform. Assicurati che le configurazioni principali rispettino i seguenti standard (e le linee guida Terraform precedenti, se applicabili). I consigli espliciti per i moduli principali sostituiscono le linee guida generali.

Questa guida non è un'introduzione a Terraform. Per un'introduzione all'utilizzo di Terraform con Google Cloud, consulta la guida introduttiva all'utilizzo di Terraform.

Riduci al minimo il numero di risorse in ogni modulo principale

È importante impedire a una singola configurazione principale di diventare troppo grande, con troppe risorse archiviate nella stessa directory e nello stesso stato. Tutte le risorse di una determinata configurazione principale vengono aggiornate ogni volta che viene eseguito Terraform. Ciò può causare un'esecuzione lenta se in un singolo stato sono incluse troppe risorse. Una regola generale: non includere più di 100 risorse (e idealmente solo alcune decine) in un singolo stato.

Utilizza directory separate per ogni applicazione

Per gestire le applicazioni e i progetti in modo indipendente, inserisci le risorse per ogni applicazione e progetto nelle rispettive directory Terraform. Un servizio potrebbe rappresentare una determinata applicazione o un servizio comune come la condivisione della rete. Raggruppa tutto il codice Terraform per un determinato servizio in una directory (incluse le sottodirectory).

Suddividere le applicazioni in sottodirectory specifiche per l'ambiente

Quando esegui il deployment dei servizi in Google Cloud, dividi la configurazione Terraform per il servizio in due directory di primo livello: una directory modules che contiene la configurazione effettiva del servizio e una directory environments che contiene le configurazioni principali per ogni ambiente.

-- SERVICE-DIRECTORY/
   -- OWNERS
   -- modules/
      -- <service-name>/
         -- main.tf
         -- variables.tf
         -- outputs.tf
         -- provider.tf
         -- README
      -- ...other…
   -- environments/
      -- dev/
         -- backend.tf
         -- main.tf

      -- qa/
         -- backend.tf
         -- main.tf

      -- prod/
         -- backend.tf
         -- main.tf

Utilizzare le directory dell'ambiente

Per condividere il codice tra ambienti, fai riferimento ai moduli. In genere, potrebbe trattarsi di un modulo di servizio che include la configurazione di Terraform condivisa di base per il servizio. Nei moduli di servizio, codifica gli input comuni e richiedi solo input specifici per l'ambiente come variabili.

Ogni directory dell'ambiente deve contenere i seguenti file:

  • Un file backend.tf che dichiara la posizione dello stato del backend Terraform (in genere Cloud Storage)
  • Un file main.tf che esegue l'inizializzazione del modulo di servizio

Ogni directory dell'ambiente (dev, qa, prod) corrisponde a un spazio di lavoro Terraform predefinito e esegue il deployment di una versione del servizio in quell'ambiente. Questi spazi di lavoro isoleranno le risorse specifiche dell'ambiente nei rispettivi contesti. Utilizza solo lo spazio di lavoro predefinito.

Non è consigliabile avere più spazi di lavoro CLI all'interno di un ambiente per i seguenti motivi:

  • Può essere difficile ispezionare la configurazione in ogni area di lavoro.
  • Non è consigliabile avere un unico backend condiviso per più spazi di lavoro perché diventa un singolo punto di errore se viene utilizzato per la separazione dell'ambiente.
  • Sebbene il riutilizzo del codice sia possibile, il codice diventa più difficile da leggere perché deve cambiare in base alla variabile dello spazio di lavoro corrente (ad esempioterraform.workspace == "foo" ? this : that).

Per ulteriori informazioni, consulta le seguenti risorse:

Esporre gli output tramite lo stato remoto

Assicurati di esporre output utili delle istanze del modulo da un modulo principale.

Ad esempio, il seguente snippet di codice passa l'output dell'ID progetto dall'istanza del modulo di fabbrica del progetto come output del modulo principale.

# Project root module
terraform {
  backend "gcs" {
    bucket  = "BUCKET"
  }
}

module "project" {
  source  = "terraform-google-modules/project-factory/google"
  ...
}

output "project_id" {
  value       = module.project.project_id
  description = "The ID of the created project"
}

Altri ambienti e applicazioni Terraform possono fare riferimento solo agli output di livello del modulo principale.

Utilizzando lo stato remoto, puoi fare riferimento alle uscite del modulo principale. Per consentire l'utilizzo da parte di altre app dipendenti per la configurazione, assicurati di esportare le informazioni relative agli endpoint di un servizio nello stato remoto.

# Networks root module
data "terraform_remote_state" "network_project" {
  backend = "gcs"

  config = {
    bucket = "BUCKET"
  }
}

module "vpc" {
  source  = "terraform-google-modules/network/google"
  version = "~> 9.0"

  project_id   = data.terraform_remote_state.network_project.outputs.project_id
  network_name = "vpc-1"
  ...
}

A volte, ad esempio quando viene chiamato un modulo di servizio condiviso dalle directory dell'ambiente, è opportuno esportare nuovamente l'intero modulo secondario, come segue:

output "service" {
  value       = module.service
  description = "The service module outputs"
}

Bloccare le versioni secondarie del fornitore

Nei moduli principali, dichiara ogni provider e fissalo a una versione secondaria. In questo modo, è possibile eseguire l'upgrade automatico alle nuove release delle patch mantenendo un obiettivo solido. Per coerenza, assegna al file delle versioni il nome versions.tf.

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 4.0.0"
    }
  }
}

Memorizzare le variabili in un file tfvars

Per i moduli principali, fornisci le variabili utilizzando un file di variabili .tfvars. Per mantenere la coerenza, assegna ai file delle variabili il nome terraform.tfvars.

Non specificare le variabili utilizzando opzioni di riga di comando alternative var-files o var='key=val'. Le opzioni della riga di comando sono effimere e facili da dimenticare. L'utilizzo di un file di variabili predefinite è più prevedibile.

Controlla il file .terraform.lock.hcl

Per i moduli principali, il file .terraform.lock.hcl dependency lock deve essere sottoposto a controllo del codice sorgente. In questo modo è possibile monitorare e esaminare le modifiche alle selezioni dei fornitori per una determinata configurazione.

Passaggi successivi