| /* |
| Copyright 2021 The Kubernetes Authors. |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 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 |
