Documentation sur Oracle Cloud Infrastructure

Utilisation de l'inventaire Ansible

Ansible permet de suivre les ressources de configuration en préservant des listes, appelées listes d'inventaire, en tant que fichiers simples (parfois appelés fichiers hôtes). Ces listes d'inventaire peuvent être statiques ou dynamiques. Les listes dynamiques peuvent être mises à jour automatiquement lorsque des ressources d'inventaire sont ajoutées, supprimées ou déplacées.

Étant donné que de nombreuses ressources Oracle Cloud Infrastructure (OCI) sont ajoutées et supprimées au fil du temps, les listes d'inventaire statique peuvent facilement devenir obsolètes. Des outils tels que Terraform ou les SDK pour l'OCI peuvent également affecter vos ressources.

Oracle Cloud Infrastructure fournit un plugiciel d'inventaire dynamique pour assurer l'exactitude de l'inventaire Ansible.

Pour plus d'informations sur les fichiers d'inventaire Ansible, voir Utilisation de l'inventaire et Utilisation de l'inventaire dynamique.

Activation du plugiciel d'inventaire

Si vous avez un fichier ansible.cfg existant et que cette configuration active déjà les plugiciels à l'aide de enable_plugins, vous devez activer le plugiciel d'inventaire OCI en l'ajoutant également. Par exemple :

[inventory]
enable_plugins = oracle.oci.oci

Si vous n'avez pas encore de fichier ansible.cfg contenant enable_plugins, vous n'avez pas besoin d'ajouter le plugiciel d'inventaire OCI à la configuration.

Configuration du plugiciel d'inventaire

La seule exigence pour l'utilisation d'un plugiciel d'inventaire OCI une fois qu'il est activé est de fournir une source d'inventaire à analyser. Les sources d'inventaire sont définies dans un fichier de configuration YAML. Pour plus d'informations, voir Autorisations d'utilisateur.

Pour commencer à utiliser le plugiciel d'inventaire avec une source de configuration YAML, créez un fichier avec l'un des noms de fichiers acceptés suivants :

  • <nomdefichier>.oci.yml
  • <nomdefichier>.oci.yaml

Ajoutez plugin: oracle.oci.oci au fichier de configuration YAML.

Par exemple, voici le fichier de source d'inventaire minimal nécessaire pour exécuter le plugiciel d'inventaire OCI :

# demo.oci.yml
plugin: oracle.oci.oci
 
# Optional fields to specify oci connection config:
config_file: ~/.oci/config
config_profile: DEFAULT

Cet exemple utilise les paramètres config_file et config_profile afin que le plugiciel puisse utiliser les informations d'authentification décrites dans le fichier de configuration des trousses SDK et de l'interface de ligne de commande. Certains paramètres peuvent également être fournis en tant que variables d'environnement.

Pour une liste complète des paramètres et des variables d'environnement pris en charge par le plugiciel, voir Plugiciel d'inventaire OCI. Les scénarios d'inventaire incluent la plupart des paramètres disponibles.

Important

Par défaut, le plugiciel d'inventaire OCI détecte et liste uniquement les instances de calcul qui ont une adresse IP publique. Pour plus d'informations, voir Préférences de format du nom d'hôte.

Ordre de priorité

Le plugiciel d'inventaire utilise l'ordre de priorité suivant lorsqu'une option est fournie dans plusieurs emplacements :

  1. Paramètres du fichier YAML.
  2. Variables d'environnement.
  3. Paramètres de configuration pour le profil profile sélectionné dans votre fichier de configuration OCI.

Extraction des hôtes de base de données

Par défaut, le plugiciel d'inventaire OCI détecte et liste uniquement les instances de calcul. Les noeuds de base de données sont des serveurs exécutant le logiciel de base de données. Les noeuds de base de données sont extraits en réglant l'option fetch_db_hosts à true. Par exemple :

# demo.oci.yml

# DB Hosts
plugin: oracle.oci.oci
fetch_db_hosts: true

Utilisation du plugiciel d'inventaire

Les plugiciels d'inventaire Ansible vous permettent de définir les sources de données utilisées pour compiler un inventaire d'hôtes qu'Ansible utilise pour les tâches cibles. Ces sources de données sont accessibles à l'aide des paramètres de ligne de commande -i /path/to/file ou -i 'host1, host2', ou à partir d'autres sources de configuration.

Par exemple, vous pouvez lancer l'inventaire avec cette commande :

ansible-inventory -i <filename>.oci.yml --graph

Cela produira une sortie similaire à la suivante :

@all:
  |--@oci:
  |  |--compute_instance1
  |  |--compute_instance2
  |–@ungrouped:
