You are looking at the documentation of a prior release. To read the documentation of the latest release, please
visit here.
New to Stash? Please start here.
Snapshot
What is Snapshot
A Snapshot
is a representation of restic backup snapshot in a Kubernetes native way. With the help of Aggregated API Servers, Stash provides the users a way to view
,list
and delete
snapshots from restic repositories. Now, a user can view some crucial information of snapshots like creationTimestamp
, snapshot id
, backed up path
etc. In future, this will enable the users to recover a particular snapshot using stash.
Snapshot structure
A sample Snapshot
object’s structure created by backing up a Deployment
is shown below,
apiVersion: repositories.stash.appscode.com/v1alpha1
kind: Snapshot
metadata:
creationTimestamp: 2018-04-09T06:43:03Z
labels:
repository: deployment.stash-demo
restic: stash-demo
workload-kind: Deployment
workload-name: stash-demo
name: deployment.stash-demo-11156792
namespace: default
selfLink: /apis/repositories.stash.appscode.com/v1alpha1/namespaces/default/snapshots/deployment.stash-demo-11156792
uid: 11156792ffe5a52ef076c4e7c74f79a4e6ad6f8d4d2a8a078cf9ee507a8f360c
status:
gid: 0
hostname: stash-demo
paths:
- /source/data
tree: ab2311afd593e5ef6f95df652215c9d1102b1731b72e2784386350ae95f1a145
uid: 0
username: ""
Here, we are going to describe some important sections of Snapshot
object.
Snapshot Name
name
filed in metadata
of a Snapshot
object represent its name. It follows this pattern,
<respective repository crd name>-<first 8 digits of snapshot id>
Snapshot UID
uid
field in metadata
of Snapshot
object represents complete restic snapshot id.
CreationTimestamp
creationTimestamp
in metadata
field of a Snapshot
object represents the time when the snapshot was created.
Snapshot Labels
A Snapshot
object maintains some important information using labels. These labels enable a user to filter Snapshot
according to repository
, restic
, workload-kind
, workload-name
, node-name
etc. Details of these labels are given below.
Label name | Description |
---|---|
repository | Name of the Repository where this Snapshot is stored. |
restic | Name of the Restic which is responsible for this Snapshot . |
workload-kind | Kind of the workload for which the Snapshot has been created. |
workload-name | Name of the workload for which the Snapshot has been created. |
pod-name | This label present when the respective workload is StatefulSet . It represents the pod name of the StatefulSet who is responsible for this Snapshot . |
node-name | This label present when the respective workload is DaemonSet . It represents the node name where the DaemonSet is running. |
Snapshot Status
Snapshot
object has following status fields,
status.gid
indicates the group identifier of the user who took this backup.status.hostname
indicates the name of the host object whose data is backed up in this snapshot. ForDeployment
,ReplicaSet
andReplicationController
it is workload name. ForDaemonSet
hostname is node name and forStatefulSet
hostname is pod name.status.path
indicates the path that is backed up in this snapshot.status.tree
indicatestree
of the restic snapshot. For more details see here.status.uid
indicates id of the user who took this backup. Forroot
user it is 0.status.username
indicates the name of the user.status.tags
indicates tags of the snapshot.
Working with Snapshot
Listing Snapshots:
# List Snapshots of all repositories in the current namespace
$ kubectl get snapshot
# List Snapshots of a particular repository
$ kubectl get snapshot -l repository=deployment.stash-demo
# List all Snapshots of a particular workload type
$ kubectl get snapshot -l workload-kind=Deployment
# List Snapshots of a particular workload
$ kubectl get snapshot -l workload-name=stash-demo
# List all Snapshots created by a particular restic
$ kubectl get snapshot -l restic=stash-demo
# List Snapshots of a particular pod(only for StatefulSet)
$ kubectl get snapshot -l pod-name=stash-demo-0
# List Snapshots of a particular node(only for DaemonSet)
kubectl get snapshot -l node-name=minikube
# List Snapshot of specific repositories
$ kubectl get snapshot -l 'repository in (deployment.stash-demo,statefulset.stash-demo-0)'
Viewing information of a particular Snapshot:
$ kubectl get snapshot <snapshot name> -o yaml
# Example:
$ kubectl get snapshot deployment.stash-demo-3d8cd994 -o yaml
apiVersion: repositories.stash.appscode.com/v1alpha1
kind: Snapshot
metadata:
creationTimestamp: 2018-04-09T10:06:04Z
labels:
repository: deployment.stash-demo
restic: stash-demo
workload-kind: Deployment
workload-name: stash-demo
name: deployment.stash-demo-3d8cd994
namespace: default
selfLink: /apis/repositories.stash.appscode.com/v1alpha1/namespaces/default/snapshots/deployment.stash-demo-3d8cd994
uid: 3d8cd994a3bddcff1d16ac166601d93454d0eb31e2240801e7c1ec030e5af0bf
status:
gid: 0
hostname: stash-demo
paths:
- /source/data
tree: ab2311afd593e5ef6f95df652215c9d1102b1731b72e2784386350ae95f1a145
uid: 0
username: ""
Deleting a particular Snapshot:
$ kubectl delete snapshot <snapshot name>
# Example:
$ kubectl delete snapshot statefulset.stash-demo-0-d690726d
snapshot "statefulset.stash-demo-0-d690726d" deleted
Precondition for Snaphsot
- Stash provides
Snapshots
listing facility with the help of aggregated api server. Stash start aggregated api server if any of theValidatingWebhook
andMutatingWebhook
is enabled. If both of the webhooks are disabled or if your cluster does not support aggregated api server or webhooks, you won’t able to listSnapshot
. - If you are using
hostPath
forRestic
backend, stash takes help of workload pod to provide snapshot list. In this case, workload pod must be running while listingSnapshot
. - If you are using offline backup and
hostPath
as yourRestic
backend, you won’t able to listSnapshot
.
Next Steps
- Learn how to use Stash to backup a Kubernetes deployment here.
- To restore a backup see here.
- Learn about the details of Recovery CRD here.
- To run backup in offline mode see here
- See the list of supported backends and how to configure them here.
- See working examples for supported workload types here.
- Thinking about monitoring your backup operations? Stash works out-of-the-box with Prometheus.
- Learn about how to configure RBAC roles.
- Want to hack on Stash? Check our contribution guidelines.