Skip to content

docs: add FAQ on TiDB X and Dedicated Projects, detailing changes and… #22656

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
awxxxxxx wants to merge 2 commits into
base: feature/preview-one-console
Choose a base branch
from
+68 −0
Open

docs: add FAQ on TiDB X and Dedicated Projects, detailing changes and… #22656

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
210c056
docs: add FAQ on TiDB X and Dedicated Projects, detailing changes and…
awxxxxxx Mar 31, 2026
c50d6d6
docs: address review comments for TiDB X project FAQ
awxxxxxx Mar 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions tidb-cloud/tidbx-instance-move-faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# TiDB X Project and Dedicated Project: what changed and why instances need to move

## What changed

TiDB Cloud introduces **typed projects** to provide a clearer separation between different product tiers. Projects are classified into two distinct types:

- **TiDB X Project** — designed for TiDB Cloud X instances (Starter, Essential, Premium)

Check failure on line 7 in tidb-cloud/tidbx-instance-move-faq.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.EmDash] Don't put a space before or after a dash.

Raw Output:
{"message": "[PingCAP.EmDash] Don't put a space before or after a dash.", "location": {"path": "tidb-cloud/tidbx-instance-move-faq.md", "range": {"start": {"line": 7, "column": 21}}}, "severity": "ERROR"}
- **Dedicated Project** — designed for TiDB Cloud Dedicated clusters

Check failure on line 8 in tidb-cloud/tidbx-instance-move-faq.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.EmDash] Don't put a space before or after a dash.

Raw Output:
{"message": "[PingCAP.EmDash] Don't put a space before or after a dash.", "location": {"path": "tidb-cloud/tidbx-instance-move-faq.md", "range": {"start": {"line": 8, "column": 24}}}, "severity": "ERROR"}

Each project type can **only host its own resource type**:

- A TiDB X Project can only contain TiDB X instances.
- A Dedicated Project can only contain Dedicated clusters.

This typed project model maintains a consistent **Organization → Project → Resource** hierarchy across all tiers, while allowing each product line to evolve with its own project behavior and capabilities.

## Why two project types

TiDB X Projects and Dedicated Projects serve different use cases and have different characteristics:

| Capability | TiDB X Project | Dedicated Project |
|---|---|---|
| Project Settings | ❌ | ✅ |
| Project-level RBAC | ✅ | ✅ |
| Billing Aggregation | ✅ | ✅ |
| Move instances between projects | ✅ | ❌ |
| Project is optional | ✅ (instances can exist at the organization level) | ❌ (clusters must belong to a project) |
| Resource type | TiDB X instances only | Dedicated clusters only |

### TiDB X Project

- **Lightweight and optional**. You can create TiDB X instances without assigning them to a project. Projects are useful when you want to organize and group resources, but they are not required.
- **Instance mobility**. You can move TiDB X instances between TiDB X Projects or back to the organization level, giving you flexibility in how you organize your resources.

### Dedicated Project

- **Mandatory project membership**. Every Dedicated cluster must belong to a Dedicated Project.
- **No instance mobility across projects**. Dedicated clusters cannot be moved between projects due to their infrastructure bindings.

## Why instances need to move

Before this change, a single project could contain both Dedicated clusters and TiDB X instances (Starter, Essential). With the introduction of typed projects, this mixed state is no longer supported.

**If your Dedicated Project currently contains TiDB X instances (Starter or Essential), you need to move those instances out.**

This is because:

1. **Each project type now exclusively hosts its own resource type.** A Dedicated Project can only contain Dedicated clusters, and a TiDB X Project can only contain TiDB X instances.
2. **TiDB X instances and Dedicated clusters have different project behaviors.** TiDB X instances benefit from lightweight, optional project membership and instance mobility — capabilities that do not apply within a Dedicated Project.

Check failure on line 49 in tidb-cloud/tidbx-instance-move-faq.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.EmDash] Don't put a space before or after a dash.

Raw Output:
{"message": "[PingCAP.EmDash] Don't put a space before or after a dash.", "location": {"path": "tidb-cloud/tidbx-instance-move-faq.md", "range": {"start": {"line": 49, "column": 174}}}, "severity": "ERROR"}
3. **Keeping them separated ensures a consistent experience.** When you interact with a Dedicated Project, you expect Dedicated-specific settings and behaviors. Mixing resource types would create confusion around which capabilities apply.

## What happens when you move instances

When you move TiDB X instances out of a Dedicated Project:

- TiDB Cloud moves the instances to a **TiDB X Project**.
- No data or service disruption occurs. This is a resource re-organization action, not an infrastructure change.
- After the move, you manage your TiDB X instances through TiDB X Projects (or at the organization level), and you continue to manage your Dedicated clusters through Dedicated Projects.

## Summary

| Before | After |
|---|---|
| A single project could contain both Dedicated clusters and TiDB X instances | Each project type exclusively hosts its own resource type |
| TiDB X instances in Dedicated Projects inherited Dedicated project behaviors | TiDB X instances are managed in TiDB X Projects with their own lightweight model |
| No distinction between project types | Clear separation: TiDB X Project vs Dedicated Project |

This change gives each product tier a project model that fits its own needs, while keeping the overall organization structure consistent and predictable.
Loading