Important

Par défaut, l'inventaire est généré pour tous les compartiments de la location. Vous devez disposer de l'autorisation COMPARTMENT_INSPECT dans le compartiment racine pour que ce script puisse accéder à tous les compartiments. Toutefois, lorsque compartment_ocid est spécifié, l'inventaire est généré uniquement pour le compartiment spécifique, de sorte que vous n'avez besoin que de l'autorisation COMPARTMENT_INSPECT sur le compartiment indiqué. Pour plus d'informations, voir Fonctionnement des politiques.

Pour extraire tous les détails d'instance, vous devez également avoir l'autorisation de lister et de lire des instances et des cartes VNIC, et de lire des VCN et des sous-réseaux. Pour plus d'informations, voir Autorisations d'utilisateur.

Vous pouvez ajouter des plugiciels d'inventaire à votre chemin de plugiciel et définir le chemin d'inventaire par défaut pour simplifier vos commandes. Ajoutez le chemin d'accès à l'inventaire par défaut dans la section [defaults] de votre fichier ansible.cfg ou utilisez la variable d'environnement ANSIBLE_INVENTORY pour désigner vos sources d'inventaire. Vous pouvez ensuite exécuter la commande suivante pour produire la même sortie que lorsque vous transmettez directement vos sources de configuration YAML :

ansible-inventory --graph

En général, les plugiciels d'inventaire ne se lancent qu'au début d'une exécution, avant que les livres de jeu, les jeux et les rôles soient chargés. Vous pouvez "reexécuter" un plugiciel en utilisant la tâche meta: refresh_inventory, qui efface l'inventaire existant et la reconstruit.

Sortie d'inventaire

La liste d'inventaire générée par le plugiciel d'inventaire est regroupée à l'aide des attributs suivants :

  • La région dans laquelle réside l'instance de calcul
  • Le nom du compartiment auquel appartient l'instance de calcul
  • Le domaine de disponibilité dans lequel se trouve l'instance de calcul
  • Le vcn_id du réseau en nuage virtuel dans lequel se trouve l'instance de calcul
  • Le subnet_id du sous-réseau dans lequel se trouve l'instance de calcul
  • Les security_list_ids du sous-réseau dans lequel se trouve l'instance de calcul
  • L'image_id de l'image utilisée pour lancer l'instance de calcul
  • La forme de l'instance de calcul
  • Les marqueurs à structure libre de l'instance de calcul, avec le nom du groupe réglé à tag_<tag_name>=<tag_value>
  • Les marqueurs définis de l'instance de calcul, avec le nom du groupe réglé à <tag_namespace>#<tag_name>=<tag_value>
  • Les métadonnées d'instance du service de calcul pour OCI ( paires clé-valeur) avec le nom du groupe réglé à <metadata-key>=<metadata-value>
  • Les métadonnées étendues d'instance du service de calcul pour OCI ( paires clé-valeur) avec le nom du groupe réglé à <metadata-key>=<metadata-value>

Préférences de format du nom d'hôte

L'inventaire généré par le plugiciel d'inventaire OCI ne contient que des instances qui ont une adresse IP publique par défaut. Cela s'avère utile lorsque le noeud du contrôleur Ansible se trouve à l'extérieur du réseau en nuage virtuel, car Ansible ne peut atteindre que des instances ayant des adresses IP publiques.

Vous pouvez configurer inventory_hostname sur private_ip ou tout nom d'hôte personnalisé en transmettant des expressions Jinja2 sous forme de liste à l'option hostname_format_preferences. L'option hostname_format_preferences accepte une liste d'expressions Jinja2 par ordre de priorité pour composer inventory_hostname. Le plugiciel d'inventaire ignore les expressions si le résultat est une chaîne vide ou la valeur "Aucun". L'instance est ignorée si aucune des expressions hostname_format_preferences ne produit une valeur non vide.

L'exemple suivant règle inventory_hostname à "display_name+'.oci.com'" ou "private_ip" ou "public_ip" :

hostname_format_preferences:
  - "display_name+'.oci.com'"
  - "private_ip"
  - "public_ip"

Les expressions du répertoire host_vars de chaque instance sont évaluées. L'évaluation respecte l'ordre de priorité de votre configuration pour composer inventory_hostname. Dans l'exemple précédent, "display_name+'.oci.com'" est évalué avant "private_ip" et "public_ip".

Filtrage des hôtes

Le plugiciel d'inventaire OCI est fourni avec diverses options de filtrage des hôtes retournés par le plugiciel.

Exclure des hôtes de l'inventaire

