Documentazione dell'infrastruttura Oracle Cloud

Utilizzo del magazzino Ansible

Ansible tiene traccia delle risorse di configurazione conservando le liste, denominate liste di inventario, come file semplici (a volte chiamati anche file_host). Questi elenchi di inventario possono essere statici o dinamici. Le liste dinamiche possono essere aggiornate automaticamente quando le risorse di magazzino vengono aggiunte, eliminate o spostate.

Poiché molte risorse Oracle Cloud Infrastructure (OCI) vengono aggiunte ed eliminate nel tempo, le liste di inventario statiche possono diventare facilmente obsolete. Anche strumenti come Terraform o gli SDK OCI possono influire sulle risorse.

Oracle Cloud Infrastructure fornisce un plugin di inventario dinamico per mantenere un inventario Ansible accurato.

Per ulteriori informazioni sui file di magazzino Ansible, vedere Utilizzo del magazzino e Utilizzo del magazzino dinamico.

Abilitazione del plugin Magazzino

Se si dispone di un file ansible.cfg esistente e tale configurazione abilita già i plugin utilizzando enable_plugins, è necessario abilitare anche il plugin inventario OCI aggiungendolo. Ad esempio:

[inventory]
enable_plugins = oracle.oci.oci

Se non si dispone già di un file ansible.cfg contenente enable_plugins, non è necessario aggiungere il plugin dell'inventario OCI alla configurazione.

Configurazione del plugin Inventory

L'unico requisito per l'uso del plugin di inventario OCI dopo che è stato abilitato è fornire un'origine di inventario di cui si dispone delle autorizzazioni per l'analisi. Le origini magazzino sono definite in un file di configurazione YAML. Per ulteriori informazioni, vedere Autorizzazioni utente.

Per iniziare a utilizzare il plugin inventario con un'origine di configurazione YAML, creare un file con uno dei seguenti nomi di file accettati:

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

Aggiungere plugin: oracle.oci.oci al file di configurazione YAML.

Il file di origine inventario minimo necessario per eseguire il plugin inventario OCI è simile al seguente, ad esempio:

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

In questo esempio vengono utilizzati i parametri config_file e config_profile, in modo che il plugin possa utilizzare le informazioni di autenticazione indicate nel documento SDK and CLI Configuration File. Alcuni parametri possono essere forniti anche come variabili di ambiente.

Per un elenco completo dei parametri e delle variabili di ambiente supportati dal plugin, vedere Plugin inventario OCI. Gli scenari di magazzino includono molti dei parametri disponibili.

Importante

Per impostazione predefinita, il plugin inventario OCI rileva ed elenca solo le istanze di computazione che dispongono di un indirizzo IP pubblico. Per ulteriori informazioni, vedere Preferenze del formato del nome host.

Ordine di precedenza

Il plugin inventario utilizza il seguente ordine di precedenza quando un'opzione viene fornita in più di una posizione:

  1. Impostazioni file YAML.
  2. Variabili di ambiente.
  3. Impostazioni di configurazione nel file di configurazione OCI selezionato profile.

Recupero degli host del database

Per impostazione predefinita, il plugin di inventario OCI rileva ed elenca solo le istanze di computazione. I nodi del database sono server che eseguono software di database. I nodi del database vengono recuperati impostando l'opzione fetch_db_hosts su true. Ad esempio:

# demo.oci.yml

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

Uso del plugin Magazzino

I plugin di inventario Ansible consentono di definire le origini dati utilizzate per compilare un inventario di host utilizzati da Ansible per i task di destinazione. Per accedere a queste origini dati si utilizzano i parametri della riga di comando -i /path/to/file o -i 'host1, host2' oppure altre origini di configurazione.

È possibile eseguire l'inventario con questo comando, ad esempio:

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

Ciò produce un output simile al seguente:

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

Per impostazione predefinita, l'inventario viene generato per tutti i compartimenti nella tenancy. Per consentire a questo script di accedere a tutti i compartimenti, è necessario disporre dell'autorizzazione COMPARTMENT_INSPECT nel compartimento radice. Tuttavia, quando si specifica compartment_ocid, l'inventario viene generato solo per il compartimento specifico, pertanto è necessaria solo l'autorizzazione COMPARTMENT_INSPECT per il compartimento specificato. Per ulteriori informazioni, vedere Funzionamento dei criteri.

Per recuperare tutti i dettagli dell'istanza, è inoltre necessario disporre dell'autorizzazione per elencare e leggere le istanze e le VNIC, nonché leggere le VCN e le subnet. Per ulteriori informazioni, vedere Autorizzazioni utente.

