Oracle Cloud Infrastructure - Dokumentation

Mit Ansible-Bestand arbeiten

Ansible verfolgt Konfigurationsressourcen, indem Listen, die auch als Bestandslisten bezeichnet werden, als einfache Dateien beibehalten wird (gelegentlich auch als Hostdateien bezeichnet). Diese Bestandslisten können statisch oder dynamisch sein. Dynamische Listen können automatisch aktualisiert werden, wenn Bestandsressourcen hinzugefügt, gelöscht oder verschoben werden.

Da im Laufe der Zeit viele Oracle Cloud Infrastructure-(OCI-)Ressourcen hinzugefügt und gelöscht werden, können statische Bestandslisten leicht veralten. Tools wie Terraform oder die OCI-SDKs haben möglicherweise ebenfalls Einfluss auf Ihre Ressourcen.

Oracle Cloud Infrastructure stellt ein dynamisches Bestands-Plug-in zur Verwaltung der genauen Ansible-Bestände bereit.

Weitere Informationen zu Ansible-Bestandsdateien finden Sie unter Mit Bestand arbeiten und Mit dynamischem Bestand arbeiten.

Bestands-Plug-in aktivieren

Wenn Sie über eine vorhandene Datei ansible.cfg verfügen und diese Konfiguration bereits Plug-ins mit enable_plugins aktiviert, müssen Sie auch das OCI-Bestands-Plug-in aktivieren, indem sie es hinzufügen. Beispiel:

[inventory]
enable_plugins = oracle.oci.oci

Wenn Sie noch keine ansible.cfg-Datei mit enable_plugins vorhanden sind, müssen Sie das OCI-Bestands-Plug-in nicht zur Konfiguration hinzufügen.

Bestands-Plug-in konfigurieren

Die einzige Voraussetzung für die Verwendung des OCI-Bestands-Plug-ins nach der Aktivierung ist die Angabe einer Bestandsquelle, für die Sie Parsingberechtigungen besitzen. Bestandsquellen sind in einer YAML-Konfigurationsdatei definiert. Weitere Informationen finden Sie unter Benutzerberechtigungen.

Um das Bestands-Plug-in mit einer YAML-Konfigurationsquelle zu verwenden, erstellen Sie eine Datei mit einem der folgenden akzeptierten Dateinamen:

  • <Dateiname>.oci.yml
  • <Dateiname>.oci.yaml

Fügen Sie plugin: oracle.oci.oci zur YAML-Konfigurationsdatei hinzu.

Die minimale Bestandsausgangsdatei, die zum Ausführen des OCI-Bestands-Plug-ins benötigt wird, sieht beispielsweise folgendermaßen aus:

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

In diesem Beispiel werden die Parameter config_file und config_profile verwendet, damit das Plug-in Authentifizierungsinformationen verwenden kann, die in der SDK- und CLI-Konfigurationsdatei beschrieben sind. Einige Parameter können auch als Umgebungsvariablen angegeben werden.

Eine vollständige Liste der vom Plug-in unterstützten Parameter und Umgebungsvariablen finden Sie unter OCI-Bestands-Plug-in. Die Bestandszenarios enthalten viele der verfügbaren Parameter.

Wichtig

Standardmäßig wird vom OCI-Bestands-Plug-in nur Compute, die eine öffentliche IP-Adresse aufweisen, erkannt und aufgeführt. Weitere Informationen finden Sie unter Voreinstellungen für Hostnamensformat.

Prioritätsfolge

Das Bestands-Plug-in verwendet die folgende Prioritätsreihenfolge, wenn eine Option an mehreren Stellen angegeben wird:

  1. YAML-Dateieinstellungen.
  2. Umgebungsvariablen.
  3. Konfigurationseinstellungen im ausgewählten profile-Abschnitt in der OCI-Konfigurationsdatei.

Datenbankhosts abrufen

Standardmäßig erkennt und listet das OCI-Bestands-Plug-in nur Compute-Instanzen auf. Datenbankknoten sind Server, auf denen Datenbanksoftware ausgeführt wird. Datenbankknoten werden abgerufen, indem die Option fetch_db_hosts auf true gesetzt wird. Beispiel:

# demo.oci.yml

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

Bestands-Plug-in verwenden

Mit Bestands-Plug-ins von Ansible können Sie die Datenquellen definieren, mit denen ein Bestand von Hosts kompiliert wird, an denen Ansible Aufgaben ausführt. Auf diese Datenquellen wird entweder über die Befehlszeilenparameter -i /path/to/file oder -i 'host1, host2' zugegriffen. Alternativ ist der Zugriff auch über andere Konfigurationsquellen möglich.

Sie können das Bestands-Plug-in z.B. mit dem folgenden Befehl ausführen:

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

Dieser Befehl erzeugt eine Ausgabe, die in etwa wie folgt aussieht:

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

Standardmäßig wird der Bestand für alle Compartments im Mandanten generiert. Sie benötigen die Berechtigung COMPARTMENT_INSPECT im Root-Compartment für dieses Skript, um auf alle Compartments zugreifen zu können. Wenn jedoch compartment_ocid angegeben wird, wird das Bestandsverzeichnis nur für dieses Compartment generiert, sodass Sie nur die Berechtigung COMPARTMENT_INSPECT für das angegebene Compartment benötigen. Weitere Informationen finden Sie unter Funktionsweise von Policys.

Um alle Instanzdetails abzurufen, benötigen Sie auch die Berechtigung zum Auflisten und Lesen von Instanzen und VNICs sowie zum Lesen von VCNs und Subnetzen. Weitere Informationen finden Sie unter Benutzerberechtigungen.

Sie können Bestands-Plug-ins zu Ihrem Plug-in-Pfad hinzufügen und den Standardbestandspfad festlegen, um Befehle zu vereinfachen. Fügen Sie den Standardbestandspfad zum Abschnitt [defaults] in der Datei ansible.cfg hinzu, oder verwenden sie die Umgebungsvariable ANSIBLE_INVENTORY, um auf Ihre Bestandsquellen zu verweisen. Anschließend können Sie den folgenden Befehl ausführen, um dieselbe Ausgabe zu erhalten wie beim direkten Übergeben der YAML-Konfigurationsquellen:

ansible-inventory --graph

Bestands-Plug-ins werden normalerweise nur zu Beginn einer Ausführung ausgeführt, bevor Playbooks, Plays und Rollen geladen werden. Sie können ein Plug-in mit der Aufgabe meta: refresh_inventory erneut ausführen, indem Sie den vorhandenen Bestand löschen und neu erstellen.

Bestandsausgabe

Die vom Bestands-Plug-in generierte Bestandsliste wird anhand der folgenden Attribute gruppiert:

  • Die Region, in der sich die Compute-Instanz befindet
  • Der Name des Compartments, zu dem die Compute-Instanz gehört
  • Die Availability-Domain, in der sich die Compute-Instanz befindet
  • vcn_id des VCN, in dem sich die Compute-Instanz befindet
  • subnet_id des Subnetzes, in dem sich die Compute-Instanz befindet
  • security_list_ids des Subnetzes, in dem sich die Compute-Instanz befindet
  • image_id des Images, mit dem die Compute-Instanz gestartet wird
  • Die Compute-Ausprägung der Compute-Instanz
  • Freiformtags der Compute-Instanz, wobei der Gruppenname auf tag_<tag_name>=<tag_value> gesetzt ist
  • Definierte Tags der Compute-Instanz, wobei der Gruppenname auf <tag_namespace>#<tag_name>=<tag_value> gesetzt ist
  • Metadaten für OCI-Compute-Instanz (Schlüssel/Wert-Paare), wobei der Gruppenname auf <metadata-key>=<metadata-value> gesetzt ist
  • Erweiterte Metadaten (Schlüssel/Wert-Paare), wobei der Gruppenname auf <metadata-key>=<metadata-value> gesetzt ist

Voreinstellungen für Hostnamensformat

