WSS
On this page
Containers & OrchestrationRequiredUpdated

Kubernetes API objects reference

The foundational declarative resources used to orchestrate containers, manage networking, and handle configuration in Kubernetes.

What it is

Kubernetes is entirely API-driven. Every action, configuration, and deployment is represented as a distinct API object stored in the cluster’s control plane (specifically, within etcd). Operators do not execute commands to “run a container”; instead, they submit a declarative JSON or YAML manifest defining a specific API object. The Kubernetes control plane then works continuously to make the cluster’s actual state match the state defined in those objects.

Objects are divided into categories based on their function: workloads (running code), discovery and load balancing (networking), and config and storage (data injection).

Why it matters

Understanding the core API objects is a prerequisite for operating workloads on Kubernetes. The orchestrator’s immense flexibility comes from decoupling responsibilities. A container does not know how it is exposed to the internet, and a network load balancer does not know how to restart a crashed process. These concerns are handled by separate, composable API objects that link together through a powerful metadata tagging system called labels and selectors.

Without a firm grasp of these primitives, operators cannot construct resilient architectures or troubleshoot complex routing failures.

How to implement

Workload Objects

  • Pod: The smallest deployable unit. A Pod wraps one or more containers that share network namespaces and storage volumes. Pods are ephemeral; if a node dies, the Pod is gone forever. You rarely create standalone Pods.
  • ReplicaSet: Ensures that a specified number of identical Pod replicas are running at any given time. If a Pod crashes, the ReplicaSet creates a new one to replace it.
  • Deployment: A higher-level abstraction that manages ReplicaSets. Deployments handle version rollouts and rollbacks safely. When you update a container image, the Deployment spins up a new ReplicaSet and slowly scales down the old one. This is the primary way to run stateless web applications.
  • DaemonSet: Ensures that a copy of a specific Pod runs on every single node in the cluster. This is exclusively used for cluster-wide infrastructure tasks, like shipping logs or monitoring node health.

Discovery and Load Balancing

  • Service: A stable network abstraction. Because Pods are constantly created and destroyed, their IP addresses change constantly. A Service provides a single, static IP address and DNS name. It uses a label selector to find matching Pods and load balances traffic across them.
  • Ingress: Manages external access to the services in a cluster, typically HTTP/HTTPS. While a Service handles internal routing, an Ingress provides URL-based routing, SSL termination, and name-based virtual hosting from the outside world.

Config and Storage

  • ConfigMap: Stores non-confidential configuration data as key-value pairs. Pods can consume ConfigMaps as environment variables or mounted files, allowing operators to decouple environment-specific configuration from container images.
  • Secret: Similar to a ConfigMap, but specifically for sensitive data like passwords and TLS certificates. Secrets are stored encrypted at rest in modern clusters and are injected securely into Pods.

Common mistakes

Tightly Coupling Deployments

Operators migrating from traditional VMs often try to put a web server, a background worker, and a cache into a single Pod, treating it like a server. This prevents independent scaling. If the web server needs more CPU, you must scale the entire Pod, wasting resources on the cache. Containers within a single Pod should only be tightly coupled helper processes (like a log forwarder).

Missing Resource Limits

If a Deployment manifest omits CPU and memory limits, the Pods will consume unlimited resources on the physical node. A memory leak in one application will starve the underlying operating system and crash the entire node, taking down all other unrelated Pods hosted there. Every production workload must define precise requests and limits.

Selector Mismatches

Services route traffic to Pods by matching labels (e.g., app: frontend). If a typo exists in the Service’s selector, it will fail to find the Pods. The Deployment will show all Pods running perfectly, but the Service will return immediate connection refused errors because its routing table is empty.

Verification

To inspect the state of API objects, use the kubectl command-line tool.

List all deployments and verify their desired vs. ready states:

kubectl get deployments

Inspect a specific service to verify it has successfully selected backend Pod endpoints:

kubectl describe service my-web-app

Look at the Endpoints field in the output. If it says <none>, the Service’s label selector does not match any running Pods, and traffic routing will fail.

View the raw YAML definition of a running object to see exactly how the control plane has populated default values and status fields:

kubectl get deployment my-web-app -o yaml

Related topics

Sources & further reading