Roles that refuse bad input · Ansible

A role’s interface, up to this point, has been a convention: keys in defaults/main.yml and a README that describes them. Nothing checks that a caller supplied what the role needs, and nothing checks that what they supplied makes sense. A missing required value surfaces as an undefined-variable error somewhere in the middle of the role, after three tasks have already changed the host.

meta/argument_specs.yml replaces the convention with something the run enforces. It is a declaration of the role’s inputs, and Ansible inserts a validation task at the start of the role that fails before any of the role’s own tasks execute.

The file

# roles/webapp/meta/argument_specs.yml
argument_specs:
  main:
    short_description: Configure and run the storefront application
    description:
      - Installs the application package, writes its configuration and
        manages the systemd unit.
    options:
      webapp_listen_port:
        type: int
        required: true
        description: TCP port the application binds.

      webapp_listen_address:
        type: str
        default: 127.0.0.1
        description: Address to bind. Loopback unless a proxy fronts it.

      webapp_mode:
        type: str
        default: balanced
        choices:
          - balanced
          - strict
        description: Operating profile.

      webapp_workers:
        type: int
        default: 4
        description: Worker processes.

      webapp_vhosts:
        type: list
        elements: dict
        default: []
        description: Virtual hosts to configure.
        options:
          name:
            type: str
            required: true
          document_root:
            type: path
            required: true

main is an entry point, and it corresponds to tasks/main.yml. A role with tasks/verify.yml invoked via tasks_from: verify can declare a verify: entry point with its own options, validated independently. Options nest: elements: dict plus a nested options: block validates the shape of every item in a list.

What it does at run time

The validation task appears in the run output with a generated name that includes the entry point and its short_description:

Read-only / Safea valid call— Executed against ansible-core 2.21.3. The validation task runs first, before any task from tasks/main.yml.

$ ansible-playbook -i inventory.ini site.yml

TASK [webapp : Validating arguments against arg spec 'main' - Configure and run the storefront application] ***
ok: [web-01.example.com]

TASK [webapp : report effective configuration] *********************************
ok: [web-01.example.com] => {
  "msg": "port=8080 mode=balanced"
}

And when the call is wrong, it fails before anything is touched — reporting every problem at once rather than the first one:

Read-only / Safean invalid call, with two independent errors— Executed. The role was invoked with no webapp_listen_port and with webapp_mode set to a value not in choices. Both are reported; no task from the role body ran.

$ ansible-playbook -i inventory.ini site-bad.yml

TASK [webapp : Validating arguments against arg spec 'main' - Configure and run the storefront application] ***
fatal: [web-01.example.com]: FAILED! => {
  "argument_errors": [
      "missing required arguments: webapp_listen_port",
      "value of webapp_mode must be one of: balanced, strict, got: aggressive"
  ],
  "changed": false,
  "msg": "Validation of arguments failed:\nmissing required arguments: webapp_listen_port\nvalue of webapp_mode must be one of: balanced, strict, got: aggressive",
  "validate_args_context": {
      "argument_spec_name": "main",
      "name": "webapp",
      "path": "/srv/automation/roles/webapp",
      "type": "role"
  }
}

PLAY RECAP *********************************************************************
web-01.example.com         : ok=0    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0

Reporting all errors together is the property that makes this worth the file. A caller fixing a role invocation gets the whole list in one run rather than discovering the next problem after each fix.

The two behaviours that catch people

A spec default does not define the variable

This is the one that produces a confusing failure, and it is worth stating flatly: default: in argument_specs.yml is used for validation and does not set the variable for the role to use. You still need the key in defaults/main.yml.

Verified by execution. A role whose spec declares webapp_mode with default: balanced, and whose defaults/main.yml does not declare it, passes validation and then fails on the undefined variable:

Read-only / Safevalidation passes, the role then fails on the same variable— Executed against 2.21.3. The spec declares default: balanced for webapp_mode. Validation is satisfied. The role body is not.

$ ansible-playbook -i inventory.ini site.yml

TASK [webapp : Validating arguments against arg spec 'main' - Configure and run the storefront application] ***
ok: [web-01.example.com]

TASK [webapp : report effective configuration] *********************************
fatal: [web-01.example.com]: FAILED! => {"msg": "Task failed: Finalization of task args for 'ansible.builtin.debug' failed: Error while resolving value for 'msg': 'webapp_mode' is undefined"}

