community.sops.sops vars – Loading SOPS-encrypted vars files

Note

This vars plugin is part of the community.sops collection (version 1.8.2).

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 vars plugin, see Requirements for details.

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

New in community.sops 0.1.0

Synopsis

  • Load encrypted YAML files into corresponding groups/hosts in group_vars/ and host_vars/ directories.

  • Files are encrypted prior to reading, making this plugin an effective companion to ansible.builtin.host_group_vars plugin.

  • Files are restricted to .sops.yaml, .sops.yml, .sops.json extensions, unless configured otherwise with valid_extensions.

  • Hidden files are ignored.

Requirements

The below requirements are needed on the local controller node that executes this vars.

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.

Configuration:

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.

Configuration:

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.

Configuration:

  • INI entry:

    [community.sops]
aws_access_key_id = VALUE

    added in community.sops 1.2.0

  • Environment variable: ANSIBLE_SOPS_AWS_ACCESS_KEY_ID

    added in community.sops 1.2.0

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.

Configuration:

  • INI entry:

    [community.sops]
aws_profile = VALUE

    added in community.sops 1.2.0

  • Environment variable: ANSIBLE_SOPS_AWS_PROFILE

    added in community.sops 1.2.0

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.

Configuration:

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.

Configuration:

  • INI entry:

    [community.sops]
aws_session_token = VALUE

    added in community.sops 1.2.0

  • Environment variable: ANSIBLE_SOPS_AWS_SESSION_TOKEN

    added in community.sops 1.2.0

cache

boolean

added in community.sops 0.2.0

Whether to cache decrypted files or not.

If the cache is disabled, the files will be decrypted for almost every task. This is very slow!

Only disable caching if you modify the variable files during a playbook run and want the updated result to be available from the next task on.

Note that setting stage=inventory has the same effect as setting cache=true: the variables will be loaded only once (during inventory loading) and the vars plugin will not be called for every task.

Choices:

  • false

  • true ← (default)

Configuration:

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.

Configuration:

  • INI entry:

    [community.sops]
config_path = VALUE

    added in community.sops 1.2.0

  • Environment variable: ANSIBLE_SOPS_CONFIG_PATH

    added in community.sops 1.2.0

disable_vars_plugin_temporarily

boolean

added in community.sops 1.3.0

Temporarily disable this plugin.

Useful if ansible-inventory is supposed to be run without decrypting secrets (in AWX for instance).

Choices:

  • false ← (default)

  • true

Configuration:

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

Configuration:

  • INI entry:

    [community.sops]
enable_local_keyservice = false

    added in community.sops 1.2.0

  • Environment variable: ANSIBLE_SOPS_ENABLE_LOCAL_KEYSERVICE

    added in community.sops 1.2.0

handle_unencrypted_files

string

added in community.sops 1.8.0

How to handle files that match the extensions in valid_extensions that are not SOPS encrypted.

The default value error will produce an error.

The value skip will simply skip these files. This requires SOPS 3.9.0 or later.

The value warn will skip these files and emit a warning. This requires SOPS 3.9.0 or later.

Note that this will not help if the store SOPS uses cannot parse the file, for example because it is no valid JSON/YAML/… file despite its file extension. For extensions other than the default ones SOPS uses the binary store, which tries to parse the file as JSON.

Choices:

  • "skip"

  • "warn"

  • "error" ← (default)

Configuration:

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.

Configuration:

  • INI entry:

    [community.sops]
keyservice = VALUE

    added in community.sops 1.2.0

  • Environment variable: ANSIBLE_SOPS_KEYSERVICE

    added in community.sops 1.2.0

sops_binary

path

added in community.sops 1.0.0

Path to the SOPS binary.

By default uses sops.

Configuration:

  • INI entry:

    [community.sops]
binary = VALUE

    added in community.sops 1.2.0

  • Environment variable: ANSIBLE_SOPS_BINARY

    added in community.sops 1.2.0

stage

string

added in community.sops 0.2.0

Control when this vars plugin may be executed.

Setting this option to all will run the vars plugin after importing inventory and whenever it is demanded by a task.

Setting this option to task will only run the vars plugin whenever it is demanded by a task.

Setting this option to inventory will only run the vars plugin after parsing inventory.

If this option is omitted, the global RUN_VARS_PLUGINS configuration is used to determine when to execute the vars plugin.

Choices:

  • "all"

  • "task"

  • "inventory"

Configuration:

valid_extensions

list / elements=string

Check all of these extensions when looking for ‘variable’ files.

These files must be SOPS encrypted YAML or JSON files.

By default the plugin will produce errors when encountering files matching these extensions that are not SOPS encrypted. This behavior can be controlled with the handle_unencrypted_files option.

Default: [".sops.yml", ".sops.yaml", ".sops.json"]

Configuration:

  • INI entry:

    [community.sops]
valid_extensions = .sops.yml, .sops.yaml, .sops.json

    added in community.sops 1.7.0

  • Environment variable: ANSIBLE_VARS_SOPS_PLUGIN_VALID_EXTENSIONS

    added in community.sops 1.7.0

See Also

See also

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 decrypt SOPS-encrypted in-memory data.

community.sops.load_vars

Load SOPS-encrypted variables from files, dynamically within a task.

Authors

  • Edoardo Tenani (@endorama)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.