Data models

A directory map of the API types in this repo.

Versioned external types

staging/src/k8s.io/api/<group>/<version>/types.go is the public type definition for each group/version. The complete list of subdirectories under staging/src/k8s.io/api/:

• admission/v1
• admissionregistration/v1, v1alpha1, v1beta1
• apidiscovery/v2
• apiserverinternal/v1alpha1
• apps/v1, v1beta1, v1beta2
• authentication/v1, v1alpha1, v1beta1
• authorization/v1, v1beta1
• autoscaling/v1, v2
• batch/v1, v1beta1
• certificates/v1, v1alpha1, v1beta1
• coordination/v1, v1alpha1, v1beta1
• core/v1
• discovery/v1, v1beta1
• events/v1, v1beta1
• extensions/v1beta1 (vestigial; use apps, networking, policy instead)
• flowcontrol/v1, v1beta1, etc.
• imagepolicy/v1alpha1
• networking/v1, v1alpha1, v1beta1
• node/v1, v1alpha1, v1beta1
• policy/v1, v1beta1
• rbac/v1, v1alpha1, v1beta1
• resource/v1, v1alpha2, v1beta1, etc. (DRA)
• scheduling/v1, v1alpha1, v1beta1
• storage/v1, v1alpha1, v1beta1
• storagemigration/v1alpha1

Internal hub types

pkg/apis/<group>/types.go holds the internal type for each group. Internal types are only used inside kube-apiserver: external versions are converted to internal on read, and back on write. The conversion functions are generated into pkg/apis/<group>/<version>/zz_generated.conversion.go.

The set of subdirectories under pkg/apis/:

• admissionregistration/
• apidiscovery/
• apps/
• apiserverinternal/
• authentication/
• authorization/
• autoscaling/
• batch/
• certificates/
• coordination/
• core/
• discovery/
• events/
• extensions/
• flowcontrol/
• networking/
• node/
• policy/
• rbac/
• resource/
• scheduling/
• storage/
• storagemigration/

Each typically has:

• types.go — the internal type
• <version>/types.go — versioned external type aliases or thin shims
• <version>/zz_generated.conversion.go — generated conversion
• <version>/zz_generated.defaults.go — generated defaulters
• <version>/zz_generated.deepcopy.go — generated deep copies
• validation/validation.go — the canonical validation code
• register.go — register types with the scheme

Validation

Validation lives in pkg/apis/<group>/validation/validation.go. The canonical example is pkg/apis/core/validation/validation.go (>30,000 lines counting tests), which validates Pods, Services, Nodes, Volumes, and the rest of core/v1.

Validation functions return field.ErrorList from staging/src/k8s.io/apimachinery/pkg/util/validation/field. Each field.Error carries a path like spec.containers[0].image so clients can highlight the offending field.

Defaulting

Defaulting lives in pkg/apis/<group>/<version>/defaults.go. Defaulters are invoked by the apiserver on read and on write so the in-memory object always has explicit defaults applied.

Strategy

Strategy lives in pkg/registry/<group>/<resource>/strategy.go. See components/kube-apiserver/rest-registry.

Storage wiring

Storage wiring lives in pkg/registry/<group>/<resource>/storage/storage.go. The registry tree:

• pkg/registry/admissionregistration/
• pkg/registry/apiserverinternal/
• pkg/registry/apps/
• pkg/registry/authentication/
• pkg/registry/authorization/
• pkg/registry/autoscaling/
• pkg/registry/batch/
• pkg/registry/certificates/
• pkg/registry/coordination/
• pkg/registry/core/
• pkg/registry/discovery/
• pkg/registry/events/
• pkg/registry/flowcontrol/
• pkg/registry/networking/
• pkg/registry/node/
• pkg/registry/policy/
• pkg/registry/rbac/
• pkg/registry/resource/
• pkg/registry/scheduling/
• pkg/registry/storage/
• pkg/registry/storagemigration/

Plus pkg/registry/registrytest/ with shared test helpers.

Generated artifacts

For every API group, hack/update-codegen.sh produces:

• zz_generated.deepcopy.go (in both internal and versioned)
• zz_generated.conversion.go (in versioned)
• zz_generated.defaults.go (in versioned)
• Typed clientset under staging/src/k8s.io/client-go/kubernetes/typed/<group>/<version>/
• Typed informers under staging/src/k8s.io/client-go/informers/<group>/<version>/
• Typed listers under staging/src/k8s.io/client-go/listers/<group>/<version>/
• ApplyConfigurations under staging/src/k8s.io/client-go/applyconfigurations/<group>/<version>/
• OpenAPI definitions consolidated into pkg/generated/openapi/zz_generated.openapi.go

Field selectors

Each resource declares the field selectors it supports in its strategy's GetAttrs function. The supported set varies wildly by resource — Pod supports spec.nodeName, spec.restartPolicy, status.phase, status.podIP, etc.; many resources support only metadata.name and metadata.namespace.

Where to look first

Question	Path
What does this field mean?	staging/src/k8s.io/api/<group>/<version>/types.go
What are the validation rules?	pkg/apis/<group>/validation/validation.go
What does this resource do on update?	pkg/registry/<group>/<resource>/strategy.go
What subresources exist?	pkg/registry/<group>/<resource>/storage/storage.go
How does the typed client expose this?	staging/src/k8s.io/client-go/kubernetes/typed/<group>/<version>/