Oracle Cloud Infrastructureドキュメント

動的インベントリ・スクリプトの使用

Ansibleは、インベントリ・リストと呼ばれるリストを単純なリスト・ファイル(hostfileとも呼ばれる)として保存することによって、構成リソースを追跡します。 これらのインベントリ・ファイルは、単純な静的リストでも、インベントリ・リソースの追加、削除、移動時に自動的に更新される動的リストでもかまいません。 Ansibleインベントリ・ファイルの詳細については、「インベントリを使って作業」を参照してください。 「動的インベントリの操作」も参照してください。

Ansibleを使用してOracle Cloud Infrastructureでプロビジョニングしたホストで作業する場合、Computeインスタンスが追加され、時間の経過とともに削除されるため、静的インベントリ・リストで問題が発生する可能性があります。 Terraformなどの外部ツールやOracle Cloud Infrastructure SDKの影響を受ける可能性もあります。

Ansibleのプレイブックを実行するには、最新の正確なインベントリ庫リストを取得することが不可欠です。 Oracle Cloud Infrastructureはダウンロードして実行できるスクリプトを提供して、インスタンスのインベントリ・リストが常に最新であることを確認します。 スクリプトは、あなたのプレイブックに利用可能な現行のOracle Cloud Infrastructureコンピュート・インスタンスを常に持っていることを保証します。

動的インベントリ・スクリプトのダウンロードと構成

動的インベントリ・スクリプト(oci_inventory.py)とデフォルト構成ファイル(oci_inventory.ini)を次からダウンロードします:

重要

スクリプトを使用する前に、必ず有効なOracle Cloud Infrastructure構成を使用してください。
~/.oci/configの構成手順については、「SDKおよびCLI構成ファイル」を参照してください。

スクリプトと構成の詳細

Pythonスクリプトoci_inventory.pyは、Oracle Cloud Infrastructure Python SDKを使用してOracle Cloud Infrastructureテナンシ内のコンピュート・インスタンスを問合せし、この情報を使用してAnsibleプレイブックで使用できる動的インベントリを作成します。 Pythonスクリプトの引数を使用して、問合せする構成プロファイルとコンパートメントを制御します。

構成ファイルoci_inventory.iniを使用して、インベントリの詳細のキャッシュ方法を制御し、使用するOracle Cloud Infrastructureプロファイルを制御することができます。 このファイルを使用すると、ホスト名を変更したり、生成されたインベントリ・リスト内のホストの名前付け方法を制御できます。

コマンドライン引数

oci_inventory.pyスクリプトは、次のコマンドライン引数を受け入れます:

usage: oci_inventory.py [-h] [--list] [--host HOST] [-config CONFIG_FILE]
                        [--profile PROFILE] [--tenancy TENANCY]
                        [--compartment-ocid COMPARTMENT_OCID]
                        [--compartment COMPARTMENT]
                        [--parent-compartment-ocid PARENT_COMPARTMENT_OCID]
                        [--fetch-hosts-from-subcompartments] [--refresh-cache]
                        [--debug] [--auth {api_key,instance_principal}]
                        [--enable-parallel-processing]
                        [--max-thread-count MAX_THREAD_COUNT]
                        [--freeform-tags FREEFORM_TAGS]
                        [--defined-tags DEFINED_TAGS] [--regions REGIONS]
                        [--exclude-regions EXCLUDE_REGIONS]Produce an Ansible Inventory file based on OCIoptional arguments:
  -h, --help            show this help message and exit
  --list                List instances (default: True)
  --host HOST           Get all information about a compute instance
  -config CONFIG_FILE, --config-file CONFIG_FILE
                        OCI config file location
  --profile PROFILE     OCI config profile for connecting to OCI
  --tenancy TENANCY     OCID of the tenancy for which dynamic inventory must
                        be generated.
  --compartment-ocid COMPARTMENT_OCID
                        OCID of the compartment for which dynamic inventory
                        must be generated. If specified, any value specified
                        for compartment and parent-compartment-ocid options is
                        ignored.
  --compartment COMPARTMENT
                        Name of the compartment for which dynamic inventory
                        must be generated. If you want to generate a dynamic
                        inventory for the root compartment of the tenancy,
                        specify the tenancy name as the name of the
                        compartment.
  --parent-compartment-ocid PARENT_COMPARTMENT_OCID
                        Only valid when --compartment is set. Parent
                        compartment ocid of the specified compartment.Defaults
                        to tenancy ocid.
  --fetch-hosts-from-subcompartments
                        Only valid when --compartment is set. Default is
                        false. When set to true, inventory is built with the
                        entire hierarchy of the given compartment.
  --refresh-cache, -r   Force refresh of cache by making API requests to OCI.
                        Use this option whenever you are building inventory
                        with new filter options to avoid reading cached
                        inventory. (default: False - use cache files)
  --debug               Send debug messages to STDERR
  --auth {api_key,instance_principal}
                        The type of authentication to use for making API
                        requests. By default, the API key in your config will
                        be used. Set this option to `instance_principal` to
                        use instance principal based authentication. This
                        value can also be provided in the
                        OCI_ANSIBLE_AUTH_TYPE environment variable.
  --enable-parallel-processing
                        Inventory generation for tenants with huge number of
                        instances might take a long time.When this flag is
                        set, the inventory script uses thread pools to
                        parallelise the inventory generation.
  --max-thread-count MAX_THREAD_COUNT
                        Only valid when --enable-parallel-processing is set.
                        When set, this script uses threads to improve the
                        performance of building the inventory. This option
                        specifies the maximum number of threads to use.
                        Defaults to 50. This value can also be provided in the
                        settings config file.
  --freeform-tags FREEFORM_TAGS
                        Freeform tags provided as a string in valid JSON
                        format. Example: { "stage": "dev", "app": "demo"} Use
                        this option to build inventory of only those hosts
                        which are tagged with all the specified key-value
                        pairs.
  --defined-tags DEFINED_TAGS
                        Defined tags provided as a string in valid JSON
                        format. Example: {"namespace1": {"key1": "value1",
                        "key2": "value2"}, "namespace2": {"key": "value"}} Use
                        this option to build inventory of only those hosts
                        which are tagged with all the specified key-value
                        pairs.
  --regions REGIONS     Comma separated region names to build the inventory
                        from. Default is the region specified in the config.
                        Please specify 'all' to build inventory from all the
                        subscribed regions. Example: us-ashburn-1,us-phoenix-1
  --exclude-regions EXCLUDE_REGIONS
                        Comma separated region names to exclude while building
                        the inventory. Example: us-ashburn-1,uk-london-1

環境変数

oci_inventory.pyスクリプトは、次の表に示すいくつかの環境変数を受け入れます。

環境変数 説明
OCI_CONFIG_FILE 使用するOracle Cloud Infrastructure SDK構成ファイルを指定します。
OCI_INI_PATH どのインベントリ・スクリプト構成ファイルを使用するかを指定します。
OCI_CONFIG_PROFILE 使用するSDK構成ファイルでプロファイルする種。
OCI_USER_ID インベントリの取得に使用するユーザーのOCIDを指定します。
OCI_USER_FINGERPRINT インベントリをフェッチするために使用されているユーザーのキー・ペア・フィンガープリントを指定します。
OCI_USER_KEY_FILE インベントリを取得するために使用されているユーザーの秘密キーへのフルパスを指定します。 パスには、秘密キー・ファイル名を含める必要があります。
OCI_TENANCY インベントリの取得に使用するテナンシのOCIDを指定します。
OCI_REGION インベントリの取得に使用するOracle Cloud Infrastructureリージョンを指定します。
OCI_USER_KEY_PASS_PHRASE インベントリの取得に使用するキー(暗号化されている場合)のパスフレーズを指定します。
OCI_CACHE_DIR インベントリ・スクリプト・キャッシュ・ファイルが存在するディレクトリを指定します。 スクリプトは、このディレクトリにansible-oci.cacheという名前のファイルを作成します。
OCI_CACHE_MAX_AGE キャッシュ・ファイルが有効な秒数。 キャッシングを無効にして最新のインベントリを取得するには、この値を0 (ゼロ)に設定します。
OCI_HOSTNAME_FORMAT 生成されるインベントリ・ファイル内のホスト名をリストするための形式。 fqdnを使用して、インスタンスの完全修飾ドメイン名(FQDN)を使用してホストを一覧表示します。 public_ipを使用して、パブリックIPアドレスを使用してホストを一覧表示します。 プライベートIPアドレスを使用してホストを一覧表示するには、private_ipを使用します。
OCI_ANSIBLE_AUTH_TYPE APIリクエストの作成に使用する認証のタイプを指定します。 デフォルトでは、構成内のAPIキーが使用されます。 インスタンス出力ベースの認証を使用するには、値をinstance_principalに設定します。
OCI_INVENTORY_REGIONS 在庫の構築元となるリージョン名をカンマで区切ってください。 デフォルトは、構成で指定されたリージョンです。 すべてのサブスクライブされたリージョンから在庫を作成するには、'all'を指定してください。 例: us-ashburn-1,us-phoenix-1
OCI_INVENTORY_EXCLUDE_REGIONS

