Bewährte Methoden für die Struktur und Organisation der Codebasis - AWS Präskriptive Leitlinien

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Bewährte Methoden für die Struktur und Organisation der Codebasis

Die richtige Struktur und Organisation der Codebasis ist entscheidend, da die Nutzung von Terraform in großen Teams und Unternehmen zunimmt. Eine gut strukturierte Codebasis ermöglicht eine Zusammenarbeit in großem Maßstab und verbessert gleichzeitig die Wartbarkeit.

Dieser Abschnitt enthält Empfehlungen zur Modularität von Terraform, zu Namenskonventionen, zur Dokumentation und zu Codierungsstandards, die Qualität und Konsistenz unterstützen.

Zu den Anleitungen gehören die Aufteilung der Konfiguration in wiederverwendbare Module nach Umgebung und Komponenten, die Festlegung von Namenskonventionen mithilfe von Präfixen und Suffixen, die Dokumentation von Modulen und die klare Erläuterung von Eingaben und Ausgaben sowie die Anwendung konsistenter Formatierungsregeln mithilfe automatisierter Stilprüfungen.

Weitere bewährte Methoden umfassen die logische Organisation von Modulen und Ressourcen in einer strukturierten Hierarchie, die Katalogisierung öffentlicher und privater Module in der Dokumentation und die Zusammenfassung unnötiger Implementierungsdetails in Modulen, um die Verwendung zu vereinfachen.

Durch die Implementierung von Richtlinien für die Codebasisstruktur in Bezug auf Modularität, Dokumentation, Standards und logische Organisation können Sie eine breite Zusammenarbeit zwischen Teams unterstützen und gleichzeitig dafür sorgen, dass Terraform auch dann gewartet werden kann, wenn sich die Nutzung innerhalb eines Unternehmens verbreitet. Durch die Durchsetzung von Konventionen und Standards können Sie die Komplexität einer fragmentierten Codebasis vermeiden.

Implementieren Sie eine Standard-Repository-Struktur

