From 4063a68720c34c8d9b2692d3ec875306c68cb012 Mon Sep 17 00:00:00 2001 From: Bo Wang Date: Fri, 31 May 2024 17:05:18 +0800 Subject: [PATCH] Add missing comments in k8s.io/api/core/v1 Signed-off-by: Bo Wang Kubernetes-commit: 495af2a3d470dcfb9e9b330e08a16d6329dbb901 --- core/v1/generated.proto | 32 +++++++++++++++------- core/v1/types.go | 37 +++++++++++++++++--------- core/v1/types_swagger_doc_generated.go | 36 ++++++++++++++++--------- 3 files changed, 70 insertions(+), 35 deletions(-) diff --git a/core/v1/generated.proto b/core/v1/generated.proto index 83a7c570c..6d753fa4b 100644 --- a/core/v1/generated.proto +++ b/core/v1/generated.proto @@ -1869,6 +1869,7 @@ message GCEPersistentDiskVolumeSource { optional bool readOnly = 4; } +// GRPCAction specifies an action involving a GRPC service. message GRPCAction { // Port number of the gRPC service. Number must be in the range 1 to 65535. optional int32 port = 1; @@ -2202,21 +2203,21 @@ message Lifecycle { // 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. message LifecycleHandler { - // Exec specifies the action to take. + // Exec specifies a command to execute in the container. // +optional optional ExecAction exec = 1; - // HTTPGet specifies the http request to perform. + // HTTPGet specifies an HTTP GET request to perform. // +optional optional HTTPGetAction httpGet = 2; // 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. + // for backward compatibility. There is no validation of this field and + // lifecycle hooks will fail at runtime when it is specified. // +optional optional TCPSocketAction tcpSocket = 3; - // Sleep represents the duration that the container should sleep before being terminated. + // Sleep represents a duration that the container should sleep. // +featureGate=PodLifecycleSleepAction // +optional optional SleepAction sleep = 4; @@ -2447,12 +2448,15 @@ message NamespaceCondition { // Status of the condition, one of True, False, Unknown. optional string status = 2; + // Last time the condition transitioned from one status to another. // +optional optional .k8s.io.apimachinery.pkg.apis.meta.v1.Time lastTransitionTime = 4; + // Unique, one-word, CamelCase reason for the condition's last transition. // +optional optional string reason = 5; + // Human-readable message indicating details about last transition. // +optional optional string message = 6; } @@ -3010,8 +3014,13 @@ message PersistentVolumeClaim { // PersistentVolumeClaimCondition contains details about state of pvc message PersistentVolumeClaimCondition { + // Type is the type of the condition. + // More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=set%20to%20%27ResizeStarted%27.-,PersistentVolumeClaimCondition,-contains%20details%20about optional string type = 1; + // Status is the status of the condition. + // Can be True, False, Unknown. + // More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=state%20of%20pvc-,conditions.status,-(string)%2C%20required optional string status = 2; // lastProbeTime is the time we probed the condition. @@ -3743,9 +3752,11 @@ message PodDNSConfig { // PodDNSConfigOption defines DNS resolver options of a pod. message PodDNSConfigOption { + // Name is this DNS resolver option's name. // Required. optional string name = 1; + // Value is this DNS resolver option's value. // +optional optional string value = 2; } @@ -4659,6 +4670,7 @@ message PodTemplateSpec { optional PodSpec spec = 2; } +// PortStatus represents the error condition of a service port message PortStatus { // Port is the port number of the service port of which status is recorded here optional int32 port = 1; @@ -4783,19 +4795,19 @@ message Probe { // ProbeHandler defines a specific action that should be taken in a probe. // One and only one of the fields must be specified. message ProbeHandler { - // Exec specifies the action to take. + // Exec specifies a command to execute in the container. // +optional optional ExecAction exec = 1; - // HTTPGet specifies the http request to perform. + // HTTPGet specifies an HTTP GET request to perform. // +optional optional HTTPGetAction httpGet = 2; - // TCPSocket specifies an action involving a TCP port. + // TCPSocket specifies a connection to a TCP port. // +optional optional TCPSocketAction tcpSocket = 3; - // GRPC specifies an action involving a GRPC port. + // GRPC specifies a GRPC HealthCheckRequest. // +optional optional GRPCAction grpc = 4; } @@ -5233,6 +5245,7 @@ message ResourceRequirements { repeated ResourceClaim claims = 3; } +// ResourceStatus represents the status of a single resource allocated to a Pod. message ResourceStatus { // Name of the resource. Must be unique within the pod and in case of non-DRA resource, match one of the resources from the pod spec. // For DRA resources, the value must be "claim:/". @@ -6444,6 +6457,7 @@ message TypedLocalObjectReference { optional string name = 3; } +// TypedObjectReference contains enough information to let you locate the typed referenced object message TypedObjectReference { // APIGroup is the group for the resource being referenced. // If APIGroup is not specified, the specified Kind must be in the core API group. diff --git a/core/v1/types.go b/core/v1/types.go index 76bb347e4..d645e0cec 100644 --- a/core/v1/types.go +++ b/core/v1/types.go @@ -630,6 +630,7 @@ type PersistentVolumeClaimSpec struct { VolumeAttributesClassName *string `json:"volumeAttributesClassName,omitempty" protobuf:"bytes,9,opt,name=volumeAttributesClassName"` } +// TypedObjectReference contains enough information to let you locate the typed referenced object type TypedObjectReference struct { // APIGroup is the group for the resource being referenced. // If APIGroup is not specified, the specified Kind must be in the core API group. @@ -736,8 +737,13 @@ type ModifyVolumeStatus struct { // PersistentVolumeClaimCondition contains details about state of pvc type PersistentVolumeClaimCondition struct { - Type PersistentVolumeClaimConditionType `json:"type" protobuf:"bytes,1,opt,name=type,casttype=PersistentVolumeClaimConditionType"` - Status ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status,casttype=ConditionStatus"` + // Type is the type of the condition. + // More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=set%20to%20%27ResizeStarted%27.-,PersistentVolumeClaimCondition,-contains%20details%20about + Type PersistentVolumeClaimConditionType `json:"type" protobuf:"bytes,1,opt,name=type,casttype=PersistentVolumeClaimConditionType"` + // Status is the status of the condition. + // Can be True, False, Unknown. + // More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=state%20of%20pvc-,conditions.status,-(string)%2C%20required + Status ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status,casttype=ConditionStatus"` // lastProbeTime is the time we probed the condition. // +optional LastProbeTime metav1.Time `json:"lastProbeTime,omitempty" protobuf:"bytes,3,opt,name=lastProbeTime"` @@ -2524,6 +2530,7 @@ type TCPSocketAction struct { Host string `json:"host,omitempty" protobuf:"bytes,2,opt,name=host"` } +// GRPCAction specifies an action involving a GRPC service. type GRPCAction struct { // Port number of the gRPC service. Number must be in the range 1 to 65535. Port int32 `json:"port" protobuf:"bytes,1,opt,name=port"` @@ -2939,17 +2946,16 @@ type Container struct { // ProbeHandler defines a specific action that should be taken in a probe. // One and only one of the fields must be specified. type ProbeHandler struct { - // Exec specifies the action to take. + // Exec specifies a command to execute in the container. // +optional Exec *ExecAction `json:"exec,omitempty" protobuf:"bytes,1,opt,name=exec"` - // HTTPGet specifies the http request to perform. + // HTTPGet specifies an HTTP GET request to perform. // +optional HTTPGet *HTTPGetAction `json:"httpGet,omitempty" protobuf:"bytes,2,opt,name=httpGet"` - // TCPSocket specifies an action involving a TCP port. + // TCPSocket specifies a connection to a TCP port. // +optional TCPSocket *TCPSocketAction `json:"tcpSocket,omitempty" protobuf:"bytes,3,opt,name=tcpSocket"` - - // GRPC specifies an action involving a GRPC port. + // GRPC specifies a GRPC HealthCheckRequest. // +optional GRPC *GRPCAction `json:"grpc,omitempty" protobuf:"bytes,4,opt,name=grpc"` } @@ -2957,18 +2963,18 @@ type ProbeHandler struct { // 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. type LifecycleHandler struct { - // Exec specifies the action to take. + // Exec specifies a command to execute in the container. // +optional Exec *ExecAction `json:"exec,omitempty" protobuf:"bytes,1,opt,name=exec"` - // HTTPGet specifies the http request to perform. + // HTTPGet specifies an HTTP GET request to perform. // +optional HTTPGet *HTTPGetAction `json:"httpGet,omitempty" protobuf:"bytes,2,opt,name=httpGet"` // 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. + // for backward compatibility. There is no validation of this field and + // lifecycle hooks will fail at runtime when it is specified. // +optional TCPSocket *TCPSocketAction `json:"tcpSocket,omitempty" protobuf:"bytes,3,opt,name=tcpSocket"` - // Sleep represents the duration that the container should sleep before being terminated. + // Sleep represents a duration that the container should sleep. // +featureGate=PodLifecycleSleepAction // +optional Sleep *SleepAction `json:"sleep,omitempty" protobuf:"bytes,4,opt,name=sleep"` @@ -3150,6 +3156,7 @@ type ContainerStatus struct { AllocatedResourcesStatus []ResourceStatus `json:"allocatedResourcesStatus,omitempty" patchStrategy:"merge" patchMergeKey:"name" protobuf:"bytes,14,rep,name=allocatedResourcesStatus"` } +// ResourceStatus represents the status of a single resource allocated to a Pod. type ResourceStatus struct { // Name of the resource. Must be unique within the pod and in case of non-DRA resource, match one of the resources from the pod spec. // For DRA resources, the value must be "claim:/". @@ -4605,8 +4612,10 @@ type PodDNSConfig struct { // PodDNSConfigOption defines DNS resolver options of a pod. type PodDNSConfigOption struct { + // Name is this DNS resolver option's name. // Required. Name string `json:"name,omitempty" protobuf:"bytes,1,opt,name=name"` + // Value is this DNS resolver option's value. // +optional Value *string `json:"value,omitempty" protobuf:"bytes,2,opt,name=value"` } @@ -6570,10 +6579,13 @@ type NamespaceCondition struct { Type NamespaceConditionType `json:"type" protobuf:"bytes,1,opt,name=type,casttype=NamespaceConditionType"` // Status of the condition, one of True, False, Unknown. Status ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status,casttype=ConditionStatus"` + // Last time the condition transitioned from one status to another. // +optional LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty" protobuf:"bytes,4,opt,name=lastTransitionTime"` + // Unique, one-word, CamelCase reason for the condition's last transition. // +optional Reason string `json:"reason,omitempty" protobuf:"bytes,5,opt,name=reason"` + // Human-readable message indicating details about last transition. // +optional Message string `json:"message,omitempty" protobuf:"bytes,6,opt,name=message"` } @@ -7886,7 +7898,6 @@ const ( ) // PortStatus represents the error condition of a service port - type PortStatus struct { // Port is the port number of the service port of which status is recorded here Port int32 `json:"port" protobuf:"varint,1,opt,name=port"` diff --git a/core/v1/types_swagger_doc_generated.go b/core/v1/types_swagger_doc_generated.go index 34adb2796..472945d90 100644 --- a/core/v1/types_swagger_doc_generated.go +++ b/core/v1/types_swagger_doc_generated.go @@ -802,6 +802,7 @@ func (GCEPersistentDiskVolumeSource) SwaggerDoc() map[string]string { } var map_GRPCAction = map[string]string{ + "": "GRPCAction specifies an action involving a GRPC service.", "port": "Port number of the gRPC service. Number must be in the range 1 to 65535.", "service": "Service is the name of the service to place in the gRPC HealthCheckRequest (see https://github.com/grpc/grpc/blob/master/doc/health-checking.md).\n\nIf this is not specified, the default behavior is defined by gRPC.", } @@ -967,10 +968,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. 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": "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.", - "sleep": "Sleep represents the duration that the container should sleep before being terminated.", + "exec": "Exec specifies a command to execute in the container.", + "httpGet": "HTTPGet specifies an HTTP GET request to perform.", + "tcpSocket": "Deprecated. TCPSocket is NOT supported as a LifecycleHandler and kept for backward compatibility. There is no validation of this field and lifecycle hooks will fail at runtime when it is specified.", + "sleep": "Sleep represents a duration that the container should sleep.", } func (LifecycleHandler) SwaggerDoc() map[string]string { @@ -1104,9 +1105,12 @@ func (Namespace) SwaggerDoc() map[string]string { } var map_NamespaceCondition = map[string]string{ - "": "NamespaceCondition contains details about state of namespace.", - "type": "Type of namespace controller condition.", - "status": "Status of the condition, one of True, False, Unknown.", + "": "NamespaceCondition contains details about state of namespace.", + "type": "Type of namespace controller condition.", + "status": "Status of the condition, one of True, False, Unknown.", + "lastTransitionTime": "Last time the condition transitioned from one status to another.", + "reason": "Unique, one-word, CamelCase reason for the condition's last transition.", + "message": "Human-readable message indicating details about last transition.", } func (NamespaceCondition) SwaggerDoc() map[string]string { @@ -1398,6 +1402,8 @@ func (PersistentVolumeClaim) SwaggerDoc() map[string]string { var map_PersistentVolumeClaimCondition = map[string]string{ "": "PersistentVolumeClaimCondition contains details about state of pvc", + "type": "Type is the type of the condition. More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=set%20to%20%27ResizeStarted%27.-,PersistentVolumeClaimCondition,-contains%20details%20about", + "status": "Status is the status of the condition. Can be True, False, Unknown. More info: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#:~:text=state%20of%20pvc-,conditions.status,-(string)%2C%20required", "lastProbeTime": "lastProbeTime is the time we probed the condition.", "lastTransitionTime": "lastTransitionTime is the time the condition transitioned from one status to another.", "reason": "reason is a unique, this should be a short, machine understandable string that gives the reason for condition's last transition. If it reports \"Resizing\" that means the underlying persistent volume is being resized.", @@ -1634,8 +1640,9 @@ func (PodDNSConfig) SwaggerDoc() map[string]string { } var map_PodDNSConfigOption = map[string]string{ - "": "PodDNSConfigOption defines DNS resolver options of a pod.", - "name": "Required.", + "": "PodDNSConfigOption defines DNS resolver options of a pod.", + "name": "Name is this DNS resolver option's name. Required.", + "value": "Value is this DNS resolver option's value.", } func (PodDNSConfigOption) SwaggerDoc() map[string]string { @@ -1901,6 +1908,7 @@ func (PodTemplateSpec) SwaggerDoc() map[string]string { } var map_PortStatus = map[string]string{ + "": "PortStatus represents the error condition of a service port", "port": "Port is the port number of the service port of which status is recorded here", "protocol": "Protocol is the protocol of the service port of which status is recorded here The supported values are: \"TCP\", \"UDP\", \"SCTP\"", "error": "Error is to record the problem with the service port The format of the error shall comply with the following rules: - built-in error values shall be specified in this file and those shall use\n CamelCase names\n- cloud provider specific error values must have names that comply with the\n format foo.example.com/CamelCase.", @@ -1968,10 +1976,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. 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.", - "grpc": "GRPC specifies an action involving a GRPC port.", + "exec": "Exec specifies a command to execute in the container.", + "httpGet": "HTTPGet specifies an HTTP GET request to perform.", + "tcpSocket": "TCPSocket specifies a connection to a TCP port.", + "grpc": "GRPC specifies a GRPC HealthCheckRequest.", } func (ProbeHandler) SwaggerDoc() map[string]string { @@ -2190,6 +2198,7 @@ func (ResourceRequirements) SwaggerDoc() map[string]string { } var map_ResourceStatus = map[string]string{ + "": "ResourceStatus represents the status of a single resource allocated to a Pod.", "name": "Name of the resource. Must be unique within the pod and in case of non-DRA resource, match one of the resources from the pod spec. For DRA resources, the value must be \"claim:/\". When this status is reported about a container, the \"claim_name\" and \"request\" must match one of the claims of this container.", "resources": "List of unique resources health. Each element in the list contains an unique resource ID and its health. At a minimum, for the lifetime of a Pod, resource ID must uniquely identify the resource allocated to the Pod on the Node. If other Pod on the same Node reports the status with the same resource ID, it must be the same resource they share. See ResourceID type definition for a specific format it has in various use cases.", } @@ -2630,6 +2639,7 @@ func (TypedLocalObjectReference) SwaggerDoc() map[string]string { } var map_TypedObjectReference = map[string]string{ + "": "TypedObjectReference contains enough information to let you locate the typed referenced object", "apiGroup": "APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required.", "kind": "Kind is the type of resource being referenced", "name": "Name is the name of resource being referenced",