在庫の作成時に除外するリージョン名をカンマで区切ります。 例: us-ashburn-1,uk-london-1

OCI_COMPARTMENT_OCID 動的在庫を生成する必要があるコンパートメントのOCID。 指定した場合、コンパートメントおよびparent-compartment-ocidのオプションに指定した値は無視されます。

優先順位

ダイナミック・インベントリ・スクリプトで使用される構成の優先順位は次のとおりです:

  1. コマンド行引数
  2. 環境変数。
  3. Oracle Cloud Infrastructure構成ファイル内の選択したprofileの構成設定。

ノート

インベントリ・スクリプトで使用されるデフォルトの構成ファイルは./oci_inventory.iniです。
ただし、Oracle Cloud Infrastructure SDK構成ファイルはデフォルトで~/.oci/configになります。 プロファイル名が指定されていない場合、スクリプトはconfigファイルからDEFAULTプロファイルを読み取ります。

重要

デフォルトでは、インベントリはテナンシ内のすべてのコンパートメントに対して生成されます。
このスクリプトがすべてのコンパートメントにアクセスできるようにするには、ルート・コンパートメントに対するCOMPARTMENT_INSPECT権限が必要です。 ただし、compartment_ocidを指定すると、インベントリは特定のコンパートメントに対してのみ生成されるため、指定するコンパートメントに対するCOMPARTMENT_INSPECT権限のみが必要になります。

動的インベントリ・スクリプトによって生成されるインベントリ・リストは、次の属性を使用してグループ化されます:

  • コンピュート・インスタンスが存在するリージョン。
  • コンピュート・インスタンスが属するコンパートメントの名前。
  • コンピュート・インスタンスがある可用性ドメイン。
  • コンピュート・インスタンスが存在するvcnのvcn_id。
  • コンピュート・インスタンスがあるサブネットのsubnet_id。
  • コンピュート・インスタンスがあるサブネットのsecurity_list_ids。
  • コンピュート・インスタンスを起動するために使用されたイメージのimage_id。
  • コンピュート・インスタンスのシェイプ。
  • インスタンス・フリーフォームのタグ。グループ名はtag_ <tag_name> = <tag_value>に設定されています。
  • インスタンス定義のタグ。グループ名は<tag_namespace>#<tag_name> = <tag_value>に設定されています。
  • グループ名が<metadata-key> = <metadata-value>に設定されたOracle Cloud Infrastructureコンピュート・インスタンス・メタデータ(キーと値のペア)。
  • グループ名が<metadata-key> = <metadata-value>に設定された、Oracle Cloud Infrastructureコンピュート・インスタンス拡張メタデータ(キーと値のペア)。

重要

