update log backup user docs

.markdownlint.yaml

@@ -1,97 +1,126 @@
 comment: 'Rules for PingCAP docs-tidb-operator'
 
 # disable all by default
+
 default: false
 
 # MD001
+
 heading-increment: true
 
 # MD003
+
 heading-style:
   style: atx
 
 # MD009
+
 # no-trailing-spaces: true
 
 # MD010
+
 no-hard-tabs: true
 
 # MD007
+
 ul-indent:
   indent: 4
 
 # MD012
+
 no-multiple-blanks: true
 
 # commands-show-output: true
 
 # MD018
+
 no-missing-space-atx: true
 
 # MD019
+
 no-multiple-space-atx: true
 
 # MD022
+
 blanks-around-headings: true
 
 # MD023
+
 heading-start-left: true
 
 # MD024
+
 no-duplicate-heading:
   siblings_only: true
 
 # MD025
+
 single-title:
   front_matter_title: ''
 
 # MD026
+
 no-trailing-punctuation:
   punctuation: '.,;:!。，；：！'
 
 # MD027
+
 no-multiple-space-blockquote: true
 
 # MD029
+
 ol-prefix:
   style: ordered
 
 # MD030
+
 list-marker-space: true
 
 # MD031
+
 blanks-around-fences: true
 
 # MD032
+
 blanks-around-lists: true
 
 # MD034
+
 no-bare-urls: true
 
 # MD037
+
 no-space-in-emphasis: true
 
 # MD038
+
 no-space-in-code: true
 
 # MD039
+
 no-space-in-links: true
 
 # MD042
+
 no-empty-links: true
 
-# proper-names:
-#   names: ['TiDB', 'TiKV', 'PingCAP']
-#   code_blocks: false
+# proper-names
+
+# names: ['TiDB', 'TiKV', 'PingCAP']
+
+# code_blocks: false
 
 # MD045
+
 no-alt-text: true
 
 # MD046
+
 code-block-style:
   style: fenced
 
 # single-trailing-newline: true
 
 # MD041
+
 first-line-heading: true

en/backup-restore-cr.md

@@ -36,6 +36,11 @@ This section introduces the fields in the `Backup` CR.
     * `volume-snapshot`: back up data by volume snapshots.
     * `log`: back up log data in real time in the KV layer.
 
+* `.spec.logSubcommand`: the subcommand for controlling the log backup status in the Backup CR. This field provides three options for managing a log backup task:
+    * `log-start`: Initiates a new log backup task or resumes an existing task that has been paused. Use this option to start the log backup process or to continue it from a paused state.
+    * `log-pause`: Temporarily pauses an active log backup task, allowing it to be resumed later using the log-start command.
+    * `log-stop`: Permanently stops the log backup task. When this command is issued, the Backup CR enters a stopped state and cannot be restarted.
+
 * `.spec.restoreMode`: the restore mode. The default value is `snapshot`, which means restoring data from snapshots in the KV layer. This field is valid only for restore and has three value options currently:
     * `snapshot`: restore data from snapshots in the KV layer.
     * `volume-snapshot`: restore data from volume snapshots.

en/backup-restore-overview.md

@@ -78,6 +78,8 @@ kubectl delete backupschedule ${name} -n ${namespace}
 
 If you use TiDB Operator v1.1.2 or an earlier version, or if you use TiDB Operator v1.1.3 or a later version and set the value of `spec.cleanPolicy` to `Delete`, TiDB Operator cleans the backup data when it deletes the CR.
 
+If you are using version 1.5.5+ or 1.6.1+, when you delete a CR, TiDB Operator will attempt to automatically stop the running log backup task. The auto-stop feature will only stop log backup tasks that are running on track; it does not handle tasks that are in an error or failed state.
+
 If you back up cluster data using AWS EBS volume snapshots and set the value of `spec.cleanPolicy` to `Delete`, TiDB Operator deletes the CR, and cleans up the backup file and the volume snapshots on AWS.
 
 In such cases, if you need to delete the namespace, it is recommended that you first delete all the `Backup`/`BackupSchedule` CRs and then delete the namespace.

en/backup-to-aws-s3-using-br.md

@@ -228,6 +228,24 @@ demo1-full-backup-s3   full   snapshot   Complete   s3://my-bucket/my-full-backu
 
 You can use a `Backup` CR to describe the start and stop of a log backup task and manage the log backup data. Log backup grants permissions to remote storages in the same way as snapshot backup. In this section, the example shows log backup operations by taking a `Backup` CR named `demo1-log-backup-s3` as an example. Note that these operations assume that permissions to remote storages are granted using accessKey and secretKey. See the following detailed steps.
 
