Kubernetes objects and resources

Concept of Kubernetes Objects

Kubernetes manages everything in the cluster as an object. An object is a record of intent: you describe the desired state, and the system works to make reality match that description.

Every Kubernetes object:

• Has a type (e.g. Pod, Service, Deployment)
• Belongs to an API group and version
• Has metadata (name, namespace, labels, annotations, UID)
• Lives in a certain scope (namespaced or cluster-wide)
• Has a spec (what you want) and usually a status (what exists now)

In OpenShift, you use the same Kubernetes object model; OpenShift just adds more objects on top.

API Groups, Versions, and Kinds

Kubernetes objects are exposed via an HTTP API. Each object is identified by:

• API group – logical grouping (e.g. core/"", apps, batch, rbac.authorization.k8s.io)
• Version – evolution of the API (e.g. v1, v1beta1)
• Kind – the type of object (e.g. Pod, Service, Deployment)

Example mapping:

• apiVersion: v1, kind: Pod → core API group, version v1
• apiVersion: apps/v1, kind: Deployment → apps group, version v1
• apiVersion: batch/v1, kind: Job → batch group, version v1

Understanding this is important for:

• Writing correct YAML manifests
• Reading kubectl/oc output
• Knowing where different resources “live” in the API

Resource Types vs Individual Objects

Resource type: the collection of all objects of a given kind in the API.

• For example: the pods resource (often referred to in API paths as /api/v1/namespaces/{ns}/pods) represents all Pod objects in that namespace.

Object instance: one particular object within that resource.

• For example: the Pod named web-123 in namespace demo.

You interact with resource types using verbs:

• list – all objects of a kind (e.g. all Pods in a namespace)
• get – one object (e.g. a specific Pod)
• create, update, patch, delete – manipulate an object
• watch – stream changes to a resource type or a particular object

These verbs are fundamental for RBAC and for how controllers work.

Object Metadata

Every object has metadata, which at minimum includes:

• name – unique within its namespace (or whole cluster for cluster-scoped)
• namespace – logical grouping (for namespaced objects)
• uid – system-generated unique ID
• labels – key/value pairs for selection and grouping
• annotations – key/value pairs for non-identifying metadata

Example:

metadata:
  name: web-frontend
  namespace: production
  labels:
    app: shop
    tier: frontend
  annotations:
    description: "Main web front-end"

Labels and Label Selectors

Labels are structural metadata: they are used to define relationships between objects.

Common uses:

• Services choose which Pods to send traffic to
• Deployments track which Pods they manage
• Network policies match Pods to apply rules
• Tools (CI/CD, monitoring) group resources

Label selectors are expressions used to match labels, e.g.:

• Equality-based: app=shop, tier!=cache
• Set-based: environment in (dev,qa), release notin (canary)

Selectors appear:

• In object specs (e.g. spec.selector in Services, Deployments)
• In CLI commands:
  oc get pods -l app=shop

Changing labels can change which Pods are part of a Service or Deployment, often immediately, so be careful.

Annotations

Annotations are non-structural metadata: they do not affect object selection.

Typical uses:

• Storing configuration digests or build info
• Attaching links (e.g. to a ticket, documentation, dashboards)
• Passing hints to operators or controllers

Because they are ignored for selection, annotations are safe places to store extra context that tools may rely on.

Namespaced vs Cluster-Scoped Resources

Kubernetes groups resources into two scopes:

• Namespaced resources – live inside a namespace:
• Examples: Pods, Services, Deployments, ConfigMaps, Secrets, Ingress
• Names only have to be unique inside a namespace
• Cluster-scoped resources – exist once at cluster level:
• Examples: Nodes, Namespaces, PersistentVolumes, ClusterRoles, StorageClasses
• Names are globally unique in the cluster

The scope affects:

• How you reference an object (you may or may not specify a namespace)
• How RBAC rules are defined
• How quota and isolation work between tenants

Core Categories of Kubernetes Objects

Kubernetes has many object kinds, but they can be grouped by role. These categories help you reason about how applications are defined and managed.

Workload Resources

Workload resources describe what should run.

