Merge pull request #62563 from devdattakulkarni/client-go-details

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>.

Updated README to include client-go<->controller diagram

The sample-controller makes extensive use of various mechanisms
available in client-go. For writing custom controllers/operators
it will be helpful if there is precise description of how the
client-go library works and how/where it interfaces with
custom controller code.

Recently we published a blog post with these details here:

https://medium.com/@cloudark/kubernetes-custom-controllers-b6c7d0668fdf

This patch includes the diagram from the post, as was recommended
by @sttts on https://github.com/kubernetes/sample-controller/issues/13

**What this PR does / why we need it**:

**Which issue(s) this PR fixes** *(optional, in `fixes #<issue number>(, fixes #<issue_number>, ...)` format, will close the issue(s) when PR gets merged)*:
Fixes #

**Special notes for your reviewer**:

**Release note**:

```release-note

```

Kubernetes-commit: 773def0194ecc1cd845ea9a01da761d5a0390e6e

vendor/k8s.io/api/core/v1/generated.proto

@@ -439,6 +439,34 @@ message ConfigMapList {
   repeated ConfigMap items = 2;
 }
 
+// ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node.
+message ConfigMapNodeConfigSource {
+  // Namespace is the metadata.namespace of the referenced ConfigMap.
+  // This field is required in all cases.
+  optional string namespace = 1;
+
+  // Name is the metadata.name of the referenced ConfigMap.
+  // This field is required in all cases.
+  optional string name = 2;
+
+  // UID is the metadata.UID of the referenced ConfigMap.
+  // This field is currently reqired in Node.Spec.
+  // TODO(#61643): This field will be forbidden in Node.Spec when #61643 is resolved.
+  // TODO(#56896): This field will be required in Node.Status when #56896 is resolved.
+  // +optional
+  optional string uid = 3;
+
+  // ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap.
+  // This field is forbidden in Node.Spec.
+  // TODO(#56896): This field will be required in Node.Status when #56896 is resolved.
+  // +optional
+  optional string resourceVersion = 4;
+
+  // KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure
+  // This field is required in all cases.
+  optional string kubeletConfigKey = 5;
+}
+
 // Adapts a ConfigMap into a projected volume.
 // 
 // The contents of the target ConfigMap's Data field will be presented in a
