oxidecomputer / oxidecomputer/oxide-cloud-controller-manager
Document the load balancer model in the README
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 6
- Forks
- 2
- Avg merge
- 2h 5m
- Merged PRs (30d)
- 14
Description
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
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. - 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: Localis rejected (and why). - Which Service fields are unsupported (
loadBalancerSourceRanges,loadBalancerIP, dual-stackipFamilies).
Done when
A new user can predict LB behavior from the README alone.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading README.adoc and the existing Service-related documentation. Add a load balancer section covering the three annotations and their mutual exclusion, port conflicts, single-node floating-IP behavior, reconcile-based failover, rejected externalTrafficPolicy, and unsupported fields; done means a new user can predict LB behavior from the README alone.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kubernetes
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 90/100