Client Libraries

info

This document is generated with assistance from Qoder AI.

Introduction

This document provides comprehensive documentation for Koordinator's Go client libraries, which enable programmatic interaction with Koordinator's custom resources. The client libraries support standard Kubernetes-style operations for creating, reading, updating, and deleting Custom Resource Definitions (CRDs), including Recommendations, Reservations, and NodeMetrics. The architecture leverages Kubernetes client-go patterns with specialized extensions for efficient event-driven programming through informers and cache synchronization. This documentation covers the full spectrum of client functionality, from basic CRUD operations to advanced patterns involving shared informers, listers, and integration with controller-runtime for building custom controllers.

Clientset Architecture

The Koordinator clientset provides a unified interface for accessing all Koordinator custom resources through versioned API groups. The architecture follows Kubernetes client-go conventions with typed clients for each API group.

classDiagram
class Clientset {
+*discovery.DiscoveryClient
+analysisV1alpha1 *AnalysisV1alpha1Client
+configV1alpha1 *ConfigV1alpha1Client
+quotaV1alpha1 *QuotaV1alpha1Client
+schedulingV1alpha1 *SchedulingV1alpha1Client
+sloV1alpha1 *SloV1alpha1Client
}
class AnalysisV1alpha1Client {
+*rest.RESTClient
+recommendations *RecommendationInterface
}
class SchedulingV1alpha1Client {
+*rest.RESTClient
+reservations *ReservationInterface
+podMigrationJobs *PodMigrationJobInterface
}
class SloV1alpha1Client {
+*rest.RESTClient
+nodeMetrics *NodeMetricInterface
+nodeSLOs *NodeSLOInterface
}
Clientset --> AnalysisV1alpha1Client : "has"
Clientset --> SchedulingV1alpha1Client : "has"
Clientset --> SloV1alpha1Client : "has"
AnalysisV1alpha1Client --> RecommendationInterface : "implements"
SchedulingV1alpha1Client --> ReservationInterface : "implements"
SloV1alpha1Client --> NodeMetricInterface : "implements"

Diagram sources

• clientset.go
• analysis_client.go
• scheduling_client.go
• slo_client.go

Section sources

• clientset.go

CRUD Operations with Typed Clients

The clientset provides typed interfaces for performing CRUD operations on Koordinator custom resources. Each API group has its own client that exposes resource-specific operations through interface methods.

sequenceDiagram
participant App as Application
participant Clientset as KoordinatorClientset
participant REST as RESTClient
participant API as KubernetesAPI
App->>Clientset : NewForConfig(config)
Clientset->>Clientset : Initialize clients for all API groups
Clientset-->>App : Return Clientset
App->>Clientset : Get SLO client
Clientset-->>App : Return SloV1alpha1Client
App->>REST : Create NodeMetric
REST->>API : POST /apis/slo.koordinator.sh/v1alpha1/nodemetrics
API-->>REST : Return created resource
REST-->>App : Return NodeMetric object
App->>REST : Update NodeMetric
REST->>API : PUT /apis/slo.koordinator.sh/v1alpha1/nodemetrics/nodename
API-->>REST : Return updated resource
REST-->>App : Return updated NodeMetric

Diagram sources

• clientset.go
• nodemetric.go
• recommendation.go
• reservation.go

Section sources

• clientset.go
• nodemetric.go
• recommendation.go
• reservation.go

Informer Pattern Implementation

The informer pattern enables efficient event-driven programming by maintaining a local cache of Koordinator resources and notifying controllers of changes. Informers watch resources and keep a synchronized cache, reducing direct API server calls.

classDiagram
class SharedInformerFactory {
+client versioned.Interface
+defaultResync time.Duration
+informers map[reflect.Type]SharedIndexInformer
+startedInformers map[reflect.Type]bool
}
class NodeMetricInformer {
+Informer() cache.SharedIndexInformer
+Lister() NodeMetricLister
}
class ReservationInformer {
+Informer() cache.SharedIndexInformer
+Lister() ReservationLister
}
class RecommendationInformer {
+Informer() cache.SharedIndexInformer
+Lister() RecommendationLister
}
class SharedIndexInformer {
+AddEventHandler(handler ResourceEventHandler)
+GetStore() Store
+GetController() Controller
}
SharedInformerFactory --> NodeMetricInformer : "creates"
SharedInformerFactory --> ReservationInformer : "creates"
SharedInformerFactory --> RecommendationInformer : "creates"
NodeMetricInformer --> SharedIndexInformer : "implements"
ReservationInformer --> SharedIndexInformer : "implements"
RecommendationInformer --> SharedIndexInformer : "implements"

Diagram sources

• factory.go
• nodemetric.go
• reservation.go
• recommendation.go

Section sources

• factory.go
• nodemetric.go
• reservation.go

Lister Interfaces for Cache Queries

Lister interfaces provide read-only access to the local cache maintained by informers, enabling efficient querying of Koordinator resources without direct API server calls. Listers return objects that must be treated as read-only to maintain cache consistency.

