Documentation Oracle Cloud Infrastructure

Utilisation du repérage des ressources

La fonctionnalité de repérage des ressources du fournisseur Oracle Cloud Infrastructure (OCI) Terraform utilise terraform-exec de HashiCorp pour importer les ressources OCI repérées vers les fichiers de configuration et d'état Terraform.

Prérequis

La commande terraform-exec requiert la présence de l'interface de ligne de commande Terraform sur votre système. Pour plus d'informations sur l'installation, reportez-vous à Téléchargement et installation de Terraform.

Remarque

Si vous utilisez Terraform v0.11, cet outil ne peut pas générer de fichier d'état. Seules les configurations sont prises en charge dans v0.11. Par défaut, les configurations sont générées dans v0.12.

Si vous utilisez l'interface de ligne de commande Terraform v0.13.*, assurez-vous que la version est compatible avec la syntaxe v0.12.

En outre, le fournisseur OCI Terraform doit être téléchargé et installé. Pour obtenir des instructions de téléchargement, reportez-vous à Téléchargement et installation du fournisseur.

Ajout des outils au chemin

Pour exécuter le fournisseur OCI Terraform en tant qu'exécutable et utiliser le repérage des ressources, vous pouvez effectuer les opérations suivantes :

  • Ajouter terraform-provider-oci au chemin système
  • Exécuter le fournisseur à partir du répertoire dans lequel il est situé
  • Indiquer le chemin complet du fournisseur lorsque vous exécutez les commandes de repérage des ressources

Etant donné que les commandes de repérage des ressources utilisent terraform-exec pour appeler Terraform en votre nom, votre système doit spécifier l'emplacement de l'interface de ligne de commande Terraform à l'aide de l'une des méthodes suivantes :

  • Indiquez le chemin complet, y compris le nom de l'interface de ligne de commande Terraform, à l'aide de la variable d'environnement terraform_bin_path. Pour plus d'informations sur la définition des variables, reportez-vous à Variables d'environnement.
  • Ajoutez l'interface de ligne de commande Terraform à votre chemin système.

Authentification

Pour repérer les ressources dans votre compartiment, le fournisseur OCI Terraform a besoin d'informations d'authentification sur l'utilisateur, la location et la région avec lesquels repérer les ressources. Il est recommandé d'indiquer un utilisateur disposant d'un accès qui lui permet d'inspecter et de lire les ressources à repérer.

Vous pouvez utiliser l'authentification par clé d'API et les variables d'environnement ou l'autorisation de principal d'instance pour fournir les informations requises.

Export de ressources

Une fois que vous avez indiqué l'emplacement de l'interface de ligne de commande Terraform et les paramètres d'authentification, vous pouvez utiliser l'une des commandes suivantes pour exporter les ressources d'un compartiment :

terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
terraform-provider-oci -command=export -compartment_id=<compartment_OCID> -output_path=<output_path>

Ces commandes repèrent toutes les ressources prises en charge dans le compartiment et génèrent des fichiers de configuration Terraform dans le fichier output_path fourni. Les fichiers .tf générés contiennent la configuration Terraform avec les ressources repérées par la commande.

Attention

Assurez-vous que output_path est vide avant d'exécuter le repérage des ressources.
Remarque

Le paramètre compartment_id est requis si vous utilisez l'autorisation de principal d'instance.

Les combinaisons de paramètres communes suivantes exportent les ressources décrites :

  • compartment_id=<vide_ou_OCID_location> services=<vide_ou_non_spécifié> : toutes les ressources dans la portée de la location et du compartiment.
  • compartment_id=<vide_ou_OCID_location> services=<liste_séparée_virgules> : ressources dans la portée de la location et du compartiment pour les services spécifiés.
  • compartment_id=<OCID_nonracine> services=<vide_ou_non_spécifié> : toutes les ressources dans la portée du compartiment.
  • compartment_id=<OCID_nonracine> services=<liste_séparée_virgules> : ressources dans la portée du compartiment pour les services spécifiés. Les ressources de portée de location ne sont pas repérées même si des services avec de telles ressources sont spécifiés.
