API Machinery

API Request Flow

Every kubectl command, controller action, and kubelet heartbeat flows through the API server. The request passes through authentication, authorization, admission control, and validation before being persisted to etcd. Understanding this pipeline is critical for debugging permission errors and performance issues.

Client Request
     |
     v
Authentication (who are you?)
     |
     v
Authorization (what can you do?)
     |
     v
Admission Control (is this request allowed?)
     |
     v
Validation (is the object valid?)
     |
     v
Persistence (write to etcd)
     |
     v
Response + Watch Event

Authentication

Authentication identifies who is making the request. Kubernetes supports multiple authentication methods: X.509 client certs, bearer tokens, OpenID Connect (OIDC), service account tokens, and webhook token authentication. These are additive — if any method succeeds, the user is authenticated.

# kube-apiserver flags for OIDC
--oidc-issuer-url=https://accounts.google.com
--oidc-client-id=kubernetes
--oidc-username-claim=email
--oidc-groups-claim=groups
--oidc-ca-file=/etc/kubernetes/pki/oidc-ca.crt

Authorization

Authorization determines what the authenticated user can do. Kubernetes uses RBAC (Role-Based Access Control) as the standard authorization mode. RBAC maps users/groups to roles via RoleBinding and ClusterRoleBinding objects.

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

Admission Control

Admission controllers intercept requests after authorization but before persistence. They can mutate (change the object) or validate (reject invalid objects). Built-in admission controllers include LimitRanger, ResourceQuota, and NodeRestriction. Custom admission webhooks extend this with external logic.

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
  name: sidecar-injector
webhooks:
- name: sidecar.injector.example.com
  admissionReviewVersions: ["v1"]
  sideEffects: None
  clientConfig:
    service:
      name: webhook-server
      namespace: kube-system
      path: /inject
  rules:
  - operations: ["CREATE"]
    apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
  namespaceSelector:
    matchLabels:
      sidecar-injection: enabled

Watch Mechanism

Controllers don't poll the API server — they use the watch mechanism. A watch is a long-lived HTTP connection that streams events (Added, Modified, Deleted) as objects change. This is how controllers react to state changes in near real-time without constant polling.

# Watch for pod events
kubectl get pods -w

# Watch with JSON output for scripting
kubectl get pods -o json | jq -c '
  .items[] | {
    name: .metadata.name,
    phase: .status.phase,
    ready: (.status.conditions[]? | select(.type=="Ready") | .status)
  }'

Resource Version

Every Kubernetes object has a resourceVersion field — an opaque string that changes on every write. It is used for optimistic concurrency (preventing lost updates) and for resuming watches. If you get a conflict error, your resourceVersion is stale — re-read the object and try again.

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
  namespace: default
  resourceVersion: "12345"  # Must match current value
data:
  key: "updated-value"