Configurazioni redazione
Scrivere una configurazione Terraform per descrivere l'infrastruttura OCI utilizzando il formato HCL (Configuration Language) HashiCorp.
Terraform consente di descrivere le risorse dell'infrastruttura utilizzando il formato HCL (Configuration Language format) HashiCorp nei file di configurazione Terraform (vedere Sintassi della configurazione). I file di configurazione Terraform possono utilizzare uno dei due formati seguenti: il linguaggio specifico del dominio Terraform (HashiCorp Configuration Language format [HCL]), ovvero l'approccio consigliato oppure il formato JSON se i file devono essere leggibili dal computer. I file di configurazione che utilizzano il formato HCL terminano con l'estensione file .tf
; quelli che utilizzano il formato JSON terminano con l'estensione file .tf.json
. Il formato Terraform è leggibile dall'utente, mentre il formato JSON è leggibile dal computer.
Utilizza le configurazioni Terraform per definire le risorse Oracle Cloud Infrastructure (OCI), le definizioni delle variabili, le origini dei dati e molto altro ancora. Terraform, quindi, converte le configurazioni OCI in un set di chiamate API sugli endpoint dell'API OCI. La chiave per scrivere la configurazione Terraform è capire come astrarre concettualmente l'infrastruttura desiderata in Sintassi di configurazione.
Sebbene l'API di Oracle Cloud Infrastructure utilizzi ampiamente camelCase, Terraform non supporta camelCase nei file di configurazione. Per questo motivo, nelle configurazioni vengono visualizzati i caratteri di sottolineatura anziché le maiuscole come separatori. Ad esempio, se l'interfaccia API utilizza
availabilityDomain
, la configurazione Terraform utilizza availability_domain
.Requisiti dei file di configurazione
I file di configurazione Terraform (.tf
) hanno requisiti specifici, a seconda dei componenti definiti nel file. Ad esempio, si potrebbe avere un provider Terraform definito in un file (provider.tf
), variabili definite in un altro (variables.tf
) e origini dati definite in un altro file.
Ad esempio, i file di configurazione, vedere Esempi di provider Oracle Cloud Infrastructure di Terraform.
Definizioni provider
Per i provider di terze parti nelle configurazioni Terraform utilizzate con Resource Manager, vedere Configurazione del provider di terze parti.
L'esempio riportato di seguito che utilizza la sintassi Terraform illustra i requisiti per la definizione di un provider Terraform OCI e mostra anche le definizioni delle variabili associate. La definizione del provider si basa su variabili in modo che il file di configurazione stesso non contenga dati riservati. L'inclusione di dati sensibili crea un rischio per la sicurezza durante lo scambio o la condivisione di file di configurazione.
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}"
}
L'attributo region
specifica l'area geografica in cui vengono create le risorse del provider. Per indirizzare più aree in una singola configurazione, è sufficiente creare una definizione di provider per ogni area e quindi effettuare la differenziazione utilizzando un alias di provider, come mostrato nell'esempio riportato di seguito. Si noti che è definito un solo provider, denominato oci
, ma la definizione del provider oci
viene immessa due volte, una per l'area us-phoenix-1
(con l'alias phx
) e una per l'area us-ashburn-1
(con l'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}"
}
Per ulteriori informazioni, vedere Configurazione del provider.
Definizioni di variabile
In Resource Manager, le variabili sono soggette ai seguenti limiti.
Variabili per stack: 250
Dimensione per variabile: 8192 bytes
Le variabili in Terraform rappresentano i parametri per i moduli Terraform. Nelle definizioni delle variabili, ogni blocco configura una singola variabile di input e ogni definizione può assumere uno o tutti i seguenti argomenti facoltativi:
type
(facoltativo): definisce il tipo di variabile come uno dei tre valori consentiti:string
,list
emap
. Se questo argomento non viene utilizzato, il tipo di variabile viene derivato in base adefault
. Se non viene specificato alcun valoredefault
, si suppone che il tipo siastring
.default
(facoltativo): imposta il valore predefinito per la variabile. Se non viene fornito alcun valore predefinito, il chiamante deve fornire un valore oppure Terraform restituisce un errore.description
(facoltativo): descrizione leggibile della variabile.
Di seguito sono riportati alcuni esempi di diverse definizioni di variabili. Alcune definizioni includono parametri facoltativi.
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
}
Per ulteriori informazioni, vedere Variabili di input.
Configurazione di output
Le variabili di output forniscono uno strumento per supportare le query dell'utente finale Terraform. Utilizza variabili di output per estrarre dati significativi tra la quantità potenzialmente enorme di dati associati a un'infrastruttura complessa. Ad esempio, si potrebbe essere interessati solo a una manciata di valori chiave in un determinato momento e la definizione delle variabili di output consente di estrarre esattamente le informazioni necessarie.
Di seguito è riportato un semplice esempio in cui vengono definite solo alcune variabili di output (indirizzi IP dell'istanza e ID dei volumi di avvio):
# 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}"]
}
Per ulteriori informazioni, vedere Dati di output da Terraform. Vedere anche Valori di output.
Risorse
Le risorse sono componenti di Oracle Cloud Infrastructure. Queste risorse includono tutto, da componenti di basso livello come server fisici e virtuali, a componenti di livello superiore come provider di e-mail e database, il record DNS.
Il riferimento completo delle risorse e delle origini dati supportate del provider Terraform OCI contiene dettagli su uso, argomento e attributo. Il riferimento completo è disponibile sul sito docs.oracle.com e nel registro Terraform.
Le origini dati e le risorse vengono raggruppate per servizio all'interno del riferimento.
I file di stato Terraform contengono tutti gli attributi delle risorse specificati come parte dei file di configurazione. Se gestisci dati riservati con Terraform, ad esempio password di database o utente o chiavi private dell'istanza, ti consigliamo di considerare il file di stato stesso come dati riservati. Per ulteriori informazioni, vedere Dati sensibili in stato.
Dichiarazione delle risorse
Di seguito è riportato un semplice esempio di definizione di una risorsa che ne illustra la struttura di base.
resource "oci_core_virtual_network" "vcn1" {
cidr_block = "10.0.0.0/16"
dns_label = "vcn1"
compartment_id = "${var.compartment_ocid}"
display_name = "vcn1"
}
La dichiarazione della risorsa sulla prima riga dell'esempio utilizza la parola chiave "resource" e prende due parametri, la risorsa type
e la risorsa name
("oci_core_virtual_network" e "vcn1" nell'esempio). All'interno del blocco di codice, quindi, si trova la configurazione della risorsa.
Per ulteriori informazioni, vedere Risorse.
dipendenze risorsa
Quando una risorsa fa riferimento a un'altra risorsa all'interno del relativo blocco di risorse, Terraform deduce automaticamente la dipendenza della risorsa primaria dalla risorsa di riferimento. Una risorsa potrebbe anche dipendere da risorse a cui non viene fatto esplicitamente riferimento all'interno del relativo blocco. Ad esempio, potrebbe essere necessario creare criteri per una risorsa prima di creare la risorsa stessa.
Per definire dipendenze nascoste che Terraform non può derivare automaticamente, è possibile utilizzare il metaargomento depends_on nel blocco di risorse.
Nell'esempio seguente vengono create una risorsa oci_datascience_notebook_session
e una risorsa oci_identity_policy
per i criteri correlati. L'aggiunta del meta-argomento depends_on
alla risorsa oci_datascience_notebook_session
garantisce che i criteri vengano creati per primi:
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
}
Riferimento alle risorse in un altro stack (esportando i valori di output dello stack)
È possibile fare riferimento alle risorse esistenti in altri stack. L'origine dati remote_state
Terraform consente di leggere le variabili di output dai file di stato.
Ad esempio, quando si scrive una configurazione Terraform per una nuova applicazione Web, è possibile fare in modo che l'applicazione Web utilizzi la subnet creata dallo stack di rete, a condizione che i valori di subnet richiesti siano stati restituiti nel file di stato dello stack di rete. Nella configurazione Terraform per la nuova applicazione Web, effettuare le operazioni riportate di seguito.
-
Estrarre il file di stato dello stack di rete esistente nel contesto della configurazione Terraform corrente.
Il pull del file di stato consente di esportare in modo efficace i valori di output dello stack. Per istruzioni su come estrarre il file di stato in Resource Manager, vedere Come ottenere il file di stato di uno stack.
-
Caricare il file di stato estratto in un'origine dati per i file di stato remoti.
-
Inserire i valori delle variabili di output pertinenti del file di stato di riferimento nell'origine dati della subnet nella configurazione corrente.
-
Facoltativamente, stampare le informazioni di identificazione per l'origine dati popolata per confermare i valori previsti.
Oltre alle autorizzazioni necessarie per le operazioni di Resource Manager, sarà necessario disporre delle autorizzazioni appropriate per i tipi di risorsa a cui si fa riferimento nel compartimento a cui si fa riferimento. In questo esempio, sono necessarie autorizzazioni di lettura per le risorse di rete nel compartimento in cui si trovano.
Il seguente estratto della configurazione Terraform fa riferimento a una subnet in un altro 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}"
}
Origini dati
Le origini dati rappresentano viste di sola lettura dell'infrastruttura esistente destinate all'uso semantico nelle configurazioni Terraform. Di seguito è riportato un semplice esempio di configurazione di un'origine dati per illustrare la struttura di base:
# 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}"
}
Per ulteriori informazioni, vedere Origini dati.
Filtro delle origini dati
Le origini dati che restituiscono elenchi di risorse supportano la semantica di filtro. Per utilizzare un filtro, includere questo blocco nella definizione dell'origine dati:
filter {
name = ""
values = [""]
}
Il valore name
corrisponde al nome della proprietà qualificata con cui applicare il filtro e le liste values
possono contenere uno o più filtri di valori.
Le proprietà nidificate e gli elementi della mappa possono essere risolti qualificando il nome della proprietà con il nome della proprietà padre. L'esempio r1
fornisce tutte le istanze con immagine source_type
. L'esempio r2
fornisce tutte le istanze che contengono una tag definita con il valore "42" per la chiave CostCenter
nello spazio di nomi Operations
.
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"]
}
}
Più values
funzionano come filtro di tipo OR. Nell'esempio di forma riportato di seguito, l'origine dati risultante conterrebbe entrambe le forme VM Standard 1.1 e Standard 1.2:
data "oci_core_shape" "t" {
...
filter {
name = "name"
values = ["VM.Standard1.1", "VM.Standard1.2"]
}
}
È possibile comporre più blocchi di filtri per creare confronti di tipo AND. L'esempio riportato di seguito restituisce un'origine dati contenente le istanze in esecuzione nel primo AD di un'area.
data "oci_core_instances" "s" {
...
filter {
name = "availability_domain"
values = ["\\w*-AD-1"]
regex = true
}
filter {
name = "state"
values = ["RUNNING"]
}
}
Come mostrano gli esempi precedenti, i filtri possono anche utilizzare espressioni regolari. L'impostazione di regex = true
considera ogni elemento della lista values
come un'espressione regolare. Le barre rovesciate nelle stringhe per i caratteri speciali dell'espressione regolare devono essere precedute da un'altra barra, mostrata negli esempi precedenti come la prima \
prima di \w
in "\\w*-AD-1"
.
Il drilling negli elenchi di oggetti strutturati non è supportato. Se queste proprietà sono mirate, non vengono restituiti risultati dall'origine dati.
Funzioni
Terraform offre diverse funzioni integrate che è possibile utilizzare nei file di configurazione. Queste funzioni consentono di modificare le stringhe, eseguire calcoli in base a valori numerici, gestire le raccolte e molto altro ancora.
Per ulteriori informazioni, vedere Funzioni built-in.