Kubernetes Objects

  

Kubernetes objects can be divided into two groups:

• API objects = persistent, declarative resources stored in etcd
• Non-API objects = runtime, node-local, or in-memory artifacts created to implement API objects

Kubernetes is fundamentally an API-driven control plane + runtime realization.

What are Kubernetes API objects?

Kubernetes API objects are persistent entities stored in etcd that represent the desired state and current state of your cluster.

They are:

• Defined by a schema
• Exposed via the Kubernetes API server
• Created, read, updated, deleted via kubectl, controllers, or the API
• Continuously reconciled by controllers

In short, if it’s stored in etcd and managed via the API server, it’s an API object.

Common Kubernetes API objects (by category)

Workloads

• Pod
• Deployment
• ReplicaSet
• StatefulSet
• DaemonSet
• Job
• CronJob

Networking

• Service
• Ingress
• NetworkPolicy
• EndpointSlice
• Endpoints (legacy)

Configuration & storage

• ConfigMap
• Secret
• PersistentVolume (PV)
• PersistentVolumeClaim (PVC)
• StorageClass
• VolumeSnapshot

Cluster & node

• Node
• Namespace
• ResourceQuota
• LimitRange
• RuntimeClass

Security & access

• ServiceAccount
• Role, ClusterRole
• RoleBinding, ClusterRoleBinding
• PodSecurityPolicy (deprecated)
• PodSecurityAdmission (via config)

Custom & extension

• CustomResourceDefinition (CRD)
• Any Custom Resource (e.g. Certificate, Prometheus, IngressRoute)

Key properties of API objects

Every API object has:

apiVersion: ...

kind: ...

metadata:

  name: ...

  namespace: ...

spec:        # desired state

status:      # current state (set by controllers)

And importantly:

Declarative: you describe what you want

Reconciled: controllers try to make reality match spec

Durable: survive restarts

What are “non-API” Kubernetes objects?

This is where the term object becomes fuzzy.

There are many things in Kubernetes that are real, important, and named — but are NOT API objects because they:

• Are not stored in etcd
• Do not have YAML
• Are not CRUD’d via the API
• Are usually runtime, internal, or node-local

Major categories of non-API Kubernetes “objects”

1️⃣ Containers

• Individual containers inside a Pod
• Managed by the container runtime (containerd / CRI-O)
• Kubernetes does NOT store container objects

Example:

• You can’t do kubectl get container
• Containers exist only while the Pod is running

2️⃣ Volumes (runtime volumes)

While PV/PVC are API objects, the actual mounted volumes are not.

Examples:

• emptyDir
• hostPath
• Mounted CSI volumes

These are:

• Created on the node
• Managed by kubelet + CSI
• Invisible to the API as concrete objects

3️⃣ kube-proxy rules (iptables / IPVS)

• iptables chains
• IPVS virtual servers
• eBPF maps (Cilium)

These implement Services but are:

• Node-local
• Ephemeral
• Derived from API objects

4️⃣ Scheduler & controller internals

Examples:

• Scheduling queues
• Controller work queues
• Leader election locks (in-memory)
• Cached informers

These exist:

• In process memory
• For performance and correctness
• Never stored in etcd

5️⃣ CNI networking artifacts

Examples:

• Network namespaces
• veth pairs
• Routes
• eBPF programs
• Overlay tunnels

Created by:

• kubelet
• CNI plugins (Calico, Cilium, Flannel)

Not visible as API objects.

6️⃣ DNS records

• Service A/AAAA records
• Pod DNS entries

They’re derived from:

• Services
• EndpointSlices

But the records themselves:

• Live inside CoreDNS
• Are regenerated dynamically

7️⃣ Events (kind of special)

Event is an API object, but:

• Short-lived
• Often garbage-collected quickly
• Not something you “own” declaratively

This blurs the line between API and runtime artifacts.

8️⃣ Admission & runtime state

Examples:

• Mutated Pod specs (post-admission)
• Pod sandbox state
• cgroups
• seccomp / AppArmor profiles applied

These exist at runtime, not as first-class objects.

A useful mental model

Three layers of “things” in Kubernetes

┌─────────────────────────────┐

│  API Objects (etcd)         │  ← declarative, durable

│  Pods, Services, Secrets    │

├─────────────────────────────┤

│  Controllers & Reconcilers  │  ← logic

├─────────────────────────────┤

│  Runtime Artifacts          │  ← ephemeral, node-local

│  Containers, iptables, CNI  │

└─────────────────────────────┘

Rule of thumb

Ask these questions:

Can I kubectl get it?

→ Yes → API object

→ No → probably runtime

Is it stored in etcd?

→ Yes → API object

Does it survive a full cluster restart?

→ Yes → API object

→ No → runtime artifact

Why this distinction matters (DevOps relevance)

• Explains why “kubectl says it exists but it’s not working”
• Helps debug node-local vs cluster-wide issues
• Critical when writing controllers, operators, or CRDs
• Clarifies what’s source of truth vs derived state

---