Wir empfehlen Ihnen, das folgende Repository-Layout zu implementieren. Die modulübergreifende Standardisierung dieser Konsistenzpraktiken verbessert die Auffindbarkeit, Transparenz, Organisation und Zuverlässigkeit und ermöglicht gleichzeitig die Wiederverwendung in vielen Terraform-Konfigurationen.

  • Stammmodul oder Verzeichnis: Dies sollte der primäre Einstiegspunkt sowohl für Terraform-Root - als auch für wiederverwendbare Terraform-Module sein und es wird erwartet, dass es einzigartig ist. Wenn Sie eine komplexere Architektur haben, können Sie verschachtelte Module verwenden, um einfache Abstraktionen zu erstellen. Auf diese Weise können Sie die Infrastruktur anhand ihrer Architektur beschreiben, anstatt sie direkt anhand physischer Objekte zu beschreiben.

  • README: Das Root-Modul und alle verschachtelten Module sollten README-Dateien enthalten. Diese Datei muss benannt werden. README.md Sie sollte eine Beschreibung des Moduls und dessen Verwendungszweck enthalten. Wenn Sie ein Beispiel für die Verwendung dieses Moduls mit anderen Ressourcen hinzufügen möchten, legen Sie es in ein examples Verzeichnis. Erwägen Sie, ein Diagramm beizufügen, das die Infrastrukturressourcen, die das Modul möglicherweise erstellt, und deren Beziehungen darstellt. Verwenden Sie Terraform-Docs, um automatisch Eingaben oder Ausgaben des Moduls zu generieren.

  • main.tf: Dies ist der primäre Einstiegspunkt. Für ein einfaches Modul könnten alle Ressourcen in dieser Datei erstellt werden. Bei einem komplexen Modul kann die Ressourcenerstellung auf mehrere Dateien verteilt sein, aber alle verschachtelten Modulaufrufe sollten sich in der main.tf Datei befinden.

  • variables.tf und outputs.tf: Diese Dateien enthalten die Deklarationen für Variablen und Ausgaben. Alle Variablen und Ausgaben sollten Beschreibungen mit einem oder zwei Sätzen enthalten, die ihren Zweck erläutern. Diese Beschreibungen werden zur Dokumentation verwendet. Weitere Informationen finden Sie in der HashiCorp Dokumentation zur Variablenkonfiguration und zur Ausgabekonfiguration.

    • Alle Variablen müssen einen definierten Typ haben.

    • Die Variablendeklaration kann auch ein Standardargument enthalten. Wenn die Deklaration ein Standardargument enthält, wird die Variable als optional betrachtet, und der Standardwert wird verwendet, wenn Sie beim Aufrufen des Moduls oder beim Ausführen von Terraform keinen Wert festlegen. Das Standardargument erfordert einen Literalwert und kann nicht auf andere Objekte in der Konfiguration verweisen. Um eine Variable erforderlich zu machen, lassen Sie einen Standard in der Variablendeklaration weg und überlegen Sie, ob die Einstellung nullable = false sinnvoll ist.

    • Geben Sie für Variablen mit umgebungsunabhängigen Werten (z. B.disk_size) Standardwerte an.

    • Geben Sie für Variablen mit umgebungsspezifischen Werten (z. B.project_id) keine Standardwerte an. In diesem Fall muss das aufrufende Modul aussagekräftige Werte bereitstellen.

    • Verwenden Sie leere Standardwerte für Variablen wie leere Zeichenketten oder Listen nur, wenn das Leerlassen der Variablen eine gültige Einstellung ist, die von den zugrunde liegenden APIs nicht abgelehnt wird.

    • Gehen Sie bei der Verwendung von Variablen mit Bedacht vor. Parametrisieren Sie Werte nur, wenn sie für jede Instanz oder Umgebung variieren müssen. Wenn Sie entscheiden, ob eine Variable verfügbar gemacht werden soll, stellen Sie sicher, dass Sie einen konkreten Anwendungsfall für die Änderung dieser Variablen haben. Wenn nur eine geringe Wahrscheinlichkeit besteht, dass eine Variable benötigt wird, machen Sie sie nicht verfügbar.

      • Das Hinzufügen einer Variablen mit einem Standardwert ist abwärtskompatibel.

      • Das Entfernen einer Variablen ist abwärtsinkompatibel.

      • In Fällen, in denen ein Literal an mehreren Stellen wiederverwendet wird, sollten Sie einen lokalen Wert verwenden, ohne ihn als Variable verfügbar zu machen.

    • Übergeben Sie Ausgaben nicht direkt über Eingabevariablen, da sie dadurch nicht ordnungsgemäß zum Abhängigkeitsdiagramm hinzugefügt werden können. Um sicherzustellen, dass implizite Abhängigkeiten erstellt werden, stellen Sie sicher, dass Referenzattribute von Ressourcen ausgegeben werden. Anstatt direkt auf eine Eingabevariable für eine Instanz zu verweisen, übergeben Sie das Attribut.

  • locals.tf: Diese Datei enthält lokale Werte, die einem Ausdruck einen Namen zuweisen, sodass ein Name innerhalb eines Moduls mehrfach verwendet werden kann, anstatt den Ausdruck zu wiederholen. Lokale Werte sind wie die temporären lokalen Variablen einer Funktion. Die Ausdrücke in lokalen Werten sind nicht auf Literalkonstanten beschränkt. Sie können auch auf andere Werte im Modul verweisen, darunter Variablen, Ressourcenattribute oder andere lokale Werte, um sie zu kombinieren.

  • providers.tf: Diese Datei enthält den Terraform-Block und die Provider-Blöcke. providerBlöcke dürfen nur in Root-Modulen von Modulkonsumenten deklariert werden.

    Wenn Sie HCP Terraform verwenden, fügen Sie auch einen leeren Cloud-Block hinzu. Der cloud Block sollte als Teil einer CI/CD-Pipeline vollständig über Umgebungsvariablen und Anmeldeinformationen für Umgebungsvariablen konfiguriert werden.

  • versions.tf: Diese Datei enthält den Block required_providers. Alle Terraform-Module müssen deklarieren, welche Anbieter sie benötigen, damit Terraform diese Anbieter installieren und verwenden kann.

  • data.tf: Platzieren Sie zur einfachen Konfiguration Datenquellen neben den Ressourcen, die auf sie verweisen. Wenn Sie beispielsweise ein Bild abrufen, das beim Starten einer Instanz verwendet werden soll, platzieren Sie es neben der Instanz, anstatt Datenressourcen in einer eigenen Datei zu sammeln. Wenn die Anzahl der Datenquellen zu groß wird, sollten Sie erwägen, sie in eine spezielle data.tf Datei zu verschieben.

  • .tfvars-Dateien: Für Root-Module können Sie nicht sensible Variablen mithilfe einer Datei bereitstellen. .tfvars Benennen Sie die Variablendateien aus Konsistenzgründen. terraform.tfvars Platzieren Sie allgemeine Werte im Stammverzeichnis des Repositorys und umgebungsspezifische Werte innerhalb des envs/ Ordners.

  • Verschachtelte Module: Verschachtelte Module sollten im Unterverzeichnis existieren. modules/ Jedes verschachtelte Modul, das über eine verfügt, README.md wird von einem externen Benutzer als nutzbar angesehen. Wenn a nicht README.md existiert, wird das Modul nur für den internen Gebrauch in Betracht gezogen. Verschachtelte Module sollten verwendet werden, um komplexes Verhalten in mehrere kleine Module aufzuteilen, die Benutzer sorgfältig auswählen können.

    Wenn das Root-Modul Aufrufe verschachtelter Module enthält, sollten diese Aufrufe relative Pfade verwenden, ./modules/sample-module sodass Terraform sie beispielsweise als Teil desselben Repositorys oder Pakets betrachtet, anstatt sie erneut separat herunterzuladen.

    Wenn ein Repository oder Paket mehrere verschachtelte Module enthält, sollten sie idealerweise vom Aufrufer zusammengesetzt werden können, anstatt sich gegenseitig direkt aufzurufen und einen tief verschachtelten Modulbaum zu erstellen.

  • Beispiele: Beispiele für die Verwendung eines wiederverwendbaren Moduls sollten sich im examples/ Unterverzeichnis im Stammverzeichnis des Repositorys befinden. Für jedes Beispiel können Sie eine README-Datei hinzufügen, um das Ziel und die Verwendung des Beispiels zu erläutern. Beispiele für Submodule sollten ebenfalls im Stammverzeichnis examples/ abgelegt werden.

    Da Beispiele häufig zur Anpassung in andere Repositorien kopiert werden, sollte der Quelltext von Modulblöcken auf die Adresse gesetzt werden, die ein externer Aufrufer verwenden würde, und nicht auf einen relativen Pfad.

  • Dateien mit Dienstnamen: Benutzer möchten Terraform-Ressourcen häufig nach Diensten in mehreren Dateien trennen. Von dieser Praxis sollte so weit wie möglich abgeraten werden, und Ressourcen sollten stattdessen definiert werden. main.tf Wenn eine Sammlung von Ressourcen (z. B. IAM-Rollen und -Richtlinien) jedoch mehr als 150 Zeilen umfasst, ist es sinnvoll, sie in eigene Dateien aufzuteilen, wie z. iam.tf Andernfalls sollte der gesamte Ressourcencode in der main.tf definiert werden.

  • Benutzerdefinierte Skripte: Verwenden Sie Skripten nur bei Bedarf. Terraform berücksichtigt oder verwaltet den Status von Ressourcen, die mithilfe von Skripten erstellt werden, nicht. Verwenden Sie benutzerdefinierte Skripts nur, wenn Terraform-Ressourcen das gewünschte Verhalten nicht unterstützen. Platzieren Sie von Terraform aufgerufene benutzerdefinierte Skripte in einem Verzeichnis. scripts/

  • Hilfsskripte: Organisieren Sie Hilfsskripte, die nicht von Terraform aufgerufen werden, in einem Verzeichnis. helpers/ Dokumentieren Sie Hilfsskripte in der README.md Datei mit Erklärungen und Beispielaufrufen. Wenn Hilfsskripten Argumente akzeptieren, bieten sie eine Argumentüberprüfung und --help Ausgabe an.

  • Statische Dateien: Statische Dateien, auf die Terraform verweist, die aber nicht ausgeführt werden (z. B. auf EC2-Instances geladene Startskripte), müssen in einem Verzeichnis organisiert werden. files/ Platzieren Sie umfangreiche Dokumente getrennt von ihrer HCL in externen Dateien. Verweisen Sie mit der Funktion file () auf sie.

  • Vorlagen: Verwenden Sie für Dateien, die die Terraform-Funktion templatefile einliest, die Dateierweiterung. .tftpl Vorlagen müssen in einem Verzeichnis abgelegt werden. templates/

