From 57ed0174b1f11cba1be332251dc2b9b68c20f959 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Sat, 6 Nov 2021 07:52:22 +0000 Subject: [PATCH 1/2] updated probe handler types descriptions --- pkg/apis/core/types.go | 25 ++++++++++--------------- staging/src/k8s.io/api/core/v1/types.go | 25 ++++++++----------------- 2 files changed, 18 insertions(+), 32 deletions(-) diff --git a/pkg/apis/core/types.go b/pkg/apis/core/types.go index 0a71e884868..8a8612a552f 100644 --- a/pkg/apis/core/types.go +++ b/pkg/apis/core/types.go @@ -2189,11 +2189,8 @@ type Container struct { } // ProbeHandler defines a specific action that should be taken in a probe. -// This type has a strong relationship to LifecycleHandler - overlapping fields -// should be identical. -// TODO: pass structured data to these actions, and document that data here. +// One and only one of the fields must be specified. type ProbeHandler struct { - // One and only one of the following should be specified. // Exec specifies the action to take. // +optional Exec *ExecAction @@ -2201,25 +2198,22 @@ type ProbeHandler struct { // +optional HTTPGet *HTTPGetAction // TCPSocket specifies an action involving a TCP port. - // TODO: implement a realistic TCP lifecycle hook // +optional TCPSocket *TCPSocketAction } // LifecycleHandler defines a specific action that should be taken in a lifecycle -// hook. This type has a strong relationship to ProbeHandler - overlapping fields -// should be identical. -// TODO: pass structured data to these actions, and document that data here. +// hook. One and only one of the fields, except TCPSocket must be specified. type LifecycleHandler struct { - // One and only one of the following should be specified. // Exec specifies the action to take. // +optional Exec *ExecAction // HTTPGet specifies the http request to perform. // +optional HTTPGet *HTTPGetAction - // TCPSocket specifies an action involving a TCP port. - // TODO: implement a realistic TCP lifecycle hook + // Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept + // for the backward compatibility. There are no validation of this field and + // lifecycle hooks will fail in runtime when tcp handler is specified. // +optional TCPSocket *TCPSocketAction } @@ -2230,17 +2224,18 @@ type LifecycleHandler struct { type Lifecycle struct { // PostStart is called immediately after a container is created. If the handler fails, the container // is terminated and restarted. + // More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks // +optional PostStart *LifecycleHandler // PreStop is called immediately before a container is terminated due to an // API request or management event such as liveness/startup probe failure, // preemption, resource contention, etc. The handler is not called if the - // container crashes or exits. The reason for termination is passed to the - // handler. The Pod's termination grace period countdown begins before the - // PreStop hooked is executed. Regardless of the outcome of the handler, the + // container crashes or exits. The Pod's termination grace period countdown begins before the + // PreStop hook is executed. Regardless of the outcome of the handler, the // container will eventually terminate within the Pod's termination grace - // period. Other management of the container blocks until the hook completes + // period (unless delayed by finalizers). Other management of the container blocks until the hook completes // or until the termination grace period is reached. + // More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks // +optional PreStop *LifecycleHandler } diff --git a/staging/src/k8s.io/api/core/v1/types.go b/staging/src/k8s.io/api/core/v1/types.go index b5f892a3691..9abc10f853a 100644 --- a/staging/src/k8s.io/api/core/v1/types.go +++ b/staging/src/k8s.io/api/core/v1/types.go @@ -2382,11 +2382,8 @@ type Container struct { } // ProbeHandler defines a specific action that should be taken in a probe. -// This type has a strong relationship to LifecycleHandler - overlapping fields -// should be identical. -// TODO: pass structured data to these actions, and document that data here. +// One and only one of the fields must be specified. type ProbeHandler struct { - // One and only one of the following should be specified. // Exec specifies the action to take. // +optional Exec *ExecAction `json:"exec,omitempty" protobuf:"bytes,1,opt,name=exec"` @@ -2394,27 +2391,22 @@ type ProbeHandler struct { // +optional HTTPGet *HTTPGetAction `json:"httpGet,omitempty" protobuf:"bytes,2,opt,name=httpGet"` // TCPSocket specifies an action involving a TCP port. - // TCP hooks not yet supported - // TODO: implement a realistic TCP lifecycle hook // +optional TCPSocket *TCPSocketAction `json:"tcpSocket,omitempty" protobuf:"bytes,3,opt,name=tcpSocket"` } // LifecycleHandler defines a specific action that should be taken in a lifecycle -// hook. This type has a strong relationship to ProbeHandler - overlapping fields -// should be identical. -// TODO: pass structured data to these actions, and document that data here. +// hook. One and only one of the fields, except TCPSocket must be specified. type LifecycleHandler struct { - // One and only one of the following should be specified. // Exec specifies the action to take. // +optional Exec *ExecAction `json:"exec,omitempty" protobuf:"bytes,1,opt,name=exec"` // HTTPGet specifies the http request to perform. // +optional HTTPGet *HTTPGetAction `json:"httpGet,omitempty" protobuf:"bytes,2,opt,name=httpGet"` - // TCPSocket specifies an action involving a TCP port. - // TCP hooks not yet supported - // TODO: implement a realistic TCP lifecycle hook + // Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept + // for the backward compatibility. There are no validation of this field and + // lifecycle hooks will fail in runtime when tcp handler is specified. // +optional TCPSocket *TCPSocketAction `json:"tcpSocket,omitempty" protobuf:"bytes,3,opt,name=tcpSocket"` } @@ -2432,11 +2424,10 @@ type Lifecycle struct { // PreStop is called immediately before a container is terminated due to an // API request or management event such as liveness/startup probe failure, // preemption, resource contention, etc. The handler is not called if the - // container crashes or exits. The reason for termination is passed to the - // handler. The Pod's termination grace period countdown begins before the - // PreStop hooked is executed. Regardless of the outcome of the handler, the + // container crashes or exits. The Pod's termination grace period countdown begins before the + // PreStop hook is executed. Regardless of the outcome of the handler, the // container will eventually terminate within the Pod's termination grace - // period. Other management of the container blocks until the hook completes + // period (unless delayed by finalizers). Other management of the container blocks until the hook completes // or until the termination grace period is reached. // More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks // +optional From f0ed1a3b8579af421abb856d7bc12827574050a0 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Mon, 15 Nov 2021 20:47:15 +0000 Subject: [PATCH 2/2] ./hack/update-openapi-spec.sh after the updated probe handler types descriptions --- api/openapi-spec/swagger.json | 12 ++++----- .../src/k8s.io/api/core/v1/generated.proto | 25 ++++++------------- .../core/v1/types_swagger_doc_generated.go | 14 +++++------ 3 files changed, 21 insertions(+), 30 deletions(-) diff --git a/api/openapi-spec/swagger.json b/api/openapi-spec/swagger.json index b42a1e9db35..200b8af3145 100644 --- a/api/openapi-spec/swagger.json +++ b/api/openapi-spec/swagger.json @@ -6187,17 +6187,17 @@ }, "preStop": { "$ref": "#/definitions/io.k8s.api.core.v1.LifecycleHandler", - "description": "PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks" + "description": "PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The Pod's termination grace period countdown begins before the PreStop hook is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period (unless delayed by finalizers). Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks" } }, "type": "object" }, "io.k8s.api.core.v1.LifecycleHandler": { - "description": "LifecycleHandler defines a specific action that should be taken in a lifecycle hook. This type has a strong relationship to ProbeHandler - overlapping fields should be identical.", + "description": "LifecycleHandler defines a specific action that should be taken in a lifecycle hook. One and only one of the fields, except TCPSocket must be specified.", "properties": { "exec": { "$ref": "#/definitions/io.k8s.api.core.v1.ExecAction", - "description": "One and only one of the following should be specified. Exec specifies the action to take." + "description": "Exec specifies the action to take." }, "httpGet": { "$ref": "#/definitions/io.k8s.api.core.v1.HTTPGetAction", @@ -6205,7 +6205,7 @@ }, "tcpSocket": { "$ref": "#/definitions/io.k8s.api.core.v1.TCPSocketAction", - "description": "TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported" + "description": "Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept for the backward compatibility. There are no validation of this field and lifecycle hooks will fail in runtime when tcp handler is specified." } }, "type": "object" @@ -8198,7 +8198,7 @@ "properties": { "exec": { "$ref": "#/definitions/io.k8s.api.core.v1.ExecAction", - "description": "One and only one of the following should be specified. Exec specifies the action to take." + "description": "Exec specifies the action to take." }, "failureThreshold": { "description": "Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1.", @@ -8226,7 +8226,7 @@ }, "tcpSocket": { "$ref": "#/definitions/io.k8s.api.core.v1.TCPSocketAction", - "description": "TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported" + "description": "TCPSocket specifies an action involving a TCP port." }, "terminationGracePeriodSeconds": { "description": "Optional duration in seconds the pod needs to terminate gracefully upon probe failure. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. If this value is nil, the pod's terminationGracePeriodSeconds will be used. Otherwise, this value overrides the value provided by the pod spec. Value must be non-negative integer. The value zero indicates stop immediately via the kill signal (no opportunity to shut down). This is a beta field and requires enabling ProbeTerminationGracePeriod feature gate. Minimum value is 1. spec.terminationGracePeriodSeconds is used if unset.", diff --git a/staging/src/k8s.io/api/core/v1/generated.proto b/staging/src/k8s.io/api/core/v1/generated.proto index 9206bb3dac3..9245f52d1a3 100644 --- a/staging/src/k8s.io/api/core/v1/generated.proto +++ b/staging/src/k8s.io/api/core/v1/generated.proto @@ -1918,11 +1918,10 @@ message Lifecycle { // PreStop is called immediately before a container is terminated due to an // API request or management event such as liveness/startup probe failure, // preemption, resource contention, etc. The handler is not called if the - // container crashes or exits. The reason for termination is passed to the - // handler. The Pod's termination grace period countdown begins before the - // PreStop hooked is executed. Regardless of the outcome of the handler, the + // container crashes or exits. The Pod's termination grace period countdown begins before the + // PreStop hook is executed. Regardless of the outcome of the handler, the // container will eventually terminate within the Pod's termination grace - // period. Other management of the container blocks until the hook completes + // period (unless delayed by finalizers). Other management of the container blocks until the hook completes // or until the termination grace period is reached. // More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks // +optional @@ -1930,11 +1929,8 @@ message Lifecycle { } // LifecycleHandler defines a specific action that should be taken in a lifecycle -// hook. This type has a strong relationship to ProbeHandler - overlapping fields -// should be identical. -// TODO: pass structured data to these actions, and document that data here. +// hook. One and only one of the fields, except TCPSocket must be specified. message LifecycleHandler { - // One and only one of the following should be specified. // Exec specifies the action to take. // +optional optional ExecAction exec = 1; @@ -1943,9 +1939,9 @@ message LifecycleHandler { // +optional optional HTTPGetAction httpGet = 2; - // TCPSocket specifies an action involving a TCP port. - // TCP hooks not yet supported - // TODO: implement a realistic TCP lifecycle hook + // Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept + // for the backward compatibility. There are no validation of this field and + // lifecycle hooks will fail in runtime when tcp handler is specified. // +optional optional TCPSocketAction tcpSocket = 3; } @@ -3973,11 +3969,8 @@ message Probe { } // ProbeHandler defines a specific action that should be taken in a probe. -// This type has a strong relationship to LifecycleHandler - overlapping fields -// should be identical. -// TODO: pass structured data to these actions, and document that data here. +// One and only one of the fields must be specified. message ProbeHandler { - // One and only one of the following should be specified. // Exec specifies the action to take. // +optional optional ExecAction exec = 1; @@ -3987,8 +3980,6 @@ message ProbeHandler { optional HTTPGetAction httpGet = 2; // TCPSocket specifies an action involving a TCP port. - // TCP hooks not yet supported - // TODO: implement a realistic TCP lifecycle hook // +optional optional TCPSocketAction tcpSocket = 3; } diff --git a/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go b/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go index 2f52c1a385d..45379d99b7e 100644 --- a/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go +++ b/staging/src/k8s.io/api/core/v1/types_swagger_doc_generated.go @@ -878,7 +878,7 @@ func (KeyToPath) SwaggerDoc() map[string]string { var map_Lifecycle = map[string]string{ "": "Lifecycle describes actions that the management system should take in response to container lifecycle events. For the PostStart and PreStop lifecycle handlers, management of the container blocks until the action is complete, unless the container process fails, in which case the handler is aborted.", "postStart": "PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks", - "preStop": "PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks", + "preStop": "PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The Pod's termination grace period countdown begins before the PreStop hook is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period (unless delayed by finalizers). Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks", } func (Lifecycle) SwaggerDoc() map[string]string { @@ -886,10 +886,10 @@ func (Lifecycle) SwaggerDoc() map[string]string { } var map_LifecycleHandler = map[string]string{ - "": "LifecycleHandler defines a specific action that should be taken in a lifecycle hook. This type has a strong relationship to ProbeHandler - overlapping fields should be identical.", - "exec": "One and only one of the following should be specified. Exec specifies the action to take.", + "": "LifecycleHandler defines a specific action that should be taken in a lifecycle hook. One and only one of the fields, except TCPSocket must be specified.", + "exec": "Exec specifies the action to take.", "httpGet": "HTTPGet specifies the http request to perform.", - "tcpSocket": "TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported", + "tcpSocket": "Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept for the backward compatibility. There are no validation of this field and lifecycle hooks will fail in runtime when tcp handler is specified.", } func (LifecycleHandler) SwaggerDoc() map[string]string { @@ -1793,10 +1793,10 @@ func (Probe) SwaggerDoc() map[string]string { } var map_ProbeHandler = map[string]string{ - "": "ProbeHandler defines a specific action that should be taken in a probe. This type has a strong relationship to LifecycleHandler - overlapping fields should be identical.", - "exec": "One and only one of the following should be specified. Exec specifies the action to take.", + "": "ProbeHandler defines a specific action that should be taken in a probe. One and only one of the fields must be specified.", + "exec": "Exec specifies the action to take.", "httpGet": "HTTPGet specifies the http request to perform.", - "tcpSocket": "TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported", + "tcpSocket": "TCPSocket specifies an action involving a TCP port.", } func (ProbeHandler) SwaggerDoc() map[string]string {