특수 변수

특수 변수 (Special Variables)

Ansible은 자동으로 설정되고 사용자가 직접 바꿀 수 없는 특별한 변수들을 제공해요. 이들은 실행 중인 플레이의 내부 상태를 반영하는 '매직 변수(magic variables)'와, 호스트에 대한 정보를 담는 '사실(facts)', 그리고 연결 방식을 정하는 '연결 변수(connection variables)'로 나뉘어요. 이 글에서는 이런 변수들이 무엇을 뜻하는지 하나씩 정리할게요.

출처: 문서

본문

매직 변수 (Magic variables)

이 변수들은 사용자가 직접 설정할 수 없어요. Ansible은 항상 내부 상태를 반영하도록 이들을 덮어써요.

  • ansible_check_mode — check mode인지 아닌지를 나타내는 Boolean이에요.
  • ansible_collection_name — 실행 중인 작업이 속한 컬렉션의 이름이에요. namespace.collection 형식이에요.
  • ansible_config_file — 사용 중인 Ansible 설정 파일의 전체 경로예요.
  • ansible_dependent_role_names — 다른 플레이의 의존성으로 현재 플레이에 가져온 역할들의 이름이에요.
  • ansible_diff_mode — diff mode인지 아닌지를 나타내는 Boolean이에요.
  • ansible_forks — 이 실행에서 사용 가능한 최대 포크(fork) 수를 반영하는 정수예요.
  • ansible_index_var — loop_control.index_var에 제공된 값의 이름이에요. 2.9에서 추가되었어요.
  • ansible_inventory_sources — 인벤토리로 사용된 소스 목록이에요.
  • ansible_limit — 현재 Ansible 실행에서 --limit CLI 옵션의 내용이에요.
  • ansible_loop — loop_control.extended를 통해 활성화했을 때 확장 루프 정보를 담는 딕셔너리/맵이에요.
  • ansible_loop_var — loop_control.loop_var에 제공된 값의 이름이에요. 2.8에서 추가되었어요.
  • ansible_parent_role_names — 현재 역할이 include_role이나 import_role 액션으로 실행될 때, 모든 부모 역할 목록을 담는 변수예요. 가장 최근 역할(즉 이 역할을 포함/가져온 역할)이 목록의 첫 번째 항목이에요. 여러 번 포함되는 경우에도 목록은 마지막 역할(이 역할을 포함한 역할)을 첫 항목으로 나열해요. 특정 역할이 이 목록에 두 번 이상 나타날 수도 있어요. 예를 들어 역할 A가 역할 B를 포함하면, 역할 B 내부에서 ansible_parent_role_names는 ['A']와 같아져요. 역할 B가 역할 C를 포함하면 목록은 ['B', 'A']가 돼요.
  • ansible_parent_role_paths — 현재 역할이 include_role이나 import_role 액션으로 실행될 때, 모든 부모 역할 경로 목록을 담는 변수예요. 목록 항목의 순서는 ansible_parent_role_names를 참고하세요.
  • ansible_play_batch — 현재 플레이 실행에서 serial로 제한된 활성 호스트 목록이에요. 실패/도달 불가(Unreachable) 호스트는 '활성'으로 간주되지 않아요.
  • ansible_play_hosts — 현재 플레이 실행의 호스트 목록으로, serial로 제한되지 않아요. 실패/도달 불가 호스트는 이 목록에서 제외돼요.
  • ansible_play_hosts_all — 플레이가 대상으로 한 모든 호스트 목록이에요.
  • ansible_play_name — 현재 실행 중인 플레이의 이름이에요. 2.8에서 추가되었어요. (플레이의 name 속성이지, 플레이북 파일 이름이 아니에요.)
  • ansible_play_role_names — 현재 플레이에 가져온 역할들의 이름이에요. 이 목록에는 의존성을 통해 암시적으로 포함된 역할 이름은 포함되지 않아요.
  • ansible_playbook_python — 컨트롤 노드에서 Ansible이 사용하는 Python 인터프리터의 경로예요.
  • ansible_role_name — namespace.collection.role_name 형식의 완전한 컬렉션 역할 이름이에요.
  • ansible_role_names — 현재 플레이에 가져온 역할들, 또는 현재 플레이에 가져온 역할들의 의존성으로 참조된 역할들의 이름이에요.
  • ansible_run_tags — 현재 실행에 포함될 태그를 지정하는 --tags CLI 옵션의 내용이에요. --tags를 전달하지 않으면 이 변수는 ["all"]로 기본 설정된다는 점에 유의하세요.
  • ansible_search_path — 액션 플러그인과 lookup의 현재 검색 경로예요. 즉 template: src=myfile처럼 할 때 상대 경로를 검색하는 위치예요.
  • ansible_skip_tags — 현재 실행에서 건너뛸 태그를 지정하는 --skip-tags CLI 옵션의 내용이에요.
  • ansible_verbosity — Ansible의 현재 verbosity 설정이에요.
  • ansible_version — 실행 중인 현재 ansible 버전에 대한 정보를 담는 딕셔너리/맵이에요. full, major, minor, revision, string 키를 가져요.
  • group_names — 현재 호스트가 속한 그룹 목록이에요. 항상 inventory_hostname을 반영하고 위임(delegation)을 무시해요.
  • groups — 인벤토리의 모든 그룹과 각 그룹에 속한 호스트 목록을 담는 딕셔너리/맵이에요.
  • hostvars — 인벤토리의 모든 호스트와 그 호스트에 할당된 변수를 담는 딕셔너리/맵이에요.
  • inventory_dir — inventory_hostname이 처음 정의된 인벤토리 소스의 디렉터리예요. 항상 inventory_hostname을 반영하고 위임을 무시해요.
  • inventory_hostname — 플레이에서 순회 중인 '현재' 호스트의 인벤토리 이름이에요. 이는 위임의 영향을 받지 않으며, 항상 작업의 원래 호스트를 반영해요.
  • inventory_hostname_short — inventory_hostname의 짧은 버전으로, .으로 분리한 뒤 첫 번째 부분이에요. 예를 들어 inventory_hostname이 www.example.com이면 www가 inventory_hostname_short가 돼요. 이것은 위임의 영향을 받아, 위임된 호스트의 '짧은 이름'을 반영해요.
  • inventory_file — inventory_hostname이 처음 정의된 인벤토리 소스의 파일 이름이에요. 위임을 무시하고 항상 inventory_hostname에 대한 정보를 반영해요.
  • omit — 작업에서 옵션을 '생략(omit)'할 수 있게 하는 특수 변수예요. 예: - user: name=bob home={{ bobs_home|default(omit) }}
  • play_hosts — 더 이상 사용되지 않아요(deprecated). ansible_play_batch와 같아요.
  • playbook_dir — 현재 실행 중인 플레이북 디렉터리의 경로예요. 주의: 플레이북이 import_playbook 문을 포함할 때는 ansible-playbook 명령줄에 전달된 플레이북의 디렉터리와 다를 수 있어요.
  • role_name — 현재 실행 중인 역할의 이름이에요.
  • role_names — 더 이상 사용되지 않아요. ansible_play_role_names와 같아요.
  • role_path — 현재 실행 중인 역할의 디렉터리 경로예요.