Struktur des Stammmoduls

Terraform läuft immer im Kontext eines einzelnen Root-Moduls. Eine vollständige Terraform-Konfiguration besteht aus einem Root-Modul und dem Baum der untergeordneten Module (einschließlich der Module, die vom Root-Modul aufgerufen werden, aller Module, die von diesen Modulen aufgerufen werden, usw.).

Grundlegendes Beispiel für das Layout des Terraform-Root-Moduls:

. ├── 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

Wiederverwendbare Modulstruktur

Wiederverwendbare Module folgen den gleichen Konzepten wie Root-Module. Um ein Modul zu definieren, erstellen Sie ein neues Verzeichnis dafür und platzieren Sie die .tf Dateien darin, genau wie Sie ein Root-Modul definieren würden. Terraform kann Module entweder aus lokalen relativen Pfaden oder aus Remote-Repositorys laden. Wenn Sie erwarten, dass ein Modul von vielen Konfigurationen wiederverwendet wird, platzieren Sie es in einem eigenen Versionskontroll-Repository. Es ist wichtig, den Modulbaum relativ flach zu halten, um die Wiederverwendung der Module in verschiedenen Kombinationen zu erleichtern.

Grundlegendes Beispiel für das Layout eines wiederverwendbaren Terraform-Moduls:

