Best practice per lo stile e la struttura generali

Questo documento fornisce suggerimenti di stile e struttura di base per Configurazioni di Terraform. Questi suggerimenti si applicano a Terraform riutilizzabile ai moduli di memoria e alle configurazioni principali.

Questa guida non è un'introduzione a Terraform. Per un'introduzione all'utilizzo Terraform con Google Cloud, consulta Inizia a utilizzare Terraform.

Seguire una struttura di moduli standard

  • I moduli Terraform devono seguire le struttura standard del modulo.
  • Inizia ogni modulo con un file main.tf, in cui si trovano le risorse, predefinito.
  • In ogni modulo, includi un file README.md in formato Markdown. Nella README.md, includi la documentazione di base sul modulo.
  • Inserisci gli esempi in una cartella examples/, con una sottodirectory separata per per ciascun esempio. Per ogni esempio, includi un file README.md dettagliato.
  • Creare raggruppamenti logici di risorse con i propri file e nomi descrittivi, ad esempio network.tf, instances.tf o loadbalancer.tf.
    • Evita di assegnare a ogni risorsa il proprio file. Raggruppa le risorse per il loro scopo comune. Ad esempio, combina google_dns_managed_zone e google_dns_record_set a dns.tf.
  • Nella directory root del modulo, includi solo Terraform (*.tf) e file di metadati del repository (come README.md e CHANGELOG.md).
  • Inserisci eventuale documentazione aggiuntiva in una sottodirectory docs/.

Adotta una convenzione di denominazione

  • Assegna a tutti gli oggetti di configurazione un nome con trattini bassi per delimitare più elementi parole. Questa prassi garantisce la coerenza con la convenzione di denominazione per i tipi di risorse, i tipi di origini dati e altri valori predefiniti. Questo convenzione non si applica al nome argomenti.

    Consigliato:

    resource "google_compute_instance" "web_server" {
      name = "web-server"
    }
    

    Sconsigliato:

    resource "google_compute_instance" "web-server" {
      name = "web-server"
    }
    
  • Per semplificare i riferimenti a una risorsa che è l'unica del suo tipo (ad esempio, un singolo bilanciatore del carico per un intero modulo), denomina il nome la risorsa main.

    • Occorre un lavoro mentale extra per ricordare some_google_resource.my_special_resource.id contro some_google_resource.main.id.
  • Per differenziare tra loro risorse dello stesso tipo (ad esempio, primary e secondary), fornisci nomi significativi per le risorse.

  • Rendi i nomi delle risorse singolari.

  • Non ripetere il tipo di risorsa nel nome della risorsa. Ad esempio:

    Consigliato:

    resource "google_compute_global_address" "main" { ... }
    

    Sconsigliato:

    resource "google_compute_global_address" "main_global_address" { … }
    

Utilizza le variabili con attenzione

  • Dichiara tutte le variabili in variables.tf.
  • Assegna alle variabili nomi descrittivi pertinenti al loro utilizzo oppure scopo:
    • Input, variabili locali e output che rappresentano valori numerici come le dimensioni del disco o della RAM, devono essere denominati con (ad esempio ram_size_gb). Le API Google Cloud non dispongono di standard unità, quindi denominare le variabili con unità rende dell'unità di input cancellata per i responsabili della configurazione.
    • Per le unità di archiviazione, utilizza i prefissi delle unità binarie (potenze di 1024): kibi, mebi e gibi. Per tutte le altre unità di misura, utilizza il decimale prefissi di unità (potenza di 1000): kilo, mega, giga. Questo utilizzo e l'utilizzo in Google Cloud.
    • Per semplificare la logica condizionale, assegna nomi positivi alle variabili booleane, ad esempio ad esempio enable_external_access.
  • Le variabili devono avere descrizioni. Le descrizioni vengono incluse nella documentazione generata automaticamente di un modulo pubblicato. Le descrizioni aggiungono ulteriore contesto per i nuovi sviluppatori. non possono essere forniti.
  • Assegna i tipi definiti per le variabili.
  • Se opportuno, fornisci valori predefiniti:
    • Per le variabili che hanno valori indipendenti dall'ambiente (come il disco size), fornisci valori predefiniti.
    • Per le variabili che hanno valori specifici dell'ambiente (come project_id), non fornire valori predefiniti. In questo modo, il modulo di chiamata devono fornire valori significativi.
  • Utilizza valori predefiniti vuoti per le variabili (come stringhe o elenchi vuoti) solo quando lasciare la variabile vuota è una preferenza valida per cui le API sottostanti non rifiutare.
  • Sii prudente nell'uso delle variabili. Parametrizzare solo i valori che devono variare per ogni istanza o ambiente. Nel decidere se esporre una variabile, assicurati di avere un caso d'uso concreto per modificare . Se c'è solo una piccola probabilità che una variabile sia necessaria, non esporli.
    • L'aggiunta di una variabile con un valore predefinito è compatibile con le versioni precedenti.
    • La rimozione di una variabile non è compatibile con le versioni precedenti.
    • Se un valore letterale viene riutilizzato in più luoghi, puoi utilizzare valore locale senza esporla come variabile.

Esponi gli output

  • Organizza tutti gli output in un file outputs.tf.
  • Fornisci descrizioni significative per tutti gli output.
  • Descrizioni degli output del documento nel file README.md. Generazione automatica descrizioni relative al commit con strumenti come terraform-docs
  • Restituisce tutti i valori utili a cui i moduli principali potrebbero dover fare riferimento o che potrebbero dover condividere. Esponi tutti gli output che, soprattutto per i moduli open source o molto usati, che hanno un potenziale per il consumo.
  • Non trasmettere gli output direttamente attraverso le variabili di input, perché così facendo ne impedisce l'aggiunta corretta al grafico delle dipendenze. Per garantire che dipendenze implicite assicurati che restituisca attributi di riferimento dalle risorse. Invece di fare riferimento direttamente a una variabile di input per un'istanza, passa l'attributo tramite come mostrato qui:

    Consigliato:

    output "name" {
      description = "Name of instance"
      value       = google_compute_instance.main.name
    }
    

    Sconsigliato:

    output "name" {
      description = "Name of instance"
      value       = var.name
    }
    

Utilizza le origini dati

  • Adotta origini dati accanto alle risorse che vi fanno riferimento. Ad esempio, se recuperi un'immagine da utilizzare per avviare un'istanza, posizionala accanto anziché raccogliere risorse di dati nel proprio file.
  • Se il numero di origini dati aumenta, valuta la possibilità di spostarle in un file data.tf dedicato.
  • Per recuperare i dati relativi all'ambiente attuale, usa una variabile o una risorsa interpolazione.

Limitare l'utilizzo di script personalizzati

  • Utilizza gli script solo quando necessario. Lo stato delle risorse create tramite script non viene preso in considerazione o gestito da Terraform.
    • Se possibile, evita script personalizzati. Utilizzale solo quando Terraform delle risorse non supportano il comportamento desiderato.
    • Gli script personalizzati utilizzati devono avere una motivazione chiaramente documentata per e idealmente un piano di ritiro.
  • Terraform può richiamare script personalizzati tramite provisioner, tra cui provisioner local-exec.
  • Inserisci gli script personalizzati richiamati da Terraform in una directory scripts/.

Includi script di supporto in una directory separata

  • Organizza gli script helper che non vengono chiamati da Terraform in una Directory helpers/.
  • Script helper per i documenti nel file README.md con spiegazioni e di esempio.
  • Se gli script helper accettano argomenti, fornisci il controllo degli argomenti Output --help.

Posiziona i file statici in una directory separata

  • I file statici a cui Terraform fa riferimento, ma che non esegue (ad esempio script di avvio caricati sulle istanze Compute Engine) devono essere organizzati in una directory files/.
  • Inserisci qui il lungo documento in file esterni, separati da un apposito documento. Puoi farvi riferimento utilizzando Funzione file().
  • Per i file letti tramite Terraform Funzione templatefile, utilizza l'estensione del file .tftpl.
    • I modelli devono essere posizionati in una directory templates/.

Protezione delle risorse stateful

Per le risorse stateful, come i database, assicurati che protezione da eliminazione sia abilitato. Ad esempio:

resource "google_sql_database_instance" "main" {
  name = "primary-instance"
  settings {
    tier = "D0"
  }

  lifecycle {
    prevent_destroy = true
  }
}

Usare la formattazione integrata

Tutti i file Terraform devono essere conformi agli standard di terraform fmt.

Limitare la complessità delle espressioni

  • Limita la complessità delle singole espressioni interpolate. Se sono necessarie molte funzioni in una singola espressione, considera la possibilità di suddividerla in più espressioni utilizzando valori locali.
  • Non avere mai più di un'operazione ternaria in una singola riga. Invece, utilizzare più valori locali per creare la logica.

Utilizza count per i valori condizionali

Per creare un'istanza di una risorsa in modo condizionale, utilizza Meta-argomento count. Ad esempio:

variable "readers" {
  description = "..."
  type        = list
  default     = []
}

resource "resource_type" "reference_name" {
  // Do not create this resource if the list of readers is empty.
  count = length(var.readers) == 0 ? 0 : 1
  ...
}

Presta attenzione quando utilizzi le variabili specificate dall'utente per impostare la variabile count Google Cloud. Se viene fornito un attributo di risorsa per una variabile di questo tipo (come project_id) e questa risorsa non esiste ancora, Terraform non può per generare un piano. Terraform segnala invece l'errore value of count cannot be computed In questi casi, utilizza una variabile enable_x separata per calcolare il della logica condizionale.

Usa for_each per le risorse iterate

Se vuoi creare più copie di una risorsa in base a una risorsa di input, utilizza la for_each meta-argomento.

Pubblica moduli in un registro

Passaggi successivi