MCS control plane

The MCS control plane turns product intent into managed ClickHouse runtime resources. It has two cooperating parts:

1. the management control plane accepts user intent through the Console or a future API, applies authentication, authorization, validation, and limits, and persists desired state as MCS custom resources;
2. the runtime control plane, implemented by the MCS Operator, watches that desired state and executes it in Kubernetes.

The Runtime Operator is therefore not a separate product plane. It is the runtime executor of the MCS control plane. Together, the management control plane and Runtime Operator form the complete MCS control plane.

Today Kubernetes custom resources are the desired-state database and the handoff contract between these two parts. The Console is one client of the management control plane; it is not a second Operator.

The data plane consists of the runtime stacks produced from those custom resources. One MCSService CR declares one isolated ClickHouse service data plane, including its ClickHouse nodes, network endpoints, storage bindings, and optional ElasticQuery nodes. An MCSKeeper CR similarly declares a managed Keeper quorum. The CR belongs to the control plane; the reconciled workload belongs to the data plane.

The ClickHouse data plane and object-storage layout are documented separately in ClickHouse Architecture.

Components and control flow

The management control-plane service is the stable product boundary. The Console UI and a future API application use the same models, authorization, limits, and repository contracts. Kubernetes types and controller-runtime clients stop at the repository adapter boundary.

The complete flow is:

Console / API
    → management control-plane service
    → MCS desired-state CR
    → Runtime Operator
    → Kubernetes runtime resources
    → ClickHouse service data plane

Status travels in the opposite direction: the Runtime Operator publishes observed state to the CR, and the management control plane projects that state to users.

Desired-state resources

The Console creates, reads, updates, and deletes these resources through DesiredStateRepository. The Runtime Operator watches them and produces the runtime data plane. Other management control-plane applications may use the same service layer without going through the Console UI.

Control-plane responsibilities

Management control plane

The management control plane owns product-facing intent:

• authentication, sessions, organization membership, and authorization;
• validation, supported choices, defaults, and quota policy;
• transport-neutral models and business operations;
• desired-state CRUD through DesiredStateRepository;
• Console rendering and the future API boundary;
• projecting CR status, endpoints, credentials, and runtime observations back to users.

It stops at desired state. Creating an MCSService CR is success at this layer; it does not imply that the ClickHouse service is already Ready.

Runtime control plane

The Runtime Operator owns execution:

• watching MCS custom resources and generations;
• resolving release-specific ClickHouse, Keeper, storage, and ElasticQuery configuration;
• generating and reconciling Kubernetes resources;
• handling retries, idempotency, finalization, rollout ordering, and recovery;
• publishing observed status and conditions to the CR.

It consumes desired state but does not implement product-facing sessions, organization authorization, Console pages, or API request policy.

Data plane

The data plane owns data ingestion, storage, query execution, and runtime availability. It is composed of the resources reconciled for each service or Keeper CR:

• ClickHouse nodes and their Services;
• Keeper members used by those ClickHouse services;
• object-storage and local-storage bindings;
• optional read-only ElasticQuery nodes;
• supporting ConfigMaps, Secrets, PVCs, and workload Pods.

The Runtime Operator controls these resources, but it is not itself part of the data plane.

Runtime ownership

The direct-write cases are bootstrap or Console infrastructure. They are deliberately isolated behind DirectWriter; workload Services, StatefulSets, Deployments, ConfigMaps, and PVCs are not exposed by that interface.

Every adapter write returns repository.WriteResult, including the repository, desired-state or bootstrap classification, operation, direct-Kubernetes flag, and resource identity. This is the common boundary for future audit logging and API responses.

Control-plane packages

The service package is the shared business layer. Console UI and future API code are applications around it, while model remains independent of either transport. Product entities use explicit names such as ClickHouse service, organization, and Keeper so they are not confused with the Kubernetes Service kind.

Identity and naming

Every product entity has a stable platform ID in metadata.name and a mutable display name in spec.name. References, namespaces, DNS names, object-storage paths, and labels use only the stable ID:

Display names never become Kubernetes names or storage paths. ClickHouse node IDs are allocated once and persisted by the Operator so scaling and restarts do not rename existing nodes. MCSServiceUser objects live in the owning service namespace; their managed password Secrets and grants cannot cross that service boundary.

Storage contracts

DesiredStateRepository

Owns MCS entity CRUD. Its current implementation persists CRs because the Operator consumes CRs directly.

RuntimeReader

Reads actual Kubernetes state such as Pods and Secrets. Runtime observation remains a Kubernetes responsibility even if desired state later moves to a database.

DirectWriter

Contains only the small, reviewed set of Console-owned Kubernetes bootstrap writes. A new method is an ownership decision and requires an explanation for why an Operator controller cannot own it.

Reconciliation lifecycle

1. A user action becomes a transport-neutral command.
2. The control-plane service authorizes it and validates limits.
3. DesiredStateRepository persists the new desired state as a CR.
4. The Runtime Operator observes the generation and computes runtime resources.
5. Kubernetes converges those resources.
6. The Runtime Operator publishes status and conditions back to the CR.
7. The management control plane reads desired state through DesiredStateRepository and actual state through RuntimeReader.

Deletes follow the same ownership model: the Console deletes the desired-state CR and Kubernetes garbage collection plus Runtime Operator finalization remove owned data-plane resources.

Consistency and limits

• Updates use optimistic concurrency and retry Kubernetes conflicts.
• Kubernetes not-found and already-exists errors become repository-neutral errors.
• Service-layer rules run before persistence calls.
• The organization service-count limit is enforced by the control-plane service.
• CPU and memory usage is calculated live from desired service topology rather than stored as a mutable counter.
• CPU and memory budgets are visible but currently do not block a write.

Future persistence

No database migration is part of the current architecture. The prepared seam is DesiredStateRepository.

If a database later becomes authoritative, the control plane can add a database-backed repository and publish desired state to MCS CRs for the existing Operator. Console UI and future API applications continue to call the same service. RuntimeReader remains Kubernetes-backed, and the explicit bootstrap writes remain separate from entity persistence.

This separation prevents an unsafe partial migration: storing a record in a database is not considered runtime reconciliation, and writing runtime objects directly is not considered entity persistence.

Change rules

1. Handlers must not import controller-runtime clients.
2. Business rules belong in service, not templates or adapters.
3. Kubernetes errors must not escape the Kubernetes adapter.
4. Operator-owned runtime resources must never be created by Console.
5. New direct writes require an explicit DirectWriter method, ownership documentation, and adapter tests.
6. Console UI and future API applications must share control-plane service methods.