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.
triggerUsed to take an instant backup.
unlockUsed to unlock a Remote Repository.

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 source namespace where the Secret has existed.
--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 source namespace where the Repository has existed.
--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 source namespace where the BackupConfiguration has existed.
--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 source namespace where the VolumeSnapshot has existed.
--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 the source namespace where the pvc has existed.
--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>

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