. ├── 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

Struktur für Modularität

Im Prinzip können Sie beliebige Ressourcen und andere Konstrukte zu einem Modul kombinieren. Wenn Sie jedoch zu viele verschachtelte und wiederverwendbare Module verwenden, kann dies das Verständnis und die Wartung Ihrer gesamten Terraform-Konfiguration erschweren. Verwenden Sie diese Module daher in Maßen.

Wenn es sinnvoll ist, teilen Sie Ihre Konfiguration in wiederverwendbare Module auf, die die Abstraktionsebene erhöhen, indem Sie ein neues Konzept in Ihrer Architektur beschreiben, das aus Ressourcentypen aufgebaut ist.

Wenn Sie Ihre Infrastruktur in wiederverwendbare Definitionen modularisieren, sollten Sie logische Ressourcensätze anstelle von einzelnen Komponenten oder übermäßig komplexen Sammlungen anstreben.

Verpacken Sie keine einzelnen Ressourcen

Sie sollten keine Module erstellen, die nur eine dünne Hülle für andere einzelne Ressourcentypen bilden. Wenn Sie Probleme haben, einen Namen für Ihr Modul zu finden, der sich vom Namen des darin enthaltenen Hauptressourcentyps unterscheidet, erstellt Ihr Modul wahrscheinlich keine neue Abstraktion — es fügt unnötige Komplexität hinzu. Verwenden Sie stattdessen den Ressourcentyp direkt im aufrufenden Modul.

Kapseln Sie logische Beziehungen

Gruppieren Sie Gruppen verwandter Ressourcen wie Netzwerkgrundlagen, Datenebenen, Sicherheitskontrollen und Anwendungen. Ein wiederverwendbares Modul sollte Infrastrukturkomponenten kapseln, die zusammenarbeiten, um eine Funktion zu aktivieren.

Halten Sie die Erbschaft flach

Wenn Sie Module in Unterverzeichnissen verschachteln, vermeiden Sie es, mehr als ein oder zwei Ebenen tief zu gehen. Tief verschachtelte Vererbungsstrukturen erschweren Konfigurationen und Problembehebungen. Module sollten auf anderen Modulen aufbauen und keine Tunnel durch sie bauen.

Durch die Fokussierung der Module auf logische Ressourcengruppierungen, die Architekturmuster darstellen, können Teams schnell zuverlässige Infrastrukturgrundlagen konfigurieren. Ausgewogene Abstraktion ohne übertriebene Technik oder zu starke Vereinfachung.

Referenzressourcen in den Ergebnissen

Fügen Sie für jede Ressource, die in einem wiederverwendbaren Modul definiert ist, mindestens eine Ausgabe hinzu, die auf die Ressource verweist. Mit Variablen und Ausgaben können Sie Abhängigkeiten zwischen Modulen und Ressourcen ableiten. Ohne Ausgaben können Benutzer Ihr Modul nicht richtig in Bezug auf ihre Terraform-Konfigurationen bestellen.

Gut strukturierte Module, die eine konsistente Umgebung, zweckorientierte Gruppierungen und exportierte Ressourcenreferenzen bieten, ermöglichen eine unternehmensweite Terraform-Zusammenarbeit in großem Maßstab. Teams können die Infrastruktur aus wiederverwendbaren Bausteinen zusammenstellen.

