k8sbackup

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: AGPL-3.0 Imports: 38 Imported by: 0

Documentation

Overview

Package k8sbackup implements the Kubernetes backup agent: API resource dumps, PVC snapshots/clones, worker-pod supervision and the Secret-backed identity.

Index

Constants

View Source
const (
	EnvWorkerServerURL = "FALLBCK_WORKER_SERVER_URL"
	EnvWorkerToken     = "FALLBCK_WORKER_TOKEN"
	EnvWorkerTicket    = "FALLBCK_WORKER_TICKET"
	EnvWorkerSession   = "FALLBCK_WORKER_SESSION" // JSON temporal.BackupSessionInfo (identity fields)
	EnvWorkerPath      = "FALLBCK_WORKER_PATH"    // default /data
	EnvWorkerResult    = "FALLBCK_WORKER_RESULT"  // default /dev/termination-log
	EnvWorkerInsecure  = "FALLBCK_WORKER_INSECURE_SKIP_VERIFY"
	EnvWorkerServerCA  = "FALLBCK_WORKER_SERVER_CA" // inline PEM
	EnvWorkerPBSDirect = "FALLBCK_WORKER_PBS"       // JSON backup.DirectOptions (direct mode)

	// Database worker pods (db-worker mode)
	EnvWorkerDBPassword   = "FALLBCK_WORKER_DB_PASSWORD"
	EnvWorkerDBUser       = "FALLBCK_WORKER_DB_USER"  // overrides the spec's user (Secret user_key)
	EnvWorkerDBState      = "FALLBCK_WORKER_DB_STATE" // JSON dbbackup.JobState of the previous run
	EnvWorkerSpool        = "FALLBCK_WORKER_SPOOL"    // default /spool
	EnvWorkerHostname     = "FALLBCK_WORKER_HOSTNAME"
	EnvWorkerAgentVersion = "FALLBCK_WORKER_AGENT_VERSION"
)

Environment of a worker pod (set by the agent when building the pod spec)

View Source
const CredentialsLabel = "fallbck.io/allow-db-credentials"

CredentialsLabel must be "true" on a Secret before a database job may read it

Variables

View Source
var DefaultDBWorkerImages = map[string]string{
	"postgres": "postgres:{major}",
	"mysql":    "mysql:{major}",
	"mariadb":  "mariadb:{major}",
	"mongodb":  "mongo:{major}",
}

DefaultDBWorkerImages are the per-engine image templates; {major} is replaced with the server's detected major version (or "latest" when unknown). MySQL jobs pick "mysql" or "mariadb" by the server flavor.

Functions

func BackupVolume

func BackupVolume(ctx context.Context, c *Clients, req VolumeBackupRequest) (*spec.VolumeResult, error)

BackupVolume executes one volume backup: snapshot → clone → worker pod (or a live read-only mount), returning the worker's result. All created objects are labeled and cleaned up on every path.

func IdentityPersist

func IdentityPersist(core kubernetes.Interface, namespace, name string) func(cfg *config.AgentConfig) error

IdentityPersist adapts SaveIdentity for runtime.TokenStore.Persist (token rotations)

func LoadDBState added in v0.9.5

func LoadDBState(ctx context.Context, core kubernetes.Interface, namespace, secretName, jobID string) (*dbspec.JobState, error)

LoadDBState returns the job's previous state from the state Secret, or nil

func LoadIdentity

func LoadIdentity(ctx context.Context, core kubernetes.Interface, namespace, name string) (*config.AgentConfig, error)

LoadIdentity reads the enrolled agent configuration from the identity Secret; (nil, nil) when the Secret does not exist yet.

func PlanVolumes

func PlanVolumes(ctx context.Context, c *Clients, s *spec.Spec, clusterBackupID string) ([]spec.VolumePlan, []string, bool, error)

PlanVolumes selects the PVCs a run backs up and decides snapshot vs live per volume

func ReadSecretCredentials added in v0.9.5

func ReadSecretCredentials(ctx context.Context, core kubernetes.Interface, namespace, secretName, passwordKey, userKey string) (password, user string, err error)

ReadSecretCredentials reads the database password (and optionally the user) from a Secret in the database's namespace

func RenderDBWorkerImage added in v0.9.5

func RenderDBWorkerImage(override string, templates map[string]string, engine, flavor string, major int) string

RenderDBWorkerImage picks the dump pod image for an engine: the job override, else the template for the engine (or flavor) with the major version filled in

func RunDBWorker added in v0.9.5

func RunDBWorker(ctx context.Context) error

RunDBWorker is the database worker-pod entrypoint (db-worker mode): the dump runs in this pod with the engine's client tools, the spool is an emptyDir.