PLAY RECAP *********************************************************************
web-01.example.com         : ok=1    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0

Adding webapp_mode: balanced to defaults/main.yml fixes it. The spec and the defaults file are two declarations of the same interface and they must agree — which is a real maintenance cost and the strongest argument against adding a spec to a role that does not need one.

Keep the two files in agreement, or the drift finds you

Every option with a default: in the spec should have the same key with the same value in defaults/main.yml. A quick audit:

grep -oE '^      [a-z_]+:' roles/webapp/meta/argument_specs.yml | tr -d ' :' | sort > /tmp/spec-keys
grep -oE '^[a-z_]+:' roles/webapp/defaults/main.yml | tr -d ':' | sort > /tmp/default-keys
comm -23 /tmp/spec-keys /tmp/default-keys

Anything printed is declared in the spec and absent from the defaults. That is fine for a required: true option — a caller must supply it — and a bug for anything with a default:.

Type validation accepts, it does not convert

The second surprise: an option declared type: int accepts a string that looks like an integer, and the role then receives the original string.

Read-only / Safean int option arriving as a str— Executed. The caller passed webapp_listen_port: '8080' as a quoted string. Validation passed. type_debug inside the role reports str.

$ ansible-playbook -i inventory.ini site.yml

TASK [webapp : Validating arguments against arg spec 'main' - Configure and run the storefront application] ***
ok: [web-01.example.com]

TASK [webapp : report effective configuration] *********************************
ok: [web-01.example.com] => {
  "msg": "port=8080 type=str mode=balanced"
}

So validation tells you the value could be an int. It does not hand your role an int. Any arithmetic or numeric comparison inside the role must still convert:

- name: refuse a privileged port without the capability
  ansible.builtin.assert:
    that: webapp_listen_port | int >= 1024
    fail_msg: >-
      webapp_listen_port is {{ webapp_listen_port }}; binding below 1024
      requires CAP_NET_BIND_SERVICE on the unit, which this role does not set.

Without the | int, a string port compared against an integer raises a templating error rather than a useful message — and it raises it only for the callers who happened to quote the value, which is the worst kind of intermittent.

Validating outside a role

ansible.builtin.validate_argument_spec runs the same validation machinery from an ordinary task, which is useful for a playbook that takes inputs without being a role:

- name: validate the inputs this playbook requires
  ansible.builtin.validate_argument_spec:
    argument_spec:
      target_environment:
        type: str
        required: true
        choices: [staging, production]
      batch_size:
        type: int
        default: 5

The module has an action plugin and full check-mode support, so it fires under --check as well as a real run. That matters: a dry run that skipped input validation would report a clean plan for a run that cannot start.

Under the hood

Role argument validation is not a special engine. When Ansible loads a role that has meta/argument_specs.yml, it synthesises an ordinary task — an ansible.builtin.validate_argument_spec call carrying the parsed spec — and prepends it to the role’s task list. The validate_args_context in the failure output is the evidence: it names the role, its path on disk, and which entry point was validated.

Two consequences follow from it being a normal task.

First, it is tagged always, so --tags selections that skip the rest of the role still run the validation. You cannot tag your way past it, which is correct — a partial run with invalid inputs is not safer than a full one.

Second, it obeys the same failure semantics as any other task. Wrap the role in a block with a rescue and the rescue catches a validation failure exactly as it would catch anything else, which is occasionally what you want for a role invoked in a loop over environments where one is expected to be unconfigured.

The spec itself is parsed by the same code that parses a module’s argument_spec, which is why the option keys — type, required, default, choices, elements, options — are the ones you already know from module documentation, and why the error messages read like module errors.

What happens if you add an argument spec to a role already in production?

Every existing caller is validated against it on the next run, and any that was relying on something the spec forbids now fails.

That is usually the point, but it means the change is not additive. The sequence that avoids an outage:

Write the spec with everything required: false and no choices:. Run the estate. Nothing can fail; you have added a no-op.
Add choices: for the options you believe are constrained. Run --check across the estate. Check mode still validates, so a caller passing an unlisted value fails the dry run rather than production.
Only then mark options required: true, and only for options every caller already supplies.

The step people skip is the second one, because --check feels like it is about tasks. Argument validation is one of the few things that is fully verified by a dry run, and using it here costs one pass over the estate and catches the entire problem.