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

You can use kubectl when you cannot manage the backup center through the Container Service for Kubernetes (ACK) console or you want to automate backup and disaster recovery. By using kubectl, you can deploy BackupLocation, ApplicationBackup, and ApplicationRestore CustomResources (CRs) in the backup and restore clusters to migrate applications.

Prerequisites

migrate-controller is installed and permissions are granted. For more information, see Install migrate-controller and grant permissions.

Use scenarios

You cannot use the backup center in the ACK console because you do not have the required permissions.
You want to automate the backup procedure.

Usage notes

You cannot delete backup or restore tasks by running the kubectl delete command. For more information, see Step 4: Delete resources related to the backup center.
Pay close attention to the new releases of the backup center component named migrate-controller and update the component to the latest version at your earliest convenience. For more information, see Manage components.
Do not delete the parameters in the following sample code in case the backup files cannot be restored.

Step 1: Create a backup vault

Create a file named backuplocation.yaml in both the backup and restore clusters and add the following content to the file:

apiVersion: csdr.alibabacloud.com/v1beta1
kind: BackupLocation
metadata:
  name: <yourBackuplocationName>
  namespace: csdr
spec:
  backupSyncPeriod: 0s
  config:
    network: internal
    region: cn-beijing
  objectStorage:
    bucket: <cnfs-oss-yourBucketName>
    prefix: <subDir>
  provider: alibabacloud

The following table describes the parameters that you need to specify. Keep the default setting for other parameters.

Parameter	Required	Description
name	Yes	The name of the backup vault. The name must comply with the Kubernetes naming convention.
network	Yes	The network mode that is used to access the specified Object Storage Service (OSS) bucket. Valid values: internal: internal mode. All associated clusters must be deployed in the same region as the OSS bucket. public: public mode. This mode does not have region limits.
region	Yes	The region where the OSS bucket resides.
bucket	Yes	The name of the OSS bucket. Make sure that the OSS bucket name exists and starts with cnfs-oss-.
prefix	No	The subdirectory in the OSS bucket. If you specify this parameter, backups are stored in the specified subdirectory.

Run the following command in both the backup and restore clusters to deploy a backuplocation object:
```
kubectl apply -f backuplocation.yaml
```
Run the following command in both the backup and restore clusters to query the status of the backuplocation object:
```
kubectl describe backuplocation <yourBackuplocationName> -n csdr
```
Expected output:
```
...
Status:
  Last Validation Time:  2022-12-08T04:00:22Z
  Message:               success by csdr-controller
  Phase:                 Available
```
The output indicates that the backup vault is in the Available state. This means that the current cluster has permissions to access OSS.

Step 2: Create a backup task

Create a real-time backup task

Create a file named applicationbackup.yaml in the backup cluster and add the following content to the file:

apiVersion: csdr.alibabacloud.com/v1beta1
kind: ApplicationBackup
metadata:
  annotations:
    csdr.alibabacloud.com/backuplocations: >-
      {"name":"<yourBackuplocationName>","region":"cn-beijing","bucket":"<cnfs-oss-yourBucketName>","prefix":"<subDir>","provider":"alibabacloud"}}
  name: <yourApplicationBackupName>
  namespace: csdr
spec:
  includedNamespaces:
    - default
  includedResources:
    - statefulset
  excludedResources:
    - deployment
  labelSelector:
    matchLabels:
      app: mysql-sts
  includeClusterResources: false 
  pvBackup:
    defaultPvBackup: false
  storageLocation: <yourBackuplocationName>
  ttl: 720h0m0s

The following table describes the parameters that you need to specify. Keep the default setting for other parameters.

