hashi_vault - environment variable guidelines

[briantist]

SUMMARY

The hashi_vault lookup takes several parameters via environment variables, and recently, some via INI (ansible.cfg) as well.

Most of the original vars were intended to re-use vars that are commonly used in the vault CLI., like VAULT_ADDR and VAULT_TOKEN.

Along the way some newer ones have been added that aren't related to the vault CLI but are strictly for the plugin, but also adopted the VAULT_ prefix, and some others used ANSIBLE_VAULT_ as their prefix.

An additional consideration is that in Ansible, environment variables have higher precedence (are preferred) over INI values. We can think of this in terms of specificity; the INI value is defined "ansible-wide" (for your specific implementation), while the env var is defined per invocation so it should be considered more specific, especially given that the env vars defined for plugin parameters are specific to that Ansible plugin (usually denoted with the ANSIBLE_ prefix) and so have no use outside of that context.

The precedence issue becomes less clear when we take values that have meaning outside of ansible, like the VAULT_ vars used in the vault CLI.

I believe we should consider then that an env var with meaning outside of Ansible has a lower precedence (is less preferred) than an INI value defined in ansible.cfg, as in the context of Ansible, an INI value is a more specific value.

Additional background on the ANSIBLE_ prefix:

• https://meetbot.fedoraproject.org/ansible-meeting/2019-02-26/ansible_core_irc_public_meeting.2019-02-26-19.02.html
• https://github.com/ansible/ansible/issues/52967#issuecomment-467588878

PROPOSAL

This proposal aims to provide guidelines on how we name environment variables, and how we handle their precedence.

Ansible-only vars

This applies to a parameter to the plugin that will not inherit any existing vault CLI env var.

1. The variable should use the prefix ANSIBLE_HASHI_VAULT_. This name is on the long side, however it keeps to the pattern of starting with ANSIBLE_. Also considered (and even used before this proposal) was ANSIBLE_VAULT_ however this may cause confusion with Ansible Vault (unrelated to this plugin).
2. This variable should follow existing Ansible precedence rules, and be specified in the env: key in the plugin's argspec, so that the standard plugin loader can take care of it.

Even if there is no specific existing VAULT_ env var, we don't know whether one will be introduced in the future, and so don't want to use these names.

Variables used outside of Ansible

This applies to env vars that have a meaning outside of Ansible, but whose value we want to use. Examples include the vault CLI env vars, but also the $HOME variable as used for a default for the token_path parameter.

1. As far as naming, we of course have no choice but to use the name as it exists.
2. We should NOT specify this value in the argspec. Instead, we must write code that retrieves this value in the case that the parameter was not already set via any other means. This enforces lowest precedence.
3. Consider adding an additional ANSIBLE_HASHI_VAULT_ var (following guidelines above to add it to the argspec) so that the value can be overridden for specific Ansible invocations, overriding both the non-Ansible var and INI value.

RELATED ISSUES & PRs

See this project: https://github.com/ansible-collections/community.hashi_vault/projects/1

Not all will be listed here, but want to point some specific examples.

• ansible-collections/community.general#373 / ansible-collections/community.general#902 -- here the issue of specifying $HOME in the argspec was revealed to make the INI value practically unusable, since $HOME is basically always defined already. The solution was to load its value in code only when the value wasn't populated by any other method. In this PR I also added Ansible-specific env vars for token_path and token_file, but used a VAULT_ prefix which I now realize was an anti-pattern (I expect to introduce a PR to correct that).
• ansible-collections/community.hashi_vault#8 -- here I'm realizing that given VAULT_ADDR is probably the most common way of setting the address for a vault server, it becomes more difficult to use an INI value to enforce a specific server's usage in Ansible, without overriding the env var on every invocation. I propose a new Ansible-specific var and to load VAULT_ADDR in code as the least preferred source of the value.

COMPONENT NAME

hashi_vault.py