Everything in Kubernetes is an API object. Pods, Services, Deployments, Secrets, Nodes — even RBAC rules — are all resources exposed through a RESTful API. Understanding the API model is essential: it's the foundation for writing manifests, building operators, and debugging any issue.

1. API Groups — Organizing the API

The Kubernetes API isn't one flat list. It's organized into API groups — logical collections of related resources. This structure enables independent versioning and extension.

The Two API Paths

Common API Groups

# Discover all API groups on your cluster:
kubectl api-versions

# List resources in a specific group:
kubectl api-resources --api-group=apps
# NAME         SHORTNAMES   APIVERSION   NAMESPACED   KIND
# deployments  deploy       apps/v1      true         Deployment
# statefulsets sts          apps/v1      true         StatefulSet
# daemonsets   ds           apps/v1      true         DaemonSet
# replicasets  rs           apps/v1      true         ReplicaSet

2. GVK and GVR — The Coordinate System

Every Kubernetes resource type can be uniquely identified two ways:

GVK — Group, Version, Kind (the "type")

Identifies a type of object. Used in YAML manifests and by controllers internally.

# In a manifest, you declare GVK:
apiVersion: apps/v1      # Group: apps, Version: v1
kind: Deployment         # Kind: Deployment

# For core group:
apiVersion: v1           # Group: (core), Version: v1
kind: Pod                # Kind: Pod

GVR — Group, Version, Resource (the "URL")

Identifies the REST path to interact with that type. Used by clients to construct API URLs.

# GVR maps to the API URL:
# Group: apps, Version: v1, Resource: deployments
# → /apis/apps/v1/namespaces/{ns}/deployments/{name}

# Group: (core), Version: v1, Resource: pods
# → /api/v1/namespaces/{ns}/pods/{name}

GVK ↔ GVR Mapping

3. Object Structure — The Spec/Status Convention

Every Kubernetes object follows the same four-part structure:

apiVersion: apps/v1          # ← GV (group + version)
kind: Deployment             # ← K (kind)
metadata:                    # ← Identity + system annotations
  name: nginx
  namespace: default
  labels:
    app: nginx
  uid: a1b2c3d4-...
  resourceVersion: "12345"
  creationTimestamp: "2024-01-15T10:00:00Z"
spec:                        # ← DESIRED state (user-controlled)
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    ...
status:                      # ← ACTUAL state (system-controlled)
  availableReplicas: 3
  readyReplicas: 3
  conditions:
    - type: Available
      status: "True"

The Four Sections

Key Metadata Fields

resourceVersion and Optimistic Concurrency

Every object has a resourceVersion (an opaque string, actually the etcd ModRevision). When you update an object, you must include the current resourceVersion. If it doesn't match (someone else updated it), the API server returns 409 Conflict.

# This is why "kubectl apply" can fail with:
# "the object has been modified; please apply your changes to the latest version"
# Solution: re-read the object, re-apply your changes, try again.

4. Subresources

Some resources expose subresources — separate API endpoints nested under the main resource path. They have their own access control and semantics.

5. API Versioning & Maturity

Kubernetes resources evolve through version stages:

# Check which versions are available for a resource:
kubectl api-resources | grep deployment
# deployments   deploy   apps/v1   true   Deployment

# See all versions the server supports for a group:
kubectl api-versions | grep apps
# apps/v1

Version Conversion

The API server can store objects in one version and serve them in another. For example, a CRD might store as v1 but serve as v1 and v2. Conversion webhooks handle the transformation between versions.

6. REST URL Patterns

Once you understand GVR, you can predict any API URL:

Namespaced Resources

# List all pods in namespace "production":
GET /api/v1/namespaces/production/pods

# Get a specific pod:
GET /api/v1/namespaces/production/pods/nginx-abc123

# Create a deployment:
POST /apis/apps/v1/namespaces/default/deployments

# Update status subresource:
PUT /apis/apps/v1/namespaces/default/deployments/nginx/status

# Watch for changes:
GET /api/v1/namespaces/default/pods?watch=true&resourceVersion=9876

Cluster-Scoped Resources

# List all nodes (no namespace):
GET /api/v1/nodes

# Get a specific ClusterRole:
GET /apis/rbac.authorization.k8s.io/v1/clusterroles/admin

# List PersistentVolumes:
GET /api/v1/persistentvolumes

Namespaced vs Cluster-Scoped

# Quick check: is a resource namespaced?
kubectl api-resources --namespaced=true   # namespaced resources
kubectl api-resources --namespaced=false  # cluster-scoped resources

7. Labels & Selectors — How Objects Find Each Other

Labels are the connective tissue of Kubernetes. They're how Services find Pods, ReplicaSets track their Pods, and NetworkPolicies target workloads.

Label Syntax

metadata:
  labels:
    app: nginx                    # simple key=value
    environment: production
    app.kubernetes.io/name: nginx # recommended structured labels
    app.kubernetes.io/version: "1.25"
    app.kubernetes.io/component: frontend

Selector Types

# kubectl label selectors:
kubectl get pods -l app=nginx
kubectl get pods -l 'environment in (prod,staging)'
kubectl get pods -l app=nginx,version=v2

# In YAML (matchLabels + matchExpressions):
selector:
  matchLabels:
    app: nginx
  matchExpressions:
    - key: environment
      operator: In
      values: [production, staging]

Labels vs Annotations

Summary