Discussion: ClusterManager Implementation Patterns and Best Practices

[kahirokunn]

Background

With the introduction of status.accessProviders in ClusterProfile (KEP-5339), there is a need to establish clear guidelines for ClusterManager implementations. Currently, there are conflicting approaches being discussed regarding how ClusterProfile status fields should be managed.

Current Situation

The ClusterProfile status contains multiple fields:

• status.properties
• status.accessProviders
• status.version
• status.conditions

Conflicting Views

View 1: Separate Plugin Controller for AccessProviders

From #18 (comment):

I would consider a plugins dir, something like plugins/secretreader/cmd/plugin and plugins/secretreader/cmd/controller, since we also need a controller to update access provider field

This suggests having dedicated controllers for specific status fields like accessProviders.

View 2: Single Controller Manages All Status

A counter-argument states:

From #18 (comment):

I understood that ClusterManager automatically generates both the custom resource of ClusterProfile and its status, and also sets status.accessProviders. And there is only one controller that can update the status of ClusterProfile. This is because KEP-4322 states the following:

Each ClusterProfile resource SHOULD be managed by only one cluster manager.

Therefore, I thought that a controller to update the access provider field was unnecessary. This is because no one would use that controller.

Key concerns with separate controllers:

• No field in ClusterProfile stores information indicating which ClusterProfile was derived from which source
• Without KEP modifications, developing separate controllers may be meaningless
• The single-manager principle from KEP-4322 suggests one controller should handle all status updates

Possible Implementation Patterns

Pattern A: Monolithic Controller

• One controller per ClusterManager manages all status fields
• Pros: Clear ownership, simpler RBAC, aligns with "one manager" principle
• Cons: Less modular, harder to extend with plugins

Pattern B: Multiple Specialized Controllers

• Multiple controllers update different status fields independently
• Example: One controller for status.version, another for status.properties, another for status.accessProviders
• Similar to how different controllers can manage different status.conditions

Pattern C: Hybrid Approach

• One primary controller with plugin interfaces
• Controller orchestrates plugins but maintains ultimate ownership
• May delegate specific fields to specialized controllers using Server-Side Apply

Pattern D: Shared Field Management

• Multiple controllers can update the same field cooperatively
• Example: Multiple controllers adding entries to status.properties (like different controllers managing different status.conditions)
• Each controller is responsible for specific entries within a list field

Questions for Discussion

1. Controller Separation: Is the ClusterManager expected to be:

   • A single controller that both creates ClusterProfile resources AND updates their status?
   • Separate controllers (one for creation, another for status updates)?
   • A flexible pattern where either approach is acceptable?

2. Multiple Controllers Per Field: Should we support multiple controllers updating the same status field?

   • Example: Multiple controllers adding entries to status.properties

3. Primary Question: Should ClusterProfile status be managed by a single controller or multiple specialized controllers?

4. AccessProviders Specifically: For status.accessProviders:

   • Should this be populated by the same controller that manages other status fields?
   • Or should credential plugins be separate controllers?
   • How does this interact with KEP-5339's plugin mechanism?

5. Best Practices Documentation: What guidance should we provide to ClusterManager implementers?

   • Repository structure recommendations
   • Controller deployment patterns
   • Testing strategies
   • Plugin development guidelines
   • Field ownership conventions

Proposal Request

We need comprehensive guidelines that address:

1. ClusterManager Architecture Patterns

   • Recommended controller patterns (monolithic vs modular)
   • When to use each pattern
   • How to implement each pattern

2. Status Field Management

   • Clear ownership rules for each status field
   • Conflict resolution strategies
   • Update frequency recommendations

3. Sample Implementations

   • Reference implementations demonstrating best practices
   • Examples for common use cases (GKE, EKS, Cluster API, etc.)