Der vom OCI-Bestand-Plug-in generierte Bestand enthält standardmäßig nur Instanzen mit einer öffentlichen IP-Adresse. Das ist nützlich, wenn sich der Ansible-Controllerknoten außerhalb des VCN befindet, da Ansible nur Instanzen mit öffentlichen IP-Adressen erreichen kann.

Sie können inventory_hostname als private_ip oder einen beliebigen benutzerdefinierten Hostnamen konfigurieren, indem Sie Jinja2-Ausdrücke als Liste an die Option hostname_format_preferences übergeben. Die Option hostname_format_preferences erstellt inventory_hostname aus einer Liste der Jinja2-Ausdrücke in der Reihenfolge ihrer Priorität. Das Bestands-Plug-in ignoriert Ausdrücke, wenn das Ergebnis eine leere Zeichenfolge oder "Kein Wert" ist. Die Instanz wird ignoriert, wenn keiner der hostname_format_preferences-Ausdrücke zu einem nicht leeren Wert führt.

Im folgenden Beispiel wird inventory_hostname auf "display_name+'.oci.com'", "private_ip" oder "public_ip" gesetzt:

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

Ausdrücke werden auf host_vars jeder Instanz ausgewertet. Die Auswertung berücksichtigt die Prioritätsreihenfolge in Ihrer Konfiguration, um inventory_hostname zu erstellen. Im vorherigen Beispiel wird "display_name+'.oci.com'" vor "private_ip" und "public_ip" ausgewertet.

Hosts filtern

Das OCI-Bestands-Plug-in enthält verschiedene Filteroptionen, um die von dem Plug-in zurückgegebenen Host zu filtern.

Hosts aus Bestand ausschließen

Sie können eine Liste mit Jinja2-Bedingungsausdrücken an den Parameter exclude_host_filters übergeben. Jeder Ausdruck in der Liste wird für jeden Host ausgewertet. Wenn der Ausdruck "true" ist, wird der Host aus dem Bestand ausgeschlossen. Der Parameter exclude_host_filters hat Vorrang vor den Optionen include_host_filters und filters.

Das folgende Beispiel schließt Hosts, die sich nicht in der Region "iad" befinden, aus dem Bestand aus:

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

Hosts mit Freiformtags ausschließen

Um einen Host mit Freiformtags aus dem Bestand auszuschließen, können Sie die folgende Syntax verwenden:

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"

Beispiel:

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

Hosts mit definierten Tags ausschließen

Um einen Host mit definierten Tags aus dem Bestand auszuschließen, können Sie die folgende Syntax verwenden:

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

Beispiel:

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

Hosts in Bestand einschließen

Sie können eine Liste mit Jinja2-Bedingungsausdrücken an den Parameter include_host_filters übergeben. Jeder Ausdruck in der Liste wird für jeden Host ausgewertet. Wenn der Ausdruck "true" ist, wird der Host in das Bestandsverzeichnis aufgenommen.

Das folgende Beispiel schließt nur die Hosts in den Bestand ein, deren display_name mit ".oci.com" endet:

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

Die Optionen include_host_filters und filters können nicht gemeinsam verwendet werden.

Hosts mit Freiformtags einschließen

Um einen Host aus dem Bestand mit Freiformtags aufzunehmen, können Sie die folgende Syntax verwenden:

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"

Beispiel:

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

Hosts mit definierten Tags einschließen

Um einen Host aus dem Bestand mit definierten Tags einzuschließen, können Sie die folgende Syntax verwenden:

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

Beispiel:

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

Caching aktivieren

Caching kann aktiviert werden, um Lookups zu beschleunigen. Sie können Caching-Optionen für eine individuelle YAML-Konfigurationsquelle oder für mehrere Bestandsquellen mit Umgebungsvariablen oder Ansible-Konfigurationsdateien festlegen. Wenn Sie Caching für ein Bestands-Plug-in aktivieren, ohne bestandsspezifische Caching-Optionen anzugeben, verwendet das Bestands-Plug-in Fakten-Caching-Optionen.

Im Folgenden finden Sie ein Beispiel für das Aktivieren von Caching für eine einzelne YAML-Konfigurationsdatei:

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

Dynamische Gruppen verwenden

