API Machinery

Kubernetes organizes its API using a structured system of groups, versions, and resource types. Understanding this machinery is key to working with the API at a low level.

API Groups

Resources are organized into API groups. The core group (also called the legacy group) has no group name, while others use named groups:

# List all API groups
kubectl api-versions

# Core group resources (v1)
kubectl api-resources --api-group=""

# Apps group resources
kubectl api-resources --api-group=apps

# Networking group resources
kubectl api-resources --api-group=networking.k8s.io

GVR and GVK

Every resource in Kubernetes is identified by two triplets:

GVR (Group, Version, Resource): Used in REST API paths.

# GVR maps to API paths:
# Group: apps, Version: v1, Resource: deployments
# Path: /apis/apps/v1/namespaced/deployments

# Core group uses /api instead of /apis:
# Group: "", Version: v1, Resource: pods
# Path: /api/v1/namespaces/default/pods

# Explore the raw API
kubectl get --raw /apis/apps/v1
kubectl get --raw /api/v1/namespaces/default/pods

GVK (Group, Version, Kind): Identifies the object type in serialized form.

# Every Kubernetes object declares its GVK
kubectl get deployment myapp -o jsonpath='{.apiVersion} {.kind}'
# Output: apps/v1 Deployment

API Discovery

# List all resources with their API group and version
kubectl api-resources -o wide

# Get details about a specific resource
kubectl explain deployment
kubectl explain deployment.spec.strategy

# Check preferred version for a group
kubectl get --raw /apis/apps | python3 -m json.tool

Version Negotiation

kubectl automatically negotiates the correct API version:

# See which API version kubectl uses
kubectl get deployments -v=6 2>&1 | grep "GET"

# Force a specific API version with raw requests
kubectl get --raw /apis/apps/v1/deployments

Understanding GVR/GVK is essential when writing controllers, debugging API errors, or working with custom resources that extend the Kubernetes API.