Package: vault-anyconfig
VaultAnyconfigExtends theHVAC Hashicorp Vault Clientwith the load and dump functionality fromanyconfig. This allows automatic mixing in of secrets from Vault, allowing you to store a configuration
file with all details populated save for secrets, and then access Hashicorp Vault to load the secrets into the in-memory dictionary.Supported Secret EnginesCurrently vault-anyconfigonlysupports version 1 and 2 of the key value store.kv2 Limitationsvault-anyconfigonlywill read the latest version of a secret to maintain simplicity in the configuration fileyou must adddataafter the mountpoint for a kv2 secret, e.g.secret/data/example-secretdue to limitations in the HVAC clientFiles and FormattingThere are three configuration files (which can also be provided as strings), which can be stored in one, two or three files total as long as they are correctly written.Examples in this section will be in JSON, but any file format supported by anyconfig can be used.Vault ConfigurationThis configures the connection to the Vault, and must contain at least one member (usually the url parameter). If this section is not provided or is
left empty, then the Vault instance willnotbe configured, and instead only the anyconfig functionality will be used.The section must be namedvault_config, and can contain any of the parameters valid for initializing anHVAC client.Example{"vault_config":{"url":"https://vault.acme.com:8200"}}Vault AuthenticationThis provides authentication for use with theauto_authmethod, and must be namedvault_creds. It should contain a member namedauth_methodwhich should correspond with one of the auth method fromthe HVAC Client(without the "auth_" prefix), e.g.approle. The remaining members
should match the parameters for the specified auth method.Example{"vault_creds":{"role_id":"sample-role-id","secret_id":"sample-secret-id","auth_method":"approle"}}Main ConfigurationThe main configuration should consist of the configuration sections you needwithoutthe secrets included (unless passthrough mode is desired)
and a section namedvault_secrets. In thevault_secretssection, the keys are dot separated paths for the keys to insert into your configuration,
and the values are the path to the secret in Vault. Please see thevault_secretsusage section for the different ways to specify secrets.Additionaly, avault_filessection is included to retrieve files from Vault and write them to disk. This is discouraged (minimizing the time that
secrets are persisted should be prefered), but included for use with legacy applications which require a file path for secrets (e.g. TLS certificates).Raw Config Example{"website":{"host":"http://acme.com","site-name":"Great Products for Coyotes","tls-key":"/etc/web/acme.com.key","tls-cert":"/etc/web/acme.com.crt"},"vault_secrets":{"website.db_user":"secret/mysql/customer.user","website.db_pwd":"secret/mysql/customer.password"},"vault_files":{"website.tls-key":"secret/website/proxy.key","website.tls-cert":"secret/website/proxy.cert"}}Resulting Dictionary Example:{"website":{"host":"http://acme.com","site-name":"great products","tls-key":"/var/acme/acme.com.key","tls-cert":"/var/acme/acme.com.crt","db_user":"customer","db_pwd":"customer-password"},"vault_files":{"website.tls-key":"secret/website/proxy.key","website.tls-cert":"secret/website/proxy.cert"}}vault_secrets UsageAvault_secretsentry must have aconfig keyand asecret path. Theconfig_keyis a dot separated path to the configuration item that should
be added or updated. Thesecret_pathis the path where the secret resides in Vault. As an example:{"website":{},"vault_secrets":{"website.db_user":"secret/mysql/customer"}}Invault_secrets,website.db_useris theconfig_keyandsecret/mysql/customeris thesecret_path. The key used on thesecret_pathin Vault
will bedb_user.By default, the final portional of theconfig keywill be used as the key to the secret within Vault. However, it is possible to add a unique key
with a dot separator on thesecret_path. By way of example:{"website":{},"vault_secrets":{"website.db_user":"secret/mysql/customer.user"}}This example takes the value nameduserfrom themysql/customersecret and maps it onto the thedb_userkey of thewebsiteportion.
This enables drawing from the same secret across different configurations without forcing all of theconfig_keynames to be the same. For example,
if a cron job also required theuservalue frommysql/customer.userbut its configuration named ituser, you might end up with a configuration
file that looks like:{"website":{},"vault_secrets":{"mailer_cron.user":"secret/mysql/customer.user"}}Key-Value Store V2 Limitation: You must includedataafter the mountpoint, for example,secret/mysql/customershould besecret/data/mysql/customerwhen using V2.vault_files UsageNoteWhere ever possible, prefer to handle secrets as strings and use them only in memory. Only use this mode when configuring for applications
that require the secret to be provided as a file (a common requirement for a TLS keyfile).NoteUnlikevault_secretsthevault_filessection is retained in the dictionary returned by vault_anyconfig, in order to retain the mapping
when writing the final configuration to file (e.g. in the CLI).Warning!Thevault_filesfunctionality expects that it is being run as the user of the application, and must have appropriate permissions to
the files and location where files are to be stored.Warning!vault_fileswill happily overwrite your files, and mantains no backups.Warning!If the file location changes, it will not be deleted! Use responsibly.There are two major ways to use thevault_filessection. The first is to specify a file location directly, and the secret as the path.
For example:{"vault_files":{"/var/acme/acme.com.crt":"secret/website/proxy.key"}}The second method is to reference a key in the configuration. This avoids duplication of the file path in multiple parts of the configuration.{"website":{"tls-key":"/etc/web/acme.com.key","tls-cert":"/etc/web/acme.com.crt",},"vault_files":{"website.tls-key":"secret/website/proxy.key","website.tls-cert":"secret/website/proxy.cert"}}By default,secret_pathusesfileas the key within the Vault secret. However, thesecret_pathcan use the same dot notation used invault_secretsto specify the key, e.g.secret/acme/secret-key.keyWarning!Thesecret_pathstring can only use a dot (.) if separating the path from the key. Extra dots will cause vault_anyconfig to throw an
error.Key-Value Store V2 Limitation: You must includedataafter the mountpoint, for example,secret/website/proxyshould besecret/data/website/proxywhen using V2.Guidance for Configuration FilesAlthough all three files can be combined into a single file, it is recommend that you separate out thevault_credsandvault_configsections into
their own file(s) and use restrictive permissions on them, e.g.400, since the secrets required to access Vault must be present in these files.UsageInitializationVaultAnyconfig can be initalized in three ways (for two different modes):From a vault configuration file (see files and formatting)By specifying the parameters used in initializing anHVAC client.By providing no parameters (or a configuration file with an emptyvault_configsection) in which case it is in passthrough mode, where secrets arenotloaded from Vault.Authentication With VaultYou can useauto_authby providing a file as explained in the files and formatting section, or you can directly use the auth methods fromthe HVAC Client. If passthrough mode is set,auto_authwill always return
true, but the HVAC client methods will fail, so it is recommended to useauto_authwhere possible.Loading/Saving Files with Keys InsertedSimply call theload,loads,dumpordumpsmethods as need. Invocation is the same as for directly calling theanyconfig methods.Changelog0.0.1-dev (2019-04-05)First release on PyPI.