Parameter	Required	Description
csdr.alibabacloud.com/backuplocations	Yes	The backup vault that stores the backups. Make sure that the information is the same as the configuration of the backup vault.
name	Yes	The name of the real-time backup task.
includedNamespaces	Yes	The name of the namespace.
includedResources	No	The type of cluster resource to be included in the backup list. Important To ensure that backups are created as expected, specify only one of the following parameters: includedResources and excludedResources. If you leave both parameters empty, all resource types are backed up.
excludedResources	No	The type of cluster resource to be excluded from the backup list. Important To ensure that backups are created as expected, specify only one of the following parameters: includedResources and excludedResources. If you leave both parameters empty, all resource types are backed up.
matchLabels	No	The labels of the resources to be backed up.
includeClusterResources	No	Specify whether to back up all cluster-level resources, such as StorageClasses, CustomResourceDefinitions (CRDs), and webhooks. `true`: back up all cluster-level resources. `false`: back up only cluster-level resources used by namespace-level resources in the specified namespaces. For example, when the system backs up a pod, the service account used by the pod is assigned a cluster role. In this case, the cluster role is automatically backed up. When the system backs up a CustomResource (CR), the corresponding CRD is backed up. Note By default, `IncludeClusterResources` is set to `false` for backup tasks created in the ACK console.
defaultPvBackup		Specifies whether to back up volumes. Valid values: true: backs up applications and volumes. false: backs up only applications.
storageLocation	Yes	The name of the backup vault. Note If your ACK cluster uses Velero, join DingTalk group 35532895 to request technical support.
ttl	Yes	The validity period of backups. You cannot restore data from expired backups. Specify the time period in the 720h0m0s format. Valid values: 24h0m0s to 1572864h0m0s.

Run the following command in the backup cluster to deploy an applicationbackup object:
```
kubectl apply -f applicationbackup.yaml
```

Run the following command in the backup cluster to query the status of the real-time backup task:

kubectl describe applicationbackup <yourApplicationBackupName> -n csdr

Expected output:

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

If the status of the real-time backup task changes from Inprogress to Completed, the task is created.

Create a scheduled backup task

Create a file named backupschedule.yaml in the backup cluster and add the following content to the file:

apiVersion: csdr.alibabacloud.com/v1beta1
kind: BackupSchedule
metadata:
  annotations:
    csdr.alibabacloud.com/backuplocations: >-
      {"name":"<yourBackuplocationName>","region":"cn-beijing","bucket":"<cnfs-oss-yourBucketName>","prefix":"<subDir>","provider":"alibabacloud"}
  name: <yourBackupScheduleName>
  namespace: csdr
spec:
  schedule: 1 4 * * *
  template:
    includedNamespaces:
      - default
    includedResources:
      - statefulset
    excludedResources:
      - deployment
    labelSelector:
      matchLabels:
        app: mysql-sts
    includeClusterResources: false 
    pvBackup:
      defaultPvBackup: true
    storageLocation: <yourBackuplocationName>
    ttl: 720h0m0s

The following table describes the parameters that you need to specify. Keep the default setting for other parameters.

Parameter	Required	Description
csdr.alibabacloud.com/backuplocations	Yes	The backup vault that stores the backups. Make sure that the information is the same as the configuration of the backup vault.
name	Yes	The name of the scheduled backup task.
schedule	Yes	The backup cycle specified by a cron expression.
includedNamespaces	Yes	The name of the namespace.
includedResources	No	The type of cluster resource to be included in the backup list. Important To ensure that backups are created as expected, specify only one of the following parameters: includedResources and excludedResources. If you leave both parameters empty, all resource types are backed up.
excludedResources	No	The type of cluster resource to be excluded from the backup list. Important To ensure that backups are created as expected, specify only one of the following parameters: includedResources and excludedResources. If you leave both parameters empty, all resource types are backed up.
matchLabels	No	The labels of the resources to be backed up.
includeClusterResources	No	Specify whether to back up all cluster-level resources, such as StorageClasses, CustomResourceDefinitions (CRDs), and webhooks. `true`: back up all cluster-level resources. `false`: back up only cluster-level resources used by namespace-level resources in the specified namespaces. For example, when the system backs up a pod, the service account used by the pod is assigned a cluster role. In this case, the cluster role is automatically backed up. When the system backs up a CustomResource (CR), the corresponding CRD is backed up. Note By default, `IncludeClusterResources` is set to `false` for backup tasks created in the ACK console.
defaultPvBackup	Yes	Specifies whether to back up volumes. Valid values: true: backs up applications and volumes. false: backs up only applications.
storageLocation	Yes	The name of the backup vault. Note If your ACK cluster uses Velero, join DingTalk group 35532895 to request technical support.
ttl	Yes	The validity period of backups. You cannot restore data from expired backups. Specify the time period in the 720h0m0s format. Valid values: 24h0m0s to 1572864h0m0s.

Run the following command in the backup cluster to deploy a backupschedule object:
```
kubectl apply -f backupschedule.yaml
```

Run the following command in the backup cluster to query the status of the scheduled backup task:

kubectl describe backupschedule <yourBackupScheduleName> -n csdr

Expected output:

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

If the backup plan is in the Enabled state, the backup plan is created.

Run the following command in the backup cluster to query the periodically created backups:

kubectl get applicationbackup -n csdr | grep <yourBackupScheduleName>

Expected output:

<yourBackupScheduleName>-20221205225845   2d22h
<yourBackupScheduleName>-20221206040104   2d17h
<yourBackupScheduleName>-20221207040137   41h
<yourBackupScheduleName>-20221208040111   17h

Step 3: Create a restore task

Create a file named applicationrestore.yaml in the restore cluster and add the following content to the file:

apiVersion: csdr.alibabacloud.com/v1beta1
kind: ApplicationRestore
metadata:
  annotations:    
    csdr.alibabacloud.com/backuplocations: >-
      {"name":"<yourBackuplocationName>","region":"cn-beijing","bucket":"<cnfs-oss-yourBucketName>","prefix":"<subDir>","provider":"alibabacloud"}
  name: <yourApplicationRestoreName>
  namespace: csdr
spec:
  appRestoreOnly: false
  preserveNodePorts: true
  includedNamespaces:
    - default
  includedResources:
    - statefulset
  excludedResources:
    - secret
  convertedarg:
  - convertToStorageClassType: alicloud-disk-topology-alltype
    namespace: nas
    persistentVolumeClaim: pvc-nas
  - convertToStorageClassType: alicloud-disk-topology-alltype
    namespace: oss
    persistentVolumeClaim: pvc-oss
  backupName: <yourApplicationBackupName>
  namespaceMapping:
    <backupNamespace>: <restoreNamespace>

The following table describes the parameters that you need to specify. Keep the default setting for other parameters.

Parameter	Required	Description
csdr.alibabacloud.com/backuplocations	Yes	The backup vault that stores the backups. Make sure that the information is the same as the configuration of the backup vault.
name	Yes	The name of the restore task.
appRestoreOnly	No	Specifies whether to restore only applications from backups that contain volume data. Persistent volume claims (PVCs), persistent volumes (PVs), and the relevant data are not restored. Valid values: true: restores only applications. If you want to change the data source where you back up applications, you need to manually create a PVC and PV, create a restore task, and then set this parameter to true. false: restores applications and the relevant volume data. Default value: false.
preserveNodePorts	No	Specifies whether to retain the NodePort of the application. If the backup cluster and restore cluster use the same NodePort, set this parameter to false to change the NodePort to a random port. In other scenarios, set the parameter to true.
includedNamespaces	Yes	The name of the namespace to be restored. If you leave this parameter empty, all namespaces that have been backed up are restored.
includedResources	No	The type of cluster resource to be included in the restore list. Important To ensure that backups are created as expected, specify only one of the following parameters: includedResources and excludedResources. If you leave both parameters empty, all resource types are backed up.
excludedResources	No	The type of cluster resource to be excluded from the restore list. Important To ensure that backups are created as expected, specify only one of the following parameters: includedResources and excludedResources. If you leave both parameters empty, all resource types are backed up.
backupName	Yes	The name of the backup to be restored. If you use the scheduled backup feature, you need to specify the name of a backup that is created at a point in time. Example: <yourBackupScheduleName>-20221205225845.
namespaceMapping	No	This parameter maps the namespace in the backup cluster to a namespace in the restore cluster. Valid values: <backupNamespace>: the namespace of the backups in the backup cluster. <restoreNamespace>: the namespace to which resources are restored in the restore cluster. If you do not specify this parameter, the resources are restored to a namespace that uses the same name as the namespace in the backup cluster. Note If <restoreNamespace> does not exist, the system automatically creates one.
convertedarg	No	The StorageClass conversion list. For volumes of the FileSystem type, such as OSS, NAS, CPFS, and local volumes, you can configure this parameter to convert the StorageClasses of their PVCs to the specified StorageClass during the restoration process. For example, you can convert NAS volumes to disk volumes. convertToStorageClassType: the desired StorageClass. Make sure that the StorageClass exists in the current cluster. You can specify only the disk or NAS StorageClass. namespace: the namespace of the PVC. persistentVolumeClaim: the name of the PVC. You can run the `kubectl -ncsdr describe <backup-name>` command to query the PVC information of a backup. In the returned `status.resourceList.dataResource.pvcBackupInfo` list, the dataType field displays the data type of the PVC, which can be FileSystem or Snapshot. The nameSpace and pvcName fields display the namespace and name of the PVC. Important For ReadWriteMany volumes, restore to disk is not supported. For ReadOnlyMany volumes, when you restore to disk, ensure that replicas are not simultaneously mounted on multiple nodes to avoid forced disk detachment.

