Staging modules

A walkthrough of every module under staging/src/k8s.io/. Each section names the module, summarizes its responsibility, and points at its most important files.

Big four: api, apimachinery, apiserver, client-go

api

The set of Go types for every built-in API group. There is one subdirectory per <group>/<version>:

staging/src/k8s.io/api/
├── core/v1/types.go               # Pod, Node, Service, ConfigMap, Secret, …
├── apps/v1/types.go               # Deployment, StatefulSet, DaemonSet, ReplicaSet
├── batch/v1/types.go              # Job, CronJob
├── networking/v1/types.go         # NetworkPolicy, Ingress, IngressClass
├── rbac/v1/types.go               # Role, ClusterRole, *Binding
├── admissionregistration/v1/types.go
├── apiextensions/v1/types.go      # CustomResourceDefinition
├── certificates/v1/types.go
├── coordination/v1/types.go       # Lease
├── discovery/v1/types.go          # EndpointSlice
├── flowcontrol/v1/types.go
├── policy/v1/types.go             # PodDisruptionBudget
├── scheduling/v1/types.go         # PriorityClass
├── resource/v1/types.go           # DRA: ResourceClaim, ResourceSlice, DeviceClass
├── storage/v1/types.go            # StorageClass, CSI*
└── ... (every other group)

This is the module everyone imports. It is generated-friendly: every types.go carries +k8s: tags that drive deepcopy, conversion, openapi, and clientset generation.

apimachinery

The kernel of "API plumbing": scheme, codec, runtime types, watch protocol, label/field selectors, errors. Highlights:

• pkg/runtime/scheme.go — versioned object registration
• pkg/runtime/serializer/ — JSON, YAML, proto codecs
• pkg/api/errors/ — typed errors (IsNotFound, IsConflict, IsAlreadyExists)
• pkg/api/meta/ — OwnerReference helpers, RESTMapper
• pkg/labels/ — selector parser
• pkg/util/managedfields/ — server-side apply merge
• pkg/watch/ — Event types and Interface

Imported by literally every other module.

apiserver

The generic apiserver framework. Build any apiserver — kube-apiserver, apiextensions, kube-aggregator, sample-apiserver, your own — by composing pieces here:

• pkg/server/ — GenericAPIServer, run loop, install API groups
• pkg/registry/generic/registry/store.go — generic REST store
• pkg/storage/ — Interface, etcd3 implementation, watch cacher
• pkg/endpoints/ — REST handlers
• pkg/admission/ — admission framework
• pkg/authentication/, pkg/authorization/ — authn/authz primitives
• pkg/audit/ — audit pipeline
• pkg/util/feature/ — feature-gate plumbing
• pkg/server/options/ — flag groups every apiserver shares

client-go

The Kubernetes client library. The most-imported Kubernetes module in the world.

• kubernetes/ — typed clientsets (*v1.PodsGetter, *v1.DeploymentInterface, …) generated from api.
• dynamic/ — typed-by-GVR dynamic client.
• discovery/ — discovery clients (cached + memory).
• informers/ / listers/ — typed informer factories and listers, also generated from api.
• tools/cache/ — informer base, reflector, indexer, work queue.
• tools/leaderelection/ — lease-based leader election.
• tools/clientcmd/ — kubeconfig loading.
• rest/ — the underlying REST client.
• applyconfigurations/ — typed builders for server-side apply.

The toolkit

apiextensions-apiserver

The CRD API server. It is itself an apiserver built on top of staging/src/k8s.io/apiserver. When kube-apiserver is asked about a CRD type, it forwards to this layer. Highlights:

• pkg/apis/apiextensions/v1/types.go — CustomResourceDefinition
• pkg/apiserver/customresource_handler.go — the core handler that turns a CRD into a REST endpoint
• pkg/controller/establish/ — the controller that finalizes a newly created CRD

kube-aggregator

The aggregation layer. Implements APIService resources that proxy to extension API servers (e.g. metrics.k8s.io).

• pkg/apis/apiregistration/v1/types.go — APIService
• pkg/apiserver/handler_apis.go — the proxy handler
• pkg/controllers/openapi/ — aggregates OpenAPI from extension servers

cli-runtime

The shared CLI helpers used by kubectl and any kubectl plugin. The biggest pieces are genericclioptions/, printers/, and resource/.

component-base

Shared boot/runtime services: logs (klog wrapper), metrics (Prometheus wrapper with stability tiers), CLI, leader election helpers, feature gates, version info, config-loading helpers.

component-helpers

A miscellaneous bin of helpers used by more than one component but not big enough to warrant their own module: scheduling helpers, node helpers, storage helpers.

controller-manager

Shared library for controller-manager binaries: Run loop, client-builder, options, healthz/livez/readyz wiring, leader election integration. Used by both kube-controller-manager and cloud-controller-manager.

kubectl

The library that cmd/kubectl builds from. Subcommand packages, factory, describe, drain, explain, polymorphic helpers.

pod-security-admission

The implementation of Pod Security Standards (Restricted/Baseline/Privileged). Imported by the in-tree podsecurity admission plugin and re-usable by anyone enforcing the same policy out-of-band.

code-generator

The codegen toolchain. Each binary lives in cmd/<gen>-gen/:

• deepcopy-gen — generate DeepCopy() methods
• client-gen — generate typed clientsets
• informer-gen / lister-gen — generate informers / listers
• conversion-gen — generate version-conversion functions
• defaulter-gen — generate defaulters
• openapi-gen — generate OpenAPI v2 + v3 schemas
• applyconfiguration-gen — generate apply-config builders
• prerelease-lifecycle-gen — annotate types with introduced/deprecated/removed metadata

Driver script: kube_codegen.sh.

Protocol contracts

cri-api

The CRI gRPC contract. pkg/apis/runtime/v1/api.proto is the source-of-truth file; the generated *.pb.go carries the Go bindings consumed by kubelet (pkg/kubelet/kuberuntime/) and by every CRI-compliant runtime (containerd, CRI-O).

cri-client

A reusable gRPC client wrapping cri-api so multiple non-kubelet tools can speak CRI.

cri-streaming

The exec/attach/port-forward streaming server. Implemented as a generic library so kubelet, fake runtimes, and tests can reuse it.

csi-translation-lib

The in-tree-volume to CSI-volume translation library. Each translator (plugins/in_tree_volume.go) maps an in-tree volume spec to a CSI spec for a specific driver name. The kubelet and the attach-detach controller call into this when CSI migration is enabled for a given driver.

dynamic-resource-allocation

Library used by the scheduler, kubelet, and DRA driver authors. Includes the ResourceSlice tracker, CEL evaluator, CDI device builder, and the gRPC client for kubelet ↔ driver plugin communication.

endpointslice

Helpers shared by pkg/controller/endpointslice/ and pkg/proxy/. Mostly slice-merging utilities and topology hint computation.

kms

The KMS plugin gRPC contract. Used by encryption-at-rest providers; implementations are out-of-tree (KMS plugins for AWS KMS, Azure Key Vault, GCP KMS, Vault).

externaljwt

The contract for delegating JWT issuance to an external service. Used by clusters that don't want kube-apiserver to mint service-account tokens directly.

Samples

sample-apiserver

A minimal aggregated API server. Shows how to compose apiserver + a custom API group. Contributors copy this as the starting point for new aggregated APIs.

sample-cli-plugin

A minimal kubectl-namespaces plugin. Shows how to consume cli-runtime and present a Cobra subcommand.

sample-controller

A minimal controller. Shows the informer/workqueue/sync handler pattern with a custom resource defined via CRD. The starting point for controller authors.

Module graph integrity

Cross-module imports are constrained: api cannot import client-go; client-go cannot import apiserver; etc. The constraint graph is enforced by hack/module-graph.sh and by the publishing tool. Adding a new cross-module import requires updating the staging publish rules in staging/publishing/.

Common entry points for change

• New API type → staging/src/k8s.io/api/<group>/<version>/types.go + downstream codegen
• New client method → typically generated by client-gen; manual additions go in staging/src/k8s.io/client-go/kubernetes/typed/<group>/<version>/
• New CRI feature → edit cri-api/pkg/apis/runtime/v1/api.proto, regenerate, plumb through pkg/kubelet/kuberuntime/
• New CSI translation → add a translator in csi-translation-lib/plugins/
• New scheduler plugin → see components/kube-scheduler/framework.md