Documentation Oracle Cloud Infrastructure

Configurations de création

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

A l'aide de Terraform, vous pouvez décrire les ressources d'infrastructure à l'aide du format HashiCorp Configuration Language (HCL) dans les fichiers de configuration Terraform (reportez-vous à Syntaxe de configuration). Les fichiers de configuration Terraform peuvent utiliser l'un des deux formats suivants : le langage propre au domaine Terraform (format HCL, HashiCorp Configuration Language), qui est l'approche recommandée, ou le format JSON si les fichiers doivent être lisibles par la machine. Les fichiers de configuration qui utilisent le format HCL se terminent par l'extension de fichier .tf, alors que 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 la machine.

Utilisez les configurations Terraform pour définir des ressources Oracle Cloud Infrastructure (OCI), des définitions de variable, des sources de données et bien plus encore. Terraform convertit ensuite les configurations OCI en un ensemble d'appels d'API par rapport aux adresses d'API OCI. Pour écrire une configuration Terraform, il est important de comprendre comment extraire l'infrastructure souhaitée de manière conceptuelle dans la syntaxe de configuration Terraform.

Important

Même si l'API Oracle Cloud Infrastructure utilise intensément camelCase, Terraform ne prend pas en charge camelCase dans les fichiers de configuration. C'est pourquoi les séparateurs dans les configurations sont des traits de soulignement et non des lettres majuscules. Par exemple, lorsque l'API utilise availabilityDomain, la configuration Terraform utilise availability_domain.

Exigences relatives aux fichiers de configuration

Les fichiers de configuration Terraform (.tf) présentent des exigences spécifiques, en fonction des composants qui y sont définis. Par exemple, vous pouvez définir un fournisseur Terraform dans un fichier (provider.tf), des variables définies dans un autre (variables.tf) et des sources de données définies dans un autre.

Remarque

Pour obtenir des exemples de fichier de configuration, reportez-vous à Exemples de fournisseur Oracle Cloud Infrastructure Terraform.

Définitions de fournisseur

Remarque

Pour les fournisseurs tiers dans les configurations Terraform utilisées avec Resource Manager, reportez-vous à Configuration de fournisseur tiers.

L'exemple suivant, qui utilise la syntaxe Terraform, illustre les exigences relatives à une définition de fournisseur OCI Terraform et affiche également les définitions de variable associées. La définition de fournisseur s'appuie sur des variables de sorte que le fichier de configuration ne contienne pas de données confidentielles. L'insertion de données confidentielles entraîne un risque de sécurité lors de l'échange ou du partage des 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 votre fournisseur sont créées. Afin de cibler plusieurs régions dans une même configuration, il vous suffit de créer une définition de fournisseur pour chaque région, puis de les différencier en utilisant un alias de fournisseur, comme indiqué dans l'exemple suivant. Vous pouvez remarquer qu'un seul fournisseur nommé "oci" est défini, mais que la définition de fournisseur oci est saisie 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, reportez-vous à Configuration du fournisseur.

Définitions de variable

Remarque

Dans Resource Manager, les variables sont soumises aux limites suivantes.

Variables par pile : 250

Taille par variable : 8 192 octets

Les variables dans Terraform représentent les 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 accepter l'un des arguments facultatifs suivants ou les trois :

  • type (facultatif) : définit le type de variable sur 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 default. Si aucun argument default n'est fourni, le type est considéré comme 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 indiquer une valeur. Sinon, Terraform génère une erreur.
  • description (facultatif) : description de la variable lisible par l'utilisateur.

Voici quelques exemples de définition de variable. 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, reportez-vous à Variables d'entrée.

Configuration de sortie

Les variables de sortie permettent de prendre en charge les requêtes d'utilisateur final Terraform. Les utilisateurs peuvent ainsi extraire des données significatives à partir d'un nombre potentiellement élevé de données associées à une infrastructure complexe. Par exemple, il se peut que vous soyez intéressé uniquement par quelques valeurs clés à un moment donné. En définissant des variables de sortie, vous pouvez extraire exactement les informations dont vous avez besoin.

Vous trouverez ci-après un exemple simple dans lequel seules quelques variables de sortie (adresses IP d'instance et ID de volume d'initialisation) 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, reportez-vous à Variables de sortie. Reportez-vous également à Configuration de sortie.