classDiagram
class NodeMetricLister {
+List(selector labels.Selector) []*NodeMetric
+Get(name string) *NodeMetric
+NodeMetricListerExpansion
}
class ReservationLister {
+List(selector labels.Selector) []*Reservation
+Get(name string) *Reservation
+ReservationListerExpansion
}
class RecommendationLister {
+List(selector labels.Selector) []*Recommendation
+Recommendations(namespace string) RecommendationNamespaceLister
+RecommendationListerExpansion
}
class RecommendationNamespaceLister {
+List(selector labels.Selector) []*Recommendation
+Get(name string) *Recommendation
}
NodeMetricLister <|-- NodeMetricInformer : "provides"
ReservationLister <|-- ReservationInformer : "provides"
RecommendationLister <|-- RecommendationInformer : "provides"
RecommendationLister --> RecommendationNamespaceLister : "creates"

Diagram sources

• nodemetric_list.go
• reservation_list.go
• recommendation_list.go

Section sources

• nodemetric_list.go
• reservation_list.go
• recommendation_list.go

Shared Informer Management

Shared informer factories enable multiple controllers to share a single informer instance, reducing resource consumption and API server load. The factory manages the lifecycle of informers and ensures cache consistency across controllers.

flowchart TD
Start([Create SharedInformerFactory]) --> Configure["Configure with client and resync period"]
Configure --> Create["Create informer for specific resource"]
Create --> Start["Start informer with stop channel"]
Start --> Sync["WaitForCacheSync"]
Sync --> Ready["Informer ready for use"]
Ready --> Query["Use Lister to query cache"]
Ready --> Watch["Add event handlers for create/update/delete"]
Watch --> Process["Process events in controller logic"]
Query --> Process
Process --> End([Handle resource changes])
style Start fill:#f9f,stroke:#333
style End fill:#f9f,stroke:#333

Diagram sources

• factory.go
• factory.go

Section sources

• factory.go
• factory.go

Delegation, Rate Limiting, and Retry Mechanisms

The Koordinator client architecture implements delegation patterns with built-in rate limiting and retry mechanisms to ensure reliable communication with the Kubernetes API server while respecting cluster resource constraints.

flowchart LR
A[Application] --> B[Delegating Client]
B --> C[Rate Limiter]
C --> D[Retry Mechanism]
D --> E[Kubernetes API Server]
E --> F[Response]
F --> D
D --> C
C --> B
B --> A
subgraph "Client-Side Controls"
C
D
end
style C fill:#e6f3ff,stroke:#333
style D fill:#e6f3ff,stroke:#333

Diagram sources

• clientset.go
• generic_client.go
• registry.go

Section sources

• clientset.go
• generic_client.go
• registry.go

DeepCopy Methods and Thread Safety

All Koordinator custom resource types include generated DeepCopy methods that enable safe copying of objects in concurrent environments. These methods ensure thread safety when working with cached objects from informers.

classDiagram
class Recommendation {
+DeepCopy() *Recommendation
+DeepCopyInto(*Recommendation)
+DeepCopyObject() runtime.Object
}
class Reservation {
+DeepCopy() *Reservation
+DeepCopyInto(*Reservation)
+DeepCopyObject() runtime.Object
}
class NodeMetric {
+DeepCopy() *NodeMetric
+DeepCopyInto(*NodeMetric)
+DeepCopyObject() runtime.Object
}
class DeepCopyInterface {
+DeepCopy() interface{}
+DeepCopyInto(interface{})
}
Recommendation --> DeepCopyInterface : "implements"
Reservation --> DeepCopyInterface : "implements"
NodeMetric --> DeepCopyInterface : "implements"

Diagram sources

• zz_generated.deepcopy.go
• zz_generated.deepcopy.go
• zz_generated.deepcopy.go

Section sources

• recommendation_types.go
• reservation_types.go
• nodemetric_types.go

Integration with controller-runtime

Koordinator clients can be seamlessly integrated with controller-runtime to build custom controllers that react to changes in Koordinator resources. The integration leverages the same informer and lister patterns while providing higher-level abstractions.

sequenceDiagram
participant Manager as ControllerManager
participant Builder as ControllerBuilder
participant Reconciler as CustomReconciler
participant Client as KoordinatorClient
participant Cache as SharedInformerCache
Manager->>Builder : SetupWithManager
Builder->>Manager : Register Controller
Manager->>Cache : Start Shared Informers
Cache->>Cache : Synchronize caches
loop Event Processing
Cache->>Reconciler : Trigger Reconcile(request)
Reconciler->>Client : Get resource from cache via Lister
Client-->>Reconciler : Return resource
Reconciler->>Client : Update resource status
Client->>API : PATCH resource status
API-->>Client : Return updated resource
Client-->>Reconciler : Confirm update
Reconciler-->>Manager : Return result
end

Diagram sources

• clientset.go
• factory.go
• registry.go

Section sources

• clientset.go
• factory.go
• registry.go

Best Practices and Common Patterns

When working with Koordinator client libraries, several best practices ensure efficient and reliable operation:

flowchart TD
A[Initialize Clientset] --> B[Create SharedInformerFactory]
B --> C[Get Informer for Resource]
C --> D[Add Event Handlers]
D --> E[Start Informer]
E --> F[WaitForCacheSync]
F --> G[Use Lister for Queries]
G --> H[Handle Events with Reconciliation]
H --> I[Use DeepCopy when modifying objects]
I --> J[Handle Resource Version Conflicts]
J --> K[Implement Proper Error Handling]
K --> L[Shutdown Gracefully]
style A fill:#d4edda,stroke:#333
style L fill:#d4edda,stroke:#333

Diagram sources

• clientset.go
• factory.go
• generic_client.go

Section sources

• clientset.go
• factory.go
• generic_client.go