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.

Stash kubectl Plugin

Stash gives you kubectl plugin support named kubectl stash cli. kubectl stash cli can be used to manage Stash objects quickly and easily. It performs various operations like creating Stash objects, coping Stash objects, cloning PVC, unlock Repository, triggering an instant backup, etc. To install Stash kubectl plugin on your workstation, follow the steps here.

Available Command

Available command for kubectl stash cli are:

Main CommandUses
create repositoryCreate a new Repository.
create backupconfigCreate a new BackupConfiguration.
create restoresessionCreate a new RestoreSession.
cp secretCopy Secret from source namespace to destination namespace.
cp repositoryCopy Repository from source namespace to destination namespace.
copy backupconfigCopy BackupConfiguration from source namespace to destination namespace.
copy volumesnapshotCopy VolumeSnapshot from source namespace to destination namespace.
clone pvcClone a PVC from source namespace to destination namespace.
downloadDownload backup snapshots from backend into your local repository.
triggerTake an instant backup.
pause backupPause Stash backup.
resume backupResume Stash backup.
debug backupDebug Stash backup issues.
debug restoreDebug Stash restore issues.
debug operatorDebug Stash operator issues.

Create Command

kubectl stash create command is used to create stash objects. It creates various objects like Repository, BackupConfiguration and RestoreSession etc.

Create Repository

To create a Repository, you need to provide a Repository name and backend information and credential. You will provide the information and credential by using flags. The available flags are:

FlagDescription
--namespaceIndicates the namespace where the Repository will be created
--secretSpecify the name of the storage secret that will be used to create Repository
--bucketSpecify the name of the cloud bucket/container.
--prefixPrefix denotes the directory inside the backend.
--providerSpecify backend provider (i.e. gcs, s3, azure etc)
--endpointEndpoint for s3/s3 compatible backend
--max-connectionsSpecify maximum concurrent connections for GCS, Azure and B2 backend.

Format:

kubectl stash create <repository-name> [flags]

Example:

$ kubectl stash create repository gcs-repo --namespace=demo --secret=gcs-secret --bucket=appscode-qa --prefix=/source/data --provider=gcs

Create BackupConfiguration

To create a BackupConfiguration, you need to provide BackupConfiguration name, Repository name, Target, and RetentionPolicy, etc. You will provide the Repository name, Target, RetentionPolicy by using flags. The available flags are:

FlagDescription
--namespaceIndicates the namespace where the BackupConfiguration will be created
--target-apiversionSpecify API-Version of the target resource.
--target-kindSpecify kind of the target resource.
--target-nameSpecify name of the target resource.
--repositorySpecify name of the Repository that will be created.
--scheduleSpecify schedule of the backup.
--driverDriver indicates the mechanism used to backup (i.e. VolumeSnapshotter, Restic)
--taskSpecify name of a Task
--volumesnpashotclassSpecify name of the VolumeSnapshotClass.
--replicaReplica specifies the number of replicas whose data should be backed up.
--pathsA list of path that will be backed up
--volume-mountsSpecify a list of volumes and their mountPaths
--keep-lastNever delete the n last (most recent) snapshots.
--keep-hourlyFor the last n hours in which a snapshot was made, keep only the last snapshot for each hour.
--keep-dailyFor the last n days which have one or more snapshots, only keep the last one for that day.
--keep-weeklyFor the last n weeks which have one or more snapshots, only keep the last one for that week.
--keep-monthlyFor the last n months which have one or more snapshots, only keep the last one for that month.
--keep-yearlyFor the last n years which have one or more snapshots, only keep the last one for that year.
--pruneIf set true, Stash will cleanup unreferenced data from the backend.
--dry-runStash will not remove anything but print which snapshots would be removed.

Note: You must provide <volumenName>:<mountPath>:<subPath> in the --volume-mounts flag to specify the volumes and their mountPath and subPath. The :<subPath> part is optional.

Format:

kubectl stash create <backupconfig-name> [flags]

Example:

$ kubectl stash create backupconfig ss-backup --namespace=demo --repository=gcs-repo --schedule="*/4 * * * *" --target-apiversion=apps/v1 --target-kind=StatefulSet --target-name=stash-demo --paths=/source/data --volume-mounts=source-data:/source/data --keep-last=5 --prune=true

Create RestoreSession

To create a RestoreSession, you need to provide a Repository name, Target or VolumeClaimTemplate, etc. You will provide the Repository name, Target or VolumeClaimTemplate by using flags. The available flags are:

