Oracle Cloud Infrastructure - Dokumentation

Ressourcen-Discovery verwenden

Das Ressourcen-Discovery-Feature des Oracle Cloud Infrastructure-(OCI-)Terraform-Providers verwendet terraform-exec von HashiCorp, um die erkannten OCI-Ressourcen in Terraform-Konfigurations- und Statusdateien zu importieren.

Voraussetzungen

Terraform-exec erfordert, dass die Terraform-CLI auf Ihrem System vorhanden ist. Installationsdetails finden Sie unter Terraform herunterladen und installieren.

Hinweis

Wenn Sie Terraform-Version v0.11 verwenden, kann dieses Tool keine Statusdatei generieren. In v0.11 werden nur Konfigurationen unterstützt. Standardmäßig werden die Konfigurationen in v0.12 erstellt.

Wenn Sie v0.13.* der Terraform-CLI verwenden, stellen Sie sicher, dass die Version mit der v0.12-Syntax kompatibel ist.

Außerdem muss der OCI-Terraform-Provider heruntergeladen und installiert sein. Anweisungen zum Herunterladen finden Sie unter Provider herunterladen und installieren.

Tools zum Pfad hinzufügen

Um den OCI-Terraform-Provider als ausführbare Datei auszuführen und die Ressourcen-Discovery zu verwenden, stehen Ihnen folgende Möglichkeiten zur Verfügung:

  • Fügen Sie terraform-provider-oci zu Ihrem Systempfad hinzu.
  • Führen Sie den Provider aus dem Verzeichnis aus, in dem er gespeichert ist.
  • Geben Sie den vollständigen Pfad zum Provider an, wenn Sie Ressourcen-Discovery-Befehle ausführen.

Da Ressourcen-Discovery-Befehle terraform-exec verwenden, um Terraform in Ihrem Namen aufzurufen, muss das System den Speicherort der Terraform-CLI mit einer der folgenden Methoden angeben:

  • Geben Sie den vollständigen Pfad einschließlich Namen für die Terraform-CLI mit der Umgebungsvariable terraform_bin_path an. Weitere Informationen zum Festlegen von Variablen finden Sie unter Umgebungsvariablen.
  • Fügen Sie die Terraform-CLI dem Systempfad hinzu.

Authentifizierung

Um Ressourcen in Ihrem Compartment zu erkennen, benötigt der OCI-Terraform-Provider Authentifizierungsinformationen zu Benutzer, Mandant und Region, mit denen die Ressourcen erkannt werden können. Es wird empfohlen, dass Sie einen Benutzer mit Prüfungs- und Lesezugriff für die zu erkennenden Ressourcen angeben.

Sie können die erforderlichen Informationen mit API-Schlüsselauthentifizierung und Umgebungsvariablen oder Instanz-Principal-Autorisierung angeben.

Ressourcen exportieren

Nachdem Sie den Speicherort der Terraform-CLI und die Authentifizierungseinstellungen angegeben haben, können Sie mit einem der folgenden Befehle die Ressourcen eines Compartments exportieren:

terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
terraform-provider-oci -command=export -compartment_id=<compartment_OCID> -output_path=<output_path>

Diese Befehle erkennen alle unterstützten Ressourcen im Compartment und generieren Terraform-Konfigurationsdateien im angegebenen output_path. Die generierten .tf-Dateien enthalten die Terraform-Konfiguration mit den Ressourcen, die der Befehl erkannt hat.

Achtung

Stellen Sie sicher, dass output_path leer ist, bevor Sie die Ressourcen-Discovery ausführen.
Hinweis

Der Parameter compartment_id ist erforderlich, wenn Sie die Instanz-Principal-Autorisierung verwenden.

Die folgenden allgemeinen Parameterkombinationen exportieren die beschriebenen Ressourcen:

  • compartment_id=<empty_or_tenancy_OCID> services=<empty_or_not_specified>: Alle Ressourcen im Geltungsbereich des Mandanten und des Compartments.
  • compartment_id=<empty_or_tenancy_OCID> services=<comma_seperated_list>: Ressourcen im Geltungsbereich des Mandanten und des Compartments für die angegebenen Services.
  • compartment_id=<non-root_OCID> services=<empty_or_not_specified>: Alle Ressourcen im Geltungsbereich des Compartments.
  • compartment_id=<non-root_OCID> services=<comma_seperated_list>: Ressourcen im Geltungsbereich des Compartments für die angegebenen Services. Ressourcen im Mandantengeltungsbereich werden nicht erkannt, auch wenn Services mit diesen Ressourcen angegeben werden.
