Kubernetes API Objects Explained!

Cloudchamp

8 min read

·

Sep 3, 2025

--

Listen

Share

Kubernetes has many objects, grouped into categories.

They define desired state → what apps run, how they connect, and how resources are managed.

This notes includes explanation, manifests and example for Kubernetes objects

Press enter or click to view image in full size

Check out the Youtube video: https://youtu.be/WguJCFc5oyc?si=P8wiD9FDft385JSZ

1. Workload Objects (define running apps):

• Pod — smallest deployable unit.
• ReplicaSet — ensures a set number of pod replicas.
• Deployment — manages ReplicaSets for rolling updates.
• StatefulSet — runs pods with stable identity/storage.
• DaemonSet — ensures a pod on every node.
• Job — runs tasks once until completion.
• CronJob — runs jobs on a schedule.

2. Service & Networking Objects (connect apps):

• Service — stable network endpoint for pods.
• Ingress — HTTP/HTTPS routing to services.
• Endpoint / EndpointSlice — track service backends.
• NetworkPolicy — controls pod-to-pod traffic.

3. Configuration & Storage Objects:

• ConfigMap — stores config data.
• Secret — stores sensitive data.
• Volume / PersistentVolume (PV) — storage resource.
• PersistentVolumeClaim (PVC) — request for storage.
• StorageClass — defines dynamic storage provisioning.

4. Security & Access Control:

• ServiceAccount — identity for pods.
• Role / ClusterRole — permissions.
• RoleBinding / ClusterRoleBinding — bind roles to users/service accounts.
• PodSecurityPolicy (deprecated) / PodSecurityAdmission — security rules.

5. Cluster & Node Management:

• Namespace — logical cluster partition.
• Node — worker machine representation.
• ResourceQuota — limits resources per namespace.
• LimitRange — sets default/min/max resource requests.

6. Policy & Scheduling:

• HorizontalPodAutoscaler (HPA) — scales pods based on metrics.
• VerticalPodAutoscaler (VPA) — adjusts pod resource requests.
• PodDisruptionBudget (PDB) — controls voluntary disruptions.
• PriorityClass — scheduling priority.

Kubernetes objects define the desired state of your cluster and workloads. They are persistent entities that describe what applications should run, how they should run, and how resources should be managed. These objects can be grouped into categories.

1. Workload Objects (define running apps)

Pod

• Smallest deployable unit in Kubernetes.
• Can have one or more containers.
• Containers in a Pod share:

IP address

Volumes (storage)

Network namespace

• Pods are ephemeral → replaced when killed.
• Often created by higher-level controllers (Deployment, StatefulSet).

Example Manifest:

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

ReplicaSet

• Ensures a set number of identical Pods are running.
• Recreates Pods if they fail.
• Rarely used directly → mostly managed by Deployments.

Example Manifest:

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: my-replicaset
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest

Deployment

• Most common object for stateless apps.
• Manages ReplicaSets and Pods.
• Provides:

Rolling updates (gradual rollout).

Rollback (revert to previous version).

• Used for web servers, APIs, etc.

Example Manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest

StatefulSet

• Like Deployment but for stateful apps.
• Pods get fixed names (pod-0, pod-1).
• Ensures ordered start/stop of Pods.
• Uses volumeClaimTemplates for persistent storage.
• Common for databases, Kafka, ZooKeeper.

Example Manifest:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
spec:
  serviceName: "nginx"
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        volumeMounts:
        - name: www
          mountPath: /usr/share/nginx/html
  volumeClaimTemplates:
  - metadata:
      name: www
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 1Gi

DaemonSet

• Runs one Pod per Node automatically.
• Good for:

Logging agents (Fluentd).

Monitoring agents (Prometheus Node Exporter).

Networking agents (CNI plugins).

• Updates propagate across all nodes.

Example Manifest:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: my-daemonset
spec:
  selector:
    matchLabels:
      app: monitoring
  template:
    metadata:
      labels:
        app: monitoring
    spec:
      containers:
      - name: node-exporter
        image: prom/node-exporter

Job

• Runs Pods until completion.
• Retries failed Pods (based on backoffLimit).
• Good for one-time tasks (batch processing, reports).

Example Manifest:

apiVersion: batch/v1
kind: Job
metadata:
  name: my-job
spec:
  template:
    spec:
      containers:
      - name: pi
        image: perl
        command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
      restartPolicy: Never
  backoffLimit: 4

CronJob

• Schedules Jobs like Linux cron.
• Example: backups every night at midnight.
• Runs Jobs at defined intervals.

Example Manifest:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: hello-cron
spec:
  schedule: "*/1 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: hello
            image: busybox
            args:
            - /bin/sh
            - -c
            - date; echo Hello from the Kubernetes cluster!
          restartPolicy: OnFailure

2. Service & Networking Objects

Service

• Provides a stable endpoint (IP + DNS name).
• Types:

ClusterIP (default, inside cluster).

NodePort (exposed on each node’s IP).

LoadBalancer (uses cloud provider LB).

• Handles Pod IP changes automatically.

Example Manifest:

apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: ClusterIP

Ingress

• Exposes HTTP/HTTPS services externally.
• Supports:

Host-based routing (app.example.com).

Path-based routing (/api → service1).

• Needs an Ingress Controller (NGINX, Traefik).

Example Manifest:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NetworkPolicy

• Defines rules for which Pods can communicate.

Example Manifest:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-nginx
spec:
  podSelector:
    matchLabels:
      app: nginx
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: frontend

3. Configuration & Storage Objects

ConfigMap

