Skip to content

Commit fb53f01

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #4916 from camilamacedo86/cronjob-tutorials-docs-fixes
📖 Update Cronjob Tutorials API spec descriptions to better adopt k8s API convetions
2 parents 6ba543b + 94beea5 commit fb53f01

File tree

5 files changed

+71
-86
lines changed

5 files changed

+71
-86
lines changed

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

Lines changed: 13 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -64,46 +64,43 @@ import (
6464

6565
// CronJobSpec defines the desired state of CronJob
6666
type CronJobSpec struct {
67+
// schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
6768
// +kubebuilder:validation:MinLength=0
68-
69-
// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
69+
// +required
7070
Schedule string `json:"schedule"`
7171

72-
// +kubebuilder:validation:Minimum=0
73-
74-
// Optional deadline in seconds for starting the job if it misses scheduled
72+
// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
7573
// time for any reason. Missed jobs executions will be counted as failed ones.
7674
// +optional
75+
// +kubebuilder:validation:Minimum=0
7776
StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`
7877

79-
// Specifies how to treat concurrent executions of a Job.
78+
// concurrencyPolicy specifies how to treat concurrent executions of a Job.
8079
// Valid values are:
8180
// - "Allow" (default): allows CronJobs to run concurrently;
8281
// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
8382
// - "Replace": cancels currently running job and replaces it with a new one
8483
// +optional
8584
ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
8685

87-
// This flag tells the controller to suspend subsequent executions, it does
86+
// suspend tells the controller to suspend subsequent executions, it does
8887
// not apply to already started executions. Defaults to false.
8988
// +optional
9089
Suspend *bool `json:"suspend,omitempty"`
9190

92-
// Specifies the job that will be created when executing a CronJob.
91+
// jobTemplate defines the job that will be created when executing a CronJob.
9392
JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
9493

95-
// +kubebuilder:validation:Minimum=0
96-
97-
// The number of successful finished jobs to retain.
94+
// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
9895
// This is a pointer to distinguish between explicit zero and not specified.
9996
// +optional
100-
SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
101-
10297
// +kubebuilder:validation:Minimum=0
98+
SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
10399

104-
// The number of failed finished jobs to retain.
100+
// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
105101
// This is a pointer to distinguish between explicit zero and not specified.
106102
// +optional
103+
// +kubebuilder:validation:Minimum=0
107104
FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
108105
}
109106

@@ -147,11 +144,11 @@ type CronJobStatus struct {
147144
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
148145
// Important: Run "make" to regenerate code after modifying this file
149146

150-
// A list of pointers to currently running jobs.
147+
// active defines a list of pointers to currently running jobs.
151148
// +optional
152149
Active []corev1.ObjectReference `json:"active,omitempty"`
153150

154-
// Information when was the last time the job was successfully scheduled.
151+
// lastScheduleTime defines when was the last time the job was successfully scheduled.
155152
// +optional
156153
LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`
157154
}

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

Lines changed: 13 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -36,46 +36,43 @@ import (
3636

3737
// CronJobSpec defines the desired state of CronJob
3838
type CronJobSpec struct {
39+
// schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
3940
// +kubebuilder:validation:MinLength=0
40-
41-
// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
41+
// +required
4242
Schedule string `json:"schedule"`
4343

44-
// +kubebuilder:validation:Minimum=0
45-
46-
// Optional deadline in seconds for starting the job if it misses scheduled
44+
// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
4745
// time for any reason. Missed jobs executions will be counted as failed ones.
4846
// +optional
47+
// +kubebuilder:validation:Minimum=0
4948
StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`
5049

51-
// Specifies how to treat concurrent executions of a Job.
50+
// concurrencyPolicy specifies how to treat concurrent executions of a Job.
5251
// Valid values are:
5352
// - "Allow" (default): allows CronJobs to run concurrently;
5453
// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
5554
// - "Replace": cancels currently running job and replaces it with a new one
5655
// +optional
5756
ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
5857

59-
// This flag tells the controller to suspend subsequent executions, it does
58+
// suspend tells the controller to suspend subsequent executions, it does
6059
// not apply to already started executions. Defaults to false.
6160
// +optional
6261
Suspend *bool `json:"suspend,omitempty"`
6362

64-
// Specifies the job that will be created when executing a CronJob.
63+
// jobTemplate defines the job that will be created when executing a CronJob.
6564
JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
6665

67-
// +kubebuilder:validation:Minimum=0
68-
69-
// The number of successful finished jobs to retain.
66+
// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
7067
// This is a pointer to distinguish between explicit zero and not specified.
7168
// +optional
72-
SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
73-
7469
// +kubebuilder:validation:Minimum=0
70+
SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
7571

76-
// The number of failed finished jobs to retain.
72+
// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
7773
// This is a pointer to distinguish between explicit zero and not specified.
7874
// +optional
75+
// +kubebuilder:validation:Minimum=0
7976
FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
8077
}
8178

@@ -103,11 +100,11 @@ type CronJobStatus struct {
103100
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
104101
// Important: Run "make" to regenerate code after modifying this file
105102

106-
// A list of pointers to currently running jobs.
103+
// active defines a list of pointers to currently running jobs.
107104
// +optional
108105
Active []corev1.ObjectReference `json:"active,omitempty"`
109106

110-
// Information when was the last time the job was successfully scheduled.
107+
// lastScheduleTime defines when was the last time the job was successfully scheduled.
111108
// +optional
112109
LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`
113110
}

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

Lines changed: 16 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -47,41 +47,38 @@ type CronJobSpec struct {
4747
/*
4848
*/
4949

50-
// +kubebuilder:validation:Minimum=0
51-
52-
// Optional deadline in seconds for starting the job if it misses scheduled
50+
// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
5351
// time for any reason. Missed jobs executions will be counted as failed ones.
5452
// +optional
53+
// +kubebuilder:validation:Minimum=0
5554
StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`
5655

57-
// Specifies how to treat concurrent executions of a Job.
56+
// concurrencyPolicy defines how to treat concurrent executions of a Job.
5857
// Valid values are:
5958
// - "Allow" (default): allows CronJobs to run concurrently;
6059
// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
6160
// - "Replace": cancels currently running job and replaces it with a new one
6261
// +optional
6362
ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
6463

65-
// This flag tells the controller to suspend subsequent executions, it does
64+
// suspend tells the controller to suspend subsequent executions, it does
6665
// not apply to already started executions. Defaults to false.
6766
// +optional
6867
Suspend *bool `json:"suspend,omitempty"`
6968

70-
// Specifies the job that will be created when executing a CronJob.
69+
// jobTemplate defines the job that will be created when executing a CronJob.
7170
JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
7271

73-
// +kubebuilder:validation:Minimum=0
74-
75-
// The number of successful finished jobs to retain.
72+
// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
7673
// This is a pointer to distinguish between explicit zero and not specified.
7774
// +optional
78-
SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
79-
8075
// +kubebuilder:validation:Minimum=0
76+
SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
8177

82-
// The number of failed finished jobs to retain.
78+
// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
8379
// This is a pointer to distinguish between explicit zero and not specified.
8480
// +optional
81+
// +kubebuilder:validation:Minimum=0
8582
FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
8683

8784
// +kubebuilder:docs-gen:collapse=The rest of Spec
@@ -96,19 +93,19 @@ each corresponding Cron "field".
9693

9794
// describes a Cron schedule.
9895
type CronSchedule struct {
99-
// specifies the minute during which the job executes.
96+
// minute specifies the minutes during which the job executes.
10097
// +optional
10198
Minute *CronField `json:"minute,omitempty"`
102-
// specifies the hour during which the job executes.
99+
// hour specifies the hour during which the job executes.
103100
// +optional
104101
Hour *CronField `json:"hour,omitempty"`
105-
// specifies the day of the month during which the job executes.
102+
// dayOfMonth specifies the day of the month during which the job executes.
106103
// +optional
107104
DayOfMonth *CronField `json:"dayOfMonth,omitempty"`
108-
// specifies the month during which the job executes.
105+
// month specifies the month during which the job executes.
109106
// +optional
110107
Month *CronField `json:"month,omitempty"`
111-
// specifies the day of the week during which the job executes.
108+
// dayOfWeek specifies the day of the week during which the job executes.
112109
// +optional
113110
DayOfWeek *CronField `json:"dayOfWeek,omitempty"`
114111
}
@@ -150,11 +147,11 @@ type CronJobStatus struct {
150147
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
151148
// Important: Run "make" to regenerate code after modifying this file
152149

153-
// A list of pointers to currently running jobs.
150+
// active defines a list of pointers to currently running jobs.
154151
// +optional
155152
Active []corev1.ObjectReference `json:"active,omitempty"`
156153

157-
// Information when was the last time the job was successfully scheduled.
154+
// lastScheduleTime defines the information when was the last time the job was successfully scheduled.
158155
// +optional
159156
LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`
160157
}

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

Lines changed: 13 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -50,46 +50,43 @@ const cronjobSpecExplaination = `
5050
`
5151

5252
const cronjobSpecStruct = `
53+
// schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
5354
// +kubebuilder:validation:MinLength=0
54-
55-
// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
55+
// +required
5656
Schedule string` + " `" + `json:"schedule"` + "`" + `
5757
58-
// +kubebuilder:validation:Minimum=0
59-
60-
// Optional deadline in seconds for starting the job if it misses scheduled
58+
// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
6159
// time for any reason. Missed jobs executions will be counted as failed ones.
6260
// +optional
61+
// +kubebuilder:validation:Minimum=0
6362
StartingDeadlineSeconds *int64` + " `" + `json:"startingDeadlineSeconds,omitempty"` + "`" + `
6463
65-
// Specifies how to treat concurrent executions of a Job.
64+
// concurrencyPolicy specifies how to treat concurrent executions of a Job.
6665
// Valid values are:
6766
// - "Allow" (default): allows CronJobs to run concurrently;
6867
// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
6968
// - "Replace": cancels currently running job and replaces it with a new one
7069
// +optional
7170
ConcurrencyPolicy ConcurrencyPolicy` + " `" + `json:"concurrencyPolicy,omitempty"` + "`" + `
7271
73-
// This flag tells the controller to suspend subsequent executions, it does
72+
// suspend tells the controller to suspend subsequent executions, it does
7473
// not apply to already started executions. Defaults to false.
7574
// +optional
7675
Suspend *bool` + " `" + `json:"suspend,omitempty"` + "`" + `
7776
78-
// Specifies the job that will be created when executing a CronJob.
77+
// jobTemplate defines the job that will be created when executing a CronJob.
7978
JobTemplate batchv1.JobTemplateSpec` + " `" + `json:"jobTemplate"` + "`" + `
8079
81-
// +kubebuilder:validation:Minimum=0
82-
83-
// The number of successful finished jobs to retain.
80+
// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
8481
// This is a pointer to distinguish between explicit zero and not specified.
8582
// +optional
86-
SuccessfulJobsHistoryLimit *int32` + " `" + `json:"successfulJobsHistoryLimit,omitempty"` + "`" + `
87-
8883
// +kubebuilder:validation:Minimum=0
84+
SuccessfulJobsHistoryLimit *int32` + " `" + `json:"successfulJobsHistoryLimit,omitempty"` + "`" + `
8985
90-
// The number of failed finished jobs to retain.
86+
// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
9187
// This is a pointer to distinguish between explicit zero and not specified.
9288
// +optional
89+
// +kubebuilder:validation:Minimum=0
9390
FailedJobsHistoryLimit *int32` + " `" + `json:"failedJobsHistoryLimit,omitempty"` + "`" + `
9491
}
9592
@@ -130,11 +127,11 @@ const (
130127

131128
const cronjobList = `
132129
133-
// A list of pointers to currently running jobs.
130+
// active defines a list of pointers to currently running jobs.
134131
// +optional
135132
Active []corev1.ObjectReference` + " `" + `json:"active,omitempty"` + "`" + `
136133
137-
// Information when was the last time the job was successfully scheduled.
134+
// lastScheduleTime defines when was the last time the job was successfully scheduled.
138135
// +optional
139136
LastScheduleTime *metav1.Time` + " `" + `json:"lastScheduleTime,omitempty"` + "`" + `
140137
}

‎hack/docs/internal/multiversion-tutorial/cronjob_v2.go

Lines changed: 16 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -36,19 +36,19 @@ each corresponding Cron "field".
3636
3737
// describes a Cron schedule.
3838
type CronSchedule struct {
39-
// specifies the minute during which the job executes.
39+
// minute specifies the minutes during which the job executes.
4040
// +optional
4141
Minute *CronField ` + "`json:\"minute,omitempty\"`" + `
42-
// specifies the hour during which the job executes.
42+
// hour specifies the hour during which the job executes.
4343
// +optional
4444
Hour *CronField ` + "`json:\"hour,omitempty\"`" + `
45-
// specifies the day of the month during which the job executes.
45+
// dayOfMonth specifies the day of the month during which the job executes.
4646
// +optional
4747
DayOfMonth *CronField ` + "`json:\"dayOfMonth,omitempty\"`" + `
48-
// specifies the month during which the job executes.
48+
// month specifies the month during which the job executes.
4949
// +optional
5050
Month *CronField ` + "`json:\"month,omitempty\"`" + `
51-
// specifies the day of the week during which the job executes.
51+
// dayOfWeek specifies the day of the week during which the job executes.
5252
// +optional
5353
DayOfWeek *CronField ` + "`json:\"dayOfWeek,omitempty\"`" + `
5454
}
@@ -90,52 +90,49 @@ type CronJobStatus struct {
9090
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
9191
// Important: Run "make" to regenerate code after modifying this file
9292
93-
// A list of pointers to currently running jobs.
93+
// active defines a list of pointers to currently running jobs.
9494
// +optional
9595
Active []corev1.ObjectReference ` + "`json:\"active,omitempty\"`" + `
9696
97-
// Information when was the last time the job was successfully scheduled.
97+
// lastScheduleTime defines the information when was the last time the job was successfully scheduled.
9898
// +optional
9999
LastScheduleTime *metav1.Time ` + "`json:\"lastScheduleTime,omitempty\"`" + `
100100
}
101101
`
102102

103103
const cronJobSpecReplace = `
104-
// +kubebuilder:validation:Minimum=0
105-
106-
// Optional deadline in seconds for starting the job if it misses scheduled
104+
// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
107105
// time for any reason. Missed jobs executions will be counted as failed ones.
108106
// +optional
107+
// +kubebuilder:validation:Minimum=0
109108
StartingDeadlineSeconds *int64 ` + "`json:\"startingDeadlineSeconds,omitempty\"`" + `
110109
111-
// Specifies how to treat concurrent executions of a Job.
110+
// concurrencyPolicy defines how to treat concurrent executions of a Job.
112111
// Valid values are:
113112
// - "Allow" (default): allows CronJobs to run concurrently;
114113
// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
115114
// - "Replace": cancels currently running job and replaces it with a new one
116115
// +optional
117116
ConcurrencyPolicy ConcurrencyPolicy ` + "`json:\"concurrencyPolicy,omitempty\"`" + `
118117
119-
// This flag tells the controller to suspend subsequent executions, it does
118+
// suspend tells the controller to suspend subsequent executions, it does
120119
// not apply to already started executions. Defaults to false.
121120
// +optional
122121
Suspend *bool ` + "`json:\"suspend,omitempty\"`" + `
123122
124-
// Specifies the job that will be created when executing a CronJob.
123+
// jobTemplate defines the job that will be created when executing a CronJob.
125124
JobTemplate batchv1.JobTemplateSpec ` + "`json:\"jobTemplate\"`" + `
126125
127-
// +kubebuilder:validation:Minimum=0
128-
129-
// The number of successful finished jobs to retain.
126+
// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
130127
// This is a pointer to distinguish between explicit zero and not specified.
131128
// +optional
132-
SuccessfulJobsHistoryLimit *int32 ` + "`json:\"successfulJobsHistoryLimit,omitempty\"`" + `
133-
134129
// +kubebuilder:validation:Minimum=0
130+
SuccessfulJobsHistoryLimit *int32 ` + "`json:\"successfulJobsHistoryLimit,omitempty\"`" + `
135131
136-
// The number of failed finished jobs to retain.
132+
// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
137133
// This is a pointer to distinguish between explicit zero and not specified.
138134
// +optional
135+
// +kubebuilder:validation:Minimum=0
139136
FailedJobsHistoryLimit *int32 ` + "`json:\"failedJobsHistoryLimit,omitempty\"`" + `
140137
141138
// +kubebuilder:docs-gen:collapse=The rest of Spec

0 commit comments

Comments
 (0)