文档目录

备份与恢复简介

本文档介绍如何使用 BRDumplingTiDB Lightning 对 Kubernetes 上的 TiDB 集群进行数据备份和数据恢复。

TiDB Operator 1.1 及以上版本推荐使用基于 CustomResourceDefinition (CRD) 实现的备份恢复方式实现:

使用场景

Dumpling 是一个数据导出工具,该工具可以把存储在 TiDB/MySQL 中的数据导出为 SQL 或者 CSV 格式,可以用于完成逻辑上的全量备份或者导出。如果需要直接备份 SST 文件(键值对)或者对延迟不敏感的增量备份,请参阅 BR。如果需要实时的增量备份,请参阅 TiCDC

TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具,TiDB Lightning 有以下两个主要的使用场景:一是大量新数据的快速导入;二是全量备份数据的恢复。目前,TiDB Lightning 支持 Dumpling 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 TiDB Lightning:

  • 迅速导入大量新数据。
  • 恢复所有备份数据。

BR 是 TiDB 分布式备份恢复的命令行工具,用于对 TiDB 集群进行数据备份和恢复。相比 Dumpling 和 Mydumper,BR 更适合大数据量的场景,BR 只支持 TiDB v3.1 及以上版本。

Backup CR 字段介绍

为了对 Kubernetes 上的 TiDB 集群进行数据备份,用户可以通过创建一个自定义的 Backup Custom Resource (CR) 对象来描述一次备份,具体备份过程可参考 备份与恢复简介中列出的文档。以下介绍 Backup CR 各个字段的具体含义。

通用字段介绍

  • .spec.metadata.namespaceBackup CR 所在的 namespace。

  • .spec.toolImage:用于指定 Backup 使用的工具镜像。

    • 使用 BR 备份时,可以用该字段指定 BR 的版本:
      • 如果未指定或者为空,默认使用镜像 pingcap/br:${tikv_version} 进行备份。
      • 如果指定了 BR 的版本,例如 .spec.toolImage: pingcap/br:v4.0.13,那么使用指定的版本镜像进行备份。
      • 如果指定了镜像但未指定版本,例如 .spec.toolImage: private/registry/br,那么使用镜像 private/registry/br:${tikv_version} 进行备份。
    • 使用 Dumpling 备份时,可以用该字段指定 Dumpling 的版本,例如, spec.toolImage: pingcap/dumpling:v4.0.13。如果不指定,默认使用 Backup Manager Dockerfile 文件中 TOOLKIT_V40 指定的 Dumpling 版本进行备份。
    • TiDB Operator 从 v1.1.9 版本起支持这项配置。
  • .spec.tikvGCLifeTime:备份中的临时 tikv_gc_life_time 时间设置,默认为 72h。

    在备份开始之前,若 TiDB 集群的 tikv_gc_life_time 小于用户设置的 spec.tikvGCLifeTime,为了保证备份的数据不被 TiKV GC 掉,TiDB Operator 会在备份前调节 tikv_gc_life_timespec.tikvGCLifeTime

    备份结束后不论成功或者失败,只要老的 tikv_gc_life_time 比设置的 .spec.tikvGCLifeTime 小,TiDB Operator 都会尝试恢复 tikv_gc_life_time 为备份前的值。在极端情况下,TiDB Operator 访问数据库失败会导致 TiDB Operator 无法自动恢复 tikv_gc_life_time 并认为备份失败。

    此时,可以通过下述语句查看当前 TiDB 集群的 tikv_gc_life_time

    select VARIABLE_NAME, VARIABLE_VALUE from mysql.tidb where VARIABLE_NAME like "tikv_gc_life_time";

    如果发现 tikv_gc_life_time 值过大(通常为 10m),则需要按照调节 tikv_gc_life_timetikv_gc_life_time 调回原样。

  • .spec.cleanPolicy:备份集群后删除备份 CR 时的备份文件清理策略。目前支持三种清理策略:

    • Retain:任何情况下,删除备份 CR 时会保留备份出的文件

    • Delete:任何情况下,删除备份 CR 时会删除备份出的文件

    • OnFailure:如果备份中失败,删除备份 CR 时会删除备份出的文件

      如果不配置该字段,或者配置该字段的值为上述三种以外的值,均会保留备份出的文件。值得注意的是,在 v1.1.2 以及之前版本不存在该字段,且默认在删除 CR 的同时删除备份的文件。若 v1.1.3 及之后版本的用户希望保持该行为,需要设置该字段为 Delete

  • .spec.from.host:待备份 TiDB 集群的访问地址,为需要导出的 TiDB 的 service name,例如 basic-tidb

  • .spec.from.port:待备份 TiDB 集群的访问端口。

  • .spec.from.user:待备份 TiDB 集群的访问用户。

  • .spec.from.secretName:存储 .spec.from.user 用户的密码的 Secret。

  • .spec.from.tlsClientSecretName:指定备份使用的存储证书的 Secret。

    如果 TiDB 集群开启了 TLS,但是不想使用文档中创建的 ${cluster_name}-cluster-client-secret 进行备份,可以通过这个参数为备份指定一个 Secret,可以通过如下命令生成:

    kubectl create secret generic ${secret_name} --namespace=${namespace} --from-file=tls.crt=${cert_path} --from-file=tls.key=${key_path} --from-file=ca.crt=${ca_path}
  • .spec.storageClassName:备份时所需的 persistent volume (PV) 类型。

  • .spec.storageSize:备份时指定所需的 PV 大小,默认为 100 Gi。该值应大于备份 TiDB 集群数据的大小。一个 TiDB 集群的 Backup CR 对应的 PVC 名字是确定的,如果集群命名空间中已存在该 PVC 并且其大小小于 .spec.storageSize,这时需要先删除该 PVC 再运行 Backup job。

  • .spec.tableFilter:备份时指定让 Dumpling 或者 BR 备份符合 table-filter 规则的表。默认情况下该字段可以不用配置。

    当不配置时,如果使用 Dumpling 备份,tableFilter 字段的默认值如下:

    tableFilter:
    - "*.*"
    - "!/^(mysql|test|INFORMATION_SCHEMA|PERFORMANCE_SCHEMA|METRICS_SCHEMA|INSPECTION_SCHEMA)$/.*"

    如果使用 BR 备份,BR 会备份除系统库以外的所有数据库。

    注意:

    如果要使用排除规则 "!db.table" 导出除 db.table 的所有表,那么在 "!db.table" 前必须先添加 *.* 规则。如下面例子所示:

    tableFilter:
    - "*.*"
    - "!db.table"

