Création des configurations

Écrivez une configuration Terraform pour décrire l'infrastructure OCI à l'aide du format HCL (HashiCorp Configuration Language).

Avec Terraform, vous pouvez décrire les ressources d'infrastructure à l'aide du format HCL (langage de configuration HashiCorp) dans les fichiers de configuration Terraform (voir Syntaxe de configuration). Les fichiers de configuration Terraform peuvent utiliser l'un des deux formats suivants : Langage propre à un domaine Terraform (format HCL), qui est l'approche recommandée, ou le format JSON si les fichiers doivent être lisibles par machine. Les fichiers de configuration qui utilisent le format HCL se terminent par l'extension de fichier .tf; ceux qui utilisent le format JSON se terminent par l'extension de fichier .tf.json. Le format Terraform est lisible par l'utilisateur, alors que le format JSON est lisible par machine.

Utilisez les configurations Terraform pour définir des ressources Oracle Cloud Infrastructure (OCI), ainsi que des définitions de variable, des sources de données, etc. Terraform convertit ensuite les configurations OCI en jeu d'appels d'API aux points d'extrémité d'API OCI. La clé permettant d'écrire la configuration Terraform comprend comment convertir l'infrastructure souhaitée, du point de vue conceptuel, en Syntaxe de configuration.

Important

Bien que l'API Oracle Cloud Infrastructure utilise camelCase de manière extensive, Terraform ne prend pas en charge camelCase dans les fichiers de configuration. C'est pour cette raison que dans les configurations, vous pouvez voir des traits de soulignement en tant que séparateurs au lieu de majuscules. Par exemple, lorsque l'API utilise availabilityDomain, la configuration Terraform utilise availability_domain.

Exigences pour le fichier de configuration

Les fichiers de configuration Terraform (.tf) ont des exigences spécifiques, selon les composants définis dans le fichier. Par exemple, le fournisseur Terraform peut être défini dans un fichier (provider.tf), les variables dans un autre fichier (variables.tf) et les sources de données encore dans un autre fichier.

Note

Par exemple, pour les fichiers de configuration, voir Exemples de fournisseurs Oracle Cloud Infrastructure Terraform.

Définitions de fournisseur

Note

Pour les fournisseurs tiers dans les configurations Terraform utilisées avec le gestionnaire de ressources, voir Configuration de fournisseurs tiers.

L'exemple ci-après utilisant la syntaxe Terraform illustre les exigences pour une définition de fournisseur Terraform pour OCI et montre également les définitions de variable associées. La définition du fournisseur repose sur des variables, de sorte que le fichier de configuration lui-même ne contient pas de données sensibles. L'inclusion de données sensibles crée un risque de sécurité lors de l'échange ou du partage de fichiers de configuration.

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'attribut region spécifie la région géographique dans laquelle les ressources de fournisseur sont créées. Pour cibler plusieurs régions dans une configuration unique, il suffit de créer une définition de fournisseur pour chaque région et de les différencier à l'aide d'un alias de fournisseur, comme illustré dans l'exemple suivant. Notez qu'un seul fournisseur, nommé oci, est défini et que la définition du fournisseur oci est entrée deux fois, une fois pour la région us-phoenix-1 (avec l'alias phx) et une fois pour la région us-ashburn-1 (avec 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}"
}

Pour plus d'informations, voir Configuration du fournisseur.

Définition de variables

Note

Dans le gestionnaire de ressources, les variables sont soumises aux limites suivantes.

Variables par pile : 250

Taille par variable : 8 192 octets

Les variables dans Terraform représentent des paramètres pour les modules Terraform. Dans les définitions de variable, chaque bloc configure une variable d'entrée unique et chaque définition peut prendre l'un des arguments facultatifs suivants ou tous :

  • type (facultatif) : Définit le type de variable comme l'une des trois valeurs autorisées : string, list et map. Si cet argument n'est pas utilisé, le type de variable est déduit en fonction de la valeur default. Si aucune valeur default n'est indiquée, le type est supposé être string.
  • default (facultatif) : Définit la valeur par défaut de la variable. Si aucune valeur par défaut n'est fournie, l'appelant doit fournir une valeur ou Terraform génère une erreur.
  • description (facultatif) : Description lisible de la variable.

Exemples de définitions de variables : Certaines définitions incluent des paramètres facultatifs.

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
}

Pour plus d'informations, voir Variables d'entrée.

Configuration de sortie

Les variables de sortie fournissent un moyen pour prendre en charge les interrogations d'utilisateur Terraform. Utilisez les variables de sortie pour extraire des données pertinentes de la quantité potentiellement importante de données associées à une infrastructure complexe. Par exemple, vous n'êtes peut-être intéressé que par des valeurs de clé à un moment donné. La définition de variables de sortie vous permet d'extraire exactement les informations dont vous avez besoin.

Voici un exemple simple dans lequel seules quelques variables de sortie (adresses IP d'instance et ID volume de démarrage) sont définies :

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

Pour plus d'informations, voir Données de sortie de Terraform. Voir aussi Valeurs de sortie.

Ressources

Les ressources sont des composants d'Oracle Cloud Infrastructure. Ces ressources englobent aussi bien des composants de bas niveau, tels que des serveurs physiques et virtuels, que des composants de niveau supérieur, tels que des fournisseurs de courriel et de base de données, ou votre enregistrement DNS.

Attention

Les fichiers d'état de Terraform contiennent tous les attributs de ressource spécifiés dans les fichiers de configuration. Si vous gérez des données sensibles avec Terraform, telles que des mots de passe de base de données ou d'utilisateur ou des clés privées d'instance, nous vous recommandons de traiter le fichier d'état lui-même en tant que données sensibles. Pour plus d'informations, voir Données sensibles dans l'état.

Déclaration des ressources

Vous trouverez ci-dessous un exemple simple de définition de ressources qui illustre leur structure de 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 déclaration de ressource dans la première ligne de l'exemple utilise le mot clé "resource" et prend deux paramètres, type de ressource et name (nom) de ressource (soit "oci_core_virtual_network" et "vcn1" dans l'exemple). Dans le bloc de code, se trouve ensuite la configuration de la ressource.

