docs: Add field errors in status convention#1177
Draft
MissingRoberto wants to merge 8 commits intomainfrom
Draft
docs: Add field errors in status convention#1177MissingRoberto wants to merge 8 commits intomainfrom
MissingRoberto wants to merge 8 commits intomainfrom
Conversation
Add comprehensive documentation establishing fieldErrors in status as the convention for reporting actionable runtime validation errors in Kubernetes-style resource APIs. This document: - Establishes fieldErrors as the standard pattern instead of custom validation endpoints (/test, /validate, /check) - Explains when to use fieldErrors vs admission validators - Provides implementation examples for controllers and frontend integration - Documents the two-phase validation strategy using dryRun=true - Explains why custom validation endpoints are an antipattern - Includes cross-references from related documentation Related to grafana/grafana#116662
Update documentation to reflect that dryRun=true is a standard Kubernetes API feature usable by any client (kubectl, curl, automation scripts), not just frontend applications. Add examples for kubectl and curl usage.
MissingRoberto
requested review from
IfSentient,
amalavet,
gttrigger,
radiohead and
ryantxu
Add comprehensive documentation explaining how to handle validation when frontend and backend have different rules, particularly when API versions evolve with different validation requirements. This document covers: - Problem scenario: branch name validation changes between versions - Solution: Use fieldErrors in status instead of duplicating validation - Backend implementation: version-specific admission vs version-agnostic runtime - Frontend implementation: don't duplicate validation logic - Migration strategy for version changes - Best practices for version-specific vs runtime validation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds comprehensive documentation establishing
fieldErrorsin status as the convention for reporting actionable runtime validation errors in Kubernetes-style resource APIs.Changes
docs/architecture/field-errors-in-status.md- Complete guide on the fieldErrors conventiondocs/README.md- Added to table of contentsdocs/admission-control.md- Explained distinction between admission (static) vs fieldErrors (runtime)docs/writing-a-reconciler.md- Reference for populating fieldErrors during reconciliationdocs/architecture/reconciliation.md- Note about fieldErrors in reconciliation flowKey Points
fieldErrorsas the standard pattern instead of custom validation endpoints (/test,/validate,/check)fieldErrorsvs admission validators (static vs runtime validation)dryRun=trueRelated
Related to grafana/grafana#116662