From 65e96f84813173830e28302fe849790078d07e11 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 28 Dec 2024 15:34:15 +0100 Subject: [PATCH] Reformat documentation with 'andebox yaml-doc'. (#216) --- plugins/doc_fragments/attributes.py | 40 +++--- plugins/doc_fragments/sops.py | 145 +++++++++++---------- plugins/filter/_latest_version.py | 25 ++-- plugins/filter/decrypt.py | 135 ++++++++++---------- plugins/lookup/sops.py | 173 +++++++++++++------------ plugins/modules/load_vars.py | 38 +++--- plugins/modules/sops_encrypt.py | 11 +- plugins/vars/sops.py | 189 ++++++++++++++-------------- 8 files changed, 369 insertions(+), 387 deletions(-) diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py index 72298504..d55c51b3 100644 --- a/plugins/doc_fragments/attributes.py +++ b/plugins/doc_fragments/attributes.py @@ -11,14 +11,14 @@ class ModuleDocFragment(object): # Standard documentation fragment - DOCUMENTATION = r''' + DOCUMENTATION = r""" options: {} attributes: - check_mode: - description: Can run in C(check_mode) and return changed status prediction without modifying target. - diff_mode: - description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode. -''' + check_mode: + description: Can run in C(check_mode) and return changed status prediction without modifying target. + diff_mode: + description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode. +""" # Should be used together with the standard fragment INFO_MODULE = r''' @@ -34,12 +34,12 @@ class ModuleDocFragment(object): - This action does not modify state. ''' - FACTS = r''' + FACTS = r""" options: {} attributes: - facts: - description: Action returns an C(ansible_facts) dictionary that will update existing host facts. -''' + facts: + description: Action returns an C(ansible_facts) dictionary that will update existing host facts. +""" # Should be used together with the standard fragment and the FACTS fragment FACTS_MODULE = r''' @@ -57,18 +57,18 @@ class ModuleDocFragment(object): support: full ''' - FILES = r''' + FILES = r""" options: {} attributes: - safe_file_operations: - description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption. -''' + safe_file_operations: + description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption. +""" - FLOW = r''' + FLOW = r""" options: {} attributes: - action: - description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller. - async: - description: Supports being used with the C(async) keyword. -''' + action: + description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller. + async: + description: Supports being used with the C(async) keyword. +""" diff --git a/plugins/doc_fragments/sops.py b/plugins/doc_fragments/sops.py index fba4909e..3e5176c1 100644 --- a/plugins/doc_fragments/sops.py +++ b/plugins/doc_fragments/sops.py @@ -9,83 +9,78 @@ class ModuleDocFragment(object): - DOCUMENTATION = r''' + DOCUMENTATION = r""" requirements: - - A binary executable C(sops) (U(https://github.com/getsops/sops)) must exist either in E(PATH) or configured as - O(sops_binary). + - A binary executable C(sops) (U(https://github.com/getsops/sops)) must exist either in E(PATH) or configured as O(sops_binary). options: - sops_binary: - description: - - Path to the SOPS binary. - - By default uses C(sops). - type: path - version_added: 1.0.0 - age_key: - description: - - One or more age private keys that can be used to decrypt encrypted files. - - Will be set as the E(SOPS_AGE_KEY) environment variable when calling SOPS. - - Requires SOPS 3.7.1+. - type: str - version_added: 1.4.0 - age_keyfile: - description: - - The file containing the age private keys that SOPS can use to decrypt - encrypted files. - - Will be set as the E(SOPS_AGE_KEY_FILE) environment variable when calling SOPS. - - By default, SOPS looks for C(sops/age/keys.txt) inside your user configuration - directory. - - Requires SOPS 3.7.0+. - type: path - version_added: 1.4.0 - aws_profile: - description: - - The AWS profile to use for requests to AWS. - - This corresponds to the SOPS C(--aws-profile) option. - type: str - version_added: 1.0.0 - aws_access_key_id: - description: - - The AWS access key ID to use for requests to AWS. - - Sets the environment variable E(AWS_ACCESS_KEY_ID) for the SOPS call. - type: str - version_added: 1.0.0 - aws_secret_access_key: - description: - - The AWS secret access key to use for requests to AWS. - - Sets the environment variable E(AWS_SECRET_ACCESS_KEY) for the SOPS call. - type: str - version_added: 1.0.0 - aws_session_token: - description: - - The AWS session token to use for requests to AWS. - - Sets the environment variable E(AWS_SESSION_TOKEN) for the SOPS call. - type: str - version_added: 1.0.0 - config_path: - description: - - 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 C(--config) option. - type: path - version_added: 1.0.0 - enable_local_keyservice: - description: - - Tell SOPS to use local key service. - - This corresponds to the SOPS C(--enable-local-keyservice) option. - type: bool - default: false - version_added: 1.0.0 - keyservice: - description: - - Specify key services to use next to the local one. - - A key service must be specified in the form C(protocol://address), for - example C(tcp://myserver.com:5000). - - This corresponds to the SOPS C(--keyservice) option. - type: list - elements: str - version_added: 1.0.0 -''' + sops_binary: + description: + - Path to the SOPS binary. + - By default uses C(sops). + type: path + version_added: 1.0.0 + age_key: + description: + - One or more age private keys that can be used to decrypt encrypted files. + - Will be set as the E(SOPS_AGE_KEY) environment variable when calling SOPS. + - Requires SOPS 3.7.1+. + type: str + version_added: 1.4.0 + age_keyfile: + description: + - The file containing the age private keys that SOPS can use to decrypt encrypted files. + - Will be set as the E(SOPS_AGE_KEY_FILE) environment variable when calling SOPS. + - By default, SOPS looks for C(sops/age/keys.txt) inside your user configuration directory. + - Requires SOPS 3.7.0+. + type: path + version_added: 1.4.0 + aws_profile: + description: + - The AWS profile to use for requests to AWS. + - This corresponds to the SOPS C(--aws-profile) option. + type: str + version_added: 1.0.0 + aws_access_key_id: + description: + - The AWS access key ID to use for requests to AWS. + - Sets the environment variable E(AWS_ACCESS_KEY_ID) for the SOPS call. + type: str + version_added: 1.0.0 + aws_secret_access_key: + description: + - The AWS secret access key to use for requests to AWS. + - Sets the environment variable E(AWS_SECRET_ACCESS_KEY) for the SOPS call. + type: str + version_added: 1.0.0 + aws_session_token: + description: + - The AWS session token to use for requests to AWS. + - Sets the environment variable E(AWS_SESSION_TOKEN) for the SOPS call. + type: str + version_added: 1.0.0 + config_path: + description: + - 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 C(--config) option. + type: path + version_added: 1.0.0 + enable_local_keyservice: + description: + - Tell SOPS to use local key service. + - This corresponds to the SOPS C(--enable-local-keyservice) option. + type: bool + default: false + version_added: 1.0.0 + keyservice: + description: + - Specify key services to use next to the local one. + - A key service must be specified in the form C(protocol://address), for example C(tcp://myserver.com:5000). + - This corresponds to the SOPS C(--keyservice) option. + type: list + elements: str + version_added: 1.0.0 +""" ANSIBLE_VARIABLES = r''' options: diff --git a/plugins/filter/_latest_version.py b/plugins/filter/_latest_version.py index d24b949a..08919941 100644 --- a/plugins/filter/_latest_version.py +++ b/plugins/filter/_latest_version.py @@ -7,16 +7,15 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" name: _latest_version short_description: "[INTERNAL] Get latest version from a list of versions" version_added: 1.4.0 author: - Felix Fontein (@felixfontein) description: - - B(This is an internal tool and must only be used from roles in this collection!) - If you use it from outside this collection, be warned that its behavior can change - and it can be removed at any time, even in bugfix releases! + - B(This is an internal tool and must only be used from roles in this collection!) If you use it from outside this collection, + be warned that its behavior can change and it can be removed at any time, even in bugfix releases! - Given a list of version numbers, returns the largest of them. options: _input: @@ -25,9 +24,9 @@ type: list elements: string required: true -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Print latest version ansible.builtin.debug: msg: "{{ versions | community.sops._latest_version }}" @@ -36,15 +35,15 @@ - 1.0.0 - 1.0.0rc1 - 1.1.0 -''' +""" -RETURN = ''' +RETURN = r""" _value: - description: - - The latest version from the input. - - Returns the empty string if the input was empty. - type: string -''' + description: + - The latest version from the input. + - Returns the empty string if the input was empty. + type: string +""" from ansible.module_utils.compat.version import LooseVersion diff --git a/plugins/filter/decrypt.py b/plugins/filter/decrypt.py index b06f441f..537087ff 100644 --- a/plugins/filter/decrypt.py +++ b/plugins/filter/decrypt.py @@ -7,77 +7,74 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" name: decrpyt short_description: Decrypt SOPS-encrypted data version_added: 1.1.0 author: - - Felix Fontein (@felixfontein) + - Felix Fontein (@felixfontein) description: - - Decrypt SOPS-encrypted data. - - Allows to decrypt data that has been provided by an arbitrary source. - - Note that due to Ansible lazy-evaluating expressions, it is better to use M(ansible.builtin.set_fact) - to store the result of an evaluation in a fact to avoid recomputing the value every time the expression - is used. + - Decrypt SOPS-encrypted data. + - Allows to decrypt data that has been provided by an arbitrary source. + - Note that due to Ansible lazy-evaluating expressions, it is better to use M(ansible.builtin.set_fact) to store the result + of an evaluation in a fact to avoid recomputing the value every time the expression is used. options: - _input: - description: - - The data to decrypt. - type: string - required: true - rstrip: - description: - - Whether to remove trailing newlines and spaces. - type: bool - default: true - input_type: - description: - - Tell SOPS how to interpret the encrypted data. - - There is no auto-detection since we do not have a filename. By default - SOPS is told to treat the input as YAML. If that is wrong, please set this - option to the correct value. - - The value V(ini) is available since community.sops 1.9.0. - type: str - choices: - - binary - - json - - yaml - - dotenv - - ini - default: yaml - output_type: - description: - - Tell SOPS how to interpret the decrypted file. - - Please note that the output is always text or bytes, depending on the value of O(decode_output). - To parse the resulting JSON or YAML, use corresponding filters such as P(ansible.builtin.from_json#filter) - and P(ansible.builtin.from_yaml#filter). - - The value V(ini) is available since community.sops 1.9.0. - type: str - choices: - - binary - - json - - yaml - - dotenv - - ini - default: yaml - decode_output: - description: - - Whether to decode the output to bytes. - - When O(output_type=binary), and the file is not known to contain UTF-8 encoded text, - this should better be set to V(false) to prevent mangling the data with UTF-8 decoding. - type: bool - default: true + _input: + description: + - The data to decrypt. + type: string + required: true + rstrip: + description: + - Whether to remove trailing newlines and spaces. + type: bool + default: true + input_type: + description: + - Tell SOPS how to interpret the encrypted data. + - There is no auto-detection since we do not have a filename. By default SOPS is told to treat the input as YAML. If + that is wrong, please set this option to the correct value. + - The value V(ini) is available since community.sops 1.9.0. + type: str + choices: + - binary + - json + - yaml + - dotenv + - ini + default: yaml + output_type: + description: + - Tell SOPS how to interpret the decrypted file. + - Please note that the output is always text or bytes, depending on the value of O(decode_output). To parse the resulting + JSON or YAML, use corresponding filters such as P(ansible.builtin.from_json#filter) and P(ansible.builtin.from_yaml#filter). + - The value V(ini) is available since community.sops 1.9.0. + type: str + choices: + - binary + - json + - yaml + - dotenv + - ini + default: yaml + decode_output: + description: + - Whether to decode the output to bytes. + - When O(output_type=binary), and the file is not known to contain UTF-8 encoded text, this should better be set to + V(false) to prevent mangling the data with UTF-8 decoding. + type: bool + default: true extends_documentation_fragment: - - community.sops.sops + - community.sops.sops seealso: - - plugin: community.sops.sops - plugin_type: lookup - - plugin: community.sops.sops - plugin_type: vars - - module: community.sops.load_vars -''' - -EXAMPLES = ''' + - plugin: community.sops.sops + plugin_type: lookup + - plugin: community.sops.sops + plugin_type: vars + - module: community.sops.load_vars +""" + +EXAMPLES = r""" - name: Decrypt file fetched from URL hosts: localhost gather_facts: false @@ -99,14 +96,14 @@ - name: Show decrypted data debug: msg: "{{ decrypted_data }}" -''' +""" -RETURN = ''' +RETURN = r""" _value: - description: - - Decrypted data as text (O(decode_output=true), default) or binary string (O(decode_output=false)). - type: string -''' + description: + - Decrypted data as text (O(decode_output=true), default) or binary string (O(decode_output=false)). + type: string +""" from ansible.errors import AnsibleFilterError from ansible.module_utils.common.text.converters import to_bytes, to_native diff --git a/plugins/lookup/sops.py b/plugins/lookup/sops.py index af367b51..c211cac4 100644 --- a/plugins/lookup/sops.py +++ b/plugins/lookup/sops.py @@ -7,90 +7,86 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = """ - name: sops - author: Edoardo Tenani (@endorama) - short_description: Read SOPS-encrypted file contents - version_added: '0.1.0' +DOCUMENTATION = r""" +name: sops +author: Edoardo Tenani (@endorama) +short_description: Read SOPS-encrypted file contents +version_added: '0.1.0' +description: + - This lookup returns the contents from a file on the Ansible controller's file system. + - This lookup requires the C(sops) executable to be available in the controller PATH. +options: + _terms: + description: Path(s) of files to read. + required: true + type: list + elements: str + rstrip: + description: Whether to remove trailing newlines and spaces. + type: bool + default: true + base64: description: - - This lookup returns the contents from a file on the Ansible controller's file system. - - This lookup requires the C(sops) executable to be available in the controller PATH. - options: - _terms: - description: Path(s) of files to read. - required: true - type: list - elements: str - rstrip: - description: Whether to remove trailing newlines and spaces. - type: bool - default: true - base64: - description: - - Base64-encodes the parsed result. - - Use this if you want to store binary data in Ansible variables. - type: bool - default: false - input_type: - description: - - Tell SOPS how to interpret the encrypted file. - - By default, SOPS will chose the input type from the file extension. - If it detects the wrong type for a file, this could result in decryption - failing. - - The value V(ini) is available since community.sops 1.9.0. - type: str - choices: - - binary - - json - - yaml - - dotenv - - ini - output_type: - description: - - Tell SOPS how to interpret the decrypted file. - - By default, SOPS will chose the output type from the file extension. - If it detects the wrong type for a file, this could result in decryption - failing. - - The value V(ini) is available since community.sops 1.9.0. - type: str - choices: - - binary - - json - - yaml - - dotenv - - ini - empty_on_not_exist: - description: - - When set to V(true), will not raise an error when a file cannot be found, - but return an empty string instead. - type: bool - default: false - extract: - description: - - Tell SOPS to extract a specific key from a JSON or YAML file. - - Expects a string with the same 'querystring' syntax as SOPS' C(--encrypt) - option, for example V(["somekey"][0]). - - B(Note:) Escape quotes appropriately. - type: str - version_added: 1.9.0 - extends_documentation_fragment: - - community.sops.sops - - community.sops.sops.ansible_variables - - community.sops.sops.ansible_env - - community.sops.sops.ansible_ini - notes: - - This lookup does not understand 'globbing' - use the P(ansible.builtin.fileglob#lookup) lookup instead. - seealso: - - plugin: community.sops.decrypt - plugin_type: filter - description: The decrypt filter can be used to descrypt SOPS-encrypted in-memory data. - - plugin: community.sops.sops - plugin_type: vars - description: The sops vars plugin can be used to load SOPS-encrypted host or group variables. - - module: community.sops.load_vars + - Base64-encodes the parsed result. + - Use this if you want to store binary data in Ansible variables. + type: bool + default: false + input_type: + description: + - Tell SOPS how to interpret the encrypted file. + - By default, SOPS will chose the input type from the file extension. If it detects the wrong type for a file, this + could result in decryption failing. + - The value V(ini) is available since community.sops 1.9.0. + type: str + choices: + - binary + - json + - yaml + - dotenv + - ini + output_type: + description: + - Tell SOPS how to interpret the decrypted file. + - By default, SOPS will chose the output type from the file extension. If it detects the wrong type for a file, this + could result in decryption failing. + - The value V(ini) is available since community.sops 1.9.0. + type: str + choices: + - binary + - json + - yaml + - dotenv + - ini + empty_on_not_exist: + description: + - When set to V(true), will not raise an error when a file cannot be found, but return an empty string instead. + type: bool + default: false + extract: + description: + - Tell SOPS to extract a specific key from a JSON or YAML file. + - Expects a string with the same 'querystring' syntax as SOPS' C(--encrypt) option, for example V(["somekey"][0]). + - B(Note:) Escape quotes appropriately. + type: str + version_added: 1.9.0 +extends_documentation_fragment: + - community.sops.sops + - community.sops.sops.ansible_variables + - community.sops.sops.ansible_env + - community.sops.sops.ansible_ini +notes: + - This lookup does not understand 'globbing' - use the P(ansible.builtin.fileglob#lookup) lookup instead. +seealso: + - plugin: community.sops.decrypt + plugin_type: filter + description: The decrypt filter can be used to descrypt SOPS-encrypted in-memory data. + - plugin: community.sops.sops + plugin_type: vars + description: The sops vars plugin can be used to load SOPS-encrypted host or group variables. + - module: community.sops.load_vars """ -EXAMPLES = """ +EXAMPLES = r""" - name: Output secrets to screen (BAD IDEA!) ansible.builtin.debug: msg: "Content: {{ lookup('community.sops.sops', item) }}" @@ -99,25 +95,24 @@ - name: Add SSH private key ansible.builtin.copy: - # Note that rstrip=false is necessary for some SSH versions to be able to use the key + # Note that rstrip=false is necessary for some SSH versions to be able to use the key content: "{{ lookup('community.sops.sops', user + '-id_rsa', rstrip=false) }}" dest: /home/{{ user }}/.ssh/id_rsa owner: "{{ user }}" group: "{{ user }}" mode: 0600 - no_log: true # avoid content to be written to log + no_log: true # avoid content to be written to log - name: The file file.json is a YAML file, which contains the encryption of binary data ansible.builtin.debug: msg: "Content: {{ lookup('community.sops.sops', 'file.json', input_type='yaml', output_type='binary') }}" - """ -RETURN = """ - _raw: - description: Decrypted file content. - type: list - elements: str +RETURN = r""" +_raw: + description: Decrypted file content. + type: list + elements: str """ import base64 diff --git a/plugins/modules/load_vars.py b/plugins/modules/load_vars.py index 312462eb..000ed721 100644 --- a/plugins/modules/load_vars.py +++ b/plugins/modules/load_vars.py @@ -9,16 +9,14 @@ __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: Felix Fontein (@felixfontein) module: load_vars short_description: Load SOPS-encrypted variables from files, dynamically within a task version_added: '0.1.0' description: - Loads SOPS-encrypted YAML/JSON variables dynamically from a file during task runtime. - - To assign included variables to a different host than C(inventory_hostname), - use C(delegate_to) and set C(delegate_facts=true). + - To assign included variables to a different host than C(inventory_hostname), use C(delegate_to) and set C(delegate_facts=true). options: file: description: @@ -34,16 +32,16 @@ description: - This option controls how Jinja2 expressions in values in the loaded file are handled. - If set to V(ignore), expressions will not be evaluated, but treated as regular strings. - - If set to V(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 M(ansible.builtin.include_vars), - which unfortunately cannot handle SOPS-encrypted files. + - If set to V(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 M(ansible.builtin.include_vars), which unfortunately cannot handle SOPS-encrypted + files. type: str default: ignore choices: - - ignore - - evaluate-on-load + - ignore + - evaluate-on-load extends_documentation_fragment: - community.sops.sops - community.sops.attributes @@ -78,37 +76,37 @@ - plugin: community.sops.sops plugin_type: vars description: The sops vars plugin can be used to load SOPS-encrypted host or group variables. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - 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! + 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 + 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 = r''' +RETURN = r""" ansible_facts: description: Variables that were included and their values. returned: success type: dict sample: {'variable': 'value'} ansible_included_var_files: - description: A list of files that were successfully included + description: A list of files that were successfully included. returned: success type: list elements: str - sample: [ /path/to/file.sops.yaml ] -''' + sample: [/path/to/file.sops.yaml] +""" diff --git a/plugins/modules/sops_encrypt.py b/plugins/modules/sops_encrypt.py index 9920b90e..bae98ac9 100644 --- a/plugins/modules/sops_encrypt.py +++ b/plugins/modules/sops_encrypt.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: Felix Fontein (@felixfontein) module: sops_encrypt short_description: Encrypt data with SOPS @@ -68,9 +67,9 @@ - plugin: community.sops.sops plugin_type: lookup description: The sops lookup can be used decrypt SOPS-encrypted files. -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Encrypt a secret text community.sops.sops_encrypt: path: text-data.sops @@ -85,9 +84,9 @@ community.sops.sops_encrypt: path: stuff.sops.yaml content_yaml: "{{ result }}" -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ import base64 diff --git a/plugins/vars/sops.py b/plugins/vars/sops.py index 389a1fbf..56515547 100644 --- a/plugins/vars/sops.py +++ b/plugins/vars/sops.py @@ -7,102 +7,101 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: sops - author: Edoardo Tenani (@endorama) - short_description: Loading SOPS-encrypted vars files - version_added: '0.1.0' +DOCUMENTATION = r""" +name: sops +author: Edoardo Tenani (@endorama) +short_description: Loading SOPS-encrypted vars files +version_added: '0.1.0' +description: + - Load encrypted YAML files into corresponding groups/hosts in C(group_vars/) and C(host_vars/) directories. + - Files are encrypted prior to reading, making this plugin an effective companion to P(ansible.builtin.host_group_vars#vars) + plugin. + - Files are restricted to V(.sops.yaml), V(.sops.yml), V(.sops.json) extensions, unless configured otherwise with O(valid_extensions). + - Hidden files are ignored. +options: + valid_extensions: + default: [".sops.yml", ".sops.yaml", ".sops.json"] description: - - Load encrypted YAML files into corresponding groups/hosts in C(group_vars/) and C(host_vars/) directories. - - Files are encrypted prior to reading, making this plugin an effective companion to P(ansible.builtin.host_group_vars#vars) plugin. - - Files are restricted to V(.sops.yaml), V(.sops.yml), V(.sops.json) extensions, unless configured otherwise - with O(valid_extensions). - - Hidden files are ignored. - options: - valid_extensions: - default: [".sops.yml", ".sops.yaml", ".sops.json"] - description: - - 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 O(handle_unencrypted_files) option. - type: list - elements: string - ini: - - key: valid_extensions - section: community.sops - version_added: 1.7.0 - env: - - name: ANSIBLE_VARS_SOPS_PLUGIN_VALID_EXTENSIONS - version_added: 1.7.0 - stage: - version_added: 0.2.0 - ini: - - key: vars_stage - section: community.sops - env: - - name: ANSIBLE_VARS_SOPS_PLUGIN_STAGE - cache: - description: - - 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 O(stage=inventory) has the same effect as setting O(cache=true): - the variables will be loaded only once (during inventory loading) and the vars plugin will not - be called for every task." - type: bool - default: true - version_added: 0.2.0 - ini: - - key: vars_cache - section: community.sops - env: - - name: ANSIBLE_VARS_SOPS_PLUGIN_CACHE - disable_vars_plugin_temporarily: - description: - - Temporarily disable this plugin. - - Useful if ansible-inventory is supposed to be run without decrypting secrets (in AWX for instance). - type: bool - default: false - version_added: 1.3.0 - env: - - name: SOPS_ANSIBLE_AWX_DISABLE_VARS_PLUGIN_TEMPORARILY - handle_unencrypted_files: - description: - - How to handle files that match the extensions in O(valid_extensions) that are not SOPS encrypted. - - The default value V(error) will produce an error. - - The value V(skip) will simply skip these files. This requires SOPS 3.9.0 or later. - - The value V(warn) will skip these files and emit a warning. This requires SOPS 3.9.0 or later. - - B(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. - type: string - choices: - - skip - - warn - - error - default: error - version_added: 1.8.0 - ini: - - key: handle_unencrypted_files - section: community.sops - env: - - name: ANSIBLE_VARS_SOPS_PLUGIN_HANDLE_UNENCRYPTED_FILES - extends_documentation_fragment: - - ansible.builtin.vars_plugin_staging - - community.sops.sops - - community.sops.sops.ansible_env - - community.sops.sops.ansible_ini - seealso: - - plugin: community.sops.sops - plugin_type: lookup - description: The sops lookup can be used decrypt SOPS-encrypted files. - - plugin: community.sops.decrypt - plugin_type: filter - description: The decrypt filter can be used to decrypt SOPS-encrypted in-memory data. - - module: community.sops.load_vars -''' + - 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 O(handle_unencrypted_files) option. + type: list + elements: string + ini: + - key: valid_extensions + section: community.sops + version_added: 1.7.0 + env: + - name: ANSIBLE_VARS_SOPS_PLUGIN_VALID_EXTENSIONS + version_added: 1.7.0 + stage: + version_added: 0.2.0 + ini: + - key: vars_stage + section: community.sops + env: + - name: ANSIBLE_VARS_SOPS_PLUGIN_STAGE + cache: + description: + - 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 O(stage=inventory) has the same effect as setting O(cache=true): the variables will be loaded only + once (during inventory loading) and the vars plugin will not be called for every task.' + type: bool + default: true + version_added: 0.2.0 + ini: + - key: vars_cache + section: community.sops + env: + - name: ANSIBLE_VARS_SOPS_PLUGIN_CACHE + disable_vars_plugin_temporarily: + description: + - Temporarily disable this plugin. + - Useful if ansible-inventory is supposed to be run without decrypting secrets (in AWX for instance). + type: bool + default: false + version_added: 1.3.0 + env: + - name: SOPS_ANSIBLE_AWX_DISABLE_VARS_PLUGIN_TEMPORARILY + handle_unencrypted_files: + description: + - How to handle files that match the extensions in O(valid_extensions) that are not SOPS encrypted. + - The default value V(error) will produce an error. + - The value V(skip) will simply skip these files. This requires SOPS 3.9.0 or later. + - The value V(warn) will skip these files and emit a warning. This requires SOPS 3.9.0 or later. + - B(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. + type: string + choices: + - skip + - warn + - error + default: error + version_added: 1.8.0 + ini: + - key: handle_unencrypted_files + section: community.sops + env: + - name: ANSIBLE_VARS_SOPS_PLUGIN_HANDLE_UNENCRYPTED_FILES +extends_documentation_fragment: + - ansible.builtin.vars_plugin_staging + - community.sops.sops + - community.sops.sops.ansible_env + - community.sops.sops.ansible_ini +seealso: + - plugin: community.sops.sops + plugin_type: lookup + description: The sops lookup can be used decrypt SOPS-encrypted files. + - plugin: community.sops.decrypt + plugin_type: filter + description: The decrypt filter can be used to decrypt SOPS-encrypted in-memory data. + - module: community.sops.load_vars +""" import os from ansible.errors import AnsibleParserError