Kubernetes apimachinery

When using apimachinery, keep the following constraints in mind:

Compatibility

There are NO compatibility guarantees for this repository. It tracks the main Kubernetes repository closely. Users should expect breaking changes as the library evolves alongside Kubernetes.

Contribution and Source

This is a staged, read-only repository.

• Do not contribute here: All issues and pull requests must be directed to the main kubernetes/kubernetes repository.
• Source of truth: The code is synced from k8s.io/kubernetes/staging/src/k8s.io/apimachinery within the main Kubernetes repo.

Usage Restrictions

• Do not add API types: This repository is intended for the underlying machinery, not for defining specific API resource types.
• Do not modify pkg/: Files under the pkg directory are driven by the staging area in the main Kubernetes repository; manual changes here will be overwritten.

The pkg/api/validate package provides functions to validate fields and types in the Kubernetes API. Most public validator functions follow a standardized signature designed for automation and code generation. When implementing or calling these validators, you should expect the following pattern:

func <Name>(ctx context.Context, op operation.Operation, fldPath *field.Path, value, oldValue <ValueType>, <OtherArgs...>) field.ErrorList

Argument Details:

• ctx: Standard Go context.Context.
• op: An operation.Operation providing context about the API operation (e.g., operation.Create, operation.Update).
• fldPath: A *field.Path representing the location of the field being validated; this is used to construct descriptive error messages.
• value: The current value being validated. This is always nilable.
• oldValue: The previous value (used primarily during UPDATE operations). For CREATE operations, this is always nil. This is also always nilable.
• <OtherArgs...>: Optional additional arguments required for specific validation logic (e.g., a maximum length constraint).

Return Value:

Validators always return a field.ErrorList.

• Success: A zero-length field.ErrorList (not necessarily nil).
• Failure: An ErrorList containing one or more distinct validation failures.

import (
        "context"
        "k8s.io/apimachinery/pkg/api/operation"
        "k8s.io/apimachinery/pkg/util/validation/field"
)

// Example signature pattern
func ValidateSomething(ctx context.Context, op operation.Operation, fldPath *field.Path, value, oldValue *string) field.ErrorList

Validator functions can range from simple content checks to complex generic validators.

Implementation Patterns:

• Simple Validators: Check a single property (e.g., NonEmpty for strings).
• Generic Validators: Use Go generics to handle various types (e.g., Even for slices of any type).
• Parameterized Validators: Accept extra arguments for constraints (e.g., KeysMaxLen for map key length limits).

Best Practices:

• Nil Safety: Since value and oldValue are always nilable (pointers, slices, or maps), validator functions must avoid dereferencing nil.
• Naming: Function names should be legible when prefixed with the package name (e.g., validate.Concept()).
• Error Messaging: Follow Kubernetes API conventions by using "must" instead of "should" in error messages.

// NonEmpty validates that a string is not empty.
func NonEmpty(ctx context.Context, op operation.Operation, fldPath *field.Path, value, _ *string) field.ErrorList

// Even validates that a slice has an even number of items.
func Even[T any](ctx context.Context, op operation.Operation, fldPath *field.Path, value, _ []T) field.ErrorList

// KeysMaxLen validates that all of the string keys in a map are under the
// specified length.
func KeysMaxLen[T any](ctx context.Context, op operation.Operation, fldPath *field.Path, value, _ map[string]T, maxLen int) field.ErrorList