Remarque

L'export des ressources de compartiment prend uniquement en charge le compartiment cible. Les ressources dans les compartiments enfant ne sont pas repérées.

Paramètres

Vous pouvez utiliser les paramètres suivants pour contrôler le comportement de l'outil de repérage des ressources.

Paramètre Détails
command Commande à exécuter. Les commandes prises en charge sont les suivantes :
  • export : repère les ressources OCI dans le compartiment et génère des fichiers de configuration Terraform pour elles
  • list_export_resources : répertorie les types de ressource OCI Terraform repérés par la commande export
  • list_export_services : répertorie les valeurs autorisées pour les arguments des services, ainsi que la portée au format JSON
compartment_id OCID du compartiment à exporter. Si compartment_id ou compartment_name n'est pas indiqué, le compartiment racine est utilisé. Requis si vous recourez à l'autorisation de principal d'instance.
compartment_name Nom du compartiment à exporter. Si compartment_id ou compartment_name n'est pas indiqué, le compartiment racine est utilisé.
exclude_services Liste des ressources de service à exclure de l'export, séparées par des virgules. Tout service présent dans les arguments services et exclude_services est exclu.
filter Filtrer les ressources repérées selon les critères indiqués. Pour plus d'informations, reportez-vous à Filtrage des ressources.
generate_state Fournissez cet indicateur pour importer les ressources repérées dans un fichier d'état en plus des fichiers de configuration Terraform.
ids Liste des tuples <type_ressource:ID_ressource> (par exemple, oci_core_instance:ocid.....) pour les ressources à exporter, séparés par des virgules. L'ID peut être un OCID ou un ID d'import Terraform. Par défaut, toutes les ressources sont exportées.
list_export_services_path Chemin complet, comprenant le nom du fichier, à utiliser comme sortie pour la liste des services pris en charge, au format JSON.
output_path Chemin absolu de sortie des configurations et fichiers d'état générés du compartiment exporté.
parallelism Nombre de threads permettant de repérer les ressources en parallèle. La valeur par défaut est 1.
retry_timeout Durée en secondes pendant laquelle les appels d'API attendent et retentententent l'opération en cas d'erreurs d'API. Par défaut, le délai d'expiration de la nouvelle tentative est de 15 secondes.
services Liste des ressources de service à exporter, séparées par des virgules. Si elle n'est pas indiquée, toutes les ressources du compartiment fourni (à l'exception des ressources IAM) sont exportées.

Reportez-vous à Services pris en charge pour obtenir les valeurs acceptées et à Export de ressources d'identité pour obtenir les informations associées.
tf_version Version de la syntaxe Terraform à utiliser lors de la génération des fichiers de configuration. La valeur par défaut est v0.12. Valeurs autorisées :
  • 0.11
  • 0.12

Si vous indiquez 0.11 comme version de syntaxe, utilisez v0.11 de l'interface de ligne de commande Terraform pour repérer les ressources.

Si vous utilisez l'interface de ligne de commande Terraform v0.13 et versions ultérieures pour repérer les ressources, assurez-vous que la version est compatible avec la syntaxe v0.12.

Les fichiers d'état sont générés dans la syntaxe Terraform correspondant à la version de l'interface de ligne de commande Terraform utilisée pour repérer les ressources. Le paramètre tf_version ne s'applique pas aux fichiers d'état.
variables_global_level

Répertoriez les attributs de niveau supérieur à exporter en tant que variables, en respectant le format attribute1,attribute2. Les attributs de niveau ressource (variables_resource_level) sont exclus de cette liste.
variables_resource_level

Répertoriez les attributs de niveau ressource à exporter en tant que variables, en respectant le format resourceType.attribute. Les attributs de niveau supérieur (variables_global_level) sont exclus de cette liste.

Filtrage des ressources

