Best Practices für Stammmodule

Dieses Dokument enthält Richtlinien und Empfehlungen für die Verwendung von Stammmodulen.

Stammkonfigurationen oder Stammmodule sind die Arbeitsverzeichnisse, von denen aus Sie die Terraform-Befehlszeile ausführen. Achten Sie darauf, dass Stammkonfigurationen die folgenden Standards (und gegebenenfalls die vorherigen Terraform-Richtlinien) einhalten. Explizite Empfehlungen für Stammmodule haben Vorrang vor den allgemeinen Richtlinien.

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.

Anzahl der Ressourcen pro Stammmodul minimieren

Es ist wichtig, dass eine einzelne Stammkonfiguration nicht zu groß wird, weil zu viele Ressourcen im selben Verzeichnis und im selben Zustand gespeichert sind. Alle Ressourcen in einer bestimmten Stammkonfiguration werden bei jeder Ausführung von Terraform aktualisiert. Dies kann zu einer langsamen Ausführung führen, wenn zu viele Ressourcen in einem einzigen Zustand enthalten sind. Eine allgemeine Regel lautet: Fügen Sie nicht mehr als 100 Ressourcen (und idealerweise nur wenige Dutzend) in einem einzigen Zustand hinzu.

Separate Verzeichnisse für jede Anwendung verwenden

Um Anwendungen und Projekte unabhängig voneinander zu verwalten, platzieren Sie Ressourcen für jede Anwendung und jedes Projekt in ihren eigenen Terraform-Verzeichnissen. Ein Dienst kann eine bestimmte Anwendung oder einen gemeinsamen Dienst wie freigegebene Netzwerke darstellen. Verschachteln Sie den gesamten Terraform-Code für einen bestimmten Dienst in einem einzigen Verzeichnis (einschließlich Unterverzeichnissen).

Anwendungen in umgebungsspezifische Unterverzeichnisse aufteilen

Teilen Sie beim Bereitstellen von Diensten in Google Cloud die Terraform-Konfiguration für den Dienst in zwei oberste Verzeichnisse auf: ein modules-Verzeichnis, das die tatsächliche Konfiguration des Dienstes enthält, und ein environments-Verzeichnis, das die Stammkonfigurationen für jede Umgebung enthält.

-- SERVICE-DIRECTORY/
   -- OWNERS
   -- modules/
      -- <service-name>/
         -- main.tf
         -- variables.tf
         -- outputs.tf
         -- provider.tf
         -- README
      -- ...other…
   -- environments/
      -- dev/
         -- backend.tf
         -- main.tf

      -- qa/
         -- backend.tf
         -- main.tf

      -- prod/
         -- backend.tf
         -- main.tf

Umgebungsverzeichnisse verwenden

Verweisen Sie auf Module, um Code umgebungsübergreifend freizugeben. In der Regel kann dies ein Dienstmodul sein, das die gemeinsame Terraform-Basiskonfiguration für den Dienst enthält. In Dienstmodulen sollten Sie allgemeine Eingaben hartcodieren und nur umgebungsspezifische Eingaben als Variablen erforderlich machen.

Dieses Umgebungsverzeichnis muss die folgenden Dateien enthalten:

  • Eine backend.tf-Datei, die den Terraform-backend-Zustandsspeicherort angibt (normalerweise Cloud Storage)
  • Eine main.tf-Datei, die das Dienstmodul instanziiert

Jedes Umgebungsverzeichnis (dev, qa, prod) entspricht einem Terraform-Standardarbeitsbereich und stellt eine Version des Dienstes für diese Umgebung bereit. Diese Arbeitsbereiche isolieren umgebungsspezifische Ressourcen in ihren eigenen Kontexten. Verwenden Sie nur den Standardarbeitsbereich.

Mehrere CLI-Arbeitsbereiche innerhalb einer Umgebung werden aus folgenden Gründen nicht empfohlen:

  • Es kann schwierig sein, die Konfiguration in jedem Arbeitsbereich zu prüfen.
  • Ein einzelnes freigegebenes Backend für mehrere Arbeitsbereiche wird nicht empfohlen, da das freigegebene Backend für die Umgebungstrennung zu einem Single Point of Failure wird.
  • Die Wiederverwendung von Code ist zwar möglich, aber der Code ist schwieriger zu lesen und muss basierend auf der aktuellen Arbeitsbereichsvariable (z. B. terraform.workspace == "foo" ? this : that) geändert werden.

Hier finden Sie weitere Informationen:

Ausgaben über den Remotezustand bereitstellen

Achten Sie darauf, dass Sie nützliche Ausgaben von Modulinstanzen aus einem Stammmodul zur Verfügung stellen.

Das folgende Code-Snippet leitet beispielsweise die Projekt-ID-Ausgabe der Projekt-Factory-Modulinstanz als Ausgabe des Stammmoduls weiter.

# Project root module
terraform {
  backend "gcs" {
    bucket  = "BUCKET"
  }
}

module "project" {
  source  = "terraform-google-modules/project-factory/google"
  ...
}

output "project_id" {
  value       = module.project.project_id
  description = "The ID of the created project"
}

Andere Terraform-Umgebungen und -Anwendungen können nur auf Ausgaben auf Stammmodulebene verweisen.

Mithilfe des Remotezustands können Sie auf die Ausgaben des Stammmoduls verweisen. Wenn Sie die Verwendung durch andere abhängige Anwendungen für die Konfiguration zulassen möchten, exportieren Sie Informationen, die sich auf die Endpunkte eines Dienstes beziehen, in den Remotezustand.

# Networks root module
data "terraform_remote_state" "network_project" {
  backend = "gcs"

  config = {
    bucket = "BUCKET"
  }
}

module "vpc" {
  source  = "terraform-google-modules/network/google"
  version = "~> 9.0"

  project_id   = data.terraform_remote_state.network_project.outputs.project_id
  network_name = "vpc-1"
  ...
}

Manchmal ist es sinnvoll, das gesamte untergeordnete Modul so zu exportieren, wenn eine freigegebenes Dienstmodul aus Umgebungsverzeichnissen aufgerufen wird:

output "service" {
  value       = module.service
  description = "The service module outputs"
}

Bindung an Nebenanbieterversionen vornehmen

Deklarieren Sie in Stammmodulen jeden Anbieter und nehmen Sie eine Bindung an eine Nebenversion vor. Dies ermöglicht ein automatisches Upgrade auf neue Patchreleases unter Beibehaltung eines soliden Ziels. Aus Konsistenzgründen sollten Sie die Versionsdatei versions.tf nennen.

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

Variablen in einer tfvars-Datei speichern

Geben Sie für Stammmodule Variablen mithilfe einer .tfvars-Variablendatei an. Nennen Sie Variablendateien aus Konsistenzgründen terraform.tfvars.

Geben Sie Variablen nicht mit den alternativen Befehlszeilenoptionen var-files oder var='key=val' an. Befehlszeilenoptionen sind sitzungsspezifisch und werden leicht vergessen. Die Verwendung einer Standardvariablendatei ist vorhersehbarer.

.terraform.lock.hcl-Datei einchecken

Bei Root-Modulen sollte die Abhängigkeitssperre .terraform.lock.hcl in die Versionsverwaltung eingecheckt werden. Damit können Sie die Änderungen der Anbieterauswahl für eine bestimmte Konfiguration verfolgen und prüfen.

Nächste Schritte