Run the following command in the restore cluster to deploy an applicationrestore object:
```
kubectl apply -f applicationrestore.yaml
```

Run the following command in the restore cluster to query the status of the restore task:

kubectl describe applicationrestore <yourApplicationRestoreName> -n csdr

Expected output:

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

When the status of the restore task changes from Inprogress to Completed, the task is created.

Step 4: Delete resources related to the backup center

Important

Other clusters may also use the backup vault that you created. Therefore, the backup center does not allow you to delete the BackupLocation object.

Delete a backup schedule

Run the following schedule to delete the BackupSchedule resource of the backup schedule to stop the backup schedule.

kubectl delete backupschedule <yourBackupSchedule> - ncsdr

Delete a backup task or restore task

Create a file named deleterequest.yaml in the cluster of the task to be deleted and add the following content to the file:

apiVersion: csdr.alibabacloud.com/v1beta1
kind: DeleteRequest
metadata:
  name: <objectName-dbr>
  namespace: csdr
spec:
  deleteObjectName: <objectName>
  deleteObjectType: "Backup"

The following table describes the parameters that you need to specify. Keep the default setting for other parameters.

Parameter	Required	Description
name	Yes	The name of the deletion request. To delete a backup task, specify the request name in the following format: ApplicationBackup name of the backup task+"-dbr". To delete a restore task, specify the request name in the following format: ApplicationRestore name of the restore task+"-dbr".
deleteObjectName	Yes	The name of the resource to be deleted.
deleteObjectType	Yes	The type of resource to be deleted. Valid values: "Backup": deletes the ApplicationBackup object and relevant resources of the backup task. "Restore": deletes the ApplicationRestore object and relevant resources of the restore task. Note Deleting backup tasks does not affect the backups that are created in the cluster. Deleting restore tasks does not affect the data that is restored.

Run the following command in the cluster of the task to be deleted to deploy deleterequest resources:
```
kubectl apply -f deleterequest.yaml
```
Run the following command to query resource status:
- Query the deleted backup task
  - Run the following command to query the status of the backup task:
```
kubectl get applicationbackup <yourApplicationBackupName> -n csdr
```
    Expected output:
```
Error from server (NotFound): applicationbackups.csdr.alibabacloud.com "yourApplicationBackupName" not found
```
    The output indicates that the backup task resources are deleted.
  - Run the following command to query the status of the deleterequest resources:
```
kubectl get deleterequest <yourApplicationBackupName-dbr> -n csdr
```
    Expected output:
```
Error from server (NotFound): deleterequests.csdr.alibabacloud.com "yourApplicationBackupName-dbr" not found
```
    The output indicates that the deleterequest resources are also deleted.
- View the deleted restore task
  - Run the following command to query the status of the restore task:
```
kubectl get applicationrestore <yourApplicationRestoreName> -n csdr
```
    Expected output:
```
Error from server (NotFound): applicationrestores.csdr.alibabacloud.com "yourApplicationRestoreName" not found
```
    The output indicates that the restore task resources are deleted.
  - Run the following command to query the status of the deleterequest resources:
```
kubectl get deleterequest <yourApplicationRestoreName-dbr> -n csdr
```
    Expected output:
```
Error from server (NotFound): deleterequests.csdr.alibabacloud.com "yourApplicationRestoreName-dbr" not found
```
    The output indicates that the deleterequest resources are also deleted.

References

For more information about how to back up and migrate applications in the console, see the following topics:
For more information about how to migrate applications across clusters that use different volume plug-ins and run different Kubernetes versions, see Use the backup center to migrate applications in an ACK cluster that runs an old Kubernetes version.