{"id":15664859,"url":"https://github.com/moritzheiber/consul-connect-kickstarter","last_synced_at":"2025-06-14T11:04:23.615Z","repository":{"id":149805123,"uuid":"138895453","full_name":"moritzheiber/consul-connect-kickstarter","owner":"moritzheiber","description":"A short kickstarter for trying out and using Consul's new functionality called \"Connect\"","archived":false,"fork":false,"pushed_at":"2018-07-03T09:03:57.000Z","size":52,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-05T15:47:21.186Z","etag":null,"topics":["consul","consul-cluster","consul-connect","devops","hashicorp","service-mesh"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moritzheiber.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-27T14:48:29.000Z","updated_at":"2020-06-29T18:46:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"1a1f542a-8215-41d4-a67b-451445b232f3","html_url":"https://github.com/moritzheiber/consul-connect-kickstarter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/moritzheiber/consul-connect-kickstarter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzheiber%2Fconsul-connect-kickstarter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzheiber%2Fconsul-connect-kickstarter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzheiber%2Fconsul-connect-kickstarter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzheiber%2Fconsul-connect-kickstarter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moritzheiber","download_url":"https://codeload.github.com/moritzheiber/consul-connect-kickstarter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzheiber%2Fconsul-connect-kickstarter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259804841,"owners_count":22913901,"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":["consul","consul-cluster","consul-connect","devops","hashicorp","service-mesh"],"created_at":"2024-10-03T13:44:22.424Z","updated_at":"2025-06-14T11:04:23.597Z","avatar_url":"https://github.com/moritzheiber.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Consul Connect Kickstarter\n\nThis is meant to be an initial kickstarter to understand and try out [Hashicorp Consul's](https://www.consul.io/) new capability called \"[Connect](https://www.consul.io/docs/connect/index.html)\", which is a service mesh baked directly into Consul, with support for [Nomad](https://www.nomadproject.io) and outside proxy connectors.\n\n## Prerequisites\n\n- Docker (\u003e= 18.03.0-ce)\n- docker-compose (\u003e= 1.20.1)\n- bash (for running the convenience script)\n\n## Running the composed application setup\n\n```\n$ ./run compose\n```\n\nThis will provision the following setup:\n\n1. A Consul server, with its UI exposed on [localhost:8500/ui](http://localhost:8500). ACLs are disabled, the default datacenter `dc1` is used.\n2. Two Consul agents, `db-agent` and `client-agent`, connected to the server via a `gossip` network, so they can form a cluster\n3. A custom, unmanaged [connect proxy](https://www.consul.io/docs/connect/proxies.html), registering with the Consul cluster as a connection handler for the `postgres` service\n4. A PostgreSQL database container, running the verbatim default setup (connections are accepted from anywhere, the user is `postgres`, no password), able to talk to `db-agent` and `db-proxy`\n5. A `client-proxy` container, which runs a local proxy, able to forward connections to the PostgreSQL container using Consul Connect.\n\n### Tearing it all down again\n\nJust press `CTRL+C` on the output window. A trap will automatically reap all remaining processes and remove all networks, containers and volumes created by the setup.\n\n## Outcome\n\nThe client (`client-proxy`) and the database (`db`) are physically incapable of connecting directly to one-another. It's impossible. But you can use Consul Connect in order for the client to utilize the fully secured connection tunnel between the proxies to talk to the database:\n\n```\n# Connect to the client-proxy container\n$ docker exec -ti consulconnectkickstarter_client-proxy_1 /bin/sh\n# Connect to the database using Consul Connect, via the client proxy listening on port 5432 on 127.0.0.1\n$ psql -h 127.0.0.1 -U postgres\npsql (10.4)\nType \"help\" for help.\n\npostgres=#\n```\n\nYou are now connected to your database, via Consul Connect, using mutual TLS for authentication and authorization, via the two client proxies. Congrats!\n\n### Intentions\n\nACLs are disabled for this kickstarter, they would add an unnecessary layer of complexity for initially trying out the application. **This means the [intentions](https://www.consul.io/docs/connect/intentions.html) subsystem for managing connection access (i.e. the authorization layer) is open by default**. So don't be surprised your client is able to connect via Consul Connect although there's no explicit intention allowing you to do so.\n\nOnce you were to switch your ACL enforcement to `deny` by default this would be automatically applied to the default intention as well.\n\nYour can try out the intention authorization layer by explicitly denying access to the client service [via the UI](http://localhost:8501/ui/dc1/intentions). Click on `Create`, select `client` as the `SOURCE SERVICE` and `postgres` as the `DESTINATION SERVICE` and `Deny`. Leave a `Description` if you want to and submit the form with `Save`:\n\n![new_intention](images/new_intention.png)\n\n![saved_intention](images/saved_intention.png)\n\nNow you should no longer be able to connect to the database using the client:\n\n```\n$ psql -h 127.0.0.1 -U postgres\npsql: server closed the connection unexpectedly\n  This probably means the server terminated abnormally\n  before or while processing the request.\n```\n\nAnd in the `client-proxy` logs you're going to notice:\n\n```\nclient-proxy_1  |     2018/06/27 14:32:32 [ERR] failed to dial: remote error: tls: bad certificate\n```\n\nThis is because an intention explicitly forbids the identity `client` from connecting to the service `postgres`, and thus the `client-proxy` will be unable to attain a valid certificate from the Consul cluster in order to connect to the streaming proxy of the database using mutual TLS.\n\n## Caveats\n\n- The basic proxy provided by Consul isn't very configurable for this scenario. Thus it only allows for it to be connected via `127.0.0.1`, i.e. you have to start the client proxy in the same environment the application that is supposed to use the proxy is started in. This will either be solved in the future by extending the proxy's ability to interpret configuration parameters, supporting other schedulers or by another proxy which is not embedded inside Consul.\n- Running the proxy \"natively\" through Consul directly does not work in a \"pure\" container environment (yet). It will be in the near-term future, but right now you have to run each service proxy as an unmanaged proxy outside of Consul. Luckily, the embedded Consul Connect proxy shipped with the Consul binary is flexible enough to register itself within Consul and route traffic based on what the cluster tells it to do.\n- There are no Terraform definitions for intentions yet, but I might add those later. Right now you'll either have to whip them up yourself, use the API directly or go through the UI.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoritzheiber%2Fconsul-connect-kickstarter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoritzheiber%2Fconsul-connect-kickstarter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoritzheiber%2Fconsul-connect-kickstarter/lists"}