• Stores non-sensitive config data (env vars, properties).
• Can be mounted as:

Environment variables.

Files inside Pods.

• Keeps config outside container image.

Example Manifest:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: default
  labels:
    app: myapp
  annotations:
    description: "Configuration for myapp"
data:
  APP_MODE: "production"
  APP_PORT: "8080"

Secret

• Stores sensitive data (passwords, tokens, certs).
• Values stored in base64.
• Used like ConfigMaps but for secure data.
• Kubernetes can integrate with external secret managers (Vault, AWS Secrets Manager).

Example Manifest:

apiVersion: v1
kind: Secret
metadata:
  name: db-secret
type: Opaque
data:
  username: YWRtaW4=   # base64 for "admin"
  password: cGFzc3dvcmQ= # base64 for "password"

PersistentVolume (PV) & PersistentVolumeClaim (PVC)

PersistentVolume (PV)

• Represents actual storage resource in cluster.
• Provisioned manually or dynamically.
• Examples: AWS EBS, GCP Persistent Disk, NFS.

PersistentVolumeClaim (PVC)

• Binds to a suitable PV.
• Request for storage from a Pod.
• Example: Pod requests “5Gi, ReadWriteOnce”.
• PV: actual storage resource.
• PVC: request for storage.

Example Manifest:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

StorageClass

• Defines how PVs are provisioned automatically.
• Example: "gp2" class for AWS EBS.
• Allows dynamic provisioning.

Example Manifest:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: standard
provisioner: kubernetes.io/aws-ebs
parameters:
  type: gp2
reclaimPolicy: Retain

4. Security & Access Control

ServiceAccount

• Provides identity to Pods.
• Pods use this identity to talk to API server.
• Each namespace has a default ServiceAccount.

Example Manifest:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-serviceaccount

Role & RoleBinding

• Role: permissions in a namespace.
• RoleBinding: assigns Role to a user or ServiceAccount.

Example Manifest (Role):

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: pod-reader
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list"]

Example Manifest (RoleBinding):

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods
  namespace: default
subjects:
- kind: User
  name: jane
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

5. Cluster & Node Management

Namespace

• Logical partition
• Virtual cluster within Kubernetes.
• Separates resources (teams, projects, environments).
• Built-in namespaces:

default

kube-system

kube-public

Example Manifest:

apiVersion: v1
kind: Namespace
metadata:
  name: my-namespace

Node

• Represents a worker machine.
• Runs Kubelet, container runtime, kube-proxy.
• Schedules Pods based on resources.

ResourceQuota

• Limits total resources in a namespace.
• Example: max 10 Pods, 4 CPUs, 10Gi memory.

Example Manifest:

apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-resources
  namespace: my-namespace
spec:
  hard:
    pods: "10"
    requests.cpu: "4"
    requests.memory: 5Gi
    limits.cpu: "10"
    limits.memory: 10Gi

6. Policy & Scheduling

HorizontalPodAutoscaler (HPA)

• Auto-scales Pods based on CPU/memory/custom metrics.
• Example: add more Pods if CPU > 70%.

Example Manifest:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-deployment
  minReplicas: 1
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50

VerticalPodAutoscaler (VPA)

• Adjusts CPU/Memory requests & limits of containers in Pods.

apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: web-vpa
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-deployment
  updatePolicy:
    updateMode: Auto


#Note: Not as common as HPA; can cause Pod restarts when resizing.

PodDisruptionBudget (PDB)

• Ensures minimum Pods stay available during upgrades or maintenance.
• Example: always keep at least 2 Pods running.

Example Manifest:

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: my-pdb
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: nginx

Endpoint & EndpointSlice

• Endpoint = list of Pod IPs behind a Service.
• EndpointSlice = scalable replacement (groups Pods efficiently).
• Used internally by Services for load balancing.

CSI Driver & VolumeSnapshot (extra APIs)

• CSI Driver → lets Kubernetes use external storage systems.
• VolumeSnapshot → allows backup/restore of PVCs.

CertificateSigningRequest (CSR)

• Used to request TLS certificates.
• Common in securing cluster communications.

Webhook Configurations (extra APIs)

• MutatingWebhookConfiguration → modifies objects on create/update.
• ValidatingWebhookConfiguration → validates objects before they are stored.

PriorityClass

• Gives Pods priority during scheduling.
• High-priority Pods preempt lower-priority ones.

Affinity/AntiAffinity (extra API)

• NodeAffinity → schedule Pods on certain nodes.
• PodAffinity → schedule Pods close to each other.
• PodAntiAffinity → spread Pods across nodes.

TopologySpreadConstraints (extra API)

• Ensures Pods are spread across nodes/zones.
• Prevents all Pods from being scheduled on one node.

Summary

Categories & Examples:

• Workloads → Pod, ReplicaSet, Deployment, StatefulSet, DaemonSet, Job, CronJob
• Networking → Service, Ingress, EndpointSlice, NetworkPolicy
• Config & Storage → ConfigMap, Secret, PV, PVC, StorageClass, VolumeSnapshot
• Security & Access → ServiceAccount, Role, RoleBinding, CSR, Webhooks
• Cluster Mgmt → Namespace, Node, ResourceQuota, LimitRange, CRD, Lease
• Policy & Scheduling → HPA, VPA, PDB, PriorityClass, Affinity

Together, these objects describe how Kubernetes runs, connects, secures, and scales applications.

Want to learn more?

Subscribe: https://www.youtube.com/@cloudchamp?sub_confirmation=1
Connect on LinkedIn: https://www.linkedin.com/in/nasiullha-chaudhari/