BR 字段介绍

  • .spec.br.cluster:代表需要备份的集群名字。
  • .spec.br.clusterNamespace:代表需要备份的集群所在的 namespace
  • .spec.br.logLevel:代表日志的级别。默认为 info
  • .spec.br.statusAddr:为 BR 进程监听一个进程状态的 HTTP 端口,方便用户调试。如果不填,则默认不监听。
  • .spec.br.concurrency:备份时每一个 TiKV 进程使用的线程数。备份时默认为 4,恢复时默认为 128。
  • .spec.br.rateLimit:是否对流量进行限制。单位为 MB/s,例如设置为 4 代表限速 4 MB/s,默认不限速。
  • .spec.br.checksum:是否在备份结束之后对文件进行验证。默认为 true
  • .spec.br.timeAgo:备份 timeAgo 以前的数据,默认为空(备份当前数据),支持 "1.5h","2h45m" 等数据。
  • .spec.br.sendCredToTikv:BR 进程是否将自己的 AWS 权限 或者 GCP 权限传输给 TiKV 进程。默认为 true
  • .spec.br.options:BR 工具支持的额外参数,需要以字符串数组的形式传入。自 v1.1.6 版本起支持该参数。可用于指定 lastbackupts 以进行增量备份。

S3 存储字段介绍

  • .spec.s3.provider:支持的兼容 S3 的 provider

    更多支持的兼容 S3 的 provider 如下:

    • alibaba:Alibaba Cloud Object Storage System (OSS),formerly Aliyun
    • digitalocean:Digital Ocean Spaces
    • dreamhost:Dreamhost DreamObjects
    • ibmcos:IBM COS S3
    • minio:Minio Object Storage
    • netease:Netease Object Storage (NOS)
    • wasabi:Wasabi Object Storage
    • other:Any other S3 compatible provider
  • .spec.s3.region:使用 Amazon S3 存储备份,需要配置 Amazon S3 所在的 region。

  • .spec.s3.bucket:兼容 S3 存储的 bucket 名字。

  • .spec.s3.prefix:如果设置了这个字段,则会使用这个字段来拼接在远端存储的存储路径 s3://${.spec.s3.bucket}/${.spec.s3.prefix}/backupName

  • .spec.s3.acl:支持的 access-control list (ACL) 策略。

    Amazon S3 支持以下几种 access-control list (ACL) 策略:

    • private

    • public-read

    • public-read-write

    • authenticated-read

    • bucket-owner-read

    • bucket-owner-full-control

      如果不设置 ACL 策略,则默认使用 private 策略。这几种访问控制策略的详细介绍参考 AWS 官方文档

  • .spec.s3.storageClass:支持的 storageClass 类型。

    Amazon S3 支持以下几种 storageClass 类型:

    • STANDARD

    • REDUCED_REDUNDANCY

    • STANDARD_IA

    • ONEZONE_IA

    • GLACIER

    • DEEP_ARCHIVE

      如果不设置 storageClass,则默认使用 STANDARD_IA。这几种存储类型的详细介绍参考 AWS 官方文档

