Konfigurationen verfassen
Terraform ermöglicht die Beschreibung von Infrastrukturressourcen mit dem HashiCorp Configuration Language-Format (HCL) in Terraform-Konfigurationsdateien (siehe Konfigurationssyntax). Terraform-Konfigurationsdateien können eines von zwei Formaten verwenden: Terraform-domainspezifische Sprache (HashiCorp Configuration Language-Format [HCL], der empfohlene Ansatz) oder JSON-Format, wenn die Dateien maschinenlesbar sein müssen. Konfigurationsdateien, die das HCL-Format verwenden, enden mit der Dateierweiterung .tf
, Dateien im JSON-Format enden mit der Dateierweiterung .tf.json
. Das Terraform-Format ist menschenlesbar, während das JSON-Format maschinenlesbar ist.
Mit Terraform-Konfigurationen können Sie Oracle Cloud Infrastructure-(OCI-)Ressourcen, Variablendefinitionen, Datenquellen und vieles mehr definieren. Terraform konvertiert dann die OCI-Konfigurationen in einen Satz von API-Aufrufen an OCI-API-Endpunkte. Um die Terraform-Konfiguration schreiben zu können, müssen Sie verstehen, wie die gewünschte Infrastruktur in die Konfigurationssyntax abstrahiert wird.
Während die Oracle Cloud Infrastructure-API camelCase umfassend verwendet, unterstützt Terraform camelCase in Konfigurationsdateien nicht. Daher werden in den Konfigurationen Unterstriche statt Großbuchstaben als Trennzeichen angezeigt. Beispiel: Wenn die API
availabilityDomain
verwendet, verwendet die Terraform-Konfiguration availability_domain
.Konfigurationsdateianforderungen
Terraform-Konfigurationsdateien (.tf
) haben bestimmte Anforderungen, je nach den in der Datei definierten Komponenten. Beispiel: Sie haben den Terraform-Provider in einer Datei definiert (provider.tf
), die Variablen in einer anderen Datei (variables.tf
) und die Datenquellen in einer weiteren Datei.
Beispiele für Konfigurationsdateien finden Sie unter Beispiele für Terraform-Oracle Cloud Infrastructure-Provider.
Providerdefinitionen
Das folgende Beispiel, das die Terraform-Syntax verwendet, veranschaulicht die Anforderungen für eine OCI-Terraform-Providerdefinition und zeigt auch zugehörige Variablendefinitionen. Die Providerdefinition hängt von Variablen ab, damit die Konfigurationsdatei selbst keine sensiblen Daten enthält. Das Einbeziehen sensibler Daten stellt ein Sicherheitsrisiko beim Austausch oder Freigeben von Konfigurationsdateien dar.
variable "tenancy_ocid" {}
variable "user_ocid" {}
variable "fingerprint" {}
variable "private_key_path" {}
variable "region" {}
provider "oci" {
tenancy_ocid = "${var.tenancy_ocid}"
user_ocid = "${var.user_ocid}"
fingerprint = "${var.fingerprint}"
private_key_path = "${var.private_key_path}"
region = "${var.region}"
}
Das Attribut region
gibt die geografische Region an, in der die Providerressourcen erstellt werden. Um mehrere Regionen in einer einzelnen Konfiguration als Ziel zuzuweisen, erstellen Sie einfach eine Providerdefinition für jede Region, und differenzieren Sie dann mithilfe eines Provideralias, wie im folgenden Beispiel dargestellt. Beachten Sie, dass nur ein Provider mit dem Namen oci
definiert ist, die Providerdefinition oci
jedoch zweimal eingegeben wird, einmal für die Region us-phoenix-1
(mit dem Alias phx
) und einmal für die Region us-ashburn-1
(mit dem Alias "iad").
variable "tenancy_ocid" {}
variable "user_ocid" {}
variable "fingerprint" {}
variable "private_key_path" {}
variable "compartment_ocid" {}
provider "oci" {
region = "us-phoenix-1"
alias = "phx"
tenancy_ocid = "${var.tenancy_ocid}"
user_ocid = "${var.user_ocid}"
fingerprint = "${var.fingerprint}"
private_key_path = "${var.private_key_path}"
}
provider "oci" {
region = "us-ashburn-1"
alias = "iad"
tenancy_ocid = "${var.tenancy_ocid}"
user_ocid = "${var.user_ocid}"
fingerprint = "${var.fingerprint}"
private_key_path = "${var.private_key_path}"
}
Weitere Informationen finden Sie unter Providerkonfiguration.
Variablendefinitionen
Variablen in Terraform stellen Parameter für Terraform-Module dar. In Variablendefinitionen konfiguriert jeder Block eine einzelne Eingabevariable, und jede Definition kann beliebige oder alle der folgenden optionalen Argumente annehmen:
type
(optional): Definiert den Variablentyp als einen von drei zulässigen Werten:string
,list
undmap
. Wenn dieses Argument nicht verwendet wird, wird der Variablentyp basierend aufdefault
abgeleitet. Wenn kein Standard (default
) angegeben ist, wird vom Typstring
ausgegangen.default
(optional): Legt den Standardwert für die Variable fest. Wenn kein Standardwert angegeben wird, muss der Aufrufer einen Wert angeben. Andernfalls löst Terraform einen Fehler aus.description
(optional): Eine menschenlesbare Beschreibung der Variablen.
Im Folgenden finden Sie Beispiele für mehrere Variablendefinitionen. Einige Definitionen umfassen optionale Parameter.
variable "tenancy_ocid" {}
variable "user_ocid" {}
variable "fingerprint" {}
variable "private_key_path" {}
variable "region" {}
variable "AD" {
default = "1"
description = "Availability Domain"
}
variable "CPUCoreCount" {
default = "2"
type = string
}
Weitere Informationen finden Sie unter Eingabevariablen.
Ausgabekonfiguration
Mit Ausgabevariablen können Terraform-Endbenutzerabfragen unterstützt werden. Mit Ausgabevariablen können Sie sinnvolle Daten aus den potenziell umfangreichen Daten extrahieren, die mit einer komplexen Infrastruktur verknüpft sind. Beispiel: Sie sind zu einem bestimmten Zeitpunkt nur an einigen wenigen Schlüsselwerten interessiert, und wenn Sie Ausgabevariablen definieren, können Sie genau die erforderlichen Informationen extrahieren.
Im Folgenden finden Sie ein einfaches Beispiel, in dem nur einige Ausgabevariablen (Instanz-IP-Adressen und Boot-Volume-IDs) definiert sind:
# Output the private and public IPs of the instance
output "InstancePrivateIPs" {
value = ["${oci_core_instance.TFInstance.*.private_ip}"]
}
output "InstancePublicIPs" {
value = ["${oci_core_instance.TFInstance.*.public_ip}"]
}
# Output the boot volume IDs of the instance
output "BootVolumeIDs" {
value = ["${oci_core_instance.TFInstance.*.boot_volume_id}"]
}
Weitere Informationen finden Sie unter Daten aus Terraform ausgeben. Siehe auch Ausgabewerte.
Ressourcen
Ressourcen sind Komponenten von Oracle Cloud Infrastructure. Diese Ressourcen umfassen alles von Komponenten niedriger Ebenen, wie physischen und virtuellen Servern, bis hin zu Komponenten höherer Ebenen, wie E-Mail- und Datenbankprovidern oder Ihrem DNS-Datensatz.
Die vollständige Referenz der unterstützten Ressourcen und Datenquellen des OCI-Terraform-Providers enthält Details zu Verwendung, Argumenten und Attributen. Die vollständige Referenz ist unter docs.oracle.com und Terraform Registry verfügbar.
Datenquellen und Ressourcen werden nach Service innerhalb der Referenz gruppiert.
Terraform-Statusdateien enthalten 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, wird empfohlen, die Statusdatei selbst als sensible Daten zu behandeln. Weitere Informationen finden Sie unter Sensible Daten im Status.
Ressourcen deklarieren
Im Folgenden finden Sie ein einfaches Beispiel für eine Ressourcendefinition, das die Basisstruktur veranschaulicht.
resource "oci_core_virtual_network" "vcn1" {
cidr_block = "10.0.0.0/16"
dns_label = "vcn1"
compartment_id = "${var.compartment_ocid}"
display_name = "vcn1"
}
Die Ressourcendeklaration in der ersten Zeile des Beispiels verwendet das Schlüsselwort "resource" und zwei Parameter: resource type
und resource name
("oci_core_virtual_network" und "vcn1" im Beispiel). Im Codeblock finden Sie dann die Ressourcenkonfiguration.
Weitere Informationen finden Sie unter Ressourcen.
Ressourcenabhängigkeiten
Wenn eine Ressource eine andere Ressource innerhalb ihres Ressourcenblocks referenziert, leitet Terraform automatisch die Abhängigkeit der primären Ressource von der referenzierten Ressource ab. Eine Ressource kann auch von Ressourcen abhängig sein, die nicht explizit in ihrem Block referenziert werden. Beispiel: Sie müssen Policys für eine Ressource erstellen, bevor Sie die Ressource selbst erstellen.
Um verborgene Abhängigkeiten zu definieren, die Terraform nicht automatisch ableiten kann, können Sie das Metargument depends_on im Ressourcenblock verwenden.
Im folgenden Beispiel werden eine oci_datascience_notebook_session
-Ressource und eine oci_identity_policy
-Ressource für zugehörige Policys erstellt. Wenn Sie das Metaargument depends_on
zur Ressource oci_datascience_notebook_session
hinzufügen, wird sichergestellt, dass die Policys zuerst erstellt werden:
resource "oci_datascience_notebook_session" "ods-notebook-session" {
count = var.enable_ods ? var.ods_number_of_notebooks : 0
#Required
compartment_id = var.compartment_ocid
notebook_session_configuration_details {
#Required
shape = var.ods_compute_shape
subnet_id = local.private_subnet_id
#Optional
block_storage_size_in_gbs = var.ods_storage_size
}
project_id = oci_datascience_project.ods-project[0].id
display_name = "${var.ods_notebook_name}-${count.index}"
depends_on = ["oci_identity_policy.ods-policy"]
}
resource "oci_identity_policy" "ods-policy" {
provider = oci.home
compartment_id = var.compartment_ocid
description = "Data Science Policies"
name = var.ods_policy_name
statements = var.enable_vault ? concat(local.ods_policies , local.vault_policies) : local.ods_policies
}
Ressourcen in anderem Stack referenzieren (durch Exportieren von Stackausgabewerten)
Sie können Ressourcen in anderen Stacks referenzieren. Mit der Terraform-Datenquelle remote_state
können Sie Ausgabevariablen aus Statusdateien lesen.
Beispiel: Wenn Sie eine Terraform-Konfiguration für eine neue Webanwendung schreiben, können Sie festlegen, dass die Webanwendung das Subnetz verwendet, das aus dem Netzwerkstack erstellt wurde, solange die erforderlichen Subnetzwerte in der Statusdatei des Netzwerkstacks ausgegeben wurden. Führen Sie in der Terraform-Konfiguration für Ihre neue Webanwendung folgende Schritte aus:
-
Übertragen Sie die Statusdatei des vorhandenen Netzwerkstacks in den Kontext der aktuellen Terraform-Konfiguration.
Beim Abrufen der Statusdatei werden die Stackausgabewerte effektiv exportiert. Anweisungen zum Abrufen der Statusdatei in Resource Manager finden Sie unter Statusdatei eines Stacks abrufen.
-
Laden Sie die übertragene Statusdatei in eine Datenquelle für Remotestatusdateien.
-
Füllen Sie die Datenquelle des Subnetzes in der aktuellen Konfiguration mit Werten aus den relevanten Ausgabevariablen der referenzierten Statusdatei aus.
-
Optional können Sie die ID-Informationen für die ausgefüllte Datenquelle ausdrucken, um die erwarteten Werte zu bestätigen.
Neben den Berechtigungen, die für Resource Manager-Vorgänge erforderlich sind, benötigen Sie die entsprechenden Berechtigungen für Ressourcentypen, die Sie referenzieren, im Compartment, für das Sie sie referenzieren. In diesem Beispiel benötigen Sie Leseberechtigungen für Netzwerkressourcen im Compartment, in dem sie gespeichert sind.
Der folgende Terraform-Konfigurationsauszug referenziert ein Subnetz in einem anderen Stack:
# The following example assumes that the source stack (defined by `stack_id`) has output a value named `subnet_id`
# Terraform v0.12 is assumed
variable "stack_id" {}
# Pull the state file of the existing Resource Manager stack (the network stack) into this context
data "oci_resourcemanager_stack_tf_state" "stack1_tf_state" {
stack_id = "${var.stack_id}"
local_path = "stack1.tfstate"
}
# Load the pulled state file into a remote state data source
data "terraform_remote_state" "external_stack_remote_state" {
backend = "local"
config = {
path = "${data.oci_resourcemanager_stack_tf_state.stack1_tf_state.local_path}"
}
}
# Populate a data source in this configuration using a value from the remote state data source
data "oci_core_subnet" "subnet1" {
subnet_id = "${data.terraform_remote_state.external_stack_remote_state.outputs.subnet_id}"
}
# Print the values of the populated data source
output "print-subnet1" {
value = "${data.oci_core_subnet.subnet1}"
}
Datenquellen
Datenquellen stellen schreibgeschützte Ansichten vorhandener Infrastruktur dar, die für die semantische Verwendung in Terraform-Konfigurationen vorgesehen ist. Im Folgenden finden Sie ein einfaches Beispiel für eine Datenquellenkonfiguration, um die grundlegende Struktur zu veranschaulichen:
# Gets a list of Availability Domains
data "oci_identity_availability_domains" "ADs" {
compartment_id = "${var.tenancy_ocid}"
}
# Get DB node list
data "oci_database_db_nodes" "DBNodeList" {
compartment_id = "${var.compartment_ocid}"
db_system_id = "${oci_database_db_system.TFDBNode.id}"
}
# Get DB node details
data "oci_database_db_node" "DBNodeDetails" {
db_node_id = "${lookup(data.oci_database_db_nodes.DBNodeList.db_nodes[0], "id")}"
}
# Gets the OCID of the first (default) vNIC
data "oci_core_vnic" "DBNodeVnic" {
vnic_id = "${data.oci_database_db_node.DBNodeDetails.vnic_id}"
}
Weitere Informationen finden Sie unter Datenquellen.
Datenquellen filtern
Datenquellen, die Listen von Ressourcen zurückgeben, unterstützen Filtersemantik. Um einen Filter zu verwenden, fügen Sie diesen Block in die Datenquellendefinition ein:
filter {
name = ""
values = [""]
}
Der name
-Wert entspricht dem qualifizierten Eigenschaftsnamen, mit dem gefiltert werden soll, und die values
-Listen können einen oder mehrere Filterwerte enthalten.
Sie können verschachtelte Eigenschaften und Zuordnungselemente suchen, indem Sie den Eigenschaftsnamen mit dem Namen der übergeordneten Eigenschaft angeben. Beispiel r1
gibt alle Instanzen mit einem source_type
-Image zurück. Beispiel r2
gibt alle Instanzen zurück, die ein definiertes Tag mit dem Wert "42" für Schlüssel CostCenter
im Namespace Operations
enthalten.
data "oci_core_instances" "r1" {
...
filter {
name = "source_details.source_type"
values = ["image"]
}
}
data "oci_core_instances" "r2" {
...
filter {
name = "defined_tags.Operations.CostCenter"
values = ["42"]
}
}
Mehrere Werte (values
) fungieren als OR-Filter. Im folgenden Beispiel für eine Ausprägung enthält die Datenquelle die VM-Ausprägungen Standard 1.1 und Standard 1.2:
data "oci_core_shape" "t" {
...
filter {
name = "name"
values = ["VM.Standard1.1", "VM.Standard1.2"]
}
}
Mehrere Filterblöcke können zu AND-Vergleichen zusammengesetzt werden. Das folgende Beispiel gibt eine Datenquelle zurück, die Instanzen ausführen in der ersten AD einer Region enthält:
data "oci_core_instances" "s" {
...
filter {
name = "availability_domain"
values = ["\\w*-AD-1"]
regex = true
}
filter {
name = "state"
values = ["RUNNING"]
}
}
Wie die vorherigen Beispiele zeigen, können Filter auch reguläre Ausdrücke verwenden. Wenn Sie regex = true
festlegen, wird jedes Element in der values
-Liste als regulärer Ausdruck behandelt. Umgekehrte Strings in Zeichenfolgen für Sonderzeichen in einem regulären Ausdruck müssen mit einem weiteren Schrägstrich maskiert werden (in den vorherigen Beispielen als erster \
vor \w
in "\\w*-AD-1"
dargestellt).
Das Drilling in Listen strukturierter Objekte wird nicht unterstützt. Wenn diese Eigenschaften als Ziel festgelegt sind, werden keine Ergebnisse aus der Datenquelle zurückgegeben.
Functions
Terraform bietet mehrere integrierte Funktionen, die Sie in Ihren Konfigurationsdateien verwenden können. Mit diesen Funktionen können Sie Zeichenfolgen ändern, Berechnungen mit numerischen Werten durchführen, Collections verwalten und vieles mehr.
Weitere Informationen finden Sie unter Integrierte Funktionen.