Best Practices für wiederverwendbare Module

Dieses Dokument enthält Richtlinien und Empfehlungen für die Verwendung wiederverwendbarer Terraform-Module.

Dieser Leitfaden ist keine Einführung in Terraform. Eine Einführung in die Verwendung von Terraform mit Google Cloud finden Sie unter Erste Schritte mit Terraform.

Erforderliche APIs in Modulen aktivieren

Terraform-Module können alle erforderlichen Dienste mithilfe der Ressource google_project_service oder des Moduls project_services aktivieren. Die Einbindung der API-Aktivierung erleichtert die Demonstration.

  • Wenn die API-Aktivierung in einem Modul enthalten ist, muss die API-Aktivierung deaktivierbar sein. Stellen Sie dazu eine Variable enable_apis bereit, die standardmäßig auf true gesetzt ist.

  • Wenn die API-Aktivierung in einem Modul enthalten ist, muss die API-Aktivierung disable_services_on_destroy auf false gesetzt sein, da dieses Attribut Probleme verursachen kann, wenn Sie mit mehreren Instanzen des Moduls arbeiten.

    Beispiel:

    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
}

Inhaberdatei hinzufügen

Fügen Sie für alle freigegebenen Module eine OWNERS-Datei (oder CODEOWNERS auf GitHub) ein, die dokumentiert, wer für das Modul verantwortlich ist. Bevor eine Pull-Anfrage zusammengeführt wird, sollte sie von einem Inhaber genehmigt werden.

Getaggte Versionen veröffentlichen

Manchmal sind für Module funktionsgefährdende Änderungen erforderlich und Sie müssen die Auswirkungen den Nutzern mitteilen, damit diese ihre Konfigurationen an eine bestimmte Version binden können.

Achten Sie darauf, dass freigegebene Module SemVer v2.0.0 folgen, wenn neue Versionen getaggt oder veröffentlicht werden.

Verwenden Sie beim Verweis auf ein Modul eine Versionseinschränkung, um eine Bindung an die Hauptversion vorzunehmen. Beispiele:

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

Keine Anbieter oder Back-Ends konfigurieren

Freigegebene Module dürfen keine Anbieter oder Back-Ends konfigurieren. Stattdessen müssen Anbieter und Back-Ends in Stammmodulen konfiguriert werden.

Definieren Sie für freigegebene Module die mindestens erforderlichen Anbieterversionen so in einem required_providers-Block:

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

Sofern nicht anders angegeben, sollten Sie davon ausgehen, dass neue Anbieterversionen funktionieren.

Labels als Variable bereitstellen

Ermöglichen Sie flexible Labels für Ressourcen über die Modulschnittstelle. Sie können eine labels-Variable mit einer leeren Zuordnung als Standardwert so bereitstellen:

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

Ausgaben für alle Ressourcen bereitstellen

Anhand von Variablen und Ausgaben können Sie Abhängigkeiten zwischen Modulen und Ressourcen ableiten. Ohne Ausgaben können Nutzer Ihr Modul in Bezug auf seine Terraform-Konfigurationen nicht ordnungsgemäß sortieren.

Fügen Sie für jede in einem freigegebenen Modul definierte Ressource mindestens eine Ausgabe ein, die auf die Ressource verweist.

Inline-Untermodule für komplexe Logik verwenden

  • Mit Inline-Modulen können Sie komplexe Terraform-Module in kleinere Einheiten organisieren und gemeinsame Ressourcen deduplizieren.
  • Platzieren Sie Inline-Module in modules/$modulename.
  • Behandeln Sie Inline-Module als private Module, die nicht von externen Modulen verwendet werden sollen, es sei denn, in der Dokumentation des freigegebenen Moduls ist dies anders angegeben.
  • Terraform verfolgt keine refaktorierten Ressourcen. Wenn Sie mit mehreren Ressourcen im obersten Modul beginnen und sie dann in Untermodule übertragen, versucht Terraform, alle refaktorierten Ressourcen neu zu erstellen. Verwenden Sie bei der Refaktorierung moved-Blöcke, um dieses Verhalten zu umgehen.
  • Durch interne Module definierte Ausgaben werden nicht automatisch bereitgestellt. Wenn Sie Ausgaben von internen Modulen freigeben möchten, exportieren Sie sie noch einmal.

Nächste Schritte