GCS 存储字段介绍

  • .spec.gcs.projectId:代表 GCP 上用户项目的唯一标识。具体获取该标识的方法可参考 GCP 官方文档

  • .spec.gcs.bucket:存储数据的 bucket 名字。

  • .spec.gcs.prefix:如果设置了这个字段,则会使用这个字段来拼接在远端存储的存储路径 gcs://${.spec.gcs.bucket}/${.spec.gcs.prefix}/backupName

  • spec.gcs.storageClass:GCS 支持以下几种 storageClass 类型:

    • MULTI_REGIONAL

    • REGIONAL

    • NEARLINE

    • COLDLINE

    • DURABLE_REDUCED_AVAILABILITY

      如果不设置 storageClass,则默认使用 COLDLINE。这几种存储类型的详细介绍可参考 GCS 官方文档

  • spec.gcs.objectAcl:设置 object access-control list (ACL) 策略。

    GCS 支持以下几种 ACL 策略:

    • authenticatedRead

    • bucketOwnerFullControl

    • bucketOwnerRead

    • private

    • projectPrivate

    • publicRead

      如果不设置 object ACL 策略,则默认使用 private 策略。这几种访问控制策略的详细介绍可参考 GCS 官方文档

  • spec.gcs.bucketAcl:设置 bucket access-control list (ACL) 策略。

    GCS 支持以下几种 bucket ACL 策略:

    • authenticatedRead

    • private

    • projectPrivate

    • publicRead

    • publicReadWrite

      如果不设置 bucket ACL 策略,则默认策略为 private。这几种访问控制策略的详细介绍可参考 GCS 官方文档

Local 存储字段介绍

  • .spec.local.prefix:持久卷存储目录。如果设置了这个字段,则会使用这个字段来拼接在持久卷的存储路径 local://${.spec.local.volumeMount.mountPath}/${.spec.local.prefix}/
  • .spec.local.volume:持久卷配置。
  • .spec.local.volumeMount:持久卷挂载配置。

Restore CR 字段介绍

