ansible.builtin.register_secret filter – Register a value as a secret so it is masked in output

Note

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

New in ansible-core 2.22

Synopsis

  • Registers the input value with Ansible’s secret masker so that it is redacted from output that Ansible masks, such as display output, and module logging.

  • Registration is non-destructive; the value is returned unchanged so it can still be used by its true value, for example by registering it inline while assigning it to a variable.

  • Only string values can be registered, other types will raise an error.

Input

This describes the input of the filter, the value before | ansible.builtin.register_secret.

Parameter

Comments

Input

string / required

The value to register as a secret.

Keyword parameters

This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following example: input | ansible.builtin.register_secret(key1=value1, key2=value2, ...)

Parameter

Comments

validation_action

string

What to do if the secret is not a string or is empty after trimming surrounding whitespace.

Can be error to trigger an error, warn to display a warning, or ignore to silently ignore the validation and return the value without registration.

Choices:

  • "error" ← (default)

  • "warn"

  • "ignore"

See Also

See also

ansible.builtin.mask_secrets filter plugin

Redact registered secrets from a string.

Examples

# Register a value as a secret and assign it in one step; later uses of my_secret are masked in output.
my_secret: "{{ lookup('env', 'API_TOKEN') | register_secret }}"

Return Value

Key

Description

Return value

string

The input value, unchanged.

Returned: success

Authors

  • Ansible Core Team