# Personal Control Plane Dev Environment Design

Date: 2026-03-29

## Purpose

This document is a design draft for an internal developer platform that can:

- create a personal control-plane environment quickly
- support control-plane feature development and validation
- optionally create TiDB instances for integration testing
- destroy the environment quickly after use

This belongs in `construction/` because it is a goal-oriented design and planning artifact, not a stable KB fact set.

## Design Goal

The platform should let one developer request:

1. a personal control-plane sandbox
2. optional dedicated or serverless execution capability
3. fast teardown with predictable cost and cleanup boundaries

The design should avoid forcing every developer to own a full cloud account or a full region stack.

## Current KB Support Level

The current KB is strong enough to answer:

- which deployment objects belong to the control plane
- which services are foundational versus orchestration versus regional execution
- which deployment objects map to source repos or bundles
- where those objects are deployed today
- which direct manifest-level dependencies are already proven

The current KB is not yet strong enough to finalize a production implementation design.

## Recommended Product Shape

Provide two environment classes.

### Class A: Control-Plane-Only Sandbox

Use this for:

- API and orchestration feature development
- UI and workflow verification
- control-plane regression checks without creating real TiDB clusters

Properties:

- fastest startup
- lowest cost
- can rely on mocked or shared execution backends
- should be the default personal environment class

### Class B: Control Plane Plus Real Execution Sandbox

Use this for:

- end-to-end create, scale, pause, resume, delete testing
- real TiDB cluster creation
- private link, network, or regional orchestration validation

Properties:

- slower startup
- higher cost
- must provision or reserve real execution capacity
- should be opt-in rather than default

## Recommended Architecture

### Shared Foundation, Isolated Personal Slices

Do not give every developer a fully isolated copy of the entire platform stack.

Instead:

- keep heavy shared foundation services in a shared base environment
- create isolated personal namespaces, configs, and routing for developer-owned control-plane slices
- optionally attach a lightweight personal execution sandbox for real cluster creation tests

This is the most practical tradeoff because the current deployment knowledge shows a large shared base-cluster footprint for core control-plane and support services.

## Layer Model

### Shared Foundation Layer

Recommended to stay shared:

- `account-svc`
- `authserver`
- `billing-svc`
- `config-center`
- `config-service`
- `core-svc`
- `cluster-secret-store`
- `external-secrets-operator`
- common observability and addon bundles needed by many workloads

Reason:

- these services behave like foundational identity, configuration, and shared platform dependencies
- they already appear broadly in base-cluster style environments
- duplicating them per developer would be expensive and slow

### Personal Global Control Slice

Recommended to isolate per developer:

- `tidb-mgmt-service`
- `dedicated-global-service`
- `serverless-global-service`
- `nextgen-global-service`
- `serverless-global-regional-proxy`
- optional `tidb-mgmt-portal`

Reason:

- these are the main orchestration entrypoints
- developers need freedom to change logic, routes, and workflows without breaking each other
- isolation here gives the most product value per cost unit

### Personal Domain Addons

Recommended to isolate when the feature area requires them:

- `dataservice-central-svc`
- `dataflow-svc`
- `dedicated-metering-server`
- `devops-service`
- `o11y-svc`
- `rbac-management-service`
- `tempo-*` objects

Reason:

- some features depend on these directly
- not every personal environment needs the full set
- they should be enabled by profile rather than forced into every environment

### Optional Personal Regional Execution Slice

Needed only for real create-and-run tests:

- `dedicated-regional-server`
- `serverless-regional-service`
- `tcidm-service`
- next-gen regional execution components
- regional providers and control-plane addons required by that path

Reason:

- these objects represent the actual execution plane
- they are unnecessary for pure global-control development
- they drive most of the real cloud-resource cost and operational risk

## Recommended Environment Profiles

### Profile 1: API/Workflow Dev

Includes:

- shared foundation layer
- personal global control slice
- minimal portal and auth integration
- mocked or fixed regional backends

### Profile 2: Control Plane Integration

Includes:

- Profile 1
- selected domain addons
- stronger observability
- partial regional execution stubs or a small shared integration region

### Profile 3: Real TiDB Provisioning

Includes:

- Profile 2
- personal or reserved execution slice
- real provider credentials and regional resources
- strong cleanup controls

## Isolation Strategy

Recommended isolation keys:

- developer ID
- environment class
- feature or branch name

Recommended naming model:

- namespace: `dev-<user>-<slice>`
- config scope: `personal/<user>/<slice>`
- routing host or ingress prefix: `<user>-<slice>.<internal-domain>`

