플레이북 키워드

플레이북 키워드 (Playbook Keywords)

Ansible 동작을 구성하는 몇 가지 원천 중 하나가 키워드예요. 이 페이지는 일반적인 플레이북 객체에서 사용할 수 있는 키워드를 정리해요. 각 원천의 상대적 우선순위에 대한 자세한 내용은 'Ansible 동작 제어하기: 우선순위 규칙' 문서를 참고하세요.

출처: 문서

본문

다음은 일반적인 플레이북 객체에서 사용할 수 있는 키워드 목록이에요. 키워드는 Ansible 동작을 구성하는 여러 원천 중 하나예요. 각 원천의 상대적 우선순위에 대한 자세한 내용은 '우선순위 규칙' 문서를 참고하세요.

참고 사항:

• 지시어의 별칭(alias)이나 가변적인 것들은 여기에 반영되지 않아요. 예를 들어 태스크의 action은 어떤 Ansible 모듈의 이름으로 대체될 수 있어요.

• 키워드에는 현재 version_added 정보가 없어요.

• 일부 키워드는 객체 자체가 아니라 그 안의 객체에 대해 기본값을 설정해요.

• Play

• Role

• Block

• Task

Play

any_errors_fatal

어떤 호스트의 처리되지 않은 태스크 오류가 강제로 모든 호스트에 전파되어 play를 끝내게 해요.

become

태스크 실행에 권한 상승을 사용할지 여부를 제어하는 불리언이에요. become 플러그인이 구현해요. Become 플러그인 문서를 참고하세요.

become_exe

권한을 올리는 데 사용하는 실행 파일의 경로예요. become 플러그인이 구현해요. Become 플러그인 문서를 참고하세요.

become_flags

become이 True일 때 권한 상승 프로그램에 전달할 플래그 문자열이에요.

become_method

사용할 권한 상승 방법(예: sudo 또는 su)이에요.

become_user

권한 상승을 사용한 후 '되게 되는(become)' 사용자예요. 원격/로그인 사용자는 이 사용자가 될 권한이 있어야 해요.

check_mode

태스크가 정상적으로 실행되는지, 아니면 대상 변경을 피하고 무엇을 했을지 보고하려 하는지(체크 모드/드라이 런)를 제어하는 불리언이에요. 'Validate tasks: check mode and diff mode' 문서를 참고하세요.

collections

모듈, 플러그인, 롤을 검색할 컬렉션 네임스페이스 목록이에요. '플레이북에서 컬렉션 사용하기' 문서를 참고하세요.

참고: 롤 내부의 태스크는 play에서 collections 값을 상속받지 않아요. 롤이 컬렉션 목록을 검색하게 하려면 롤 안 meta/main.yml에서 collections 키워드를 사용하세요.

connection

태스크가 대상에서 실행할 때 사용하는 연결 플러그인을 바꿀 수 있어요. '연결 플러그인 사용하기' 문서를 참고하세요.

debugger

태스크 결과의 상태에 따라 태스크 디버깅을 활성화해요. '태스크 디버깅하기' 문서를 참고하세요.

diff

태스크가 'diff' 정보를 반환할지 여부를 토글해요.

environment

실행 시 태스크에 제공될 환경 변수로 변환되는 딕셔너리예요. 이것은 모듈에서만 사용할 수 있어요. 다른 종류의 플러그인이나 Ansible 자체, 그 구성에서는 지원되지 않아요. 태스크를 실행하는 코드를 위한 변수만 설정할 뿐이에요. 기밀 데이터를 전달하는 데는 권장되지 않는 방법이에요.

fact_path

gather_facts가 제어하는 팩트 수집 플러그인의 fact path 옵션을 설정해요.

force_handlers

play 중 실패한 호스트에도 알림받은 핸들러 실행을 강제해요. play 자체가 실패하면 트리거되지 않아요.

gather_facts

play가 호스트의 팩트를 수집하기 위해 'setup' 태스크를 자동으로 실행할지 제어하는 불리언이에요.