Konfigurieren Sie keine Anbieter

Obwohl gemeinsam genutzte Module Anbieter von aufrufenden Modulen erben, sollten Module die Anbietereinstellungen nicht selbst konfigurieren. Vermeiden Sie die Angabe von Provider-Konfigurationsblöcken in Modulen. Diese Konfiguration sollte nur einmal global deklariert werden.

Deklarieren Sie die erforderlichen Anbieter

Obwohl die Anbieterkonfigurationen von allen Modulen gemeinsam genutzt werden, müssen gemeinsam genutzte Module auch ihre eigenen Anbieteranforderungen deklarieren. Diese Vorgehensweise ermöglicht es Terraform, sicherzustellen, dass es eine einzige Version des Anbieters gibt, die mit allen Modulen in der Konfiguration kompatibel ist, und die Quelladresse anzugeben, die als globale (modulunabhängige) Kennung für den Anbieter dient. Die modulspezifischen Anbieteranforderungen spezifizieren jedoch keine der Konfigurationseinstellungen, die bestimmen, auf welche Remote-Endpunkte der Anbieter zugreift, z. B. auf. AWS-Region

Durch die Deklaration von Versionsanforderungen und die Vermeidung einer fest codierten Anbieterkonfiguration bieten Module Portabilität und Wiederverwendbarkeit in allen Terraform-Konfigurationen mithilfe gemeinsam genutzter Anbieter.

Definieren Sie für gemeinsam genutzte Module die mindestens erforderlichen Anbieterversionen in einem required_providers-Block in. versions.tf

Um zu deklarieren, dass ein Modul eine bestimmte Version des AWS Anbieters benötigt, verwenden Sie einen required_providers Block innerhalb eines terraform Blocks:

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

Wenn ein gemeinsam genutztes Modul nur eine bestimmte Version des AWS Anbieters unterstützt, verwenden Sie den pessimistischen Einschränkungsoperator (~>), mit dem nur die Versionskomponente ganz rechts inkrementiert werden kann:

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

~> 4.0Erlaubt in diesem Beispiel die Installation von und, aber nicht. 4.57.1 4.67.0 5.0.0 Weitere Informationen finden Sie in der HashiCorp Dokumentation unter Syntax von Versionseinschränkungen.

Beachten Sie die Namenskonventionen

Klare, aussagekräftige Namen erleichtern Ihnen das Verständnis der Beziehungen zwischen Ressourcen im Modul und des Zwecks von Konfigurationswerten. Die Einhaltung der Stilrichtlinien verbessert die Lesbarkeit sowohl für Benutzer als auch für Entwickler des Moduls.

Folgen Sie den Richtlinien für die Benennung von Ressourcen

  • Verwenden Sie snake_case (wobei Begriffe in Kleinbuchstaben durch Unterstriche getrennt werden) für alle Ressourcennamen, um den Standards im Terraform-Stil zu entsprechen. Diese Vorgehensweise gewährleistet die Konsistenz mit der Namenskonvention für Ressourcentypen, Datenquellentypen und andere vordefinierte Werte. Diese Konvention gilt nicht für Namensargumente.

  • Um Verweise auf eine Ressource zu vereinfachen, die die einzige Ressource ihres Typs ist (z. B. ein einzelner Load Balancer für ein ganzes Modul), geben Sie der Ressource einen Namen main oder der Übersichtlichkeit this halber.

  • Verwenden Sie aussagekräftige Namen, die den Zweck und den Kontext der Ressource beschreiben und dabei helfen, zwischen ähnlichen Ressourcen zu unterscheiden (z. B. primary für die Hauptdatenbank und read_replica für eine Read Replica der Datenbank).

  • Verwenden Sie Namen im Singular, nicht im Plural.

  • Wiederholen Sie den Ressourcentyp nicht im Ressourcennamen.

Folgen Sie den Richtlinien für die Benennung von Variablen

  • Fügen Sie den Namen von Eingaben, lokalen Variablen und Ausgaben Einheiten hinzu, die numerische Werte wie Festplattengröße oder RAM-Größe darstellen (z. B. ram_size_gb für die RAM-Größe in Gigabyte). Diese Vorgehensweise macht die zu erwartende Eingabeeinheit für Konfigurationsbetreuer deutlich.

  • Verwenden Sie binäre Einheiten wie MiB und GiB für Speichergrößen und Dezimaleinheiten wie MB oder GB für andere Metriken.

  • Geben Sie booleschen Variablen positive Namen wie. enable_external_access