사실 (Facts)

이 변수들은 현재 호스트(inventory_hostname)에 관한 정보를 담아요. 먼저 수집(gather)된 경우에만 사용할 수 있어요. 자세한 내용은 "Discovering variables: facts and magic variables" 문서를 참고하세요.

  • ansible_facts — inventory_hostname에 대해 수집되거나 캐시된 모든 사실을 담아요. 사실은 보통 플레이에서 setup 모듈이 자동으로 수집하지만, 어떤 모듈이든 사실을 반환할 수 있어요.
  • ansible_local — inventory_hostname에 대해 수집되거나 캐시된 모든 '로컬 사실(local facts)'을 담아요. 사용 가능한 키는 생성된 커스텀 사실에 따라 달라져요. 자세한 내용은 setup 모듈과 facts.d 또는 로컬 사실 문서를 참고하세요.

연결 변수 (Connection variables)

연결 변수는 보통 대상에서 작업을 실행하는 방법의 세부 사항을 설정하는 데 쓰여요. 대부분 연결 플러그인에 해당하지만, 모두가 특정 플러그인 전용은 아니에요. shell, terminal, become 같은 다른 플러그인도 보통 관여해요.

각 연결/become/shell 등 플러그인은 자체적인 override와 특정 변수를 정의할 수 있으므로, 여기서는 공통 변수만 설명해요. 연결 변수가 구성 설정, 명령줄 옵션, 플레이북 키워드와 어떻게 상호작용하는지는 "Controlling how Ansible behaves: precedence rules" 문서를 참고하세요.

  • ansible_become_user — 권한 상승(privilege escalation)을 사용한 후 Ansible이 '되는(become)' 사용자예요. '로그인 사용자(login user)'가 사용할 수 있어야 해요.
  • ansible_connection — 대상 호스트의 작업에 실제로 사용된 연결 플러그인이에요.
  • ansible_host — inventory_hostname 대신 사용할 대상 호스트의 IP/이름이에요.
  • ansible_python_interpreter — 대상 호스트에서 Ansible이 사용해야 할 Python 실행 파일의 경로예요.
  • ansible_user — Ansible이 '로그인'하는 사용자예요.

더 알아보기 (Learn more)