gather_subset

gather_facts가 제어하는 팩트 수집 플러그인에 subset 옵션을 전달할 수 있어요.

gather_timeout

gather_facts가 제어하는 팩트 수집 플러그인의 타임아웃을 설정할 수 있어요.

handlers

핸들러로 취급되는 태스크가 있는 섹션이에요. 이 태스크들은 정상적으로 실행되지 않고, 각 태스크 섹션이 끝난 후 알림받았을 때만 실행돼요. 핸들러의 listen 필드는 템플릿화할 수 없어요.

hosts

play의 대상이 되는 호스트 목록으로 변환되는 그룹·호스트·호스트 패턴 목록이에요.

ignore_errors

태스크 실패를 무시하고 play를 계속할 수 있게 해주는 불리언이에요. 연결 오류에는 영향을 주지 않아요.

ignore_unreachable

호스트에 도달할 수 없어 발생한 태스크 실패를 무시하고 play를 계속하게 해주는 불리언이에요. 다른 태스크 오류에는 영향을 주지 않지만(ignore_errors 참고), 휘발성/임시 호스트 그룹에 유용해요.

max_fail_percentage

현재 배치의 호스트 중 주어진 백분율이 실패한 후 실행을 중단하는 데 쓸 수 있어요. linear 또는 linear 파생 전략에서만 동작해요.

module_defaults

모듈의 기본 매개변수 값을 지정해요.

name

식별자예요. 문서화나 태스크/핸들러에서 사용할 수 있어요.

no_log

정보 노출을 제어하는 불리언이에요.

order

play 실행에 사용될 때 호스트가 정렬되는 방식을 제어해요. 가능한 값은 inventory(기본값), sorted, reverse_sorted, reverse_inventory, shuffle이에요.

port

연결에 사용되는 기본 포트를 덮어쓰는 데 사용돼요.

post_tasks

tasks 섹션 이후에 실행할 태스크 목록이에요.

pre_tasks

롤 이전에 실행할 태스크 목록이에요.

remote_user

연결 플러그인을 통해 대상에 로그인하는 데 사용하는 사용자예요.

roles

play로 가져올 롤 목록이에요.

run_once

호스트 루프를 우회해 태스크가 사용 가능한 첫 번째 호스트에서 실행되도록 시도하고, 이후 결과와 팩트를 같은 배치의 모든 활성 호스트에 적용하게 하는 불리언이에요.

serial

Ansible이 play 대상에서 현재 play의 실행을 어떻게 배치(batch)하는지 명시적으로 정의해요. 'serial로 배치 크기 설정' 문서를 참고하세요.

strategy

play에 사용할 전략 플러그인을 선택할 수 있어요. 전략 플러그인 문서를 참고하세요.

tags

태스크나 포함된 태스크에 적용되는 태그로, 커맨드라인에서 태스크의 하위 집합을 선택할 수 있게 해줘요.

tasks

play에서 실행할 주요 태스크 목록으로, 롤 이후 post_tasks 이전에 실행돼요.

throttle

태스크·블록·플레이북 레벨에서 동시 태스크 실행 수를 제한해요. 이것은 forks와 serial 설정과 독립적이지만 그 한도보다 높게 설정할 수는 없어요. 예를 들어 forks가 10이고 throttle이 15라면 최대 10개 호스트가 병렬로 처리돼요.

timeout

태스크 액션이 실행될 시간 제한이에요. 초과하면 Ansible이 프로세스를 중단해요. timeout에는 템플릿화나 루핑이 포함되지 않아요.

validate_argspec

문서화되지 않음!!

vars

변수의 딕셔너리/맵이에요.

vars_files

play에 포함할 변수를 담은 파일 목록이에요.

vars_prompt

프롬프트를 표시할 변수 목록이에요.

Role

any_errors_fatal

어떤 호스트의 처리되지 않은 태스크 오류가 강제로 모든 호스트에 전파되어 play를 끝내게 해요.

become

태스크 실행에 권한 상승을 사용할지 여부를 제어하는 불리언이에요. become 플러그인이 구현해요.

