Richtlinien für Stacks

Oracle empfiehlt, allgemeine Terraform-Best Practices zum Erstellen Ihrer Terraform-Vorlage zu übernehmen. Es gibt jedoch spezifische Marketplace-Stackstandards, die befolgt werden müssen, um einen Stack zu veröffentlichen.

Obligatorische Richtlinien

Im Folgenden finden Sie obligatorische Richtlinien für Stacks, die im Oracle Cloud Infrastructure Marketplace aufgeführt sind. Jede Richtlinie muss befolgt werden. Vor der Veröffentlichung wird jedes Stackartefakt anhand jeder dieser Richtlinien validiert.

  1. Das Stackartefakt muss eine ZIP-Datei mit den Terraform-Konfigurationsdateien und einer Schemadatei sein.
    • Die ZIP-Datei muss mindestens eine Konfigurationsdatei (.tf) im Stammordner enthalten.
    • Die ZIP-Datei muss die Schemadatei (.yaml) im Stammordner enthalten.
    • ZIP-Datei darf keine Terraform-Statusdatei in der ZIP-Datei enthalten. Statusdateien werden von Oracle Resource Manager (ORM) verwaltet. Wenn Kunden einen Stack starten, erstellt und verwaltet ORM die Ressourcen, und die Statusdatei steht nur zum Download zur Verfügung.
    • ZIP-Datei darf den Terraform-Laufzeitkonfigurationsordner (.terraform). nicht enthalten
  2. Die Terraform-Konfiguration darf nur Instanzimages verwenden, die genehmigte oder veröffentlichte (öffentliche oder private) Marketplace-Images sind. Sie muss über ein Marketplace-Abonnement für jedes dieser Images verfügen. Es muss hartcodierte Referenz(en) zu diesen Marketplace-Images enthalten. Weitere Informationen finden Sie unter Terraform-Beispielkonfiguration für ein Marketplace-Imageabonnement und eine Nutzung.
  3. Binärdateien dürfen nicht aus externen Repositorys heruntergeladen werden. Alle Binärdateien und Abhängigkeiten müssen in das veröffentlichte Marketplace-Image eingebettet werden.
  4. Der Terraform-Remoteausführungs-Provisioner darf nur innerhalb der Oracle Cloud Infrastructure-Domain ausgeführt werden. Es darf keine Dateien auf einen Remoteserver herunterladen.
  5. Code oder Binärdateien von Drittanbietern dürfen nicht mit cloud-init. heruntergeladen werden
    1. cloud-init ist ein häufig verwendetes Utility zur Startkonfiguration für Cloud-Compute-Instanzen. Es akzeptiert die Konfiguration über Benutzerdatenmechanismen, die als Teil der Metadatendefinition auf der Ressource oci_core_instance angegeben sind.
    2. Es gibt mehrere Benutzerdatenformate, die von cloud-init. unterstützt werden Siehe https://cloudinit.readthedocs.io/en/latest/topics/format.html.
    3. Unabhängig vom Benutzerdatenformat darf cloud-init NICHT zum Herunterladen von Code oder Binärdateien von Drittanbietern verwendet werden. Alle Binärdateien, die während des Instanzstartprozesses (Bootstrap) erforderlich sind, sollten von einem Prozess (Skript), der als Teil der Imageverteilung gebacken wird, heruntergeladen werden, und nicht über cloud-init injiziert werden (z.B. unter Verwendung von wget).
    4. Möglicherweise ist jedoch eine cloud-init-Vorlage eingerichtet, die Kunden in bestimmten Szenarios verwenden können, z.B. um eine Lizenzschlüsseldatei zu importieren oder um eine Konfigurationsdatei zu importieren. In diesem Fall müssen Sie eine Variable im Terraform-Vorlagencode angeben, damit Kunden einige Daten in den cloud-init-Baustein eingeben können, z.B. mit der Terraform-Datenquelle template_file.
  6. Der Terraform-Provider muss Oracle Cloud Infrastructure sein. Andere Cloud-Anbieter oder Drittanbieter von Anwendungen werden nicht unterstützt.
  7. Wenn ein Terraform-Modul verwendet wird, muss es aus lokalen relativen Pfaden geladen werden. Es kann nicht aus einem Remote Repository geladen werden.
  8. Die Terraform-Konfiguration muss die Instanz-Principal-Authentifizierung verwenden.
  9. Sie müssen die minimalen und maximalen unterstützten Terraform-Versionen angeben, auf denen Sie den Stack getestet haben.

    • Geben Sie die mindestens erforderliche Terraform-Version im Format ~> <major_version>.<minor_version>.<patch_version> an.

      Dabei wird patch_version immer auf 0 gesetzt. Wenn ein Stack gestartet wird, prüft Resource Manager die <major_version>.<minor_version>, die Sie in Ihrem Code definiert haben, und verwendet die neueste verfügbare Patchversion. Aus diesem Grund müssen Sie das ~>-Zeichen anstelle des =>-Signals verwenden, während Sie die mindestens erforderliche Terraform-Version angeben.

      Beispiel: ~> 0.14.0 gibt an, dass die unterstützten Terraform-Versionen 0.14.0 oder höher sind.

    • Geben Sie die maximal erforderliche Terraform-Version im Format < <major_version>.<minor_version> an.

      Beispiel: < 0.15 gibt an, dass die unterstützten Terraform-Versionen vor 0,15 liegen.

    Das folgende Beispiel zeigt, wie Sie die minimale und die maximale unterstützte Terraform-Version angeben, wenn Sie Ihren Stack nur auf Terraform 0.14 getestet haben.

    terraform 
    { required_version = "~> 0.14.0, < 0.15" }