Verwenden Sie Ressourcen für Dateianhänge

In einigen Ressourcen sind Pseudoressourcen als Attribute eingebettet. Wenn möglich, sollten Sie die Verwendung dieser eingebetteten Ressourcenattribute vermeiden und stattdessen die eindeutige Ressource verwenden, um diese Pseudoressource anzuhängen. Diese Ressourcenbeziehungen können zu cause-and-effect Problemen führen, die für jede Ressource einzigartig sind.

Verwenden eines eingebetteten Attributs (vermeiden Sie dieses Muster):

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"] } }

Verwenden von Ressourcen für Anlagen (bevorzugt):

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 }

Verwenden Sie Standard-Tags

Weisen Sie allen Ressourcen, die Tags akzeptieren können, Tags zu. Der Terraform AWS Provider verfügt über eine aws_default_tags-Datenquelle, die Sie im Root-Modul verwenden sollten.

Erwägen Sie, allen Ressourcen, die von einem Terraform-Modul erstellt wurden, die erforderlichen Tags hinzuzufügen. Hier ist eine Liste möglicher Tags, die angehängt werden können:

  • Name: Für Menschen lesbarer Ressourcenname

  • AppId: Die ID für die Anwendung, die die Ressource verwendet

  • AppRole: Die technische Funktion der Ressource, zum Beispiel „Webserver“ oder „Datenbank“

  • AppPurpose: Der Geschäftszweck der Ressource, zum Beispiel „Frontend-UI“ oder „Zahlungsabwickler“

  • Umgebung: Die Softwareumgebung, z. B. Entwicklung, Test oder Produktion

  • Projekt: Die Projekte, die die Ressource verwenden

  • CostCenter: Wem muss der Ressourcenverbrauch in Rechnung gestellt werden

Erfüllen Sie die Terraform-Registrierungsanforderungen

Ein Modul-Repository muss alle folgenden Anforderungen erfüllen, damit es in einer Terraform-Registry veröffentlicht werden kann.

Sie sollten diese Anforderungen immer einhalten, auch wenn Sie nicht vorhaben, das Modul kurzfristig in einer Registry zu veröffentlichen. Auf diese Weise können Sie das Modul später in einer Registrierung veröffentlichen, ohne die Konfiguration und Struktur des Repositorys ändern zu müssen.

  • Repository-Name: Verwenden Sie für ein Modul-Repository den dreiteiligen Namenterraform-aws-<NAME>, der die Art der Infrastruktur <NAME> widerspiegelt, die das Modul verwaltet. Das <NAME> Segment kann zusätzliche Bindestriche enthalten (z. B.). terraform-aws-iam-terraform-roles

  • Standardmodulstruktur: Das Modul muss der Standard-Repository-Struktur entsprechen. Auf diese Weise kann die Registry Ihr Modul überprüfen und Dokumentation erstellen, die Ressourcennutzung verfolgen und vieles mehr.

    • Nachdem Sie das Git-Repository erstellt haben, kopieren Sie die Moduldateien in das Stammverzeichnis des Repositorys. Wir empfehlen, dass Sie jedes Modul, das wiederverwendet werden soll, im Stammverzeichnis eines eigenen Repositorys ablegen. Sie können aber auch Module aus Unterverzeichnissen referenzieren.

    • Wenn Sie HCP Terraform verwenden, veröffentlichen Sie die Module, die gemeinsam genutzt werden sollen, in Ihrer Organisationsregistrierung. Die Registrierung verarbeitet Downloads und steuert den Zugriff mit HCP Terraform API-Token, sodass Verbraucher keinen Zugriff auf das Quell-Repository des Moduls benötigen, selbst wenn sie Terraform über die Befehlszeile ausführen.

  • Standort und Berechtigungen: Das Repository muss sich bei einem Ihrer konfigurierten Anbieter für Versionskontrollsysteme (VCS) befinden, und das HCP Terraform VCS-Benutzerkonto muss Administratorzugriff auf das Repository haben. Die Registrierung benötigt Administratorzugriff, um die Webhooks zum Importieren neuer Modulversionen zu erstellen.

  • x.y.z-Tags für Releases: Es muss mindestens ein Release-Tag vorhanden sein, damit Sie ein Modul veröffentlichen können. Die Registrierung verwendet Release-Tags, um Modulversionen zu identifizieren. Namen von Release-Tags müssen eine semantische Versionierung verwenden, der Sie optional ein Präfix v (z. B. v1.1.0 und1.1.0) voranstellen können. Die Registrierung ignoriert Tags, die nicht wie Versionsnummern aussehen. Weitere Informationen zum Veröffentlichen von Modulen finden Sie in der Terraform-Dokumentation.

