Active / controller

svc-lb-mux

Service LoadBalancer Multiplexer

Expose many L4 Services without paying for one cloud load balancer each.

svc-lb-mux is for platform and operations teams that need to expose many TCP/UDP services, but do not want every application-facing LoadBalancer Service to create another provider L4 load balancer, IP, forwarding rule, and recurring cost line.

1 muxcan front many compatible LoadBalancer Services
100 portsGKE-oriented cap per mux with default chart values
Native APIcontrol-plane only; no extra data-plane hop
GitHub Docs

Quickstart

Install one mux, expose one channel, verify the mapping.

Start with the default Helm install and a small echo Service. Provider-specific production values can come after the controller, mux Service, and first channel are visible.

Full quickstart GKE guide
01

Install the controller

helm install svc-mux oci://ghcr.io/nowakeai/charts/svc-lb-mux \
  --version 0.1.2 \
  --namespace svc-mux \
  --create-namespace
02

Watch the mux Service

kubectl get deploy -n svc-mux
kubectl get svc mux -n svc-mux -w
03

Expose a channel Service

kubectl apply -f echo-channel.yaml
kubectl get svc echo -n default
kubectl get endpoints mux -n svc-mux

Use it when

The problem is not ingress. It is too many L4 load balancers.

This is a narrow tool by design. It is useful when the workload really needs provider Layer 4 exposure and the cluster has many small services, many public ports, or a provider quota/cost ceiling that appears before the application does.

cost surface

Many small TCP/UDP Services

A cluster exposes many small services, each needing a stable external L4 endpoint. Paying for one cloud load balancer per Service becomes wasteful.

quota pressure

Quota-constrained clusters

Forwarding rules, IP addresses, load balancers, or provider-specific port limits become the bottleneck before the workload itself does.

ops fit

Service workflow must stay familiar

Application teams still create normal LoadBalancer Services. The mux handles shared provider exposure behind that Kubernetes-native API.

How it works

Mux owns the provider edge. Channels stay the app-facing API.

A mux Service is the single provider-facing LoadBalancer. Channel Services remain normal Kubernetes Services, but their spec.loadBalancerClass points at the mux instead of asking the cloud provider for another LB.

Clients
Provider L4 LB
Mux Service
selectorless LoadBalancer
controller-owned ports
Channel A
Channel B
Pods A
Pods B
controller syncs mux ports, endpoints, and status.loadBalancer.ingress

Operating model

Plain Kubernetes objects, with clear ownership boundaries.

Mux Service

Selectorless type: LoadBalancer Service. It owns the provider-facing L4 load balancer, runtime ports, and ingress status.

Channel Service

Application-facing type: LoadBalancer Service. It points at a mux through spec.loadBalancerClass and keeps stable named ports.

Control-plane only

The controller configures native Kubernetes Services and Endpoints. It does not proxy traffic or sit in the data path.

Port ownership

Static and auto-assigned mux port claims are persisted per mux in a controller-owned ConfigMap.

GitOps boundary

GitOps should manage desired config and ignore controller-owned mux spec.ports so the controller can reconcile active channels.

Provider reality

Cloud L4 behavior matters. The page should say so.

svc-lb-mux deliberately stays inside provider-managed Service LoadBalancer behavior. That keeps the normal path Kubernetes-native, but provider limits still define the safe operating envelope.

GKEActively validated

Defaults target external passthrough Network Load Balancers. One mux is capped at 100 Service ports to stay inside GKE-native behavior.

EKSSupported guide

AWS NLB setup is documented. Provider-specific validation should still be repeated in the target environment.

Other providersExperimental

The core model is Kubernetes-native, but cloud load balancer behavior, limits, and port handling vary by provider.

Docs map

The repo docs are organized around the operator workflow.

svc-lb-mux has a smaller scope than kube-insight, so the docs stay practical: install, understand channel mapping, copy examples, tune provider behavior, and debug controller-owned runtime state.

Start Getting Started

Install the chart, create a mux Service, expose a first channel, and validate status and endpoints.

 Concept Mux And Channel Services

Understand public ports, target ports, automatic allocation, state ConfigMaps, and external-dns aggregation.

 Examples Tutorials

Copyable examples for HTTP, TCP, migration, external-dns aggregation, capacity splitting, and GitOps.

 Providers GKE And AWS NLB

Provider-specific setup notes, static IP configuration, firewall behavior, and capacity boundaries.

 Operate GitOps And Troubleshooting

Separate desired config from runtime fields and diagnose missing mux ports, pending ingress, backend readiness, and drift.

 Internals Controller Design

Read the ownership model, generated endpoints, mux annotations, events, and current controller limits.

Current focus

Useful today for compatible workloads, still being hardened across providers.

The controller is intentionally small. Follow-up work is focused on larger backend state, repeatable provider validation, GitOps hardening, and better operator diagnostics.

EndpointSlice support for larger channel sets and clearer backend state.
Provider validation reports for GKE, EKS, and additional Kubernetes environments.
Debug UI rewrite with safer auth, modular diagnostics, and operator-focused topology views.

Next steps

Use the docs site for provider guides and operating notes.

The docs site renders Helm install docs, channel Service examples, GKE and AWS setup guides, GitOps notes, troubleshooting, and controller design details from the project repository.

Open GitHub GKE guide Channel manual