Sie können dynamische Gruppen mit Hostvariablen mit der Option keyed_groups erstellen. Mit der Option groups können auch Gruppen erstellt und Hostvariablen erstellt und geändert werden. Syntax für Gruppen mit Schlüsseln und Gruppen, die Tags verwenden:

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

Beispiel: 

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

Dieses Beispiel erzeugt die Ausgabe, die in etwa wie folgt aussieht: 

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

Wenn ein Host nicht über die in der Konfiguration angegebenen Variablen verfügt, wird der Host nur zu den vom Bestands-Plug-in erstellten Gruppen hinzugefügt, und die Hostvariable ansible_host wird nicht geändert.

Bestandsszenarios

Die folgenden Abschnitte enthalten Konfigurationsbeispiele für häufige Bestandszenarios.

Alle Compute-Hosts abrufen

Um alle Hosts abzurufen, kann Ihre Konfiguration so einfach wie im folgenden Beispiel sein:

plugin: oracle.oci.oci

Nur DB-Hosts abrufen

Wenn alle Knoten abgerufen werden sollen, die Datenbanksoftware hosten, während Compute-Hosts ausgeschlossen werden, sieht die Konfiguration wie im folgenden Beispiel aus:

plugin: oracle.oci.oci

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

Hosts aus bestimmten Regionen abrufen

Wenn nur Hosts in angegebenen Regionen abgerufen werden sollen, sieht die Konfiguration in etwa wie im folgenden Beispiel aus:

plugin: oracle.oci.oci

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

Bestandshostnamen festlegen

Wenn das Format des im Bestand verwendeten Bestandshostnamens festgelegt werden soll, enthält die Konfiguration einen Abschnitt wie im folgenden Beispiel:

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"

Weitere Informationen finden Sie unter Voreinstellungen für Hostnamensformat.

Hosts aus Bestand ausschließen

Wenn Hosts mit einem Jinja2-Bedingungsausdruck aus dem Bestand ausgeschlossen werden sollen, enthält die Konfiguration einen Abschnitt wie im folgenden Beispiel:

plugin: oracle.oci.oci

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

Weitere Informationen finden Sie unter Hosts filtern.

Hosts in Bestand einschließen

Wenn Hosts mit einem Jinja2-Bedingungsausdruck in den Bestand aufgenommen werden sollen, enthält die Konfiguration einen Abschnitt wie im folgenden Beispiel:

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

Weitere Informationen finden Sie unter Hosts filtern.

Hinweis

Die Optionen include_host_filters und filters können nicht gemeinsam verwendet werden.

Hosts aus bestimmten Compartments abrufen

Das folgende Beispiel zeigt, wie alle Hosts aus den angegebenen Compartments abgerufen werden:

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

Weitere Optionen

Die folgende Beispielkonfiguration kombiniert die oben genannten Szenarios mit weiteren Konfigurationsoptionen:

# 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

Fehler mit dem Bestands-Plug-in beheben

Wenn die vom OCI-Bestand-Plug-in generierte Bestandsliste nicht jede Compute-Instanz in Ihrem Mandanten enthält, lesen Sie die folgenden Informationen.

Benutzerberechtigungen

Stellen Sie sicher, dass der Benutzer über die folgenden Policy-Berechtigungen verfügt. Die Benutzer-OCID wird entweder mit der OCI_USER-Umgebungsvariablen oder dem Abschnitt profile in der SDK- und CLI-Konfigurationsdatei angegeben.

Eine Liste der Berechtigungen für API-Vorgänge finden Sie unter Details zu den Coreservices.

Das Bestands-Plug-in führt API-Aufrufe für die folgenden Vorgänge durch:

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

Weitere Informationen

Ausführliche Informationen zur Verwendung des OCI-Bestands-Plug-ins finden Sie unter docs.oracle.com und readthedocs.io.

Sie können auch den folgenden Befehl verwenden, um die Plug-in-Dokumentation anzuzeigen:

ansible-doc -t inventory oracle.oci.oci

Weitere Informationen zu Bestands-Plug-ins finden Sie in der offiziellen Ansible-Dokumentation.