Client Libraries

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.

Clientset Architecture Diagram:

Core Classes:

1. Clientset
   Fields:
   - *discovery.DiscoveryClient
   - analysisV1alpha1: *AnalysisV1alpha1Client
   - configV1alpha1: *ConfigV1alpha1Client
   - quotaV1alpha1: *QuotaV1alpha1Client
   - schedulingV1alpha1: *SchedulingV1alpha1Client
   - sloV1alpha1: *SloV1alpha1Client

2. AnalysisV1alpha1Client
   Fields:
   - *rest.RESTClient
   - recommendations: *RecommendationInterface

3. SchedulingV1alpha1Client
   Fields:
   - *rest.RESTClient
   - reservations: *ReservationInterface
   - podMigrationJobs: *PodMigrationJobInterface

4. SloV1alpha1Client
   Fields:
   - *rest.RESTClient
   - nodeMetrics: *NodeMetricInterface
   - nodeSLOs: *NodeSLOInterface

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

CRUD Operations Sequence Diagram:

Participants:
- Application
- KoordinatorClientset
- RESTClient
- KubernetesAPI

Flow:

1. Application → KoordinatorClientset: NewForConfig(config)
2. KoordinatorClientset internal: Initialize clients for all API groups
3. KoordinatorClientset → Application: Return Clientset
4. Application → KoordinatorClientset: Get SLO client
5. KoordinatorClientset → Application: Return SloV1alpha1Client
6. Application → RESTClient: Create NodeMetric
7. RESTClient → KubernetesAPI: POST /apis/slo.koordinator.sh/v1alpha1/nodemetrics
8. KubernetesAPI → RESTClient: Return created resource
9. RESTClient → Application: Return NodeMetric object
10. Application → RESTClient: Update NodeMetric
11. RESTClient → KubernetesAPI: PUT /apis/slo.koordinator.sh/v1alpha1/nodemetrics/nodename
12. KubernetesAPI → RESTClient: Return updated resource
13. RESTClient → Application: 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.

Informer Pattern Class Diagram:

Core Classes:

1. SharedInformerFactory
   Fields:
   - client: versioned.Interface
   - defaultResync: time.Duration
   - informers: map[reflect.Type]SharedIndexInformer
   - startedInformers: map[reflect.Type]bool

2. NodeMetricInformer
   Methods:
   - Informer() cache.SharedIndexInformer
   - Lister() NodeMetricLister

3. ReservationInformer
   Methods:
   - Informer() cache.SharedIndexInformer
   - Lister() ReservationLister

4. RecommendationInformer
   Methods:
   - Informer() cache.SharedIndexInformer
   - Lister() RecommendationLister

5. SharedIndexInformer
   Methods:
   - AddEventHandler(handler ResourceEventHandler)
   - GetStore() Store
   - GetController() Controller

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

Lister Interfaces Class Diagram:

Core Classes:

1. NodeMetricLister
   Methods:
   - List(selector labels.Selector) []*NodeMetric
   - Get(name string) *NodeMetric
   - NodeMetricListerExpansion

2. ReservationLister
   Methods:
   - List(selector labels.Selector) []*Reservation
   - Get(name string) *Reservation
   - ReservationListerExpansion

3. RecommendationLister
   Methods:
   - List(selector labels.Selector) []*Recommendation
   - Recommendations(namespace string) RecommendationNamespaceLister
   - RecommendationListerExpansion

4. RecommendationNamespaceLister
   Methods:
   - List(selector labels.Selector) []*Recommendation
   - Get(name string) *Recommendation

Relationships:
- NodeMetricInformer → NodeMetricLister (provides)
- ReservationInformer → ReservationLister (provides)
- RecommendationInformer → RecommendationLister (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.

Shared Informer Management Flow:

1. Create SharedInformerFactory
   ↓
2. Configure with client and resync period
   ↓
3. Create informer for specific resource
   ↓
4. Start informer with stop channel
   ↓
5. WaitForCacheSync
   ↓
6. Informer ready for use
   ├── Use Lister to query cache
   └── Add event handlers for create/update/delete
        ↓
7. Process events in controller logic
   ↓
8. Handle resource changes

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.

Delegation, Rate Limiting, and Retry Architecture:

Application
  ↓
Delegating Client
  ↓
Rate Limiter ───┬───────────────
  ↓             │ Client-Side Controls
Retry Mechanism ─┴───────────────
  ↓
Kubernetes API Server
  ↓
Response
  ↓
Retry Mechanism
  ↓
Rate Limiter
  ↓
Delegating Client
  ↓
Application

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.

DeepCopy Methods Class Diagram:

Core Classes:

1. Recommendation
   Methods:
   - DeepCopy() *Recommendation
   - DeepCopyInto(*Recommendation)
   - DeepCopyObject() runtime.Object

2. Reservation
   Methods:
   - DeepCopy() *Reservation
   - DeepCopyInto(*Reservation)
   - DeepCopyObject() runtime.Object

3. NodeMetric
   Methods:
   - DeepCopy() *NodeMetric
   - DeepCopyInto(*NodeMetric)
   - DeepCopyObject() runtime.Object

4. DeepCopyInterface
   Methods:
   - DeepCopy() interface{}
   - DeepCopyInto(interface{})

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

Integration with controller-runtime Sequence Diagram:

Participants:
- ControllerManager
- ControllerBuilder
- CustomReconciler
- KoordinatorClient
- SharedInformerCache

Flow:

1. ControllerManager → ControllerBuilder: SetupWithManager
2. ControllerBuilder → ControllerManager: Register Controller
3. ControllerManager → SharedInformerCache: Start Shared Informers
4. SharedInformerCache internal: Synchronize caches

[Event Processing Loop]
5. SharedInformerCache → CustomReconciler: Trigger Reconcile(request)
6. CustomReconciler → KoordinatorClient: Get resource from cache via Lister
7. KoordinatorClient → CustomReconciler: Return resource
8. CustomReconciler → KoordinatorClient: Update resource status
9. KoordinatorClient → API: PATCH resource status
10. API → KoordinatorClient: Return updated resource
11. KoordinatorClient → CustomReconciler: Confirm update
12. CustomReconciler → ControllerManager: Return result
[Loop 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:

Best Practices Flow:

1. Initialize Clientset
   ↓
2. Create SharedInformerFactory
   ↓
3. Get Informer for Resource
   ↓
4. Add Event Handlers
   ↓
5. Start Informer
   ↓
6. WaitForCacheSync
   ↓
7. Use Lister for Queries
   ↓
8. Handle Events with Reconciliation
   ↓
9. Use DeepCopy when modifying objects
   ↓
10. Handle Resource Version Conflicts
    ↓
11. Implement Proper Error Handling
    ↓
12. Shutdown Gracefully

Diagram sources

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

Section sources

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