Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Procedure consigliate per la struttura e l'organizzazione della base di codice

La struttura e l'organizzazione corrette della base di codice sono fondamentali poiché l'utilizzo di Terraform cresce tra team e aziende di grandi dimensioni. Una base di codice ben architettata consente la collaborazione su larga scala migliorando al contempo la manutenibilità.

Questa sezione fornisce consigli sulla modularità di Terraform, sulle convenzioni di denominazione, sulla documentazione e sugli standard di codifica che supportano qualità e coerenza.

Le linee guida includono la suddivisione della configurazione in moduli riutilizzabili per ambiente e componenti, la definizione di convenzioni di denominazione utilizzando prefissi e suffissi, la documentazione dei moduli e la spiegazione chiara di input e output e l'applicazione di regole di formattazione coerenti utilizzando controlli di stile automatici.

Le migliori pratiche aggiuntive riguardano l'organizzazione logica di moduli e risorse in una gerarchia strutturata, la catalogazione di moduli pubblici e privati nella documentazione e l'astrazione dei dettagli di implementazione non necessari nei moduli per semplificarne l'utilizzo.

Implementando le linee guida sulla struttura del codice base relative a modularità, documentazione, standard e organizzazione logica, puoi supportare un'ampia collaborazione tra i team mantenendo Terraform gestibile man mano che l'utilizzo si diffonde all'interno dell'organizzazione. Applicando convenzioni e standard, è possibile evitare la complessità di una base di codice frammentata.

Implementa una struttura di repository standard

Si consiglia di implementare il seguente layout di repository. La standardizzazione su queste pratiche di coerenza tra i moduli migliora la reperibilità, la trasparenza, l'organizzazione e l'affidabilità, consentendo al contempo il riutilizzo in molte configurazioni Terraform.

Struttura del modulo principale

Terraform viene sempre eseguito nel contesto di un singolo modulo root. Una configurazione Terraform completa consiste in un modulo root e nell'albero dei moduli figlio (che include i moduli chiamati dal modulo root, tutti i moduli chiamati da tali moduli e così via).

Esempio di base del layout del modulo root Terraform:

.
├── data.tf
├── envs
│   ├── dev
│   │   └── terraform.tfvars
│   ├── prod
│   │   └── terraform.tfvars
│   └── test
│       └── terraform.tfvars
├── locals.tf
├── main.tf
├── outputs.tf
├── providers.tf
├── README.md
├── terraform.tfvars
├── variables.tf
└── versions.tf

Struttura del modulo riutilizzabile

I moduli riutilizzabili seguono gli stessi concetti dei moduli root. Per definire un modulo, create una nuova directory e inserite .tf i file al suo interno, proprio come fareste con un modulo root. Terraform può caricare i moduli da percorsi relativi locali o da repository remoti. Se prevedi che un modulo venga riutilizzato da molte configurazioni, inseriscilo nel suo repository di controllo della versione. È importante mantenere l'albero dei moduli relativamente piatto per facilitare il riutilizzo dei moduli in combinazioni diverse.

Esempio di base del layout del modulo riutilizzabile Terraform:

.
├── data.tf
├── examples
│   ├── multi-az-new-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   ├── versions.tf
│   │   └── vpc.tf
│   └── single-az-existing-vpc
│   │   ├── data.tf
│   │   ├── locals.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   ├── README.md
│   │   ├── terraform.tfvars
│   │   ├── variables.tf
│   │   └── versions.tf
├── iam.tf
├── locals.tf
├── main.tf
├── outputs.tf
├── README.md
├── variables.tf
└── versions.tf

Struttura per la modularità

In linea di principio, puoi combinare qualsiasi risorsa e altri costrutti in un modulo, ma un uso eccessivo di moduli annidati e riutilizzabili può rendere più difficile la comprensione e la manutenzione della configurazione complessiva di Terraform, quindi usa questi moduli con moderazione.

Quando ha senso, suddividi la configurazione in moduli riutilizzabili che aumentano il livello di astrazione descrivendo un nuovo concetto nell'architettura costruito con tipi di risorse.

Quando modularizzate l'infrastruttura in definizioni riutilizzabili, puntate a set logici di risorse anziché a singoli componenti o raccolte eccessivamente complesse.

Non racchiudete singole risorse

Non dovreste creare moduli che siano involucri sottili attorno ad altri tipi di risorse singole. Se hai difficoltà a trovare un nome per il tuo modulo che sia diverso dal nome del tipo di risorsa principale al suo interno, probabilmente il modulo non sta creando una nuova astrazione, ma sta aggiungendo complessità non necessarie. Utilizza invece il tipo di risorsa direttamente nel modulo chiamante.