Pour plus d'informations, voir Ressources.

Dépendances de ressource

Lorsqu'une ressource référence une autre ressource dans son bloc de ressource, Terraform ajoute automatiquement la dépendance de la ressource principale à la ressource référencée. Une ressource peut également dépendre de ressources qui ne sont pas référencées explicitement dans son bloc. Par exemple, il peut être nécessaire de créer des politiques pour une ressource avant de créer la ressource elle-même.

Pour définir des dépendances masquées que Terraform ne peut pas déduire automatiquement, vous pouvez utiliser le méta-argument depends_on dans le bloc de ressource.

L'exemple suivant crée une ressource oci_datascience_notebook_session et une ressource oci_identity_policy pour les politiques connexes. L'ajout du méta-argument depends_on à la ressource oci_datascience_notebook_session garantit que les politiques sont créées en premier :

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
 }

Référencement des ressources dans une autre pile (en exportant les valeurs de sortie de la pile)

Vous pouvez référencer des ressources qui existent dans d'autres piles. La source de données remote_state de Terraform vous permet de lire des variables de sortie à partir de fichiers d'état.

Par exemple, lors de l'écriture d'une configuration Terraform pour une nouvelle application Web, vous pouvez faire en sorte que l'application Web utilise le sous-réseau créé à partir de la pile réseau, tant que les valeurs de sous-réseau requises ont été générées en sortie dans le fichier d'état de la pile réseau. Dans la configuration Terraform de votre nouvelle application Web, procédez de la façon suivante :

  • Extrayez le fichier d'état de la pile réseau existante dans le contexte de la configuration Terraform courante.

    L'extraction du fichier d'état exporte les valeurs de sortie de la pile. Pour obtenir des instructions sur l'extraction du fichier d'état dans le gestionnaire de ressources, voir Obtention du fichier d'état d'une pile.

  • Chargez le fichier d'état extrait vers une source de données pour les fichiers d'état distants.

  • Alimentez la source de données du sous-réseau dans la configuration courante avec des valeurs provenant des variables de sortie appropriées du fichier d'état référencé.

  • Facultativement, imprimez les informations d'identification de la source de données alimentée pour confirmer les valeurs attendues.

Note

En plus des autorisations requises pour les opérations du gestionnaire de ressources, vous aurez besoin des autorisations appropriées pour les types de ressource que vous référencez, dans le compartiment dans lequel vous les référencez. Dans cet exemple, vous devez disposer d'autorisations de lecture pour les ressources de réseau dans le compartiment dans lequel elles se trouvent.

L'extrait de la configuration Terraform suivante référence un sous-réseau dans une autre pile :

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

Sources de données

Les sources de données représentent des vues en lecture seule de l'infrastructure existante destinée à une utilisation sémantique dans les configurations Terraform. Voici un exemple simple de configuration de source de données pour illustrer sa structure de 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}"
}

Pour plus d'informations, voir Sources de données.

Filtrage des sources de données

Les sources de données qui retournent des listes de ressources prennent en charge la sémantique de filtrage. Pour utiliser un filtre, incluez ce bloc dans la définition de source de données :

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

La valeur name correspond au nom de propriété qualifié sur lequel effectuer le filtrage et les listes values peuvent contenir un ou plusieurs filtres de valeur.

Les propriétés imbriquées et les éléments de mappage peuvent être traités en qualifiant le nom de la propriété avec le nom de la propriété parent. L'exemple r1 donne toutes les instances qui ont l'image source_type. Exemple r2 donne toutes les instances qui contiennent un marqueur défini avec la valeur "42" pour la clé CostCenter dans l'espace de noms 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"]
  }
}

Plusieurs valeurs (values) fonctionnent en tant que filtre de type OR. Dans l'exemple de forme suivant, la source de données résultante contient les formes de machine virtuelle Standard 1.1 et Standard 1.2 :

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

Plusieurs blocs de filtres peuvent être composés pour former des comparaisons de type AND. L'exemple suivant retourne une source de données contenant des instances en cours d'exécution dans le premier domaine de disponibilité d'une région :

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

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

Comme le montrent les exemples précédents, les filtres peuvent également utiliser des expressions régulières. Le paramètre regex = true traite chaque élément de la liste values comme une expression rationnelle. Les barres obliques inverses dans les chaînes pour les caractères spéciaux d'expression rationnelle doivent être échappées avec une autre barre oblique, affichée dans les exemples précédents en tant que première barre oblique \ avant \w dans "\\w*-AD-1".

Note

Le forage dans les listes d'objets structurés n'est pas pris en charge. Si ces propriétés sont ciblées, la source de données ne retourne aucun résultat.

Fonctions

Terraform offre plusieurs fonctions intégrées que vous pouvez utiliser dans vos fichiers de configuration. Ces fonctions vous permettent de modifier des chaînes, d'effectuer des calculs en fonction des valeurs numériques, de gérer des collections et bien plus encore.

Pour plus d'informations, voir Fonctions intégrées.