FlagDescription
--namespaceIndicates the namespace where the RestoreSession will be created
--target-apiversionAPI-Version of the target resource.
--target-kindSpecify kind of the target resource.
--target-nameSpecify name of the target resource.
--repositoryspecify name of the Repository.
--driverDriver indicates the mechanism used to backup (i.e. VolumeSnapshotter, Restic)
--taskName of the Task
--replicaReplica specifies the number of replicas whose data should be backed up.
--pathsA list of path that will be backed up
--volume-mountsA list of volumes and their mountPaths
--snapshotsSpecify the name of the Snapshot(single)
--hostSpecify the name of the Source host
--claim.nameSpecify the name of the VolumeClaimTemplate
--claim.access-modesAccess mode of the VolumeClaimTemplates
--claim.storageclassSpecify the name of the Storage secret for VolumeClaimTemplate
--claim.sizeTotal requested size of the VolumeClaimTemplate
--claim.datasourceDataSource of the VolumeClaimTemplate

Note: You must provide <volumenName>:<mountPath>:<subPath> in the --volume-mounts flag to specify the volumes and their mountPath and subPath. The :<subPath> part is optional.

Format:

kubectl stash create restoresession <restoresession-name> [flags]

Example:

$ kubectl stash create restoresession ss-restore --namespace=demo --repository=gcs-repo --target-apiversion=apps/v1 --target-kind=StatefulSet --target-name=stash-recovered --paths=/source/data --volume-mounts=source-data:/source/data

Copy Command

kubectl stash cp command is used to copy stash objects from one namespace to another namespace. It copies various objects like Secret, Repository, BackupConfiguration and VolumeSnapshot etc.

Copy Secret

To copy a Secret, you need to provide Secret name and destination namespace. You will provide the destination namespace by using flag. The available flags are:

FlagDescription
--namespaceIndicates the namespace of the respective Secret.
--to-namespaceIndicates the destination namespace where the Secret will be copied.

Format:

kubectl stash cp secret <secret-name> [flags]

Example:

$ kubectl stash cp secret my-secret --namespace=demo --to-namespace=demo1

Copy Repository

To copy a Repository, you need to provide a Repository name and destination namespace. When we run the command the coping process consists of the following steps:

  • At first, the cli copies Secret from source namespace to destination namespace.
  • Then it copies Repository from source namespace to destination namespace.

You will provide the destination namespace by using flag. The available flags are:

FlagDescription
--namespaceIndicates the namespace of the respective Repository.
--to-namespaceIndicates the destination namespace where the Repository will be copied.

Format:

kubectl stash cp repository <repository-name> [flags]

Example:

$ kubectl stash cp repository my-repo --namespce=demo --to-namespace=demo1

Copy BackupConfiguration

To copy a BackupConfiguration, you need to provide BackupConfiguration name and destination namespace. When we run the command the coping process consists of the following steps:

  • At first, the cli copies Secret from source namespace to destination namespace.
  • Then it copies Repository from source namespace to destination namespace.
  • finally it copies BackupConfiguration from source namespace to destination namespace.

You will provide the destination namespace by using flags. The available flags are:

FlagDescription
--namespaceIndicates the namespace of the respective BackupConfiguration.
--to-namespaceIndicates the destination namespace where the BackupConfiguration will be copied.

Format:

kubectl stash cp backupconfig <backupconfig-name> [flags]

Example:

$ kubectl stash cp backupconfig my-backupconfig --namespace=demo --to-namespace=demo1

Copy VolumeSnapshot

To copy a VolumeSnapshot, you need to provide VolumeSnapshot name and destination namespace. You will provide the destination namespace by using flag. The available flags are:

FlagDescription
--namespaceIndicates the namespace of the respective VolumeSnapshot.
--to-namespaceIndicates the destination namespace where the VolumeSnapshot will be copied.

Example:

$ kubectl stash cp volumesnapshot my-vol-snap --namespace=demo --to-namespace=demo1

Clone PVC

kubectl stash clone pvc command is used to clone PVC from one namespace to another namespace. When we run the command the cloning process consists of the following steps:

  • At first, It creates a Repository in the source namespace.
  • Using this repository, it creates a BackupConfiguration targeting the PVC to take backup.
  • After the backup process succeeded, It copies Repository to the destination namespace
  • finally, It restores the backed up data into VolumeClaimTemplate in the destination namespace.

