Creación de configuraciones

Con Terraform, puede describir sus recursos de infraestructura utilizando el formato HashiCorp Configuration Language (HCL) en los archivos de configuración de Terraform (consulte Sintaxis de configuración). Los archivos de configuración de Terraform pueden utilizar uno de estos dos formatos: lenguaje específico del dominio de Terraform (formato HashiCorp Configuration Language [HCL]), que es el enfoque recomendado, o formato JSON si los archivos deben ser legibles por una máquina. Los archivos de configuración que utilizan el formato HCL terminan con la extensión de archivo .tf; los que utilizan formato JSON terminan con la extensión de archivo .tf.json. El formato de Terraform es legible por el usuario, mientras que el formato JSON es legible por una máquina.

Utilice las configuraciones de Terraform para definir los recursos, las definiciones de variables y los orígenes de datos de Oracle Cloud Infrastructure (OCI), entre otras muchas cosas. A continuación, Terraform convierte las configuraciones de OCI en un juego de llamadas de API a puntos finales de API de OCI. La clave para escribir la configuración de Terraform es comprender cómo extraer la infraestructura deseada conceptualmente en la sintaxis de configuración de Terraform.

Importante

Si bien la API de Oracle Cloud Infrastructure utiliza camelCase ampliamente, Terraform no soporta camelCase en los archivos de configuración. Por este motivo, en las configuraciones verá caracteres de subrayado en lugar de mayúsculas como separadores. Por ejemplo, cuando la API utiliza availabilityDomain, la configuración de Terraform utiliza availability_domain.

Requisitos del archivo de configuración

Los archivos de configuración de Terraform (.tf) tienen requisitos específicos, según los componentes definidos en el archivo. Por ejemplo, puede tener el proveedor de Terraform definido en un archivo (provider.tf), las variables en otro (variables.tf) y los orígenes de datos en otro.

Nota

Para ver archivos de configuración de ejemplo, consulte Ejemplos de proveedor de Oracle Cloud Infrastructure de Terraform.

Definiciones de proveedor

En el siguiente ejemplo, que utiliza la sintaxis de Terraform, se ilustran los requisitos para la definición de un proveedor de Terraform de OCI y también se muestran las definiciones de variables asociadas. La definición de proveedor se basa en variables para que el archivo de configuración no contenga datos sensibles. La inclusión de datos confidenciales crea un riesgo de seguridad al intercambiar o compartir archivos de configuración.

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}"
}

El atributo region especifica la región geográfica en la que se crean sus recursos de proveedor. Para dirigirse a varias regiones en una única configuración, solo tiene que crear una definición de proveedor para cada región y, a continuación, diferenciarlas mediante un alias de proveedor, como se muestra en el siguiente ejemplo. Tenga en cuenta que solo se ha definido un proveedor, denominado oci, y que la definición del proveedor oci se ha introducido dos veces, una vez para la región us-phoenix-1 (con el alias phx) y otra vez para la región us-ashburn-1 (con el 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}"
}

Para obtener más información, consulte Configuración de proveedor.

Definiciones de variables

Las variables en Terraform representan parámetros para módulos de Terraform. En las definiciones de variables, cada bloque configura una variable de entrada única y cada definición puede tomar cualquiera de los siguientes argumentos opcionales o todos ellos:

type (opcional): define el tipo de variable como uno de los tres valores permitidos: string, list y map. Si este argumento no se utiliza, el tipo de variable se infiere en función de default. Si no se proporciona default , se asume que el tipo es string.
default (opcional): define el valor por defecto de la variable. Si no se proporciona ningún valor por defecto, el emisor de la llamada debe proporcionar un valor o Terraform devuelve un error.
description (opcional): descripción legible por el usuario de la variable.

A continuación se muestran ejemplos de varias definiciones de variables. Algunas definiciones incluyen parámetros opcionales.

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
}

Para obtener más información, consulte Variables de entrada.

Configuración de salida

Las variables de salida proporcionan un medio para soportar las consultas del usuario final de Terraform. Utilice variables de salida para extraer datos significativos de una cantidad potencialmente masiva de datos asociados con una infraestructura compleja. Por ejemplo, puede estar interesado solo en una serie de valores clave en un momento determinado y la definición de variables de salida le permite extraer exactamente la información que necesita.

A continuación se muestra un ejemplo sencillo en el que solo se definen algunas variables de salida (direcciones IP de instancia e ID de volumen de inicio):

# 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}"]
}

Para obtener más información, consulte Variables de salida. Consulte también Configuración de salida.

Recursos

Los recursos son componentes de Oracle Cloud Infrastructure. Estos recursos incluyen todo, desde los componentes de bajo nivel, como los servidores físicos y virtuales, hasta componentes de nivel superior, como los proveedores de correo electrónico y base de datos, el registro DNS.

La referencia completa de los recursos y orígenes de datos que soporta el proveedor de Terraform de OCI contiene detalles sobre el uso, los argumentos y los atributos. La referencia completa está disponible en docs.oracle.com y en Terraform Registry.

Los recursos y los orígenes de datos se agrupan por servicio en la referencia.

Atención

Los archivos de estado de Terraform contienen todos los atributos de recursos especificados como parte de los archivos de configuración. Si gestiona datos confidenciales con Terraform, como contraseñas de bases de datos o de usuarios o claves privadas de instancias, le recomendamos que trate el archivo de estado como datos confidenciales. Consulte la sección sobre datos confidenciales en el estado para obtener más información.

Declaración de recursos

