Merge pull request #54920 from tengqm/improve-cronjob-doc

Automatic merge from submit-queue. If you want to cherry-pick this change to another branch, please follow the instructions <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md">here</a>.

Improve cronjob concurrency policy doc

**What this PR does / why we need it**:
The CronJob API documentation (https://kubernetes.io/docs/api-reference/v1.8/#cronjobspec-v1beta1-batch) did not clearly state what can be used as `concurrencyPolicy`. Instead, it only says that the default value is "Raw".

**Which issue(s) this PR fixes**:

**Special notes for your reviewer**:
This patch is not changing any code logic but it involves generated "code".

**Release note**:
```release-note
NONE
```

api/openapi-spec/swagger.json

@@ -70759,7 +70759,7 @@
     ],
     "properties": {
      "concurrencyPolicy": {
-      "description": "Specifies how to treat concurrent executions of a Job. Defaults to Allow.",
+      "description": "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",
       "type": "string"
      },
      "failedJobsHistoryLimit": {
@@ -70894,7 +70894,7 @@
     ],
     "properties": {
      "concurrencyPolicy": {
-      "description": "Specifies how to treat concurrent executions of a Job. Defaults to Allow.",
+      "description": "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",
       "type": "string"
      },
      "failedJobsHistoryLimit": {

api/swagger-spec/batch_v1beta1.json

@@ -1504,7 +1504,7 @@
      },
      "concurrencyPolicy": {
       "type": "string",
-      "description": "Specifies how to treat concurrent executions of a Job. Defaults to Allow."
+      "description": "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"
      },
      "suspend": {
       "type": "boolean",

api/swagger-spec/batch_v2alpha1.json

@@ -1504,7 +1504,7 @@
      },
      "concurrencyPolicy": {
       "type": "string",
-      "description": "Specifies how to treat concurrent executions of a Job. Defaults to Allow."
+      "description": "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"
      },
      "suspend": {
       "type": "boolean",

docs/api-reference/batch/v1beta1/definitions.html

@@ -3407,7 +3407,7 @@ When an object is created, the system will populate this list with the current s
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">concurrencyPolicy</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies how to treat concurrent executions of a Job. Defaults to Allow.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">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&#8217;t finished yet; - "Replace": cancels currently running job and replaces it with a new one</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
 <td class="tableblock halign-left valign-top"></td>

docs/api-reference/batch/v2alpha1/definitions.html

@@ -2173,7 +2173,7 @@ When an object is created, the system will populate this list with the current s
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">concurrencyPolicy</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies how to treat concurrent executions of a Job. Defaults to Allow.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">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&#8217;t finished yet; - "Replace": cancels currently running job and replaces it with a new one</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
 <td class="tableblock halign-left valign-top"></td>

pkg/apis/batch/types.go

@@ -250,7 +250,10 @@ type CronJobSpec struct {
 	StartingDeadlineSeconds *int64
 
 	// Specifies how to treat concurrent executions of a Job.
-	// Defaults to Allow.
+	// 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
 

staging/src/k8s.io/api/batch/v1beta1/generated.proto

@@ -71,7 +71,10 @@ message CronJobSpec {
   optional int64 startingDeadlineSeconds = 2;
 
   // Specifies how to treat concurrent executions of a Job.
-  // Defaults to Allow.
+  // 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
   optional string concurrencyPolicy = 3;
 

staging/src/k8s.io/api/batch/v1beta1/types.go

@@ -100,7 +100,10 @@ type CronJobSpec struct {
 	StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty" protobuf:"varint,2,opt,name=startingDeadlineSeconds"`
 
 	// Specifies how to treat concurrent executions of a Job.
-	// Defaults to Allow.
+	// 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" protobuf:"bytes,3,opt,name=concurrencyPolicy,casttype=ConcurrencyPolicy"`
 

staging/src/k8s.io/api/batch/v1beta1/types_swagger_doc_generated.go

@@ -52,7 +52,7 @@ var map_CronJobSpec = map[string]string{
 	"":                           "CronJobSpec describes how the job execution will look like and when it will actually run.",
 	"schedule":                   "The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.",
 	"startingDeadlineSeconds":    "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.",
-	"concurrencyPolicy":          "Specifies how to treat concurrent executions of a Job. Defaults to Allow.",
+	"concurrencyPolicy":          "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",
 	"suspend":                    "This flag tells the controller to suspend subsequent executions, it does not apply to already started executions.  Defaults to false.",
 	"jobTemplate":                "Specifies the job that will be created when executing a CronJob.",
 	"successfulJobsHistoryLimit": "The number of successful finished jobs to retain. This is a pointer to distinguish between explicit zero and not specified. Defaults to 3.",

staging/src/k8s.io/api/batch/v2alpha1/generated.proto

@@ -71,7 +71,10 @@ message CronJobSpec {
   optional int64 startingDeadlineSeconds = 2;
 
   // Specifies how to treat concurrent executions of a Job.
-  // Defaults to Allow.
+  // 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
   optional string concurrencyPolicy = 3;
 

staging/src/k8s.io/api/batch/v2alpha1/types.go

@@ -100,7 +100,10 @@ type CronJobSpec struct {
 	StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty" protobuf:"varint,2,opt,name=startingDeadlineSeconds"`
 
 	// Specifies how to treat concurrent executions of a Job.
-	// Defaults to Allow.
+	// 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" protobuf:"bytes,3,opt,name=concurrencyPolicy,casttype=ConcurrencyPolicy"`
 

staging/src/k8s.io/api/batch/v2alpha1/types_swagger_doc_generated.go

@@ -52,7 +52,7 @@ var map_CronJobSpec = map[string]string{
 	"":                           "CronJobSpec describes how the job execution will look like and when it will actually run.",
 	"schedule":                   "The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.",
 	"startingDeadlineSeconds":    "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.",
-	"concurrencyPolicy":          "Specifies how to treat concurrent executions of a Job. Defaults to Allow.",
+	"concurrencyPolicy":          "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",
 	"suspend":                    "This flag tells the controller to suspend subsequent executions, it does not apply to already started executions.  Defaults to false.",
 	"jobTemplate":                "Specifies the job that will be created when executing a CronJob.",
 	"successfulJobsHistoryLimit": "The number of successful finished jobs to retain. This is a pointer to distinguish between explicit zero and not specified.",