플레이 인자 검증

플레이 인자 검증 (Play Argument Validation)

2.20 버전부터 플레이 키워드 validate_argspec로 **인자 검증(argument validation)**을 활성화할 수 있어요. 이 기능은 플레이 수준의 fact 수집 뒤에 validate_argument_spec 작업을 추가해요. 이 기능은 **기술 프리뷰(tech preview)**예요.

플레이 인자 검증은 크게 두 부분으로 이뤄져요. 하나는 validate_argspec 키워드이고, 다른 하나는 인자 명세(argument specifications)를 정의하는 .meta.yml 파일이에요. 플레이 인자 검증을 활성화하려면 validate_argspec 키워드에 값을 설정해 인자 명세 식별자를 정의하고(값을 True로 주면 플레이 이름을 쓰고, 문자열로 줄 수도 있어요), 플레이북과 같은 디렉터리의 <playbook_name>.meta.yml 파일에 유효한 인자 명세를 제공해야 해요.

출처: 문서

본문

create_webserver.yml 플레이북을 위해 setup webserver라는 유효한 빈 인자 명세를 제공하는 예시예요.

# create_webserver.meta.yml
argument_specs:
  setup webserver:
    options: {}

다음 플레이북에서는 두 플레이 모두 setup webserver 인자 명세에 맞춰 플레이 인자를 검증해요.

# create_webserver.yml
- name: setup webserver
  hosts: all
  validate_argspec: True

- hosts: all
  validate_argspec: setup webserver

명세 형식 (Specification Format)

플레이 인자 명세는 플레이북의 .meta.yml 파일 안 최상위 argument_specs 블록에 정의해야 해요. 모든 필드는 소문자예요.

  • argument-spec-name — 플레이 또는 인자 명세의 이름.
  • description — 여러 줄을 포함할 수 있는 플레이에 대한 설명. 단일 문자열이거나 문자열 목록일 수 있어요.
  • options — 플레이 인자의 딕셔너리를 정의하는 섹션. 각 플레이 옵션(인자)마다 다음을 포함할 수 있어요.

각 옵션에는 다음 필드를 써요.

  • option-name — 옵션/인자의 이름(필수).
  • description — 이 옵션이 무엇을 하는지에 대한 자세한 설명. 완전한 문장으로 작성해야 해요. 단일 문자열이거나 문자열 목록일 수 있어요.
  • type — 옵션의 데이터 타입. type에 허용되는 값은 Argument spec 문서를 참고하세요. 기본값은 str이에요. 옵션이 list 타입이면 elements를 지정해야 해요.
  • required — true일 때만 필요해요. 없으면 그 옵션은 필수가 아니에요.
  • choices — 옵션 값의 목록. 비어 있으면 없어야 해요.
  • elements — 타입이 list일 때 목록 요소의 데이터 타입을 지정해요.
  • options — 이 옵션이 dict 또는 dict 목록을 받으면 여기서 구조를 정의할 수 있어요.

샘플 명세

# create_webservers.meta.yml
description: Set up basic HTTPS-enabled webserver to serve content from a specified document root.
argument_specs:
  setup webserver:
    options:
      document_root:
        description: Path to the directory containing static web content to be served.
        type: str
        required: True
      port:
        description:
          - Port number on which the webserver listens for incoming HTTPS connections.
          - When unspecified, the port is 443.
        type: int
      ssl_cert_path:
        description: Path to the SSL certificate.
        type: str
        required: True
      ssl_key_path:
        description: Path to the private key corresponding to the SSL certificate.
        type: str
        required: True

위 명세는 document_root, ssl_cert_path, ssl_key_path를 필수로, port를 선택으로 정의해요. 플레이에서 이 인자들을 빼먹거나 타입을 어기면 검증 작업이 이를 잡아내요.

더 알아보기 (Learn more)

인자 명세(type, choices, elements 등)의 허용 값과 동작에 대한 자세한 내용은 Argument spec 문서를 참고하세요. 변수 전반과 우선순위는 playbooks_variables 문서에서 다뤄요.