• Pods – smallest deployable unit: one or more containers sharing:
• Network namespace (same IP, ports)
• Volumes
• Some Linux namespaces
• Workload controllers – manage Pods for you:
• Deployment – stateless, replicated Pods, rolling updates
• ReplicaSet – keeps a stable set of replicas (usually owned by a Deployment)
• StatefulSet – ordered, stable network identities and storage for stateful apps
• DaemonSet – one Pod per Node (for agents, logging, monitoring)
• Job – run Pods to completion (batch tasks)
• CronJob – run Jobs on a schedule

In practice, you rarely create Pods directly; you create controllers that manage them.

Service Discovery and Networking Resources

These resources control how workloads talk to each other:

• Service – stable virtual IP and DNS name to front Pods
• Endpoints / EndpointSlice – backing IPs/ports for a Service
• Ingress – HTTP(S) routing into the cluster
• NetworkPolicy – rules for which Pods can talk to which

OpenShift extends these with its own routing primitives, but they are built on this core model.

Storage and Data Resources

These represent storage and configuration related to persistent data:

• PersistentVolume (PV) – a piece of storage in the cluster (cluster-scoped)
• PersistentVolumeClaim (PVC) – a claim by a Pod for storage (namespaced)
• StorageClass – defines how to provision storage dynamically
• Volume definitions – embedded in Pods to mount storage

These objects let you describe what storage you need, not how to attach a specific disk or NFS path.

Configuration and Secret Resources

Used to externalize configuration and sensitive material from your code:

• ConfigMap – key/value pairs or configuration files
• Secret – similar to ConfigMap but for sensitive data:
• Passwords, tokens, certificates, keys
• ServiceAccount – identity for Pods when talking to the API

These objects enable 12-factor style configuration and separation of concerns.

Access Control and Policy Resources

Kubernetes models permissions and security-related policies using objects:

• Role / ClusterRole
• RoleBinding / ClusterRoleBinding
• PodSecurityPolicy / alternative mechanisms depending on version
• NetworkPolicy

OpenShift builds on top of these with its own policy constructs, but the base is the same resource model.

Object Structure: Spec and Status

Most Kubernetes objects follow a common high-level shape:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  # Desired state (what you want)
status:
  # Observed state (what exists now), filled in by the system

• spec – describes your intent:
• Number of replicas
• Pod template (containers, images, ports, env vars)
• Selector (which Pods are managed)
• Strategy (rolling update details)
• status – describes current reality:
• How many replicas are running and ready
• Conditions (available, progressing, degraded)
• Events and error messages in some cases

Controllers continuously reconcile status towards spec. You almost always edit spec, and you read status to understand what’s going on.

API Operations and Resource Lifecycles

Every resource follows the same general lifecycle:

1. Create – via YAML manifest, oc create, or another controller
2. Read – oc get, oc describe, watches
3. Update/Patch – modifying spec, labels, annotations, or other fields
4. Delete – marking for deletion and cleaning up dependent resources

Under the hood, the API server exposes REST-like endpoints:

• GET /apis/apps/v1/namespaces/{ns}/deployments
• POST /apis/apps/v1/namespaces/{ns}/deployments
• PUT/PATCH/DELETE on specific objects

This is the same model used by oc, by controllers, and by Operators.

Custom Resources and Extensibility

Kubernetes can be extended with new object kinds without changing the core platform by using CustomResourceDefinitions (CRDs).

• A CRD defines a new resource type (e.g. MyDatabase, MLJob)
• Once installed, you can create objects of that new kind
• Controllers or Operators watch these resources and act on them

OpenShift makes heavy use of CRDs and Operators, but the underlying mechanism is still “objects and resources” in the API.

Objects in Practice with `oc`/`kubectl`

Although OpenShift uses oc, the resource concepts map directly:

• Get objects of a kind:
• oc get pods
• oc get deployments.apps
• View a single object:
• oc get pod web-123 -o yaml
• Edit desired state:
• oc edit deployment web
• Use labels:
• oc get pods -l app=shop,tier=frontend

Behind every command is the same notion: manipulating Kubernetes objects and their resources in the cluster API.