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.
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.
Stellen Sie sicher, dass
output_path
leer ist, bevor Sie die Ressourcen-Discovery ausführen.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.
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:
|
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:
Wenn Sie 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 Parametertf_version gilt nicht für Statusdateien. |
variables_global_level |
Listet zu exportierende Attribute der obersten Ebene als Variablen auf. Format: |
variables_resource_level |
Listet zu exportierende Attribute auf Ressourcenebene als Variablen auf. Format: |
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
terraform-provider-oci -command=export -output_path=<output_path> -services=identity
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
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.
Die von diesem Befehl generierte Terraform-Statusdatei ist nur mit Terraform v0.12.4 und höher kompatibel.