stackbackup

Documentation

Overview

Package stackbackup implements `obol stack export` / `obol stack import`: a single archive capturing everything a running stack needs that is not regenerable from the obol binary — host config (helmfiles, values, sell offer descriptors, wallet metadata), agent data dirs (brains + remote-signer keystores), portable encrypted wallet backups, and the etcd-resident resources that drifted out of helmfile management (Agent CRs, ServiceOffers, LiteLLM/eRPC config mutations).

Design notes live in plans/stack-export-import.md. The archive is a plain tar.gz with manifest.json as its first entry:

manifest.json          archive + obol version, stack id, component notes
config/...             $OBOL_CONFIG_DIR minus kubeconfig*/defaults/
data/<namespace>/...   agent data dirs (hermes-*, openclaw-*, agent-*)
wallets/...            walletbackup-format files (encrypted if passphrase)
cluster/...            stripped JSON dumps of CRs/ConfigMaps/Secrets

The archive contains keystore passwords and provider API keys in the same plaintext form they already have on the host's disk — callers must treat it as a secret. The wallets/ component is additionally encryptable so wallet keys stay portable on their own.

Index

• Constants
• func Export(cfg *config.Config, opts ExportOptions, u *ui.UI) (string, error)
• func Import(cfg *config.Config, opts ImportOptions, u *ui.UI) error
• func PromptExportBeforePurge(cfg *config.Config, u *ui.UI) bool
• func StripK8sJSON(data []byte) ([]byte, error)
• type Component
• type ExportOptions
• type ImportOptions
• type Manifest

Constants

const ManifestFileName = "manifest.json"

ManifestFileName is the archive's first entry.

const ManifestVersion = 1

ManifestVersion is the current archive format version. Import refuses archives with a different version.

Functions

func Export

func Export(cfg *config.Config, opts ExportOptions, u *ui.UI) (string, error)

Export captures the stack into a tar.gz archive and returns its path. Safe with the cluster up (agent deployments are quiesced while their data dirs are copied — never copy a live SQLite state.db) and with the cluster down (host dirs are the source of truth; the cluster component is skipped).

func Import

func Import(cfg *config.Config, opts ImportOptions, u *ui.UI) error

Import restores an export archive. Host state (config + data) is restored first so a subsequent `obol stack up` mounts the right brains and keystores; if the cluster is already reachable the etcd-resident resources are re-applied and agent instances re-synced. When the cluster is down, Import restores host state and prints the two remaining steps instead of failing — re-run with --cluster-only after `obol stack up`.

func PromptExportBeforePurge

func PromptExportBeforePurge(cfg *config.Config, u *ui.UI) bool

PromptExportBeforePurge offers a full stack export before a destructive purge and returns true when one was written (callers can then skip narrower wallet-only prompts). Non-interactive shells get a warning but are never blocked, mirroring openclaw.PromptBackupBeforePurge.

This closes the gap that cost real agent state: the pre-existing purge prompt covered OpenClaw wallets only — Hermes wallets and every agent's brain (sessions, memory, workspace) were destroyed silently.

func StripK8sJSON

func StripK8sJSON(data []byte) ([]byte, error)

StripK8sJSON removes server-managed fields (status, managedFields, resourceVersion, uid, ownerReferences, last-applied annotation, ...) from a kubectl JSON dump so it can be re-applied to a fresh cluster. Returns nil for an empty List.

Types

type Component

type Component struct {
	Name     string   `json:"name"`
	Included bool     `json:"included"`
	Notes    []string `json:"notes,omitempty"`
}

Component records what one export component captured (or why it was skipped) so import and humans can reason about archive contents.

type ExportOptions

type ExportOptions struct {
	Output      string
	Passphrase  string
	HasPassFlag bool
}

ExportOptions holds options for `obol stack export`.

type ImportOptions

type ImportOptions struct {
	Input       string
	Force       bool
	SkipCluster bool
	ClusterOnly bool
	SkipSync    bool
}

ImportOptions holds options for `obol stack import`.

type Manifest

type Manifest struct {
	Version     int         `json:"version"`
	ObolVersion string      `json:"obolVersion"`
	StackID     string      `json:"stackId,omitempty"`
	CreatedAt   string      `json:"createdAt"`
	ConfigDir   string      `json:"configDir"`
	DataDir     string      `json:"dataDir"`
	Components  []Component `json:"components"`
}

Manifest describes an export archive.