Document the load balancer model in the README

Open Beginner friendly
#278 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
90/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
kubernetes
Domain
documentation

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.

Description

Documentation Kubernetes Cloud Controller Manager (CCM)

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.

Dominant language
Go
Stars
6
Forks
2
Avg merge
2h 5m
Merged PRs (30d)
14

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from oxidecomputer/oxide-cloud-controller-manager

All issues in oxidecomputer/oxide-cloud-controller-manager

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.