@@ -1815,7 +1843,8 @@ message NodeCondition {
 
 // NodeConfigSource specifies a source of node configuration. Exactly one subfield (excluding metadata) must be non-nil.
 message NodeConfigSource {
-  optional ObjectReference configMapRef = 1;
+  // ConfigMap is a reference to a Node's ConfigMap
+  optional ConfigMapNodeConfigSource configMap = 2;
 }
 
 // NodeDaemonEndpoints lists ports opened by daemons running on the Node.

vendor/k8s.io/api/core/v1/register.go

@@ -57,7 +57,6 @@ func addKnownTypes(scheme *runtime.Scheme) error {
 		&Endpoints{},
 		&EndpointsList{},
 		&Node{},
-		&NodeConfigSource{},
 		&NodeList{},
 		&NodeProxyOptions{},
 		&Binding{},

vendor/k8s.io/api/core/v1/types.go

@@ -3640,12 +3640,49 @@ type NodeSpec struct {
 	DoNotUse_ExternalID string `json:"externalID,omitempty" protobuf:"bytes,2,opt,name=externalID"`
 }
 
-// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
-
 // NodeConfigSource specifies a source of node configuration. Exactly one subfield (excluding metadata) must be non-nil.
 type NodeConfigSource struct {
-	metav1.TypeMeta `json:",inline"`
-	ConfigMapRef    *ObjectReference `json:"configMapRef,omitempty" protobuf:"bytes,1,opt,name=configMapRef"`
+	// For historical context, regarding the below kind, apiVersion, and configMapRef deprecation tags:
+	// 1. kind/apiVersion were used by the kubelet to persist this struct to disk (they had no protobuf tags)
+	// 2. configMapRef and proto tag 1 were used by the API to refer to a configmap,
+	//    but used a generic ObjectReference type that didn't really have the fields we needed
+	// All uses/persistence of the NodeConfigSource struct prior to 1.11 were gated by alpha feature flags,
+	// so there was no persisted data for these fields that needed to be migrated/handled.
+
+	// +k8s:deprecated=kind
+	// +k8s:deprecated=apiVersion
+	// +k8s:deprecated=configMapRef,protobuf=1
+
+	// ConfigMap is a reference to a Node's ConfigMap
+	ConfigMap *ConfigMapNodeConfigSource `json:"configMap,omitempty" protobuf:"bytes,2,opt,name=configMap"`
+}
+
+// ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node.
+type ConfigMapNodeConfigSource struct {
+	// Namespace is the metadata.namespace of the referenced ConfigMap.
+	// This field is required in all cases.
+	Namespace string `json:"namespace" protobuf:"bytes,1,opt,name=namespace"`
+
+	// Name is the metadata.name of the referenced ConfigMap.
+	// This field is required in all cases.
+	Name string `json:"name" protobuf:"bytes,2,opt,name=name"`
+
+	// UID is the metadata.UID of the referenced ConfigMap.
+	// This field is currently reqired in Node.Spec.
+	// TODO(#61643): This field will be forbidden in Node.Spec when #61643 is resolved.
+	// TODO(#56896): This field will be required in Node.Status when #56896 is resolved.
+	// +optional
+	UID types.UID `json:"uid,omitempty" protobuf:"bytes,3,opt,name=uid"`
+
+	// ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap.
+	// This field is forbidden in Node.Spec.
+	// TODO(#56896): This field will be required in Node.Status when #56896 is resolved.
+	// +optional
+	ResourceVersion string `json:"resourceVersion,omitempty" protobuf:"bytes,4,opt,name=resourceVersion"`
+
+	// KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure
+	// This field is required in all cases.
+	KubeletConfigKey string `json:"kubeletConfigKey" protobuf:"bytes,5,opt,name=kubeletConfigKey"`
 }
 
 // DaemonEndpoint contains information about a single Daemon endpoint.

vendor/k8s.io/api/core/v1/types_swagger_doc_generated.go

@@ -262,6 +262,19 @@ func (ConfigMapList) SwaggerDoc() map[string]string {
 	return map_ConfigMapList
 }
 
+var map_ConfigMapNodeConfigSource = map[string]string{
+	"":                 "ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node.",
+	"namespace":        "Namespace is the metadata.namespace of the referenced ConfigMap. This field is required in all cases.",
+	"name":             "Name is the metadata.name of the referenced ConfigMap. This field is required in all cases.",
+	"uid":              "UID is the metadata.UID of the referenced ConfigMap. This field is currently reqired in Node.Spec.",
+	"resourceVersion":  "ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap. This field is forbidden in Node.Spec.",
+	"kubeletConfigKey": "KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure This field is required in all cases.",
+}
+
+func (ConfigMapNodeConfigSource) SwaggerDoc() map[string]string {
+	return map_ConfigMapNodeConfigSource
+}
+
 var map_ConfigMapProjection = map[string]string{
 	"":         "Adapts a ConfigMap into a projected volume.\n\nThe contents of the target ConfigMap's Data field will be presented in a projected volume as files using the keys in the Data field as the file names, unless the items element is populated with specific mappings of keys to paths. Note that this is identical to a configmap volume source without the default mode.",
 	"items":    "If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'.",
@@ -969,7 +982,8 @@ func (NodeCondition) SwaggerDoc() map[string]string {
 }
 
 var map_NodeConfigSource = map[string]string{
-	"": "NodeConfigSource specifies a source of node configuration. Exactly one subfield (excluding metadata) must be non-nil.",
+	"":          "NodeConfigSource specifies a source of node configuration. Exactly one subfield (excluding metadata) must be non-nil.",
+	"configMap": "ConfigMap is a reference to a Node's ConfigMap",
 }
 
 func (NodeConfigSource) SwaggerDoc() map[string]string {

vendor/k8s.io/api/core/v1/zz_generated.deepcopy.go

@@ -631,6 +631,22 @@ func (in *ConfigMapList) DeepCopyObject() runtime.Object {
 	return nil
 }
 
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *ConfigMapNodeConfigSource) DeepCopyInto(out *ConfigMapNodeConfigSource) {
+	*out = *in
+	return
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ConfigMapNodeConfigSource.
+func (in *ConfigMapNodeConfigSource) DeepCopy() *ConfigMapNodeConfigSource {
+	if in == nil {
+		return nil
+	}
+	out := new(ConfigMapNodeConfigSource)
+	in.DeepCopyInto(out)
+	return out
+}
+
 // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
 func (in *ConfigMapProjection) DeepCopyInto(out *ConfigMapProjection) {
 	*out = *in
@@ -2360,13 +2376,12 @@ func (in *NodeCondition) DeepCopy() *NodeCondition {
 // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
 func (in *NodeConfigSource) DeepCopyInto(out *NodeConfigSource) {
 	*out = *in
-	out.TypeMeta = in.TypeMeta
-	if in.ConfigMapRef != nil {
-		in, out := &in.ConfigMapRef, &out.ConfigMapRef
+	if in.ConfigMap != nil {
+		in, out := &in.ConfigMap, &out.ConfigMap
 		if *in == nil {
 			*out = nil
 		} else {
-			*out = new(ObjectReference)
+			*out = new(ConfigMapNodeConfigSource)
 			**out = **in
 		}
 	}
@@ -2383,14 +2398,6 @@ func (in *NodeConfigSource) DeepCopy() *NodeConfigSource {
 	return out
 }
 
-// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
-func (in *NodeConfigSource) DeepCopyObject() runtime.Object {
-	if c := in.DeepCopy(); c != nil {
-		return c
-	}
-	return nil
-}
-
 // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
 func (in *NodeDaemonEndpoints) DeepCopyInto(out *NodeDaemonEndpoints) {
 	*out = *in