🌱 Update cronjob-tutorial automatically

.golangci.yml

@@ -11,6 +11,10 @@ issues:
   exclude-rules:
     - linters: [gosec]
       path: "test/e2e/*"
+    - path: "hack/docs/*"
+      linters:
+        - lll
+        - gosec
 
 linters-settings:
   govet:

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

@@ -17,10 +17,12 @@ limitations under the License.
 
 /*
  */
+
 package v1
 
 /*
  */
+
 import (
 	batchv1 "k8s.io/api/batch/v1"
 	corev1 "k8s.io/api/core/v1"

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

@@ -54,7 +54,7 @@ This marker is responsible for generating a mutating webhook manifest.
 The meaning of each marker can be found [here](/reference/markers/webhook.md).
 */
 
-//+kubebuilder:webhook:path=/mutate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=true,failurePolicy=fail,sideEffects=None,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=mcronjob.kb.io,admissionReviewVersions=v1
+//+kubebuilder:webhook:path=/mutate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=true,failurePolicy=fail,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=mcronjob.kb.io,sideEffects=None,admissionReviewVersions=v1
 
 /*
 We use the `webhook.Defaulter` interface to set defaults to our CRD.

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

@@ -39,6 +39,7 @@ Since we need to use all the types in this package in our controller, it's
 helpful (and the convention) to have a convenient method to add all the types to
 some other `Scheme`. SchemeBuilder makes this easy for us.
 */
+
 var (
 	// GroupVersion is group version used to register these objects
 	GroupVersion = schema.GroupVersion{Group: "batch.tutorial.kubebuilder.io", Version: "v1"}

docs/book/src/cronjob-tutorial/testdata/project/cmd/main.go

@@ -20,7 +20,6 @@ package main
 import (
 	"flag"
 	"os"
-	"tutorial.kubebuilder.io/project/internal/controller"
 
 	// Import all Kubernetes client auth plugins (e.g. Azure, GCP, OIDC, etc.)
 	// to ensure that exec-entrypoint and run can make use of them.
@@ -34,6 +33,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/log/zap"
 
 	batchv1 "tutorial.kubebuilder.io/project/api/v1"
+	"tutorial.kubebuilder.io/project/internal/controller"
 	//+kubebuilder:scaffold:imports
 )
 
@@ -47,6 +47,7 @@ objects in our controller.
 If we would be using any other CRD we would have to add their scheme the same way.
 Builtin types such as Job have their scheme added by `clientgoscheme`.
 */
+
 var (
 	scheme   = runtime.NewScheme()
 	setupLog = ctrl.Log.WithName("setup")

docs/book/src/cronjob-tutorial/testdata/project/config/samples/batch_v1_cronjob.yaml

@@ -23,4 +23,5 @@ spec:
             - /bin/sh
             - -c
             - date; echo Hello from the Kubernetes cluster
-          restartPolicy: OnFailure
+          restartPolicy: OnFailure
+

docs/book/src/cronjob-tutorial/testdata/project/internal/controller/cronjob_controller.go

@@ -19,6 +19,7 @@ limitations under the License.
 We'll start out with some imports.  You'll see below that we'll need a few more imports
 than those scaffolded for us.  We'll talk about each one when we use it.
 */
+
 package controller
 
 import (
@@ -547,6 +548,7 @@ var (
 	apiGVStr    = batchv1.GroupVersion.String()
 )
 
+// SetupWithManager sets up the controller with the Manager.
 func (r *CronJobReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	// set up a real clock, since we're not in a test
 	if r.Clock == nil {

docs/book/src/cronjob-tutorial/testdata/project/internal/controller/suite_test.go

@@ -22,6 +22,7 @@ Kubebuilder scaffolded a `internal/controller/suite_test.go` file that does the
 First, it will contain the necessary imports.
 */
 
+
 package controller
 
 import (
@@ -33,6 +34,7 @@ import (
 
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
+
 	"k8s.io/client-go/kubernetes/scheme"
 	"k8s.io/client-go/rest"
 	"sigs.k8s.io/controller-runtime/pkg/client"

hack/docs/check.sh

@@ -14,6 +14,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+source "$(dirname "$0")/../../test/common.sh"
+
+build_kb
 
 check_directory="$(dirname "$0")/../../docs/book/src/"
 

hack/docs/generate_samples.go

@@ -19,7 +19,9 @@ package main
 import (
 	"fmt"
 
-	componentconfig "sigs.k8s.io/kubebuilder/v3/hack/docs/internal"
+	componentconfig "sigs.k8s.io/kubebuilder/v3/hack/docs/internal/component-config-tutorial"
+	cronjob "sigs.k8s.io/kubebuilder/v3/hack/docs/internal/cronjob-tutorial"
+	"sigs.k8s.io/kubebuilder/v3/pkg/plugin/util"
 )
 
 func main() {
@@ -28,13 +30,13 @@ func main() {
 	fmt.Println("Generating component-config tutorial...")
 	UpdateComponentConfigTutorial()
 
-	// TODO: Generate cronjob-tutorial
-
+	fmt.Println("Generating cronjob tutorial...")
+	UpdateCronjobTutorial()
 	// TODO: Generate multiversion-tutorial
 }
 
 func UpdateComponentConfigTutorial() {
-	binaryPath := "/tmp/kubebuilder/bin/kubebuilder"
+	binaryPath := util.KubebuilderBinName
 	samplePath := "docs/book/src/component-config-tutorial/testdata/project/"
 
 	sp := componentconfig.NewSample(binaryPath, samplePath)
@@ -47,3 +49,16 @@ func UpdateComponentConfigTutorial() {
 
 	sp.CodeGen()
 }
+
+func UpdateCronjobTutorial() {
+	binaryPath := util.KubebuilderBinName
+	samplePath := "docs/book/src/cronjob-tutorial/testdata/project/"
+
+	sp := cronjob.NewSample(binaryPath, samplePath)
+
+	sp.Prepare()
+
+	sp.GenerateSampleProject()
+
+	sp.UpdateTutorial()
+}

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

@@ -0,0 +1,148 @@
+/*
+Copyright 2023 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 cronjob
+
+const CronjobSpecExplaination = `
+
+// +kubebuilder:docs-gen:collapse=Imports
+
+/*
+ First, let's take a look at our spec.  As we discussed before, spec holds
+ *desired state*, so any "inputs" to our controller go here.
+
+ Fundamentally a CronJob needs the following pieces:
+
+ - A schedule (the *cron* in CronJob)
+ - A template for the Job to run (the
+ *job* in CronJob)
+
+ We'll also want a few extras, which will make our users' lives easier:
+
+ - A deadline for starting jobs (if we miss this deadline, we'll just wait till
+   the next scheduled time)
+ - What to do if multiple jobs would run at once (do we wait? stop the old one? run both?)
+ - A way to pause the running of a CronJob, in case something's wrong with it
+ - Limits on old job history
+
+ Remember, since we never read our own status, we need to have some other way to
+ keep track of whether a job has run.  We can use at least one old job to do
+ this.
+
+ We'll use several markers (` + "`" + `// +comment` + "`" + `) to specify additional metadata.  These
+ will be used by [controller-tools](https://github.com/kubernetes-sigs/controller-tools) when generating our CRD manifest.
+ As we'll see in a bit, controller-tools will also use GoDoc to form descriptions for
+ the fields.
+*/
+`
+
+const CronjobSpecStruct = `
+	//+kubebuilder:validation:MinLength=0
+
+	// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
+	Schedule string` + " `" + `json:"schedule"` + "`" + `
+
+	//+kubebuilder:validation:Minimum=0
+
+	// Optional deadline in seconds for starting the job if it misses scheduled
+	// time for any reason.  Missed jobs executions will be counted as failed ones.
+	// +optional
+	StartingDeadlineSeconds *int64` + " `" + `json:"startingDeadlineSeconds,omitempty"` + "`" + `
+
+	// Specifies how to treat concurrent executions of a Job.
+	// Valid values are:
+	// - "Allow" (default): allows CronJobs to run concurrently;
+	// - "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
+	ConcurrencyPolicy ConcurrencyPolicy` + " `" + `json:"concurrencyPolicy,omitempty"` + "`" + `
+
+	// This flag tells the controller to suspend subsequent executions, it does
+	// not apply to already started executions.  Defaults to false.
+	// +optional
+	Suspend *bool` + " `" + `json:"suspend,omitempty"` + "`" + `
+
+	// Specifies the job that will be created when executing a CronJob.
+	JobTemplate batchv1.JobTemplateSpec` + " `" + `json:"jobTemplate"` + "`" + `
+
+	//+kubebuilder:validation:Minimum=0
+
+	// The number of successful finished jobs to retain.
+	// This is a pointer to distinguish between explicit zero and not specified.
+	// +optional
+	SuccessfulJobsHistoryLimit *int32` + " `" + `json:"successfulJobsHistoryLimit,omitempty"` + "`" + `
+
+	//+kubebuilder:validation:Minimum=0
+
+	// The number of failed finished jobs to retain.
+	// This is a pointer to distinguish between explicit zero and not specified.
+	// +optional
+	FailedJobsHistoryLimit *int32` + " `" + `json:"failedJobsHistoryLimit,omitempty"` + "`" + `
+}
+
+/*
+ We define a custom type to hold our concurrency policy.  It's actually
+ just a string under the hood, but the type gives extra documentation,
+ and allows us to attach validation on the type instead of the field,
+ making the validation more easily reusable.
+*/
+
+// ConcurrencyPolicy describes how the job will be handled.
+// Only one of the following concurrent policies may be specified.
+// If none of the following policies is specified, the default one
+// is AllowConcurrent.
+// +kubebuilder:validation:Enum=Allow;Forbid;Replace
+type ConcurrencyPolicy string
+
+const (
+	// AllowConcurrent allows CronJobs to run concurrently.
+	AllowConcurrent ConcurrencyPolicy = "Allow"
+
+	// ForbidConcurrent forbids concurrent runs, skipping next run if previous
+	// hasn't finished yet.
+	ForbidConcurrent ConcurrencyPolicy = "Forbid"
+
+	// ReplaceConcurrent cancels currently running job and replaces it with a new one.
+	ReplaceConcurrent ConcurrencyPolicy = "Replace"
+)
+
+/*
+ Next, let's design our status, which holds observed state.  It contains any information
+ we want users or other controllers to be able to easily obtain.
+
+ We'll keep a list of actively running jobs, as well as the last time that we successfully
+ ran our job.  Notice that we use` + " `" + `metav1.Time` + "`" + ` instead of` + " `" + `time.Time` + "`" + ` to get the stable
+ serialization, as mentioned above.
+*/`
+
+const CronjobList = `
+
+	// A list of pointers to currently running jobs.
+	// +optional
+	Active []corev1.ObjectReference` + " `" + `json:"active,omitempty"` + "`" + `
+
+	// Information when was the last time the job was successfully scheduled.
+	// +optional
+	LastScheduleTime *metav1.Time` + " `" + `json:"lastScheduleTime,omitempty"` + "`" + `
+}
+
+/*
+ Finally, we have the rest of the boilerplate that we've already discussed.
+ As previously noted, we don't need to change this, except to mark that
+ we want a status subresource, so that we behave like built-in kubernetes types.
+*/
+
+`