+#### Log backup subcommands
+
+The logSubcommand field in the Backup CR allows you to control the status of a log backup task. There are three valid inputs for logSubcommand:
+
+ • log-start: This command initiates a new log backup task or resumes an existing task that has been paused. It can be used to start the log backup process or resume from the paused state.
+
+ • log-pause: This command temporarily pauses an active log backup task. The task can be resumed later using the log-start command.
+
+ • log-stop: This command permanently stops the log backup task. When this command is issued, the Backup CR enters a stopped state and cannot be restarted.
+
+These commands allow fine-grained control over the lifecycle of log backup tasks, enabling start, pause, resume, and stop operations to manage log data retention in a Kubernetes environment.
+
+<Tip>
+In v1.5.5 and earlier TiDB Operator versions, you could use the logStop: true/false field to stop or start a task. This field is retained for backward compatibility.
+
+However, you must not mix logStop with logSubcommand in the same YAML file. Doing so is unsupported, and using logStop is not recommended in later versions. Stick to logSubcommand for better clarity and consistency.
+</Tip>
+
 #### Start log backup
 
 1. In the `backup-test` namespace, create a `Backup` CR named `demo1-log-backup-s3`.
@@ -247,6 +265,7 @@ You can use a `Backup` CR to describe the start and stop of a log backup task an
       namespace: backup-test
     spec:
       backupMode: log
+      logSubcommand: log-start
       br:
         cluster: demo1
         clusterNamespace: test1
@@ -308,15 +327,101 @@ Conditions:
 Log Checkpoint Ts:       436569119308644661
 ```
 
+#### Pause log backup
+
+Because you already created a `Backup` CR named `demo1-log-backup-s3` when you started log backup, you can pause the log backup by modifying the same `Backup` CR.
+
+```shell
+kubectl edit backup demo1-log-backup-s3 -n backup-test
+```
+
+To pause the log backup task, you only need to change the `logSubcommand` from `log-start` to `log-pause`. Then save and quit the editor. The modified content is as follows:
+
+```yaml
+---
+apiVersion: pingcap.com/v1alpha1
+kind: Backup
+metadata:
+  name: demo1-log-backup-s3
+  namespace: backup-test
+spec:
+  backupMode: log
+  logSubcommand: log-pause
+  br:
+    cluster: demo1
+    clusterNamespace: test1
+    sendCredToTikv: true
+  s3:
+    provider: aws
+    secretName: s3-secret
+    region: us-west-1
+    bucket: my-bucket
+    prefix: my-log-backup-folder
+```
+
+You can see the `STATUS` of the `Backup` CR named `demo1-log-backup-s3` change from `Running` to `Pause`:
+
+```shell
+kubectl get backup -n backup-test
+```
+
+```
+NAME                       MODE     STATUS    ....
+demo1-log-backup-s3        log      Pause     ....
+```
+
+#### Resume log backup
+
+If a log backup task is paused, you could set `logSubcommand: log-start` to resume it. Be aware that, you couldn't resume a task from `Fail` or `Stopped` state.
+
+```shell
+kubectl edit backup demo1-log-backup-s3 -n backup-test
+```
+
+To resume the log backup task, you only need to change the `logSubcommand` from `log-pause` to `log-start`. Then save and quit the editor. The modified content is as follows:
+
+```yaml
+---
+apiVersion: pingcap.com/v1alpha1
+kind: Backup
+metadata:
+  name: demo1-log-backup-s3
+  namespace: backup-test
+spec:
+  backupMode: log
+  logSubcommand: log-start
+  br:
+    cluster: demo1
+    clusterNamespace: test1
+    sendCredToTikv: true
+  s3:
+    provider: aws
+    secretName: s3-secret
+    region: us-west-1
+    bucket: my-bucket
+    prefix: my-log-backup-folder
+```
+
+You can see the `STATUS` of the `Backup` CR named `demo1-log-backup-s3` change from `Running` to `Pause`:
+
+```shell
+kubectl get backup -n backup-test
+```
+
+```
+NAME                       MODE     STATUS    ....
+demo1-log-backup-s3        log      Running   ....
+```
+
 #### Stop log backup
 
-Because you already created a `Backup` CR named `demo1-log-backup-s3` when you started log backup, you can stop the log backup by modifying the same `Backup` CR. The priority of all operations is: stop log backup > delete log backup data > start log backup.
+Because you already created a `Backup` CR named `demo1-log-backup-s3` when you started log backup, you can stop the log backup by modifying the same `Backup` CR.
 
 ```shell
 kubectl edit backup demo1-log-backup-s3 -n backup-test
 ```
 
-In the last line of the CR, append `spec.logStop: true`. Then save and quit the editor. The modified content is as follows:
+Change the `logSubcommand` to `log-stop`. Then save and quit the editor. The modified content is as follows:
 
 ```yaml
 ---
@@ -327,6 +432,7 @@ metadata:
   namespace: backup-test
 spec:
   backupMode: log
