Back up and restore applications using kubectl - Container Service for Kubernetes

Prerequisites

Before you begin, ensure that you have:

Installed the migrate-controller backup service component and configured the required permissions. See Install the migrate-controller component.

Important notes

Keep migrate-controller up to date. Outdated versions may cause unexpected behavior. See Manage components.
Use DeleteRequest to remove backup and restore jobs. Backup and restore tasks cannot be simply deleted using the kubectl delete command. To delete both the CR and its associated backup data, create a DeleteRequest CR instead. See Step 4: Delete backup and restore resources.
Do not remove parameters from the example YAML files. Deleting required fields causes backup and restore operations to fail.
BackupLocation resources cannot be deleted through Backup Center because a backup repository may be shared across multiple clusters.

Step 1: Create a backup repository

A backup repository (BackupLocation) points to the OSS bucket where backup data is stored. Create the same BackupLocation on both the backup cluster and the restore cluster so both can access the same data.

Create backuplocation.yaml with the following content:

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 backup 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 has direct access to 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) together with the Persistent Volumes (PVs) they use.
Data Protection: Backs up PVs only, without the associated application resources.

For guidance on choosing between them, 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 backup jobs created from the ACK console, 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

For cron expression format details, 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 the names of these point-in-time backups—you'll need them when creating 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 only to Application Backup jobs and have no effect in Data Protection scenarios.

To find the PVC names and data types in a backup, run kubectl -ncsdr describe <backup-name> and inspect status.resourceList.dataResource.pvcBackupInfo. The dataType field shows FileSystem or Snapshot, and 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, Apsara File Storage NAS, Cloud Parallel File
                          # Storage (CPFS), or local storage) to a Cloud Disk or
                          # Apsara 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. Backup and restore tasks cannot be simply deleted using kubectl delete. To delete both the CR and its associated data, use a DeleteRequest CR as described below.

Delete a scheduled backup plan

To stop a schedule and prevent future backups, delete the BackupSchedule resource:

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

Delete a backup job or restore task

Create deleterequest.yaml in the cluster that contains the resource to delete:

Deleting a backup job does not affect replicas already synchronized to the cluster. Deleting a restore task does not affect resources already restored.

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 automatically removed on completion. For a backup job deletion:

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 deletion:

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

What's next

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