Weitere Informationen zu Terraform, einschließlich des Oracle Cloud Infrastructure-Providers, der Instanz-Principal-Authentifizierung und des Remoteausführungs-Provisioners, finden Sie in der Terraform-Dokumentation für die Providerkonfiguration. Informationen zu unterstützten Versionen von Terraform finden Sie unter Erste Schritte mit dem Terraform-Provider in der Oracle Cloud Infrastructure-Dokumentation.

Codierungsrichtlinien für Terraform-Konfigurationen

Die folgenden Richtlinien werden für Stacks empfohlen, die im Oracle Cloud Infrastructure Marketplace aufgeführt sind. Jede Richtlinie gilt als Best Practice, die nach Möglichkeit befolgt werden sollte.

  • Das Stackartefakt muss es Kunden ermöglichen, entweder alle Infrastrukturressourcen zu erstellen oder auf vorhandene Ressourcen (Netzwerk, Speicher usw.) zu verweisen.
  • Benennungskonventionen und Formatierungen sollten befolgt werden:
    • Groß-/Kleinschreibung: Verwenden Sie lower_snake_case für alle Benennungen. Dies gilt für Variablennamen, Ressourcennamen, Modulnamen, Dateinamen, Anzeigenamen usw.
    • Angeben des Ressourcentyps - Nehmen Sie den Ressourcen- oder Datenquellentyp nicht in den Namen auf. In Terraform werden Ressourcen und Datenquellen immer von <type>.<name>. referenziert Daher ist es nicht erforderlich, den Typ in den Namen selbst aufzunehmen.
    • ID ggü. OCID - In Oracle Cloud Infrastructure bezieht sich id im Allgemeinen auf ein Feld, das eine OCID annimmt. Daher sollten Variablen id verwenden, wenn sie auf OCID-Werte verweisen, anstatt ocid zu verwenden.
    • Variablennamen - Variablennamen für Oracle Cloud Infrastructure-Ressourcen müssen in der Regel denselben Namen verwenden wie für die Terraform-Ressource.
    • Anzeigenamen: Anzeigenamen für Oracle Cloud Infrastructure-Ressourcen müssen in der Regel denselben Namen verwenden wie für die Terraform-Ressource.
    • Benennungsmodulvariablen und -ausgaben - Bei Verwendung eines Moduls sollten die Benennung der Eingabe (Variablen) und der Ausgaben dem Aufrufer angezeigt werden.
    • terraform fmt muss auf alle Terraform angewendet werden, bevor es eingecheckt wird.