Add doc.go and ARCHITECTURE.md to client-go

Kubernetes-commit: accdd9e27e74706f63e06ff5cb0476098b377b1e

doc.go

@@ -14,4 +14,97 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package clientgo is the official Go client for the Kubernetes API. It provides
+// a standard set of clients and tools for building applications, controllers,
+// and operators that communicate with a Kubernetes cluster.
+//
+// # Key Packages
+//
+//   - kubernetes: Contains the typed Clientset for interacting with built-in,
+//     versioned API objects (e.g., Pods, Deployments). This is the most common
+//     starting point.
+//
+//   - dynamic: Provides a dynamic client that can perform operations on any
+//     Kubernetes object, including Custom Resources (CRs). It is essential for
+//     building controllers that work with CRDs.
+//
+//   - discovery: Used to discover the API groups, versions, and resources
+//     supported by a Kubernetes cluster.
+//
+//   - tools/cache: The foundation of the controller pattern. This package provides
+//     efficient caching and synchronization mechanisms (Informers and Listers)
+//     for building controllers.
+//
+//   - tools/clientcmd: Provides methods for loading client configuration from
+//     kubeconfig files. This is essential for out-of-cluster applications and CLI tools.
+//
+//   - rest: Provides a lower-level RESTClient that manages the details of
+//     communicating with the Kubernetes API server. It is useful for advanced
+//     use cases that require fine-grained control over requests, such as working
+//     with non-standard REST verbs.
+//
+// # Connecting to the API
+//
+// There are two primary ways to configure a client to connect to the API server:
+//
+//  1. In-Cluster Configuration: For applications running inside a Kubernetes pod,
+//     the `rest.InClusterConfig()` function provides a straightforward way to
+//     configure the client. It automatically uses the pod's service account for
+//     authentication and is the recommended approach for controllers and operators.
+//
+//  2. Out-of-Cluster Configuration: For local development or command-line tools,
+//     the `clientcmd` package is used to load configuration from a
+//     kubeconfig file.
+//
+// The `rest.Config` object allows for fine-grained control over client-side
+// performance and reliability. Key settings include:
+//
+//   - QPS: The maximum number of queries per second to the API server.
+//   - Burst: The maximum number of queries that can be issued in a single burst.
+//   - Timeout: The timeout for individual requests.
+//
+// # Interacting with API Objects
+//
+// Once configured, a client can be used to interact with objects in the cluster.
+//
+//   - The Typed Clientset (`kubernetes` package) provides a strongly typed
+//     interface for working with built-in Kubernetes objects.
+//
+//   - The Dynamic Client (`dynamic` package) can work with any object, including
+//     Custom Resources, using `unstructured.Unstructured` types.
+//
+//   - For Custom Resources (CRDs), the `k8s.io/code-generator` repository
+//     contains the tools to generate typed clients, informers, and listers. The
+//     `sample-controller` is the canonical example of this pattern.
+//
+//   - Server-Side Apply is a patching strategy that allows multiple actors to
+//     share management of an object by tracking field ownership. This prevents
+//     actors from inadvertently overwriting each other's changes and provides
+//     a mechanism for resolving conflicts. The `applyconfigurations` package
+//     provides the necessary tools for this declarative approach.
+//
+// # Handling API Errors
+//
+// Robust error handling is essential when interacting with the API. The
+// `k8s.io/apimachinery/pkg/api/errors` package provides functions to inspect
+// errors and check for common conditions, such as whether a resource was not
+// found or already exists. This allows controllers to implement robust,
+// idempotent reconciliation logic.
+//
+// # Building Controllers
+//
+// The controller pattern is central to Kubernetes. A controller observes the
+// state of the cluster and works to bring it to the desired state.
+//
+//   - The `tools/cache` package provides the building blocks for this pattern.
+//     Informers watch the API server and maintain a local cache, Listers provide
+//     read-only access to the cache, and Workqueues decouple event detection
+//     from processing.
+//
+//   - In a high-availability deployment where multiple instances of a controller
+//     are running, leader election (`tools/leaderelection`) is used to ensure
+//     that only one instance is active at a time.
+//
+//   - Client-side feature gates allow for enabling or disabling experimental
+//     features in `client-go`. They can be configured via the `rest.Config` object.
 package clientgo