Best practice per i moduli principali

Questo documento fornisce linee guida e suggerimenti da considerare quando si utilizzano i moduli principali.

Le configurazioni root o i moduli principali sono le directory di lavoro da cui esegui l'interfaccia a riga di comando di Terraform. Assicurati che le configurazioni root rispettino gli standard seguenti (e le precedenti linee guida di Terraform, se applicabili). I suggerimenti espliciti per i moduli principali hanno la precedenza sulle 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 evitare che una singola configurazione root diventi troppo grande, con troppe risorse archiviate nella stessa directory e nello stesso stato. Tutte le risorse di una determinata configurazione root vengono aggiornate ogni volta che viene eseguito Terraform. Ciò può causare un'esecuzione lenta se sono incluse troppe risorse in un unico stato. Una regola generale: non includere più di 100 risorse (e idealmente solo qualche decina) in un unico stato.

Usa directory separate per ogni applicazione

Per gestire applicazioni e progetti in modo indipendente, inserisci le risorse per ogni applicazione e progetto nelle rispettive directory Terraform. Un servizio potrebbe rappresentare una particolare applicazione o un servizio comune come il networking condiviso. Nidifica tutto il codice Terraform per un determinato servizio in una directory (incluse le sottodirectory).

Suddividi le applicazioni in sottodirectory specifiche per l'ambiente

Quando esegui il deployment di servizi in Google Cloud, suddividi la configurazione Terraform per il servizio in due directory di primo livello: una directory modules contenente la configurazione effettiva del servizio e una directory environments contenente 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

Utilizza le directory di ambiente

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

Ogni directory di ambiente deve contenere i seguenti file:

  • Un file backend.tf, che dichiara la posizione dello stato del backend di Terraform (in genere Cloud Storage)
  • Un file main.tf che crea un'istanza del modulo di servizio

Ogni directory di ambiente (dev, qa, prod) corrisponde a un'area di lavoro Terraform predefinita ed esegue il deployment di una versione del servizio in quell'ambiente. Queste aree di lavoro isolano le risorse specifiche dell'ambiente nei rispettivi contesti. Utilizza solo l'area di lavoro predefinita.

Non è consigliabile avere più aree di lavoro dell'interfaccia a riga di comando 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ù aree di lavoro perché il backend condiviso diventa un single point of failure se viene utilizzato per la separazione degli ambienti.
  • Sebbene sia possibile riutilizzare il codice, diventa più difficile leggere il codice dover cambiare in base alla variabile dell'area di lavoro corrente (ad esempio, terraform.workspace == "foo" ? this : that).

Per ulteriori informazioni, consulta le seguenti risorse:

Esponi gli output tramite stato remoto

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

Ad esempio, il seguente snippet di codice passa attraverso 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 principali a livello di modulo.

Utilizzando lo stato remoto, puoi fare riferimento agli output dei moduli principali. Per consentire l'utilizzo da parte di altre app dipendenti per la configurazione, assicurati di esportare in stato remoto le informazioni relative agli endpoint di un servizio.

# 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 richiami un modulo di servizio condiviso dalle directory dell'ambiente, è opportuno esportare nuovamente l'intero modulo figlio, come segue:

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

Fissa sulle versioni secondarie del provider

Nei moduli principali, dichiara ogni provider e bloccalo a una versione secondaria. Ciò consente l'upgrade automatico alle nuove patch mantenendo un obiettivo consolidato. Per coerenza, assegna al file delle versioni il nome versions.tf.

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

Archivia le variabili in un file tfvars

Per i moduli principali, fornisci le variabili usando un file di variabili .tfvars. Per uniformità, assegna un nome ai file di variabili terraform.tfvars.

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

Controlla in .terraform.lock.hcl file

Per i moduli principali, il file di blocco delle dipendenze .terraform.lock.hcl deve essere registrato nel controllo del codice sorgente. Ciò consente di monitorare e rivedere le modifiche nelle selezioni dei provider per una determinata configurazione.

Passaggi successivi