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
- Variables
- func BackupVolume(ctx context.Context, c *Clients, req VolumeBackupRequest) (*spec.VolumeResult, error)
- func IdentityPersist(core kubernetes.Interface, namespace, name string) func(cfg *config.AgentConfig) error
- func LoadDBState(ctx context.Context, core kubernetes.Interface, ...) (*dbspec.JobState, error)
- func LoadIdentity(ctx context.Context, core kubernetes.Interface, namespace, name string) (*config.AgentConfig, error)
- func PlanVolumes(ctx context.Context, c *Clients, s *spec.Spec, clusterBackupID string) ([]spec.VolumePlan, []string, bool, error)
- func ReadSecretCredentials(ctx context.Context, core kubernetes.Interface, ...) (password, user string, err error)
- func RenderDBWorkerImage(override string, templates map[string]string, engine, flavor string, major int) string
- func RunDBWorker(ctx context.Context) error
- func RunWorker(ctx context.Context) error
- func SaveDBState(ctx context.Context, core kubernetes.Interface, ...) error
- func SaveIdentity(ctx context.Context, core kubernetes.Interface, namespace, name string, ...) error
- func Sweep(ctx context.Context, c *Clients, agentID string, ...)
- type Clients
- type DBBackupOutcome
- type DBBackupRequest
- type DBWorkerConfig
- type DumpStats
- type VolumeBackupRequest
- type WorkerConfig
Constants ¶
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)
const CredentialsLabel = "fallbck.io/allow-db-credentials"
CredentialsLabel must be "true" on a Secret before a database job may read it
Variables ¶
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
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 ¶
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)
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 ¶
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