È possibile aggiungere plugin di inventario al percorso del plugin e impostare il percorso di inventario predefinito per semplificare i comandi. Aggiungere il percorso inventario predefinito alla sezione [defaults] del file ansible.cfg oppure utilizzare la variabile di ambiente ANSIBLE_INVENTORY per puntare le origini inventario. È quindi possibile eseguire il comando seguente per produrre lo stesso output di quando si passano direttamente le origini di configurazione YAML:

ansible-inventory --graph

In genere i plugin di inventario vengono eseguiti solo all'inizio di un'esecuzione, prima del caricamento di playbook, riproduzioni e ruoli. È possibile eseguire di nuovo un plugin utilizzando il task meta: refresh_inventory, che cancella l'inventario esistente e lo ricostruisce.

Output magazzino

L'elenco di inventario generato dal plugin inventario viene raggruppato utilizzando i seguenti attributi:

  • Area in cui risiede l'istanza di computazione
  • Nome del compartimento a cui appartiene l'istanza di computazione
  • Dominio di disponibilità in cui si trova l'istanza di computazione
  • La vcn_id della VCN in cui si trova l'istanza di computazione
  • subnet_id della subnet in cui si trova l'istanza di computazione
  • security_list_ids della subnet in cui si trova l'istanza di computazione
  • image_id dell'immagine utilizzata per avviare l'istanza di computazione
  • Forma dell'istanza di calcolo
  • Tag in formato libero dell'istanza di computazione, con il nome del gruppo impostato su tag_<tag_name>=<tag_value>
  • Tag definite dell'istanza di computazione, con il nome del gruppo impostato su <tag_namespace>#<tag_name>=<tag_value>
  • Metadati dell'istanza di computazione OCI (coppie chiave-valore), con il nome del gruppo impostato su <metadata-key>=<metadata-value>
  • Metadati estesi dell'istanza di computazione OCI (coppie chiave-valore), con il nome del gruppo impostato su <metadata-key>=<metadata-value>

Preferenze formato nome host

L'inventario generato dal plugin inventario OCI contiene solo le istanze che dispongono di un indirizzo IP pubblico per impostazione predefinita. Ciò è utile nei casi in cui il nodo del controller Ansible si trova al di fuori della VCN, poiché Ansible può raggiungere solo le istanze che dispongono di indirizzi IP pubblici.

È possibile configurare inventory_hostname in private_ip o in qualsiasi nome host personalizzato passando espressioni Jinja2 come elenco all'opzione hostname_format_preferences. L'opzione hostname_format_preferences accetta un elenco di espressioni Jinja2 in ordine di precedenza per la composizione di inventory_hostname. Il plugin inventario ignora le espressioni se il risultato è una stringa vuota o un valore "Nessuno". L'istanza viene ignorata se nessuna delle espressioni hostname_format_preferences restituisce un valore non vuoto.

L'esempio seguente imposta inventory_hostname su "display_name+'.oci.com'", "private_ip" o "public_ip":

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

Le espressioni vengono valutate su host_vars di ogni istanza. La valutazione rispetta l'ordine di precedenza nella configurazione per la composizione di inventory_hostname. Nell'esempio precedente, "display_name+'.oci.com'" viene valutato prima di "private_ip" e "public_ip".

Filtro degli host

Il plugin di inventario OCI include varie opzioni di filtro per filtrare gli host restituiti dal plugin.

Escludi host da magazzino

È possibile passare una lista di espressione condizionali Jinja2 al parametro exclude_host_filters. Ogni espressione nella lista viene valutata per ogni host. Quando l'espressione è vera, l'host viene escluso dall'inventario. Il parametro exclude_host_filters ha la priorità sulle opzioni include_host_filters e filters.

L'esempio seguente esclude dall'inventario gli host che non si trovano nell'area 'iad':

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

Escludi host che utilizzano tag in formato libero

Per escludere un host dall'inventario utilizzando tag in formato libero, è possibile utilizzare la seguente sintassi:

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"

Ad esempio:

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

Escludi host mediante tag definite

Per escludere un host dall'inventario utilizzando tag definiti, è possibile utilizzare la sintassi seguente:

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

Ad esempio:

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

Includi host in inventario

È possibile passare una lista di espressione condizionali Jinja2 al parametro include_host_filters. Ogni espressione nella lista viene valutata per ogni host. Quando l'espressione è vera, l'host viene incluso nell'inventario.

L'esempio seguente include solo gli host con display_name che terminano con '.oci.com' nell'inventario:

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

