You are looking at the documentation of a prior release. To read the documentation of the latest release, please visit here.

Local Backend

Local backend refers to a local path inside stash sidecar container. Any Kubernetes supported persistent volume such as PersistentVolumeClaim, HostPath, EmptyDir (for testing only), NFS, gcePersistentDisk etc. can be used as local backend.

In order to use Kubernetes volumes as backend, you have to create a Secret and a Repository object pointing to the desired volume.

Create Storage Secret

To configure storage secret for local backend, following secret keys are needed:

KeyTypeDescription
RESTIC_PASSWORDRequiredPassword that will be used to encrypt the backup snapshots

Create storage secret as below,

$ echo -n 'changeit' > RESTIC_PASSWORD
$ kubectl create secret generic -n demo local-secret --from-file=./RESTIC_PASSWORD
secret/local-secret created

Create Repository

Now, you have to create a Repository crd that uses Kubernetes volume as a backend. You have to provide the storage secret that we have created earlier in spec.backend.storageSecretName field.

Following parameters are available for Local backend.

ParameterTypeDescription
local.mountPathRequiredPath where this volume will be mounted inside the sidecar container. Example: /safe/data.
We have put stash binary in the root directory. Hence, you can not use /stash or /stash/* as local.mountPath
local.subPathOptionalSub-path inside the referenced volume where the backed up snapshot will be stored instead of its root.
local.VolumeSourceRequiredAny Kubernetes volume. Can be specified inlined. Example: hostPath.

Here, we are going to show some sample Repository crds that uses different Kubernetes volume as a backend.

HostPath volume as Backend

Below, the YAML of a sample Repository crd that uses a hostPath volume as a backend.

apiVersion: stash.appscode.com/v1alpha1
kind: Repository
metadata:
  name: local-repo-with-hostpath
  namespace: demo
spec:
  backend:
    local:
      mountPath: /safe/data
      hostPath:
        path: /data/stash-test/repo
    storageSecretName: local-secret

Create the Repository we have shown above using the following command,

$ kubectl apply -f https://github.com/stashed/docs/raw/v2024.2.13/docs/guides/backends/local/examples/hostPath.yaml
repository/local-repo-with-hostpath created

Note that by default, Stash runs as non-root user. hostPath volume is writable only for root user. So, in order to use hostPath volume as backend, either you have to run Stash as root user using securityContext or you have to change the permission of the hostPath to make it writable for non-root users.

PersistentVolumeClaim as Backend

Below, the YAML of a sample Repository crd that uses a PersistentVolumeClaim as a backend.

apiVersion: stash.appscode.com/v1alpha1
kind: Repository
metadata:
  name: local-repo-with-pvc
  namespace: demo
spec:
  backend:
    local:
      mountPath: /safe/data
      persistentVolumeClaim:
        claimName: repo-pvc
    storageSecretName: local-secret

Create the Repository we have shown above using the following command,

$ kubectl apply -f https://github.com/stashed/docs/raw/v2024.2.13/docs/guides/backends/local/examples/pvc.yaml
repository/local-repo-with-pvc created
NFS volume as Backend

Below, the YAML of a sample Repository crd that uses an NFS volume as a backend.

apiVersion: stash.appscode.com/v1alpha1
kind: Repository
metadata:
  name: local-repo-with-nfs
  namespace: demo
spec:
  backend:
    local:
      mountPath: /safe/data
      nfs:
        server: "nfs-service.storage.svc.cluster.local" # use you own NFS server address
        path: "/" # this path is relative to "/exports" path of NFS server
    storageSecretName: local-secret

Create the Repository we have shown above using the following command,

$ kubectl apply -f https://github.com/stashed/docs/raw/v2024.2.13/docs/guides/backends/local/examples/nfs.yaml
repository/local-repo-with-nfs created

For NFS backend, Stash may have to run the network volume accessor deployments in privileged mode to provide Snapshot listing facility. In this case, please configure network volume accessors by following the instruction here.

GCE PersitentDisk as Backend

Below, the YAML of a sample Repository crd that uses a gcePersistentDisk as a backend.

apiVersion: stash.appscode.com/v1alpha1
kind: Repository
metadata:
  name: local-repo-with-gcepersistentdisk
  namespace: demo
spec:
  backend:
    local:
      mountPath: /safe/data
      gcePersistentDisk:
        pdName: stash-repo
        fsType: ext4
    storageSecretName: local-secret

Create the Repository we have shown above using the following command,

$ kubectl apply -f https://github.com/stashed/docs/raw/v2024.2.13/docs/guides/backends/local/examples/gcePersistentDisk.yaml
repository/local-repo-with-gcepersistentdisk created

In order to use gcePersistentDisk volume as backend, the node where stash container is running must be a GCE VM and the VM must be in same GCE project and zone as the Persistent Disk.

AWS EBS volume as Backend

Below, the YAML of a sample Repository crd that uses an awsElasticBlockStore as a backend.

apiVersion: stash.appscode.com/v1alpha1
kind: Repository
metadata:
  name: local-repo-with-awsebs
  namespace: demo
spec:
  backend:
    local:
      mountPath: /safe/data
      awsElasticBlockStore: # This AWS EBS volume must already exist.
        volumeID: <volume-id>
        fsType: ext4
    storageSecretName: local-secret

Create the Repository we have shown above using the following command,

$ kubectl apply -f https://github.com/stashed/docs/raw/v2024.2.13/docs/guides/backends/local/examples/awsElasticBlockStore.yaml
repository/local-repo-with-awsebs created

In order to use awsElasticBlockStore volume as backend, the pod where stash container is running must be running on an AWS EC2 instance and the instance must be in the same region and availability-zone as the EBS volume.

Azure Disk as Backend

Below, the YAML of a sample Repository crd that uses an azureDisk as a backend.

apiVersion: stash.appscode.com/v1alpha1
kind: Repository
metadata:
  name: local-repo-with-azuredisk
  namespace: demo
spec:
  backend:
    local:
      mountPath: /safe/data
      azureDisk:
        diskName: stash.vhd
        diskURI: https://someaccount.blob.microsoft.net/vhds/stash.vhd
    storageSecretName: local-secret

Create the Repository we have shown above using the following command,

$ kubectl apply -f https://github.com/stashed/docs/raw/v2024.2.13/docs/guides/backends/local/examples/azureDisk.yaml
repository/local-repo-with-azuredisk created
StorageOS as Backend

Below, the YAML of a sample Repository crd that uses a storageOS volume as a backend.

apiVersion: stash.appscode.com/v1alpha1
kind: Repository
metadata:
  name: local-repo-with-storageos
  namespace: demo
spec:
  backend:
    local:
      mountPath: /safe/data
      storageos:
        volumeName: stash-vol01 # The `stash-vol01` volume must already exist within StorageOS in the `demo` namespace.
        fsType: ext4
    storageSecretName: local-secret

Create the Repository we have shown above using the following command,

$ kubectl apply -f https://github.com/stashed/docs/raw/v2024.2.13/docs/guides/backends/local/examples/storageOS.yaml
repository/local-repo-with-storageos created
EmptyDir volume as Backend

Below, the YAML of a sample Repository crd that uses an emptyDir as a backend.

apiVersion: stash.appscode.com/v1alpha1
kind: Repository
metadata:
  name: local-repo-with-emptydir
  namespace: demo
spec:
  backend:
    local:
      mountPath: /safe/data
      emptyDir: {}
    storageSecretName: local-secret

Create the Repository we have shown above using the following command,

$ kubectl apply -f https://github.com/stashed/docs/raw/v2024.2.13/docs/guides/backends/local/examples/emptyDir.yaml
repository/local-repo-with-emptydir created

Warning: Data of an emptyDir volume is not persistent. If you delete the pod that runs the respective stash container, you will lose all the backed up data. You should use this kind of volumes only to test backup process.

Next Steps

  • Learn how to use Stash to backup workloads data from here.
  • Learn how to use Stash to backup databases from here.
  • Learn how to use Stash to backup stand-alone PVC from here.