# Service Deployment Topology

Date: 2026-03-28

## Scope

This document connects three views of the system:

1. deployment objects in `app-delivery`
2. source repositories under `knowledge/repos/*`
3. runtime dependency signals from `service-mapping`

It is not a full one-to-one inventory of every application in `app-delivery`.
Instead, it establishes the main deployment topology and the most important service dependency chains that affect rollout ordering.

Primary evidence sources:

- `~/coding/app-delivery/app-registry/`
- `~/coding/app-delivery/<service>/`
- `knowledge/repos/*/meta.json`
- `knowledge/repos/*/service-mapping/*.json`

Filtered exclusion still applies:

- `tidbcloud/db9-cd`

## Executive Summary

The service deployment topology has five practical layers:

1. platform and infra components
2. configuration and identity foundations
3. global control-plane services
4. regional execution services
5. asynchronous dataflow, CDC, observability, and ops services

The most important topology rule is:

`global services do not stand alone`

They usually depend on one or more regional services for execution, plus shared foundation services for identity, configuration, billing, and infrastructure discovery.

This is especially clear in:

- dedicated flow: `tidb-mgmt-service -> dedicated-global-service -> dedicated-regional-server`
- serverless flow: `tidb-mgmt-service -> serverless-global-service -> serverless-regional-service`
- next-gen/shared-pool flow: `nextgen-global-service` and `cluster-ng-service -> executor/dataplane-manager/config-center`

## Topology Layers

### Layer 1: Platform and Infra Components

Representative deployment objects in `app-delivery`:

- `infra-api-crd`
- `infra-api-providerconfig`
- `infra-api-webhook`
- `infra-webhook`
- `external-secrets-operator`
- `eks-provider`
- `gke-provider`
- `gardener-provider`
- `dedicated-regional-server/crossplane-*`
- `dedicated-regional-server/cert-manager`
- `dedicated-regional-server/aws-load-balancer-controller`

Role:

- establish CRDs, provider configs, secret sync, ingress and certificate capabilities
- provide cloud and Kubernetes control primitives that higher-level services assume already exist

Evidence:

- `~/coding/app-delivery/app-registry/infra-api-crd.yaml`
- `~/coding/app-delivery/dedicated-regional-server/`
- `knowledge/repos/infra-api/meta.json`
- `knowledge/repos/infra-api/service-mapping/cmd-infra-provider.json`

### Layer 2: Configuration and Identity Foundations

Representative deployment objects:

- `config-center`
- `config-center-regional`
- `config-manager`
- `config-service`
- `account-svc`
- `authserver`
- `billing-svc`
- `core-svc`

Role:

- runtime configuration distribution
- identity and permission checks
- core metadata and control APIs
- billing and quota enforcement

Evidence:

- `knowledge/repos/config-center/service-mapping/cmd-server.json`
- `knowledge/repos/config-service/service-mapping/config-service.json`
- `knowledge/repos/account/service-mapping/central-cmd-central.json`
- `knowledge/repos/auth-server/service-mapping/cmd-auth-server.json`
- `knowledge/repos/billing/service-mapping/cmd-server.json`
- `knowledge/repos/core-svc/service-mapping/svc-cmd-server.json`

### Layer 3: Global Control Plane

Representative deployment objects:

- `tidb-mgmt-service`
- `dedicated-global-service`
- `nextgen-global-service`
- `serverless-global-service`
- `serverless-global-regional-proxy`
- `dedicated-metering-server`
- `dataservice-central-svc`
- `dataflow-svc`

Role:

- accept user or internal control-plane requests
- coordinate global metadata
- fan out work to regional executors or domain-specific services

Evidence:

- `knowledge/repos/tidb-management-service/meta.json`
- `knowledge/repos/tidb-management-service/service-mapping/tidb-mgmt-service-cmd-tidb-mgmt-service.json`
- `knowledge/repos/tidb-management-service/service-mapping/dedicated-global-service-cmd-dedicated-global-service.json`
- `knowledge/repos/tidb-management-service/service-mapping/serverless-global-service-cmd-serverless-global-service.json`
- `knowledge/repos/tidb-management-service/service-mapping/nextgen-global-service-cmd-nextgen-global-service.json`

### Layer 4: Regional Execution Plane

Representative deployment objects:

- `dedicated-regional-server`
- `serverless-regional-service`
- `config-center-regional`
- `dedicated-ticdc-service`
- `tcidm-service`
- `dataservice-regional-svc`
- `nextgen-regional-control-plane`
- `o11y-agent-control-server`

Role:

- execute region-scoped control actions
- interact with regional Kubernetes, cloud, network, and dataplane resources
- host region-local APIs and controllers

Evidence:

- `~/coding/app-delivery/dedicated-regional-server/`
- `~/coding/app-delivery/serverless-regional-service/`
- `knowledge/repos/tcidm/service-mapping/cmd-regional_tcidm_service.json`
- `knowledge/repos/config-center/service-mapping/cmd-server.json`

### Layer 5: Async Dataflow, CDC, Observability, and Ops

Representative deployment objects:

- `dedicated-ticdc-service`
- `dataflow-service-ng`
- `serverless-metering`
- `metrics-integration`
- `o11y-svc`
- `devops-service`
- `infra-exporter`
- `quota-exporter`

Role:

- background workers, import/export, CDC, metering, observability, and operator support

Evidence:

- `knowledge/repos/dataflow-service/service-mapping/cmd-dataflow.json`
- `knowledge/repos/dataflow-service/service-mapping/cmd-dataflow-ng.json`
- `knowledge/repos/devops/service-mapping/cmd-devops-server.json`
- `knowledge/repos/metrics-integration/`

## Deployment Object to Source Repo Mapping

The table below focuses on core topology anchors rather than every app-delivery object.

| Deployment object | Most likely source repo | Confidence | Evidence |
| --- | --- | --- | --- |
| `account-svc` | `tidbcloud/account` | High | `knowledge/repos/account/meta.json` and `service-mapping/central-cmd-*.json` |
| `authserver` | `tidbcloud/auth-server` | High | `knowledge/repos/auth-server/meta.json` |
| `auditservice` | `tidbcloud/auditservice` | High | `knowledge/repos/auditservice/meta.json` |
| `billing-svc` | `tidbcloud/billing` | High | `knowledge/repos/billing/meta.json` |
| `config-center` | `tidbcloud/config-center` | High | `knowledge/repos/config-center/meta.json` |
| `config-center-regional` | `tidbcloud/config-center` | High | `config-center` service mapping depends on `config-center-regional` |
| `config-manager` | `tidbcloud/infra-api` | High | `knowledge/repos/infra-api/meta.json` contains binary `config-manager` |
| `config-service` | `tidbcloud/config-service` | High | `knowledge/repos/config-service/meta.json` |
| `core-svc` | `tidbcloud/core-svc` | High | `knowledge/repos/core-svc/meta.json` |
| `tidb-mgmt-service` | `tidbcloud/tidb-management-service` | High | binary `tidb-mgmt-service` |
| `dedicated-global-service` | `tidbcloud/tidb-management-service` | High | binary `dedicated-global-service` |
| `nextgen-global-service` | `tidbcloud/tidb-management-service` | High | binary `nextgen-global-service` |
| `serverless-global-service` | `tidbcloud/tidb-management-service` | High | binary `serverless-global-service` |
| `serverless-global-regional-proxy` / `tempo-proxy` | `tidbcloud/tidb-management-service` | Medium | binaries `regional_proxy` and `tempo-proxy` exist in same repo; naming differs in app-delivery |
| `dataflow-svc` | `tidbcloud/dataflow-service` | High | binary `cmd/dataflow` |
| `dataflow-service-ng` | `tidbcloud/dataflow-service` | High | binary `dataflow-service-ng/cmd/dataflow` |
| `dataservice-central-svc` | `tidbcloud/dataservices` | Medium | central and regioncentral binaries live in same repo; app-delivery splits central vs regional deployment shape |
| `dataservice-regional-svc` | `tidbcloud/dataservices` | Medium | same reason as above |
| `dedicated-ticdc-service` | `tidbcloud/dataflow-service` | Medium | dataflow service mapping references `regional-ticdc-service`; app-delivery package name differs |
| `tcidm-service` | `tidbcloud/tcidm` | High | binary `regional_tcidm_service` |
| `devops-service` | `tidbcloud/devops` | High | binary `devops-server` |
| `cluster-ng-service` | `tidbcloud/cluster-service-ng` | High | binary `cluster_ng_server` |
| `infra-api-webhook` / `infra-api-providerconfig` | `tidbcloud/infra-api` or adjacent infra-provider stack | Medium | same deployment domain, exact binary split not fully represented in KB |

## Main Dependency Chains

### Chain A: Dedicated Cluster Management

Representative flow:

`account/auth/core -> tidb-mgmt-service -> dedicated-global-service -> dedicated-regional-server`

Confirmed signals:

- `tidb-mgmt-service` calls `dedicated-global-service` for dedicated delete/restore/scale flows
- `dedicated-global-service` depends on `regional-server` for create, scale, pause, resume, delete, VPC peering, and private link operations
- `dedicated-global-service` also references account provider, Kafka, MySQL, KMS, PCA, and workflow engine

Deployment implication:

- `dedicated-global-service` should not be treated as deployable in isolation
- its steady-state usefulness depends on regional-server availability and foundational services

Evidence:

- `knowledge/repos/tidb-management-service/service-mapping/tidb-mgmt-service-cmd-tidb-mgmt-service.json`
- `knowledge/repos/tidb-management-service/service-mapping/dedicated-global-service-cmd-dedicated-global-service.json`

### Chain B: Serverless Cluster Management

Representative flow:

`tidb-mgmt-service -> serverless-global-service -> serverless-regional-service`

Confirmed signals:

- `tidb-mgmt-service` calls `serverless-global-service` for serverless create and delete
- `serverless-global-service` calls `serverless-regional-service` for create, update, delete, list, import precheck, DM precheck, private link, DNS, and cloud storage checks
- `serverless-global-service` also depends on `serverless-svc`, `billing`, `account-provider`, and `cluster-proxy`

Deployment implication:

- the serverless global plane sits above multiple specialized domains, not only one regional API
- rollout order should ensure account, billing, proxy, and regional services are already healthy

Evidence:

- `knowledge/repos/tidb-management-service/service-mapping/tidb-mgmt-service-cmd-tidb-mgmt-service.json`
- `knowledge/repos/tidb-management-service/service-mapping/serverless-global-service-cmd-serverless-global-service.json`

### Chain C: Next-Gen / Shared Pool Flow

Representative flow:

`nextgen-global-service -> cluster-ng-service -> executor/dataplane-manager/config-center`

Confirmed signals:

- `nextgen-global-service` depends on `regional-server`, `billing-service`, `dataflow-service`, and KMS
- `cluster_ng_server` depends on:
  - `executor`
  - `dataplane-manager`
  - `cluster-config-center`
- `executor` itself depends on `dataplane-manager`, `cluster-config-center`, and metering

Deployment implication:

- next-gen control paths are more workflow-heavy and configuration-dependent than classic global-only control paths
- `cluster-ng-service` and its executor path are core orchestration dependencies for next-gen resource pool operations

Evidence:

- `knowledge/repos/tidb-management-service/service-mapping/nextgen-global-service-cmd-nextgen-global-service.json`
- `knowledge/repos/cluster-service-ng/service-mapping/cmd-cluster_ng_server.json`
- `knowledge/repos/cluster-service-ng/service-mapping/cmd-executor.json`

### Chain D: Config Distribution

Representative flow:

`oneconfig -> config-center -> config-center-regional -> runtime services`

Confirmed signals:

