Principle:Kserve Kserve CRD Schema Validation
| Knowledge Sources | |
|---|---|
| Domains | Kubernetes, API_Governance, Schema_Validation |
| Last Updated | 2026-02-13 00:00 GMT |
Overview
A declarative API contract enforcement mechanism that uses OpenAPI v3 schemas embedded in Custom Resource Definitions to validate resource structure at admission time.
Description
CRD Schema Validation leverages the OpenAPI v3 schema specification within Kubernetes CustomResourceDefinition objects to enforce structural contracts on custom resources before they are persisted to etcd. Each CRD declares the complete shape of its API -- required fields, allowed types, enum constraints, pattern matching, and nested object structures -- so that the Kubernetes API server rejects malformed resources at admission time without requiring custom webhook logic.
In KServe, every custom resource type (InferenceService, InferenceGraph, ServingRuntime, ClusterServingRuntime, ClusterStorageContainer, TrainedModel, LLMInferenceService, LLMInferenceServiceConfig, LocalModelCache, LocalModelNode, LocalModelNodeGroup) ships with a full CRD schema that documents and enforces the allowed API surface. Minimal CRD variants strip the schema for environments with tight etcd size constraints, trading validation strictness for smaller resource footprint.
Usage
Apply this principle when defining or extending Kubernetes custom resources for any operator. It is relevant whenever:
- New fields are added to a CRD API and must be validated before reaching the controller
- Multiple API versions coexist and conversion webhooks must preserve schema compatibility
- Cluster administrators need to choose between full validation (full CRDs) and minimal footprint (minimal CRDs)
Theoretical Basis
# CRD schema validation flow (NOT implementation code)
1. User submits a custom resource (e.g., InferenceService YAML) to the API server
2. API server locates the matching CRD for the resource's group/version/kind
3. OpenAPI v3 schema from the CRD is applied:
a. Required fields checked (e.g., spec.predictor is required)
b. Type constraints enforced (string, integer, boolean, object, array)
c. Enum values validated (e.g., protocol must be "v1" or "v2")
d. Pattern regexes applied (e.g., DNS-compatible names)
e. Nested object schemas recursively validated
4. If validation passes → resource proceeds to webhooks and then storage
5. If validation fails → API server returns 422 Unprocessable Entity
Full CRD vs Minimal CRD:
Full: Complete OpenAPI v3 schema → strict validation, larger etcd footprint
Minimal: Reduced schema (x-kubernetes-preserve-unknown-fields) → permissive, smaller footprint
Related Pages
Implemented By
- Implementation:Kserve_Kserve_LLMInferenceServiceConfig_CRD
- Implementation:Kserve_Kserve_LLMInferenceService_Full_CRD
- Implementation:Kserve_Kserve_InferenceService_Full_CRD
- Implementation:Kserve_Kserve_InferenceGraph_Full_CRD
- Implementation:Kserve_Kserve_ClusterServingRuntime_CRD
- Implementation:Kserve_Kserve_ServingRuntime_CRD
- Implementation:Kserve_Kserve_ClusterStorageContainer_CRD
- Implementation:Kserve_Kserve_LocalModelNodeGroup_CRD
- Implementation:Kserve_Kserve_LocalModelCache_CRD
- Implementation:Kserve_Kserve_LocalModelNode_CRD
- Implementation:Kserve_Kserve_TrainedModel_Full_CRD