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.
Variables ¶
This section is empty.
Functions ¶
func Export ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files