Merge pull request kubernetes#130349 from jpbetz/validation-gen-pr1

KEP-5073: Declarative Validation: Add validation generator

Author: k8s-ci-robot

go.mod

@@ -212,7 +212,7 @@ require (
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/natefinch/lumberjack.v2 v2.2.1 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
-	k8s.io/gengo/v2 v2.0.0-20240911193312-2b36238f13e9 // indirect
+	k8s.io/gengo/v2 v2.0.0-20250207200755-1244d31929d7 // indirect
 	sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.31.2 // indirect
 	sigs.k8s.io/json v0.0.0-20241010143419-9aa6b5e7a4b3 // indirect
 	sigs.k8s.io/kustomize/api v0.19.0 // indirect

go.sum

@@ -654,8 +654,8 @@ gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gotest.tools/v3 v3.0.2/go.mod h1:3SzNCllyD9/Y+b5r9JIKQ474KzkZyqLqEfYqMsX94Bk=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
-k8s.io/gengo/v2 v2.0.0-20240911193312-2b36238f13e9 h1:si3PfKm8dDYxgfbeA6orqrtLkvvIeH8UqffFJDl0bz4=
-k8s.io/gengo/v2 v2.0.0-20240911193312-2b36238f13e9/go.mod h1:EJykeLsmFC60UQbYJezXkEsG2FLrt0GPNkU5iK5GWxU=
+k8s.io/gengo/v2 v2.0.0-20250207200755-1244d31929d7 h1:2OX19X59HxDprNCVrWi6jb7LW1PoqTlYqEq5H2oetog=
+k8s.io/gengo/v2 v2.0.0-20250207200755-1244d31929d7/go.mod h1:EJykeLsmFC60UQbYJezXkEsG2FLrt0GPNkU5iK5GWxU=
 k8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk=
 k8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=
 k8s.io/kube-openapi v0.0.0-20241212222426-2c72e554b1e7 h1:hcha5B1kVACrLujCKLbr8XWMxCxzQx42DY8QKYJrDLg=

hack/update-codegen.sh

@@ -52,7 +52,11 @@ fi
 # Generate a list of directories we don't want to play in.
 DIRS_TO_AVOID=()
 kube::util::read-array DIRS_TO_AVOID < <(
-    git ls-files -cmo --exclude-standard -- ':!:vendor/*' ':(glob)*/**/go.work' \
+    git ls-files -cmo --exclude-standard \
+        -- \
+        ':!:vendor/*' \
+        ':(glob)*/**/go.work' \
+        ':(glob)**/_codegenignore/**' \
         | while read -r F; do \
             echo ':!:'"$(dirname "${F}")"; \
         done
@@ -62,15 +66,20 @@ function git_find() {
     # Similar to find but faster and easier to understand.  We want to include
     # modified and untracked files because this might be running against code
     # which is not tracked by git yet.
-    git ls-files -cmo --exclude-standard ':!:vendor/*' "${DIRS_TO_AVOID[@]}" "$@"
+    git ls-files -cmo --exclude-standard \
+        ':!:vendor/*' \
+        "${DIRS_TO_AVOID[@]}" \
+        "$@"
 }
 
 function git_grep() {
     # We want to include modified and untracked files because this might be
     # running against code which is not tracked by git yet.
     # We need vendor exclusion added at the end since it has to be part of
     # the pathspecs which are specified last.
-    git grep --untracked "$@" ':!:vendor/*' "${DIRS_TO_AVOID[@]}"
+    git grep --untracked "$@" \
+        ':!:vendor/*' \
+        "${DIRS_TO_AVOID[@]}"
 }
 
 # Generate a list of all files that have a `+k8s:` comment-tag.  This will be
@@ -380,6 +389,74 @@ function codegen::defaults() {
     fi
 }
 
+# Validation generation
+#
+# Any package that wants validation functions generated must include a
+# comment-tag in column 0 of one file of the form:
+#     // +k8s:validation-gen=<VALUE>
+#
+# The <VALUE> depends on context:
+#     on packages:
+#       *: all exported types are candidates for having validation generated
+#       FIELDNAME: any type with a field of this name is a candidate for
+#                  having validation generated
+#     on types:
+#       true:  always generate validation for this type
+#       false: never generate validation for this type
+function codegen::validation() {
+    # Build the tool.
+    GOPROXY=off go install \
+        k8s.io/code-generator/cmd/validation-gen
+
+    # TODO: Where do we want these output?  It should be somewhere internal..
+    # The result file, in each pkg, of validation generation.
+    local output_file="${GENERATED_FILE_PREFIX}validations.go"
+
+    # All directories that request any form of validation generation.
+    if [[ "${DBG_CODEGEN}" == 1 ]]; then
+        kube::log::status "DBG: finding all +k8s:validation-gen tags"
+    fi
+    local tag_dirs=()
+    kube::util::read-array tag_dirs < <( \
+        grep -l --null '+k8s:validation-gen=' "${ALL_K8S_TAG_FILES[@]}" \
+            | while read -r -d $'\0' F; do dirname "${F}"; done \
+            | sort -u)
+    if [[ "${DBG_CODEGEN}" == 1 ]]; then
+        kube::log::status "DBG: found ${#tag_dirs[@]} +k8s:validation-gen tagged dirs"
+    fi
+
+    local tag_pkgs=()
+    for dir in "${tag_dirs[@]}"; do
+        tag_pkgs+=("./$dir")
+    done
+
+    local extra_pkgs=(
+        k8s.io/apimachinery/pkg/apis/meta/v1
+    )
+
+    kube::log::status "Generating validation code for ${#tag_pkgs[@]} targets"
+    if [[ "${DBG_CODEGEN}" == 1 ]]; then
+        kube::log::status "DBG: running validation-gen for:"
+        for dir in "${tag_dirs[@]}"; do
+            kube::log::status "DBG:     $dir"
+        done
+    fi
+
+    git_find -z ':(glob)**'/"${output_file}" | xargs -0 rm -f
+
+    validation-gen \
+        -v "${KUBE_VERBOSE}" \
+        --go-header-file "${BOILERPLATE_FILENAME}" \
+        --output-file "${output_file}" \
+        $(printf -- " --extra-pkg %s" "${extra_pkgs[@]}") \
+        "${tag_pkgs[@]}" \
+        "$@"
+
+    if [[ "${DBG_CODEGEN}" == 1 ]]; then
+        kube::log::status "Generated validation code"
+    fi
+}
+
 # Conversion generation
 
 # Any package that wants conversion functions generated into it must

staging/publishing/import-restrictions.yaml

@@ -61,6 +61,7 @@
   - k8s.io/code-generator
   - k8s.io/kube-openapi
   - k8s.io/klog
+  - k8s.io/utils/ptr
 
 - baseImportPath: "./staging/src/k8s.io/component-base"
   allowedImports:

staging/src/k8s.io/apiextensions-apiserver/go.mod

@@ -121,7 +121,7 @@ require (
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/natefinch/lumberjack.v2 v2.2.1 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
-	k8s.io/gengo/v2 v2.0.0-20240911193312-2b36238f13e9 // indirect
+	k8s.io/gengo/v2 v2.0.0-20250207200755-1244d31929d7 // indirect
 	k8s.io/kms v0.0.0 // indirect
 	sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.31.2 // indirect
 )

staging/src/k8s.io/apiextensions-apiserver/go.sum

@@ -0,0 +1,56 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package operation
+
+import "k8s.io/apimachinery/pkg/util/sets"
+
+// Operation provides contextual information about a validation request and the API
+// operation being validated.
+// This type is intended for use with generate validation code and may be enhanced
+// in the future to include other information needed to validate requests.
+type Operation struct {
+	// Type is the category of operation being validated.  This does not
+	// differentiate between HTTP verbs like PUT and PATCH, but rather merges
+	// those into a single "Update" category.
+	Type Type
+
+	// Options declare the options enabled for validation.
+	//
+	// Options should be set according to a resource validation strategy before validation
+	// is performed, and must be treated as read-only during validation.
+	//
+	// Options are identified by string names. Option string names may match the name of a feature
+	// gate, in which case the presence of the name in the set indicates that the feature is
+	// considered enabled for the resource being validated.  Note that a resource may have a
+	// feature enabled even when the feature gate is disabled. This can happen when feature is
+	// already in-use by a resource, often because the feature gate was enabled when the
+	// resource first began using the feature.
+	//
+	// Unset options are disabled/false.
+	Options sets.Set[string]
+}
+
+// Code is the request operation to be validated.
+type Type uint32
+
+const (
+	// Create indicates the request being validated is for a resource create operation.
+	Create Type = iota
+
+	// Update indicates the request being validated is for a resource update operation.
+	Update
+)

staging/src/k8s.io/apimachinery/pkg/api/operation/operation.go

@@ -0,0 +1,37 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package safe
+
+// Field takes a pointer to any value (which may or may not be nil) and
+// a function that traverses to a target type R (a typical use case is to dereference a field),
+// and returns the result of the traversal, or the zero value of the target type.
+// This is roughly equivalent to "value != nil ? fn(value) : zero-value" in languages that support the ternary operator.
+func Field[V any, R any](value *V, fn func(*V) R) R {
+	if value == nil {
+		var zero R
+		return zero
+	}
+	o := fn(value)
+	return o
+}
+
+// Cast takes any value, attempts to cast it to T, and returns the T value if
+// the cast is successful, or else the zero value of T.
+func Cast[T any](value any) T {
+	result, _ := value.(T)
+	return result
+}

staging/src/k8s.io/apimachinery/pkg/api/safe/safe.go

@@ -0,0 +1,64 @@
+# API validation
+
+This package holds functions which validate fields and types in the Kubernetes
+API. It may be useful beyond API validation, but this is the primary goal.
+
+Most of the public functions here have signatures which adhere to the following
+pattern, which is assumed by automation and code-generation:
+
+```
+import (
+        "context"
+        "k8s.io/apimachinery/pkg/api/operation"
+        "k8s.io/apimachinery/pkg/util/validation/field"
+)
+
+func <Name>(ctx context.Context, op operation.Operation, fldPath *field.Path, value, oldValue <ValueType>, <OtherArgs...>) field.ErrorList
+```
+
+The name of validator functions should consider that callers will generally be
+spelling out the package name and the function name, and so should aim for
+legibility.  E.g. `validate.Concept()`.
+
+The `ctx` argument is Go's usual Context.
+
+The `opCtx` argument provides information about the API operation in question.
+
+The `fldPath` argument indicates the path to the field in question, to be used
+in errors.
+
+The `value` and `oldValue` arguments are the thing(s) being validated.  For
+CREATE operations (`opCtx.Operation == operation.Create`), the `oldValue`
+argument will be nil.  Many validators functions only look at the current value
+(`value`) and disregard `oldValue`.
+
+The `value` and `oldValue` arguments are always nilable - pointers to primitive
+types, slices of any type, or maps of any type.  Validator functions should
+avoid dereferencing nil. Callers are expected to not pass a nil `value` unless the
+API field itself was nilable. `oldValue` is always nil for CREATE operations and 
+is also nil for UPDATE operations if the `value` is not correlated with an `oldValue`.
+
+Simple content-validators may have no `<OtherArgs>`, but validator functions
+may take additional arguments.  Some validator functions will be built as
+generics, e.g. to allow any integer type or to handle arbitrary slices.
+
+Examples:
+
+```
+// 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
+```
+
+Validator functions always return an `ErrorList` where each item is a distinct
+validation failure and a zero-length return value (not just nil) indicates
+success.
+
+Good validation failure messages follow the Kubernetes API conventions, for
+example using "must" instead of "should".

staging/src/k8s.io/apimachinery/pkg/api/validate/README.md

@@ -0,0 +1,28 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package validate
+
+import (
+	"context"
+
+	"k8s.io/apimachinery/pkg/api/operation"
+	"k8s.io/apimachinery/pkg/util/validation/field"
+)
+
+// ValidateFunc is a function that validates a value, possibly considering the
+// old value (if any).
+type ValidateFunc[T any] func(ctx context.Context, op operation.Operation, fldPath *field.Path, newValue, oldValue T) field.ErrorList