mkmik · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/docs/map/README.md b/docs/map/README.md
@@ -0,0 +1,25 @@
+# Coverage map
+
+This directory is a [todography](https://github.com/mkmik/todography) map of
+which Kubernetes kinds have a template in `k8s.libsonnet`.
+
+- Each directory is an *area*: one built-in API group, or one add-on project.
+  Its `AREA.md` says which.
+- Each other `.md` file is one kind. `status = "done"` means it has a
+  template; a missing status means it doesn't yet; `dropped` means it is
+  created by controllers or API calls, so a template would add little.
+- Built-in kinds come from Kubernetes v1.37. Add-on areas cover the projects
+  the library supports plus other widely used ones. Each lists the kinds in
+  the project's CRDs, and its `AREA.md` names the release and CRD source they
+  were checked against. Add-on APIs change
+  versions on their own schedule, so re-check them when bumping.
+- `lib/` holds the shared pieces the templates are built on.
+
+```sh
+todography lint        # check the map
+todography next --all  # what to add next
+todography open        # look at it in a browser
+```
+
+When you add a template to `k8s.libsonnet`, mark its kind as done here in the
+same commit.
diff --git a/docs/map/admission/AREA.md b/docs/map/admission/AREA.md
@@ -0,0 +1,7 @@
++++
+title = "admissionregistration.k8s.io"
+band = "cluster"
+summary = "Admission webhooks and admission policies"
++++
+
+No templates in `k8s.libsonnet` yet. Kinds without a template still work through `k8s.Object { apiVersion, kind }`.
diff --git a/docs/map/admission/mutatingadmissionpolicy.md b/docs/map/admission/mutatingadmissionpolicy.md
@@ -0,0 +1,17 @@
++++
+title = "MutatingAdmissionPolicy"
+summary = "In-process mutation rules written in CEL"
+aka = ["admissionregistration.k8s.io/v1 MutatingAdmissionPolicy"]
+kind = "builtin"
+intent = "aspiration"
+research = "done"
+status = "todo"
+
+[[needs]]
+on = "/lib/cluster-scoped"
+why = "Cluster-wide: must not pick up the shared namespace"
++++
+
+`apiVersion: admissionregistration.k8s.io/v1`, `kind: MutatingAdmissionPolicy`, cluster-wide.
+
+New in v1; wait and see how much it is used.
diff --git a/docs/map/admission/mutatingadmissionpolicybinding.md b/docs/map/admission/mutatingadmissionpolicybinding.md
@@ -0,0 +1,15 @@
++++
+title = "MutatingAdmissionPolicyBinding"
+summary = "Turns a MutatingAdmissionPolicy on for some objects"
+aka = ["admissionregistration.k8s.io/v1 MutatingAdmissionPolicyBinding"]
+kind = "builtin"
+intent = "aspiration"
+research = "done"
+status = "todo"
+
+[[needs]]
+on = "/lib/cluster-scoped"
+why = "Cluster-wide: must not pick up the shared namespace"
++++
+
+`apiVersion: admissionregistration.k8s.io/v1`, `kind: MutatingAdmissionPolicyBinding`, cluster-wide.
diff --git a/docs/map/admission/mutatingwebhookconfiguration.md b/docs/map/admission/mutatingwebhookconfiguration.md
@@ -0,0 +1,18 @@
++++
+title = "MutatingWebhookConfiguration"
+summary = "Sends objects to a webhook that can change them"
+aka = ["admissionregistration.k8s.io/v1 MutatingWebhookConfiguration"]
+kind = "builtin"
+intent = "goal"
+research = "done"
+status = "todo"
+milestone = "m2"
+
+[[needs]]
+on = "/lib/cluster-scoped"
+why = "Cluster-wide: must not pick up the shared namespace"
++++
+
+`apiVersion: admissionregistration.k8s.io/v1`, `kind: MutatingWebhookConfiguration`, cluster-wide.
+
+Ships with every operator that has a mutating webhook.
diff --git a/docs/map/admission/validatingadmissionpolicy.md b/docs/map/admission/validatingadmissionpolicy.md
@@ -0,0 +1,18 @@
++++
+title = "ValidatingAdmissionPolicy"
+summary = "In-process validation rules written in CEL"
+aka = ["admissionregistration.k8s.io/v1 ValidatingAdmissionPolicy"]
+kind = "builtin"
+intent = "goal"
+research = "done"
+status = "todo"
+milestone = "m2"
+
+[[needs]]
+on = "/lib/cluster-scoped"
+why = "Cluster-wide: must not pick up the shared namespace"
++++
+
+`apiVersion: admissionregistration.k8s.io/v1`, `kind: ValidatingAdmissionPolicy`, cluster-wide.
+
+v1 since Kubernetes 1.30.
diff --git a/docs/map/admission/validatingadmissionpolicybinding.md b/docs/map/admission/validatingadmissionpolicybinding.md
@@ -0,0 +1,16 @@
++++
+title = "ValidatingAdmissionPolicyBinding"
+summary = "Turns a ValidatingAdmissionPolicy on for some objects"
+aka = ["admissionregistration.k8s.io/v1 ValidatingAdmissionPolicyBinding"]
+kind = "builtin"
+intent = "goal"
+research = "done"
+status = "todo"
+milestone = "m2"
+
+[[needs]]
+on = "/lib/cluster-scoped"
+why = "Cluster-wide: must not pick up the shared namespace"
++++
+
+`apiVersion: admissionregistration.k8s.io/v1`, `kind: ValidatingAdmissionPolicyBinding`, cluster-wide.
diff --git a/docs/map/admission/validatingwebhookconfiguration.md b/docs/map/admission/validatingwebhookconfiguration.md
@@ -0,0 +1,18 @@
++++
+title = "ValidatingWebhookConfiguration"
+summary = "Sends objects to a webhook that can reject them"
+aka = ["admissionregistration.k8s.io/v1 ValidatingWebhookConfiguration"]
+kind = "builtin"
+intent = "goal"
+research = "done"
+status = "todo"
+milestone = "m2"
+
+[[needs]]
+on = "/lib/cluster-scoped"
+why = "Cluster-wide: must not pick up the shared namespace"
++++
+
+`apiVersion: admissionregistration.k8s.io/v1`, `kind: ValidatingWebhookConfiguration`, cluster-wide.
+
+Ships with every operator that has a validating webhook.
diff --git a/docs/map/apiextensions/AREA.md b/docs/map/apiextensions/AREA.md
@@ -0,0 +1,7 @@
++++
+title = "apiextensions.k8s.io"
+band = "cluster"
+summary = "CustomResourceDefinitions"
++++
+
+Templates live in `k8s.libsonnet` under `k8s['apiextensions.k8s.io'].v1`.
diff --git a/docs/map/apiextensions/customresourcedefinition.md b/docs/map/apiextensions/customresourcedefinition.md
@@ -0,0 +1,18 @@
++++
+title = "CustomResourceDefinition"
+summary = "Adds a new kind to the API"
+aka = ["apiextensions.k8s.io/v1 CustomResourceDefinition", "crd"]
+kind = "builtin"
+intent = "goal"
+research = "done"
+status = "done"
+refs = ["k8s.libsonnet"]
+
+[[needs]]
+on = "/lib/cluster-scoped"
+why = "Cluster-wide: must not pick up the shared namespace"
++++
+
+`apiVersion: apiextensions.k8s.io/v1`, `kind: CustomResourceDefinition`, cluster-wide.
+
+Template only.
diff --git a/docs/map/apiregistration/AREA.md b/docs/map/apiregistration/AREA.md
@@ -0,0 +1,7 @@
++++
+title = "apiregistration.k8s.io"
+band = "cluster"
+summary = "Aggregated API servers"
++++
+
+No templates in `k8s.libsonnet` yet. Kinds without a template still work through `k8s.Object { apiVersion, kind }`.
diff --git a/docs/map/apiregistration/apiservice.md b/docs/map/apiregistration/apiservice.md
@@ -0,0 +1,17 @@
++++
+title = "APIService"
+summary = "Plugs an extra API server into the main one"
+aka = ["apiregistration.k8s.io/v1 APIService"]
+kind = "builtin"
+intent = "aspiration"
+research = "done"
+status = "todo"
+
+[[needs]]
+on = "/lib/cluster-scoped"
+why = "Cluster-wide: must not pick up the shared namespace"
++++
+
+`apiVersion: apiregistration.k8s.io/v1`, `kind: APIService`, cluster-wide.
+
+Ships with metrics-server and similar.
diff --git a/docs/map/apiserver-internal/AREA.md b/docs/map/apiserver-internal/AREA.md
@@ -0,0 +1,7 @@
++++
+title = "internal.apiserver.k8s.io"
+band = "runtime"
+summary = "Storage versions (alpha)"
++++
+
+Every kind in this group is created by the cluster or by API calls, so none of them needs a template.
diff --git a/docs/map/apiserver-internal/storageversion.md b/docs/map/apiserver-internal/storageversion.md
@@ -0,0 +1,17 @@
++++
+title = "StorageVersion"
+summary = "Which version each API server stores"
+aka = ["internal.apiserver.k8s.io/v1alpha1 StorageVersion"]
+kind = "builtin"
+intent = "aspiration"
+research = "done"
+status = "dropped"
+
+[[needs]]
+on = "/lib/cluster-scoped"
+why = "Cluster-wide: must not pick up the shared namespace"
++++
+
+`apiVersion: internal.apiserver.k8s.io/v1alpha1`, `kind: StorageVersion`, cluster-wide.
+
+Alpha, and written by API servers.
diff --git a/docs/map/apps/AREA.md b/docs/map/apps/AREA.md
@@ -0,0 +1,7 @@
++++
+title = "apps"
+band = "workloads"
+summary = "Deployments, StatefulSets and DaemonSets"
++++
+
+Templates live in `k8s.libsonnet` under `k8s.apps.v1`.
diff --git a/docs/map/apps/controllerrevision.md b/docs/map/apps/controllerrevision.md
@@ -0,0 +1,13 @@
++++
+title = "ControllerRevision"
+summary = "A saved revision of a StatefulSet or DaemonSet"
+aka = ["apps/v1 ControllerRevision"]
+kind = "builtin"
+intent = "aspiration"
+research = "done"
+status = "dropped"
++++
+
+`apiVersion: apps/v1`, `kind: ControllerRevision`.
+
+Created by the cluster or by API calls, not written by hand, so a template would add little.
diff --git a/docs/map/apps/daemonset.md b/docs/map/apps/daemonset.md
@@ -0,0 +1,25 @@
++++
+title = "DaemonSet"
+summary = "One pod on every node"
+aka = ["apps/v1 DaemonSet", "ds"]
+kind = "builtin"
+intent = "goal"
+research = "done"
+refs = ["k8s.libsonnet"]
+
+[[feature]]
+id = "template"
+title = "Template with apiVersion and kind"
+status = "done"
+
+[[feature]]
+id = "pod-overlays"
+title = "Pod template gets the shared PodTemplateSpec overlays"
+status = "done"
+
+[[needs]]
+on = "/lib/pod-template"
+why = "Its pods get the shared overlays"
++++
+
+`apiVersion: apps/v1`, `kind: DaemonSet`.
diff --git a/docs/map/apps/deployment.md b/docs/map/apps/deployment.md
@@ -0,0 +1,27 @@
++++
+title = "Deployment"
+summary = "Keeps a set of identical pods running"
+aka = ["apps/v1 Deployment", "deploy"]
+kind = "builtin"
+intent = "goal"
+research = "done"
+refs = ["k8s.libsonnet"]
+
+[[feature]]
+id = "template"
+title = "Template with apiVersion and kind"
+status = "done"
+
+[[feature]]
+id = "pod-overlays"
+title = "Pod template gets the shared PodTemplateSpec overlays"
+status = "done"
+
+[[needs]]
+on = "/lib/pod-template"
+why = "Its pods get the shared overlays"
++++
+
+`apiVersion: apps/v1`, `kind: Deployment`.
+
+The main workload kind.
diff --git a/docs/map/apps/replicaset.md b/docs/map/apps/replicaset.md
@@ -0,0 +1,13 @@
++++
+title = "ReplicaSet"
+summary = "Keeps N copies of a pod"
+aka = ["apps/v1 ReplicaSet", "rs"]
+kind = "builtin"
+intent = "aspiration"
+research = "done"
+status = "dropped"
++++
+
+`apiVersion: apps/v1`, `kind: ReplicaSet`.
+
+Created and managed by Deployments.
diff --git a/docs/map/apps/statefulset.md b/docs/map/apps/statefulset.md
@@ -0,0 +1,32 @@
++++
+title = "StatefulSet"
+summary = "Pods with stable names and their own storage"
+aka = ["apps/v1 StatefulSet", "sts"]
+kind = "builtin"
+intent = "goal"
+research = "done"
+refs = ["k8s.libsonnet"]
+
+[[feature]]
+id = "template"
+title = "Template with apiVersion and kind"
+status = "done"
+
+[[feature]]
+id = "pod-overlays"
+title = "Pod template gets the shared PodTemplateSpec overlays"
+status = "done"
+
+[[feature]]
+id = "volume-claim-templates"
+title = "volumeClaimTemplates_ keyed by metadata.name"
+status = "done"
+
+[[needs]]
+on = "/lib/pod-template"
+why = "Its pods get the shared overlays"
++++
+
+`apiVersion: apps/v1`, `kind: StatefulSet`.
+
+`serviceName` is optional (documented so since Kubernetes v1.33), so the template doesn't require it.
diff --git a/docs/map/argo-cd/AREA.md b/docs/map/argo-cd/AREA.md
@@ -0,0 +1,9 @@
++++
+title = "Argo CD"
+band = "addons"
+summary = "argoproj.io: GitOps deployment"
++++
+
+No templates in `k8s.libsonnet` yet. Kinds without a template still work through `k8s.Object { apiVersion, kind }`.
+
+Checked against Argo CD v3.5.5: https://github.com/argoproj/argo-cd/tree/v3.5.5/manifests/crds. Argo Rollouts and Argo Workflows share the argoproj.io group but are separate projects, not mapped.
diff --git a/docs/map/argo-cd/application.md b/docs/map/argo-cd/application.md
@@ -0,0 +1,14 @@
++++
+title = "Application"
+summary = "Something Argo CD deploys from Git and keeps in sync"
+aka = ["argoproj.io/v1alpha1 Application", "app"]
+kind = "crd"
+intent = "goal"
+research = "done"
+status = "todo"
+milestone = "m1"
++++
+
+`apiVersion: argoproj.io/v1alpha1`, `kind: Application`.
+
+Very common in GitOps repositories.
diff --git a/docs/map/argo-cd/applicationset.md b/docs/map/argo-cd/applicationset.md
@@ -0,0 +1,11 @@
++++
+title = "ApplicationSet"
+summary = "Generates Applications from a template"
+aka = ["argoproj.io/v1alpha1 ApplicationSet", "appset"]
+kind = "crd"
+intent = "aspiration"
+research = "done"
+status = "todo"
++++
+
+`apiVersion: argoproj.io/v1alpha1`, `kind: ApplicationSet`.
diff --git a/docs/map/argo-cd/appproject.md b/docs/map/argo-cd/appproject.md
@@ -0,0 +1,14 @@
++++
+title = "AppProject"
+summary = "Limits what a group of Argo CD Applications may deploy, and where"
+aka = ["argoproj.io/v1alpha1 AppProject", "appproj"]
+kind = "crd"
+intent = "goal"
+research = "done"
+status = "todo"
+milestone = "m1"
++++
+
+`apiVersion: argoproj.io/v1alpha1`, `kind: AppProject`.
+
+Very common in GitOps repositories.