Le opzioni include_host_filters e filters non possono essere utilizzate insieme.

Includi host che utilizzano tag in formato libero

Per includere un host dall'inventario utilizzando tag in formato libero, è possibile utilizzare la seguente sintassi:

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"

Ad esempio:

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

Includi host con tag definite

Per includere un host dall'inventario utilizzando tag definite, è possibile utilizzare la sintassi seguente:

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

Ad esempio:

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

Abilitazione dell'inserimento nella cache

L'inserimento nella cache può essere abilitato per velocizzare le ricerche. È possibile impostare le opzioni di inserimento nella cache per una singola origine di configurazione YAML o per più origini magazzino utilizzando variabili di ambiente o file di configurazione Ansible. Se si abilita l'inserimento nella cache per un plugin di inventario senza fornire opzioni di inserimento nella cache specifiche dell'inventario, il plugin di inventario utilizza opzioni di inserimento nella cache dei dati fact.

Di seguito è riportato un esempio di abilitazione dell'inserimento nella cache per un singolo file di configurazione YAML.

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

Uso dei gruppi dinamici

È possibile creare gruppi dinamici utilizzando variabili host con l'opzione keyed_groups creata. L'opzione groups può essere utilizzata anche per creare gruppi e creare e modificare variabili host. Di seguito è riportata la sintassi per i gruppi e i gruppi con chiave che utilizzano le tag.

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

Ad esempio: 

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

In questo esempio viene prodotto un output simile al seguente: 

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

Se un host non dispone delle variabili specificate nella configurazione, l'host non viene aggiunto a gruppi diversi da quelli creati dal plugin inventario e la variabile host ansible_host non viene modificata.

Scenari magazzino

Le sezioni seguenti includono esempi di configurazione che riguardano scenari di magazzino comuni.

Recupera tutti gli host di computazione

Per recuperare tutti gli host, la configurazione può essere semplice come nell'esempio riportato di seguito.

plugin: oracle.oci.oci

Recupera solo host DB

Per recuperare tutti i nodi che ospitano il software del database escludendo gli host di computazione, la configurazione dovrebbe avere l'aspetto seguente:

plugin: oracle.oci.oci

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

Recupera host da aree specifiche

Per recuperare gli host solo nelle aree specificate, la configurazione sarà simile all'esempio riportato di seguito.

plugin: oracle.oci.oci

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

Imposta nome host magazzino

Per impostare il formato del nome host dell'inventario utilizzato nell'inventario, la configurazione include una sezione simile all'esempio seguente:

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"

Per ulteriori informazioni, vedere Preferenze del formato del nome host.

Escludi host da magazzino

Per utilizzare un'espressione condizionale Jinja2 per escludere gli host dall'inventario, la configurazione include una sezione simile all'esempio seguente:

plugin: oracle.oci.oci

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

Per ulteriori informazioni, vedere Filtro degli host.

Includi host in inventario

Per utilizzare un'espressione condizionale Jinja2 per includere host nell'inventario, la configurazione include una sezione simile all'esempio riportato di seguito.

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

Per ulteriori informazioni, vedere Filtro degli host.

Nota

Le opzioni include_host_filters e filters non possono essere utilizzate insieme.

Recupera host da compartimenti specifici

L'esempio seguente mostra come recuperare tutti gli host dai compartimenti specificati:

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

Altre Opzioni

La configurazione di esempio riportata di seguito combina gli scenari precedenti con altre opzioni di configurazione.

# 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

Risoluzione dei problemi relativi al plugin Inventory

Se la lista di inventario generata dal plugin di inventario OCI non include tutte le istanze di computazione nella tenancy, esaminare le informazioni riportate di seguito.

Autorizzazioni utente

Assicurarsi che l'utente disponga delle autorizzazioni dei criteri seguenti. L'OCID utente viene specificato utilizzando la variabile di ambiente OCI_USER o la sezione profile nel file di configurazione dell'SDK e dell'interfaccia CLI.

Per visualizzare una lista di autorizzazioni per le operazioni API, vedere Dettagli per i servizi di base.

Il plugin Inventory effettua chiamate API per le seguenti operazioni:

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

Per ulteriori informazioni

Informazioni dettagliate sull'uso del plugin inventario OCI sono disponibili su docs.oracle.com e readthedocs.io.

È inoltre possibile utilizzare il seguente comando per visualizzare la documentazione del plugin:

ansible-doc -t inventory oracle.oci.oci

Per ulteriori informazioni sui plugin di inventario, consultare la documentazione ufficiale di Ansible.