func RunWorker

func RunWorker(ctx context.Context) error

RunWorker is the worker-pod entrypoint: mount is at /data, credentials in the environment; the outcome is written to the termination-message file so the agent can read it from the pod status.

func SaveDBState added in v0.9.5

func SaveDBState(ctx context.Context, core kubernetes.Interface, namespace, secretName, jobID string, st *dbspec.JobState) error

SaveDBState writes the job's state into the state Secret (create or update)

func SaveIdentity

func SaveIdentity(ctx context.Context, core kubernetes.Interface, namespace, name string, cfg *config.AgentConfig) error

SaveIdentity writes the agent configuration into the identity Secret (create or update)

func Sweep

func Sweep(ctx context.Context, c *Clients, agentID string, isActive func(runID string) bool)

Sweep removes leftover worker pods, clone PVCs and VolumeSnapshots this agent created (crashes, evictions). isActive reports whether a run id is currently executing on this agent; objects of active runs are never touched. Runs at agent start and every 6 hours.

Types

type Clients

type Clients struct {
	Discovery discovery.DiscoveryInterface
	Dynamic   dynamic.Interface
	Core      kubernetes.Interface
}

Clients bundles the API clients the agent needs; tests inject fakes.

func InClusterClients

func InClusterClients() (*Clients, error)

InClusterClients builds the clients from the pod's ServiceAccount

type DBBackupOutcome added in v0.9.5

type DBBackupOutcome struct {
	Result *temporal.BackupExecutionResult
	// State is the chain state to persist for the next run (nil when unchanged)
	State *dbspec.JobState
	// Precheck marks a configuration/environment failure a retry cannot fix
	Precheck bool
}

DBBackupOutcome is what the dump pod reported

func BackupDatabase added in v0.9.5

func BackupDatabase(ctx context.Context, c *Clients, req DBBackupRequest) (*DBBackupOutcome, error)

BackupDatabase runs the dump pod and returns its outcome. The pod is labeled and deleted on every path.

type DBBackupRequest added in v0.9.5

type DBBackupRequest struct {
	Namespace string
	// BackupID is the PBS group (used for the deterministic pod name)
	BackupID string
	RunID    string
	AgentID  string
	Timeout  time.Duration
	Worker   DBWorkerConfig
	Progress func(phase string)
}

DBBackupRequest is one database job's dump order

type DBWorkerConfig added in v0.9.5

type DBWorkerConfig struct {
	// Image is the engine's client-tools image (postgres:17, mariadb:11, mongo:7, …)
	Image string
	// AgentImage supplies the fallbck-k8s-agent binary through an init container
	AgentImage      string
	ImagePullPolicy string
	// Resources / SecurityContext are corev1 JSON blobs from the Helm chart (optional)
	ResourcesJSON       string
	SecurityContextJSON string
	// SpoolSizeLimit bounds the spool emptyDir (Kubernetes quantity; "" = unbounded)
	SpoolSizeLimit string
	// Env carries the worker credentials, session and previous state
	Env []corev1.EnvVar
}

DBWorkerConfig describes the dump pod the agent spawns for a database job

type DumpStats

type DumpStats struct {
	Counts       map[string]int
	Excluded     []string
	FailedGroups []string
	Namespaces   []string
	Warnings     []string
}

DumpStats summarises a resource dump for the manifest

func DumpResources

func DumpResources(ctx context.Context, c *Clients, s *spec.Spec, spoolDir string, progress func(phase string)) (*DumpStats, error)

DumpResources writes every selected API resource as YAML under spoolDir: cluster/<group>/<version>/<plural>/<name>.yaml and namespaces/<ns>/<group>/<version>/<plural>/<name>.yaml. Memory stays flat: objects are fetched in pages of 500, written and dropped.

type VolumeBackupRequest

type VolumeBackupRequest struct {
	Plan              spec.VolumePlan
	RunID             string
	AgentID           string
	SnapshotTimeout   time.Duration
	VolumeTimeout     time.Duration
	AllowLiveFallback bool
	Worker            WorkerConfig
	Progress          func(phase string)
}

VolumeBackupRequest is one volume's backup order

type WorkerConfig

type WorkerConfig struct {
	Image string
	// ImagePullPolicy for worker pods (default IfNotPresent; ":latest" would otherwise
	// imply Always and break air-gapped/preloaded images)
	ImagePullPolicy string
	// Resources / SecurityContext are corev1 JSON blobs from the Helm chart (optional)
	ResourcesJSON       string
	SecurityContextJSON string
	// Env carries the worker credentials and session (built by the activity)
	Env []corev1.EnvVar
}

WorkerConfig describes the worker pod the agent spawns per volume

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL