--- name: cloudconfig description: | Manage cluster and tenant-init configurations, config changes, templates, parameter attributes, and versions. Covers read, preview, create, apply, and cancel workflows for config changes. --- # Overview This sub-skill operates the **Config Center** (API name: `cloudconfig`) system via the DevOps HTTP API. It covers: - **Cluster Configuration** — read current config and manage config changes for a specific cluster. - **Tenant Init Configuration** — read and manage the default init config for a tenant. - **Config Changes (shared)** — get, apply, or cancel any config change by ID. - **Templates** — list, get, diff config templates; list template changes. - **Default Config** — query global default template bindings and default version rules. - **Parameter Attributes** — list and query parameter definitions (apply policy, default value, validation, risk). - **Versions** — list available component/cluster versions. # Key Concepts ## Product Tiers and Cluster Types TiDB Cloud has the following product tiers: | User-facing name | Internal deploy type | Config Center support | |---|---|---| | Starter | `DEPLOY_TYPE_SERVERLESS` | Not supported | | Essential | `DEPLOY_TYPE_SERVERLESS` | Not supported | | Premium | `DEPLOY_TYPE_NEXTGEN` | Supported — `LOGICAL_CLUSTER` | | BYOC | `DEPLOY_TYPE_NEXTGEN` | Supported — `LOGICAL_CLUSTER` (same as Premium, different region model) | | Dedicated | `DEPLOY_TYPE_DEDICATED` | Supported — `DEDICATED_TIDB` | Additional notes: - **Starter and Essential** are serverless-managed; config changes via this API are not supported. - **Premium and BYOC** are the same from a config change perspective. The tenant-level shared components are called **Resource Pool** in user-facing UIs, but **Shared Pool** (`SHARED_POOL`) in the Config Center API. - When a user refers to a Premium/BYOC **logical cluster instance**, use `cluster_type: LOGICAL_CLUSTER`. When referring to the **shared pool** (Resource Pool), use `cluster_type: SHARED_POOL`. ## ClusterType Valid API values: `DEDICATED_TIDB`, `TICDC`, `CHANGEFEED`, `SHARED_POOL`, `LOGICAL_CLUSTER`, `TICDC_NG`, `CHANGEFEED_NG`. Map from deploy type to `cluster_type`: | Deploy Type | cluster_type | |---|---| | `DEPLOY_TYPE_DEDICATED` | `DEDICATED_TIDB` | | `DEPLOY_TYPE_NEXTGEN` | `LOGICAL_CLUSTER` | | `DEPLOY_TYPE_RESOURCE_POOL` | `SHARED_POOL` | `DEPLOY_TYPE_SERVERLESS` clusters do not support cloudconfig changes via this API. ## ChangeType `change_type` scopes which components and config files a change covers. Use the following rules: - **Config parameter change** (any cluster type): use the full-scope value for that type — `fulltidb` (Dedicated), `logicalcluster` (Premium/BYOC), `sharedpool` (Resource Pool). - **Dedicated cluster upgrade**: use the component being upgraded — `tidb` (main stack), `tiproxy`, or `data-migration`. - `change_type` is required in all create and preview requests. ## ParameterApplyPolicy Valid values: `None`, `HotReload`, `RollingRestart`, `EnsureUpdateToTC`, `NewInstancesOnly`, `ForceRestart`. ## TemplateType Passed as a query parameter when working with templates. Common values: `default`, `tenant_default`. --- # Available Actions ## Cluster Configuration ### Get Cluster Configuration Get the current configuration of a cluster, including component image tags and parameters. API Path: `/cloudconfig/cluster/config` Method: `GET` Query parameters: - `cluster_type` (string, required): cluster type e.g. `DEDICATED_TIDB` - `cluster_id` (string, required): cluster ID ### List Cluster Configuration Changes List configuration changes for a cluster. API Path: `/cloudconfig/cluster/changes` Method: `GET` Query parameters: - `cluster_type` (string, required) - `cluster_id` (string, required) - `page` (integer, optional): default `1` - `per_page` (integer, optional): default `20` - `id_only` (boolean, optional): return only change IDs - `have_modified_param_like` (string, optional): filter by modified parameter name substring ### Create Cluster Configuration Change Create a new configuration change for a cluster. API Path: `/cloudconfig/cluster/changes` Method: `POST` All parameters go in the request body (JSON). There are no query parameters. Required body fields: `cluster_type`, `cluster_id`. Request body schema: ``` { "cluster_type": string (required), "cluster_id": string (required), "reason": string, "apply_policy": ParameterApplyPolicy, "change_type": string, "components": [ { "component": string, "overwrite_image_tag": { "to_image_tag": string } } ], "files": [ { "filename": string, "config_type": string, "previous_text": string, // REQUIRED: the current "text" value from Get Cluster Configuration "custom_parameters": [ { "name": string, "value": any, "comment": string } ], "template": { "to_template": integer } // optional: switch to a different template } ], "version": { "to_version": string } } ``` Notes: - `components`, `files`, and `version` are all optional; include only what needs to change. - `previous_text` is a concurrency guard: the backend rejects the request if the cluster's config has changed since you last read it. Always fetch the current config immediately before submitting the create request — do not reuse a value obtained during an earlier preview step. - `custom_parameters` is a **full replacement** of all custom parameters for that file, not an append. To preserve existing custom parameters, read the current config first and include all parameters with `source: "custom"` alongside any new ones. Returns: `{ "change_id": integer }` ### Preview Cluster Configuration Change Preview what a configuration change would produce before creating it. API Path: `/cloudconfig/cluster/changes/preview` Method: `POST` All parameters go in the request body (JSON). There are no query parameters. Required body fields: `cluster_type`, `cluster_id`. Request body schema: same as Create, minus `reason` and `apply_policy`. --- ## Tenant Init Configuration ### Get Tenant Init Configuration API Path: `/cloudconfig/tenantinit/config` Method: `GET` Query parameters: - `cluster_type` (string, required) - `tenant_id` (string, required): numeric tenant ID as string ### List Tenant Init Images List available component images for a tenant init configuration. API Path: `/cloudconfig/tenantinit/images` Method: `GET` Query parameters: - `cluster_type` (string, required) - `tenant_id` (string, required) ### List Tenant Init Configuration Changes API Path: `/cloudconfig/tenantinit/changes` Method: `GET` Query parameters: - `cluster_type` (string, required) - `tenant_id` (string, required) - `page`, `per_page`, `id_only`, `have_modified_param_like` (optional, same as cluster) ### Preview Tenant Init Configuration Change API Path: `/cloudconfig/tenantinit/changes/preview` Method: `POST` All parameters go in the request body (JSON). There are no query parameters. Required body fields: `cluster_type`, `tenant_id`. Request body schema: same as cluster preview, replacing `cluster_id` with `tenant_id`. ### Create Tenant Init Configuration Change API Path: `/cloudconfig/tenantinit/changes` Method: `POST` All parameters go in the request body (JSON). There are no query parameters. Required body fields: `cluster_type`, `tenant_id`. Request body schema: same as cluster create, replacing `cluster_id` with `tenant_id`. --- ## Config Changes (shared) ### Get Configuration Change Get a config change by ID. API Path: `/cloudconfig/changes/{change_id}` Method: `GET` ### Apply Configuration Change Apply a config change (trigger rollout to clusters). API Path: `/cloudconfig/changes/{change_id}/apply` Method: `POST` The change must be in `approved` phase before apply. Request body must always be provided (use `{}` if no options needed — omitting the body causes a parse error). ```json {} ``` Or with apply method restrictions: ```json { "mode": { "allow_methods": ["HotReload"], "deny_methods": [] } } ``` ### Cancel Configuration Change API Path: `/cloudconfig/changes/{change_id}/cancel` Method: `POST` --- ## Templates ### List Templates API Path: `/cloudconfig/template/templates` Method: `GET` Query parameters: - `cluster_type` (string, required) - `template_type` (string, optional) - `id_in` (string[], optional): comma-separated template IDs - `name_in` (string[], optional): comma-separated template names - `version` (string, optional) - `tenant_id` (string, optional) ### Get Template API Path: `/cloudconfig/template/templates/{template_id}` Method: `GET` Query parameters: - `cluster_type` (string, required) - `with_default_cases` (boolean, optional) ### Diff Template Compare two templates. API Path: `/cloudconfig/template/templates/{template_id}/diff` Method: `GET` Query parameters: - `cluster_type` (string, required) - `target_template_id` (string, required): ID of the template to diff against ### List Configuration Template Changes API Path: `/cloudconfig/template/changes` Method: `GET` Query parameters: - `cluster_type` (string, required) - `template_type` (string, required) - `tenant_id` (string, optional) - `page`, `per_page`, `id_only`, `have_modified_param_like` (optional) --- ## Default Config ### List Template Default Case Bindings API Path: `/cloudconfig/default-config/template-bindings` Method: `GET` Query parameters: - `cluster_type` (string, required) - `config_type_is` (string, optional) - `default_for_version` (string, optional) - `default_for_cloud_provider` (string, optional) - `default_for_instance_type` (string, optional) - `default_for_tenant_id` (string, optional) - `exact_match` (boolean, optional) - `page`, `per_page` (optional) ### List Default Version Rules API Path: `/cloudconfig/default-config/versions/defaultrules` Method: `GET` Query parameters: - `component` (string, optional): filter by component name --- ## Parameter Attributes ### List Parameter Versions API Path: `/cloudconfig/parameter/versions` Method: `GET` Query parameters: - `cluster_type` (string, required) ### List Parameter Attributes API Path: `/cloudconfig/parameter/attribute/{config_type}/{version}` Method: `GET` Query parameters: - `name_like` (string, optional): filter by parameter name substring - `name_in` (string[], optional) - `page`, `per_page` (optional) ### Get Parameter Attribute API Path: `/cloudconfig/parameter/attribute/{config_type}/{version}/{param_name}` Method: `GET` --- ## Versions ### List Available Cluster Versions API Path: `/cloudconfig/versions/cluster/{cluster_type}` Method: `GET` ### List Available Component Versions API Path: `/cloudconfig/versions/component/{component}` Method: `GET` Query parameters: - `cluster_type` (string, optional): default `DEDICATED_TIDB` - `tenant_id` (string, optional) ### List Instance Types API Path: `/cloudconfig/instance-types/{cluster_type}` Method: `GET` Query parameters: - `version` (string, optional) - `config_type` (string, optional) ### List Config Types API Path: `/cloudconfig/config-types/{cluster_type}` Method: `GET` ### List Components API Path: `/cloudconfig/components` Method: `GET` Query parameters: - `cluster_type` (string, required) --- # Workflows ## Config Parameter Change When the user wants to change configuration parameters for a cluster: 1. **Collect required information**: `cluster_type`, `cluster_id` (or `tenant_id`), which parameters to change, and a reason. 2. **Get current config**: Call Get Cluster Configuration to obtain the current `text` for each file you plan to modify. The `text` value is required as `previous_text` in the create request. Also collect all parameters with `source: "custom"` — these must be re-included in `custom_parameters` to avoid being cleared. 3. **Optional — preview first**: Call the preview endpoint to show the user a diff of what will change. 4. **Confirm with user**: Show the intended request body and ask for confirmation before creating. 5. **Create the change**: POST to the appropriate `/changes` endpoint. Returns a `change_id`. 6. **Apply the change**: POST to `/cloudconfig/changes/{change_id}/apply` with body `{}`. The change must be in `approved` phase first. 7. **Return change URL**: `${DEVOPS_BASE_DOMAIN}/confighistories/{change_id}`. ## Hotfix Image Change Use this workflow when the user wants to update a component's image tag only (e.g. apply a patch build), without changing the cluster version or any configuration parameters. ### Step 1: Get current image tags Call Get Cluster Configuration and note the current `effective_image_tag` and `overwrite_image_tag` for each component. ### Step 2: Preview the image change Call Preview Cluster Configuration Change with only `components` — no `version`, no `files`: ```json { "cluster_type": "DEDICATED_TIDB", "cluster_id": "", "components": [ { "component": "tidb", "overwrite_image_tag": { "to_image_tag": "" } } ] } ``` The preview response shows the updated `effective_image_tag` per component. Present this to the user for confirmation. ### Step 3: Create the change Re-fetch Get Cluster Configuration for a fresh `previous_text`, then create the change with only `components`: ```json { "cluster_type": "DEDICATED_TIDB", "cluster_id": "", "reason": "", "apply_policy": "RollingRestart", "components": [ { "component": "tidb", "overwrite_image_tag": { "to_image_tag": "" } } ] } ``` No `version` or `files` needed. After approval, apply via `POST /cloudconfig/changes/{change_id}/apply` with body `{}`. --- ## Cluster Version Upgrade Upgrading a cluster version is a 3-step flow: ### Step 1: Choose target version Call List Available Component Versions to show the user available versions for the component being upgraded (e.g. `tidb`): ``` GET /cloudconfig/versions/component/{component}?cluster_type=DEDICATED_TIDB ``` Ask the user to select a target version. Also check whether the cluster has new-arch TiCDC changefeeds — if it does, warn the user that they must also upgrade the TiCDC clusters separately. ### Step 2: Review and optionally modify component image tags Call Preview Cluster Configuration Change with the target version to show what component images will change: ```json { "cluster_type": "DEDICATED_TIDB", "cluster_id": "", "version": { "to_version": "" }, "change_type": "" } ``` The preview response shows the new `components` map with updated `effective_image_tag` values. Present this to the user; they may optionally override individual image tags by specifying `overwrite_image_tag` in the `components` array. **Special case — upgrading to v8.5.0+**: If the cluster is currently below v8.5.0 and the target is v8.5.0 or above, automatically inject the following TiKV parameter unless it is already set: ``` coprocessor.region-split-size = "96MiB" ``` ### Step 3: Review parameters and create the change Call Preview again with the finalized `components` and any parameter changes and present the full diff to the user for confirmation. Just before submitting the create request, re-fetch Get Cluster Configuration to get a fresh `previous_text` — this guards against concurrent changes made between preview and submit. Once confirmed, create the change: ```json { "cluster_type": "DEDICATED_TIDB", "cluster_id": "", "reason": "", "apply_policy": "RollingRestart", "change_type": "", "version": { "to_version": "" }, "components": [ { "component": "tidb", "overwrite_image_tag": { "to_image_tag": "" } } ], "files": [ { "filename": "tikv", "config_type": "tikv", "previous_text": "", "custom_parameters": [ { "name": "coprocessor.region-split-size", "value": "96MiB" } ] } ] } ``` After the change is approved, apply it via `POST /cloudconfig/changes/{change_id}/apply` with body `{}`.