Use kubectl to back up and restore cluster applications - Container Service for Kubernetes

Prerequisites

Ensure that you have:

The migrate-controller add-on is installed and required permissions are configured.

Usage notes

Keep migrate-controller up to date. Outdated versions may cause unexpected behavior. See Components.
Use DeleteRequest to remove backup and restore jobs. kubectl delete does not remove associated backup data. Use a DeleteRequest CR instead. See Step 4: Delete backup and restore resources.
Do not remove parameters from the example YAML files. Removing required fields causes backup and restore to fail.
BackupLocation resources cannot be deleted from Backup Center because repositories may be shared across clusters.

Step 1: Create a backup repository

A backup repository (BackupLocation) defines the OSS bucket that stores backup data. Create the same BackupLocation on both the backup and restore clusters so they share the same data.

Create backuplocation.yaml:

apiVersion: csdr.alibabacloud.com/v1beta1
kind: BackupLocation
metadata:
  name: <your-backup-location-name>   # Must follow Kubernetes naming conventions
  namespace: csdr
spec:
  backupSyncPeriod: 0s
  config:
    network: internal   # internal: clusters and bucket must be in the same region
                        # public: no region restriction
    region: cn-beijing  # Region where the OSS bucket is located
  objectStorage:
    bucket: <cnfs-oss-your-bucket-name>   # Must start with cnfs-oss-; create in advance
    prefix: <your-subdirectory-name>       # Optional: store backups in this subdirectory
  provider: alibabacloud

Apply the manifest on both clusters:
```
kubectl apply -f backuplocation.yaml
```

Verify the repository is available on each cluster:

kubectl describe backuplocation <your-backup-location-name> -n csdr

The repository is ready when Phase shows Available:

...
Status:
  Last Validation Time:  2022-12-08T04:00:22Z
  Message:               success by csdr-controller
  Phase:                 Available

Available confirms the cluster can access the OSS bucket.

Step 2: Create a backup job

Backup Center supports two backup types:

Application Backup: Backs up Kubernetes resources (such as StatefulSets and Deployments) with their Persistent Volumes (PVs).
Data Protection: Backs up PVs only, without application resources.

See Scenarios for Application Backup and Data Protection.

Each type supports on-demand and scheduled backups.

Application backup

On-demand backup

Create applicationbackup.yaml in the backup cluster:

Important

Configure either includedResources or excludedResources, not both. When both are empty, all resource types are backed up.

For console-created backup jobs, includeClusterResources defaults to false.

apiVersion: csdr.alibabacloud.com/v1beta1
kind: ApplicationBackup
metadata:
  annotations:
    csdr.alibabacloud.com/backuplocations: >-
      {"name":"<your-backup-repository-name>","region":"cn-beijing","bucket":"<your-oss-bucket-name>","prefix":"<your-subdirectory-name>","provider":"alibabacloud"}
  name: <your-application-backup-name>
  namespace: csdr
spec:
  includedNamespaces:
    - default                # Namespaces to include in the backup
  includedResources:
    - statefulset            # Resource types to include (configure only one of
  excludedResources:         # includedResources or excludedResources; when both
    - deployment             # are empty, all resource types are backed up)
  labelSelector:
    matchLabels:
      app: mysql-sts         # Only resources with this label are backed up
  includeClusterResources: false   # false: only cluster-level resources referenced
                                   # by selected namespace resources are backed up
                                   # (e.g., ClusterRoles, CRDs)
                                   # true: all cluster-level resources are backed up
  pvBackup:
    defaultPvBackup: false   # false: back up application resources only
                             # true: back up application resources and PVs
  storageLocation: <your-backup-repository-name>
                             # Note: If your cluster already uses Velero, join the
                             # DingTalk user group (Group Number: 35532895) for assistance.
  ttl: 720h0m0s              # Retention period; range: 24h0m0s to 1572864h0m0s

Apply the manifest in the backup cluster:
```
kubectl apply -f applicationbackup.yaml
```

Check the backup status:

kubectl describe applicationbackup <your-application-backup-name> -n csdr

The backup is complete when Phase changes from Inprogress to Completed:

...
Status:
  Completion Timestamp:  2022-12-05T15:02:35Z
  Expiration:            2023-01-04T15:02:25Z
  Message:               success
  Phase:                 Completed

Scheduled backup

Create backupschedule.yaml in the backup cluster:

apiVersion: csdr.alibabacloud.com/v1beta1
kind: BackupSchedule
metadata:
  annotations:
    csdr.alibabacloud.com/backuplocations: >-
      {"name":"<your-backup-repository-name>","region":"cn-beijing","bucket":"<your-oss-bucket-name>","prefix":"<your-subdirectory-name>","provider":"alibabacloud"}
  name: <your-backup-schedule-name>
  namespace: csdr
spec:
  schedule: 1 4 * * *   # Cron expression:
                         # ┌── minute (0–59)
                         # │ ┌── hour (0–23)
                         # │ │ ┌── day of month (1–31)
                         # │ │ │ ┌── month (1–12)
                         # │ │ │ │ ┌── day of week (0–6, Sunday=0)
                         # │ │ │ │ │
                         # 1 4 * * *  → runs at 04:01 every day
                         # For more cron examples, see How to specify a backup schedule.
  template:
    includedNamespaces:
      - default
    includedResources:
      - statefulset
    excludedResources:
      - deployment
    labelSelector:
      matchLabels:
        app: mysql-sts
    includeClusterResources: false
    pvBackup:
      defaultPvBackup: true   # Required for scheduled backups; true: back up app + PVs
    storageLocation: <your-backup-repository-name>
                               # Note: If your cluster already uses Velero, join the
                               # DingTalk user group (Group Number: 35532895) for assistance.
    ttl: 720h0m0s

See How to specify a backup schedule.

Apply the manifest in the backup cluster:
```
kubectl apply -f backupschedule.yaml
```

Verify the schedule is active:

kubectl describe backupschedule <your-backup-schedule-name> -n csdr

The schedule is running when Phase shows Enabled:

...
Status:
  Last Backup:          2022-12-07T20:01:11Z
  Last Processed Time:  2022-12-08T13:05:37Z
  Phase:                Enabled

List the point-in-time backups created by the schedule:

kubectl get applicationbackup -n csdr | grep <your-backup-schedule-name>

Each scheduled run creates a timestamped ApplicationBackup resource:

<your-backup-schedule-name>-20221205225845   2d22h
<your-backup-schedule-name>-20221206040104   2d17h
<your-backup-schedule-name>-20221207040137   41h
<your-backup-schedule-name>-20221208040111   17h

Note these names—you need them to create a restore task.

Data protection

Data Protection backs up PVs only. Use kind: ApplicationBackup with backupType: PvBackup (a fixed value).

On-demand backup

Create applicationbackup.yaml in the backup cluster:

Important

If both pvcList and storageClassList are specified, storageClassList is ignored. If neither is specified, all PVs in the specified namespace are backed up.

apiVersion: csdr.alibabacloud.com/v1beta1
kind: ApplicationBackup
metadata:
  annotations:
    csdr.alibabacloud.com/backuplocations: >-
      {"name":"<your-backup-repository-name>","region":"cn-beijing","bucket":"<your-oss-bucket-name>","prefix":"<your-subdirectory-name>","provider":"alibabacloud"}
  name: <your-application-backup-name>
  namespace: csdr
spec:
  backupType: PvBackup   # Fixed value for Data Protection
  includedNamespaces:
    - default
  pvBackup:
    # Option 1: specify PVCs by name
    pvcList:
      - name: essd-pvc-0
        namespace: default
      - name: essd-pvc-1
        namespace: default
    # Option 2: specify PVCs by storage class (ignored if pvcList is also set)
    storageClassList:
      - disk-essd
      - disk-ssd
    # If neither pvcList nor storageClassList is set, all PVs in the namespace are backed up.
  storageLocation: <your-backup-repository-name>
                   # Note: If your cluster already uses Velero, join the
                   # DingTalk user group (Group Number: 35532895) for assistance.
  ttl: 720h0m0s

Apply the manifest in the backup cluster:
```
kubectl apply -f applicationbackup.yaml
```

Check the backup status:

kubectl describe applicationbackup <your-application-backup-name> -n csdr

Expected output when complete:

...
Status:
  Completion Timestamp:  2025-03-25T08:20:24Z
  Expiration:            2025-04-24T08:18:03Z
  Message:               success
  Phase:                 Completed

Scheduled backup

Create backupschedule.yaml in the backup cluster:

apiVersion: csdr.alibabacloud.com/v1beta1
kind: BackupSchedule
metadata:
  annotations:
    csdr.alibabacloud.com/backuplocations: >-
      {"name":"<your-backup-repository-name>","region":"cn-beijing","bucket":"<your-oss-bucket-name>","prefix":"<your-subdirectory-name>","provider":"alibabacloud"}
  name: <your-backup-schedule-name>
  namespace: csdr
spec:
  schedule: 1 4 * * *
  template:
    backupType: PvBackup   # Fixed value for Data Protection
    includedNamespaces:
      - default
    pvBackup:
      pvcList:
        - name: essd-pvc-0
          namespace: default
        - name: essd-pvc-1
          namespace: default
      storageClassList:
        - disk-essd
        - disk-ssd
    storageLocation: <your-backup-repository-name>
    ttl: 720h0m0s

Apply the manifest in the backup cluster:
```
kubectl apply -f backupschedule.yaml
```

Verify the schedule is active:

kubectl describe backupschedule <your-backup-schedule-name> -n csdr

Expected output when active:

...
Status:
  Last Backup:  2025-03-25T09:24:38Z
  Phase:        Enabled

Step 3: Create a restore task

Create applicationrestore.yaml in the restore cluster:

appRestoreOnly, preserveNodePorts, includedResources, and excludedResources apply to Application Backup only and are ignored in Data Protection.

To find PVC names and data types, run kubectl -ncsdr describe <backup-name> and check status.resourceList.dataResource.pvcBackupInfo. dataType shows FileSystem or Snapshot; nameSpace and pvcName identify the PVC.

apiVersion: csdr.alibabacloud.com/v1beta1
kind: ApplicationRestore
metadata:
  annotations:
    csdr.alibabacloud.com/backuplocations: >-
      {"name":"<your-backup-repository-name>","region":"cn-beijing","bucket":"<your-oss-bucket-name>","prefix":"<your-subdirectory-name>","provider":"alibabacloud"}
  name: <your-application-restore-name>
  namespace: csdr
spec:
  backupName: <your-application-backup-name>   # For scheduled backups, specify the
                                                # point-in-time name, e.g.:
                                                # <your-backup-schedule-name>-20221205225845
  includedNamespaces:
    - default             # Namespaces to restore; leave blank to restore all namespaces
  appRestoreOnly: false   # Application Backup only; ignored in Data Protection
                          # false (default): restore app resources and PV data
                          # true: restore app resources only (use when manually
                          #       pre-creating PVCs before restore)
  preserveNodePorts: true # Application Backup only; ignored in Data Protection
                          # false: assign random NodePort values (use when restoring
                          #        to the same cluster to avoid port conflicts)
                          # true: preserve original NodePort values (use when
                          #       restoring to a different cluster)
  includedResources:
    - statefulset         # Application Backup only; resource types to restore
  excludedResources:
    - secret              # Application Backup only; resource types to skip
  namespaceMapping:
    <source-namespace>: <target-namespace>   # Remap namespace during restore;
                                              # target namespace is created if it
                                              # doesn't exist
  imageRegistryMapping:
    <old-image-registry>: <new-image-registry>   # Remap image registry for all
                                                   # images whose address starts with
                                                   # the source prefix
  convertedarg:           # StorageClass conversions for file system-type volumes
                          # (OSS, File Storage NAS (NAS), Cloud Parallel File
                          # Storage (CPFS), or local storage) to a Cloud Disk or
                          # File Storage NAS StorageClass
    - convertToStorageClassType: alicloud-disk-topology-alltype   # Target StorageClass
                                                                   # (must exist in cluster)
      convertToAccessModes:
        - ReadWriteOnce   # Required when converting PVs with ReadWriteMany or
                          # ReadOnlyMany access modes to a Cloud Disk StorageClass
      namespace: nas
      persistentVolumeClaim: pvc-nas
    - convertToStorageClassType: alicloud-disk-topology-alltype
      namespace: oss
      persistentVolumeClaim: pvc-oss

Apply the manifest in the restore cluster:
```
kubectl apply -f applicationrestore.yaml
```

Check the restore status:

kubectl describe applicationrestore <your-application-restore-name> -n csdr

The restore is complete when Phase changes from Inprogress to Completed:

...
Status:
  Completion Timestamp:  2022-12-05T15:52:19Z
  Phase:                 Completed
  Start Timestamp:       2022-12-05T15:52:09Z

Step 4: Delete backup and restore resources

Important

Do not use kubectl delete to remove ApplicationBackup or ApplicationRestore resources. kubectl delete does not remove associated data. Use a DeleteRequest CR instead.

Delete a scheduled backup plan

Delete the BackupSchedule resource to stop a schedule and prevent future backups:

kubectl delete backupschedule <your-backup-schedule-name> -n csdr

Delete a backup job or restore task

Create deleterequest.yaml in the cluster where the resource resides:

Deleting a backup job does not affect synchronized replicas. Deleting a restore task does not affect restored resources.

apiVersion: csdr.alibabacloud.com/v1beta1
kind: DeleteRequest
metadata:
  name: <object-name>-dbr   # Append -dbr to the name of the resource being deleted
  namespace: csdr
spec:
  deleteObjectName: <object-name>         # Name of the ApplicationBackup or
                                           # ApplicationRestore resource to delete
  deleteObjectType: "Backup"              # "Backup": deletes the ApplicationBackup job
                                           # "Restore": deletes the ApplicationRestore task

Apply the delete request:
```
kubectl apply -f deleterequest.yaml
```

Verify the deletion. Both the target resource and the DeleteRequest CR are removed automatically. For a backup job:

kubectl get applicationbackup <your-application-backup-name> -n csdr

Expected output:

Error from server (NotFound): applicationbackups.csdr.alibabacloud.com "your-application-backup-name" not found

kubectl get deleterequest <your-application-backup-name>-dbr -n csdr

Expected output:

Error from server (NotFound): deleterequests.csdr.alibabacloud.com "your-application-backup-name-dbr" not found

For a restore task:

kubectl get applicationrestore <your-application-restore-name> -n csdr

Expected output:

Error from server (NotFound): applicationrestores.csdr.alibabacloud.com "your-application-restore-name" not found

kubectl get deleterequest <your-application-restore-name>-dbr -n csdr

Expected output:

Error from server (NotFound): deleterequests.csdr.alibabacloud.com "your-application-restore-name-dbr" not found

Next steps

To manage backups from the ACK console instead of kubectl:
See Use Backup Center to migrate applications from an earlier-version Kubernetes cluster.
See Back up and restore applications using Terraform.