{"id":31904205,"url":"https://github.com/cloudfoundry-community/vault-boshrelease","last_synced_at":"2025-10-23T20:05:05.639Z","repository":{"id":34110914,"uuid":"37940286","full_name":"cloudfoundry-community/vault-boshrelease","owner":"cloudfoundry-community","description":null,"archived":false,"fork":false,"pushed_at":"2022-11-30T20:05:38.000Z","size":14362,"stargazers_count":28,"open_issues_count":2,"forks_count":36,"subscribers_count":39,"default_branch":"master","last_synced_at":"2024-04-14T22:47:44.241Z","etag":null,"topics":["bosh","bosh-lite","bosh-release","cloud-foundry","vault"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/cloudfoundry-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-23T19:31:59.000Z","updated_at":"2024-02-09T14:24:05.000Z","dependencies_parsed_at":"2023-01-15T04:41:27.326Z","dependency_job_id":null,"html_url":"https://github.com/cloudfoundry-community/vault-boshrelease","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/cloudfoundry-community/vault-boshrelease","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry-community%2Fvault-boshrelease","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry-community%2Fvault-boshrelease/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry-community%2Fvault-boshrelease/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry-community%2Fvault-boshrelease/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudfoundry-community","download_url":"https://codeload.github.com/cloudfoundry-community/vault-boshrelease/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry-community%2Fvault-boshrelease/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015342,"owners_count":26085686,"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-13T02:00:06.723Z","response_time":61,"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":["bosh","bosh-lite","bosh-release","cloud-foundry","vault"],"created_at":"2025-10-13T13:47:55.199Z","updated_at":"2025-10-13T13:48:02.312Z","avatar_url":"https://github.com/cloudfoundry-community.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"Vault - Secure Credentials Storage\n==================================\n\n**NOTE**: This BOSH release has a lot of configuration options,\nand is intended more for people who want to tinker with Vault and\nits various storage backends.  If you are looking for a\n**rock-solid** Vault deployment on BOSH, check out the [safe BOSH\nRelease](https://github.com/cloudfoundry-community/safe-boshrelease)\ninstead.\n\nQuestions? Pop in our [slack channel][slack]\n\nThis [BOSH][bosh] release packages the excellent [Vault][vault]\nsoftware from [Hashicorp][hashicorp], primarily for tinkering,\nexperimentation.\n\n  - Release engineering and testing by [Stark \u0026 Wayne Concourse][ci]\n  - All PRs will be run through CI/CD (see `testflight-pr` job)\n\n## Usage\n\nTo use this BOSH release:\n\n```\n$ export BOSH_ENVIRONMENT=\u003calias\u003e\n$ export BOSH_DEPLOYMENT=vault\n\n$ git clone https://github.com/cloudfoundry-community/vault-boshrelease.git\n$ cd vault-boshrelease\n$ bosh deploy manifests/vault.yml --vars-store tmp/creds.yml\n```\n\nIf your BOSH has Credhub/Config Server, then you do not need\n`--vars-store`. Rather certificates/credentials will be generated\nand stored within Credhub. Subsequent instructions below will\ncontinue to use `--vars-store` examples.\n\nRun `bosh instances` to get the IP address for one of your Vault\ninstances:\n\n```\n$ bosh instances\n\nInstance                                    Process State  AZ  IPs\nvault/259fbc67-0a0f-4714-a122-f3370ffd5bd6  running        z3  10.244.0.187\nvault/5a692a5e-260a-414f-9906-6e1ccbf66433  running        z2  10.244.0.186\nvault/9f34f839-92a0-4827-a713-c43a2430c0d9  running        z1  10.244.0.185\n```\n\nNext you need to initialize the Vault. Connect via port `:8200`:\n\n```\n$ export VAULT_ADDR=https://10.244.0.187:8200\n$ export VAULT_SKIP_VERIFY=true\n$ vault operator init\n```\n\nThis generates a root encryption key for encrypting all of the\nsecrets.  At this point, the vault is _sealed_, and you will need\nto unseal it three times, each time with a different key:\n\n```\n$ vault operator unseal\n$ vault operator unseal\n$ vault operator unseal\n```\n\nOnce unsealed, your Vault should be ready for authentication with\nyour _initial root token_:\n\n```\n$ vault login\n```\n\nNow, you can put secrets in the Vault, and read them back out (try\nany path with `secret/` prefix):\n\n```\n$ vault write secret/handshake knock=knock\n$ vault read secret/handshake\n```\n\nYou may want to look at [safe][safe], an alternative command-line\nutility for Vault that provides higher-level abstractions like\ntree-based listing, secret generation, secure terminal password\nentry, etc.\n\n## Configuration\n\n### Template Strings\n\nAs the base manifest shows, a full HCL configuration can be\nassigned to the `vault.config` property. If you're using Vault in\nHA mode (which is recommended) you'll probably need to set values\nlike `api_addr` and `cluster_address`.  The `vault.config`\nproperty supports the following template strings to make setting\nthese values easier:\n\n**`(ip)`**\n\nDuring deployment this value will be replaced with the IP address\nof the instance. This will not include the protocol or any port\ninformation. For example for an IP based configuration:\n\n```hcl\nstorage \"consul\" {\n  path = \"vault/\"\n  check_timeout = \"5s\"\n  max_parallel = \"128\"\n}\napi_addr = \"http://(ip):8200\"\ncluster_addr = \"https://(ip):8201\"\n```\n\n**`(index)`**\n\nDuring deployment this value will be replaced with the index of\nthe instance. This can be particularly useful for DNS\nconfiguration values. For example, if you were deploying 3\ninstances, this would ensure each one had a unique DNS value in\nits configuration::\n\n```hcl\nstorage \"consul\" {\n  path = \"vault/\"\n  check_timeout = \"5s\"\n  max_parallel = \"128\"\n}\napi_addr = \"http://vault-(index).yoursite.biz:8200\"\ncluster_addr = \"https://vault-(index).yoursite.biz:8201\"\n```\n### Certificate Management\n\nYour Vault configuration is likely going to require TLS. This\nrelease's `vault.tls` property can lets you provide these\ncertificates:\n\n```yaml\nproperties:\n  tls:\n    - name: \"my_tls_cert\"\n      cert: |\n        -----BEGIN CERTIFICATE-----\n        CertBlockAsRawText\n        -----END CERTIFICATE-----\n      key: ((or_use_a_variable))\n\n    - name: \"other_tls_cert\"\n      cert: ((other_tls_certificate_content))\n      key: ((other_tls_key_content))\n```\n\nThe above configuration will create the following files on the\nVault instance before starting Vault:\n\n  - `/var/vcap/jobs/vault/tls/my_tls_cert/cert.pem`\n  - `/var/vcap/jobs/vault/tls/my_tls_cert/key.pem`\n  - `/var/vcap/jobs/vault/tls/other_tls_cert/cert.pem`\n  - `/var/vcap/jobs/vault/tls/other_tls_cert/key.pem`\n\n### Management of Additional Configuration Files\n\nVault's configuration supports lots of cool features that sometimes require additional configuration files be present.\nAn example of this is GCP auto unsealing. To support these kinds of cases this Bosh release provides the \n`additional_config` property.\n\n```\nproperties:\n  vault:\n    additional_config:\n      - name: gcp.json\n        config: |\n          {\n            \"some\":\"valid_json\"\n          }\n```\n\nThe above configuration will create the file `/var/vcap/jobs/vault/config/gcp.json` on the Vault instance before \nstarting Vault.\n\n### Monit Script Configuration\n\nIn order to enable features like zero downtime redeploys this Bosh release\nbundles scripts that utilize the Vault CLI. Manifest properties are available to\nexplicitly set the value of the `VAULT_SKIP_VERIFY` and `VAULT_ADDR`\nenvironment variables in the context of these monit scripts:\n\n```yaml\n  properties:\n    vault:\n      skip_verify: false                      #default if absent\n      addr:        \"https://127.0.0.1:8200\"   #default if absent\n```\n\nPrior to 1.0.0 release, the `VAULT_SKIP_VERIFY` environment\nvariable is set if the vault address contains `https`, so\nconnecting to the vault server on 127.0.0.1 (during unseal) would\nnot throw an SSL exception. Since 1.0.0 release, the environmental\nvariable is no longer  set  by default. There are several possible\nways to address the situation.\n\n- If you have **only one** vault node, you can use\n  `properties.vault.addr` to set `VAULT_ADDR` environmental variable\n  according to your cert CN.\n\n- If you have more than one nodes, **and** can use SAN IP entry of\n  `127.0.0.1` in your certs, leave out `properties.vault.addr`\n  (using the default).\n\n- If you have more than one nodes, and can _NOT_ use SAN IP entry\n  of `127.0.0.1` in your certs, you need to specify\n  `vault.skip_verify`, and leave out `vault.addr`. This breaks the\n  [security model][security], though minor since the communication\n  is at the local host.\n\nZero Downtime Updates\n---------------------\n\nTo enable zero-downtime updates you must provide an auth token\nthat is authorized to perform `vault step-down`. Once you have\nunsealed vault you can set it up as follows:\n\n```\n$ cat \u003e step-down.hcl \u003c\u003cEOF\npath \"sys/step-down\" {\n  capabilities = [\"update\", \"sudo\"]\n}\nEOF\n\n$ vault policy write step-down ./step-down.hcl\nPolicy 'step-down' written.\n$ vault token create -policy=\"step-down\" -display-name=\"step-down\" -no-default-policy -orphan\nKey             Value\n---             -----\ntoken           STEP-DOWN-TOKEN\ntoken_accessor  cf37c98a-685a-1cf0-fc2e-4bd21a4a6be2\ntoken_duration  768h0m0s\ntoken_renewable true\ntoken_policies  [step-down]\n```\n\nThen add the token value to your deployment file under\n`properties.vault.update.step_down_token`. This will cause Vault\nto perform a controlled failover before updating each individual\nnode.\n\nOnce the update of a node has completed it will need to be\nunsealed. If you add your unseal keys under\n`properties.vault.update.unseal_keys` this will also be taken care\nof. This will make the entire update process truely zero-downtime\nie. when using a consul-agent to provide dns, the domain name\n`vault.service.consul` should always be pointing to a Vault that\nwill accept connections.\n\n```\n$ bosh deploy manifests/vault.yml --vars-store tmp/creds.yml \\\n  -o manifests/operators/step-down-token.yml \\\n  -v \"vault-step-down-token=STEP-DOWN-TOKEN\" \\\n  -v \"vault-unseal-keys=[UNSEAL1,UNSEAL2,UNSEAL3]\"\n```\n\n\nIt is highly recommended to run `vault rekey` after an update\nwhere the unseal keys were provided have taken place to not leave\nthe keys exposed in the manifest.\n\n**WARNING!!!** If you add the unseal keys to your manifest and do\nnot rekey once the deployment is done then it will be possible for\nanyone with access to the manifest to decrypt and see all secrets\nstored in vault.\n\nYou will provide three of the original unseal keys to `vault\nrekey`, so run it three times to generate new unseal keys:\n\n```\n$ vault operator rekey\n$ vault operator rekey\n$ vault operator rekey\n```\n\nSee [rekeying and rotating][rekey] (in the Vault documentation)\nfor additional instructions.\n\n[BOSH]:      https://bosh.io\n[vault]:     https://vaultproject.io\n[hashicorp]: https://hashicorp.com\n[slack]:     https://cloudfoundry.slack.com/messages/vault/\n[ci]:        https://ci.starkandwayne.com/teams/main/pipelines/vault-boshrelease\n[safe]:      https://github.com/starkandwayne/safe\n[rekey]:     https://www.vaultproject.io/guides/rekeying-and-rotating.html\n[security]:  https://www.vaultproject.io/docs/commands/index.html#vault_skip_verify\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfoundry-community%2Fvault-boshrelease","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudfoundry-community%2Fvault-boshrelease","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfoundry-community%2Fvault-boshrelease/lists"}