Filtrer les ressources repérées selon les critères indiqués :

  • Filtre de type de ressource : Type<operator><provider-resource-type>

    <operator> est = (égal à) ou != (n'est pas égal à)

  • Filtre d'attribut : AttrName=<attribute-name>;Value<operator><value> Rechercher toutes les ressources avec l'attribut et la valeur correspondants
  • Jusqu'à 10 filtres (les ressources doivent tous satisfaire)
Filtre de type de ressource : VCN uniquement
--filter="Type=oci_core_vcn"
Filtre de type de ressource : Tout sauf VCN
--filter="Type!=oci_core_vcn"
Filtre d'attribut : Valeur de balise définie
--filter="AttrName=defined_tags.example-namespace.example-key;Value=example-value"
Filtres multiples : VCN uniquement, l'attribut dns_label doit être défini pour le test
--filter="Type=oci_core_vcn" --filter="AttrName=dns_label;Value=test"

Pour plus d'informations sur le filtrage des ressources repérées, reportez-vous à Filtrage des ressources repérées via le repérage des ressources.

Journalisation en mode verbose

Pour obtenir une sortie de console détaillée lorsque le fournisseur est en cours d'exécution, faites précéder la commande de repérage de ressources des indicateurs TF_LOG ou OCI_TF_LOG. Par exemple :

TF_LOG=DEBUG terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
OCI_TF_LOG=DEBUG terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>

Les indicateurs TF_LOG (niveau) et OCI_TF_LOG peuvent également être définis en tant que variables d'environnement.

Pour rediriger la sortie de la console en mode verbose vers un fichier journal, définissez la variable d'environnement OCI_TF_LOG_PATH et indiquez le chemin.

Statut de sortie

Pour toute erreur liée aux API OCI ou à l'indisponibilité du service lors du repérage des ressources, l'outil passe à la recherche de la ressource suivante. Toutes les erreurs rencontrées sont affichées une fois le repérage terminé.

  • Code de sortie 0 : succès.
  • Code de sortie 1 : échec en raison d'erreurs telles que des variables d'environnement, des arguments ou une configuration incorrects.
  • Code de sortie 64 : succès partiel. Le repérage des ressources n'a pas pu trouver toutes les ressources en raison d'échecs de service.

Export de ressources d'identité

Certaines ressources, telles que les ressources d'identité, existent uniquement au niveau de la location et ne peuvent pas être repérées dans un compartiment spécifique. Pour repérer ces ressources, utilisez la commande suivante, qui omet tout paramètre de compartiment :
terraform-provider-oci -command=export -output_path=<output_path> -services=identity
Remarque

Lorsque vous exportez des ressources d'identité, la valeur compartment_id, si elle est indiquée, est ignorée.

Export de ressources vers un autre compartiment

Une fois que vous avez examiné les fichiers de configuration Terraform générés et apporté les modifications nécessaires, la configuration peut être utilisée avec Terraform. L'un des cas d'emploi est le redéploiement de ces ressources dans un nouveau compartiment ou une nouvelle location, à l'aide de Terraform.

Pour ce faire, indiquez les variables d'environnement suivantes :

export TF_VAR_tenancy_ocid=<target_tenancy_OCID>
export TF_VAR_compartment_ocid=<target_compartment_OCID>

Exécutez ensuite la commande suivante :

terraform apply

Génération d'un fichier d'état Terraform

Attention

Le fichier d'état contient 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 à Stockage des données confidentielles.

Il est également possible de générer un fichier d'état Terraform pour gérer les ressources repérées. Pour ce faire, exécutez la commande suivante, qui inclut l'indicateur -generate_state :

terraform-provider-oci -command=export -compartment_id=<compartment_OCID> -output_path=<output_path> -generate_state

Résultent de cette commande les fichiers .tf représentant la configuration Terraform et un fichier terraform.tfstate représentant l'état. Pour plus d'informations, reportez-vous à Etat.

Remarque

Le fichier d'état Terraform généré par cette commande est uniquement compatible avec Terraform v0.12.4 et versions ultérieures.