Stash Documentation

Stash is a cloud-native data backup and recovery solution for Kubernetes workloads. It operates as a Kubernetes operator that leverages restic or Kubernetes CSI Driver VolumeSnapshotter functionality.

Stash allows you to:

• Backup Kubernetes volumes mounted in workloads (Deployments, DaemonSets, StatefulSets, etc.).
• Backup stand-alone volumes (PersistentVolumeClaims and PersistentVolumes).
• Backup and restore databases (available in Enterprise Edition).
• Extend functionality for custom workloads using addons.

To run the Stash service, you must use the StashConfig type to provide both a GenericConfig (for the Kubernetes API server) and an ExtraConfig (for the Stash controller).

Follow this pattern to initialize the server:

1. Populate a StashConfig object.
2. Call Complete() on the config to get a CompletedConfig.
3. Call New() on the CompletedConfig to instantiate the StashServer.
4. Call Run(ctx) on the resulting StashServer to start the controller and the API server.

StashConfig is the initial configuration structure used to define the parameters for the Stash service. It requires two main components:

• GenericConfig: A *genericapiserver.RecommendedConfig used to configure the underlying Kubernetes generic API server.
• ExtraConfig: A *controller.Config used to configure the Stash-specific controller logic, including webhooks and client configurations.

The main package provides the entrypoint for the Stash application. It initializes the root command using cmds.NewRootCmd(), configures logging via logs.Init, and executes the command-line interface. If execution fails, it logs the error using klog.Fatalln.

package main

import (
	"os"
	"runtime"

	"stash.appscode.dev/stash/pkg/cmds"
	"gomodules.xyz/logs"
	"k8s.io/klog/v2"
)

func main() {
	rootCmd := cmds.NewRootCmd()
	logs.Init(rootCmd, true)
	defer logs.FlushLogs()

	if len(os.Getenv("GOMAXPROCS")) == 0 {
		runtime.GOMAXPROCS(runtime.NumCPU())
	}

	if err := rootCmd.Execute(); err != nil {
		klog.Fatalln("Error in Stash Main:", err)
	}
	klog.Infoln("Exiting Stash Main")
}

The StashOptions struct is the primary configuration object used to initialize, validate, and run the Stash server. It combines standard Kubernetes RecommendedOptions with ExtraOptions specific to Stash.

To use it, follow this lifecycle:

1. Initialize with NewStashOptions(out, errOut).
2. Register flags using AddFlags(fs).
3. Validate the configuration using Validate(args).
4. Run the server using Run(ctx) (which internally calls Config() and Complete()).

The Config() method transforms StashOptions into a server.StashConfig. This process:

• Sets up secure serving with self-signed certificates on localhost (127.0.0.1) if not otherwise configured.
• Applies options to a new genericapiserver.RecommendedConfig.
• Configures OpenAPI (v2 and v3) definitions using v1alpha1.GetOpenAPIDefinitions.
• Sets up IgnorePrefixes for various admission webhooks and validators to prevent OpenAPI discovery issues.
• Initializes ExtraConfig using controller.NewConfig and applies ExtraOptions to it.