Hinweis

Der Export von Compartment-Ressourcen unterstützt nur das Ziel-Compartment. Ressourcen in untergeordneten Compartments werden nicht erkannt.

Parameter

Mit den folgenden Parametern können Sie das Verhalten des Ressourcen-Discovery-Tools steuern.

Parameter Details
command Der auszuführende Befehl. Unterstützte Befehle:
  • export: Erkennt OCI-Ressourcen im Compartment und generiert Terraform-Konfigurationsdateien für sie.
  • list_export_resources: Listet die Terraform-OCI-Ressourcentypen auf, die vom Befehl export erkannt werden.
  • list_export_services: Listet die zulässigen Werte für Serviceargumente zusammen mit dem Geltungsbereich im JSON-Format auf.
compartment_id Die OCID des zu exportierenden Compartments. Wenn compartment_id oder compartment_name nicht angegeben ist, wird das Root Compartment verwendet. Erforderlich, wenn Instanz-Principal-Autorisierung verwendet wird.
compartment_name Der Name eines zu exportierenden Compartments. Wenn compartment_id oder compartment_name nicht angegeben ist, wird das Root Compartment verwendet.
exclude_services Eine durch Komma getrennte Liste der Serviceressourcen, die vom Export ausgeschlossen werden sollen. Alle im Argument services und exclude_services vorhandenen Services werden ausgeschlossen.
filter Ermittelte Ressourcen nach angegebenen Kriterien filtern. Weitere Informationen finden Sie unter Ressourcen filtern.
generate_state Geben Sie dieses Kennzeichen an, um die erkannten Ressourcen zusätzlich zu den Terraform-Konfigurationsdateien in eine Statusdatei zu importieren.
ids Eine durch Komma getrennte Liste von Tupeln <resource_type:resource_ID> (z.B. oci_core_instance:ocid.....) für zu exportierende Ressourcen. Die ID kann entweder eine OCID oder eine Terraform-Import-ID sein. Standardmäßig werden alle Ressourcen exportiert.
list_export_services_path Der vollständige Pfad, einschließlich des Dateinamens, der als Ausgabe für die Liste der unterstützten Services im JSON-Format verwendet werden soll.
output_path Der absolute Pfad für die Ausgabe der generierten Konfigurationen und Statusdateien des exportierten Compartments.
parallelism Die Anzahl der Threads zum parallelen Erkennen von Ressourcen. Der Standardwert lautet 1.
retry_timeout Die Zeit in Sekunden, wie lange API-Aufrufe im Fall von API-Fehler warten und den Vorgang wiederholen. Standardmäßig beträgt die Dauer des Wiederholungstimeouts 15 Sekunden.
services Eine durch Komma getrennte Liste der zu exportierenden Serviceressourcen. Wenn dieser Parameter nicht angegeben ist, werden alle Ressourcen in dem angegebenen Compartment (ausgenommen IAM-Ressourcen) exportiert.

Unter Unterstützte Services finden Sie akzeptierte Werte und unter Identitätsressourcen exportieren zugehörige Informationen.
tf_version Die Version der Terraform-Syntax, die beim Generieren von Konfigurationsdateien verwendet werden soll. Der Standardwert ist v0.12. Zulässige Werte:
  • 0.11
  • 0.12

Wenn Sie 0.11 als Syntaxversion angeben, verwenden Sie Ressourcen mit v0.11 der Terraform-CLI.

Wenn Sie Terraform-CLI v0.13 und höher verwenden, um Ressourcen zu erkennen, stellen Sie sicher, dass die Version mit v0.12-Syntax kompatibel ist.

Statusdateien werden in der Terraform-Syntax generiert, die mit der Version der Terraform-CLI übereinstimmt, mit der Ressourcen erkannt werden. Der Parameter tf_version gilt nicht für Statusdateien.
variables_global_level

Listet zu exportierende Attribute der obersten Ebene als Variablen auf. Format: attribute1,attribute2. Attribute auf Ressourcenebene (variables_resource_level) sind aus dieser Liste ausgeschlossen.
variables_resource_level

Listet zu exportierende Attribute auf Ressourcenebene als Variablen auf. Format: resourceType.attribute. Attribute der obersten Ebene (variables_global_level) sind aus dieser Liste ausgeschlossen.

Ressourcen filtern

Ermittelte Ressourcen nach angegebenen Kriterien filtern:

  • Ressourcentypfilter: Type<operator><provider-resource-type>

    <operator> hat entweder den Wert = (entspricht) oder != (entspricht nicht)

  • Attributfilter: AttrName=<attribute-name>;Value<operator><value> Alle Ressourcen mit übereinstimmenden Attributen und Werten suchen
  • Bis zu 10 Filter (Ressourcen müssen alle erfüllen)