become_exe

권한을 올리는 데 사용하는 실행 파일의 경로예요. become 플러그인이 구현해요.

become_flags

become이 True일 때 권한 상승 프로그램에 전달할 플래그 문자열이에요.

become_method

사용할 권한 상승 방법(예: sudo 또는 su)이에요.

become_user

권한 상승을 사용한 후 '되게 되는' 사용자예요. 원격/로그인 사용자는 이 사용자가 될 권한이 있어야 해요.

check_mode

태스크가 정상적으로 실행되는지, 아니면 대상 변경을 피하고 무엇을 했을지 보고하려 하는지(체크 모드/드라이 런)를 제어하는 불리언이에요.

collections

모듈, 플러그인, 롤을 검색할 컬렉션 네임스페이스 목록이에요. '플레이북에서 컬렉션 사용하기' 문서를 참고하세요.

참고: 롤 내부의 태스크는 play에서 collections 값을 상속받지 않아요. 롤이 컬렉션 목록을 검색하게 하려면 롤 안 meta/main.yml에서 collections 키워드를 사용하세요.

connection

태스크가 대상에서 실행할 때 사용하는 연결 플러그인을 바꿀 수 있어요.

debugger

태스크 결과의 상태에 따라 태스크 디버깅을 활성화해요.

delegate_facts

팩트를 inventory_hostname 대신 위임된 호스트에 적용하게 해주는 불리언이에요.

delegate_to

대상(inventory_hostname) 대신 태스크를 실행할 호스트예요. 위임된 호스트의 연결 변수도 태스크에 사용돼요.

diff

태스크가 'diff' 정보를 반환할지 여부를 토글해요.

environment

실행 시 태스크에 제공될 환경 변수로 변환되는 딕셔너리예요. 모듈에서만 사용할 수 있어요.

ignore_errors

태스크 실패를 무시하고 play를 계속할 수 있게 해주는 불리언이에요.

ignore_unreachable

호스트에 도달할 수 없어 발생한 태스크 실패를 무시하고 play를 계속하게 해주는 불리언이에요.

module_defaults

모듈의 기본 매개변수 값을 지정해요.

name

식별자예요.

no_log

정보 노출을 제어하는 불리언이에요.

port

연결에 사용되는 기본 포트를 덮어쓰는 데 사용돼요.

remote_user

연결 플러그인을 통해 대상에 로그인하는 데 사용하는 사용자예요.

run_once

호스트 루프를 우회해 태스크가 사용 가능한 첫 번째 호스트에서 실행되도록 시도하고 결과와 팩트를 같은 배치의 모든 활성 호스트에 적용하게 하는 불리언이에요.

tags

태스크나 포함된 태스크에 적용되는 태그로, 커맨드라인에서 하위 집합을 선택하게 해줘요.

throttle

태스크·블록·플레이북 레벨에서 동시 태스크 실행 수를 제한해요. forks와 serial 설정과 독립적이지만 그 한도보다 높게는 설정할 수 없어요.

timeout

태스크 액션이 실행될 시간 제한이에요. 초과하면 Ansible이 프로세스를 중단해요.

vars

변수의 딕셔너리/맵이에요.

when

조건 표현식으로, 태스크의 반복이 실행될지 여부를 결정해요.

Block

always

블록에 오류가 있든 없든 실행되는 블록 내 태스크 목록이에요.

any_errors_fatal

어떤 호스트의 처리되지 않은 태스크 오류가 강제로 모든 호스트에 전파되어 play를 끝내게 해요.

become

태스크 실행에 권한 상승을 사용할지 여부를 제어하는 불리언이에요. become 플러그인이 구현해요.

become_exe

권한을 올리는 데 사용하는 실행 파일의 경로예요. become 플러그인이 구현해요.

become_flags

become이 True일 때 권한 상승 프로그램에 전달할 플래그 문자열이에요.

become_method

사용할 권한 상승 방법(예: sudo 또는 su)이에요.