Incapsula le relazioni logiche

Raggruppa set di risorse correlate come basi di rete, livelli di dati, controlli di sicurezza e applicazioni. Un modulo riutilizzabile dovrebbe incapsulare componenti dell'infrastruttura che interagiscono per abilitare una funzionalità.

Mantieni invariata l'ereditarietà

Quando annidi i moduli nelle sottodirectory, evita di approfondire più di uno o due livelli. Strutture ereditarie profondamente annidate complicano le configurazioni e la risoluzione dei problemi. I moduli devono basarsi su altri moduli, non creare tunnel attraverso di essi.

Concentrando i moduli su raggruppamenti di risorse logiche che rappresentano modelli di architettura, i team possono configurare rapidamente basi infrastrutturali affidabili. Bilancia l'astrazione senza ingegnerizzare o semplificare eccessivamente.

Risorse di riferimento negli output

Per ogni risorsa definita in un modulo riutilizzabile, includi almeno un output che faccia riferimento alla risorsa. Le variabili e gli output consentono di dedurre le dipendenze tra moduli e risorse. Senza alcun output, gli utenti non possono ordinare correttamente il modulo in relazione alle loro configurazioni Terraform.

Moduli ben strutturati che forniscono coerenza ambientale, raggruppamenti mirati e riferimenti alle risorse esportati consentono la collaborazione Terraform a livello di organizzazione su larga scala. I team possono assemblare l'infrastruttura partendo da elementi costitutivi riutilizzabili.

Non configurare i provider

Sebbene i moduli condivisi ereditino i provider dai moduli di chiamata, i moduli non dovrebbero configurare autonomamente le impostazioni del provider. Evita di specificare i blocchi di configurazione del provider nei moduli. Questa configurazione deve essere dichiarata solo una volta a livello globale.

Dichiarare i provider richiesti

Sebbene le configurazioni dei provider siano condivise tra i moduli, i moduli condivisi devono inoltre dichiarare i propri requisiti di provider. Questa pratica consente a Terraform di garantire che esista un'unica versione del provider compatibile con tutti i moduli della configurazione e di specificare l'indirizzo di origine che funge da identificatore globale (indipendente dal modulo) per il provider. Tuttavia, i requisiti del provider specifici del modulo non specificano nessuna delle impostazioni di configurazione che determinano a quali endpoint remoti accederà il provider, ad esempio un. Regione AWS

Dichiarando i requisiti di versione ed evitando la configurazione del provider codificata, i moduli forniscono portabilità e riusabilità tra le configurazioni Terraform utilizzando provider condivisi.

Per i moduli condivisi, definisci le versioni minime richieste del provider in un blocco required_providers in. versions.tf

Per dichiarare che un modulo richiede una particolare versione del AWS provider, usa un blocco all'interno di un required_providers blocco: terraform

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0.0"
    }
  }
}

Se un modulo condiviso supporta solo una versione specifica del AWS provider, utilizzate l'operatore di vincolo pessimistico (~>), che consente solo al componente della versione più a destra di incrementare:

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

In questo esempio, ~> 4.0 consente l'installazione di and but not. 4.57.1 4.67.0 5.0.0 Per ulteriori informazioni, vedete Version Constraint Syntax nella documentazione. HashiCorp

Segui le convenzioni di denominazione

Nomi chiari e descrittivi semplificano la comprensione delle relazioni tra le risorse del modulo e lo scopo dei valori di configurazione. La coerenza con le linee guida di stile migliora la leggibilità sia per gli utenti che per i manutentori del modulo.

Segui le linee guida per la denominazione delle risorse

Segui le linee guida per la denominazione delle variabili

Usa le risorse relative agli allegati

Alcune risorse contengono delle pseudo-risorse incorporate come attributi. Ove possibile, dovresti evitare di utilizzare questi attributi di risorsa incorporati e utilizzare invece la risorsa unica per allegare quella pseudo-risorsa. Queste relazioni tra le risorse possono causare cause-and-effect problemi unici per ogni risorsa.

Utilizzando un attributo incorporato (evita questo schema):

resource "aws_security_group" "allow_tls" {
  ...
  ingress {
    description      = "TLS from VPC"
    from_port        = 443
    to_port          = 443
    protocol         = "tcp"
    cidr_blocks      = [aws_vpc.main.cidr_block]
    ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }
}

Utilizzo delle risorse relative agli allegati (preferito):

