From 21579cfd7df2f43129906e3e51df1093aefc80af Mon Sep 17 00:00:00 2001
From: Matthew Mellor <matthew@mellor.earth>
Date: Wed, 1 Apr 2026 12:56:07 -0500
Subject: [PATCH] feat(standards): add Kubernetes standards page for kustomize
 and kubeconform

Add Kubernetes standards documentation covering Kustomize overlay
validation and kubeconform schema validation. Update standards index
with Kubernetes in per-language links.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 content/docs/standards/_index.md     |  1 +
 content/docs/standards/kubernetes.md | 62 ++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)
 create mode 100644 content/docs/standards/kubernetes.md

diff --git a/content/docs/standards/_index.md b/content/docs/standards/_index.md
index d25cd50..c7f7d58 100644
--- a/content/docs/standards/_index.md
+++ b/content/docs/standards/_index.md
@@ -52,6 +52,7 @@ Each Makefile target runs the relevant tools for all languages declared in `.dev
 - [Rust Standards](/docs/standards/rust/) -- clippy, rustfmt, cargo-audit, cargo-deny, cargo test
 - [Swift Standards](/docs/standards/swift/) -- SwiftLint, swift-format, swift test, xcodebuild
 - [Kotlin Standards](/docs/standards/kotlin/) -- ktlint, detekt, Gradle, Android Lint
+- [Kubernetes Standards](/docs/standards/kubernetes/) -- kustomize, kubeconform
 - [Universal Security](/docs/standards/universal/) -- trivy, gitleaks, git-cliff
 
 ## Consistent Page Structure
diff --git a/content/docs/standards/kubernetes.md b/content/docs/standards/kubernetes.md
new file mode 100644
index 0000000..0070ecd
--- /dev/null
+++ b/content/docs/standards/kubernetes.md
@@ -0,0 +1,62 @@
+---
+title: "Kubernetes"
+linkTitle: "Kubernetes"
+weight: 55
+description: "Kubernetes tooling standards: kustomize and kubeconform for manifest validation."
+---
+
+Kubernetes projects use kustomize for rendering overlays and kubeconform for schema validation. Detection is automatic based on `kustomization.yaml` file presence -- no `.devrail.yml` language entry is needed.
+
+## Tools
+
+| Category | Tool | Purpose |
+|---|---|---|
+| Manifest Validation | kustomize build | Render overlays, catch structural errors |
+| Schema Validation | kubeconform | Validate against Kubernetes API schemas |
+
+All tools are pre-installed in the dev-toolchain container. Do not install them on the host.
+
+## Configuration
+
+### kustomize
+
+No config file required. Reads `kustomization.yaml` in each overlay directory.
+
+### kubeconform
+
+No config file required. Validates against built-in Kubernetes schemas. Override the target version if needed:
+
+```bash
+kustomize build overlays/production | kubeconform -strict -kubernetes-version 1.29.0
+```
+
+For CRDs, add additional schema sources:
+
+```bash
+kubeconform -strict \
+  -schema-location default \
+  -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json'
+```
+
+## Makefile Targets
+
+| Target | Command | Description |
+|---|---|---|
+| `make lint` | `kustomize build <dir> \| kubeconform -strict -summary` | Validate each Kustomize overlay |
+
+Detection is automatic. Every directory containing `kustomization.yaml` is validated independently.
+
+## Pre-Commit Hooks
+
+### CI-Only (too slow for local hooks)
+
+Kustomize validation runs via `make lint` in CI. It is not configured as a local pre-commit hook because `kustomize build` may need to fetch remote bases.
+
+## Notes
+
+- **Kustomize is a companion tool, not a language.** No `.devrail.yml` entry needed. Auto-detected by `kustomization.yaml` presence.
+- **kubeconform replaces kubeval.** kubeval is deprecated. kubeconform is the maintained successor with better CRD support.
+- **Each overlay is validated independently.** The Makefile finds all `kustomization.yaml` files and validates each directory.
+- **CRD validation requires schema sources.** Core Kubernetes resources are validated by default. CRDs need additional schema locations configured.
+- **All tools are pre-installed in the dev-toolchain container.** Do not install them on the host.
+- For cross-cutting coding practices and git workflow standards, see [Coding Practices](/docs/standards/practices/).