📖 (docs/tutorials): ensure all fields follow Kubernetes API conventions

docs/book/src/cronjob-tutorial/testdata/project/api/v1/cronjob_types.go

@@ -81,6 +81,7 @@ type CronJobSpec struct {
 	// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
 	// - "Replace": cancels currently running job and replaces it with a new one
 	// +optional
+	// +kubebuilder:default:=Allow
 	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
 
 	// suspend tells the controller to suspend subsequent executions, it does
@@ -89,6 +90,7 @@ type CronJobSpec struct {
 	Suspend *bool `json:"suspend,omitempty"`
 
 	// jobTemplate defines the job that will be created when executing a CronJob.
+	// +required
 	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
 
 	// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
@@ -146,6 +148,9 @@ type CronJobStatus struct {
 
 	// active defines a list of pointers to currently running jobs.
 	// +optional
+	// +listType=atomic
+	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:MaxItems=10
 	Active []corev1.ObjectReference `json:"active,omitempty"`
 
 	// lastScheduleTime defines when was the last time the job was successfully scheduled.

docs/book/src/cronjob-tutorial/testdata/project/config/crd/bases/batch.tutorial.kubebuilder.io_cronjobs.yaml

@@ -27,6 +27,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -3835,7 +3836,10 @@ spec:
                       type: string
                   type: object
                   x-kubernetes-map-type: atomic
+                maxItems: 10
+                minItems: 1
                 type: array
+                x-kubernetes-list-type: atomic
               conditions:
                 items:
                   properties:

docs/book/src/cronjob-tutorial/testdata/project/dist/chart/templates/crd/batch.tutorial.kubebuilder.io_cronjobs.yaml

@@ -33,6 +33,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -3841,7 +3842,10 @@ spec:
                       type: string
                   type: object
                   x-kubernetes-map-type: atomic
+                maxItems: 10
+                minItems: 1
                 type: array
+                x-kubernetes-list-type: atomic
               conditions:
                 items:
                   properties:

docs/book/src/cronjob-tutorial/testdata/project/dist/install.yaml

@@ -35,6 +35,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -3843,7 +3844,10 @@ spec:
                       type: string
                   type: object
                   x-kubernetes-map-type: atomic
+                maxItems: 10
+                minItems: 1
                 type: array
+                x-kubernetes-list-type: atomic
               conditions:
                 items:
                   properties:

docs/book/src/cronjob-tutorial/testdata/project/go.mod

@@ -9,6 +9,7 @@ require (
 	k8s.io/api v0.33.0
 	k8s.io/apimachinery v0.33.0
 	k8s.io/client-go v0.33.0
+	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738
 	sigs.k8s.io/controller-runtime v0.21.0
 )
 
@@ -89,7 +90,6 @@ require (
 	k8s.io/component-base v0.33.0 // indirect
 	k8s.io/klog/v2 v2.130.1 // indirect
 	k8s.io/kube-openapi v0.0.0-20250318190949-c8a335a9a2ff // indirect
-	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738 // 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/randfill v1.0.0 // indirect

docs/book/src/cronjob-tutorial/testdata/project/internal/webhook/v1/cronjob_webhook_test.go

@@ -22,6 +22,7 @@ import (
 
 	batchv1 "tutorial.kubebuilder.io/project/api/v1"
 	// TODO (user): Add any additional imports if needed
+	"k8s.io/utils/ptr"
 )
 
 var _ = Describe("CronJob Webhook", func() {
@@ -40,8 +41,8 @@ var _ = Describe("CronJob Webhook", func() {
 			Spec: batchv1.CronJobSpec{
 				Schedule:                   schedule,
 				ConcurrencyPolicy:          batchv1.AllowConcurrent,
-				SuccessfulJobsHistoryLimit: new(int32),
-				FailedJobsHistoryLimit:     new(int32),
+				SuccessfulJobsHistoryLimit: ptr.To(int32(3)),
+				FailedJobsHistoryLimit:     ptr.To(int32(1)),
 			},
 		}
 		*obj.Spec.SuccessfulJobsHistoryLimit = 3
@@ -51,8 +52,8 @@ var _ = Describe("CronJob Webhook", func() {
 			Spec: batchv1.CronJobSpec{
 				Schedule:                   schedule,
 				ConcurrencyPolicy:          batchv1.AllowConcurrent,
-				SuccessfulJobsHistoryLimit: new(int32),
-				FailedJobsHistoryLimit:     new(int32),
+				SuccessfulJobsHistoryLimit: ptr.To(int32(3)),
+				FailedJobsHistoryLimit:     ptr.To(int32(1)),
 			},
 		}
 		*oldObj.Spec.SuccessfulJobsHistoryLimit = 3
@@ -95,20 +96,20 @@ var _ = Describe("CronJob Webhook", func() {
 		It("Should not overwrite fields that are already set", func() {
 			By("setting fields that would normally get a default")
 			obj.Spec.ConcurrencyPolicy = batchv1.ForbidConcurrent
-			obj.Spec.Suspend = new(bool)
-			*obj.Spec.Suspend = true
-			obj.Spec.SuccessfulJobsHistoryLimit = new(int32)
-			*obj.Spec.SuccessfulJobsHistoryLimit = 5
-			obj.Spec.FailedJobsHistoryLimit = new(int32)
-			*obj.Spec.FailedJobsHistoryLimit = 2
+			obj.Spec.Suspend = ptr.To(true)
+			obj.Spec.SuccessfulJobsHistoryLimit = ptr.To(int32(5))
+			obj.Spec.FailedJobsHistoryLimit = ptr.To(int32(2))
 
 			By("calling the Default method to apply defaults")
 			_ = defaulter.Default(ctx, obj)
 
 			By("checking that the fields were not overwritten")
 			Expect(obj.Spec.ConcurrencyPolicy).To(Equal(batchv1.ForbidConcurrent), "Expected ConcurrencyPolicy to retain its set value")
+			Expect(obj.Spec.Suspend).NotTo(BeNil())
 			Expect(*obj.Spec.Suspend).To(BeTrue(), "Expected Suspend to retain its set value")
+			Expect(obj.Spec.SuccessfulJobsHistoryLimit).NotTo(BeNil())
 			Expect(*obj.Spec.SuccessfulJobsHistoryLimit).To(Equal(int32(5)), "Expected SuccessfulJobsHistoryLimit to retain its set value")
+			Expect(obj.Spec.FailedJobsHistoryLimit).NotTo(BeNil())
 			Expect(*obj.Spec.FailedJobsHistoryLimit).To(Equal(int32(2)), "Expected FailedJobsHistoryLimit to retain its set value")
 		})
 	})

docs/book/src/getting-started.md

@@ -83,7 +83,9 @@ we will allow configuring the number of instances with the following:
 ```go
 type MemcachedSpec struct {
 	...
-	Size int32 `json:"size,omitempty"`
+	// +kubebuilder:validation:Minimum=0
+	// +required
+	Size *int32 `json:"size,omitempty"`
 }
 ```
 

docs/book/src/multiversion-tutorial/testdata/project/api/v1/cronjob_types.go

@@ -53,6 +53,7 @@ type CronJobSpec struct {
 	// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
 	// - "Replace": cancels currently running job and replaces it with a new one
 	// +optional
+	// +kubebuilder:default:=Allow
 	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
 
 	// suspend tells the controller to suspend subsequent executions, it does
@@ -61,6 +62,7 @@ type CronJobSpec struct {
 	Suspend *bool `json:"suspend,omitempty"`
 
 	// jobTemplate defines the job that will be created when executing a CronJob.
+	// +required
 	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
 
 	// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
@@ -102,6 +104,9 @@ type CronJobStatus struct {
 
 	// active defines a list of pointers to currently running jobs.
 	// +optional
+	// +listType=atomic
+	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:MaxItems=10
 	Active []corev1.ObjectReference `json:"active,omitempty"`
 
 	// lastScheduleTime defines when was the last time the job was successfully scheduled.

docs/book/src/multiversion-tutorial/testdata/project/api/v2/cronjob_types.go

@@ -41,7 +41,8 @@ We'll leave our spec largely unchanged, except to change the schedule field to a
 */
 // CronJobSpec defines the desired state of CronJob
 type CronJobSpec struct {
-	// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
+	// schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
+	// +required
 	Schedule CronSchedule `json:"schedule"`
 
 	/*
@@ -59,6 +60,7 @@ type CronJobSpec struct {
 	// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
 	// - "Replace": cancels currently running job and replaces it with a new one
 	// +optional
+	// +kubebuilder:default:=Allow
 	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
 
 	// suspend tells the controller to suspend subsequent executions, it does
@@ -67,6 +69,7 @@ type CronJobSpec struct {
 	Suspend *bool `json:"suspend,omitempty"`
 
 	// jobTemplate defines the job that will be created when executing a CronJob.
+	// +required
 	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
 
 	// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
@@ -148,6 +151,9 @@ type CronJobStatus struct {
 	// Important: Run "make" to regenerate code after modifying this file
 	// active defines a list of pointers to currently running jobs.
 	// +optional
+	// +listType=atomic
+	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:MaxItems=10
 	Active []corev1.ObjectReference `json:"active,omitempty"`
 
 	// lastScheduleTime defines the information when was the last time the job was successfully scheduled.

docs/book/src/multiversion-tutorial/testdata/project/config/crd/bases/batch.tutorial.kubebuilder.io_cronjobs.yaml

@@ -27,6 +27,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -3835,7 +3836,10 @@ spec:
                       type: string
                   type: object
                   x-kubernetes-map-type: atomic
+                maxItems: 10
+                minItems: 1
                 type: array
+                x-kubernetes-list-type: atomic
               conditions:
                 items:
                   properties:
@@ -3899,6 +3903,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -7717,7 +7722,10 @@ spec:
                       type: string
                   type: object
                   x-kubernetes-map-type: atomic
+                maxItems: 10
+                minItems: 1
                 type: array
+                x-kubernetes-list-type: atomic
               conditions:
                 items:
                   properties:

docs/book/src/multiversion-tutorial/testdata/project/dist/chart/templates/crd/batch.tutorial.kubebuilder.io_cronjobs.yaml

@@ -48,6 +48,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -3856,7 +3857,10 @@ spec:
                       type: string
                   type: object
                   x-kubernetes-map-type: atomic
+                maxItems: 10
+                minItems: 1
                 type: array
+                x-kubernetes-list-type: atomic
               conditions:
                 items:
                   properties:
@@ -3920,6 +3924,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -7738,7 +7743,10 @@ spec:
                       type: string
                   type: object
                   x-kubernetes-map-type: atomic
+                maxItems: 10
+                minItems: 1
                 type: array
+                x-kubernetes-list-type: atomic
               conditions:
                 items:
                   properties:

docs/book/src/multiversion-tutorial/testdata/project/dist/install.yaml

@@ -46,6 +46,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -3854,7 +3855,10 @@ spec:
                       type: string
                   type: object
                   x-kubernetes-map-type: atomic
+                maxItems: 10
+                minItems: 1
                 type: array
+                x-kubernetes-list-type: atomic
               conditions:
                 items:
                   properties:
@@ -3918,6 +3922,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -7736,7 +7741,10 @@ spec:
                       type: string
                   type: object
                   x-kubernetes-map-type: atomic
+                maxItems: 10
+                minItems: 1
                 type: array
+                x-kubernetes-list-type: atomic
               conditions:
                 items:
                   properties:

docs/book/src/multiversion-tutorial/testdata/project/internal/webhook/v1/cronjob_webhook_test.go

@@ -22,6 +22,7 @@ import (
 
 	batchv1 "tutorial.kubebuilder.io/project/api/v1"
 	// TODO (user): Add any additional imports if needed
+	"k8s.io/utils/ptr"
 )
 
 var _ = Describe("CronJob Webhook", func() {
@@ -39,8 +40,8 @@ var _ = Describe("CronJob Webhook", func() {
 			Spec: batchv1.CronJobSpec{
 				Schedule:                   schedule,
 				ConcurrencyPolicy:          batchv1.AllowConcurrent,
-				SuccessfulJobsHistoryLimit: new(int32),
-				FailedJobsHistoryLimit:     new(int32),
+				SuccessfulJobsHistoryLimit: ptr.To(int32(3)),
+				FailedJobsHistoryLimit:     ptr.To(int32(1)),
 			},
 		}
 		*obj.Spec.SuccessfulJobsHistoryLimit = 3
@@ -50,8 +51,8 @@ var _ = Describe("CronJob Webhook", func() {
 			Spec: batchv1.CronJobSpec{
 				Schedule:                   schedule,
 				ConcurrencyPolicy:          batchv1.AllowConcurrent,
-				SuccessfulJobsHistoryLimit: new(int32),
-				FailedJobsHistoryLimit:     new(int32),
+				SuccessfulJobsHistoryLimit: ptr.To(int32(3)),
+				FailedJobsHistoryLimit:     ptr.To(int32(1)),
 			},
 		}
 		*oldObj.Spec.SuccessfulJobsHistoryLimit = 3

hack/docs/internal/cronjob-tutorial/api_design.go

@@ -67,6 +67,7 @@ const cronjobSpecStruct = `
 	// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
 	// - "Replace": cancels currently running job and replaces it with a new one
 	// +optional
+	// +kubebuilder:default:=Allow
 	ConcurrencyPolicy ConcurrencyPolicy` + " `" + `json:"concurrencyPolicy,omitempty"` + "`" + `
 
 	// suspend tells the controller to suspend subsequent executions, it does
@@ -75,6 +76,7 @@ const cronjobSpecStruct = `
 	Suspend *bool` + " `" + `json:"suspend,omitempty"` + "`" + `
 
 	// jobTemplate defines the job that will be created when executing a CronJob.
+	// +required
 	JobTemplate batchv1.JobTemplateSpec` + " `" + `json:"jobTemplate"` + "`" + `
 
 	// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
@@ -129,6 +131,9 @@ const cronjobList = `
 
 	// active defines a list of pointers to currently running jobs.
 	// +optional
+	// +listType=atomic
+	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:MaxItems=10
 	Active []corev1.ObjectReference` + " `" + `json:"active,omitempty"` + "`" + `
 
 	// lastScheduleTime defines when was the last time the job was successfully scheduled.