- `oneconfig` is the runtime config source of truth from earlier deployment analysis
- `config-center` service mapping references `config-center-regional`
- `cluster_ng_server` depends on `cluster-config-center`
- `dataflow-service` depends on `config-center`

Deployment implication:

- configuration is not only an external concern
- many control-plane services rely on config-center or config-service before higher-level business APIs become fully functional

Evidence:

- `knowledge/deployment/deployment-structure-analysis.md`
- `knowledge/repos/config-center/service-mapping/cmd-server.json`
- `knowledge/repos/cluster-service-ng/service-mapping/cmd-cluster_ng_server.json`
- `knowledge/repos/dataflow-service/service-mapping/cmd-dataflow.json`

### Chain E: Data Service Path

Representative flow:

`dataservice-central-svc -> regional gateways/executors`

Confirmed signals:

- `dataservices/cmd/central` depends on `core-svc`, `account-provider`, `infra-api`, and `regional-dataapp-control`
- `dataservices/cmd/dataapi` depends on `account-service`, `core-svc`, and `regional-dataapi-gateway`
- `dataservices/cmd/dataapi-gateway` depends on `dataapi-executor`

Deployment implication:

- dataservices are split across central coordination and regional execution
- central-only rollout is incomplete without regional gateway / executor availability

Evidence:

- `knowledge/repos/dataservices/service-mapping/cmd-central.json`
- `knowledge/repos/dataservices/service-mapping/cmd-dataapi.json`
- `knowledge/repos/dataservices/service-mapping/cmd-dataapi-gateway.json`

## Global vs Regional Deployment Shape

The deployment directory structure in `app-delivery` makes the split visible.

Confirmed facts:

- `dedicated-global-service/envs/{dev,staging,prod}` uses environment-level overlays
- `serverless-global-service/envs/{dev,staging,prod}` does the same
- `serverless-regional-service/envs/*` uses cloud-and-region-specific overlays such as `prod-aws-us-east-1`
- `dedicated-regional-server/` contains many region-specific overlays and region-local platform components
- `dedicated-ticdc-service/ticdc-service/envs/*` is also region-specific

Implication:

- global services are promoted environment by environment
- regional services are promoted region by region inside each environment

Evidence:

- `~/coding/app-delivery/dedicated-global-service/`
- `~/coding/app-delivery/serverless-global-service/`
- `~/coding/app-delivery/serverless-regional-service/`
- `~/coding/app-delivery/dedicated-regional-server/`
- `~/coding/app-delivery/dedicated-ticdc-service/`

## Recommended Deployment Ordering

This is a recommended high-level order derived from deployment structure plus service dependencies.

### Phase 0: Cluster and Platform Registration

- regional cluster exists and is registered into ArgoCD
- infra provider configs, CRDs, webhook, secret store, cert-manager, load-balancer controller, and crossplane components are ready

Main owners:

- `auto-deploy`
- `app-delivery` regional base components
- `infra-cd` where required

### Phase 1: Configuration and Identity Base

- `config-center`
- `config-center-regional`
- `config-manager`
- `config-service`
- `account-svc`
- `authserver`
- `core-svc`
- `billing-svc`

Reason:

- most higher-level control-plane services read config, authenticate users, enforce permissions, or consume billing/account context

### Phase 2: Global Control Plane

- `tidb-mgmt-service`
- `dedicated-global-service`
- `nextgen-global-service`
- `serverless-global-service`
- `serverless-global-regional-proxy`
- central dataservices

Reason:

- these coordinate user-facing orchestration but delegate real execution downward

### Phase 3: Regional Execution Plane

- `dedicated-regional-server`
- `serverless-regional-service`
- `tcidm-service`
- `dedicated-ticdc-service`
- `dataservice-regional-svc`
- region-local config-center and o11y control components

Reason:

- these perform region-scoped actions required by global APIs

### Phase 4: Dataflow, CDC, Metering, and Ops

- `dataflow-svc`
- `dataflow-service-ng`
- `serverless-metering`
- `metrics-integration`
- `devops-service`
- exporters and o11y services