Vous pouvez transmettre une liste d'expressions conditionnelles Jinja2 au paramètre exclude_host_filters. Chaque expression de la liste est évaluée pour chaque hôte. Lorsque l'évaluation retourne la valeur True, l'hôte est exclu de l'inventaire. Le paramètre exclude_host_filters est prioritaire sur les options include_host_filters et filters.

L'exemple suivant exclut de l'inventaire les hôtes qui ne se trouvent pas dans la région 'iad' :

exclude_host_filters:
  - "region not in ['iad']"

Exclure des hôtes à l'aide de marqueurs à structure libre

Pour exclure un hôte de l'inventaire à l'aide de marqueurs à structure libre, vous pouvez utiliser la syntaxe suivante :

exclude_host_filters:
  # filter the hosts with freeform tag with key <tag_key> which has value <tag_value>
  - "'<tag_value>' == freeform_tags.<tag_key>"
  # filter the hosts which has <tag_key> freeform tag
  - "'<tag_key>' in freefrom_tags"

Par exemple :

exclude_host_filters:
  - "'operating_system' in freeform_tags"
  - "'linux' == freeform_tags.operating_system"

Exclure des hôtes à l'aide de marqueurs définis

Pour exclure un hôte de l'inventaire à l'aide de marqueurs définis, vous pouvez utiliser la syntaxe suivante :

exclude_host_filters:
  #filter the hosts with defined tag in <namespace> with <tag_key> and <tag_value>
  - "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  # filter the hosts with <tag_key> in the <namespace> in defined tags
  - "'<tag_key>' in defined_tags.<namespace>"

Par exemple :

exclude_host_filters:
  - "'ansible' == defined_tags.ansible_collections_tag_namespace.managed_by"
  - "'managed_by' in defined_tags.ansible_collections_tag_namespace"

Inclure des hôtes dans l'inventaire

Vous pouvez transmettre une liste d'expressions conditionnelles Jinja2 au paramètre include_host_filters. Chaque expression de la liste est évaluée pour chaque hôte. Lorsque l'évaluation retourne la valeur True, l'hôte est inclus dans l'inventaire.

L'exemple suivant inclut uniquement les hôtes dont le display_name se termine par '.oci.com' dans l'inventaire :

include_host_filters:
  - "display_name is match('.*.oci.com')"
Note

Les options include_host_filters et filters ne peuvent pas être utilisées conjointement.

Inclure des hôtes à l'aide de marqueurs à structure libre

Pour inclure un hôte dans l'inventaire à l'aide de marqueurs à structure libre, vous pouvez utiliser la syntaxe suivante :

include_host_filters:
  # filter the hosts with freeform tag with key <tag_key> which has value <tag_value>
  - "'<tag_value>' == freeform_tags.<tag_key>"
  # filter the hosts which has <tag_key> freeform tag
  - "'<tag_key>' in freefrom_tags"

Par exemple :

include_host_filters:
  - "'operating_system' in freeform_tags"
  - "'linux' == freeform_tags.operating_system"

Inclure des hôtes à l'aide de marqueurs définis

Pour inclure un hôte dans l'inventaire à l'aide de marqueurs définis, vous pouvez utiliser la syntaxe suivante :

include_host_filters:
  #filter the hosts with defined tag in <namespace> with <tag_key> and <tag_value>
  - "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  # filter the hosts with <tag_key> in the <namespace> in defined tags
  - "'<tag_key>' in defined_tags.<namespace>"

Par exemple :

include_host_filters:
  -  "'ansible' == defined_tags.ansible_collections_tag_namespace.managed_by"
  -  "'managed_by' in defined_tags.ansible_collections_tag_namespace"

Activation de la mise en mémoire cache

La mise en mémoire cache peut être activée pour accélérer les consultations. Vous pouvez définir les options de mise en mémoire cache pour une source de configuration YAML individuelle ou pour des sources d'inventaire multiples à l'aide de variables d'environnement ou de fichiers de configuration Ansible. Si vous activez la mise en mémoire cache pour un plugiciel d'inventaire sans indiquer d'options de mise en mémoire cache propres à l'inventaire, le plugiciel d'inventaire utilise les options de mise en mémoire cache de fait.

Voici un exemple d'activation de la mise en mémoire cache pour un fichier de configuration YAML individuel :

# demo.oci.yml
plugin: oracle.oci.oci
cache: yes
cache_plugin: jsonfile
cache_timeout: 7200
cache_connection: /tmp/oci_inventory
cache_prefix: oci

Utilisation de groupes dynamiques

Vous pouvez créer des groupes dynamiques à l'aide de variables d'hôte avec l'option keyed_groups. Vous pouvez également utiliser l'option groups pour créer des groupes et créer et modifier des variables d'hôte. Syntaxe pour les groupes avec clé et les groupes qui utilisent des marqueurs :

keyed_groups
- key: freeform_tags.<tag key>
  prefix: <my_prefix>
- key: defined_tags.<namespace>.<tag key>
  prefix: <my_prefix>

groups:
  <group_name>: "'<tag_value>' == freeform_tags.<tag_key>"
  <group_name>: "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  <group_name>: "'<tag_key>' in defined_tags.<namespace>"

Par exemple : 

# demo.oci.yml
plugin: oracle.oci.oci
regions:
  - us-phoenix-1
  - us-ashburn-1
keyed_groups:
  # add hosts to tag_Name_value groups for each oci host's tags.Name variable
  - key: tags.Name
    prefix: tag_Name_
groups:
  # add hosts to the group development if any of the dictionary's keys or values is the word 'devel'
  development: "'devel' in (tags|list)"
  # add hosts with freefrom_tags that has 'operating_system' key and 'linux' value to 'linux' group
  linux: "'linux' == freeform_tags.operating_system"
  # add hosts with freefrom tags that has 'operating_system' key to os group
  os: "'operating_system' in freeform_tags"
  # add hosts with defined tags in the namespace 'ansible_collections_tag_namespace' with tag 'managed_by' and value 'ansible'
  ansible_managed: "'ansible' == defined_tags.ansible_collections_tag_namespace.managed_by"
  # add hosts with defined tags in the namespace 'ansible_collections_tag_namespace' with tag 'managed_by'
  cm_managed_hosts: "'managed_by' in defined_tags.ansible_collections_tag_namespace"

Cet exemple produit une sortie similaire à la suivante : 

@all:
  |--@development:
  |  |--compute_instance1
  |  |--compute_instance2
  |--@linux:
  |  |--compute_instance1
  |--@os:
  |  |--compute_instance1
  |  |--compute_instance2
  |--@ansible_managed:
  |  |--compute_instance1
  |--@cm_managed_hosts:
  |  |--compute_instance2
  |--@ungrouped

Si un hôte ne comporte pas les variables spécifiées dans la configuration, il n'est pas ajouté à des groupes autres que ceux que le plugiciel d'inventaire crée et la variable d'hôte ansible_host n'est pas modifiée.

Scénarios d'inventaire

Les sections suivantes présentent des exemples de configuration qui illustrent les scénarios d'inventaire communs.

Extraire tous les hôtes de calcul

Pour extraire tous les hôtes, la configuration peut être aussi simple que la suivante :

plugin: oracle.oci.oci

Extraire uniquement les hôtes de base de données

Pour extraire tous les noeuds qui hébergent un logiciel de base de données tout en excluant les hôtes de calcul, la configuration se présente comme suit :

plugin: oracle.oci.oci

# fetch databse hosts
fetch_db_hosts: true
# don't fetch Compute hosts
fetch_compute_hosts: False

Extraire les hôtes de régions spécifiques

Pour extraire les hôtes des régions spécifiées, la configuration est semblable à l'exemple suivant :

plugin: oracle.oci.oci

# Fetch only the hosts in the regions us-ashburn-1, us-phoenix-1
regions:
  - us-ashburn-1
  - us-phoenix-1

Définir le nom d'hôte de l'inventaire

Pour définir le format du nom d'hôte d'inventaire utilisé dans l'inventaire, votre configuration doit comporter une section semblable à la suivante :

plugin: oracle.oci.oci

# Sets the inventory_hostname to either "display_name+'.oci.com'", "public_ip", "private_ip", or "id" 
# "display_name+'.oci.com'" has more preference than "public_ip", "private_ip", "id".
hostname_format_preferences:
  - "display_name+'.oci.com'"
  - "public_ip"
  - "private_ip"
  - "id"

Pour plus d'informations, voir Préférences de format du nom d'hôte.

Exclure des hôtes de l'inventaire

Pour utiliser une expression conditionnelle Jinja2 pour exclure des hôtes de l'inventaire, votre configuration doit comporter une section semblable à la suivante :

plugin: oracle.oci.oci

# Excludes hosts that are not in the region 'iad' from the inventory
exclude_host_filters:
  - "region not in ['iad']"

Voir Filtrage des hôtes pour plus d'informations.

Inclure des hôtes dans l'inventaire

Pour utiliser une expression conditionnelle Jinja2 pour inclure des hôtes dans l'inventaire, votre configuration doit comporter une section semblable à la suivante :

plugin: oracle.oci.oci

