{"id":21038508,"url":"https://github.com/tuenti/kube2lb","last_synced_at":"2025-05-15T15:33:43.406Z","repository":{"id":64304508,"uuid":"52272109","full_name":"tuenti/kube2lb","owner":"tuenti","description":"Dinamically configure load balancers to expose Kubernetes services","archived":false,"fork":false,"pushed_at":"2018-03-02T13:04:27.000Z","size":5742,"stargazers_count":22,"open_issues_count":1,"forks_count":5,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-11-15T00:18:03.311Z","etag":null,"topics":["go","haproxy-configuration","kubernetes","load-balancer"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/tuenti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-22T12:31:42.000Z","updated_at":"2024-03-02T07:28:59.000Z","dependencies_parsed_at":"2023-01-15T10:15:52.378Z","dependency_job_id":null,"html_url":"https://github.com/tuenti/kube2lb","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuenti%2Fkube2lb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuenti%2Fkube2lb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuenti%2Fkube2lb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuenti%2Fkube2lb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuenti","download_url":"https://codeload.github.com/tuenti/kube2lb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225361542,"owners_count":17462263,"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":["go","haproxy-configuration","kubernetes","load-balancer"],"created_at":"2024-11-19T13:32:47.309Z","updated_at":"2024-11-19T13:32:47.981Z","avatar_url":"https://github.com/tuenti.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kube2lb\n\nDinamically configure a load balancer by reading services information from\nKubernetes API.\n\n`kube2lb` uses a template and the information obtained from a Kubernetes API to\ngenerate a configuration file for a load balancer, then `kube2lb` signals the\nload balancer to reload the configuration.\n\nIt's intended to be used on Kubernetes clusters deployed on bare-metal that\nneed to expose services to applications running out of the cluster, with a\nsimilar approach to cloud providers in Kubernetes. All services of types\n`LoadBalancer` or `NodePort` are exposed.\n\n## Quick start\n\n`kube2lb` needs to know the location of the template, the configuration file\nused by the load balancer, its PID and the Kubernetes API endpoint.\n\nFor example, to configure a [Caddy server](https://caddyserver.com/):\n\n```\necho localhost :8080 \u003e Caddyfile\ncaddy -conf=Caddyfile -pidfile=caddy.pid\n\nkube2lb -kubecfg=~/.kube/config \\\n\t-template=examples/caddy/Caddyfile.tpl \\\n\t-config=Caddyfile \\\n\t-domain=cluster.local \\\n\t-notify=pidfile:SIGUSR1:caddy.pid\n```\n\nThis will read Kubernetes client configuration from `~/.kube/config`, the\ntemplate from the `examples` directory and will pass the domain `cluster.local`\nto the template execution to generate the host names. Then when something\nchanges it will generate the configuration file and notify on the process\nwhose PID is the one in caddy.pid with the `SIGUSR1` signal, the one used\nby Caddy for online configuration reload.\n\nYou can see examples in the `[examples](examples)` directory.\n\n## Compiling\n\n`godep restore` is required to use vendorized dependencies.\n\n```\nmake\n```\n\n## Configuration details\n\n### Kubeconfig\n\nKubernetes connections to the API are done using the same libraries as other\ntools as `kubectl` or `kube2sky` and following similar principles.\n\nConfiguration is taken in this order:\n\n1. API server (`-apiserver` flag)\n1. Configuration file (`-kubecfg` flag, api server endpoint can be overriden\n   with `-apiserver`)\n1. In cluster configuration, useful if `kube2lb` is deployed in a pod\n\n### Server names\n\nTemplates receive the list of nodes, services and the domain passed with the\n`-domain` flag.\n\nTemplates can use the `ServerNames` function, that generates a list of server\nnames to be used in load balancers configuration. This list is generated using\na comma-separated list of templates passed with the `-server-name-templates`.\n\nFor example, this flag could be used to generate two server names for each\nservice, one with just the service name as a subdomain of example.com,\nand another one with the default names used by kubernetes:\n```\nkube2lb ... -server-name-templates \"{{ .Service.Name }}.example.com,{{ .Service.Name }}.{{ .Service.Namespace }}.svc.{{ .Domain }}\"\n```\n\nAdditional server names can be added also as a comma-sepparated list in the\n`kube2lb/external-domains` annotation in the service definition, e.g:\n```\napiVersion: v1\nkind: Service\nmetadata:\n  annotations:\n    kube2lb/external-domains: test.example.com,~^(test1|test2)\\.example\\.(com|net)$\n...\n```\n\nUse `~` to indicate that it must be handled as a regular expression.\n\nAnd in the configuration file template:\n```\n{{ range $serverName := ServerNames $service $domain }}\n{{- if $serverName.IsRegexp }}\nacl svc_{{ $label }} hdr_reg(host) {{ $serverName.Regexp }}{{- else }}\nacl svc_{{ $label }} hdr_dom(host) -i {{ $serverName }}{{- end }}\n{{- end }}\n```\n\nWhen looking for matches in the `Host` header take into account that it can also\ninclude the port in the form `host:port`. In the previous example the regexp would\nbe applied to the whole `Host` header, including the port, so it has to be\nconsidered when writing the annotation. On the other hand this template would handle\nit for plain server names by using the `hdr_dom` function, that compares with the\n\"domain\" part of the header.\n\n### Port modes\n\nLoad balancers use to differenciate TCP and HTTP connections, for HTTP\nconnections they have additional features as the possibility of choosing a\nbackend depending on an specific HTTP header. `kube2lb` allows to declare\ndifferent modes for some ports.\n\nDefault mode can be changed with the `-default-port-mode` flag, it is \nhttp by default.\n\nAn annotation can be used to declare different modes. e.g:\n```\napiVersion: v1\nkind: Service\nmetadata:\n  annotations:\n    kube2lb/port-mode: |\n      { \"mysql\": \"tcp\", \"healthz\": \"http\" }\n...\n```\nThe annotation must be a string to string map represented as valid JSON, with\nthe port name as key and the mode as value. Ports must declare their names\nin order to use this feature.\n\n### Timeouts\n\nFor convenience, kube2lb allows to declare per-service backend timeouts using\nkubernetes annotations. Other timeouts are assumed to be global, so they can\nbe declared on specific templates.\n\nTo declare the backend timeout for a service:\n\n```\napiVersion: v1\nkind: Service\nmetadata:\n  annotations:\n    kube2lb/backend-timeout: |\n      { \"http\": 20000 }\n...\n```\nThe annotation must be a string to integer map represented as valid JSON, with\nthe port name as key and the timeout in milliseconds as value. Ports must declare\ntheir names in order to use this feature.\n\nThey can be used in templates as an attribute of each service:\n\n```\n{{- range $i, $service := $services }}\n{{- if gt $service.Timeout 0 }}\ntimeout server {{ $service.Timeout }}\n{{- end }}\n{{- end }}\n```\n\n### Notifiers\n\n`kube2lb` can be used with any service that is configured with configuration\nfiles and can do online configuration reload. To notify the service that it\nmust reload its configuration a notifier needs to be configured.\n\nBy now these notifier definitions can be used:\n\n* `command:COMMAND` executes a command to notify, this command is executed\n  inside a shell (e.g: `-notify command:\"haproxy -f /etc/haproxy.cfg -p /run/haproxy.pid -sf \\$(cat /run/haproxy.pid)\"`)\n* `pid:SIGNAL:PID` notifies to an specific pid (e.g: `-notify pid:SIGHUP:5678`)\n* `pidfile:SIGNAL:PIDFILE` notifies to the pid in a pidfile (e.g: `-notify pidfile:SIGUSR1:/var/run/caddy.pid`)\n* `debug:` doesn't notify, it just logs when `kube2lb` detects a change in\n  nodes or services, it can be used to test configurations.\n\n## Credits \u0026 Contact\n\n`kube2lb` was created by [Tuenti Technologies S.L.](http://github.com/tuenti)\n\nYou can follow Tuenti engineering team on Twitter [@tuentieng](http://twitter.com/tuentieng).\n\n## License\n\n`kube2lb` is available under the Apache License, Version 2.0. See LICENSE file\nfor more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuenti%2Fkube2lb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuenti%2Fkube2lb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuenti%2Fkube2lb/lists"}