Skip to content

Document the load balancer model in the README #278

Description

@sudomateo

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions