kubernetes/kubernetes

API

Kubernetes is, by construction, an API-first system. The kube-apiserver speaks a uniform REST surface organized into named groups and versions. This page is a high-level guide; the detailed authn/authz/admission story is in systems/auth-and-admission, the storage layer is in systems/api-registry-and-storage, and the kube-apiserver wiring is in components/kube-apiserver.

Groups and versions

Every API resource is identified by group, version, and kind. Built-in groups in this repo:

Group	Examples
`(core)` (no group / `v1`)	Pod, Node, Service, ConfigMap, Secret, PersistentVolume, PersistentVolumeClaim, Namespace, Event, Endpoints, ServiceAccount
`apps`	Deployment, ReplicaSet, StatefulSet, DaemonSet, ControllerRevision
`batch`	Job, CronJob
`networking.k8s.io`	NetworkPolicy, Ingress, IngressClass
`discovery.k8s.io`	EndpointSlice
`rbac.authorization.k8s.io`	Role, ClusterRole, RoleBinding, ClusterRoleBinding
`authentication.k8s.io`	TokenReview, SelfSubjectReview
`authorization.k8s.io`	SelfSubjectAccessReview, SubjectAccessReview, LocalSubjectAccessReview, SelfSubjectRulesReview
`admissionregistration.k8s.io`	MutatingWebhookConfiguration, ValidatingWebhookConfiguration, ValidatingAdmissionPolicy, ValidatingAdmissionPolicyBinding, MutatingAdmissionPolicy (alpha)
`apiextensions.k8s.io`	CustomResourceDefinition
`apiregistration.k8s.io`	APIService
`autoscaling`	HorizontalPodAutoscaler
`certificates.k8s.io`	CertificateSigningRequest, ClusterTrustBundle
`coordination.k8s.io`	Lease
`events.k8s.io`	Event (newer kind, alongside core/v1.Event)
`flowcontrol.apiserver.k8s.io`	FlowSchema, PriorityLevelConfiguration
`node.k8s.io`	RuntimeClass
`policy`	PodDisruptionBudget
`resource.k8s.io`	ResourceClaim, ResourceClaimTemplate, DeviceClass, ResourceSlice, ResourcePool
`scheduling.k8s.io`	PriorityClass
`storage.k8s.io`	StorageClass, VolumeAttachment, CSIDriver, CSINode, CSIStorageCapacity
`storagemigration.k8s.io`	StorageVersionMigration (alpha)

The full list and version status is in pkg/controlplane/import_known_versions.go.

Discovery

Two discovery endpoints are served:

Per-group: /api, /apis, /apis/<group>, /apis/<group>/<version> — returns lists of group/versions and kinds. The legacy shape.
Aggregated: /apis with Accept: application/json;g=apidiscovery.k8s.io;v=v2;as=APIGroupDiscoveryList — a single document with the full tree. Cheaper for kubectl and client-go discovery caches.

Aggregated discovery has been the default since 1.27 and is implemented in staging/src/k8s.io/apiserver/pkg/endpoints/discovery/aggregated/.

OpenAPI

/openapi/v2 and /openapi/v3 serve the schema for every registered resource. The v3 endpoint serves one document per group/version, which is dramatically cheaper to fetch than the legacy v2 (which served everything in one document).

The schemas are generated by openapi-gen from +k8s: annotations on staging/src/k8s.io/api/<group>/<version>/types.go and consolidated into pkg/generated/openapi/zz_generated.openapi.go (74,000+ lines).

Versioning

The API versioning policy is documented in detail in community/contributors/devel/sig-architecture/api_changes.md. The summary:

Alpha (v1alpha1) — may break, may be removed without notice. Disabled by default behind a feature gate.
Beta (v1beta1, v1beta2) — must be supported for at least 9 months or 3 releases. Disabled by default since 1.24.
GA / Stable (v1) — must be supported indefinitely. Field changes follow strict compatibility rules.

A new version requires a KEP. Promotion from alpha → beta → GA also requires a KEP.

Subresources

Most resources expose subresources at /{name}/<subresource>. Common ones:

/status — separate write path for controllers
/scale — Scale subresource for HPA targets
/log, /exec, /attach, /portforward, /proxy — Pod streaming
/eviction — Pod eviction respecting PDB
/binding — Pod binding (legacy scheduler path)
/finalize — Namespace finalizer

Every subresource has its own storage type with its own (often lighter-weight) verbs.

Server-side apply

kubectl apply --server-side (and clients using the application/apply-patch+yaml content type) send a partial object that the server merges into the existing one. The server tracks field managers so concurrent applies from different operators don't trample each other. Conflicts surface as 409 unless the client passes force: true.

The merge logic lives in staging/src/k8s.io/apimachinery/pkg/util/managedfields/.

CRDs and aggregation

Two extension paths:

CustomResourceDefinition — declarative. Define a schema as YAML; the apiserver serves CRUD plus validation, defaulting, conversion, and OpenAPI. Implementation in staging/src/k8s.io/apiextensions-apiserver.
APIService aggregation — imperative. Register an external HTTPS server; kube-apiserver proxies all /apis/<group>/<version> requests to it. Implementation in staging/src/k8s.io/kube-aggregator.

CRDs are the right answer for almost every new declarative API. Aggregation is reserved for cases that can't be declarative (e.g., metrics-server's TableConvertor with arbitrary Go logic).

API