Ressources

Les ressources sont des composants de votre instance Oracle Cloud Infrastructure. Ces ressources incluent aussi bien les composants de niveau inférieur, tels que les serveurs physiques et virtuels, que les composants de niveau supérieur, tels que les fournisseurs de messagerie et de base de données, ou votre enregistrement DNS.

La référence complète des ressources et sources de données prises en charge par le fournisseur OCI Terraform contient les détails relatifs à la syntaxe, aux arguments et aux attributs. La référence complète est disponible à l'adresse docs.oracle.com et Terraform Registry.

Les sources de données et les ressources sont regroupées par service dans la référence.

Attention

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

Déclaration de ressources

Vous trouverez ci-dessous un exemple simple de définition de ressource illustrant la 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 sur la première ligne de l'exemple utilise le mot-clé "resource" et inclut deux paramètres de ressource, type et name ("oci_core_virtual_network" et "vcn1" dans l'exemple). La configuration de la ressource se trouve dans le bloc de code.

Pour plus d'informations, reportez-vous à Configuration de ressource.

Dépendances des ressources

Lorsqu'une ressource référence une autre ressource dans son bloc, Terraform déduit 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 explicitement référencées dans son bloc. Par exemple, vous devrez peut-être créer des stratégies pour une ressource avant de créer la ressource elle-même.

Pour définir les 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 stratégies associées. L'ajout du méta-argument depends_on à la ressource oci_datascience_notebook_session fait en sorte que les stratégies 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 de ressources dans une autre pile (en exportant les valeurs de sortie de pile)

Vous pouvez référencer les ressources qui existent dans d'autres piles. La source de données remote_state 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 précédemment créé à partir de votre pile réseau, tant que les valeurs de sous-réseau requises ont été générées dans le fichier d'état de la pile réseau. Dans la configuration Terraform de la nouvelle application Web, procédez comme suit : 

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

    L'extraction du fichier d'état exporte les valeurs de sortie de pile. Pour obtenir des instructions sur l'extraction du fichier d'état dans Resource Manager, reportez-vous à Obtention du fichier d'état d'une pile.

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

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

  • Eventuellement, imprimez les informations d'identification de la source de données qui a été remplie pour vérifier les valeurs attendues.

Remarque

Outre les droits d'accès requis pour les opérations de Resource Manager, vous avez besoin des droits d'accès appropriés pour les types de ressource que vous référencez, dans le compartiment où vous les référencez. Dans cet exemple, vous devez disposer de droits d'accès en lecture pour les ressources réseau du compartiment où elles se trouvent.

L'extrait de configuration Terraform suivant référence un sous-réseau d'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ées à 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, reportez-vous à la configuration des sources de données.

Filtrer les sources de données

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

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

La valeur name correspond au nom de propriété qualifié pour le filtrage et les listes values peuvent contenir des valeurs pour le filtrage.

Les propriétés imbriquées et les éléments de correspondance peuvent être obtenus en qualifiant le nom de propriété avec le nom de propriété parent. L'exemple r1 renvoie toutes les instances avec une image source_type. L'exemple r2 renvoie toutes les instances contenant une balise définie 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"]
  }
}

L'indication de plusieurs éléments values fonctionne comme un filtre de type OR. Dans l'exemple de forme ci-dessous, la source de données obtenue 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 ci-dessous renvoie 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 indiqué ci-dessus, les filtres peuvent également utiliser des expressions régulières. Si vous définissez regex = true, chaque élément de la liste values est traité comme une expression régulière. Les barres obliques inverses dans les chaînes pour les caractères spéciaux d'expression régulière doivent être échappées avec une autre barre oblique inverse, représentée ci-dessus par la première barre \ avant \w dans "\\w*-AD-1".

Remarque

L'exploration des listes d'objets structurés n'est pas prise en charge actuellement. Si ces propriétés sont ciblées, aucun résultat n'est renvoyé à partir de la source de données.

Fonctions

Terraform offre toute une variété de 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 par rapport à des valeurs numériques, de gérer des collections et bien plus encore.

Pour plus d'informations, reportez-vous à Fonctions.