+  logSubcommand: log-stop
   br:
     cluster: demo1
     clusterNamespace: test1
@@ -337,7 +443,6 @@ spec:
     region: us-west-1
     bucket: my-bucket
     prefix: my-log-backup-folder
-  logStop: true
 ```
 
 You can see the `STATUS` of the `Backup` CR named `demo1-log-backup-s3` change from `Running` to `Stopped`:
@@ -352,12 +457,14 @@ demo1-log-backup-s3        log      Stopped   ....
 ```
 
 <Tip>
-You can also stop log backup by taking the same steps as in [Start log backup](#start-log-backup). The existing `Backup` CR will be updated.
+Stopped is the terminated state of a log backup CR, you couldn't change the state again, but you still could clean log backup data.
+
+In v1.5.5 and earlier TiDB Operator versions, you could use the logStop: true/false field to stop or start a task. This field is retained for backward compatibility.
 </Tip>
 
 #### Clean log backup data
 
-1. Because you already created a `Backup` CR named `demo1-log-backup-s3` when you started log backup, you can clean the log data backup by modifying the same `Backup` CR. The priority of all operations is: stop log backup > delete log backup data > start log backup. The following example shows how to clean log backup data generated before 2022-10-10T15:21:00+08:00.
+1. Because you already created a `Backup` CR named `demo1-log-backup-s3` when you started log backup, you can clean the log data backup by modifying the same `Backup` CR. The following example shows how to clean log backup data generated before 2022-10-10T15:21:00+08:00.
 
     ```shell
     kubectl edit backup demo1-log-backup-s3 -n backup-test
@@ -374,6 +481,7 @@ You can also stop log backup by taking the same steps as in [Start log backup](#
       namespace: backup-test
     spec:
       backupMode: log
+      logSubcommand: log-start/log-pause/log-stop
       br:
         cluster: demo1
         clusterNamespace: test1

en/renew-tls-certificate.md

@@ -110,7 +110,7 @@ If the original TLS certificates are issued by [the `cfssl` system](enable-tls-b
 
     > **Note:**
     >
-    >  The above command only renews the server-side and the client-side certificate between PD, TiKV, and TiDB components. If you need to renew the server-side certificates for other components, such as TiCDC, TiFlash and TiProxy, you can execute the similar command.
+    > The above command only renews the server-side and the client-side certificate between PD, TiKV, and TiDB components. If you need to renew the server-side certificates for other components, such as TiCDC, TiFlash and TiProxy, you can execute the similar command.
 
 3. [Perform the rolling restart](restart-a-tidb-cluster.md) to components that need to load the new certificates.
 

zh/backup-restore-cr.md

@@ -34,6 +34,11 @@ summary: 介绍用于备份与恢复的 Custom Resource (CR) 资源的各字段
     * `volume-snapshot`：基于卷快照的备份。
     * `log`：从 KV 层备份实时数据变更日志数据。
 
+* `.spec.logSubcommand`：指定日志备份任务的子命令，用于控制日志备份任务的状态。该字段提供以下三种选项：
+    * `log-start`：启动一个新的日志备份任务，或恢复一个已暂停的任务。可以用于开始日志备份流程或从暂停状态恢复。
+    * `log-pause`：暂时暂停正在运行的日志备份任务，可以稍后使用 log-start 命令恢复任务。
+    * `log-stop`：永久停止日志备份任务。当此命令发出后，Backup CR 进入停止状态，无法再次启动。
+
 * `.spec.restoreMode`：指定 Restore 的模式，默认为 `snapshot`，即基于 KV 层的快照恢复。该字段仅在恢复时有效，目前支持以下三种类型：
     * `snapshot`：基于 KV 层的快照恢复。
     * `volume-snapshot`：基于卷快照的 TiDB 集群恢复。

zh/backup-restore-overview.md

@@ -78,6 +78,8 @@ kubectl delete backupschedule ${name} -n ${namespace}
 
 如果你使用 v1.1.2 及以前版本，或使用 v1.1.3 及以后版本并将 `spec.cleanPolicy` 设置为 `Delete` 时，TiDB Operator 在删除 CR 时会同时清理备份文件。
 
+如果你使用 v1.5.5, v1.6.1 及以后的版本，当你删除CR时，TiDB Operator 会尝试自动停止正在运行的日志备份任务。自动停止功能只会停止正常运行的日志备份任务，并不处理错误或者失败的任务。
+
 如果你使用基于 AWS EBS 卷快照的备份，并将 `spec.cleanPolicy` 设置为 `Delete` 时，TiDB Operator 在删除 CR 以及清理备份文件的同时删除 AWS 上相关的所有卷快照。
 
 在满足上述条件时，如果需要删除 namespace，建议首先删除所有的 Backup/BackupSchedule CR，再删除 namespace。