From e78b5af686bf0e424414ba11ee7ef82704c2e5f3 Mon Sep 17 00:00:00 2001 From: Simon Koudijs Date: Mon, 5 Oct 2026 12:33:24 +0000 Subject: [PATCH] docs(glossary): explain kubectl, apply, last-applied configuration, managed fields and SSA Adds a 'How Kubernetes records writes' section so the machinery the editor protects, and the write paths a page shares an object with, are defined for frontend readers. States why krm-stream saves with conditional merge patches rather than server-side apply. Co-Authored-By: Claude Opus 5.5 --- docs/glossary.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/glossary.md b/docs/glossary.md index a5b7140..c966c1e 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -63,6 +63,46 @@ formats can carry errors. `connectNativeWatch` reads native watch JSON; `connect and delivers the current SSE protocol. A host can separately proxy native Kubernetes access with a session cookie while keeping cluster credentials server-side. +## How Kubernetes records writes + +A page rarely edits an object alone. The same object is usually also written by `kubectl`, a CI +pipeline, a GitOps tool or a controller, and Kubernetes keeps some bookkeeping about those writes in +the object itself. + +**kubectl** is Kubernetes' command-line client, and talks to the same API a page reaches through a +proxy or the gateway. `kubectl get --watch` lists and watches; `kubectl edit`, `patch` and `apply` +write. An object a page shows may change under an open draft because someone ran one of these. + +**`kubectl apply`** writes a configuration file declaratively: the file says what the fields should +be, and kubectl works out the change. Without `--server-side` this is **client-side apply**: kubectl +compares the file with the live object and with the configuration it applied last time, so it knows +which fields to delete when they disappear from the file. A later `kubectl apply` of the same file +resets any field the file sets, including one a person changed in the browser. + +**Last-applied-configuration annotation** (`kubectl.kubernetes.io/last-applied-configuration`) is +where client-side apply keeps that previous configuration: a JSON copy of the last file applied. It +is bookkeeping for kubectl, not content. Changing it changes what the next `kubectl apply` deletes. +Every gateway projection removes it. Native objects carry it, so the editor keeps it read-only under +every policy, and host checks refuse a patch that touches it. + +**Managed fields** (`metadata.managedFields`) record, for each field, which **field manager** last +set it and how: kubectl, a controller or a host's save endpoint, by update or by apply. The API +server maintains them on every write. They are large and not meant for people: projections remove +them and the editor keeps them read-only. A merge patch from a save endpoint is recorded as an update +by that endpoint's manager. + +**Server-side apply (SSA)** moves apply into the API server. A client sends only the fields it wants +to own, under a field manager name (`kubectl apply --server-side`, or a PATCH with +`application/apply-patch+yaml`), and the server merges them using managed fields rather than the +last-applied annotation. If another manager owns a field and set it to a different value, the apply +fails with an **ownership conflict** unless it forces ownership. A field the manager stops sending is +removed, unless another manager also owns it. A browser save takes ownership of the fields it +changes, so the next server-side apply of a file setting one of them to another value conflicts +instead of silently resetting it. krm-stream saves with JSON merge patches and a resourceVersion precondition instead. SSA +detects disputes between managers, not a person saving from an out-of-date view, and one manager +shared by every browser user provides no locking between them. An SSA write path is a separate host +design; see [why SSA is an option, not a guarantee](proposals/0005-kubernetes-stream-and-save-semantics.md#why-ssa-is-an-option-not-a-replacement-guarantee). + ## Optional editing and saving **Server and draft** are separate objects in the editor: the latest delivered authoritative view and