API Discovery and OpenAPI Schema
What you'll learn: How clients find out what's available in the Kubernetes API and validate their requests before sending them.
When you interact with a Kubernetes cluster, you need to know what resources exist, what versions they support, and how to structure your requests correctly. API discovery is the process by which clients (like kubectl or custom applications) learn what the cluster offers without hardcoding this knowledge.
How Discovery Works
Think of API discovery like walking into a library with a computerized catalog. Instead of memorizing every book, you query the catalog to see what's available, where it is, and how it's organized.
Kubernetes exposes discovery endpoints at the API server that clients can query:
/apiand/apislist available API groups- Each group endpoint reveals supported versions
- Version endpoints list available resources (Pods, Services, etc.)
This dynamic discovery means your client tools work across different Kubernetes versions and with custom resources without needing updates.
OpenAPI Schema: The Validation Blueprint
Once you know what resources exist, you need to know their exact structure. The OpenAPI schema (formerly Swagger) provides a machine-readable specification describing:
- Required and optional fields
- Field data types (string, integer, object)
- Valid values and constraints
- Nested object structures
The API server exposes this schema at /openapi/v2 or /openapi/v3. When you run kubectl explain pod.spec.containers, you're querying this schema. It enables client-side validation, preventing malformed requests from reaching the server and providing helpful error messages.
Key Takeaway: API discovery lets clients dynamically learn what resources a cluster supports, while the OpenAPI schema provides the exact specification needed to construct valid requests—together they enable flexible, self-documenting API interactions without hardcoded assumptions.