API Objects

In Kubernetes, everything is an API object. Understanding API objects is fundamental because they represent all the resources in your cluster—pods, services, deployments, nodes, and more. Every operation you perform creates, reads, updates, or deletes API objects.

Think of API objects like forms in a filing system. Each form (object) has a specific structure (schema), contains information (spec and status), and represents something real in your cluster (a running pod, a network service, etc.). Just as you fill out forms to request things, you create API objects to tell Kubernetes what you want.

What are API Objects?

API objects are persistent entities in Kubernetes that represent the state of your cluster. They have:

A type (kind) - What type of object it is (Pod, Service, Deployment)
Metadata - Name, labels, annotations, namespace
Spec - Desired state (what you want)
Status - Current state (what actually is)

Every resource in Kubernetes—whether it’s a pod running your application, a service exposing it, or a node in the cluster—is represented as an API object.

Object Structure

All API objects follow a consistent structure:

apiVersion: v1          # API group and version
kind: Pod              # Type of object
metadata:              # Object metadata
  name: my-pod         # Object name
  namespace: default   # Namespace (if namespaced)
  labels:              # Labels for selection
    app: my-app
  annotations:        # Annotations for metadata
    description: "My pod"
spec:                  # Desired state
  containers:
  - name: nginx
    image: nginx:1.21
status:                # Current state (read-only)
  phase: Running
  conditions: [...]

Metadata

Metadata includes:

name - Unique identifier within namespace
namespace - Namespace the object belongs to (if namespaced)
labels - Key-value pairs for selection and organization
annotations - Key-value pairs for metadata (not for selection)
uid - Unique identifier across all namespaces
resourceVersion - Version for optimistic concurrency
creationTimestamp - When object was created

Spec

The spec defines the desired state:

What you want the object to be
Written by you (or controllers)
Kubernetes tries to make reality match spec
Can be updated

Status

The status shows the current state:

What the object actually is
Written by Kubernetes (controllers, kubelet)
Read-only (you can’t directly modify)
Reflects actual cluster state

Object Lifecycle

graph LR A[Create Object] --> B[API Server Validates] B --> C[Stored in etcd] C --> D[Controllers Watch] D --> E[Controllers Reconcile] E --> F[Status Updated] F --> G{Desired = Actual?} G -->|No| E G -->|Yes| H[Steady State] H --> I[Update Spec] I --> E H --> J[Delete Object] J --> K[Object Removed] style A fill:#e1f5ff style C fill:#fff4e1 style E fill:#e8f5e9 style H fill:#e8f5e9 style K fill:#f3e5f5

Create - You create an object with a spec
Validate - API server validates the object
Store - Object stored in etcd
Watch - Controllers watch for the object
Reconcile - Controllers work to make status match spec
Update Status - Controllers update status as they work
Steady State - When spec matches status
Update/Delete - You can update spec or delete object

Core vs Workload Objects

Kubernetes objects are often categorized:

Core Objects

Fundamental objects that provide basic functionality:

Pods - Running containers
Services - Network services
ConfigMaps - Configuration data
Secrets - Sensitive data
Namespaces - Resource isolation
Nodes - Worker machines
PersistentVolumes - Storage

Workload Objects

Objects that manage pods:

Deployments - Manage ReplicaSets for stateless apps
ReplicaSets - Maintain desired number of pods
StatefulSets - Manage stateful applications
DaemonSets - Run pods on all/some nodes
Jobs - Run pods to completion
CronJobs - Scheduled jobs

Namespaced vs Cluster-Scoped

Objects are either namespaced or cluster-scoped:

Namespaced Objects

Exist within a namespace:

Pods, Services, Deployments
Must have unique name within namespace
Can have same name in different namespaces
Most objects are namespaced

Cluster-Scoped Objects

Exist at cluster level:

Nodes, PersistentVolumes
Must have unique name across entire cluster
Not in any namespace
Fewer objects are cluster-scoped

Object Operations

You can perform CRUD operations on objects:

Create

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
  - name: nginx
    image: nginx:1.21

kubectl create -f pod.yaml

Read

# Get object
kubectl get pod my-pod

# Get with details
kubectl get pod my-pod -o yaml

Update

# Update from file
kubectl apply -f pod.yaml

# Edit object
kubectl edit pod my-pod

# Patch object
kubectl patch pod my-pod -p '{"spec":{"containers":[{"name":"nginx","image":"nginx:1.22"}]}}'

Delete

kubectl delete pod my-pod

Object Relationships

Objects often reference other objects:

graph TB Deployment --> ReplicaSet ReplicaSet --> Pod Service --> Pod Pod --> ConfigMap Pod --> Secret Pod --> PersistentVolumeClaim PersistentVolumeClaim --> PersistentVolume style Deployment fill:#e1f5ff style ReplicaSet fill:#fff4e1 style Pod fill:#e8f5e9 style Service fill:#f3e5f5

Deployments create ReplicaSets
ReplicaSets create Pods
Services select Pods by labels
Pods reference ConfigMaps and Secrets
Pods use PersistentVolumeClaims for storage

Object Ownership

Objects can have owners:

Owner references - Links to parent objects
Cascading deletion - Deleting owner deletes owned objects
Garbage collection - Removes objects without owners

Example: Deleting a Deployment deletes its ReplicaSet, which deletes its Pods.

Topics

Core Objects Overview - Fundamental Kubernetes objects
Workload Objects Overview - Objects that manage pods

Key Takeaways

Everything in Kubernetes is an API object
Objects have consistent structure: apiVersion, kind, metadata, spec, status
Spec defines desired state, status shows current state
Objects go through a lifecycle: create, validate, reconcile, steady state
Objects are either namespaced or cluster-scoped
Objects can reference and own other objects
CRUD operations work on all objects