Documentation Oracle Cloud Infrastructure

Utilisation de l'inventaire Ansible

Ansible effectue le suivi d'une configuration en conservant des listes, nommées listes d'inventaire, en tant que fichiers de listes simples (parfois appelés fichiers d'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.

Etant donné que de nombreuses ressources Oracle Cloud Infrastructure (OCI) sont ajoutées et supprimées au fil du temps, les listes d'inventaire statiques peuvent facilement devenir obsolètes. Les outils tels que Terraform ou les kits SDK OCI peuvent également avoir une incidence sur vos ressources.

Oracle Cloud Infrastructure fournit un module d'ajout d'inventaire dynamique pour garantir l'exactitude de l'inventaire Ansible.

Pour plus d'informations sur les fichiers d'inventaire Ansible, reportez-vous à Utilisation de l'inventaire et à Utilisation de l'inventaire dynamique.

Activation du module d'extension d'inventaire

Si vous disposez d'un fichier ansible.cfg existant et que cette configuration permet déjà les modules d'application d'extension via enable_plugins, vous devez activer le module d'application d'inventaire OCI en l'ajoutant également. Par exemple :

[inventory]
enable_plugins = oracle.oci.oci

Si vous ne disposez pas encore d'un fichier ansible.cfg contenant enable_plugins, vous n'avez pas besoin d'ajouter le module d'application d'extension d'inventaire OCI à la configuration.

Configuration du module d'extension d'inventaire

La seule exigence concernant l'utilisation du module d'ajout d'inventaire OCI après son activation est de fournir une source d'inventaire que vous êtes autorisé à analyser. Les sources d'inventaire sont définies dans un fichier de configuration YAML. Pour plus d'informations, reportez-vous à Droits d'accès utilisateur.

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

  • <filename>.oci.yml
  • <filename>.oci.yaml

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

Le fichier source d'inventaire minimal requis pour exécuter le module d'extension d'inventaire OCI se présente comme dans l'exemple suivant :

# 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 pour que le module d'extension utilise les informations d'authentification qui sont présentées dans Fichier de configuration du kit SDK et de l'interface de ligne de commande. Certains paramètres peuvent également être fournis en tant que variables d'environnement.

Pour obtenir la liste complète des paramètres et des variables d'environnement pris en charge par le module d'extension, reportez-vous à Module d'extension d'inventaire OCI. Les scénarios d'inventaire incluent de nombreux paramètres disponibles.

Important

Par défaut, le module d'ajout d'inventaire OCI repère et répertorie uniquement les instances de calcul disposant d'une adresse IP publique. Pour plus d'informations, reportez-vous à Préférences de format de nom d'hôte.

Ordre de priorité

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

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

Extraction des hôtes de base de données

Par défaut, le module d'ajout d'inventaire OCI repère et répertorie uniquement les instances de calcul. Les noeuds de base de données sont des serveurs exécutant un logiciel de base de données. Les noeuds de base de données sont extraits lorsque l'option fetch_db_hosts est définie sur true. Par exemple :

# demo.oci.yml

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

Utilisation du module d'extension d'inventaire

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

Vous pouvez exécuter l'inventaire à l'aide de cette commande, par exemple :

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

Cette commande produit un résultat semblable à ce qui suit :

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

Par défaut, l'inventaire est généré pour tous les compartiments dans la location. Vous devez disposer du droit d'accès COMPARTMENT_INSPECT sur 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 concerné. Vous n'avez donc besoin que du droit d'accès COMPARTMENT_INSPECT sur le compartiment spécifié. Pour plus d'informations, reportez-vous à Fonctionnement des stratégies.

Pour extraire tous les détails d'instance, vous devez également disposer de droits d'accès permettant de répertorier et de lire les instances et les cartes d'interface réseau virtuelles, ainsi que de lire les réseaux cloud virtuels et les sous-réseaux. Pour plus d'informations, reportez-vous à Droits d'accès utilisateur.

Vous pouvez ajouter des modules d'extension d'inventaire à votre chemin de module d'extension et définir le chemin d'inventaire par défaut pour simplifier vos commandes. Ajoutez le chemin d'inventaire par défaut à la section [defaults] de votre fichier ansible.cfg, ou utilisez la variable d'environnement ANSIBLE_INVENTORY de façon à pointer vers vos sources d'inventaire. Vous pouvez ensuite exécuter la commande suivante pour générer la même sortie que la transmission directe de vos sources de configuration YAML :

ansible-inventory --graph

En règle générale, les modules d'extension d'inventaire ne sont exécutés qu'au début d'une exécution, avant le chargement des livres de jeux, des jeux et des rôles. Vous pouvez réexécuter un module d'extension à l'aide de 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 module d'extension d'inventaire est regroupée selon les attributs suivants :

  • Région dans laquelle réside l'instance de calcul
  • Nom du compartiment auquel appartient l'instance de calcul
  • Domaine de disponibilité dans lequel figure l'instance de calcul
  • vcn_id du réseau cloud virtuel dans lequel se trouve l'instance Compute
  • subnet_id du sous-réseau dans lequel se trouve l'instance de calcul
  • security_list_ids du sous-réseau dans lequel se trouve l'instance de calcul
  • image_id de l'image utilisée pour lancer l'instance de calcul
  • Forme de l'instance de calcul
  • Balises à format libre de l'instance de calcul, avec le nom de groupe défini sur tag_<tag_name>=<tag_value>
  • Balises définies de l'instance de calcul, avec le nom de groupe défini sur <tag_namespace>#<tag_name>=<tag_value>
  • Métadonnées d'instance de calcul OCI (paires clé-valeur), avec le nom de groupe défini sur <metadata-key>=<metadata-value>
  • Métadonnées étendues du calcul OCI (paires clé-valeur), avec le nom de groupe défini sur <metadata-key>=<metadata-value>

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

L'inventaire généré par le module d'ajout d'inventaire OCI contient uniquement les instances disposant d'une adresse IP publique par défaut. Ceci est utile lorsque le noeud de contrôleur Ansible est situé en dehors du réseau cloud virtuel, car Ansible ne peut accéder qu'aux instances possédant des adresses IP publiques.

Vous pouvez configurer inventory_hostname sur private_ip ou sur n'importe quel nom d'hôte personnalisé en transmettant des expressions Jinja2 sous forme de liste à l'option hostname_format_preferences. L'option hostname_format_preferences prend la liste des expressions Jinja2 par ordre de priorité pour composer inventory_hostname. Le module d'extension 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 génère une valeur non vide.

L'exemple suivant définit inventory_hostname sur "display_name+'.oci.com'", sur "private_ip" ou sur "public_ip" :

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

Les expressions sont évaluées sur host_vars pour chaque instance. L'évaluation respecte l'ordre de priorité établi dans 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 module d'ajout d'inventaire OCI est fourni avec différentes options de filtrage permettant de filtrer les hôtes renvoyés par le module d'extension.

Exclusion d'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'expression a 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']"

Exclusion d'hôtes à l'aide de balises à format libre

Pour exclure un hôte de l'inventaire à l'aide de balises à format 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"

Exclusion d'hôtes à l'aide de balises définies

Pour exclure un hôte de l'inventaire à l'aide de balises définies, 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"

Inclusion d'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'expression a la valeur True, l'hôte est inclus dans l'inventaire.

L'exemple suivant inclut uniquement les hôtes avec un nom display_name se terminant par '.oci.com' dans l'inventaire :

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

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

Inclusion d'hôtes à l'aide de balises à format libre

Pour inclure un hôte dans l'inventaire à l'aide de balises à format 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"

Inclusion d'hôtes à l'aide de balises définies

Pour inclure un hôte dans l'inventaire à l'aide de balises définies, 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 cache

La mise en cache peut être activée pour accélérer les recherches. Vous pouvez définir des options de mise en cache pour une source de configuration YAML individuelle ou pour plusieurs sources d'inventaire à l'aide de variables d'environnement ou de fichiers de configuration Ansible. Si vous activez la mise en cache pour un module d'extension d'inventaire sans fournir d'options de mise en cache propres à l'inventaire, le module utilise les options de mise en cache de faits.

Voici un exemple d'activation de la mise en 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 avec des variables hôte à l'aide de l'option keyed_groups construite. L'option groups peut également être utilisée pour créer des groupes, et créer et modifier des variables hôte. La syntaxe pour les groupes et les groupes saisis qui utilisent des balises est la suivante :

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 un résultat semblable à ce qui suit : 

@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 dispose pas des variables spécifiées dans la configuration, il n'est pas ajouté à des groupes autres que ceux créés par le module d'extension d'inventaire et la variable hôte ansible_host n'est pas modifiée.

Scénarios d'inventaire

Les sections suivantes contiennent des exemples de configuration qui couvrent les scénarios d'inventaire courants.

Extraction de tous les hôtes de calcul

Pour extraire tous les hôtes, la configuration peut être aussi simple que dans l'exemple suivant :

plugin: oracle.oci.oci

Extraction des hôtes de base de données uniquement

Pour extraire tous les noeuds hébergeant le logiciel de base de données en excluant les hôtes de calcul, la configuration ressemble à l'exemple suivant :

plugin: oracle.oci.oci

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

Extraction des hôtes de régions spécifiques

Pour extraire les hôtes uniquement dans les régions spécifiées, la configuration ressemble à 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éfinition du nom d'hôte d'inventaire

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

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, reportez-vous à Préférences de format de nom d'hôte.

Exclusion d'hôtes de l'inventaire

Pour utiliser une expression conditionnelle Jinja2 afin d'exclure des hôtes de l'inventaire, la configuration doit inclure une section semblable à l'exemple suivant :

plugin: oracle.oci.oci

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

Pour plus d'informations, reportez-vous à Filtrage des données.

Inclusion d'hôtes dans l'inventaire

Pour utiliser une expression conditionnelle Jinja2 afin d'inclure des hôtes dans l'inventaire, la configuration doit inclure une section semblable à l'exemple suivant :

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')"

Pour plus d'informations, reportez-vous à Filtrage des données.

Remarque

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

Extraction des hôtes de compartiments spécifiques

L'exemple suivant indique 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 combine les scénarios précédents avec 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 module d'extension d'inventaire

Si la liste d'inventaire générée par le module d'ajout d'inventaire OCI n'inclut pas toutes Les instances de calcul de votre location, vérifiez les informations ci-après.

Droits d'accès utilisateur

Assurez-vous que l'utilisateur dispose des droits d'accès de stratégie suivants. L'OCID utilisateur est indiqué avec la variable d'environnement OCI_USER ou la section profile du fichier de configuration du kit SDK et de l'interface de ligne de commande.

Afin d'obtenir la liste des droits d'accès pour les opérations d'API, reportez-vous à Détails des services de base.

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

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

Informations supplémentaires

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

La commande suivante permet également de consulter la documentation du module d'extension :

ansible-doc -t inventory oracle.oci.oci

Reportez-vous à la documentation Ansible officielle pour plus d'informations sur les modules d'extension d'inventaire.