为了对 Kubernetes 上的 TiDB 集群进行数据恢复,用户可以通过创建一个自定义的 Restore Custom Resource (CR) 对象来描述一次恢复,具体恢复过程可参考 备份与恢复简介中列出的文档。以下介绍 Restore CR 各个字段的具体含义。

  • .spec.metadata.namespaceRestore CR 所在的 namespace。

  • .spec.toolImage:用于指定 Restore 使用的工具镜像。

    • 使用 BR 恢复时,可以用该字段指定 BR 的版本。例如,spec.toolImage: pingcap/br:v4.0.10。如果不指定,默认使用 pingcap/br:${tikv_version} 进行恢复。
    • 使用 Lightning 恢复时,可以用该字段指定 Lightning 的版本,例如spec.toolImage: pingcap/lightning:v4.0.10。如果不指定,默认使用 Backup Manager Dockerfile 文件中 TOOLKIT_V40 指定的 Lightning 版本进行恢复。
    • TiDB Operator 从 v1.1.9 版本起支持这项配置。
  • .spec.to.host:待恢复 TiDB 集群的访问地址。

  • .spec.to.port:待恢复 TiDB 集群的访问端口。

  • .spec.to.user:待恢复 TiDB 集群的访问用户。

  • .spec.to.secretName:存储 .spec.to.user 用户的密码的 secret。

  • .spec.to.tlsClientSecretName:指定恢复备份使用的存储证书的 Secret。

    如果 TiDB 集群开启了 TLS,但是不想使用文档中创建的 ${cluster_name}-cluster-client-secret 恢复备份,可以通过这个参数为恢复备份指定一个 Secret,可以通过如下命令生成:

    kubectl create secret generic ${secret_name} --namespace=${namespace} --from-file=tls.crt=${cert_path} --from-file=tls.key=${key_path} --from-file=ca.crt=${ca_path}
  • .spec.storageClassName:指定恢复时所需的 PV 类型。

  • .spec.storageSize:指定恢复集群时所需的 PV 大小。该值应大于 TiDB 集群备份的数据大小。

  • .spec.tableFilter:恢复时指定让 BR 恢复符合 table-filter 规则 的表。默认情况下该字段可以不用配置。

    当不配置时,如果使用 TiDB Lightning 恢复,tableFilter 字段的默认值如下:

    tableFilter:
    - "*.*"
    - "!/^(mysql|test|INFORMATION_SCHEMA|PERFORMANCE_SCHEMA|METRICS_SCHEMA|INSPECTION_SCHEMA)$/.*"

    如果使用 BR 恢复,BR 会恢复备份文件中的所有数据库:

    注意:

    如果要使用排除规则 "!db.table" 导出除 db.table 的所有表,那么在 "!db.table" 前必须先添加 *.* 规则。如下面例子所示:

    tableFilter:
    - "*.*"
    - "!db.table"
  • .spec.br:BR 相关配置,具体介绍参考 BR 字段介绍

  • .spec.s3:S3 兼容存储相关配置,具体介绍参考 S3 字段介绍

  • .spec.gcs:GCS 存储相关配置,具体介绍参考 GCS 字段介绍

  • .spec.local:持久卷存储相关配置,具体介绍参考 Local 字段介绍

BackupSchedule CR 字段介绍

backupSchedule 的配置由两部分组成。一部分是 backupSchedule 独有的配置,另一部分是 backupTemplatebackupTemplate 指定集群及远程存储相关的配置,字段和 Backup CR 中的 spec 一样,详细介绍可参考 Backup CR 字段介绍。下面介绍 backupSchedule 独有的配置项:

  • .spec.maxBackups:一种备份保留策略,决定定时备份最多可保留的备份个数。超过该数目,就会将过时的备份删除。如果将该项设置为 0,则表示保留所有备份。
  • .spec.maxReservedTime:一种备份保留策略,按时间保留备份。例如将该参数设置为 24h,表示只保留最近 24 小时内的备份条目。超过这个时间的备份都会被清除。时间设置格式参考 func ParseDuration。如果同时设置最大备份保留个数和最长备份保留时间,则以最长备份保留时间为准。
  • .spec.schedule:Cron 的时间调度格式。具体格式可参考 Cron
  • .spec.pause:该值默认为 false。如果将该值设置为 true,表示暂停定时调度。此时即使到了调度时间点,也不会进行备份。在定时备份暂停期间,备份 Garbage Collection (GC) 仍然正常进行。将 true 改为 false 则重新开启定时全量备份。

删除备份的 Backup CR

用户可以通过下述语句来删除对应的备份 CR 或定时全量备份 CR。

kubectl delete backup ${name} -n ${namespace}
kubectl delete backupschedule ${name} -n ${namespace}

如果你使用 v1.1.2 及以前版本,或使用 v1.1.3 及以后版本并将 spec.cleanPolicy 设置为 Delete 时,TiDB Operator 在删除 CR 时会同时删除备份文件。

在满足上述条件时,如果需要删除 namespace,建议首先删除所有的 Backup/BackupSchedule CR,再删除 namespace。

如果直接删除存在 Backup/BackupSchedule CR 的 namespace,TiDB Operator 会持续尝试创建 Job 清理备份的数据,但因为 namespace 处于 Terminating 状态而创建失败,从而导致 namespace 卡在该状态。

这时需要通过下述命令删除 finalizers

kubectl edit backup ${name} -n ${namespace}

删除 metadata.finalizers 配置,即可正常删除 CR。