Weitere Informationen finden Sie unter Vorbereiten eines Modul-Repositorys in der Terraform-Dokumentation.

Verwenden Sie die empfohlenen Modulquellen

Terraform verwendet das source Argument in einem Modulblock, um den Quellcode für ein untergeordnetes Modul zu finden und herunterzuladen.

Wir empfehlen, lokale Pfade für eng verwandte Module zu verwenden, die den Hauptzweck haben, wiederholte Codeelemente auszuschließen, und eine native Terraform-Modulregistrierung oder einen VCS-Anbieter für Module zu verwenden, die von mehreren Konfigurationen gemeinsam genutzt werden sollen.

Die folgenden Beispiele veranschaulichen die gängigsten und empfohlenen Quelltypen für die gemeinsame Nutzung von Modulen. Registrierungsmodule unterstützen die Versionierung. Sie sollten immer eine bestimmte Version angeben, wie in den folgenden Beispielen gezeigt.

Registrierung

Terraform-Registrierung:

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

Indem Sie Commit-Hashes anheften, können Sie verhindern, dass öffentliche Register verlassen, die anfällig für Angriffe auf die Lieferkette sind.

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 }

VCS-Anbieter

VCS-Anbieter unterstützen das ref Argument für die Auswahl einer bestimmten Revision, wie in den folgenden Beispielen gezeigt.

GitHub (HTTPS):

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

Generisches Git-Repository (HTTPS):

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

Generisches Git-Repository (SSH):

Warnung

Sie müssen Anmeldeinformationen konfigurieren, um auf private Repositorys zugreifen zu können.

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

Befolgen Sie die Codierungsstandards

Wenden Sie konsistente Terraform-Formatierungsregeln und -Stile für alle Konfigurationsdateien an. Setzen Sie Standards durch, indem Sie automatisierte Stilprüfungen in CI/CD-Pipelines verwenden. Wenn Sie bewährte Programmierpraktiken in Team-Workflows integrieren, bleiben die Konfigurationen lesbar, wartbar und kollaborativ, da sich die Nutzung im gesamten Unternehmen verbreitet.

Halten Sie sich an die Stilrichtlinien

  • Formatieren Sie alle Terraform-Dateien (.tfDateien) mit dem Befehl terraform fmt so, dass sie den Stilstandards entsprechen. HashiCorp

  • Verwenden Sie den Befehl terraform validate, um die Syntax und Struktur Ihrer Konfiguration zu überprüfen.

  • Analysieren Sie die Codequalität statisch mithilfe von TFLint. Dieser Linter sucht nach bewährten Methoden von Terraform, die über die bloße Formatierung hinausgehen, und schlägt beim Erstellen fehl, wenn Fehler auftreten.

Konfigurieren Sie Pre-Commit-Hooks

Konfigurieren Sie clientseitige Pre-Commit-Hooks, dieterraform fmt, tflintcheckov, und andere Codescans und Stilprüfungen ausführen, bevor Sie Commits zulassen. Diese Vorgehensweise hilft Ihnen, die Einhaltung von Standards zu einem früheren Zeitpunkt in Entwickler-Workflows zu überprüfen.

Verwenden Sie Pre-Commit-Frameworks wie Pre-Commit, um Terraform-Linting, Formatierung und Code-Scanning als Hooks auf Ihrem lokalen Computer hinzuzufügen. Hooks werden bei jedem Git-Commit ausgeführt und schlagen beim Commit fehl, wenn die Prüfungen nicht bestanden werden.

Durch die Verlagerung von Stil- und Qualitätsprüfungen auf lokale Pre-Commit-Hooks erhalten Entwickler schnelles Feedback, bevor Änderungen eingeführt werden. Standards werden Teil des Codierungs-Workflows.