{"id":13651483,"url":"https://github.com/sous-chefs/consul","last_synced_at":"2025-04-04T12:10:21.072Z","repository":{"id":16156546,"uuid":"18902498","full_name":"sous-chefs/consul","owner":"sous-chefs","description":"Development repository for the consul cookbook","archived":false,"fork":false,"pushed_at":"2024-07-15T17:13:30.000Z","size":1301,"stargazers_count":192,"open_issues_count":8,"forks_count":244,"subscribers_count":34,"default_branch":"main","last_synced_at":"2024-10-29T21:41:33.361Z","etag":null,"topics":["chef","chef-cookbook","chef-resource","consul","hacktoberfest","managed-by-terraform"],"latest_commit_sha":null,"homepage":"https://supermarket.chef.io/cookbooks/consul","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/sous-chefs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"sous-chefs"}},"created_at":"2014-04-18T04:26:51.000Z","updated_at":"2024-10-02T20:02:27.000Z","dependencies_parsed_at":"2024-11-06T03:14:27.982Z","dependency_job_id":"cc5882b2-2e75-4408-b3e0-2ef241083d2e","html_url":"https://github.com/sous-chefs/consul","commit_stats":{"total_commits":1011,"total_committers":149,"mean_commits":6.785234899328859,"dds":0.9000989119683481,"last_synced_commit":"7b4f0242ebcc5beaf2057e6190011ba6792ddc2c"},"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fconsul","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fconsul/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fconsul/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Fconsul/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sous-chefs","download_url":"https://codeload.github.com/sous-chefs/consul/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245258184,"owners_count":20585977,"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","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":["chef","chef-cookbook","chef-resource","consul","hacktoberfest","managed-by-terraform"],"created_at":"2024-08-02T02:00:49.892Z","updated_at":"2025-03-28T11:11:31.564Z","avatar_url":"https://github.com/sous-chefs.png","language":"Ruby","funding_links":["https://opencollective.com/sous-chefs"],"categories":["Projects"],"sub_categories":["Provisioning"],"readme":"# Consul Cookbook\n\n[![Cookbook Version](https://img.shields.io/cookbook/v/consul.svg)](https://supermarket.chef.io/cookbooks/consul)\n[![CI State](https://github.com/sous-chefs/consul/workflows/ci/badge.svg)](https://github.com/sous-chefs/consul/actions?query=workflow%3Aci)\n[![OpenCollective](https://opencollective.com/sous-chefs/backers/badge.svg)](#backers)\n[![OpenCollective](https://opencollective.com/sous-chefs/sponsors/badge.svg)](#sponsors)\n[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)\n\n[Application cookbook][0] which installs and configures [Consul][1].\n\nConsul is a tool for discovering and configuring services within your\ninfrastructure. This is an application cookbook which takes a\nsimplified approach to configuring and installing\nConsul. Additionally, it provides Chef primitives for more advanced\nconfiguration.\n\n## Maintainers\n\nThis cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit [sous-chefs.org](https://sous-chefs.org/) or come chat with us on the Chef Community Slack in [#sous-chefs](https://chefcommunity.slack.com/messages/C2V7B88SF).\n\n## Basic Usage\n\nFor most infrastructure we suggest first starting with the default\nrecipe. This installs and configures Consul from the latest supported\nrelease. It is also what is used to certify platform support through\nthe use of our integration tests.\n\nThis cookbook provides node attributes which are used to fine tune\nthe default recipe which installs and configures Consul. These values\nare passed directly into the Chef resource/providers which are exposed\nfor more advanced configuration.\n\nOut of the box the following platforms are certified to work and are\ntested using our [Test Kitchen][8] configuration. Additional platforms\n_may_ work, but your mileage may vary.\n\n- RHEL/CentOS 7 \u0026 8\n- Ubuntu 16.04, 18.04 \u0026 20.04\n- Debian 9 \u0026 10\n- Windows Server 2012 R2\n\n### Client\n\nOut of the box the default recipe installs and configures the Consul\nagent to run as a service in _client mode_. The intent here is that\nyour infrastructure already has a [quorum of servers][13]. In order\nto configure Consul to connect to your cluster you would supply an\narray of addresses for the Consul agent to join. This would be done\nin your [wrapper cookbook][2]:\n\n```ruby\nnode.default['consul']['config']['start_join'] = %w{c1.internal.corporate.com c2.internal.corporate.com c3.internal.corporate.com}\n```\n\n### Server\n\nThis cookbook is designed to allow for the flexibility to bootstrap a\nnew cluster. The best way to do this is through the use of a\n[wrapper cookbook][2] which tunes specific node attributes for a\nproduction server deployment.\n\nThe [Consul cluster cookbook][14] is provided as an example.\n\n## Advanced Usage\n\nAs explained above this cookbook provides Chef primitives in the form\nof resource/provider to further manage the install and configuration\nof Consul. These primitives are what is used in the default recipe,\nand should be used in your own [wrapper cookbooks][2] for more\nadvanced configurations.\n\n### Configuration\n\nIt is very important to understand that each resource/provider has\ndefaults for some properties. Any changes to a resource's default\nproperties may need to be also changed in other resources. The best\nexample is the Consul configuration directory.\n\nIn the example below we're going to change the configuration file from\nthe default (/etc/consul.json) to one that may be on a special volume.\nIt is obvious that we need to change the path where `consul_config`\nwrites its file to, but it is less obvious that this needs to be\npassed into `consul_service`.\n\nInside of a recipe in your [wrapper cookbook][2] you'll want to do\nsomething like the following block of code. It uses the validated\ninput from the configuration resource and passes it into the service\nresource. This ensures that we're using the _same data_.\n\n```ruby\nconfig = consul_config '/data/consul/default.json'\nconsul_service 'consul' do\n  config_file config.path\nend\n```\n\n### Security\n\nThe default recipe makes the Consul configuration writable by the consul service\nuser to avoid breaking existing implementations. You can make this more secure\nby setting the `node['consul']['config']['owner']` attribute to `root`, or set\nthe `owner` property of `consul_config` explicitly:\n\n```ruby\n# attributes file\ndefault['consul']['config']['owner'] = 'root'\n```\n\nor\n\n```ruby\n# recipe file\nconsul_config '/etc/consul/consul.json' do\n  owner 'root'\nend\n```\n\n### Watches/Definitions\n\nIn order to provide an idempotent implementation of Consul\nwatches and definitions. We write these out as\na separate configuration file in the JSON file format. The provider\nfor both of these resources are identical in functionality.\n\nBelow is an example of writing a [Consul service definition][10] for\nthe master instance of Redis. We pass in several parameters and tell\nthe resource to notify the proper instance of the Consul service to\nreload.\n\n```ruby\nconsul_definition 'redis' do\n  type 'service'\n  parameters(tags: %w{master}, address: '127.0.0.1', port: 6379)\n  notifies :reload, 'consul_service[consul]', :delayed\nend\n```\n\nA [check definition][11] can easily be added as well. You simply have\nto change the type and pass in the correct parameters. The definition\nbelow checks memory utilization using a script on a ten second interval.\n\n```ruby\nconsul_definition 'mem-util' do\n  type 'check'\n  parameters(script: '/usr/local/bin/check_mem.py', interval: '10s')\n  notifies :reload, 'consul_service[consul]', :delayed\nend\n```\n\nA service definition with an integrated check can also be created. You will have to define a regular service and then add a check as a an additional parameter. The definition below checks if the vault service is healthy on a 10 second interval and 5 second timeout.\n\n```ruby\nconsul_definition 'vault' do\n  type 'service'\n  parameters(\n    port:  8200,\n    address: '127.0.0.1',\n    tags: ['vault', 'http'],\n    check: {\n      interval: '10s',\n      timeout: '5s',\n      http: 'http://127.0.0.1:8200/v1/sys/health'\n    }\n  )\n  notifies :reload, 'consul_service[consul]', :delayed\nend\n```\n\nFinally, a [watch][9] is created below to tell the agent to monitor to\nsee if an application has been deployed. Once that application is\ndeployed a script is run locally. This can be used, for example, as a\nlazy way to clear a HTTP disk cache.\n\n```ruby\nconsul_watch 'app-deploy' do\n  type 'event'\n  parameters(handler: '/usr/local/bin/clear-disk-cache.sh')\n  notifies :reload, 'consul_service[consul]', :delayed\nend\n```\n\nA keen eye would notice that we are _delaying the reload of the Consul\nservice instance_. The reason we do this is to minimize the number of\ntimes we need to tell Consul to actually reload configurations. If\nthere are several definitions this may save a little time off your\nChef run.\n\n### ACLs\n\nThe `consul_acl` resource allows management of [Consul ACL rules][15]. Supported\nactions are `:create` and `:delete`. The `:create` action will update/insert\nas necessary.\n\nThe `consul_acl` resource requires the [Diplomat Ruby API][16] gem to be\ninstalled and available to Chef before using the resource. This can be\naccomplished by including `consul::client_gem` recipe in your run list. If you\nare using Chef Infra Client 15.8+ you will need to make sure you are using at\nleast version 2.2.6 of the diplomat gem.\n\nIn order to make the resource idempotent and only notify when necessary, the\n`id` field is always required (defaults to the name of the resource).\nIf `type` is not provided, it will default to \"client\". The `acl_name`\nand `rules` attributes are also optional; if not included they will be empty\nin the resulting ACL.\n\nThe example below will create a client ACL token with an `ID` of the given UUID,\n`Name` of \"AwesomeApp Token\", and `Rules` of the given string.\n\n```ruby\nconsul_acl '49f06aa9-782f-465a-becf-44f0aaefd335' do\n  acl_name 'AwesomeApp Token'\n  type 'client'\n  rules \u003c\u003c-EOS.gsub(/^\\s{4}/, '')\n    key \"\" {\n      policy = \"read\"\n    }\n    service \"\" {\n      policy = \"write\"\n    }\n  EOS\n  auth_token node['consul']['config']['acl_master_token']\nend\n```\n\n### Execute\n\nThe command-line agent provides a mechanism to facilitate remote\nexecution. For example, this can be used to run the `uptime` command\nacross your fleet of nodes which are hosting a particular API service.\n\n```ruby\nconsul_execute 'uptime' do\n  options(service: 'api')\nend\n```\n\n### Warning on git based installs\n\nConsul v1.0 states that Go 1.9 is a requirement. The default go installation uses\n1.5, so you may need to override a `['go']['version']` attribute to allow the\ngit installation to work reliably.\n\nAll of the [options available on the command-line][12] can be passed\ninto the resource. This could potentially be a very dangerous\noperation. You should absolutely understand what you are doing. By the\nnature of this command it is _impossible_ for it to be idempotent.\n\n[1]: http://consul.io\n[8]: https://github.com/test-kitchen/test-kitchen\n[13]: https://en.wikipedia.org/wiki/Quorum_(distributed_computing)\n[14]: https://github.com/johnbellone/consul-cluster-cookbook\n[16]: https://github.com/WeAreFarmGeek/diplomat\n\n## Contributors\n\nThis project exists thanks to all the people who [contribute.](https://opencollective.com/sous-chefs/contributors.svg?width=890\u0026button=false)\n\n### Backers\n\nThank you to all our backers!\n\n![https://opencollective.com/sous-chefs#backers](https://opencollective.com/sous-chefs/backers.svg?width=600\u0026avatarHeight=40)\n\n### Sponsors\n\nSupport this project by becoming a sponsor. Your logo will show up here with a link to your website.\n\n![https://opencollective.com/sous-chefs/sponsor/0/website](https://opencollective.com/sous-chefs/sponsor/0/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/1/website](https://opencollective.com/sous-chefs/sponsor/1/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/2/website](https://opencollective.com/sous-chefs/sponsor/2/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/3/website](https://opencollective.com/sous-chefs/sponsor/3/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/4/website](https://opencollective.com/sous-chefs/sponsor/4/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/5/website](https://opencollective.com/sous-chefs/sponsor/5/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/6/website](https://opencollective.com/sous-chefs/sponsor/6/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/7/website](https://opencollective.com/sous-chefs/sponsor/7/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/8/website](https://opencollective.com/sous-chefs/sponsor/8/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/9/website](https://opencollective.com/sous-chefs/sponsor/9/avatar.svg?avatarHeight=100)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsous-chefs%2Fconsul","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsous-chefs%2Fconsul","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsous-chefs%2Fconsul/lists"}