To clone a PVC, you need to provide backend credentials for creating Repository. You will provide the backend credential by using flags. The available flags are:

FlagDescription
--namespaceIndicates namespace of the respective pvc.
--to-namespaceIndicates the destination namespace where the PVC will be cloned.
--secretSpecify the name of the storage secret that will be used to create Repository
--bucketSpecify the name of the cloud bucket/container.
--prefixPrefix denotes the directory inside the backend.
--providerSpecify backend provider (i.e. gcs, s3, azure etc)
--endpointEndpoint for s3/s3 compatible backend
--max-connectionsSpecify maximum concurrent connections for GCS, Azure and B2 backend.

Format:

kubectl stash clone pvc <pvc-name> [flags]

Example:

$ kubectl stash clone pvc my-pvc -n demo --to-namespace=demo-1 --secret=<secret> --bucket=<bucket> --prefix=<prefix> --provider=<provider>

Download Snapshots

kubectl stash download command is used to download the snapshots from backend repository into your local machine. To download the snapshots you have to provide Repository name, download directory and snapshot list. You will provide the download directory and snapshot list using flags. The available flags are:

FlagDescription
--namespaceIndicates the namespace of the respective Repository.
--destinationIndicates the local directory where the snapshots will be downloaded.
--snapshotsSpecifies the list of snapshots. (Provide a list of snapshot ID)

Format:

kubectl stash download <repository-name> [flags]

Example:

$ kubectl stash download gcs-repo --namespace=demo --destination=/home/downloads/ --snapshots="19eb4793,b7244d52"

Use kubectl get snapshots to get the available snapshots.

Trigger an Instant Backup

kubectl stash trigger command is used to take an instant backup in stash. To trigger an instant backup, you need to have a BackupConfiguration in your cluster. You need to provide the BackupConfiguration name. You can also provide the namespace by using the --namespace flag. This flag indicates the namespace where the trigger backup will be occurred.

Format:

$ kubectl stash trigger <backupconfig-name>[flags]

Example:

$ kubectl stash trigger my-config --namespace=demo

Unlock Repository

kubectl stash unlock are used to remove lock from the backend repository. To unlock the Repository, you need to provide a Repository name. You can also provide the namespace by using the --namespace flag. This flag indicates the Repository namespace.

Format:

kubectl stash unlock <repository-name> [flags]

Example:

$ kubectl stash unlock my-repo --namespace=demo

Pause Command

kubectl stash pause command is used to pause Stash backup temporarily.

Pause Backup

To pause a backup you have to provide the BackupConfiguration name or BackupBatch name by using flags. The available flags are:

FlagDescription
--namespaceIndicates the namespace of the respective BackupConfiguration or BackupBatch.
--backupconfigName of the BackupConfiguration.
--backupbatchName of the BackupBatch.

Format:

kubectl stash pause backup [flags]

Example:

$ kubectl stash pause backup --namespace=demo --backupconfig=my-config

Resume Backup

To resume a backup you have to provide the BackupConfiguration name or BackupBatch name by using flags. The available flags are:

FlagDescription
--namespaceIndicates the namespace of the respective BackupConfiguration or BackupBatch.
--backupconfigName of the BackupConfiguration.
--backupbatchName of the BackupBatch.

Format:

kubectl stash resume backup [flags]

Example:

$ kubectl stash resume backup --namespace=demo --backupconfig==my-config

Debug Command

kubectl stash debug command is used to debug stash resources. This command describes the necessary resources and shows logs from the related pods which makes the debugging process quicker and easier.

Debug Backup

To debug a backup you have to provide the BackupConfiguration name or BackupBatch name by using flags. The available flags are:

FlagDescription
--namespaceIndicates the namespace of the respective BackupConfiguration or BackupBatch.
--backupconfigName of the BackupConfiguration.
--backupbatchName of the BackupBatch.

Format:

kubectl stash debug backup [flags]

Example:

$ kubectl stash debug backup --namespace=demo --backupconfig=my-config

Debug Restore

To debug a restore you have to provide the RestoreSession name or RestoreBatch name by using flags. The available flags are:

FlagDescription
--namespaceIndicates the namespace of the respective RestoreSession or RestoreBatch.
--restoresessionName of the RestoreSession.
--restorebatchName of the RestoreBatch.

Format:

kubectl stash debug restore [flags]

Example:

$ kubectl stash debug restore --namespace=demo --restoresession=my-restore