Kubernetes Manifest Structure: apiVersion, kind, metadata, and spec

The four required fields

apiVersion: <API group>/<version>   # e.g., apps/v1, v1, batch/v1
kind: <Resource type>               # e.g., Deployment, Service, Pod
metadata:
  name: my-resource                 # required
  namespace: default                # optional, defaults to default
  labels:
    app: my-app
    env: production
spec:
  # resource-specific desired state

Every Kubernetes resource follows this structure. apiVersion and kind together identify which controller handles the resource. metadata provides identity and routing. spec describes what you want.

Common resource examples

Deployment (apps/v1):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: production
  labels:
    app: api
    version: "2.1"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api        # must match pod template labels
  template:
    metadata:
      labels:
        app: api      # pods get these labels
    spec:
      containers:
        - name: api
          image: my-api:2.1
          ports:
            - containerPort: 8080
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi

Service (v1):

apiVersion: v1
kind: Service
metadata:
  name: api-service
  namespace: production
spec:
  selector:
    app: api          # routes to pods with this label
  ports:
    - name: http
      port: 80        # service port (what clients connect to)
      targetPort: 8080  # container port (where traffic goes)
  type: ClusterIP     # or LoadBalancer, NodePort

ConfigMap (v1):

apiVersion: v1
kind: ConfigMap
metadata:
  name: api-config
  namespace: production
data:
  LOG_LEVEL: "info"
  MAX_CONNECTIONS: "100"
  config.yaml: |
    server:
      port: 8080
      timeout: 30s

Labels and selectors

Labels are key-value metadata applied to resources. Selectors filter resources by label. This is how Services route traffic to Pods, and how Deployments manage ReplicaSets.

# Service selector must match pod labels exactly
kind: Service
spec:
  selector:
    app: api       # routes to pods where labels include app=api
    env: prod      # AND env=prod

# Deployment pod template labels must match deployment selector
kind: Deployment
spec:
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api   # must include all selector labels
        env: prod  # can have additional labels
        version: "2.1"

A selector mismatch between a Service and its target Pods means the Service has no endpoints — traffic silently drops with connection refused errors.

metadata:
  labels:
    app: api            # used by selectors, kubectl get -l, etc.
    env: production
  annotations:
    deployment.kubernetes.io/revision: "5"    # informational metadata
    kubectl.kubernetes.io/last-applied-configuration: |
      {...}
    prometheus.io/scrape: "true"              # consumed by Prometheus operator
    prometheus.io/port: "9090"

Checking available API versions

# List all resource types with their API versions
kubectl api-resources

# Output includes:
# NAME          SHORTNAMES   APIVERSION    NAMESPACED   KIND
# pods          po           v1            true         Pod
# deployments   deploy       apps/v1       true         Deployment
# services      svc          v1            true         Service
# jobs                       batch/v1      true         Job
# cronjobs      cj           batch/v1      true         CronJob
# ingresses     ing          networking.k8s.io/v1  true  Ingress

# Check what fields are valid for a resource
kubectl explain deployment.spec.strategy
kubectl explain pod.spec.containers

kubectl explain documents every field in the spec without leaving the terminal.