Documentation
¶
Overview ¶
Package stackcmd is the behaviour behind the host-side verbs — install/converge, upgrade, restart, status and uninstall — with no command-line framework attached.
Two front-ends drive it, and they must not drift:
- `miabi setup|upgrade|stack …` in the CLI (cobra), the normal path;
- `docker run miabi/miabi:<tag> install …` on the server image (okapicli), which is how a user without root installs — the image runs as uid 10001 with the host's docker group, so nothing has to be written to /usr/local/bin.
Each front-end owns only its flag parsing and its rendering; everything that decides what happens to a host lives here, once.
Index ¶
- Constants
- func Apply(ctx context.Context, svc *stack.Service, path string, yes bool, ui UI) error
- func Backup(ctx context.Context, svc *stack.Service, path string, o BackupOptions, ui UI) (string, error)
- func BackupDir(manifestPath string) string
- func EnvGet(path, key string, o EnvOptions) (value string, found bool, err error)
- func EnvList(path string, o EnvOptions) (map[string]string, string, error)
- func EnvSet(ctx context.Context, svc *stack.Service, path string, assignments []string, ...) error
- func EnvUnset(ctx context.Context, svc *stack.Service, path string, keys []string, ...) error
- func Restart(ctx context.Context, svc *stack.Service, path, component string, yes bool, ...) error
- func Restore(ctx context.Context, svc *stack.Service, path string, o RestoreOptions, ui UI) error
- func Uninstall(ctx context.Context, svc *stack.Service, path string, withVolumes, yes bool, ...) error
- func Upgrade(ctx context.Context, svc *stack.Service, path string, o UpgradeOptions, ui UI) error
- func WithInstallHint(err error) error
- type BackupOptions
- type DBBackup
- type EnvOptions
- type RestoreOptions
- type SetupOptions
- type SetupResult
- type StatusReport
- type UI
- type UpgradeOptions
Constants ¶
const LabelPreRestore = "pre-restore"
LabelPreRestore marks the dump a restore takes of the database it replaces. Only these are pruned; a dump the operator asked for is never deleted.
Variables ¶
This section is empty.
Functions ¶
func Apply ¶ added in v1.10.14
Apply converges the stack onto the manifest, recreating only the components whose spec changed. It is the second half of `env set`, so a batch of edits costs one recreate per component.
func Backup ¶ added in v1.10.21
func Backup(ctx context.Context, svc *stack.Service, path string, o BackupOptions, ui UI) (string, error)
Backup dumps the platform database. It covers the database only — not volumes, certificates or the manifest, whose encryption key the dump is useless without.
func BackupDir ¶ added in v1.10.21
BackupDir is where dumps go by default: beside the manifest, which every install already has writable and which the containerized installer already bind-mounts.
func EnvGet ¶ added in v1.10.1
func EnvGet(path, key string, o EnvOptions) (value string, found bool, err error)
EnvGet returns one variable's value. found is false when the manifest does not carry it, which the caller should report as such rather than printing an empty line.
func EnvList ¶ added in v1.10.1
EnvList returns the environment the manifest carries, and the name of the block it came from.
func EnvSet ¶ added in v1.10.1
func EnvSet(ctx context.Context, svc *stack.Service, path string, assignments []string, o EnvOptions, ui UI) error
EnvSet writes KEY=VALUE pairs into the manifest, converging only with o.Apply. Validation is Normalize's: invalid names, variables Miabi sets itself, and settings that belong to their own spec section are all refused there, with an error that names where the value really lives.
func EnvUnset ¶ added in v1.10.1
func EnvUnset(ctx context.Context, svc *stack.Service, path string, keys []string, o EnvOptions, ui UI) error
EnvUnset removes variables. A key Miabi seeds into the manifest comes back at its default rather than disappearing, and the caller is told so — otherwise the operator diffs the file and finds the variable still there.
func Restart ¶
func Restart(ctx context.Context, svc *stack.Service, path, component string, yes bool, ui UI) error
Restart restarts containers WITHOUT recreating them, so they re-read what is on disk. Editing the gateway's goma.yml is the obvious case (Goma watches its providers directory, not its base config); a spec change is the obvious non-case, and Service.Restart says so.
func Restore ¶ added in v1.10.21
Restore replaces the platform database with a dump. The control plane is stopped for the swap and recreated afterwards; the current database is dumped first, so a restore can itself be undone.
func Uninstall ¶
func Uninstall(ctx context.Context, svc *stack.Service, path string, withVolumes, yes bool, ui UI, removeFile func(string) error) error
Uninstall removes the stack's containers. Volumes are kept unless withVolumes, in which case the manifest goes too — it describes an install that no longer exists.
func Upgrade ¶
Upgrade rolls a component to a newer image, rolling back automatically if the new one never becomes healthy. With no component named it moves the control plane and re-converges the rest.
func WithInstallHint ¶
WithInstallHint turns "no manifest" into an answer rather than a dead end. The same error means very different things depending on whether Miabi is running.
Types ¶
type BackupOptions ¶ added in v1.10.21
BackupOptions is the flag surface of `stack backup`, already parsed.
type DBBackup ¶ added in v1.10.21
DBBackup is one dump found on disk.
func ListBackups ¶ added in v1.10.21
ListBackups returns the dumps in dir, newest first. Files that do not follow the naming scheme are ignored rather than guessed at.
type EnvOptions ¶ added in v1.10.1
type EnvOptions struct {
// Gateway edits the gateway's environment instead of the control plane's.
Gateway bool
// Apply converges right after saving. Off by default, so several edits cost one recreate
// through Apply rather than one each.
Apply bool
Yes bool
}
EnvOptions is the flag surface of the env verbs, already parsed.
type RestoreOptions ¶ added in v1.10.21
type RestoreOptions struct {
// File is a path, or the bare name of a dump in BackupDir.
File string
Yes bool
// Force restores a dump taken by a newer Miabi than the one running.
Force bool
}
RestoreOptions is the flag surface of `stack restore`, already parsed.
type SetupOptions ¶
type SetupOptions struct {
Domain, AdminEmail, ACMEEmail, ControlURL string
Image, GatewayImage, RunnerImage, GomaConfig string
RegistryHost, Subnet, InternalSubnet string
Registry, NoHostProc, Yes bool
// IPv6 gives the shared app network and every workspace network a dual-stack address space.
IPv6 bool
// AdminPassword is the first admin's password; empty generates one. Only a fresh install uses it.
AdminPassword string
DefaultImage func() string
}
SetupOptions is the flag surface of install/setup, already parsed.
type SetupResult ¶
type SetupResult struct {
Manifest *stack.Manifest
Path string
// NewInstall is false for a converge of an existing manifest.
NewInstall bool
}
SetupResult reports what a Setup did, so the caller can print its own next-steps hint — the one piece of the output that legitimately differs between the two front-ends.
func Setup ¶
func Setup(ctx context.Context, svc *stack.Service, path string, o SetupOptions, ui UI) (*SetupResult, error)
Setup installs the stack, or converges an existing install to its manifest. It is idempotent: run against an existing manifest it keeps the stored secrets, because a regenerated database password would lock the new control plane out of its own data.
type StatusReport ¶
type StatusReport struct {
Manifest *stack.Manifest
Path string
Found []stack.Component
// LegacyConfig is set when the manifest is at the pre-rename path. The host IS installed —
// saying otherwise sends its operator hunting for a Compose stack that never existed.
LegacyConfig error
// Unmanaged is set when containers exist but no manifest does: a Compose or hand-rolled install.
Unmanaged bool
// Drift lists components running an image the manifest does not pin.
Drift []string
}
StatusReport is what status found. The caller renders it: the two front-ends draw different tables, but neither decides what is in one.
type UI ¶
type UI interface {
Printf(format string, a ...any)
Info(format string, a ...any)
Success(format string, a ...any)
Warn(format string, a ...any)
// Confirm asks a yes/no question. It is never called when the caller passed Yes.
Confirm(prompt string) bool
}
UI is the front-end's output. The CLI colors it; the server image prints plainly.
type UpgradeOptions ¶
type UpgradeOptions struct {
// Component is empty for the whole stack, else one component by name.
Component string
Image string
Version string
Yes bool
// DefaultImage is as in SetupOptions.
DefaultImage func() string
}
UpgradeOptions is the flag surface of upgrade/update, already parsed.