Reason:

- these are often background or asynchronous dependencies and may depend on earlier layers being stable

## Gaps and Confidence

### High Confidence Areas

- the global vs regional split
- the core dedicated / serverless / next-gen dependency chains
- the role of config-center and core identity foundations
- the fact that many global services delegate execution to regional services

### Medium Confidence Areas

- exact source-repo mapping for some app-delivery objects whose deployment names differ from source repo or binary names
- complete coverage for all observability, provider, and auxiliary applications
- exact deployment order inside the regional base component set

### Why Coverage Is Partial

- `app-delivery` contains more deployment objects than the currently deep-scanned repo set can fully explain
- some application names are deployment-package names rather than source-repo names
- some repos expose multiple binaries that app-delivery splits into separate deployment units

## Key Conclusions

1. The most important deployment topology boundary is `global vs regional`, not `repo vs repo`.
2. `tidb-mgmt-service` is an entry coordinator, not the final executor.
3. `dedicated-global-service`, `serverless-global-service`, and `nextgen-global-service` are orchestration services that rely on regional execution planes.
4. `config-center`, `account`, `auth`, `core`, and `billing` are foundational and should be treated as early-layer dependencies.
5. `app-delivery` deploy order should follow service topology, not just folder order or PR order.

## Evidence Index

- `~/coding/app-delivery/app-registry/`
- `~/coding/app-delivery/dedicated-global-service/`
- `~/coding/app-delivery/dedicated-regional-server/`
- `~/coding/app-delivery/serverless-global-service/`
- `~/coding/app-delivery/serverless-regional-service/`
- `~/coding/app-delivery/dedicated-ticdc-service/`
- `knowledge/repos/tidb-management-service/meta.json`
- `knowledge/repos/tidb-management-service/service-mapping/tidb-mgmt-service-cmd-tidb-mgmt-service.json`
- `knowledge/repos/tidb-management-service/service-mapping/dedicated-global-service-cmd-dedicated-global-service.json`
- `knowledge/repos/tidb-management-service/service-mapping/serverless-global-service-cmd-serverless-global-service.json`
- `knowledge/repos/tidb-management-service/service-mapping/nextgen-global-service-cmd-nextgen-global-service.json`
- `knowledge/repos/cluster-service-ng/meta.json`
- `knowledge/repos/cluster-service-ng/service-mapping/cmd-cluster_ng_server.json`
- `knowledge/repos/cluster-service-ng/service-mapping/cmd-executor.json`
- `knowledge/repos/config-center/meta.json`
- `knowledge/repos/config-center/service-mapping/cmd-server.json`
- `knowledge/repos/config-service/meta.json`
- `knowledge/repos/account/meta.json`
- `knowledge/repos/account/service-mapping/central-cmd-central.json`
- `knowledge/repos/auth-server/meta.json`
- `knowledge/repos/auth-server/service-mapping/cmd-auth-server.json`
- `knowledge/repos/billing/meta.json`
- `knowledge/repos/billing/service-mapping/cmd-server.json`
- `knowledge/repos/core-svc/meta.json`
- `knowledge/repos/core-svc/service-mapping/svc-cmd-server.json`
- `knowledge/repos/dataservices/meta.json`
- `knowledge/repos/dataservices/service-mapping/cmd-central.json`
- `knowledge/repos/dataservices/service-mapping/cmd-dataapi.json`
- `knowledge/repos/dataservices/service-mapping/cmd-dataapi-gateway.json`
- `knowledge/repos/dataflow-service/meta.json`
- `knowledge/repos/dataflow-service/service-mapping/cmd-dataflow.json`
- `knowledge/repos/dataflow-service/service-mapping/cmd-dataflow-ng.json`
- `knowledge/repos/tcidm/meta.json`
- `knowledge/repos/tcidm/service-mapping/cmd-regional_tcidm_service.json`
- `knowledge/repos/infra-api/meta.json`