resource "aws_security_group" "allow_tls" {
  ...
}

resource "aws_security_group_rule" "example" {
  type              = "ingress"
  description      = "TLS from VPC"
  from_port        = 443
  to_port          = 443
  protocol         = "tcp"
  cidr_blocks      = [aws_vpc.main.cidr_block]
  ipv6_cidr_blocks = [aws_vpc.main.ipv6_cidr_block]
  security_group_id = aws_security_group.allow_tls.id
}

Usa tag predefiniti

Assegna tag a tutte le risorse che possono accettare tag. Il Terraform AWS Provider ha una fonte di dati aws_default_tags che dovresti usare all'interno del modulo root.

Prendi in considerazione l'aggiunta dei tag necessari a tutte le risorse create da un modulo Terraform. Ecco un elenco di possibili tag da allegare:

Soddisfa i requisiti del registro Terraform

Un repository di moduli deve soddisfare tutti i seguenti requisiti per poter essere pubblicato su un registro Terraform.

Dovresti sempre seguire questi requisiti anche se non hai intenzione di pubblicare il modulo in un registro a breve termine. In questo modo, è possibile pubblicare il modulo in un registro in un secondo momento senza dover modificare la configurazione e la struttura del repository.

Per ulteriori informazioni, consulta Preparazione di un repository di moduli nella documentazione di Terraform.

Usa i sorgenti dei moduli consigliati

Terraform utilizza l'sourceargomento in un blocco di modulo per trovare e scaricare il codice sorgente di un modulo figlio.

Ti consigliamo di utilizzare percorsi locali per moduli strettamente correlati che hanno lo scopo principale di estrarre elementi di codice ripetuti e di utilizzare un registro di moduli Terraform nativo o un provider VCS per moduli destinati a essere condivisi da più configurazioni.

Gli esempi seguenti illustrano i tipi di sorgenti più comuni e consigliati per la condivisione dei moduli. I moduli di registro supportano il controllo delle versioni. È necessario fornire sempre una versione specifica, come illustrato negli esempi seguenti.

Registro

Registro Terraform:

module "lambda" {
  source = "github.com/terraform-aws-modules/terraform-aws-lambda.git?ref=e78cdf1f82944897ca6e30d6489f43cf24539374" #--> v4.18.0

  ...

}

Aggiungendo gli hash di commit, è possibile evitare la deviazione dai registri pubblici che sono vulnerabili agli attacchi alla catena di approvvigionamento.

HCP Terraform:

module "eks_karpenter" {
  source = "app.terraform.io/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

Terraform Enterprise:

module "eks_karpenter" {
  source = "terraform.mydomain.com/my-org/eks/aws"
  version = "1.1.0"

  ...

  enable_karpenter = true
}

Fornitori di VCS

I provider VCS supportano l'refargomento a favore della selezione di una revisione specifica, come illustrato negli esempi seguenti.

GitHub (HTTPS):

module "eks_karpenter" {
  source = "github.com/my-org/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Archivio Git generico (HTTPS):

module "eks_karpenter" {
  source = "git::https://example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Archivio Git generico (SSH):

module "eks_karpenter" {
  source = "git::ssh://username@example.com/terraform-aws-eks.git?ref=v1.1.0"

  ...

  enable_karpenter = true
}

Segui gli standard di codifica

Applica regole e stili di formattazione Terraform coerenti su tutti i file di configurazione. Applica gli standard utilizzando controlli di stile automatizzati nelle pipeline CI/CD. Quando incorpori le migliori pratiche di codifica nei flussi di lavoro dei team, le configurazioni rimangono leggibili, gestibili e collaborative anche se l'utilizzo si diffonde ampiamente all'interno dell'organizzazione.

Segui le linee guida di stile

Configura gli hook di pre-commit

Configura gli hook di pre-commit sul lato client che eseguono e terraform fmt eseguono altre scansioni del codice e controlli di stile prima di consentire i commit. tflint checkov Questa pratica consente di convalidare la conformità agli standard nelle fasi iniziali dei flussi di lavoro degli sviluppatori.

Usa framework di pre-commit come pre-commit per aggiungere il linting, la formattazione e la scansione del codice Terraform come hook sul tuo computer locale. Gli hook vengono eseguiti su ogni commit Git e falliscono il commit se i controlli non vengono superati.

Lo spostamento dei controlli di stile e qualità negli hook locali di pre-commit fornisce un feedback rapido agli sviluppatori prima che vengano introdotte le modifiche. Gli standard entrano a far parte del flusso di lavoro di codifica.