Restore
This chapter describes the APIs that can be used to perform a Kubernetes cluster restore.
Listing available recovery points
GET /api/v1/backupinstances?where={"state":"READY"}
{
"_items": [
{
"_created": "Fri, 09 Oct 2020 21:05:44 GMT",
"_etag": "13efb5b5cc8fc5766e5270c835e3e852381b60a3",
"_id": "5f80d0a8f281487d59c69f5e",
"_links": {
"related": {
"backupdef": {
"href": "/v1/kubebackups/5f80d0a511556131dd9894e5",
"title": "Kubebackup"
},
"cluster": {
"href": "/v1/kubeclusters/5f80d09ff281487d59c69f5b",
"title": "Kubecluster"
}
},
"self": {
"href": "/v1/backupinstances/5f80d0a8f281487d59c69f5e",
"title": "Backupinstance"
}
},
"_updated": "Fri, 09 Oct 2020 21:05:54 GMT",
"backup_selection": {
"all_namespaces": true,
"snapshotPersistentVolumes": true
},
"backupdef": "5f80d0a511556131dd9894e5",
"backupdef_name": "testbackup",
"cluster": "5f80d09ff281487d59c69f5b",
"cluster_name": "testcluster",
"pv_count": 2,
"end_time": 1602277553,
"name": "backupinst-1602277544",
"type": "COPY",
"source_type": "kubernetes",
"start_time": 1602277544,
"state": "READY",
...
}
],
"_links": {
"parent": {
"href": "/",
"title": "home"
},
"self": {
"href": "v1/backupinstances",
"title": "/v1/backupinstances"
}
},
"_meta": {
"max_results": 25,
"page": 1,
"total": 1
}
}
Apart from the standard properties such as name, the following properties are present in the backup instance resource:
- type
String. Type of this recovery point. Possible values are [“SNAPSHOT”, “COPY”].
- source_type
String. Source type of this recovery point. Possible values are [“kubernetes”, “awsrds”].
“kubernetes”: This recovery point is related to Kubernetes backup
“awsrds”: This recovery point is related to RDS backup
- start_time
Integer. Start time of the job expressed as number of seconds elapsed since January 1, 1970 UTC.
- end_time
Integer. End time of the job expressed as number of seconds elapsed since January 1, 1970 UTC.
- state
String. Clients should only request backup instances in “READY” state.
- cluster
ID of the Kubernetes cluster that is backed up.
- cluster_name
Name of the cluster that is backed up.
- pv_count
Number of PVs that are available for restore in a given recovery point.
- backupdef
ID of the “kubebackup” resource corresponding to the backup.
- backupdef_name
Name of the “kubebackup” resource corresponding to the backup.
- backup_selection
This is same as the “source” field in the “kubebackups” resource corresponding to the backup.
Note
Note that a tuple of “type” and “source_type” should be used to identify the type of backup instance. For example, a backupinstance resource with “type” = “COPY”, AND, “source_type” = “kubernetes” defines this recovery point to be a Kubernetes backup from a COPY/OFFLOAD operation.
Filtering by time
It is possible to use filtering to limit the list of recovery points to a given day or week or any time frame. Here is an example:
GET /api/v1/backupinstances?where={"state":"READY",
"start_time":{"$gt":1601646625,"$lt":1601647286}}
So if you want to find all recovery points in the month of September 2020, build the timestamps (number of seconds elapsed since January 1, 1970 UTC) for beginning and end of the day and then use the query similar to above.
Similar logic can be used to find recovery points for a given week or month.
Listing namespaces in a backup
GET /api/v1/kubenamespaces?where={"backupinst_id":"5f80d1fecea44311f78bdb63"}
The response would be same as what is returned in the API to list namespaces of a cluster. The only difference would be the presence of “backupinst_id” filed in each “kubenamespace” resource.
Listing Persistent Volumes in a backup
GET /api/v1/kubepvclaims?where={"backupinst_id":"5fb37ad251ba23c69264dd99"}
The response would be same as what is returned in the API to list persistent volume claims of a cluster. The only difference would be the presence of “backupinst_id” filed in each “kubepvclaim” resource. There are additional fields related to the backup of PV in this response.
HTTP/1.1 200 OK
{
"_items": [
{
"_created": "Tue, 17 Nov 2020 07:25:14 GMT",
"_etag": "41c158c443c1eb1a551c97056f76b99de38df428",
"_id": "5fb37ada17ed74cb280d577f",
"_links": {
"related": {
"backupinst_id": {
"href": "/v1/backupinstances/5fb37ad251ba23c69264dd99",
"title": "Backupinstance"
},
"cluster_id": {
"href": "/v1/kubeclusters/5fb37a2617ed74cb280d577e",
"title": "Kubecluster"
}
},
"self": {
"href": "/v1/kubepvclaims/5fb37ada17ed74cb280d577f",
"title": "Kubepvclaim"
}
},
"_updated": "Tue, 17 Nov 2020 07:25:14 GMT",
"backupinst_id": "5fb37ad251ba23c69264dd99",
"cluster_id": "5fb37a2617ed74cb280d577e",
"driver": "hostpath.csi.k8s.io",
"name": "csi-pvc",
"namespace_name": "test-csi-snapshot",
"restore_size": 52428800,
"snapshot_handle": "051c4f9c-28a6-11eb-a892-0242ac120004",
"snapshot_taken": true,
"volume_handle": "669f1f8a-28a5-11eb-a892-0242ac120004",
"volume_snapshot_class_name": "csi-hostpath-snapclass",
"volume_type": "CSI"
}
],
"_links": {
"parent": {
"href": "/",
"title": "home"
},
"self": {
"href": "v1/kubepvclaims?where={\"backupinst_id\": \"5fb37ad251ba23c69264dd99\"}",
"title": "/v1/kubepvclaims"
}
},
"_meta": {
"max_results": 1000,
"page": 1,
"total": 1
}
}
Listing storage classes in backup instance
POST /api/v1/backupinstances/61a88c3b835f2d0a8152f443/action/list-storage-classes
{
"namespaces": [
"nginx-example",
"test-csi-snapshot"
]
}
The response will contain list of storage classes used backup PVCs if given backup instance.
This API accepts usual page and max_results pagination parameters. Otherwise, default values will be used.
HTTP/1.1 200 OK
{
"_items": [
{
"storage_class_name": "csi-storageclass",
"driver": "hostpath.csi.k8s.io"
}
]
}
Note: If the request body or the namespace list is passed empty then the API will return all storage classes for the PVCs in backup instance.
Listing resource types available for restore
GET /api/v1/backupinstances/61a88c3b835f2d0a8152f443/resource-types
The response will contain list of resource types as follows:
HTTP/1.1 200 OK
{
"_items": [
"secrets",
"deployments",
"pods"
]
}
Listing labels in a backup
The backup instance resource contains a field called “backup_selection”. It is the exact value of “source” as set in the “kubebackup” resource. In other words, any selection in the backup is available in backup instance resource in the field “backup_selection”. This is the way in which labels selected by the user for the backup can be accessed from backup instances.
For example, here is one possible backup selection with labels:
"backup_selection": {
"label_selector": {
"app": "nginx"
}
}
Note that selecting labels in backup definition is optional so you will find labels in the field “backup_selection” only if there were part of backup.
Defining restore
Restore definition works very similar to how a backup is defined.
POST /api/v1/kuberestores
{
"backup_inst": "5f835618ceeabae22999d468",
"name": "testrestore",
"namespaces_map": {
"kube-system": "new-kube-system"
},
"namespaces_prefix": "abc-",
"namespaces_suffix": "-def",
"selection": {
"all_namespaces": true
}
}
201 CREATED
...
...
Schema
- backup_inst
Required. ID of the backup instance that is being restored from.
- cluster
Optional. ID of the cluster where restore needs to be done. If not given, cluster from the backup is used.
- namespaces_prefix
Optional. String. When given, the value is prepended to all namespaces that are being restored.
- namespaces_suffix
Optional. String. When given, the value is appended to all namespaces that are being restored.
- namespaces_map
Optional. A mapping of backup to target namespace names.
If a namespace is present in the map, the value from the map is used as target namespace name. If it is not present, then the values of “namespaces_suffix” and “namespaces_prefix” will be used, if given.
- storage_class_map
Optional. A mapping of old storage classes to new storage classes.
The storage_class_map is key value pair where key is old storage class and value is new storage class. If storage class mapping has been provided by the user in restore definition then the old storage classes used in PVCs will be replaced by the new storage classes. The new storage classes can have different configurations from the ones at the backup time but they must use CSI drivers.
- selection
Required. Definition of what needs to be restored.
Note
Note that prefix, suffix, and a new namespace must be valid DNS Label Name.
selection schema
- all_namespaces
Boolean. Optional. If set to true, all namespaces from the backup are restored. In this case, values passed in “namespaces” field, if any, will be ignored.
- namespaces
Optional. List of namespace names (not IDs) that need to be restored.
- label_selector
Optional. A map of label key and value pairs.
A map of label key and “,” separated values to support OR set based operation.
When multiple key-value specified then it will be AND-ED together.
- restorePersistentVolumes
Boolean. Default is True. When set to true, the restore will include volumes that were backed up.
- include_resource_types
Optional. List of resource types to be restored.
Restores only specific resource types passed in the list (e.g secrets, deployments).
Some examples of “selection”:
Restore everything:
"selection": {
"all_namespaces": true
}
Restore few namespaces:
"selection": {
"namespaces": [
"appns1",
"appns2"
]
}
Restore with label selectors:
"selection": {
"label_selector": {
"app": "nginx"
}
}
"selection": {
"label_selector": {
"app": "nginx,wordpress"
}
}
"selection": {
"label_selector": {
"tier": "frontend",
"app": "nginx,wordpress"
}
}
Restore specific resource types:
"selection": {
"include_resource_types": [
"secrets",
"deployments"
]
}
Some examples of “storage_class_map”:
"storage_class_map": {
"csi-storageclass": "csi-storageclass-new"
}
Response will also contain “status” field with the following schema. Note that “status” may not appear immediately so client will need to poll until it sees the field.
- state
String. Possible values are “PENDING”, “FAILED”, “JOB_CREATED”.
- source_cluster
ID of the cluster from where backup is taken.
- jobid
String. ID of the job.
- message
String
Running a Restore
Defining a restore resource doesn’t do anything other than saving the resource data. To perform restore, the following “run” API needs to be invoked.:
POST /api/v1/kuberestores/<ID>/action/run
No input data is needed for the API.
Deleting a restore
DELETE /api/v1/kuberestores/<ID>
Note
Delete will fail if there is a running job corresponding to the restore resource.