# Includes only the hosts that have a display_name ending with '.oci.com' in the inventory
include_host_filters:
  - "display_name is match('.*.oci.com')"

Voir Filtrage des hôtes pour plus d'informations.

Note

Les options include_host_filters et filters ne peuvent pas être utilisées conjointement.

Extraire les hôtes de compartiments spécifiques

L'exemple suivant montre comment extraire tous les hôtes des compartiments spécifiés :

# Fetch all hosts
plugin: oracle.oci.oci

# Select compartment by OCID or name
compartments:
  - compartment_ocid: <ocid1.compartment.oc1..exampleuniqueID>
    fetch_hosts_from_subcompartments: false

  - compartment_name: "<compartment_name>"
    parent_compartment_ocid: <ocid1.tenancy.oc1..exampleuniqueID>

Autres options

L'exemple de configuration suivant associe les scénarios précédents à d'autres options de configuration :

# Fetch all hosts
plugin: oracle.oci.oci

# Optional fields:
config_file: ~/.oci/config
config_profile: DEFAULT

# Example select regions
regions:
  - us-ashburn-1
  - us-phoenix-1

# Enable threads to speedup lookup
enable_parallel_processing: yes

# Select compartment by ocid or name
compartments:
  - compartment_ocid: <ocid1.compartment.oc1..exampleuniqueID>
    fetch_hosts_from_subcompartments: false

  - compartment_name: "<compartment_name>"
    parent_compartment_ocid: <ocid1.tenancy.oc1..exampleuniqueID>

# Sets the inventory_hostname. Each item is a Jinja2 expression and it gets evaluated on host_vars.
hostname_format_preferences:
  - "display_name+'.oci.com'"
  - "private_ip"
  - "public_ip"

# Excludes a host from the inventory when any of the Jinja2 expression evaluates to true.
exclude_host_filters:
  - "region not in ['iad']"
  - "'<tag_key>' in freeform_tags"
  - "'<tag_value>' == freeform_tags.<tag_key>"
  - "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  - "'<tag_key>' in defined_tags.<namespace>"

# Includes a host in the inventory when any of the Jinja2 expression evaluates to true.
include_host_filters:
  - "display_name is match('.*.oci.com')"
  - "'<tag_key>' in freeform_tags"
  - "'<tag_value>' == freeform_tags.<tag_key>"
  - "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  - "'<tag_key>' in defined_tags.<namespace>"

# Example group results by key
keyed_groups
- key: freeform_tags.<tag key>
  prefix: <my_prefix>
- key: defined_tags.<namespace>.<tag key>
  prefix: <my_prefix>

groups:
  <group_name>: "'<tag_value>' == freeform_tags.<tag_key>"
  <group_name>: "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  <group_name>: "'<tag_key>' in defined_tags.<namespace>"

# Example to create and modify a host variable
compose:
  ansible_host: display_name+'.oracle.com'

# Example flag to turn on debug mode
debug: true

# Enable Cache
cache: yes
cache_plugin: jsonfile
cache_timeout: 7200
cache_connection: /tmp/oci-cache
cache_prefix: oci_

# DB Hosts
fetch_db_hosts: True

# Compute Hosts (bool type)
fetch_compute_hosts: True

# Process only the primary vnic of a compute instance
primary_vnic_only: True

Dépannage du plugiciel d'inventaire

Si la liste d'inventaire générée par le plugiciel d'inventaire OCI ne comprend pas toutes les instances de calcul de votre location, vérifiez les informations suivantes.

Autorisations d'utilisateur

Assurez-vous que l'utilisateur dispose des autorisations pour les politiques suivantes. L'OCID de l'utilisateur est spécifié à l'aide de la variable d'environnement OCI_USER ou de la section profile dans votre fichier de configuration des trousses SDK et de l'interface de ligne de commande.

Pour consulter la liste des autorisations pour les opérations d'API, voir Informations détaillées sur les services de base.

Le plugiciel d'inventaire effectue des appels d'API pour les opérations suivantes :

  • ListCompartments
  • GetCompartment
  • ListVNICAttachments
  • GetVNIC
  • GetSubnet
  • GetVLAN
  • GetVCN
  • ListInstances
  • GetInstance
  • ListDBNodes
  • ListDBSystems
  • ListRegionSubscriptions

Pour plus d'informations

Des informations détaillées sur l'utilisation du plugiciel d'inventaire OCI sont disponibles sur docs.oracle.com et readthedocs.io.

Vous pouvez également utiliser la commande suivante pour voir la documentation sur le plugiciel :

ansible-doc -t inventory oracle.oci.oci

Consultez la documentation Ansible officielle pour plus d'informations sur les plugiciels d'inventaire.