# DATAPLANE-MANAGER KNOWLEDGE BASE

## OVERVIEW

`dataplane-manager` is the regional infrastructure controller and API server used by Cluster Service. It runs `controller` and `server` components, manages high-level dataplane CRs in `dataplane-metadata`, and keeps most cloud/Kubernetes orchestration logic under `pkg/controllers/`.

This file is a map, not a tutorial.

→ **Deep architecture and troubleshooting**: [`ARCHITECTURE.md`](ARCHITECTURE.md)  
→ **Parent service map**: [`../AGENTS.md`](../AGENTS.md)

## STRUCTURE

- `main.go`: startup flags such as `--enabled-components` and `--enabled-controllers`.
- `pkg/component/`: wiring for `server` and `controller`.
- `api/v1alpha1/`: top-level CRD types.
- `pkg/controllers/`: reconcile loops by CRD domain.
- `pkg/controllers/*/task/`: task pipelines behind each controller.
- `pkg/service/` and `pkg/router/`: gRPC and HTTP surface.
- `pkg/repository/`: access layer for dataplane-manager CRDs.
- `pkg/k8s/`: apply helpers for non-dataplane-manager K8s resources.
- `pkg/config/` and `examples/`: config schema and example manifests.
- `pkg/consts/` and `pkg/namer/`: labels, annotations, naming rules.

## WHERE TO LOOK

| Task | Location | Guide |
|------|----------|-------|
| Understand namespace layout and CRD hierarchy | [`ARCHITECTURE.md`](ARCHITECTURE.md) | [`ARCHITECTURE.md` → Namespace Layout](ARCHITECTURE.md#namespace-layout) |
| Follow top-level DataPlane orchestration | `pkg/controllers/dataplane/`, `pkg/controllers/dataplane/task/` | [`ARCHITECTURE.md` → DataPlane Task Pipeline](ARCHITECTURE.md#dataplane-task-pipeline) |
| Work on AppBox component rollout | `pkg/controllers/appbox/taskbuilder.go`, `pkg/controllers/appbox/task/{common,eks,ack,aks}/` | [`ARCHITECTURE.md` → AppBox Component Pipeline](ARCHITECTURE.md#appbox-component-pipeline) |
| Change API behavior | `pkg/service/`, `pkg/router/`, `../../api/tidbcloud/dataplane-manager/` | grpc + grpc-gateway surface |
| Change CRD fields or annotations | `api/v1alpha1/`, `pkg/consts/` | Check labels, annotations, and generated CRDs together |
| Change resource access semantics | `pkg/repository/`, `pkg/k8s/` | CRDs vs generic K8s resources use different access paths |
| Troubleshoot unhealthy dataplane resources | [`ARCHITECTURE.md`](ARCHITECTURE.md) | [`ARCHITECTURE.md` → CR Dependency Chain (Troubleshooting)](ARCHITECTURE.md#cr-dependency-chain-troubleshooting) |
| Regenerated outputs | `api/v1alpha1/zz_generated.deepcopy.go`, `test/api/dataplane-manager/`, `test/mockrepository/` | Do not hand-edit generated files |

## COMMANDS

```bash
make build
make test
make lint
make e2e
make ft
make manifests
make generate
make mock
make swagger-generate-client
make devselfcheck
```

## LOCAL GUARDRAILS

- Dataplane-manager CRDs go through `pkg/repository`; other K8s resources use `pkg/k8s` helpers.
- In task pipelines, mutate task context or the cached CR and keep reconcile writes coordinated; avoid scattered status updates in one loop.
- Deletion is explicit: honor `tidbcloud.com/confirm-deletion` and cleanup paths; do not rely on Kubernetes cascade deletion.
- Do not hand-edit generated deepcopy, swagger client, or mock files.
- Keep provider-specific logic inside the matching `ack/`, `aks/`, or `eks/` task tree unless you have verified a cross-provider abstraction.
- Controllers that create cloud provider resources must preserve API ownership of child `Spec.Tags`. Inherited `DataPlane.Spec.CloudTags` must be included in effective provider tags without mutating API-owned `Spec.Tags`; new provider-resource controllers must include focused tests proving inherited dataplane tags reach cloud resources and have highest precedence.

## RELATED SOURCES

| Document | Purpose |
|----------|---------|
| [`ARCHITECTURE.md`](ARCHITECTURE.md) | CRD hierarchy, task pipelines, cloud mappings, troubleshooting |
| [`../AGENTS.md`](../AGENTS.md) | Parent `internal/` service map |
| [`pkg/controllers/resourcetagger/README.md`](pkg/controllers/resourcetagger/README.md) | ResourceTagger-specific behavior |