{"id":17180774,"url":"https://github.com/jsok/hiera-vault","last_synced_at":"2025-10-23T19:56:50.004Z","repository":{"id":33208277,"uuid":"36850981","full_name":"jsok/hiera-vault","owner":"jsok","description":"A Hiera backend to retrieve secrets from Hashicorp's Vault","archived":false,"fork":false,"pushed_at":"2022-02-03T05:57:05.000Z","size":37,"stargazers_count":102,"open_issues_count":13,"forks_count":22,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-10-23T01:54:32.057Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jsok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-04T05:54:06.000Z","updated_at":"2025-06-03T00:27:13.000Z","dependencies_parsed_at":"2022-08-31T08:25:09.895Z","dependency_job_id":null,"html_url":"https://github.com/jsok/hiera-vault","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/jsok/hiera-vault","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsok%2Fhiera-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsok%2Fhiera-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsok%2Fhiera-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsok%2Fhiera-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsok","download_url":"https://codeload.github.com/jsok/hiera-vault/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsok%2Fhiera-vault/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280684030,"owners_count":26372970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-23T02:00:06.710Z","response_time":142,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-15T00:31:35.302Z","updated_at":"2025-10-23T19:56:49.967Z","avatar_url":"https://github.com/jsok.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Gem Version Badge](https://img.shields.io/gem/v/hiera-vault.svg)](https://rubygems.org/gems/hiera-vault)\n[![Build Status](https://travis-ci.org/jsok/hiera-vault.svg?branch=master)](https://travis-ci.org/jsok/hiera-vault)\n\n# hiera-vault\nA Hiera backend to retrieve secrets from Hashicorp's Vault\n\n[Vault](https://vaultproject.io) secures, stores, and tightly controls access to tokens, passwords, certificates, API keys, and other secrets in modern computing. Vault handles leasing, key revocation, key rolling, and auditing. Vault presents a unified API to access multiple backends: HSMs, AWS IAM, SQL databases, raw key/value, and more.\n\n## Configuration\n\nYou should modify `hiera.yaml` as follows:\n\n    :backends:\n        - vault\n\n    :vault:\n        :addr: http://127.0.0.1:8200\n        :token: fake\n\nAlternatively (and recommended) you can specify your vault client configuration\nvia the same environment variables read by\n[vault-ruby](https://github.com/hashicorp/vault-ruby#usage), e.g.\n\n    VAULT_TOKEN=secret hiera -c hiera.yml foo\n\n\n## Lookups\n\n### Hash - default\n\nSince vault stores data in Key/Value pairs, this naturally lends itself to\nreturning a Hash on lookup.\nFor example:\n\n    vault write secret/foo value=bar other=baz\n\nThe hiera lookup for `foo` will return a Hash:\n\n    {\"value\"=\u003e\"bar\",\"other\"=\u003e\"baz\"}\n\n### Single Value - optional\n\nIf you use just a single field to store data, eg. \"value\" - you can request that just this is returned as a string, instead of a hash.\n\nTo do this, set:\n\n    :vault:\n        :default_field: value\n\nFor example:\n\n    vault write secret/foo value=bar other=baz\n\nThe hiera lookup for `foo` will return just \"bar\" as a string.\n\nIn case `foo` does not have the `value` field, a Hash is returned as normal.\nIn versions \u003c= 0.1.4 an error occurred.\n\n#### Default field behavior - optional\nWhen using `:default_field`, by default, additional fields are ignored, and\nif the field is not present, nil will be returned.\n\nTo only return the value of the default field if it is present and the only one, set:\n\n    :vault:\n        :default_field: value\n        :default_field_behavior: only\n\nThen, when `foo` contains more fields in addition to `value`, a Hash will be returned, just like with the default behaviour.\nAnd, in case `foo` does not contain the `value` field, a Hash with the actual fields will be returned, as if `:default_field`\nwas not specified.\n\n#### JSON parsing of single values - optional\nOnly applicable when `:default_field` is used.\nTo use JSON parsing, set, for example:\n\n    :vault:\n        :default_field: json_value\n        :default_field_parse: json\n\nThen, for example, when:\n\n    vault write secret/foo json_value='[\"bird\",\"spider\",\"fly\"]'\n\nthe hiera lookup for `foo` will return an array.\nWhen used in Array lookups (hiera_array), all occurences of `foo` will be merged into a single array.\n\nWhen, for example:\n\n    vault write secret/foo json_value='{\"user1\":\"pass1\",\"user2\":\"pass2\"}'\n\nthe hiera lookup for `foo` will return a hash. This is the same behavior as when:\n\n    vault write secret/foo user1='pass1' user2='pass2'\n\nBoth will result in a hash:\n\n    {\"user1\"=\u003e\"pass1\",\"user2\"=\u003e\"pass2\"}\n\n\nIn case the single field does not contain a parseable JSON string, the string will be returned as is.\nWhen used in Hash lookups, this will result in an error as normal.\n\n\n### Lookup type behavior\n\nIn case Array or Hash lookup is done, usual array or hash merging takes place based on the configured global `:merge_behavior` setting.\n\n\n## Backends and Mounts\n\nThe `mounts` config attribute should be used to customise which secret backends\nare interrogated in a hiera lookup.\n\nCurrently only the `generic` secret backend is supported.\nBy default the `secret/` mount is used if no mounts are specified.\n\nInspect your `vault mounts` output, e.g.:\n\n    \u003e vault mounts\n    Path        Type     Description\n    staging/    generic  generic secret storage for Staging data\n    production/ generic  generic secret storage for Production data\n    secret/     generic  generic secret storage\n    sys/        system   system endpoints used for control, policy and debugging\n\nFor the above scenario, you may wish to separate your per-environment secrets\ninto their own mount. This could be achieved with a configuration like:\n\n    :vault:\n        # ...\n        :mounts:\n            :generic:\n                - %{environment}\n                - secret\n\n\nSince version 0.2.0, the `:hierarchy` source paths from the hiera configuration are used\non top of each mount.\nThis makes the behavior of the vault backend the same as other backends.\nAdditionally, this enables usage of the third parameter to the hiera functions in puppet,\nthe so-called 'override' parameter.\nSee http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions\n\nExample: In case we have the following hiera config:\n\n    :backends:\n        - vault\n        - yaml\n\n    :hierarchy:\n      - \"nodes/%{::fqdn}\"\n      - \"hostclass/%{::hostclass}\"\n      - ...\n      - common\n\n    :yaml:\n      :datadir: \"/var/lib/hiera/%{::environment}/\"\n\n    :vault:\n        :addr: ...\n        :mounts:\n            :generic:\n                - \"%{::environment}\"\n                - secret\n\nEach hiera lookup will result in a lookup under each mount, honouring the configured `:hierarchy`. e.g.:\n\n    %{::environment}/nodes/%{::fqdn}\n    %{::environment}/hostclass/${::hostclass}\n    %{::environment}/...\n    %{environment}/common\n    secret/nodes/%{::fqdn}\n    secret/hostclass/%{::hostclass}\n    secret/...\n    secret/common\n\nWith the third argument to the hiera functions, the `override` parameter, the call\n\n    $val = hiera('thekey', 'thedefault', 'override_path/look_here_first')\n\nwill result in lookups through the following paths in vault:\n\n    %{::environment}/override_path/look_here_first\n    %{::environment}/nodes/%{::fqdn}\n    %{::environment}/hostclass/%{::hostclass}\n    %{::environment}/...\n    %{::environment}/common\n    secret/override_path/look_here_first\n    secret/nodes/%{::fqdn}\n    secret/hostclass/%{::hostclass}\n    secret/...\n    secret/common\n\n\n## SSL\n\nSSL can be configured with the following config variables:\n\n    :vault:\n        :ssl_pem_file: /path/to/pem\n        :ssl_ca_cert: /path/to/ca.crt\n        :ssl_ca_path: /path/to/ca/\n        :ssl_verify: false\n        :ssl_ciphers: \"MY:SSL:CIPHER:CONFIG\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsok%2Fhiera-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsok%2Fhiera-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsok%2Fhiera-vault/lists"}