Best practice per i moduli riutilizzabili

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

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

Attiva le API richieste nei moduli

I moduli Terraform possono attivare tutti i servizi richiesti utilizzando la risorsa google_project_service o il modulo project_services. L'inclusione dell'attivazione dell'API semplifica le dimostrazioni.

  • Se l'attivazione dell'API è inclusa in un modulo, deve essere disattivabile esponendo una variabile enable_apis che per impostazione predefinita è true.

  • Se l'attivazione dell'API è inclusa in un modulo, deve impostare disable_services_on_destroy su false, perché questo attributo può causare problemi quando si utilizzano più istanze del modulo.

    Ad esempio:

    module "project-services" {
  source  = "terraform-google-modules/project-factory/google//modules/project_services"
  version = "~> 12.0"

  project_id  = var.project_id
  enable_apis = var.enable_apis

  activate_apis = [
    "compute.googleapis.com",
    "pubsub.googleapis.com",
  ]
  disable_services_on_destroy = false
}

Includi un file di proprietari

Per tutti i moduli condivisi, includi un file OWNERS (o CODEOWNERS su GitHub) che documenti chi è responsabile del modulo. Prima che qualsiasi richiesta di pull venga unita, un proprietario deve approvarla.

Versioni con tag di release

A volte i moduli richiedono modifiche che comportano interruzioni e devi comunicare gli effetti agli utenti in modo che possano bloccare le configurazioni su una versione specifica.

Assicurati che i moduli condivisi rispettino la versione 2.0.0 di SemVer quando vengono taggate o rilasciate nuove versioni.

Quando fai riferimento a un modulo, utilizza un vincolo di versione per bloccare la versione principale. Ad esempio:

module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google"
  version = "~> 20.0"
}

Non configurare provider o backend

I moduli condivisi non devono configurare provider o backend. Configura invece i provider e i backend nei moduli principali.

Per i moduli condivisi, definisci le versioni minime richieste dei provider in un blocco required_providers, come segue:

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

Se non viene dimostrato il contrario, presupponi che le nuove versioni del provider funzioneranno.

Esporre le etichette come variabile

Consente la flessibilità nell'etichettatura delle risorse tramite l'interfaccia del modulo. Valuta la possibilità di fornire una variabile labels con un valore predefinito di una mappa vuota, come segue:

variable "labels" {
  description = "A map of labels to apply to contained resources."
  default     = {}
  type        = "map"
}

Esponi gli output per tutte le risorse

Le variabili e gli output ti consentono di dedurre le dipendenze tra moduli e risorse. Senza output, gli utenti non possono ordinare correttamente il tuo modulo in base alle loro configurazioni Terraform.

Per ogni risorsa definita in un modulo condiviso, includi almeno un output che fa riferimento alla risorsa.

Utilizzare sottomoduli in linea per la logica complessa

  • I moduli in linea ti consentono di organizzare moduli Terraform complessi in unità più piccole e deduplicare le risorse comuni.
  • Inserisci i moduli in linea in modules/$modulename.
  • Tratta i moduli in linea come privati e non utilizzabili da moduli esterni, a meno che la documentazione del modulo condiviso non indichi esplicitamente il contrario.
  • Terraform non monitora le risorse sottoposte a refactoring. Se inizi con diverse risorse nel modulo di primo livello e poi le inserisci nei sottomoduli, Terraform tenta di ricreare tutte le risorse sottoposte a refactoring. Per attenuare questo comportamento, utilizza i blocchi moved durante il refactoring.
  • Le uscite definite dai moduli interni non vengono esposte automaticamente. Per condividere gli output dei moduli interni, esportali di nuovo.

Passaggi successivi