Context
README.adoc covers none of the load balancer behavior users will actually interact with. Every item below will surprise a user today.
Scope
Add a load balancer section to the README documenting:
- The three service annotations:
oxide.computer/floating-ip, oxide.computer/floating-ip-pool, oxide.computer/floating-ip-version (including mutual-exclusion rules).
- There can only be one
LoadBalancer service per unique spec.ports[].port. Since floating IPs are transparent to Oxide instances, traffic will arrive on the instance’s internal IP address using spec.ports[].port. The service controller adds both the floating IP and the instance’s internal IP to the LoadBalancer status so that Kubernetes creates the per-node firewall rules needed to allow the traffic. Put another way, a load balancer configured to use port 443 will conflict with another load balancer configured to use port 443.
- That the "load balancer" is a floating IP pinned to a single node chosen alphabetically — a bandwidth bottleneck, with failover happening on reconcile cadence rather than instantly.
- That
externalTrafficPolicy: Local is rejected (and why).
- Which Service fields are unsupported (
loadBalancerSourceRanges, loadBalancerIP, dual-stack ipFamilies).
Done when
A new user can predict LB behavior from the README alone.
Context
README.adoccovers none of the load balancer behavior users will actually interact with. Every item below will surprise a user today.Scope
Add a load balancer section to the README documenting:
oxide.computer/floating-ip,oxide.computer/floating-ip-pool,oxide.computer/floating-ip-version(including mutual-exclusion rules).LoadBalancerservice per uniquespec.ports[].port. Since floating IPs are transparent to Oxide instances, traffic will arrive on the instance’s internal IP address usingspec.ports[].port. The service controller adds both the floating IP and the instance’s internal IP to theLoadBalancerstatus so that Kubernetes creates the per-node firewall rules needed to allow the traffic. Put another way, a load balancer configured to use port 443 will conflict with another load balancer configured to use port 443.externalTrafficPolicy: Localis rejected (and why).loadBalancerSourceRanges,loadBalancerIP, dual-stackipFamilies).Done when
A new user can predict LB behavior from the README alone.