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!

[clux]

did two pages on this recently since questions about them kept coming up:

• testing - took a while
• security - easier

kind of want to do a few more while i am in the zone, but not sure which one is most value. thinking possibly one of the hard ones

• containerisation/productionising via write guide section on: productionising, containers and dev workflow #14
• signal handling (look at new approaches that can propagate signal results up / maybe david's elegantdeparture lib)
• packaging/OLM stuff

all of these require some research though, but they feel like the most important ones

EDIT: or maybe just finish off the stability policy in #18 now that we have more useful data on how quickly people upgrade (see bottom of crates/kube)

[clux]

As as bit of a status report here, have revamped a lot of pages in the past couple of months, and have more of a plan for the final sections.

Recently created pages:

• Generics - one solution to one generic code problem
• Manifests - most common questions about how to write yaml
• GC - finalizers/ownerrefs - to have something to point to with questions
• Streams - about the unstable streams interface
• Optimization - the types of benefits you can get from tweaking streams and controller/watcher options - which led to a bunch of tweaks in kube upstream

also revamped

• Relations - to include better mapper examples for external docs + linking to how to do it with streams
• Schemas - revamped to be a bit more of anoverview

Also some improvements to the site itself has happened so there's now an edit icon on each page that puts you in a fork/edit view on github for hopefully quick feedback on typos etc.