# TiDB Configuration of TiDB Cloud

This repository controls the configurations (including version, component configurations) of TiDB clusters on TiDB Cluster. See [Overview](#overview) to understand the repository structure, follow [change process](#change-process) to propose a change, see [examples](#examples) to get useful usage guides.

## Overview

```
// overlay process the layered configuration file tree the file tree assumed to be the following format
//  .
// ├── tenants
// │   └── tenant-1270613000524402688
// │       ├── clusters
// │       │   └── cluster-1270613313241
// │       │       ├── tikv.toml      # cluster config overlays, optional
// │       │       └── meta.yaml      # cluster’s meta, optional
// │       ├── tikv.toml              # tenant config overlays, optional
// │       └── meta.yaml              # tenant’s default meta, optional
// ├── versions                       # must include all supported versions, required
// │   └── v4.0.9                     # base config of v4.0.9, required
// │       ├── base
// │       │   ├── backup.yaml
// │       │   ├── restore.yaml
// │       │   ├── pd.toml
// │       │   ├── tidb.toml
// │       │   ├── tiflash.toml
// │       │   ├── tikv.toml
// │       │   └── meta.yaml
// │       └── instances               # instance overlays, optional
// │           ├── aws.m5.2xlarge
// │           │   └── tikv.toml       # tuning for instance type `aws.m5.2xlarge`
// │           └── gcp.n2-standard-8
// │               └── tikv.toml       # tuning for instance type `gcp.n2-standard-8`
// └── meta.yaml                       # Global default meta, required
```

## Change Process

### Change Global Defaults

1. checkout your <feature> branch from `master`
2. local development
3. file a pull request to `master`
4. make sure the CI passed
5. merge PR to master, evaluate the change in dev environment
6. cherry-pick the change to `staging`
7. cherry-pick the change to `prod`

### Change Tenant/Cluster Overlays

1. checkout your <feature> branch from the env branch the tenant/cluster located, e.g. `prod` branch
2. local development
3. file a pull request to the target env branch
4. merge PR to the env branch

## Examples

### Update global configuration

Edit the configurations under `versions` directory and the global defaults will be updated.

### Choose the policy of updating

Currently, the following update policy is supported:
- Dryrun: output the update plan in the log of `config-service`, but do **NOT** perform actual update;
- Immediate: update the target cluster(s) immediately after the current operation on the cluster(s) is done.

The default value is `Dryrun`, policy can be controlled in `meta.yaml` at global/tenant/cluster level.

### Add a new version

Add a directory under `versions` and:

- Add the configurations of each component
- Add the machine overlays for components that need to be tuned for specific machines

### Add a new instance overlay

Some components need to be tuned for specific instance attributes (e.g. machine type), such configurations can be declared in `instance overlay`. To add 
a `instance overlay` for a specific version, add a `${instanceName}` folder under `versions/${version}/instances` directory and add the overlay configurations under that folder.

### Update global version

Edit the `meta.yaml` under root directory and the global version will be updated, the version must be exist
in the `verisons` directory.

### Update config/version of a special tenant

Create or find the tenant directory under `./tenants`, the tenant directory should be named as `tenant-${tenantID}`,
create or find the configuration file to edit.

### Update config/version of a special cluster

Create or find the cluster directory under `./tenants/tenant-${tenantID}/clusters/`, 
the cluster directory should be named as `cluster-${clusterID}`, create or find the configuration file to edit.

**NOTE**: cluster specified configuration will **NOT** be inherited by the clusters that are restored from the target cluster.
If you also want to alter the configuration of clusters that restored in the future, alter the tenant's configuration.

### Canary release

1. Update the global policy to `Dryrun`
2. Edit configuration
3. Enable update for the canary tenant/cluster
4. Expand the canary coverage.
5. Update the global policy to `Immediate` to complete canary.

### Update global defaults without affecting special tenant/cluster

There are two options to accomplish this:

- Edit the global defaults and set the `updatePolicy` of the special `tenant/cluster` to `Dryrun`
- Edit the global defaults as above, and edit the tenant/cluster configuration to make sure the rendered manifest
of that tenant/cluster is unchanged.