デフォルトでは、グループ名およびホスト名の英数字以外の文字は、インベントリがハッシュ(#)、等号((=)、ピリオド(.)およびダッシュ(-)を除いて生成されるときに、アンダースコア(_)で置換されます。
これにより、これらの名前をAnsibleグループ名として使用できます。 このデフォルトの置換を無効にするには、動的インベントリ設定ファイルのsanitize_namesFalseに設定します。デフォルトのロケーションは./oci_inventory.iniです。 sanitize_namesTrueのときにダッシュ(-)を置き換えるには、設定ファイルでreplace_dash_in_namesTrue に設定します。

動的インベントリの使用方法

プレイブック実行時の動的インベントリの使用

動的インベントリを使用するには、まずOracle Cloud Infrastructure SDK構成ファイルが正しいことを確認します。 必要に応じて、oci_inventory.iniファイルを作成することもできます。

次のコマンドを使用してansible-playbookを呼び出します:

$ ansible-playbook -i <path-to-inventory-file>/oci_inventory.py <your-playbook-using-the-generated-inventory>

または、次のコマンドを使用してANSIBLE_HOSTS環境変数を使用します:

$ ANSIBLE_HOSTS=<path-to-inventory-file>/oci_inventory.py ansible-playbook <your-playbook-using-the-generated-inventory>

キャッシュの無効化と最新のインベントリ・リストの取得

スタンドアロン方式で動的インベントリ・スクリプトを実行している場合、キャッシュされたインベントリ・リストを無視して、次の例に示すように、--refresh (-r)引数を使用して最新のインベントリ・リストをフェッチできます:

$ \<path-to-inventory-file\>/oci_inventory.py --refresh

代わりに、Ansibleプレイブック呼び出し中にインベントリ・スクリプトを使用する場合は、OCI_CACHE_MAX_AGE環境変数を0 (ゼロ)に設定して、キャッシュ・リストを無視し、次の例に示すように最新のコンピュート・インスタンスをフェッチします:

$ OCI_CACHE_MAX_AGE=0 ansible-playbook -i <path-to-inventory-file>/oci_inventory.py <your-playbook-using-the-generated-inventory>

インベントリ・リストのデバッグ

インベントリ・リストを調べるには、以下に示すように、--list引数を使用して動的インベントリ・スクリプトを実行します:

$ \<path-to-inventory-file\>/oci_inventory.py --list

追加のデバッグ情報をSTDERRに出力する場合は、次のように--debug引数を使用します:

$ \<path-to-inventory-file\>/oci_inventory.py --debug

ホストに関する情報を取得

--host引数を使用してホストIPアドレスを指定すると、指定されたホストに関する情報を提供するようにインベントリ・スクリプトを構成できます:

$ \<path-to-inventory-file\>/oci_inventory.py --host <host IP address>

このコマンドは、次の変数と値のセットを返します:

{
  "availability_domain": "IwGV:US-ASHBURN-AD-1",
  "compartment_id": "ocid1.compartment.oc1..<xxxxxEXAMPLExxxxx>",
  "defined_tags": {},
  "display_name": "ansible-test-instance",
  "extended_metadata": {},
  "freeform_tags": {},
  "id": "ocid1.instance.oc1.iad.<xxxxxEXAMPLExxxxx>",
  "image_id": "ocid1.image.oc1.iad.<xxxxxEXAMPLExxxxx>",
  "ipxe_script": null,
  "launch_mode": "CUSTOM",
  "launch_options": {
     "boot_volume_type": "ISCSI",
     "firmware": "UEFI_64",
     "network_type": "VFIO",
     "remote_data_volume_type": "ISCSI"
  },
  "lifecycle_state": "AVAILABLE",
  "metadata": {
     "baz": "quux",
     "foo": "bar"
  },
  "region": "iad",
  "shape": "VM.Standard1.1",
  "source_details": {
    "image_id": "ocid1.image.oc1.iad.<xxxxxEXAMPLExxxxx>",
  "source_type": "image"
  },
  "time_created": "2018-01-16T12:13:35.336000+00:00"
}

動的インベントリ・スクリプトのトラブルシューティング

インベントリ・スクリプトによって生成されたインベントリ・リストに、テナンシ内のすべてのコンピュート・インスタンスが含まれていない場合は、次の情報を確認してください。

ユーザーの権限

ユーザーOCID (OCI_USER環境変数またはSDK構成ファイルのprofileセクションのいずれかを使用して指定)に、コンピュート・インスタンスを一覧表示するためのポリシー権限があることを確認します。 API操作の権限のリストを表示するには、「コア・サービスの詳細」を参照してください。

インベントリ・スクリプトは、次の操作のAPI呼び出しを行います:

  • ListCompartments
  • ListVNICAttachments
  • GetSubnet
  • GetVCN
  • GetVNIC
  • GetInstance

ホスト名形式

OCI_HOSTNAME_FORMATのデフォルトはpublic_ipです。 OCI_HOSTNAME_FORMATpublic_ipに設定して生成された動的インベントリには、パブリックIPアドレスを持つコンピュート・インスタンスのみが含まれます。 これは、AnsibleがパブリックIPアドレスを持つインスタンスにしか到達できないため、Ansibleコントローラ・ノードがVCNの外部にある場合に役立ちます。

ただし、VCN内のコンピュート・インスタンスでAnsibleを実行していて、プライベートIPアドレスを持つコンピュート・インスタンスを含むVCN内のすべてのサブネットにアクセスできる場合は、OCI_HOSTNAME_FORMATprivate_ipに設定して、プライベートIPアドレス。