Concepts

This document outlines the core concepts behind the client-go library, providing a comprehensive overview of its functionality, structure, and use cases.

Motivation

The primary objective of client-go is to simplify and streamline interactions with the Kubernetes API server from Go applications. This library offers a comprehensive set of tools and abstractions for interacting with the Kubernetes API, enabling developers to easily manage and control Kubernetes resources, build controllers, and extend the Kubernetes ecosystem.

Structure and Organization

The client-go library is structured into several key packages, each responsible for distinct functionalities:

• kubernetes package: Provides the clientset for accessing Kubernetes API resources.
• discovery package: Used to dynamically discover APIs supported by a Kubernetes API server.
• dynamic package: Provides a dynamic client for generic operations on arbitrary Kubernetes API objects.
• plugin/pkg/client/auth packages: Contain optional authentication plugins for acquiring credentials from external sources.
• transport package: Responsible for setting up authentication and establishing connections to the API server.
• tools/cache package: Offers essential tools for developing robust controllers, including the informer framework and work queues.

Client Types

client-go supports two primary client types for interacting with the Kubernetes API:

• Typed Clients: Utilize pre-generated local API objects to interact with the API server. These clients offer a more RPC-like programming experience and benefit from program compilation for type safety and validation. However, typed clients are tightly coupled with the specific version and types used, making them less flexible for managing resources across different API versions.

• Dynamic Client: Utilizes the unstructured.Unstructured type, which represents all object values from the API server using a collection of nested map[string]interface{} values. The dynamic client is more adaptable as it does not rely on pre-generated types.

Examples

The client-go repository includes various examples demonstrating key functionalities. These examples serve as practical guides for building your own applications and controllers:

• Resource Management with API: Demonstrates the basic operations of creating, getting, updating, and deleting Kubernetes resources (e.g., Deployments). Source: examples/README.md
• Work Queues and Informers: Introduces the concept of work queues and demonstrates how to create a hotloop-free controller using the informer framework. Source: examples/README.md
• Custom Resource Definition (CRD): Guides users on registering custom resources, creating controllers to manage these resources, and handling updates and queries. Source: examples/README.md
• Leader Election: Provides an example of implementing highly available controllers by using the leader election package. Source: examples/README.md
• Typed Clients: Showcases the use of typed client sets for managing resources with pre-generated API objects. Source: examples/dynamic-create-update-delete-deployment/README.md
• Dynamic Clients: Illustrates using the dynamic package to perform basic CRUD operations on resources. Source: examples/dynamic-create-update-delete-deployment/README.md

Versioning and Compatibility

Compatibility Matrix:

client-go HEAD	Kubernetes main repo, master branch	✓
1.4	Kubernetes 1.4	=
1.5	Kubernetes 1.5	=

Key:

• ✓: Changes in the main Kubernetes repository are actively published to client-go by a bot.
• =: Maintenance is manual. Only severe security bugs are patched.
• -: Deprecated; please upgrade.

Compatibility:

• Codebase: The client-go codebase aims to maintain compatibility with the latest Kubernetes release.
• Kubernetes Clusters: The client-go library is compatible with Kubernetes clusters running the corresponding versions indicated in the compatibility matrix.

Contributing Code

Contributions to the client-go library are welcome. Please submit pull requests against the client packages in the main Kubernetes repository. Source: README.md

Further Information

For detailed information and documentation on specific client-go components, refer to the official documentation: https://godoc.org/k8s.io/client-go

Top-Level Directory Explanations

applyconfigurations/ - This directory contains examples and tests for applying Kubernetes configurations using the client-go library.

discovery/ - This directory contains code related to service discovery in Kubernetes.

dynamic/ - This directory contains code for working with dynamic resources in the Kubernetes API.

examples/ - This directory contains example usage of the client-go library.

features/ - This directory contains experimental features that are not yet stable.

gentype/ - This directory contains generated Go types for the Kubernetes API.

informers/ - This directory contains code for caching Kubernetes resources using informers.

kubernetes/ - This directory contains the main package for the client-go library, which provides types and functions for interacting with the Kubernetes API.

listers/ - This directory contains interfaces and implementations for listing Kubernetes resources.

metadata/ - This directory contains code related to metadata in Kubernetes.

rest/ - This directory contains code for working with the REST API in the client-go library.

scale/ - This directory contains code for working with scale and autoscaling in Kubernetes.

tools/ - This directory contains various tools for working with the client-go library.