write a controller guide

[clux]

WIP: Current progress visible at https://kube.rs/controllers/intro/

1. Main Section

• intro - controller guide intro + object clarification #9
• root objects; k8s-openapi objects crds, deriving, kopium, dyn objects - controller guide intro + object clarification #9
• app build, cargo/ci/controller - main parts of controller guide #13
• reconciler; context/idempotency/ownerrefs/finalizers/instrumentation/o11y/diagnostics - main parts of controller guide #13
• garbage collection - finalizers and ownererfs - Add a controller doc about garbage collection #43
• related objects - controller options main parts of controller guide #13

2. Advanced Section

• generic code - Add a doc about how to re-use reconciler/controller logic #47
• schema writing - deriving/validation/customization/enums/x-kubernetes - quick doc on schemas #37
• web servers integration for external control hooks
• testing Controller testing guidelines #27
• signal handling (advice on propagating failures and still gracefully handling, look at elegantdeparture + conrad's thing)
• kubectl integrations; events and conditions (requires some upstream work - Condition creation & management helpers kube#427)
• admission controllers - web server setup, certificates, admission policy, x-kubernetes-validation as alternatives - Admission control setups, where to start, and more modern options #53
• crd state machinery dropping over concerns with the state machine model and krator disrepair

3. Operational Section

• productionising, containers and dev workflow write guide section on: productionising, containers and dev workflow #14
• scaling, availability, leases Scaling and availability docs with leader election advice #58
• packaging (yaml, helm, OLM) - write a page about operator packaging #12
• security concerns - Basic security guide for controllers #28
• manifest setup, for the harder rbac/netpol stuff Add a manifests section to help people deploying #49
• observability (depends on how much we put in first reconciler doc) main parts of controller guide #13

[clux]

definitely room for expansion on topics and breath here; kubebuilder book goes into a lot more details. otoh, we also cover a lot of this within docs.rs so personally thinking it might be most sensible to keep the webpage content to the grand concepts and how to combine them, and maybe link to docs.rs for certain specifics specifics to avoid creating a massive thing to maintain (at least initially).

anyway, happy to help review sketches for this if people have time. it should have its own dedicated folder under docs and its own category under the listed markdown docs in the mkdocs.yml nav section

[clux]

the world is in a shit place this week and don't feel like tackling anything complicated. so will instead try to compose my thoughts and start writing something here.

[clux]

merged the first 2 documents today. going to try to finish off the introductory application and reconciler section and then open up bits for external contribution to try and speed this up.

some things that have been very helpful:

• writing stubs marked as WIP but not adding them to mkdocs.yml's nav to hide them (but keep working links to them)
• material-mkdocs reference
  • we support most stuff there: mermaid diagrams, footnotes, tables, admonitions, abbreviations, etc. use it!
• markdown links from footer:

--8<-- "includes/abbreviations.md"
--8<-- "includes/links.md"

[clux]

going to take a bit of a break from this a bit now. if anyone wants to help out with other items, please lemme know!