{"id":39037191,"url":"https://github.com/gstackio/gk-consul-boshrelease","last_synced_at":"2026-01-17T17:45:04.761Z","repository":{"id":94562021,"uuid":"219223849","full_name":"gstackio/gk-consul-boshrelease","owner":"gstackio","description":"A modern BOSH Release to deploy Hashicorp Consul clusters","archived":false,"fork":false,"pushed_at":"2024-08-10T23:37:05.000Z","size":136,"stargazers_count":0,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-11T00:33:31.402Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/gstackio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-02T22:51:16.000Z","updated_at":"2024-08-10T23:37:09.000Z","dependencies_parsed_at":"2024-06-04T21:36:53.373Z","dependency_job_id":"53c091e9-fe91-4b5a-a8fb-b6fda6636994","html_url":"https://github.com/gstackio/gk-consul-boshrelease","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/gstackio/gk-consul-boshrelease","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gstackio%2Fgk-consul-boshrelease","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gstackio%2Fgk-consul-boshrelease/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gstackio%2Fgk-consul-boshrelease/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gstackio%2Fgk-consul-boshrelease/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gstackio","download_url":"https://codeload.github.com/gstackio/gk-consul-boshrelease/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gstackio%2Fgk-consul-boshrelease/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28513975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2026-01-17T17:45:04.681Z","updated_at":"2026-01-17T17:45:04.742Z","avatar_url":"https://github.com/gstackio.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Consul BOSH Release\n\nThis is a modern BOSH Release for Consul, which is the fastest way to get up\nand running with a cluster of [Hashicorp Consul][hashicorp_consul] when you're\nusing [BOSH][bosh_io].\n\nYou are provided here with all the necessary binaries, configuration\ntemplates, and startup scripts for _converging_ Consul clusters (i.e.\ninstalling and updating over time) on Ubuntu Bionic nodes. Plus, we also\nprovide here a standard [deployment manifest][depl_manifest] to help you\ndeploy your first Consul cluster easily.\n\n[bosh_io]: https://bosh.io/\n[hashicorp_consul]: https://www.consul.io/\n[depl_manifest]: ./deploy/gk-consul.yml\n\n\n\n## Usage\n\nThis repository includes base manifests and operator files. They can be used\nfor initial deployments and subsequently used for updating your deployments.\n\n```\ngit clone https://github.com/gstackio/gk-consul-boshrelease.git\ncd gk-consul-boshrelease/deploy\n\nexport BOSH_ENVIRONMENT=\u003cbosh-alias\u003e\nexport BOSH_DEPLOYMENT=consul\nbosh deploy gk-consul.yml --vars-file=default-vars.yml\n```\n\nIf your BOSH does not have Credhub/Config Server (but it should), then\nremember to use `--vars-store` to allow generation of passwords and\ncertificates into a local YAML file.\n\n\n\n### Update\n\nWhen new versions of `gk-consul-boshrelease` are released, the\n`deploy/gk-consul.yml` file is updated. This means you can easily `git pull`\nand `bosh deploy` to upgrade.\n\n```\nexport BOSH_ENVIRONMENT=\u003cbosh-alias\u003e\nexport BOSH_DEPLOYMENT=consul\ncd gk-consul-boshrelease/deploy\ngit pull\nbosh deploy gk-consul.yml --vars-file=default-vars.yml\n```\n\n\n\n### Clustering\n\nHorizontal scaling works out of the box, with a mere updating of the\n[`instances:` property][instances_prop] in the deployment manifest. Scaling\nout to `5` nodes and then scaling in to `3` nodes again is a sandard test in\nthe CI pipeline.\n\n[instances_prop]: ./deploy/gk-consul.yml#L6\n\n\n\n## Design notes\n\nThis is a modern BOSH Release for Consul. This implies several design choices.\n\n- Use of [BPM][bpm_doc] is mandatory.\n\n- Recent Consul version: 1.6.1, where other BOSH Release stick to version 0.7.x\n  - v0.8.4 for [Consul BOSH Release][consul_boshrelease]\n  - v0.7.4 for [Consul Release][consul_release]\n  - v0.7.5 for a9s Consul BOSH Release (closed source)\n\n- About the start/drain/stop workflow:\n\n  - Contrarily to [Consul Release][consul_release] which implements a complex\n    and non-documented Confab Golang binary to manage the Consul agent state,\n    we don't run into such hard-to-maintain design.\n\n  - Just like the [Consul BOSH Release][consul_boshrelease], we chose to run\n    `consul leave` (ourselves, with `leave_on_terminate: false` to disallow\n    Consul to do it “auto-magically”), and adopt `rejoin_after_leave: true`.\n\n  - Contrarily to the [Consul BOSH Release][consul_boshrelease], we chose to\n    run `consul leave` at `drain` time, instead of doing it at `monit stop`\n    time. We do this in order not to introduce unnecessary delays at\n    `monit stop` time (which is discouraged), but at `drain` time (which is\n    recommended).\n\n  - Unfortunately, Consul has no “consul drain” command in order for the node\n    to drain any client connections and possibly step down from any cluster\n    leader role. Instead, we use `consul leave` which is the only available\n    command that is close enough from what we need when draining a node. For\n    connections to have the necessary time to be drained, we adopt a 10\n    seconds delay in the `drain` script (with `leave_drain_time: \"10s\"`).\n\n- About DNS-based service discovery\n\n  - We don't allow other co-located jobs to expose `/var/vcap/jobs/*/consul`\n    directories for pushing their own config about locally-checked service. On\n    the contrary, the [Consul BOSH Release][consul_boshrelease] adds such\n    directories as `-config-dir` arguments to the Consul agent. See also the\n    (now deprecated) [Redis-Consul BOSH Release][redis_consul_boshrelease].\n\n  - We don't implement serice definition similar to\n    [`consul.services`][consul_services], allowing to specify locally-checked\n    services. They are written to the ephemeral disk storage in\n    `/var/vcap/data/consul/services` and this directory is added as\n    `-config-dir` to the Consul agent invocation.\n\n  - We natively interface Consul with BOSH DNS. We do this because BOSH DNS\n    features have now been widely adopted in the BOSH community, and are the\n    recommended way to do robust and resilient service discovery. Thus, this\n    BOSH Release always registers Consul as a BOSH DNS handler. In this\n    design, BOSH DNS delegates DNS requests to Consul whenever the\n    Consul-reserved DNS domain (`.consul` by default) is queried.\n\n    - This is the opposite of [Consul BOSH Release][consul_boshrelease] design\n      where Consul is the primary DNS server (as overridden in\n      `/etc/resolv.conf`) and then recurse to external DNS servers for queries\n      unrelated to the Consul-reserved DNS domain.\n\n    - We don't run the Consul DNS service on port `53`. We always keep it on\n      the default `8600` port instead.\n\n    - We don't provide the\n      [`consul.resolvconf_override`][consul_resolvconf_override] feature to\n      force the local Consul agent as the primary DNS name server to use, in\n      `/etc/resolv.conf`.\n\n- We higly support and enforce TLS encryption, with `tls.enable` defaulting to\n  `true`, and mutual-TLS authentication with `tls.enforce_mutual_tls` also\n  defaulting to `true`. Plus, we actively support TLS CA certificate rotation\n  through the `tls.ca_bundle` property.\n\n- We also support enabling/disabling encryption with `encrypt_verify_incoming`\n  and `encrypt_verify_outgoing` through the 3-steps process described in\n  [Consul documentation][enable_encrypt_existing_cluster]. Note: we haven't\n  confirmed this yet, but disabling encryption temporarily might be the only\n  way to rotate the encryption key, as Consul doesn't support two keys at the\n  same time.\n\n- We use the recommended `8501` port for HTTPS API on Consul servers. The\n  older [Consul BOSH Release][consul_boshrelease] is re-using the HTTP port\n  `8500` for this, which might create incompatibilities with toolings.\n\n- We help the BOSH operator to set the `encrypt` key more easily. Instead of\n  requiring her/him to compute a Base-64 encoded 32-bytes encryption key with\n  `consul keygen` manually, we allow the BOSH operator to use a 50+\n  charaters-long Credhub-generated (or BOSH CLI-generated) password, and we\n  infer a 32-bytes binary key (taking care of not loosing entropy in the\n  process) that we automatocally encode as Base-64 in Consul config.\n\n[bpm_doc]: https://bosh.io/docs/bpm/bpm/\n[consul_boshrelease]: https://bosh.io/releases/github.com/cloudfoundry-community/consul-boshrelease\n[consul_release]: https://bosh.io/releases/github.com/cloudfoundry-incubator/consul-release\n[consul_services]: https://github.com/cloudfoundry-community/consul-boshrelease/blob/master/jobs/consul/spec#L72-L73\n[consul_resolvconf_override]: https://github.com/cloudfoundry-community/consul-boshrelease/blob/master/jobs/consul/spec#L36-L38\n[redis_consul_boshrelease]: https://github.com/cloudfoundry-community-attic/redis-consul-boshrelease\n[enable_encrypt_existing_cluster]: https://learn.hashicorp.com/consul/security-networking/agent-encryption#enable-on-an-existing-cluster\n\n\n\n## Authors and License\n\nCopyright © 2019-present, Benjamin Gandon, Gstack\n\nLike the rest of BOSH, this Gstack Consul BOSH Release is released under the\nterms of the [Apache 2.0 license](http://www.apache.org/licenses/LICENSE-2.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgstackio%2Fgk-consul-boshrelease","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgstackio%2Fgk-consul-boshrelease","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgstackio%2Fgk-consul-boshrelease/lists"}