Discovery & OpenAPI

API discovery and OpenAPI are fundamental to how clients interact with Kubernetes. Discovery allows clients to dynamically find out what APIs are available without hardcoding resource types, while OpenAPI provides a complete specification of the API that enables code generation, validation, and tooling.

Think of API discovery like a restaurant menu—you can ask “what do you have?” and get a list of available items. OpenAPI is like a detailed recipe book that tells you exactly how to prepare each dish, what ingredients you need, and what the result should look like.

What is API Discovery?

API discovery is the process by which clients find out what APIs are available in a Kubernetes cluster. Instead of hardcoding resource types, clients can query the API server to discover:

• What API groups exist
• What resources are available in each group
• What API versions are supported
• What operations are allowed on each resource

This makes clients more flexible and allows them to work with custom resources (CRDs) without code changes.

Discovery Endpoints

Kubernetes provides several discovery endpoints:

API Groups

List all available API groups:

kubectl get --raw /apis

Returns a list of API groups with their versions and preferred versions.

API Resources

List resources in a specific API group:

# Core API group
kubectl get --raw /api/v1

# Apps API group
kubectl get --raw /apis/apps/v1

Returns a list of resources with their names, kinds, and supported verbs.

All API Resources

List all resources across all API groups:

kubectl api-resources

Shows a table of all resources with their API group, version, namespaced status, and kind.

How Discovery Works

1. Client queries API groups - Gets list of available API groups
2. Client queries resources - Gets list of resources in each group
3. Client uses resources - Can now interact with discovered resources

kubectl api-resources

The kubectl api-resources command is a convenient way to discover APIs:

# List all resources
kubectl api-resources

# List resources with details
kubectl api-resources -o wide

# Filter by API group
kubectl api-resources --api-group=apps

# Filter by kind
kubectl api-resources | grep Deployment

Output Format

NAME          SHORTNAMES   APIVERSION   NAMESPACED   KIND
pods          po           v1           true         Pod
services      svc          v1           true         Service
deployments   deploy       apps/v1      true         Deployment

• NAME - Resource name (plural)
• SHORTNAMES - Abbreviated names (e.g., po for pods)
• APIVERSION - API group and version
• NAMESPACED - Whether resource is namespaced
• KIND - Resource kind (singular, capitalized)

API Verbs

Each resource supports specific verbs (operations):

• get - Retrieve a single resource
• list - List multiple resources
• create - Create a new resource
• update - Update an existing resource
• patch - Partially update a resource
• delete - Delete a resource
• watch - Watch for changes
• proxy - Proxy requests to pods/services

You can check supported verbs:

kubectl api-resources --verbs=get,list

What is OpenAPI?

OpenAPI (formerly Swagger) is a specification for describing REST APIs. Kubernetes exposes its API specification in OpenAPI format, providing a complete description of:

• All available resources
• Resource schemas (fields, types, validation rules)
• API operations and parameters
• Response formats
• Authentication requirements

OpenAPI in Kubernetes

Kubernetes provides OpenAPI specifications for:

• API discovery - Finding available resources
• Schema validation - Validating resource definitions
• Code generation - Generating client libraries
• Documentation - API documentation
• Tooling - IDE support, validation tools

OpenAPI Endpoints

# Get OpenAPI specification
kubectl get --raw /openapi/v2

# Get OpenAPI v3 specification (if supported)
kubectl get --raw /openapi/v3

The OpenAPI spec is a large JSON document describing the entire API.

Using OpenAPI

Schema Validation

Tools can use OpenAPI to validate YAML files:

# Using kubeval (example)
kubeval deployment.yaml

# Using kubectl (built-in validation)
kubectl apply --dry-run=client -f deployment.yaml

Code Generation

OpenAPI can generate client libraries:

• client-go - Generated from OpenAPI
• kubernetes-client (Python) - Generated from OpenAPI
• kubernetes-client (Java) - Generated from OpenAPI

IDE Support

IDEs can use OpenAPI for:

• Autocomplete in YAML files
• Schema validation
• Documentation tooltips
• Error detection

API Resource Versions

Discovery shows available versions for each resource:

kubectl api-resources -o wide

Shows:

• APIVERSION - Preferred version
• Available versions can be queried via discovery

Preferred Versions

Each API group has a preferred version:

• Used when version is not specified
• Typically the most recent stable version
• Can be overridden in requests

Custom Resource Discovery

CRDs are automatically included in discovery:

When you create a CRD, it automatically appears in:

• kubectl api-resources
• Discovery endpoints
• OpenAPI specification

This allows tools and clients to work with custom resources without modification.

Discovery in Client Libraries

Client libraries use discovery to:

Dynamic Clients

Some clients can work with any resource type:

// client-go example
discoveryClient, _ := clientset.Discovery()
resources, _ := discoveryClient.ServerResources()

for _, resource := range resources {
    // Work with any discovered resource
}

Code Generation

Other clients generate code from OpenAPI:

# kubernetes-client (Python) example
from kubernetes import client, config

config.load_kube_config()
v1 = client.AppsV1Api()
# Type-safe access to apps/v1 resources

API Version Negotiation

Clients can negotiate API versions:

1. Query available versions - Via discovery
2. Select version - Choose appropriate version
3. Use version - Make requests with selected version

The API server handles conversion between versions automatically.

Practical Examples

Discovering Resources

# Find all deployment-related resources
kubectl api-resources | grep -i deploy

# Find resources in networking API group
kubectl api-resources --api-group=networking.k8s.io

# Find cluster-scoped resources
kubectl api-resources --namespaced=false

Using Discovery in Scripts

#!/bin/bash
# Get all resource types
RESOURCES=$(kubectl api-resources -o name)

for resource in $RESOURCES; do
    echo "Listing $resource..."
    kubectl get $resource --all-namespaces
done

OpenAPI for Validation

# Download OpenAPI spec
kubectl get --raw /openapi/v2 > openapi.json

# Use with validation tools
# (example with openapi-validator)
openapi-validator validate deployment.yaml --schema openapi.json

Best Practices

Use Discovery for Flexibility

• Don’t hardcode resource types
• Use discovery to find available resources
• Support custom resources automatically

Validate with OpenAPI

• Use OpenAPI schemas for validation
• Catch errors before applying to cluster
• Improve YAML editing experience

Check API Versions

• Use discovery to find supported versions
• Prefer stable (v1) versions
• Check for deprecated versions

Leverage Tooling

• Use IDE plugins that use OpenAPI
• Use validation tools
• Generate clients from OpenAPI

Key Takeaways

• API discovery allows clients to find available APIs dynamically
• Discovery endpoints provide lists of API groups, resources, and versions
• kubectl api-resources is a convenient discovery tool
• OpenAPI provides complete API specification for validation and code generation
• CRDs are automatically included in discovery
• Client libraries use discovery and OpenAPI for flexibility
• Discovery enables working with custom resources without code changes

See Also

• APIs & Access - Overview of Kubernetes API
• API Groups & Versions - Understanding API organization
• Clients: kubectl & client-go - Using discovery in clients
• CRDs - Custom resources and discovery