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

Author: camilamacedo86

diff.txt

@@ -12,7 +12,7 @@ index e4ce67d37..df8b86128 100644
 -	// +kubebuilder:validation:Minimum=1
 -	// +kubebuilder:validation:Maximum=3
 -	// +kubebuilder:validation:ExclusiveMaximum=false
--	Size int32 `json:"size,omitempty"`
+-	Size *int32 `json:"size,omitempty"`
 +	// size defines the number of Busybox instances
 +	// +kubebuilder:default=1
 +	// +kubebuilder:validation:Minimum=0

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

@@ -81,6 +81,8 @@ 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:validation:Enum=Allow;Forbid;Replace
+	// +kubebuilder:default:=Allow
 	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
 
 	// suspend tells the controller to suspend subsequent executions, it does
@@ -89,6 +91,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 +149,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,10 +27,16 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
-                enum:
-                - Allow
-                - Forbid
-                - Replace
+                allOf:
+                - enum:
+                  - Allow
+                  - Forbid
+                  - Replace
+                - enum:
+                  - Allow
+                  - Forbid
+                  - Replace
+                default: Allow
                 type: string
               failedJobsHistoryLimit:
                 format: int32
@@ -3835,7 +3841,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,10 +33,16 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
-                enum:
-                - Allow
-                - Forbid
-                - Replace
+                allOf:
+                - enum:
+                  - Allow
+                  - Forbid
+                  - Replace
+                - enum:
+                  - Allow
+                  - Forbid
+                  - Replace
+                default: Allow
                 type: string
               failedJobsHistoryLimit:
                 format: int32
@@ -3841,7 +3847,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,10 +35,16 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
-                enum:
-                - Allow
-                - Forbid
-                - Replace
+                allOf:
+                - enum:
+                  - Allow
+                  - Forbid
+                  - Replace
+                - enum:
+                  - Allow
+                  - Forbid
+                  - Replace
+                default: Allow
                 type: string
               failedJobsHistoryLimit:
                 format: int32
@@ -3843,7 +3849,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,8 @@ 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:validation:Enum=Allow;Forbid;Replace
+	// +kubebuilder:default:=Allow
 	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
 
 	// suspend tells the controller to suspend subsequent executions, it does
@@ -61,6 +63,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 +105,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,8 @@ 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:validation:Enum=Allow;Forbid;Replace
+	// +kubebuilder:default:=Allow
 	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
 
 	// suspend tells the controller to suspend subsequent executions, it does
@@ -67,6 +70,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 +152,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.