A continuación se muestra un ejemplo sencillo de una definición de recurso que ilustra su estructura básica.

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 declaración de recursos en la primera línea del ejemplo utiliza la palabra clave" resource" y toma dos parámetros, el recurso type y el recurso name ("oci_core_virtual_network" y"vcn1" en el ejemplo). Dentro del bloque de código está la configuración de recursos.

Para obtener más información, consulte Configuración de recursos.

Dependencias de recursos

Cuando un recurso hace referencia a otro recurso dentro de su bloque de recursos, Terraform infiere automáticamente la dependencia del recurso principal en el recurso al que se hace referencia. Un recurso también puede depender de recursos a los que no se hace referencia explícita dentro de su bloque. Por ejemplo, puede que necesite crear políticas para un recurso antes de crear el recurso en sí.

Para definir dependencias ocultas que Terraform no puede inferir automáticamente, puede utilizar el metaargumento depends_on en el bloque de recursos.

En el siguiente ejemplo, se crea un recurso oci_datascience_notebook_session y un recurso oci_identity_policy para políticas relacionadas. La adición del metaargumento depends_on al recurso oci_datascience_notebook_session garantiza que se creen primero las políticas:

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
 }

Referencia a recursos en otra pila (exportación de los valores de salida de la pila)

Puede hacer referencia a recursos que existen en otras pilas. El origen de datos de Terraform remote_state permite leer las variables de salida de los archivos de estado.

Por ejemplo, al escribir una configuración de Terraform para una nueva aplicación web, puede hacer que la aplicación web utilice la subred creada a partir de la pila de red, siempre que los valores de subred necesarios se hayan generado en el archivo de estado de la pila de red. En la configuración de Terraform para la nueva aplicación web, haga lo siguiente:

Obtenga el archivo de estado de la pila de red existente en el contexto de la configuración actual de Terraform.

Al recuperar el archivo de estado, se exportan eficazmente los valores de salida de la pila. Para obtener instrucciones sobre cómo recuperar el archivo de estado en Resource Manager, consulte Obtención de un archivo de estado de una pila.
Cargue el archivo de estado obtenido en un origen de datos para archivos de estado remotos.
Rellene el origen de datos de subred de la configuración actual con valores de las variables de salida relevantes del archivo de estado de referencia.
Opcionalmente, imprima la información de identificación del origen de datos rellenado para confirmar los valores esperados.

Nota

Además de los permisos necesarios para las operaciones del gestor de recursos, necesitará los permisos adecuados para los tipos de recursos a los que hace referencia en el compartimento en el que hace referencia a ellos. En este ejemplo, necesitará permisos de lectura para los recursos de red en el compartimento donde se encuentran.

El siguiente fragmento de configuración de Terraform hace referencia a una subred en otra pila:

# 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}"
}

Orígenes de datos

Los orígenes de datos representan vistas de solo lectura de la infraestructura existente destinada al uso semántico en configuraciones de Terraform. A continuación se muestra un ejemplo sencillo de una configuración de origen de datos para ilustrar su estructura básica:

# 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}"
}

Para obtener más información, consulte Configuración de origen de datos.

Filtrado de orígenes de datos

Los orígenes de datos que devuelven listas de recursos soportan la semántica de filtrado. Para utilizar un filtro, incluya este bloque en la definición del origen de datos:

filter {
    name = ""
    values = [""]
}

El valor name corresponde al nombre de propiedad completo con el que filtrar y las listas de values pueden contener uno o varios valores con los que filtrar.

Las propiedades anidadas y los elementos de asignación se pueden abordar completando el nombre de propiedad con el nombre de propiedad principal. El ejemplo r1 proporciona todas las instancias que tienen la imagen source_type. El ejemplo r2 proporciona todas las instancias que contienen una etiqueta definida con el valor "42" para la clave CostCenter en el espacio de nombres 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"]
  }
}

La incorporación de varios elementos en values funciona como un filtro de tipo OR. En el siguiente ejemplo de una unidad, el origen de datos resultante incluiría tanto la unidad de VM Standard 1.1 como la Standard 1.2:

data "oci_core_shape" "t" {
  ...
  filter {
    name = "name"
    values = ["VM.Standard1.1", "VM.Standard1.2"]
  }
}

También se pueden componer bloques de varios filtros para formar comparaciones de tipo AND. El siguiente ejemplo devuelve un origen de datos que contiene las instancias en ejecución en el primer dominio de disponibilidad de una región:

data "oci_core_instances" "s" {
    ...
  filter {
    name = "availability_domain"
    values = ["\\w*-AD-1"]
    regex = true
  }

  filter {
    name = "state"
    values = ["RUNNING"]
  }
}

Como muestran los ejemplos anteriores, los filtros también pueden emplear expresiones regulares. La definición de regex = true trata cada elemento de la lista values como una expresión regular. Las barras invertidas de las cadenas para caracteres especiales de expresiones regulares se deben escapar con otra barra, como se muestra en los ejemplos anteriores con la primera \ antes de \w en "\\w*-AD-1".

Nota

La obtención de detalles en las listas de objetos estructurados no está soportada. Si se abordan estas propiedades, el origen de datos no devuelve resultados.

Functions

Terraform ofrece varias funciones incorporadas que puede utilizar en los archivos de configuración. Estas funciones permiten cambiar cadenas, realizar cálculos con valores numéricos, gestionar recopilaciones y mucho más.

Para obtener más información, consulte los detalles sobre las funciones.

Documentación de Oracle Cloud Infrastructure