ansible.builtin.validate_argument_spec module – Validate role argument specs.

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name validate_argument_spec even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.validate_argument_spec for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

New in ansible-core 2.11

Synopsis

  • This module validates role arguments with a defined argument specification.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

argument_spec

string / required

A dictionary like AnsibleModule argument_spec. See argument spec definition.

provided_arguments

string

A dictionary of the arguments that will be validated according to argument_spec.

Attributes

Attribute

Support

Description

action

Support: full

Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller

async

Support: none

Supports being used with the async keyword

become

Support: none

Is usable alongside become keywords

bypass_host_loop

Support: none

Forces a ‘global’ task that does not execute per host, this bypasses per host templating and serial, throttle and other loop considerations

Conditionals will work as if run_once is being used, variables used will be from the first available host

This action will not work normally outside of lockstep strategies

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

connection

Support: none

Uses the target’s configured connection information to execute code on it

delegation

Support: none

Can be used in conjunction with delegate_to and related keywords

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platforms: all

Target OS/families that can be operated against

Examples

- name: verify vars needed for this task file are present when included
  ansible.builtin.validate_argument_spec:
    argument_spec: '{{ required_data }}'
  vars:
    required_data:
      # unlike spec file, just put the options in directly
      stuff:
        description: stuff
        type: str
        choices: ['who', 'knows', 'what']
        default: what
      but:
        description: i guess we need one
        type: str
        required: true


- name: verify vars needed for this task file are present when included, with spec from a spec file
  ansible.builtin.validate_argument_spec:
    argument_spec: "{{ (lookup('ansible.builtin.file', 'myargspec.yml') | from_yaml )['specname']['options'] }}"


- name: verify vars needed for next include and not from inside it, also with params i'll only define there
  block:
    - ansible.builtin.validate_argument_spec:
        argument_spec: "{{ lookup('ansible.builtin.file', 'nakedoptions.yml') }}"
        provided_arguments:
          but: "that i can define on the include itself, like in it's `vars:` keyword"

    - name: the include itself
      vars:
        stuff: knows
        but: nobuts!

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

argument_errors

list / elements=string

A list of arg validation errors.

Returned: failure

Sample: ["error message 1", "error message 2"]

argument_spec_data

dictionary

A dict of the data from the ‘argument_spec’ arg.

Returned: failure

Sample: {"some_arg": {"type": "str"}, "some_other_arg": {"required": true, "type": "int"}}

validate_args_context

dictionary

A dict of info about where validate_args_spec was used

Returned: always

Sample: {"argument_spec_name": "main", "name": "my_role", "path": "/home/user/roles/my_role/", "type": "role"}

Authors

  • Ansible Core Team