# ACS Bumper User Guide

This guide is for engineers using ACS Bumper in their daily TiDB Cloud delivery work. It covers: viewing region status, generating safe change previews, and creating controlled-change Pull Requests.

> **ACS Bumper never directly modifies the production environment.** All change workflows operate on the local `app-delivery` repository: creating branches, committing changes, pushing branches, and opening GitHub Pull Requests. Pull Requests still follow the team's normal review and merge process.

## Scope

| Task | Feature | Result |
|---|---|---|
| View current component versions across regions | Dashboard / Regions | Read-only view |
| Upgrade ACS, Vector, or VMagent image tags in selected regions | Image Bump | `app-delivery` Pull Request |
| Sync supported `config.yaml` changes from a source region to target regions | Config Sync | `app-delivery` Pull Request |
| Sync supported `deployment.yaml` changes from a source region to target regions | Deployment Sync | `app-delivery` Pull Request |

## Prerequisites

Before using ACS Bumper, ensure your machine meets the following requirements:

- **Node.js 20+**: Runtime environment
- **Local `app-delivery` repository**: Cloned to your machine
- **GitHub CLI authenticated**: Run `gh auth status` to confirm login state
- **Repository permissions**: Branch push and Pull Request creation access on `tidbcloud/app-delivery`
- **Clean working tree**: The `app-delivery` repository must have no uncommitted changes before running any change workflow

Create `.env.local` in the ACS Bumper repository root:

```bash
APP_DELIVERY_REPO_PATH=/your/absolute/path/to/app-delivery
GITHUB_REPO=tidbcloud/app-delivery
```

`GITHUB_REPO` is optional, defaults to `tidbcloud/app-delivery`.

## Starting the Application

Install dependencies and start the development server:

```bash
npm install
npm run dev
```

After startup, visit:

```text
http://localhost:3210
```

## Operating Principles

All write workflows follow the **preview-first, then execute** principle:

1. Select the operation type, source data, and target regions.
2. Click **Preview Changes** to generate a preview.
3. Carefully review the generated Pull Request metadata and file-level diffs.
4. After confirming the preview meets expectations, click **Confirm & Create PR** to submit.

Before creating a Pull Request, verify each item:

- The `app-delivery` working tree is clean.
- The target region list matches the intended release scope.
- The image tag or source region selection is correct.
- The preview diff contains only expected changes — no unintended modifications.

## Dashboard

The Dashboard shows a status overview of the current `app-delivery` repository.

![dashboard.png](./images/dashboard.png)

**Available information:**

- Current `app-delivery` branch
- Working tree status: `Clean` or `Dirty`
- Region count by architecture: Dedicated, NextGen, Serverless, BYOC
- Version distribution of ACS, Vector, and VMagent across environments

**Recommendations:**

- **Do not** run change workflows when the repository status is `Dirty`.
- Use version distribution cards to confirm whether rollouts have covered the intended environments.
- If the repository status information appears stale, sync the `app-delivery` main branch and refresh the page.

## Regions

The Regions page is the only entry point for choosing target regions. Image Bump, Config Sync, and Deployment Sync receive this fixed target set from the Regions page; use **Change targets** to return here if the target set needs adjustment.

**Supported filters:**

- **Text search**: Region name, directory path, provider, or current tag
- **Architecture**: `dedicated`, `nextgen`, `serverless`, `byoc`
- **Environment**: `dev`, `staging`, `prod`
- **Provider**: `aws`, `gcp`, `azure`, `alicloud`
- **Gray release**: Built-in production gray release presets for NextGen, Serverless, Dedicated, and BYOC regions
- **Component tag**: ACS, Vector, VMagent

Before selecting regions, confirm:

- `Environment` matches the intended release stage.
- `Architecture` matches the intended region type.
- `Provider` matches the target cloud vendor.

### Updating Gray Release Presets

Gray release presets are maintained in `config/gray-release.json`. Update the `regionIds` list under the matching preset:

- `nextgen`: NextGen regions
- `serverless`: Serverless regions
- `dedicated`: Dedicated regions
- `byoc`: BYOC regions

Use the full region ID from the Regions page/API, not only the directory name. The scanner format is:

```text
<architecture>:<provider>:<environment>:<directory-name>
```

Examples:

```text
nextgen:aws:prod:prod-aws-ap-south-1-ng
serverless:aws:prod:prod-aws-us-west-2-f02
dedicated:aws:prod:aws-prod-ap-east-1
byoc:aws:prod:prod-aws-byoc-usw2-mithra
```

After editing the file, refresh the Regions page and open **Gray Release**. Each preset shows `matched/total`; if the matched count is `0`, the region ID does not match the scanned region list or is hidden by the current filters.

## Image Bump

Image Bump is used to batch update ACS, Vector, or VMagent image tags in selected regions.

### Workflow

1. **Select target regions.** Check the regions to upgrade on the Regions page.

    ![image-bump-0.png](./images/image-bump-0.png)

2. **Select component.** Choose `ACS`, `Vector`, or `VMagent` (ACS shown as example). The target regions are shown as a read-only summary and list.

    ![image-bump-1.png](./images/image-bump-1.png)

3. **Enter target image tag.** Optionally choose whether to update template files in variant directories.

    ![image-bump-2.png](./images/image-bump-2.png)

4. **Preview changes.** Click **Preview Changes**. Optionally enable image version checking.

    ![image-bump-3.png](./images/image-bump-3.png)

5. **Confirm and create PR.** After verifying the preview, click **Confirm & Create PR**.

    ![image-bump-4.png](./images/image-bump-4.png)

6. **View image check Action.** An image check is triggered after PR creation.

    ![image-bump-5.png](./images/image-bump-5.png)