become_user

권한 상승을 사용한 후 '되게 되는' 사용자예요.

block

블록 내 태스크 목록이에요.

check_mode

태스크가 정상적으로 실행되는지, 아니면 대상 변경을 피하고 무엇을 했을지 보고하려 하는지(체크 모드/드라이 런)를 제어하는 불리언이에요.

collections

모듈, 플러그인, 롤을 검색할 컬렉션 네임스페이스 목록이에요.

참고: 롤 내부의 태스크는 play에서 collections 값을 상속받지 않아요. 롤이 컬렉션 목록을 검색하게 하려면 롤 안 meta/main.yml에서 collections 키워드를 사용하세요.

connection

태스크가 대상에서 실행할 때 사용하는 연결 플러그인을 바꿀 수 있어요.

debugger

태스크 결과의 상태에 따라 태스크 디버깅을 활성화해요.

delegate_facts

팩트를 inventory_hostname 대신 위임된 호스트에 적용하게 해주는 불리언이에요.

delegate_to

대상(inventory_hostname) 대신 태스크를 실행할 호스트예요.

diff

태스크가 'diff' 정보를 반환할지 여부를 토글해요.

environment

실행 시 태스크에 제공될 환경 변수로 변환되는 딕셔너리예요. 모듈에서만 사용할 수 있어요.

ignore_errors

태스크 실패를 무시하고 play를 계속할 수 있게 해주는 불리언이에요.

ignore_unreachable

호스트에 도달할 수 없어 발생한 태스크 실패를 무시하고 play를 계속하게 해주는 불리언이에요.

module_defaults

모듈의 기본 매개변수 값을 지정해요.

name

식별자예요.

no_log

정보 노출을 제어하는 불리언이에요.

notify

태스크가 'changed=True' 상태를 반환할 때 알릴 핸들러 목록이에요.

port

연결에 사용되는 기본 포트를 덮어쓰는 데 사용돼요.

remote_user

연결 플러그인을 통해 대상에 로그인하는 데 사용하는 사용자예요.

rescue

주 블록 목록에 태스크 오류가 있을 때 실행되는 블록 내 태스크 목록이에요.

run_once

호스트 루프를 우회하고 결과·팩트를 같은 배치의 모든 활성 호스트에 적용하게 하는 불리언이에요.

tags

태스크나 포함된 태스크에 적용되는 태그로, 커맨드라인에서 하위 집합을 선택하게 해줘요.

throttle

태스크·블록·플레이북 레벨에서 동시 태스크 실행 수를 제한해요.

timeout

태스크 액션이 실행될 시간 제한이에요. 초과하면 Ansible이 프로세스를 중단해요.

vars

변수의 딕셔너리/맵이에요.

when

조건 표현식으로, 태스크의 반복이 실행될지 여부를 결정해요.

Task

action

태스크에 대해 실행할 '액션'으로, 보통 모듈 또는 액션 플러그인으로 변환돼요.

any_errors_fatal

어떤 호스트의 처리되지 않은 태스크 오류가 강제로 모든 호스트에 전파되어 play를 끝내게 해요.

args

태스크에 인자를 추가하는 보조 방법이에요. 키가 옵션과 값을 매핑하는 딕셔너리를 받아요.

async

액션이 지원한다면 태스크를 비동기로 실행해요. 값은 초 단위 최대 실행 시간이에요.

become

태스크 실행에 권한 상승을 사용할지 여부를 제어하는 불리언이에요. become 플러그인이 구현해요.

become_exe

권한을 올리는 데 사용하는 실행 파일의 경로예요. become 플러그인이 구현해요.

become_flags

become이 True일 때 권한 상승 프로그램에 전달할 플래그 문자열이에요.

become_method

사용할 권한 상승 방법(예: sudo 또는 su)이에요.

become_user

권한 상승을 사용한 후 '되게 되는' 사용자예요.

changed_when

태스크의 일반적인 'changed' 상태를 덮어쓰는 조건 표현식이에요.

check_mode

