# KubeLB


## Overview

KubeLB is a project by Kubermatic, it is a Kubernetes native tool, responsible for centrally managing Layer 4 and 7 load balancing configurations for Kubernetes clusters across multi-cloud and on-premise environments.

### Motivation and Background

Kubernetes does not offer any implementation for load balancers and in turn relies on the in-tree or out-of-tree cloud provider implementations to take care of provisioning and managing load balancers. This means that if you are not running on a supported cloud provider, your services of type `LoadBalancer` will never be allotted a load balancer IP address. This is an obstacle for bare-metal Kubernetes environments.

There are solutions available like [MetalLB](https://metallb.universe.tf/), [Cilium](https://cilium.io/use-cases/load-balancer/), etc. that solve this issue. However, these solutions are focused on a single cluster where you have to deploy the application in the same cluster where you want the load balancers. This is not ideal for multi-cluster environments since you have to configure load balancing for each cluster separately, which makes IP address management not trivial.

For application load balancing, we have the same case where an external application like [nginx-ingress](https://kubernetes.github.io/ingress-nginx/), [envoy gateway](https://gateway.envoyproxy.io/), needs to be deployed in the cluster. To further secure traffic, additional tools are required for managing DNS, TLS certificates, Web Application Firewall, etc.

KubeLB solves this problem by providing a centralized management solution that can manage the data plane for multiple Kubernetes clusters across multi-cloud and on-premise environments. This enables you to manage fleet of Kubernetes clusters in a centralized way, ensuring security compliance, enforcing policies, and providing a consistent experience for developers.

## Architecture

KubeLB follows the **hub and spoke** model in which the "Management Cluster" acts as the hub and the "Tenant Clusters" act as the spokes. The information flow is from the tenant clusters to the management cluster. The agent running in the tenant cluster watches for nodes, services, ingresses, and Gateway API etc. resources and then propagates the configuration to the management cluster. The management cluster then deploys the load balancer and configures it according to the desired specification. Management cluster then uses Envoy Proxy to route traffic to the appropriate endpoints i.e. the node ports open on the nodes of the tenant cluster.

For security and isolation, the tenants have no access to any native kubernetes resources in the management cluster. The tenants can only interact with the management cluster via the KubeLB CRDs. This ensures that they are not exceeding their access level and only perform controlled operations in the management cluster.

[![KubeLB Architecture](https://github.com/kubermatic/kubelb/raw/main/docs/kubelb-high-level-architecture.png align="left")](https://github.com/kubermatic/kubelb/blob/main/docs/kubelb-high-level-architecture.png)

## Documentation

For detailed documentation [KubeLB Docs](https://docs.kubermatic.com/kubelb).

## Installation

### Manager

Please refer to the [KubeLB Manager README](https://github.com/kubermatic/kubelb/blob/main/charts/kubelb-manager/README.md) for installation instructions.

### CCM

Please refer to the [KubeLB CCM README](https://github.com/kubermatic/kubelb/blob/main/charts/kubelb-ccm/README.md) for installation instructions.

## Troubleshooting

If you encounter issues [file an issue](https://github.com/kubermatic/kubelb/issues) or talk to us on the [#kubermatic channel](https://kubermatic.slack.com/messages/kubermatic) on the [Kubermatic Slack](http://slack.kubermatic.io/).

## Contributing

Thanks for taking the time to join our community and start contributing!

Feedback and discussion are available on [the mailing list](https://gateway.envoyproxy.io/).

### Before you start

* Please familiarize yourself with the [Code of Conduct](https://kubernetes.github.io/ingress-nginx/) before contributing.
    
* See [CONTRIBUTING.md](https://metallb.universe.tf/) for instructions on the developer certificate of origin that we require.
    

### Pull requests

* We welcome pull requests. Feel free to dig through the [issues](https://github.com/kubermatic/kubelb/issues) and jump in.
    

## Changelog

See [the list of releases](https://cilium.io/use-cases/load-balancer/) to find out about feature changes.

| [.github](https://github.com/kubermatic/kubelb/tree/main/.github) | [chore - update dependencies](https://github.com/kubermatic/kubelb/commit/895ed658f7801cb7c073b85e71db77fae5edcb0d) | last year |
| --- | --- | --- |
| [.prow](https://github.com/kubermatic/kubelb/tree/main/.prow) | [Fix CI job to publish helm chart (](https://github.com/kubermatic/kubelb/commit/fdc2079d897b37bfbf3895f1cea02a471bfbb543)[#52](https://github.com/kubermatic/kubelb/pull/52)[)](https://github.com/kubermatic/kubelb/commit/fdc2079d897b37bfbf3895f1cea02a471bfbb543) | last week |
| [api/kubelb.k8c.io/v1alpha1](https://github.com/kubermatic/kubelb/tree/main/api/kubelb.k8c.io/v1alpha1) | [Fix status propagation and global topology (](https://github.com/kubermatic/kubelb/commit/6bbea5c3f1492eb65c105391040c9ae4a00ea4f2)[#54](https://github.com/kubermatic/kubelb/pull/54)[)](https://github.com/kubermatic/kubelb/commit/6bbea5c3f1492eb65c105391040c9ae4a00ea4f2) | last week |
| [charts](https://github.com/kubermatic/kubelb/tree/main/charts) | [Use enable-gateway-api instead of disable-gateway-api (](https://github.com/kubermatic/kubelb/commit/ff431502cf33d770dbd2fe1d8c14a515e466baa2)[#59](https://github.com/kubermatic/kubelb/pull/59)[)](https://github.com/kubermatic/kubelb/commit/ff431502cf33d770dbd2fe1d8c14a515e466baa2) | 4 days ago |
| [cmd](https://github.com/kubermatic/kubelb/tree/main/cmd) | [Fix flag parsing (](https://github.com/kubermatic/kubelb/commit/c193cd8071459bfa009b976c7ace3658fa05d8d8)[#60](https://github.com/kubermatic/kubelb/pull/60)[)](https://github.com/kubermatic/kubelb/commit/c193cd8071459bfa009b976c7ace3658fa05d8d8) | 4 days ago |
| [config](https://github.com/kubermatic/kubelb/tree/main/config) | [Fix status propagation and global topology (](https://github.com/kubermatic/kubelb/commit/6bbea5c3f1492eb65c105391040c9ae4a00ea4f2)[#54](https://github.com/kubermatic/kubelb/pull/54)[)](https://github.com/kubermatic/kubelb/commit/6bbea5c3f1492eb65c105391040c9ae4a00ea4f2) | last week |
| [docs](https://github.com/kubermatic/kubelb/tree/main/docs) | [Update readme (](https://github.com/kubermatic/kubelb/commit/e7b71c8fcf4a483a9ea29c788c030d843df754f7)[#57](https://github.com/kubermatic/kubelb/pull/57)[)](https://github.com/kubermatic/kubelb/commit/e7b71c8fcf4a483a9ea29c788c030d843df754f7) | 4 days ago |
| [hack](https://github.com/kubermatic/kubelb/tree/main/hack) | [Update readme (](https://github.com/kubermatic/kubelb/commit/e7b71c8fcf4a483a9ea29c788c030d843df754f7)[#57](https://github.com/kubermatic/kubelb/pull/57)[)](https://github.com/kubermatic/kubelb/commit/e7b71c8fcf4a483a9ea29c788c030d843df754f7) | 4 days ago |
| [internal](https://github.com/kubermatic/kubelb/tree/main/internal) | [Disable Gateway API watches if gateway is disabled (](https://github.com/kubermatic/kubelb/commit/33c91054e65be41af01e51a812804cc95b2e890e)[#58](https://github.com/kubermatic/kubelb/pull/58)[)](https://github.com/kubermatic/kubelb/commit/33c91054e65be41af01e51a812804cc95b2e890e) | 4 days ago |
| [.dockerignore](https://github.com/kubermatic/kubelb/blob/main/.dockerignore) | [Layer 7 load balancing support for Ingress (](https://github.com/kubermatic/kubelb/commit/a8fd7912eb45eaeddea3e4f79be924737f1e7382)[#22](https://github.com/kubermatic/kubelb/pull/22)[)](https://github.com/kubermatic/kubelb/commit/a8fd7912eb45eaeddea3e4f79be924737f1e7382) | last month |
| [.gimps.yaml](https://github.com/kubermatic/kubelb/blob/main/.gimps.yaml) | [Update linter and add gimps (](https://github.com/kubermatic/kubelb/commit/8eb41002f997c6e0829daa628efc32a6eff2850b)[#54](https://github.com/kubermatic/kubelb/pull/54)[)](https://github.com/kubermatic/kubelb/commit/8eb41002f997c6e0829daa628efc32a6eff2850b) | last year |
| [.gitignore](https://github.com/kubermatic/kubelb/blob/main/.gitignore) | [Upgrade to Go 1.22.6 & RBAC fixes (](https://github.com/kubermatic/kubelb/commit/44df5309f9c66b0ba439f5a4ddda269c1a138710)[#48](https://github.com/kubermatic/kubelb/pull/48)[)](https://github.com/kubermatic/kubelb/commit/44df5309f9c66b0ba439f5a4ddda269c1a138710) | 2 weeks ago |
| [.golangci.yml](https://github.com/kubermatic/kubelb/blob/main/.golangci.yml) | [Tenant and Global configurations (](https://github.com/kubermatic/kubelb/commit/b436a7f2d45fbc999fdf63e46b90dc2c791b18da)[#41](https://github.com/kubermatic/kubelb/pull/41)[)](https://github.com/kubermatic/kubelb/commit/b436a7f2d45fbc999fdf63e46b90dc2c791b18da) | 2 weeks ago |
| [.typos.toml](https://github.com/kubermatic/kubelb/blob/main/.typos.toml) | [Add typos config (](https://github.com/kubermatic/kubelb/commit/b0dc1ed70b97682e2275843fa4eb90a5a8de3690)[#29](https://github.com/kubermatic/kubelb/pull/29)[)](https://github.com/kubermatic/kubelb/commit/b0dc1ed70b97682e2275843fa4eb90a5a8de3690) | last month |
| [.wwhrd.yml](https://github.com/kubermatic/kubelb/blob/main/.wwhrd.yml) | [Minor fixes and improvements (](https://github.com/kubermatic/kubelb/commit/c14cd1e25a716bfbc2f0be5de8035d39277e3659)[#37](https://github.com/kubermatic/kubelb/pull/37)[)](https://github.com/kubermatic/kubelb/commit/c14cd1e25a716bfbc2f0be5de8035d39277e3659) | 3 weeks ago |
| [.yamllint.conf](https://github.com/kubermatic/kubelb/blob/main/.yamllint.conf) | [Add helm charts for kubelb (#80)](https://github.com/kubermatic/kubelb/commit/97a36dec88e28c8ef27c9bcc80f4a45bb509dab4) | 10 months ago |
| [CHANGELOG.md](https://github.com/kubermatic/kubelb/blob/main/CHANGELOG.md) | [Updates (](https://github.com/kubermatic/kubelb/commit/507f798ac25e00ecf31f63b562412ec5da2874a7)[#49](https://github.com/kubermatic/kubelb/pull/49)[)](https://github.com/kubermatic/kubelb/commit/507f798ac25e00ecf31f63b562412ec5da2874a7) | last week |
| [CODE\_OF\_CONDUCT.md](https://github.com/kubermatic/kubelb/blob/main/CODE_OF_CONDUCT.md) | [add open source requirements](https://github.com/kubermatic/kubelb/commit/ce41c8cf4bafb32c0f1862a69b7054afdcc5046a) | 4 years ago |
| [CONTRIBUTING.md](https://github.com/kubermatic/kubelb/blob/main/CONTRIBUTING.md) | [add open source requirements](https://github.com/kubermatic/kubelb/commit/ce41c8cf4bafb32c0f1862a69b7054afdcc5046a) | 4 years ago |
| [DCO](https://github.com/kubermatic/kubelb/blob/main/DCO) | [Prepare for v1.0.0 release (](https://github.com/kubermatic/kubelb/commit/3bac3975ead10e6e4143ec0a1dab8f419ffefb05)[#1](https://github.com/kubermatic/kubelb/pull/1)[)](https://github.com/kubermatic/kubelb/commit/3bac3975ead10e6e4143ec0a1dab8f419ffefb05) | 5 months ago |
| [LICENSE](https://github.com/kubermatic/kubelb/blob/main/LICENSE) | [add open source requirements](https://github.com/kubermatic/kubelb/commit/ce41c8cf4bafb32c0f1862a69b7054afdcc5046a) | 4 years ago |
| [Makefile](https://github.com/kubermatic/kubelb/blob/main/Makefile) | [Fix CI job to publish helm chart (](https://github.com/kubermatic/kubelb/commit/fdc2079d897b37bfbf3895f1cea02a471bfbb543)[#52](https://github.com/kubermatic/kubelb/pull/52)[)](https://github.com/kubermatic/kubelb/commit/fdc2079d897b37bfbf3895f1cea02a471bfbb543) | last week |
| [NOTICE](https://github.com/kubermatic/kubelb/blob/main/NOTICE) | [add open source requirements](https://github.com/kubermatic/kubelb/commit/ce41c8cf4bafb32c0f1862a69b7054afdcc5046a) | 4 years ago |
| [OWNERS](https://github.com/kubermatic/kubelb/blob/main/OWNERS) | [Update OWNERS](https://github.com/kubermatic/kubelb/commit/73a68da7570acce992ab3a5dd99ff986ebcb3418) | last year |
| [OWNERS\_ALIASES](https://github.com/kubermatic/kubelb/blob/main/OWNERS_ALIASES) | [Synchronize OWNERS\_ALIASES file with Github teams (](https://github.com/kubermatic/kubelb/commit/39f631374a5abeb28a9e23489995619873ed6a09)[#15](https://github.com/kubermatic/kubelb/pull/15)[)](https://github.com/kubermatic/kubelb/commit/39f631374a5abeb28a9e23489995619873ed6a09) | 3 months ago |
| [PROJECT](https://github.com/kubermatic/kubelb/blob/main/PROJECT) | [Support for synchronizing secrets from tenant to LB cluster (](https://github.com/kubermatic/kubelb/commit/445edcb7754b6073e310f3e9bfc410e4efea175a)[#42](https://github.com/kubermatic/kubelb/pull/42)[)](https://github.com/kubermatic/kubelb/commit/445edcb7754b6073e310f3e9bfc410e4efea175a) | 2 weeks ago |
| [README.md](https://github.com/kubermatic/kubelb/blob/main/README.md) | [Update readme (](https://github.com/kubermatic/kubelb/commit/e7b71c8fcf4a483a9ea29c788c030d843df754f7)[#57](https://github.com/kubermatic/kubelb/pull/57)[)](https://github.com/kubermatic/kubelb/commit/e7b71c8fcf4a483a9ea29c788c030d843df754f7) | 4 days ago |
| [ccm.dockerfile](https://github.com/kubermatic/kubelb/blob/main/ccm.dockerfile) | [KubeLB is now built with Go 1.23 (](https://github.com/kubermatic/kubelb/commit/a7b74eff9f3f7095727a8318664150c78c724c4f)[#51](https://github.com/kubermatic/kubelb/pull/51)[)](https://github.com/kubermatic/kubelb/commit/a7b74eff9f3f7095727a8318664150c78c724c4f) | last week |
| [go.mod](https://github.com/kubermatic/kubelb/blob/main/go.mod) | [Upgrade to Go 1.22.6 & RBAC fixes (](https://github.com/kubermatic/kubelb/commit/44df5309f9c66b0ba439f5a4ddda269c1a138710)[#48](https://github.com/kubermatic/kubelb/pull/48)[)](https://github.com/kubermatic/kubelb/commit/44df5309f9c66b0ba439f5a4ddda269c1a138710) | 2 weeks ago |
| [go.sum](https://github.com/kubermatic/kubelb/blob/main/go.sum) | [Upgrade to Go 1.22.6 & RBAC fixes (](https://github.com/kubermatic/kubelb/commit/44df5309f9c66b0ba439f5a4ddda269c1a138710)[#48](https://github.com/kubermatic/kubelb/pull/48)[)](https://github.com/kubermatic/kubelb/commit/44df5309f9c66b0ba439f5a4ddda269c1a138710) | 2 weeks ago |
| [kubelb.dockerfile](https://github.com/kubermatic/kubelb/blob/main/kubelb.dockerfile) | [KubeLB is now built with Go 1.23 (](https://github.com/kubermatic/kubelb/commit/a7b74eff9f3f7095727a8318664150c78c724c4f)[#51](https://github.com/kubermatic/kubelb/pull/51)[)](https://github.com/kubermatic/kubelb/commit/a7b74eff9f3f7095727a8318664150c78c724c4f) | last week |