Mini Control Plane

Mini Control Plane is a research prototype for white-box fault analysis of Kubernetes-style control-plane semantics. It focuses on the mechanics that make control planes correct under concurrency: declarative resources, MVCC storage, watch-driven reconciliation, leader election, scheduler status updates, and controlled fault injection.

This repository accompanies the paper: "White-Box Fault Analysis for Kubernetes-Style Control Plane Semantics." It is organized for artifact evaluation: experiment configurations live in specs/experiments/, aggregated results reside in results/, and analyze_all_trials.py provides the evaluation pipeline.

Artifact Status

Category	Status
Stage	Experimental research artifact
Scope	Kubernetes-style control-plane semantics & Rollouts
Storage	etcd MVCC (distributed 3-node) plus in-memory test storage
Reproducibility	Versioned experiment configs, automated Go test suites, and analysis scripts
Production readiness	Not production-ready

Core Architecture

The control plane implements a strict 3-tier controller cascade identical to Kubernetes:

1. Deployment Controller: Manages rollouts (RollingUpdate / Recreate) and rollbacks. Owns ReplicaSets.
2. ReplicaSet Controller: Maintains replica count. Owns Resource objects.
3. Resource Controller: Binds to the Scheduler and manages actual runtime instances.

Architecture Diagram

graph TD
    Client([Client]) --> APIServer[API Server]
    APIServer -->|Persist State| Etcd[(etcd MVCC Storage)]

    subgraph Control Plane
        direction TB
        Etcd -.->|Watch / Informer| DepCtrl[Deployment Controller]
        Etcd -.->|Watch / Informer| RSCtrl[ReplicaSet Controller]
        Etcd -.->|Watch / Informer| ResCtrl[Resource Controller]
        
        DepCtrl --> Rollout[Rollout Engine]
        Rollout -->|Update RS Specs| Etcd
        RSCtrl -->|Update Resource Specs| Etcd
    end

    subgraph Execution Plane
        ResCtrl -->|Schedule| Scheduler[Scheduler]
        ResCtrl -->|Create/Delete| Runtime[Runtime Instances]
        Runtime -.->|Observed State| ResCtrl
    end

    classDef storage fill:#f9f9f9,stroke:#333,stroke-width:2px;
    class Etcd storage;

Loading

Key Research Features

• Strict Invariant Enforcement: Controllers mathematically enforce capacity limits (e.g., "Always 3, Never 6") during rollouts.
• Two-Phase Commit Analysis: The experiment framework intentionally triggers MVCC conflicts to prove that under strict capacity limits, scale-down-first execution prevents cluster surging at the cost of temporary capacity drops.
• Pluggable Fault Injection: pkg/fault/ provides middleware for probabilistic event dropping, latency injection, and MVCC conflict simulation.
• Automated Experiment Framework: cmd/experiment/ runs fully automated fault-injection campaigns and outputs structured JSONL metrics compatible with the Python analysis pipeline.

Research Questions

• How do Kubernetes-style controllers behave under conflicting status updates?
• Which fault-injection scenarios expose unsafe reconciliation behavior?
• How do leader-election timing parameters affect controller conflicts?
• Can controller state converge under partial observability (watch event loss)?
• What is the tail-latency impact of Raft consensus in a distributed control plane?

Running the System

1. Start Dependencies

bash scripts/start_etcd_cluster.sh

2. Start Controllers

go run cmd/apiserver/main.go &
go run cmd/deployment-controller/main.go &
go run cmd/replicaset-controller/main.go &
go run cmd/resource-controller/main.go &

3. Run Automated Fault Experiments

The easiest way to observe the control plane's behavior under chaos is via the isolated experiment binary:

go run cmd/experiment/main.go

Results are saved to experiments/deployment-rollout-mvcc-50pct/events.jsonl.

4. Analyze Results

python3 analysis/scripts/analyze_all_trials.py

Resource Model

Deployment

metadata:
  name: frontend
spec:
  replicas: 3
  strategy: RollingUpdate # Options: RollingUpdate, Recreate
  template:
    name: frontend
    version: v1

Testing

The core invariant logic is backed by rigorous Go tests that prove rollouts, rollbacks, and fault injection do not corrupt state:

go test ./pkg/deployment/... -v

Acknowledgments

The author acknowledges the use of the etcd and Kubernetes open-source ecosystems, which provided the foundational semantics for this fault-analysis prototype.

Citation

@inproceedings{pathak2026minicontrolplane,
  title = {White-Box Fault Analysis for Kubernetes-Style Control Plane Semantics},
  author = {Pathak, Aditya},
  booktitle =
  note = {Artifact: [https://github.com/Phoenix1504e/mini-control-plane](https://github.com/Phoenix1504e/mini-control-plane)}
}

Contributions & Governance

Maintainer: Aditya Pathak

License: Apache License 2.0

Code of Conduct: This project follows the CNCF Code of Conduct.