오래된 플레이북(제품에 딸려 온 설치 스크립트 등)을 최신 Ansible 로 돌리면 이 오류로 즉시 멈춘다.
ERROR! [DEPRECATED]: ansible.builtin.include has been removed.
Use include_tasks or import_tasks instead.
This feature was removed from ansible-core in a release after 2023-05-16.
Please update your playbooks.
include 모듈은 오래전부터 사용 중단 경고를 내다가 ansible-core 에서 완전히 제거됐다. 경고가 아니라 제거이므로 옵션으로 끌 수 없고, 플레이북을 고치거나 Ansible 버전을 낮추는 것 외에 방법이 없다.
include 하나가 두 개로 갈라졌다. 단순 치환이 아니라 동작이 다르므로 어느 쪽인지 판단해야 한다.
import_tasks |
include_tasks |
|
|---|---|---|
| 처리 시점 | 플레이북 파싱 시(정적) | 실행 중(동적) |
| 파일명에 변수 사용 | 불가 | 가능 |
loop 적용 |
불가 | 가능 |
when 적용 범위 |
포함된 모든 태스크에 각각 전파 | include 문 자체에만 적용 |
--list-tasks 표시 |
표시됨 | 표시되지 않음 |
| 태그 전파 | 하위 태스크로 전파됨 | include 문에만 붙음 |
판단 기준은 단순하다. 파일명이 고정이면 import_tasks, 변수나 반복이 끼면 include_tasks.
# 고정 경로 — import
- name: Install OpenLDAP server
ansible.builtin.import_tasks: install-ldap.yml
# 변수가 들어가거나 반복 — include
- name: Apply per-role tasks
ansible.builtin.include_tasks: "roles/{{ item }}/setup.yml"
loop: "{{ target_roles }}"
when 의 차이가 특히 함정이다. import_tasks 에 when 을 붙이면 조건이 하위 태스크 전부에 복제되어 각각 평가된다. 하위 태스크가 set_fact 로 조건 변수를 바꾸는 구조였다면 결과가 달라질 수 있다.
grep -rn --include='*.yml' --include='*.yaml' -E '^\s*-?\s*include:' .
grep -rn --include='*.yml' --include='*.yaml' -E 'include_vars|include_role|import_role' .
include_vars · include_role · import_role 은 제거 대상이 아니므로 그대로 둔다. 제거된 것은 태스크 포함용 include 하나다.
플레이 수준에서 다른 플레이북 파일을 부르는 - include: other.yml 형태라면 import_playbook 으로 바꾼다.
- ansible.builtin.import_playbook: other.yml
제품이 제공한 플레이북이라 손대기 부담스러우면, 그 플레이북이 검증한 Ansible 버전을 별도 가상 환경에 설치해 쓰는 방법이 있다. 시스템 전역 Ansible 은 건드리지 않는다.
python3 -m venv ~/venv/ansible-legacy
~/venv/ansible-legacy/bin/pip install "ansible-core<2.16"
~/venv/ansible-legacy/bin/ansible-playbook -i inventory site.yml
ansible.builtin.include 는 ansible-core 2.16 에서 제거됐다. 그보다 낮은 계열을 쓰면 경고만 나오고 동작한다.
확인 필요 — 제거 시점의 정확한 마이너 버전은 배포 경로(ansible 패키지 vs ansible-core)에 따라 체감이 다를 수 있다. 고정할 버전은 ansible-core 의 changelog 에서 해당 항목을 직접 확인한 뒤 정한다.
다만 이 방법은 시간을 버는 것일 뿐이다. 그 플레이북을 계속 쓸 거라면 결국 고쳐야 한다. 치환 자체는 기계적이라 오래 걸리지 않는다.
ansible-playbook --syntax-check -i inventory site.yml
ansible-playbook --list-tasks -i inventory site.yml
ansible-playbook --check -i inventory site.yml
--list-tasks 로 보이던 태스크가 사라졌다면 include_tasks 로 바꾼 것이다. 태그로 부분 실행을 하고 있었다면 이 변화가 실행 범위를 바꾸므로 함께 점검한다.