태스크가 정상적으로 실행되는지, 아니면 대상 변경을 피하고 무엇을 했을지 보고하려 하는지(체크 모드/드라이 런)를 제어하는 불리언이에요.

collections

모듈, 플러그인, 롤을 검색할 컬렉션 네임스페이스 목록이에요.

참고: 롤 내부의 태스크는 play에서 collections 값을 상속받지 않아요. 롤이 컬렉션 목록을 검색하게 하려면 롤 안 meta/main.yml에서 collections 키워드를 사용하세요.

connection

태스크가 대상에서 실행할 때 사용하는 연결 플러그인을 바꿀 수 있어요.

debugger

태스크 결과의 상태에 따라 태스크 디버깅을 활성화해요.

delay

재시도 사이에 지연할 초 수예요. 이 설정은 until과 함께 쓸 때만 사용돼요.

delegate_facts

팩트를 inventory_hostname 대신 위임된 호스트에 적용하게 해주는 불리언이에요.

delegate_to

대상(inventory_hostname) 대신 태스크를 실행할 호스트예요.

diff

태스크가 'diff' 정보를 반환할지 여부를 토글해요.

environment

실행 시 태스크에 제공될 환경 변수로 변환되는 딕셔너리예요. 모듈에서만 사용할 수 있어요.

failed_when

태스크의 일반적인 'failed' 상태를 덮어쓰는 조건 표현식이에요.

ignore_errors

태스크 실패를 무시하고 play를 계속할 수 있게 해주는 불리언이에요.

ignore_unreachable

호스트에 도달할 수 없어 발생한 태스크 실패를 무시하고 play를 계속하게 해주는 불리언이에요.

local_action

action과 같지만 delegate_to: localhost를 암시해요.

loop

태스크가 반복할 목록을 받아 각 목록 요소를 item 변수에 저장해요(loop_control로 구성 가능).

loop_control

여기에 있는 여러 키로 태스크의 루프 동작을 수정/설정할 수 있어요. 'Adding controls to loops' 문서를 참고하세요.

module_defaults

모듈의 기본 매개변수 값을 지정해요.

name

식별자예요.

no_log

정보 노출을 제어하는 불리언이에요.

notify

태스크가 'changed=True' 상태를 반환할 때 알릴 핸들러 목록이에요.

poll

async 태스크의 폴링 간격(초)을 설정해요(기본 10초).

port

연결에 사용되는 기본 포트를 덮어쓰는 데 사용돼요.

register

태스크 상태와 모듈 반환 데이터를 담을 변수의 이름이에요.

remote_user

연결 플러그인을 통해 대상에 로그인하는 데 사용하는 사용자예요.

retries

until 루프에서 포기하기 전 재시도 횟수예요. 이 설정은 until과 함께 쓸 때만 사용돼요.

run_once

호스트 루프를 우회하고 결과·팩트를 같은 배치의 모든 활성 호스트에 적용하게 하는 불리언이에요.

tags

태스크나 포함된 태스크에 적용되는 태그로, 커맨드라인에서 하위 집합을 선택하게 해줘요.

throttle

태스크·블록·플레이북 레벨에서 동시 태스크 실행 수를 제한해요.

timeout

태스크 액션이 실행될 시간 제한이에요. 초과하면 Ansible이 프로세스를 중단해요.

until

이 키워드는 여기에 제공된 조건이 충족되거나 retries 한도에 도달할 때까지 계속되는 'retries 루프'를 암시해요.

vars

변수의 딕셔너리/맵이에요.

when

조건 표현식으로, 태스크의 반복이 실행될지 여부를 결정해요.

with_<lookup_plugin>

loop와 같지만 아이템 목록을 생성하기 위해 어떤 lookup 플러그인의 출력을 자동으로 추가해요.

더 알아보기 (Learn more)

• 키워드의 상대적 우선순위는 'Ansible 동작 제어하기: 우선순위 규칙' 문서를 확인해요.
• 플레이북 문법과 구조는 플레이북 다루기 문서를 참고해요.