Documentation
¶
Overview ¶
Package backup copies volume disks to S3-compatible object storage and back. A volume's backups live under one path in a bucket:
<path>/jokku-backup.json what the backups are: format, volume, key ID <path>/backups/<time>.backup one per backup: the disk's size and which block goes where <path>/blocks/ab/abcd... the disk's 1 MiB blocks, named by their contents
A block is uploaded once and shared by every backup that holds it, so each backup is complete on its own but only adds the blocks that changed. Holes and all-zero blocks are never stored. Blocks and backup files are compressed, and encrypted when there is a key.
Index ¶
- Constants
- Variables
- func CheckPath(p string) error
- func Delete(ctx context.Context, st Store, p, name string) error
- func List(ctx context.Context, st Store, p string) ([]string, error)
- func PackState(dataDir, db string, w io.Writer) error
- func ParseEndpoint(endpoint string) (*url.URL, error)
- func Prune(ctx context.Context, st Store, p string, r Retention, now time.Time) ([]string, int, error)
- func UnpackState(r io.Reader, dir string) ([]string, error)
- type Dir
- type Info
- type Key
- type Manifest
- type Object
- type Options
- type Result
- type Retention
- type Store
- type Usage
Constants ¶
const ( StateDir = "state" ArtifactsDir = "artifacts" // StateVolume and ArtifactsVolume stand for the volume ID in their // paths' jokku-backup.json. StateVolume = "cluster-state" ArtifactsVolume = "cluster-artifacts" )
A cluster backup holds the control node's state, under <path>/state, and the root filesystems of recent releases, under <path>/artifacts (one backup per artifact, named by its file, sharing blocks).
const ( // NameFormat names backups by when they were made, in UTC; names sort // in time order. NameFormat = "2006-01-02T15-04-05Z" )
Variables ¶
var ErrNotFound = errors.New("not found")
ErrNotFound is a key the store doesn't have.
var Open = OpenS3
Open connects to a destination's bucket. Tests replace it.
var StateFiles = []string{"jokku.db", "tls/control.key", "tls/control.crt", "wireguard.key", "control-token", "agent-token"}
StateFiles are what the state backup holds, relative to the data dir: a snapshot of the database, and the control node's identity (its TLS key, which nodes pin, its WireGuard key, and its tokens).
Functions ¶
func CheckPath ¶
CheckPath refuses a backup path that is empty or climbs out of the bucket's folders.
func PackState ¶
PackState writes the state as a tar: db (a snapshot of the database) as jokku.db, and the other StateFiles from dataDir that exist. Uncompressed: it is backed up block by block, and blocks are compressed then.
func ParseEndpoint ¶
ParseEndpoint checks an endpoint is a bare https:// (or http://) host, adding https:// when no scheme is given.
Types ¶
type Info ¶
type Info struct {
Format int `json:"format"`
BlockSize int `json:"block_size"`
Encrypted bool `json:"encrypted"`
KeyID string `json:"key_id,omitempty"`
// Volume is the ID of the volume whose backups these are, so two
// volumes (on two clusters, say) never mix their backups in one path.
Volume string `json:"volume"`
App string `json:"app,omitempty"`
Name string `json:"name,omitempty"`
}
Info is jokku-backup.json, which says what a path holds.
type Key ¶
type Key struct {
// contains filtered or unexported fields
}
Key encrypts a cluster's backups. It is shown to the user once and is the only way to read them: Jokku keeps a copy, but losing the cluster loses that.
type Manifest ¶
type Manifest struct {
Version int `json:"version"`
Name string `json:"name"`
Volume string `json:"volume"`
Created time.Time `json:"created"`
Size int64 `json:"size"`
BlockSize int `json:"block_size"`
// Index[i] is where the block Names[i] goes, in blocks.
Index []int64 `json:"index"`
Names []string `json:"names"`
}
Manifest is one backup: the disk's size and its blocks.
func ReadManifest ¶
ReadManifest reads one backup's manifest.
func Restore ¶
func Restore(ctx context.Context, st Store, key *Key, p, name, dst string, progress func(done, total int64)) (*Manifest, error)
Restore writes backup name of a path to dst, a new disk image, checking every block against its name. progress is told the bytes written so far and the total.
type Options ¶
type Options struct {
Store Store
Key *Key // nil: not encrypted
Path string
Volume, App, VolumeName string // recorded in Info
Disk string // the disk image
Name string // the backup's name, from NameFormat
// Freeze, when something may be writing to the disk, stops writes
// until thaw is called, so the backup is the disk at one moment.
Freeze func(ctx context.Context) (thaw func() error, err error)
// Staging is a directory for blocks that change while the backup runs.
Staging string
Log func(string)
}
Options say what to back up, and where.
type Result ¶
type Result struct {
Name string `json:"name"`
Size int64 `json:"size"` // the disk's size
Blocks int `json:"blocks"` // blocks holding data
NewBlocks int `json:"new_blocks"` // of them, not already in the bucket
NewBytes int64 `json:"new_bytes"` // what was uploaded, after compression
}
Result says what a backup stored.
type Retention ¶
type Retention struct {
Recent time.Duration
Daily int
Also []string // backups to keep regardless, such as one about to be restored
}
Retention says which backups to keep: every one from the last Recent, the last one of each of the last Daily days (UTC, today included), and always the newest.
type Store ¶
type Store interface {
// Check reports whether the bucket can be reached with these
// credentials.
Check(ctx context.Context) error
Put(ctx context.Context, key string, data []byte) error
// Get returns ErrNotFound for a key that isn't there.
Get(ctx context.Context, key string) ([]byte, error)
// List returns the objects under prefix, sorted by key.
List(ctx context.Context, prefix string) ([]Object, error)
Delete(ctx context.Context, key string) error
}
Store is where backups are kept: a bucket, as objects named by key.