7. **View final PR.** Confirm the PR content and diff meet expectations.

    ![image-bump-6.png](./images/image-bump-6.png)

### Preview Checklist

Before confirming, verify each item:

- **Target**: The exact image tag to apply.
- **Regions**: Only includes intended targets.
- **File diffs**: Only replaces the expected image tag values.

### Section Policies for Vector and VMagent

Vector and VMagent upgrades support scoping changes by section. Available sections are determined by both component type and region architecture.

| Component | Dedicated | NextGen / Serverless / BYOC |
|---|---|---|
| Vector | `k8s`, `tidbcluster` | `k8s`, `sharedpool`, `tidbgroup` |
| VMagent | `k8s`, `tidbcluster` | `k8s`, `sharedpool` |

## Config Sync

Config Sync propagates verified `config.yaml` changes from a source region to one or more target regions at the YAML path level.

**Typical scenario:** A configuration change has been verified in one region and now needs to be applied to comparable target regions with the same semantics.

### Workflow

1. **Prepare source region changes.** Ensure the source region's `config.yaml` contains the intended diff. The following example changes `promscrape.maxScrapeSize` from `64MiB` to `128MiB`.

    ```shell
    diff --git a/dev/nextgen-regional-control-plane/o11y-agent-control-server/envs/dev-aws-us-east-1-ng/config.yaml b/dev/nextgen-regional-control-plane/o11y-agent-control-server/envs/dev-aws-us-east-1-ng/config.yaml
    index baa84a6c83..367c7e03bb 100644
    --- a/dev/nextgen-regional-control-plane/o11y-agent-control-server/envs/dev-aws-us-east-1-ng/config.yaml
    +++ b/dev/nextgen-regional-control-plane/o11y-agent-control-server/envs/dev-aws-us-east-1-ng/config.yaml
    @@ -104,7 +104,7 @@ o11yConfig:
                   promscrape.config.strictParse: "false"
                   promscrape.suppressDuplicateScrapeTargetErrors: "true"
                   promscrape.streamParse: "true"
    -              promscrape.maxScrapeSize: 64MiB
    +              promscrape.maxScrapeSize: 128MiB
                 statefulStorage:
                   volumeClaimTemplate:
                     spec:
    ```

2. **Select target regions.** Check the regions to sync on the Regions page. The sync workflow receives these targets as a fixed set.

    ![config-sync-1.png](./images/config-sync-1.png)

3. **Specify source region.** Select the region containing the verified changes as the sync source. The source can be any discovered region; if it is also in the target set, ACS Bumper excludes it from sync targets.

    ![config-sync-2.png](./images/config-sync-2.png)

4. **Preview changes.** Click **Preview Changes** to view the sync diff for each target.

    ![config-sync-3.png](./images/config-sync-3.png)

5. **Confirm and create PR.** After verifying all target diffs are correct, click **Confirm & Create PR**.

    ![config-sync-4.png](./images/config-sync-4.png)

6. **Review PR changes.** Confirm the diff in each PR file meets expectations.

    ![config-sync-5.png](./images/config-sync-5.png)

7. **Review PR Summary.** Confirm the auto-generated summary is accurate.

    ![config-sync-6.png](./images/config-sync-6.png)

### Source Region Requirements

ACS Bumper automatically checks the source region status before previewing. The following conditions will block the preview:

- The source region has no supported changes.
- The source file is missing.
- The change requires value type modification, or adding a new key where the parent path does not exist in the target / the target already has a different value.

### Preview Checklist

Before confirming, verify each item:

- **Source region**: Correctly selected.
- **Target regions**: Complete list. If the selected source is also in the list, it is excluded from execution.
- **Diff paths**: Each changed path meets expectations.
- **`oldValue` / `newValue`**: Match the intended configuration sync content.
- **Failed targets**: No failures in the preview.

### Sync Semantics

Config Sync is **path-level YAML sync**, not whole-file copy. Current constraints:

- Only syncs paths that changed in the source region — does not overwrite the entire `config.yaml` file.
- Preserves existing YAML formatting, comments, and unrelated settings.
- Allows adding new object keys, but requires the parent path to exist in the target; if the target already has the same key with a different value, that target will fail.
- Key deletion is not allowed.
- Type changes are not allowed.

These constraints are designed to reduce the risk of inadvertently propagating unrelated configuration from the source region to other regions.

## Deployment Sync

Deployment Sync propagates verified `deployment.yaml` changes from a source region to one or more target regions at the YAML path level.

**Typical scenario:** A deployment-level change has been verified in one region and now needs to be applied to comparable target regions.

### Workflow

Same as the [Config Sync](#config-sync) workflow.

### Comparison with Config Sync

| Item | Config Sync | Deployment Sync |
|---|---|---|
| Target file | `config.yaml` | `deployment.yaml` |
| Primary use | Sync configuration values | Sync deployment settings |
| Workflow | Preview-first, then execute | Preview-first, then execute |
| Safety controls | Preview token + hash verification | Preview token + hash verification |

### Image Tag Check

If the source deployment diff includes an ACS image tag change, the Preview stage optionally enables image tag checking.

If no ACS image tag change is detected, ACS Bumper will indicate that image tag checking will be skipped.

## Operation History

Operation History displays historical Image Bump Pull Requests discovered via the GitHub API.

**Use cases:**

- View past ACS, Vector, or VMagent bump PRs.
- Check PR status, author, title, and creation date.
- Quickly open historical PRs for reference.

If the list is empty, confirm:

- `gh auth status` shows successful authentication.
- Your GitHub account has access to the `app-delivery` repository.
- Your network can reach GitHub.