{"id":37121774,"url":"https://github.com/holoplot/kubelish","last_synced_at":"2026-01-14T14:01:05.757Z","repository":{"id":161988803,"uuid":"623431777","full_name":"holoplot/kubelish","owner":"holoplot","description":"📣 mDNS service publisher for Kubernetes cluster nodes","archived":false,"fork":false,"pushed_at":"2025-07-14T22:01:29.000Z","size":113,"stargazers_count":35,"open_issues_count":5,"forks_count":1,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-07-15T03:02:10.473Z","etag":null,"topics":["dns-sd","iot","kubernetes","mdns","service-mesh"],"latest_commit_sha":null,"homepage":"","language":"Go","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/holoplot.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,"zenodo":null}},"created_at":"2023-04-04T11:07:44.000Z","updated_at":"2025-06-11T08:59:00.000Z","dependencies_parsed_at":"2024-04-09T16:02:18.539Z","dependency_job_id":"9a370781-6e85-403f-8c6b-d03fd2ff5ea0","html_url":"https://github.com/holoplot/kubelish","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/holoplot/kubelish","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holoplot%2Fkubelish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holoplot%2Fkubelish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holoplot%2Fkubelish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holoplot%2Fkubelish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/holoplot","download_url":"https://codeload.github.com/holoplot/kubelish/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holoplot%2Fkubelish/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28422402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T13:30:50.153Z","status":"ssl_error","status_checked_at":"2026-01-14T13:29:08.907Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["dns-sd","iot","kubernetes","mdns","service-mesh"],"created_at":"2026-01-14T14:01:05.065Z","updated_at":"2026-01-14T14:01:05.748Z","avatar_url":"https://github.com/holoplot.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kubelish - mDNS service publisher for Kubernetes cluster nodes\n\nThis project implements a way to expose k8s services with external IPs as mDNS services.\n\nThe rationale behind this project is to allow k8s services to be discovered by\ndevices on the local network dynamically, without the need to configure static IPs\nor DNS entries. This is particularly useful for IoT devices, which are often unable\nto become part of a traditional service mesh but need to access services of\nthe k8s cluster.\n\nIn contrast to other solutions, this project exposes mDNS services (SRV records)\nrather than hosts (A records) which has the advantage that the daemon can run\non multiple nodes of the same cluster that have IP addresses in the same subnet,\nand offer the service on each of them. Clients will hence pick one of the nodes at\nrandom.\n\n## How it works\n\nThe `kubelish` daemon runs on each node of the cluster and listens for new `LoadBalancer`\nservices with external IPs. When a service is created or updated, the daemon checks\nthe annotations of the service to see if it should be exposed.\n\nThe following keys are required:\n\n```yaml\nmetadata:\n  annotations:\n    kubelish/service-name: Example\n    kubelish/service-type: _example._tcp\n    kubelish/txt: Optional TXT record to be exposed along with the service on mDNS\n```\n\nIf the service is annotated that way it will be exposed as an mDNS service.\n\nThe hostname of the node will be appended to the service name (e.g. `Example on node.local`)\nto avoid mDNS collisions when the same service is announced by other nodes.\n\nIf a service is deleted or updated to not be exposed, the daemon will remove\nthe mDNS service.\n\n## Kubernetes services with multiple ports\n\nIf a service has multiple ports, the port to be exposed as an mDNS service\nhas to be annotated with the same name as the mDNS service name, e.g.:\n\n```yaml\nmetadata:\n  annotations:\n    kubelish/service-name: Example\n    kubelish/service-type: _example._tcp\n    kubelish/txt: Optional TXT record to be exposed along with the service on mDNS\n    ...\nspec:\n  ...\n  ports:\n  - name: Example\n    nodePort: 10000\n    port: 9090\n    protocol: TCP\n    targetPort: 9090\n```\n\n## Running the daemon\n\nThe daemon must be run natively on a node of the cluster, outside of Kubernetes.\n\nInstall the daemon by using\n\n```bash\ngo install github.com/holoplot/kubelish/cmd/kubelish@latest\n```\n\nThen move the binary to a suitable location in your `$PATH`, e.g. `/usr/local/bin/kubelish`.\n\nThe binary supports the following commands:\n\n- `kubelish watch` - Runs the watcher daemon\n- `kubelish add \u003ck8s-service\u003e` - Adds annotations to a service to expose it as an mDNS service and dumps the YAML to stdout\n- `kubelish remove \u003ck8s-service\u003e` - Removes annotations from a service and dumps the YAML to stdout\n\nA systemd service file is [provided](kubelish.service). Make sure you\nedit the file to set the correct path to the binary and the kubeconfig file.\n\n### Global flags\n\nThe following flags can be used with all commands:\n* `--namespace` - Namespace to watch for services. Defaults to `default`.\n\n### Environment variables\n\nThe environment variables below can be used to configure the daemon:\n\n- `KUBECONFIG` - Path to the kubeconfig file to use. Defaults to `~/.kube/config`.\n\n### Example\n\nLet's assume we have a service called `my-loadbalancer` in the `default` namespace that\nyou want to expose as an mDNS service.\n\nFirst, run the daemon on the node that has the IP address of the service:\n\n```bash\nkubelish watch\n```\n\nThen, in a second terminal, add the annotations to the service using the following command:\n\n```bash\nkubelish add my-loadbalancer --service-name example --service-type _example._tcp --txt Example \\\n\t| kubectl apply -f -\n```\n\nThe service should now be exposed as an mDNS service. You can verify this by using\nthe `avahi-browse` command:\n\n```bash\navahi-browse -r _example._tcp\n```\n\nTo remove the service, run the following command:\n\n```bash\nkubelish remove my-loadbalancer | kubectl apply -f -\n```\n\n## Limitations\n\nThis project is still in its early stages and has some limitations:\n\n- Only supports Linux\n- Depends on `avahi-daemon` to be installed on the host\n- Does not support miniKube's way of exposing services with `minikube tunnel`\n\n## Releasing\n\nTo make a new release run `release.sh` with the version number you would like\nto release e.g. `./release.sh 4.3.2`. This will make the required changes to\nthe helm chart. When this change is merged into the `main` branch GitHub\nworkflows will create a release and publish the container image and helm chart\nwith the appropriate release tags.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholoplot%2Fkubelish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fholoplot%2Fkubelish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholoplot%2Fkubelish/lists"}