Ressourcentypfilter: nur VCN
--filter="Type=oci_core_vcn"
Ressourcentypfilter: Alles außer VCN
--filter="Type!=oci_core_vcn"
Attributfilter: Definierter Tagwert
--filter="AttrName=defined_tags.example-namespace.example-key;Value=example-value"
Mehrere Filter: Nur VCN. Für den Test muss das Attribut dns_label festgelegt sein
--filter="Type=oci_core_vcn" --filter="AttrName=dns_label;Value=test"

Weitere Informationen zum Filtern ermittelter Ressourcen finden Sie unter Ressourcen filtern, die über die Ressourcen-Discovery ermittelt wurden.

Verbose-Logging

Um die Verbose-Konsolenausgabe beim Ausführen des Providers abzurufen, stellen Sie dem Ressourcen-Discovery-Befehl die Kennzeichen TF_LOG oder OCI_TF_LOG voran. Beispiel:

TF_LOG=DEBUG terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
OCI_TF_LOG=DEBUG terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>

Die TF_LOG--Ebene und das Kennzeichen OCI_TF_LOG können auch als Umgebungsvariablen festgelegt werden.

Um die Verbose-Konsolenausgabe in eine Logdatei umzuleiten, legen Sie die Umgebungsvariable OCI_TF_LOG_PATH fest, und geben Sie den Pfad an.

Beendigungsstatus

Bei Fehlern im Zusammenhang mit den OCI-APIs oder der Nichtverfügbarkeit des Service beim Erkennen von Ressourcen sucht das Tool die nächste Ressource. Alle aufgetretenen Fehler werden nach Abschluss der Discovery angezeigt.

  • Exitcode 0: Erfolgreich.
  • Exitcode 1: Fehler aufgrund von falschen Umgebungsvariablen, Argumenten oder Konfigurationen.
  • Exitcode 64: Teilweise erfolgreich. Die Ressourcen-Discovery konnte aufgrund von Serviceausfällen nicht alle Ressourcen finden.

Identitätsressourcen exportieren

Einige Ressourcen, wie Identitätsressourcen, sind nur auf Mandantenebene vorhanden und können nicht in einem bestimmten Compartment erkannt werden. Um derartige Ressourcen zu erkennen, verwenden Sie den folgenden Befehl, der alle Compartment-Parameter auslässt:
terraform-provider-oci -command=export -output_path=<output_path> -services=identity
Hinweis

Beim Exportieren von Identitätsressourcen wird der Wert compartment_id ignoriert, falls er angegeben wird.

Ressourcen in ein anderes Compartment exportieren

Nachdem Sie die generierten Terraform-Konfigurationsdateien geprüft und erforderliche Änderungen vorgenommen haben, kann die Konfiguration mit Terraform verwendet werden. So könnten Sie z.B. diese Ressourcen in einem neuen Compartment oder Mandanten mit Terraform erneut bereitstellen.

Dazu geben Sie die folgenden Umgebungsvariablen an:

export TF_VAR_tenancy_ocid=<target_tenancy_OCID>
export TF_VAR_compartment_ocid=<target_compartment_OCID>

Führen Sie anschließend den folgenden Befehl aus:

terraform apply

Terraform-Statusdatei generieren

Achtung

Die Statusdatei enthält alle Ressourcenattribute, die als Teil von Konfigurationsdateien angegeben sind. Wenn Sie sensible Daten mit Terraform verwalten, wie Datenbank- oder Benutzerkennwörter oder Private Keys für Instanzen, müssen Sie die Statusdatei selbst als sensible Daten behandeln. Weitere Informationen finden Sie unter Sensible Daten speichern.

Sie können auch eine Terraform-Statusdatei generieren, um die erkannten Ressourcen zu verwalten. Führen Sie dazu den folgenden Befehl aus, der das Kennzeichen -generate_state enthält:

terraform-provider-oci -command=export -compartment_id=<compartment_OCID> -output_path=<output_path> -generate_state

Die Ergebnisse dieses Befehls sind die .tf-Dateien, die die Terraform-Konfiguration darstellen, und eine terraform.tfstate-Datei, die den Status darstellt. Weitere Informationen finden Sie unter Status.

Hinweis

Die von diesem Befehl generierte Terraform-Statusdatei ist nur mit Terraform v0.12.4 und höher kompatibel.