community.sops.load_vars module – Load SOPS-encrypted variables from files, dynamically within a task

Note

This module is part of the community.sops collection (version 2.0.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.sops. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.sops.load_vars.

New in community.sops 0.1.0

Synopsis

  • Loads SOPS-encrypted YAML/JSON variables dynamically from a file during task runtime.

  • To assign included variables to a different host than inventory_hostname, use delegate_to and set delegate_facts=true.

Note

This module has a corresponding action plugin.

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter

Comments

age_key

string

added in community.sops 1.4.0

One or more age private keys that can be used to decrypt encrypted files.

Will be set as the SOPS_AGE_KEY environment variable when calling SOPS.

Requires SOPS 3.7.1+.

age_keyfile

path

added in community.sops 1.4.0

The file containing the age private keys that SOPS can use to decrypt encrypted files.

Will be set as the SOPS_AGE_KEY_FILE environment variable when calling SOPS.

By default, SOPS looks for sops/age/keys.txt inside your user configuration directory.

Requires SOPS 3.7.0+.

aws_access_key_id

string

added in community.sops 1.0.0

The AWS access key ID to use for requests to AWS.

Sets the environment variable AWS_ACCESS_KEY_ID for the SOPS call.

aws_profile

string

added in community.sops 1.0.0

The AWS profile to use for requests to AWS.

This corresponds to the SOPS --aws-profile option.

aws_secret_access_key

string

added in community.sops 1.0.0

The AWS secret access key to use for requests to AWS.

Sets the environment variable AWS_SECRET_ACCESS_KEY for the SOPS call.

aws_session_token

string

added in community.sops 1.0.0

The AWS session token to use for requests to AWS.

Sets the environment variable AWS_SESSION_TOKEN for the SOPS call.

config_path

path

added in community.sops 1.0.0

Path to the SOPS configuration file.

If not set, SOPS will recursively search for the config file starting at the file that is encrypted or decrypted.

This corresponds to the SOPS --config option.

enable_local_keyservice

boolean

added in community.sops 1.0.0

Tell SOPS to use local key service.

This corresponds to the SOPS --enable-local-keyservice option.

Choices:

  • false ← (default)

  • true

expressions

string

This option controls how Jinja2 expressions in values in the loaded file are handled.

If set to ignore, expressions will not be evaluated, but treated as regular strings.

If set to evaluate-on-load, expressions will be evaluated on execution of this module, in other words, when the file is loaded.

Unfortunately, there is no way for non-core modules to handle expressions “unsafe”, in other words, evaluate them only on use. This can only achieved by ansible.builtin.include_vars, which unfortunately cannot handle SOPS-encrypted files.

Choices:

  • "ignore" ← (default)

  • "evaluate-on-load"

file

path

The file name from which variables should be loaded.

If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook.

keyservice

list / elements=string

added in community.sops 1.0.0

Specify key services to use next to the local one.

A key service must be specified in the form protocol://address, for example tcp://myserver.com:5000.

This corresponds to the SOPS --keyservice option.

name

string

The name of a variable into which assign the included vars.

If omitted (null) they will be made top level vars.

sops_binary

path

added in community.sops 1.0.0

Path to the SOPS binary.

By default uses sops.

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

This action runs completely on the controller.

Supports being used with the async keyword.

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: N/A

This action does not modify state.

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

facts

Support: full

Action returns an ansible_facts dictionary that will update existing host facts.

See Also

See also

ansible.builtin.set_fact

Set host variable(s) and fact(s).

ansible.builtin.include_vars

Load variables from files, dynamically within a task.

Controlling where tasks run: delegation and local actions

More information related to task delegation.

community.sops.sops lookup plugin

The sops lookup can be used decrypt SOPS-encrypted files.

community.sops.decrypt filter plugin

The decrypt filter can be used to descrypt SOPS-encrypted in-memory data.

community.sops.sops vars plugin

The sops vars plugin can be used to load SOPS-encrypted host or group variables.

Examples

- name: Include variables of stuff.sops.yaml into the 'stuff' variable
  community.sops.load_vars:
    file: stuff.sops.yaml
    name: stuff
    expressions: evaluate-on-load # interpret Jinja2 expressions in stuf.sops.yaml on load-time!

- name: Conditionally decide to load in variables into 'plans' when x is 0, otherwise do not
  community.sops.load_vars:
    file: contingency_plan.sops.yaml
    name: plans
    expressions: ignore # do not interpret possible Jinja2 expressions
  when: x == 0

- name: Load variables into the global namespace
  community.sops.load_vars:
    file: contingency_plan.sops.yaml

Return Values

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

Key

Description

ansible_included_var_files

list / elements=string

A list of files that were successfully included.

Returned: success

Sample: ["/path/to/file.sops.yaml"]

Authors

  • Felix Fontein (@felixfontein)