はじめに

Ansible には、OSのバージョンやIPアドレスなどのシステム情報を収集する仕組みがあります。これらのシステム情報をファクト（fact / fatcs）と呼びます。

ファクトは、ansible_ というプレフィックスを持つ変数や、変数 ansible_facts の中に入る値として参照できます。たとえば時刻であれば、ansible_date_time というトップレベルの変数か、ansible_facts['date_time'] といった具合です。

もともとトップレベルの変数の仕様があって、どこかの Ansible のバージョンから ansible_facts['hoge'] でも参照できるようになったという経緯があります。

2025年11月にリリースされた ansible-core 2.20.0 では、トップレベルの変数としてのファクト（ansible_date_time など）の参照が非推奨（Deprecated）になりました。

ansible-core 2.20.0 の Changelog より引用
- INJECT_FACTS_AS_VARS configuration currently defaults to True, this is now deprecated and it will switch to False by Ansible 2.24.

参照すると警告が表示されます。ansible-core 2.24 ではいよいよ利用できなくなる（変数未定義扱い）になる予定です。

実際、どのような警告が表示されるのか試してみたので、結果をまとめます。

検証環境
- ansible-core 2.20.0

検証 Playbook

以下のような Playbook を利用します。

ファクトを収集する必要があるので、gather_facts: false は指定しません。

---
- name: Facts test Play
  hosts: localhost
  connection: local

  tasks:
    - name: Facts test
      ansible.builtin.debug:
        msg: "{{ ansible_date_time }}"  # トップレベルの変数を参照

実行結果

実行結果は以下のとおりです。

ansible_date_time を参照している箇所が示され、プレフィックス ansible_ （トップレベル）ではなく、ansible_facts["fact_name"] を使ってねという警告が表示されました。エラーではなく警告なので、Playbook の処理自体は続行されました。

$ ansible-playbook -i localhost, facts_test.yml

PLAY [Facts test Play] ********************************************************************************************

TASK [Gathering Facts] ********************************************************************************************

ok: [localhost]

TASK [Facts test] *************************************************************************************************
[WARNING]: Deprecation warnings can be disabled by setting `deprecation_warnings=False` in ansible.cfg.
[DEPRECATION WARNING]: INJECT_FACTS_AS_VARS default to `True` is deprecated, top-level facts will not be auto injected after the change. This feature will be removed from ansible-core version 2.24.
Origin: /home/sakana/ansible/ac220/facts_test.yml:10:14

 8     - name: Facts test
 9       ansible.builtin.debug:
10         msg: "{{ ansible_date_time }}"
                ^ column 14

Use `ansible_facts["fact_name"]` (no `ansible_` prefix) instead.

ok: [localhost] => {
    "msg": {
        "date": "2025-12-05",
        "day": "05",
        "epoch": "1764916154",
        "epoch_int": "1764916154",
        "hour": "15",
        "iso8601": "2025-12-05T06:29:14Z",
        "iso8601_basic": "20251205T152914982733",
        "iso8601_basic_short": "20251205T152914",
        "iso8601_micro": "2025-12-05T06:29:14.982733Z",
        "minute": "29",
        "month": "12",
        "second": "14",
        "time": "15:29:14",
        "tz": "JST",
        "tz_dst": "JST",
        "tz_offset": "+0900",
        "weekday": "Friday",
        "weekday_number": "5",
        "weeknumber": "48",
        "year": "2025"
    }
}

PLAY RECAP ********************************************************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

もちろん、ansible_facts['date_time'] を参照する場合は、警告なしで実行できます。

設定による制御

トップレベルの変数としてのファクトが参照できるのは、INJECT_FACTS_AS_VARSという設定が、現状（ansible-core 2.20.0現在）はデフォルトで True であるためです。

$ ansible-config dump | grep -i inject
INJECT_FACTS_AS_VARS(default) = True

この設定を False にすることで、トップレベルの変数としてのファクトが参照できなくなります。ansible-core 2.24 への備えにもなるかもしれません。

[defaults]
inject_facts_as_vars=False

ansible.cfg で設定する場合は、上記のような定義をしておき Playbook を実行すると、以下のような結果になります。

例の警告は表示されず、いきなり ansible_date_time という変数は未定義ですというエラーです。エラーなので処理も止まります。

$ ansible-playbook -i localhost, facts_test.yml

PLAY [Facts test Play] *****************************************************************************************

TASK [Gathering Facts] *****************************************************************************************

ok: [localhost]

TASK [Facts test] **********************************************************************************************
[ERROR]: Task failed: Finalization of task args for 'ansible.builtin.debug' failed: Error while resolving value for 'msg': 'ansible_date_time' is undefined

Task failed.
Origin: /home/sakana/ansible/ac220/facts_test.yml:8:7

6
7   tasks:
8     - name: Facts test
        ^ column 7

<<< caused by >>>

Finalization of task args for 'ansible.builtin.debug' failed.
Origin: /home/yokochi/git/general/ansible/ac220/facts_test.yml:9:7

7   tasks:
8     - name: Facts test
9       ansible.builtin.debug:
        ^ column 7

<<< caused by >>>

Error while resolving value for 'msg': 'ansible_date_time' is undefined
Origin: /home/yokochi/git/general/ansible/ac220/facts_test.yml:10:14

 8     - name: Facts test
 9       ansible.builtin.debug:
10         msg: "{{ ansible_date_time }}"
                ^ column 14

fatal: [localhost]: FAILED! => {"msg": "Task failed: Finalization of task args for 'ansible.builtin.debug' failed: Error while resolving value for 'msg': 'ansible_date_time' is undefined"}

PLAY RECAP *****************************************************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0

おわりに

まだ警告レベルなので修正の緊急度は高くないですが、少なくとも今後書く際は ansible_facts["fact_name"] の形式がよいと思います。

ま余談ですが、こんなこともあろうかと（？）、「Ansible実践ガイド第3版」から「Ansible 実践ガイド第4版 [基礎編]」に改版するときに、ansible_facts['hogehoge'] の形式に書き換えています。

参考

ansible-core 2.20 ポーティングガイド
- The INJECT_FACTS_AS_VARS configuration currently defaults to True, but this is now deprecated and it will switch to False in Ansible 2.24.
Ansible Forum 上の関連書き込み