## Provisioning Workflow

### Create

1. choose profile and TTL
2. allocate naming, namespace, and config scope
3. materialize a personal app-delivery projection or generated overlays
4. deploy the personal global control slice
5. attach optional domain addons
6. attach optional regional execution slice
7. run smoke checks and publish endpoints

### Destroy

1. drain or delete developer-created TiDB instances first
2. remove personal regional execution resources
3. remove personal control-plane workloads
4. remove personal config scope and routing
5. confirm no leftover namespaces, secrets, or cloud artifacts remain

## Minimal Service Sets

### Minimum Set For Control-Plane Feature Work

- shared foundation layer
- `tidb-mgmt-service`
- one of:
  - `dedicated-global-service`
  - `serverless-global-service`
  - `nextgen-global-service`
- required support objects for that chosen path

### Minimum Set For Dedicated Cluster Creation

- shared foundation layer
- `tidb-mgmt-service`
- `dedicated-global-service`
- `dedicated-regional-server`
- required infra/provider path for that region

### Minimum Set For Serverless Creation

- shared foundation layer
- `tidb-mgmt-service`
- `serverless-global-service`
- `serverless-regional-service`
- `serverless-svc`
- required billing and account dependencies

### Minimum Set For Next-Gen / Shared Pool Creation

- shared foundation layer
- `nextgen-global-service`
- `cluster-ng-service` or equivalent next-gen execution path
- required config and metering dependencies

## Recommended MVP

Start with a pragmatic MVP instead of full self-service region creation.

### MVP Scope

- support Profile 1 first
- allow developers to spin up personal global-control slices in shared base clusters
- provide feature flags to choose dedicated/serverless/next-gen control services
- provide one small shared integration backend for non-production workflow tests
- postpone fully personal real execution slices until cleanup and cost controls are proven

## Five Missing Information Categories

The current KB still lacks five implementation-critical information categories for this goal.

### 1. Service Bootstrap And External Dependency Contracts

Still missing:

- exact database, queue, cache, object-store, and KMS dependencies per critical service
- boot order and health expectations for those dependencies
- whether a personal environment can reuse shared backends safely

Without this:

- startup automation will be fragile
- personal environments may boot partially but not become functional

### 2. Real TiDB Provisioning Boundary

Still missing:

- the exact minimal regional and data-plane components required to create a real TiDB instance
- which parts can be mocked
- which parts must create real cloud resources

Without this:

- a "create TiDB cluster" profile cannot be scoped accurately
- cost and blast-radius estimates remain unreliable

### 3. Minimum Healthy Subgraph Inside Large Bundles

Still missing:

- the minimum runnable subset inside bundles such as `clinic` and next-gen regional bundles
- which internal components are optional versus required
- which components can stay shared

Without this:

- bundle-based profiles will over-provision by default
- startup time and cost will be unnecessarily high

### 4. Identity, Secret, And Permission Model

Still missing:

- secret-store strategy for personal environments
- IAM or cloud-role boundaries for developer-owned execution
- whether personal environments can reuse shared control-plane credentials safely

Without this:

- self-service creation is unsafe
- destroy-time cleanup cannot be trusted

### 5. Cost, Quota, And Reclamation Strategy

Still missing:

- per-profile cost model
- concurrency limits
- TTL defaults
- leak-detection and cleanup guarantees

Without this:

- the platform can create uncontrolled cloud spend
- the destroy flow may not actually reclaim resources

## Required Platform Capabilities

The future implementation should include:

- environment templates by profile
- per-developer config generation
- namespace and ingress automation
- TTL and scheduled cleanup
- quota control
- audit trail of who created which environment
- destroy-time resource leak checks
- smoke test packs per profile

## Key Risks

### 1. Shared Foundation Drift

If personal slices rely on mutable shared services, reproducibility will be imperfect.

### 2. Secret And Credential Scope

Real execution tests will require careful scoping of cloud credentials and secret stores.

### 3. Bundle Complexity

Large bundles such as `clinic` and next-gen regional control bundles are not yet fully decomposed into minimum healthy subsets.

### 4. Cleanup Reliability

Real cluster creation tests can leave behind cloud resources unless teardown is strongly enforced.

## Current Recommendation

Yes, the current KB is strong enough to design the platform at architecture level.

No, the current KB is not yet strong enough to finalize a production implementation design.

The best next step is to turn this draft into an implementation-oriented follow-up focused on:

- minimum service set per profile
- shared versus isolated boundary decisions
- region and provider strategy for real TiDB provisioning
- concrete answers for the five missing information categories