Documentation
¶
Overview ¶
Package wsbundle defines the Miabi Portable Bundle format; it depends on nothing else in Miabi.
Index ¶
- Constants
- Variables
- func DatabasePath(prefix, ref string) string
- func Encode(st *State, passphrase string) ([]byte, error)
- func EncodeInfo(i *Info) ([]byte, error)
- func InfoObject(prefix, ref string) string
- func IsRef(s string) bool
- func NewRef(workspace string, at time.Time) string
- func RefFromInfoObject(key string) string
- func Root(prefix, ref string) string
- func Seal(st *State, passphrase string) ([]byte, error)
- func Segment(s string) string
- func StateFile(ref string, encrypted bool) string
- func StateObject(prefix, ref string, encrypted bool) string
- func ValidatePassphrase(pass string) error
- func VolumePath(prefix, ref string) string
- type Application
- type Artifact
- type Certificate
- type Config
- type Connection
- type CronJob
- type DNSProvider
- type DatabaseInstance
- type Domain
- type EnvVar
- type Environment
- type GitRepository
- type GitSource
- type Info
- type InstanceLink
- type JobDefinition
- type LogicalDatabase
- type Member
- type Middleware
- type Mount
- type Network
- type Pipeline
- type Port
- type Registry
- type Route
- type RouteMaintenance
- type SealingKey
- type Secret
- type Source
- type Stack
- type State
- type Volume
- type Workspace
Constants ¶
const ( InfoNotice = "Miabi portable workspace bundle index. The state file beside it is encrypted with the backup passphrase." PlainInfoNotice = "" /* 137-byte string literal not displayed */ )
The info file is deliberately readable and carries no secret; secrets live in the sealed state file.
const ( // Exactly one per bundle; without it a bundle restores nothing. SubjectState = "state" // SubjectDatabase is one logical database's dump. SubjectDatabase = "database" // SubjectVolume is one workspace volume's archive. SubjectVolume = "volume" )
Artifact subjects.
const ( StateExt = ".mbws" PlainStateExt = ".json" )
StateExt is the sealed state file's extension; PlainStateExt the unencrypted one's.
const HealthcheckNoneDisables = 3
HealthcheckNoneDisables is the first schema whose "none" healthcheck disables the image's own check.
const InfoExt = ".xml"
const InfoSchema = 1
InfoSchema is the info file's version.
const MinStateSchema = 1
Every version in range differs only by fields absent in older ones, which decode to zero.
const RefPrefix = "mbwb_"
Restore matches on the prefix, so a mistyped argument fails fast instead of listing a whole bucket.
const StateSchema = 6
StateSchema history: 2 configs, 3 "none" healthcheck disables, 4 sealing keys, 5 version policy, 6 db source.
Variables ¶
var ( // A wrong passphrase and a tampered file are indistinguishable by design. ErrBadPassphrase = errors.New("bundle state did not decrypt: wrong passphrase or corrupt file") // ErrNotState means the bytes are not a bundle state file at all. ErrNotState = errors.New("not a Miabi workspace bundle state file") // ErrPassphraseRequired means the state file is sealed but no passphrase was given. ErrPassphraseRequired = errors.New("this bundle is encrypted: set the bundle passphrase it was created with to restore it") ErrWeakPassphrase = fmt.Errorf("backup passphrase must be at least %d characters and mix letters with digits or symbols", minPassLen) )
Functions ¶
func DatabasePath ¶
DatabasePath is where a bundle's database dumps live.
func Encode ¶ added in v1.10.7
An empty passphrase writes plain JSON, carrying the workspace's secrets in the clear.
func EncodeInfo ¶
Validate does not assign the schema: a validator that repairs what it checks cannot report a mismatch.
func InfoObject ¶
The info file sits at the top of the prefix so listing it lists bundles rather than their contents.
func RefFromInfoObject ¶
Lets a restore discover bundles in a bucket with no database to list them from.
func Root ¶
A per-bundle branch lets restore list one bundle's artifacts and an operator delete it by one prefix.
func Seal ¶
A fresh salt and nonce per call, so sealing the same state twice never yields the same bytes.
func StateObject ¶
func ValidatePassphrase ¶
A bundle holds every workspace secret, so the floor is enforced rather than suggested.
func VolumePath ¶
VolumePath is where a bundle's volume archives live.
Types ¶
type Application ¶
type Application struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
SourceType string `json:"source_type,omitempty"` // image | git
Icon string `json:"icon,omitempty"`
Image string `json:"image,omitempty"`
Tag string `json:"tag,omitempty"`
GitRepo string `json:"git_repo,omitempty"`
GitRef string `json:"git_ref,omitempty"`
BuildMethod string `json:"build_method,omitempty"`
Builder string `json:"builder,omitempty"`
Buildpacks []string `json:"buildpacks,omitempty"`
BuildEnv map[string]string `json:"build_env,omitempty"`
// Registry and GitRepository name the stored credentials this app uses.
Registry string `json:"registry,omitempty"`
GitRepository string `json:"git_repository,omitempty"`
Stack string `json:"stack,omitempty"`
Networks []string `json:"networks,omitempty"`
Command []string `json:"command,omitempty"`
Port int `json:"port,omitempty"`
Ports []Port `json:"ports,omitempty"`
Mounts []Mount `json:"mounts,omitempty"`
Env []EnvVar `json:"env,omitempty"`
MemoryBytes int64 `json:"memory_bytes,omitempty"`
NanoCPUs int64 `json:"nano_cpus,omitempty"`
GPUCount int `json:"gpu_count,omitempty"`
GPUKind string `json:"gpu_kind,omitempty"`
RunAsUser string `json:"run_as_user,omitempty"`
RestartPolicy string `json:"restart_policy,omitempty"`
ImagePullPolicy string `json:"image_pull_policy,omitempty"`
RuntimeKind string `json:"runtime_kind,omitempty"`
Replicas int `json:"replicas,omitempty"`
PlacementConstraints []string `json:"placement_constraints,omitempty"`
HealthcheckType string `json:"healthcheck_type,omitempty"`
HealthcheckHTTPPath string `json:"healthcheck_http_path,omitempty"`
HealthcheckPort int `json:"healthcheck_port,omitempty"`
HealthcheckCommand string `json:"healthcheck_command,omitempty"`
HealthcheckIntervalSeconds int `json:"healthcheck_interval_seconds,omitempty"`
HealthcheckTimeoutSeconds int `json:"healthcheck_timeout_seconds,omitempty"`
HealthcheckRetries int `json:"healthcheck_retries,omitempty"`
HealthcheckStartPeriodSeconds int `json:"healthcheck_start_period_seconds,omitempty"`
DeployStrategy string `json:"deploy_strategy,omitempty"`
ContainerLabels map[string]string `json:"container_labels,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
}
Application is a workload's full spec.
type Artifact ¶
type Artifact struct {
// Subject is "state", "database" or "volume".
Subject string `json:"subject" xml:"subject,attr"`
Database string `json:"database,omitempty" xml:"database,omitempty"`
Instance string `json:"instance,omitempty" xml:"instance,omitempty"`
// Engine decides which restore tool can read a dump back.
Engine string `json:"engine,omitempty" xml:"engine,omitempty"`
// By Miabi name, never the Docker name, which the target mints itself.
Volume string `json:"volume,omitempty" xml:"volume,omitempty"`
// File is the artifact's name as the *-bkup tools record it, relative to Path.
File string `json:"file" xml:"file"`
// Recorded per artifact so a restore never re-derives the layout and looks where nothing was written.
Path string `json:"path,omitempty" xml:"path,omitempty"`
SizeBytes int64 `json:"size_bytes,omitempty" xml:"sizeBytes,omitempty"`
Encrypted bool `json:"encrypted,omitempty" xml:"encrypted,omitempty"`
// A bundle that lists what it failed to capture is honest; silently omitting it looks complete.
Error string `json:"error,omitempty" xml:"error,omitempty"`
}
Artifact is one file in a bundle.
type Certificate ¶
type Certificate struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Source string `json:"source,omitempty"` // imported | acme
DNSNames []string `json:"dns_names,omitempty"`
// CertPEM and KeyPEM are the material, present only for an imported cert.
CertPEM string `json:"cert_pem,omitempty"`
KeyPEM string `json:"key_pem,omitempty"`
DNSProvider string `json:"dns_provider,omitempty"`
AutoRenew bool `json:"auto_renew,omitempty"`
}
Only uploaded certs carry material; a managed cert's key belongs to a host still resolving to the source.
type Config ¶ added in v1.9.0
type Config struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description,omitempty"`
Data map[string]string `json:"data"`
Mode string `json:"mode,omitempty"`
Sensitive bool `json:"sensitive,omitempty"`
Delimiters []string `json:"delimiters,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
type Connection ¶ added in v1.10.25
type Connection struct {
Host string `json:"host,omitempty"`
User string `json:"user,omitempty"`
Password string `json:"password,omitempty"`
URI string `json:"uri,omitempty"`
ReadOnlyUser string `json:"readonly_user,omitempty"`
ReadOnlyPassword string `json:"readonly_password,omitempty"`
ReadOnlyURI string `json:"readonly_uri,omitempty"`
}
Connection is a logical database's connection details as the source install saw them.
type CronJob ¶
type CronJob struct {
Name string `json:"name"`
App string `json:"app"`
Schedule string `json:"schedule"`
Command []string `json:"command,omitempty"`
Entrypoint []string `json:"entrypoint,omitempty"`
Image string `json:"image,omitempty"`
Registry string `json:"registry,omitempty"`
TimeoutSecs int `json:"timeout_secs,omitempty"`
Enabled bool `json:"enabled"`
ConcurrencyPolicy string `json:"concurrency_policy,omitempty"`
HistoryLimit int `json:"history_limit,omitempty"`
DisplayName string `json:"display_name,omitempty"`
RunAsUser string `json:"run_as_user,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
}
type DNSProvider ¶
type DNSProvider struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Type string `json:"type"` // cloudflare | route53 | digitalocean
Credentials string `json:"credentials,omitempty"`
}
Credentials travel because the target must publish ownership TXT records and answer DNS-01 before serving.
type DatabaseInstance ¶
type DatabaseInstance struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Engine string `json:"engine"`
Version string `json:"version,omitempty"`
VolumeSize int64 `json:"volume_size_bytes,omitempty"`
// Restoring onto an install without that class falls back to the default one.
StorageClass string `json:"storage_class,omitempty"`
MemoryBytes int64 `json:"memory_bytes,omitempty"`
NanoCPUs int64 `json:"nano_cpus,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
Databases []LogicalDatabase `json:"logical_databases,omitempty"`
// Links are the apps the whole instance is linked to (Redis).
Links []InstanceLink `json:"links,omitempty"`
}
Credentials don't travel: data is dumped into a server the target initialized; EnvPrefix/App re-inject apps.
type Domain ¶
type Domain struct {
Name string `json:"name"`
TLSMode string `json:"tls_mode,omitempty"`
// Lets the target prove ownership without an operator pasting a TXT record.
DNSProvider string `json:"dns_provider,omitempty"`
Wildcard bool `json:"wildcard,omitempty"`
}
Ownership is not carried: a restored domain starts unverified and re-proves itself against DNS.
type EnvVar ¶
type EnvVar struct {
Key string `json:"key"`
Value string `json:"value,omitempty"`
IsSecret bool `json:"is_secret,omitempty"`
}
Plaintext inside the sealed file because the target re-encrypts under its own key.
type Environment ¶
type Environment struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description,omitempty"`
Rank int `json:"rank,omitempty"`
RequiredApprovals int `json:"required_approvals,omitempty"`
GitSource string `json:"gitops_source,omitempty"`
}
Approvals don't travel: they are decisions made on the platform that held the release.
type GitRepository ¶
type GitRepository struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
URL string `json:"url"`
AuthType string `json:"auth_type,omitempty"`
Username string `json:"username,omitempty"`
Secret string `json:"secret,omitempty"`
}
GitRepository is a Git credential, so a git-source app still clones.
type GitSource ¶
type GitSource struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
RepoURL string `json:"repo_url"`
Ref string `json:"ref,omitempty"`
Path string `json:"path,omitempty"`
GitRepository string `json:"git_repository,omitempty"` // stored credential, by name
SyncPolicy string `json:"sync_policy,omitempty"` // manual | auto
Prune bool `json:"prune,omitempty"`
SelfHeal bool `json:"self_heal,omitempty"`
AllowEmpty bool `json:"allow_empty,omitempty"`
// RequireSealedSecrets keeps the target refusing plaintext Secret values, as the source did.
RequireSealedSecrets bool `json:"require_sealed_secrets,omitempty"`
// Lets the target treat HEAD as already synced instead of redeploying everything.
LastSyncedCommit string `json:"last_synced_commit,omitempty"`
}
The webhook secret does not travel, or the same push would drive two installs.
type Info ¶
type Info struct {
XMLName xml.Name `json:"-" xml:"workspaceBundle"`
Notice string `json:"_notice" xml:"notice"`
Schema int `json:"schema" xml:"schema,attr"`
Ref string `json:"ref" xml:"ref,attr"`
Workspace string `json:"workspace" xml:"workspace"`
DisplayName string `json:"display_name,omitempty" xml:"displayName,omitempty"`
// Informational: bundles are portable, so a restore never requires a match.
SourceInstall string `json:"source_install,omitempty" xml:"sourceInstall,omitempty"`
MiabiVersion string `json:"miabi_version,omitempty" xml:"miabiVersion,omitempty"`
Encrypted bool `json:"encrypted" xml:"encrypted"`
Bucket string `json:"bucket,omitempty" xml:"bucket,omitempty"`
// Prefix is the object prefix the bundle's own branch lives under.
Prefix string `json:"prefix,omitempty" xml:"prefix,omitempty"`
// The sealed state file can't be inspected without the passphrase, so these counts make a listing informative.
Apps int `json:"apps" xml:"apps,omitempty"`
Databases int `json:"databases" xml:"databases,omitempty"`
Volumes int `json:"volumes" xml:"volumes,omitempty"`
Secrets int `json:"secrets" xml:"secrets,omitempty"`
Configs int `json:"configs" xml:"configs,omitempty"`
Routes int `json:"routes" xml:"routes,omitempty"`
Certificates int `json:"certificates" xml:"certificates,omitempty"`
Pipelines int `json:"pipelines" xml:"pipelines,omitempty"`
GitOpsSources int `json:"gitops_sources" xml:"gitopsSources,omitempty"`
Artifacts []Artifact `json:"artifacts" xml:"artifacts>artifact"`
CreatedAt time.Time `json:"created_at" xml:"createdAt"`
}
Info lets a restore work with only the bucket and the passphrase, even after the source DB is gone.
func DecodeInfo ¶
DecodeInfo parses and validates an info file read from the bucket.
func (*Info) StateArtifact ¶
StateArtifact returns the sealed state file's artifact, or nil.
type InstanceLink ¶ added in v1.10.13
type JobDefinition ¶ added in v1.10.13
type JobDefinition struct {
Name string `json:"name"`
App string `json:"app"`
Command []string `json:"command,omitempty"`
Entrypoint []string `json:"entrypoint,omitempty"`
Image string `json:"image,omitempty"`
Registry string `json:"registry,omitempty"`
RunAsUser string `json:"run_as_user,omitempty"`
TimeoutSecs int `json:"timeout_secs,omitempty"`
RunPolicy string `json:"run_policy,omitempty"`
WaitForDeploy bool `json:"wait_for_deploy"`
HistoryLimit int `json:"history_limit,omitempty"`
BackoffLimit int `json:"backoff_limit,omitempty"`
SpecHash string `json:"spec_hash,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
}
JobDefinition is a declared Job. Its fingerprint travels with it; its runs do not.
type LogicalDatabase ¶
type LogicalDatabase struct {
Name string `json:"name"`
EnvPrefix string `json:"env_prefix,omitempty"`
EnvMap map[string]string `json:"env_map,omitempty"`
App string `json:"app,omitempty"` // owning application, by name
Metadata map[string]string `json:"metadata,omitempty"`
// Credentials never travel, so the read-only user is recreated with new ones.
ReadOnlyUser bool `json:"readonly_user,omitempty"`
// Restore must not add connection variables an attach-only app never had.
AttachOnly bool `json:"attach_only,omitempty"`
// Restore rewrites env or config values carrying the source connection to the target's.
Source *Connection `json:"source,omitempty"`
}
LogicalDatabase is one named database on an instance and the app it belongs to.
type Member ¶
type Member struct {
Email string `json:"email"`
Role string `json:"role"`
Owner bool `json:"owner,omitempty"`
}
Users are instance-global; password hashes, sessions, 2FA secrets and tokens never travel.
type Middleware ¶
type Middleware struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Type string `json:"type"`
Paths []string `json:"paths,omitempty"`
Rule map[string]any `json:"rule,omitempty"`
}
The rule may hold secret fields, which is why it only exists inside the sealed state file.
type Mount ¶
type Mount struct {
Volume string `json:"volume"`
Config string `json:"config,omitempty"`
Key string `json:"key,omitempty"`
Mode string `json:"mode,omitempty"`
Path string `json:"path"`
ReadOnly bool `json:"read_only,omitempty"`
}
Host-path binds aren't carried: their allow-listed preset may not exist, or mean something else, on the target.
type Network ¶
type Network struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Driver string `json:"driver,omitempty"`
Internal bool `json:"internal,omitempty"`
}
The Docker name is globally unique and platform-managed, so the target mints its own.
type Pipeline ¶
type Pipeline struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
App string `json:"app,omitempty"`
Spec string `json:"spec"`
Enabled bool `json:"enabled"`
// A repo-owned spec is carried as last read and re-read from the repository at the next run.
Source string `json:"source,omitempty"`
SourcePath string `json:"source_path,omitempty"`
SourceRef string `json:"source_ref,omitempty"`
// Lets a restored repository continue its numbering instead of reusing existing tags; opaque here.
Versioning json.RawMessage `json:"versioning,omitempty"`
}
Runs, logs and images stay behind; the definition is what reproduces them.
type Port ¶
type Port struct {
Container int `json:"container"`
Protocol string `json:"protocol,omitempty"`
Scheme string `json:"scheme,omitempty"`
Name string `json:"name,omitempty"`
}
Port is a container port the app exposes.
type Route ¶
type Route struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
App string `json:"app"`
Hosts []string `json:"hosts,omitempty"`
Path string `json:"path,omitempty"`
Methods []string `json:"methods,omitempty"`
Middlewares []string `json:"middlewares,omitempty"`
Rewrite string `json:"rewrite,omitempty"`
TargetPort int `json:"target_port,omitempty"`
TLSMode string `json:"tls_mode,omitempty"`
Certificate string `json:"certificate,omitempty"`
Enabled bool `json:"enabled"`
ExploitProtection bool `json:"exploit_protection,omitempty"`
Maintenance *RouteMaintenance `json:"maintenance,omitempty"`
}
Route is an HTTP routing rule bound to an app by name.
type RouteMaintenance ¶ added in v1.8.3
type SealingKey ¶ added in v1.10.15
type SealingKey struct {
Version int `json:"version"`
Identity string `json:"identity"`
Active bool `json:"active"`
CreatedAt time.Time `json:"created_at"`
}
SealingKey is a workspace sealing key, private half included.
type Secret ¶
type Secret struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description,omitempty"`
Value string `json:"value"`
Metadata map[string]string `json:"metadata,omitempty"`
// Lets a GitOps source re-syncing on the target see the secret as unchanged.
SealedFP string `json:"sealed_fp,omitempty"`
SealedKeyVersion int `json:"sealed_key_version,omitempty"`
}
Secret is one vault entry with its value.
type Source ¶
type Source struct {
InstallID string `json:"install_id,omitempty"`
MiabiVersion string `json:"miabi_version,omitempty"`
ExportedAt time.Time `json:"exported_at"`
}
Source is the bundle's provenance.
type Stack ¶
type Stack struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description,omitempty"`
Env []EnvVar `json:"env,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
}
Stack groups applications and carries the environment shared by its members.
type State ¶
type State struct {
Schema int `json:"schema"`
Source Source `json:"source"`
Workspace Workspace `json:"workspace"`
Registries []Registry `json:"registries,omitempty"`
GitRepos []GitRepository `json:"git_repositories,omitempty"`
DNSProviders []DNSProvider `json:"dns_providers,omitempty"`
Networks []Network `json:"networks,omitempty"`
// SealingKeys travel so values sealed to the source workspace keep opening on the target.
SealingKeys []SealingKey `json:"sealing_keys,omitempty"`
Secrets []Secret `json:"secrets,omitempty"`
Configs []Config `json:"configs,omitempty"`
Volumes []Volume `json:"volumes,omitempty"`
Stacks []Stack `json:"stacks,omitempty"`
Databases []DatabaseInstance `json:"databases,omitempty"`
Certificates []Certificate `json:"certificates,omitempty"`
Apps []Application `json:"apps,omitempty"`
CronJobs []CronJob `json:"cron_jobs,omitempty"`
// Carried so a restored GitOps source re-syncs them as unchanged rather than running every Job again.
JobDefinitions []JobDefinition `json:"job_definitions,omitempty"`
Middlewares []Middleware `json:"middlewares,omitempty"`
Routes []Route `json:"routes,omitempty"`
Domains []Domain `json:"domains,omitempty"`
Environments []Environment `json:"environments,omitempty"`
Pipelines []Pipeline `json:"pipelines,omitempty"`
GitSources []GitSource `json:"gitops_sources,omitempty"`
Members []Member `json:"members,omitempty"`
}
Every reference is a name, since uint ids are meaningless across installs; it only exists sealed or in memory.
func Decode ¶ added in v1.10.7
The form is read from the bytes, not the index, so it decodes whatever the workspace's current setting is.
type Volume ¶
type Volume struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
SizeBytes int64 `json:"size_bytes,omitempty"`
Driver string `json:"driver,omitempty"`
AccessMode string `json:"access_mode,omitempty"`
HostPath string `json:"host_path,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
}
Contents travel separately as a data artifact named after Name.