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. NellaREADME.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 fileREADME.md
dettagliato. - Creare raggruppamenti logici di risorse con i propri file e
nomi descrittivi, ad esempio
network.tf
,instances.tf
oloadbalancer.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
egoogle_dns_record_set
adns.tf
.
- Evita di assegnare a ogni risorsa il proprio file. Raggruppa le risorse per
il loro scopo comune. Ad esempio, combina
- Nella directory root del modulo, includi solo Terraform
(
*.tf
) e file di metadati del repository (comeREADME.md
eCHANGELOG.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
controsome_google_resource.main.id
.
- Occorre un lavoro mentale extra per ricordare
Per differenziare tra loro risorse dello stesso tipo (ad esempio,
primary
esecondary
), 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
egibi
. 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
.
- Input, variabili locali e output che rappresentano valori numerici
come le dimensioni del disco o della RAM, devono essere denominati con
(ad esempio
- 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/
.
- I modelli devono essere posizionati in una directory
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
Moduli riutilizzabili: pubblica moduli riutilizzabili in un nel registro di moduli.
Moduli open source: pubblica moduli open source nel Terraform Registry.
Moduli privati: pubblica moduli privati in un registro privato.
Passaggi successivi
- Scopri le best practice per l'utilizzo dei moduli riutilizzabili.
- Scopri le best practice per l'utilizzo dei moduli principali di Terraform.