Documentation
¶
Overview ¶
Package stack installs Miabi's own stack via the Docker API, since Miabi can't self-update while Compose owns it.
Index ¶
- Constants
- Variables
- func CheckAdminPassword(pw string) error
- func ConvertFile(path string, m *Manifest) (bool, error)
- func GomaConfig() []byte
- func IsDocument(b []byte) bool
- func JSONSchema() ([]byte, error)
- func ManifestPath() string
- func MarshalDocument(d *Document) ([]byte, error)
- func PortConflictError(conflicts []PortConflict) error
- func Save(path string, m *Manifest) error
- func UserConfigPath() string
- type ACME
- type AdminSpec
- type BackupDestination
- type BackupEncryption
- type BackupRetention
- type BackupSpec
- type Component
- type DNSSpec
- type Document
- type DocumentMeta
- type Endpoints
- type ExternalSpec
- type Gateway
- type GatewaySpec
- type HostPortsSpec
- type ImageSpec
- type Images
- type InstallSettings
- type LicenseSpec
- type Manifest
- type NetworkConfig
- type NetworkingSpec
- type PoolSpec
- type PortConflict
- type Registry
- type RegistrySpec
- type Secrets
- type SecretsSpec
- type ServerSpec
- type Service
- func (s *Service) AllowNetworkRecreate()
- func (s *Service) CheckDaemon(ctx context.Context) error
- func (s *Service) CheckOrphanedData(ctx context.Context) error
- func (s *Service) CheckPorts(ctx context.Context) ([]PortConflict, error)
- func (s *Service) Component(m *Manifest, name string) (component, bool)
- func (s *Service) ComponentNames(m *Manifest) []string
- func (s *Service) Converge(ctx context.Context, m *Manifest) error
- func (s *Service) ConvergeData(ctx context.Context, m *Manifest) error
- func (s *Service) Discover(ctx context.Context) ([]Component, error)
- func (s *Service) DumpDatabase(ctx context.Context, m *Manifest, dir, name string) (string, error)
- func (s *Service) EnsureGatewayConfig(ctx context.Context, m *Manifest) error
- func (s *Service) IPv6Upgrades(ctx context.Context, m *Manifest) ([]string, error)
- func (s *Service) NodeGatewayImageDrift(ctx context.Context, want string) string
- func (s *Service) Pending(ctx context.Context, m *Manifest) ([]string, error)
- func (s *Service) Restart(ctx context.Context, m *Manifest, only string) error
- func (s *Service) RestoreDatabase(ctx context.Context, m *Manifest, file string) error
- func (s *Service) Rollout(ctx context.Context, m *Manifest, name, newImage string, ...) error
- func (s *Service) StopControlPlane(ctx context.Context) error
- func (s *Service) Teardown(ctx context.Context, withVolumes bool) error
- func (s *Service) ValidateGatewayConfig(ctx context.Context, m *Manifest) error
- type Spec
Constants ¶
const ( // MinAdminPasswordLength matches the control plane's own minimum, which refuses to seed a shorter one. MinAdminPasswordLength = 12 // MaxAdminPasswordBytes is bcrypt's input limit; a longer password would fail the seed at startup. MaxAdminPasswordBytes = 72 )
const ( // Mount the directory, not the file: a single-file bind keeps the old inode and misses rename-based updates. GeoIPDir = "geoip" // Provider-neutral, because Miabi does not choose the provider. DefaultGeoIPFile = "country.mmdb" // MaxMind's own download name, so operators following MaxMind or geoipupdate land on it. LegacyGeoIPFile = "GeoLite2-Country.mmdb" )
const ( ConfigPathEnv = "MIABI_CONFIG_FILE" ManifestPathEnv = "MIABI_STACK_FILE" )
ManifestPathEnv is the older spelling and is still honoured.
const ( ContainerControlPlane = "miabi" ContainerPostgres = "miabi-postgres" ContainerRedis = "miabi-redis" ContainerGateway = "miabi-gateway" )
Names match examples/compose/compose.yaml so `docker logs miabi` works on both install paths.
const ( VolumePGData = "mb-platform-pgdata" VolumeRedisData = "mb-platform-redisdata" VolumeLogs = "mb-platform-logs" VolumeGatewayCerts = "mb-platform-gateway-certs" VolumeGatewayProviders = "mb-platform-gateway-providers" // No longer created; kept only so Teardown can clean it up on older installs. VolumeGatewayConfig = "mb-platform-gateway-config" )
The mb- prefix makes dockerimport's name shield skip them for import.
const ( DefaultPostgresImage = bundled.PostgresImage DefaultRedisImage = bundled.RedisImage DefaultRunnerImage = "miabi/runner:latest" DefaultNetwork = "miabi-proxy" // Pre-rename installs keep this name because their app containers are attached to it by name. LegacyNetwork = "miabi" DefaultSubnet = "10.63.0.0/16" // Separate from the shared proxy fabric, where anything is reachable from a tenant container. DefaultInternalNetwork = "miabi-internal" // Below DefaultSubnet because 10.64.0.0/16 would collide with the workspace allocator's pool. DefaultInternalSubnet = "10.62.0.0/16" )
Pinned for reproducible installs; tags carry no leading "v" because Docker tags don't.
const ( // Matches Goma's own default; written down to make the knob visible. DefaultGomaLogLevel = "info" // On because the consumer runs by default; in gateway.env, not the spec, so operators can still override it. DefaultGomaAnalytics = "true" )
const ( DefaultTimezone = "UTC" DefaultLogLevel = "info" )
Seeded into the manifest so `env:` shows the knobs; both stay ordinary editable entries.
const APIVersion = "install.miabi.io/v1"
Deliberately not miabi.io/v1, whose generated kind enum would make ControlPlane look apply-able.
const AdminPasswordEnv = "MIABI_ADMIN_PASSWORD"
AdminPasswordEnv supplies the first admin's password to setup, so an automated install can choose it.
const BackupSuffix = ".bak"
BackupSuffix names the copy ConvertFile leaves behind.
const CurrentVersion = 1
CurrentVersion is the manifest schema version this build writes.
const DBBackupExt = ".dump"
pg_dump's custom format is compressed and lets a restore load into a fresh database.
const DefaultConfigPath = "/etc/miabi/miabi.yaml"
Must be a host file, not the DB: the CLI cannot read Postgres to learn how to start Postgres.
const DefaultGatewayConfigFile = "goma.yml"
DefaultGatewayConfigFile is the gateway config's name beside miabi.yaml.
const KindControlPlane = "ControlPlane"
KindControlPlane is the install document's only kind today.
const LegacyConfigPath = "/etc/miabi/stack.yaml"
Still detected so old installs are told to migrate; never deleted since it holds the DB password.
const SchemaFileName = "install.miabi.io-v1.schema.json"
const SchemaID = "https://docs.miabi.io/schema/install.miabi.io-v1.schema.json"
Editors resolve $ref against it, so it must be the URL the file is served from.
const UserConfigDir = ".miabi"
Same layout as /etc/miabi because everything else resolves relative to the manifest.
Variables ¶
var DefaultGatewayImage = bundled.GatewayImage()
DefaultGatewayImage is set at build time from versions.miabi.io (see package bundled).
var ErrLegacyConfig = errors.New("the stack manifest is at its pre-1.8 path")
Not ErrNotInstalled: this host is installed, and saying otherwise sends the operator hunting for Compose.
var ErrNoDocument = errors.New("no ControlPlane document found")
ErrNoDocument is returned for input that parses as YAML but holds no install document.
var ErrNotInstalled = errors.New("no Miabi stack manifest found")
It does not mean there is no Miabi: a Compose install has no manifest either.
var ErrOrphanedData = errors.New("an existing Miabi database was found, but its manifest is missing")
var ErrRootlessDaemon = errors.New("this Docker daemon runs rootless, which Miabi does not support")
ErrRootlessDaemon is returned by CheckDaemon for a rootless Docker daemon.
Functions ¶
func CheckAdminPassword ¶ added in v1.10.22
Setup fails before anything is created rather than leaving a control plane that cannot start.
func ConvertFile ¶ added in v1.10.1
The copy is mandatory: it is the only record of the secrets and an older CLI can't read the new shape.
func GomaConfig ¶
func GomaConfig() []byte
GomaConfig exposes the embedded config so the drift test can compare it.
func IsDocument ¶ added in v1.10.1
Keys off apiVersion alone so a malformed document still gets its own error.
func JSONSchema ¶ added in v1.10.1
Generated from the parser's types so editor validation and install validation stay identical.
func ManifestPath ¶
func ManifestPath() string
An existing manifest is found before choosing by privilege, so a non-sudo read-only command still finds /etc.
func MarshalDocument ¶ added in v1.10.1
MarshalDocument renders a document with the indentation the rest of the platform's YAML uses.
func PortConflictError ¶
func PortConflictError(conflicts []PortConflict) error
PortConflictError renders conflicts as something an operator can act on.
func Save ¶
Atomic because this is the only record of the install's secrets; a partial write would lose the database.
func UserConfigPath ¶ added in v1.10.4
func UserConfigPath() string
Empty when there is no home directory, which the caller must handle.
Types ¶
type ACME ¶ added in v1.10.1
type ACME struct {
Email string `yaml:"email,omitempty"`
DirectoryURL string `yaml:"directoryUrl,omitempty"`
}
Email doubles as the admin login when none is given.
type AdminSpec ¶ added in v1.10.1
type AdminSpec struct {
Email string `yaml:"email,omitempty"`
}
Only the address: the password is a credential and is generated into spec.secrets.
type BackupDestination ¶ added in v1.10.1
type BackupDestination struct {
Endpoint string `yaml:"endpoint,omitempty"`
Bucket string `yaml:"bucket,omitempty"`
Region string `yaml:"region,omitempty"`
AccessKey string `yaml:"accessKey,omitempty"`
SecretKey string `yaml:"secretKey,omitempty"`
UseSSL *bool `yaml:"useSSL,omitempty"`
ForcePathStyle *bool `yaml:"forcePathStyle,omitempty"`
Path string `yaml:"path,omitempty"`
DatabasePath string `yaml:"databasePath,omitempty"`
VolumePath string `yaml:"volumePath,omitempty"`
}
All-or-nothing: with bucket, accessKey or secretKey missing the control plane ignores the block.
type BackupEncryption ¶ added in v1.10.1
type BackupEncryption struct {
Passphrase string `yaml:"passphrase,omitempty"`
Encrypt *bool `yaml:"encrypt,omitempty"`
IncludeIdentity *bool `yaml:"includeIdentity,omitempty"`
}
Never set the passphrase to the master key; includeIdentity seals the master key in for fresh-hardware restores.
type BackupRetention ¶ added in v1.10.1
BackupRetention caps whole recovery points. Zero is unbounded.
type BackupSpec ¶ added in v1.10.1
type BackupSpec struct {
Schedule string `yaml:"schedule,omitempty"`
Destination BackupDestination `yaml:"destination,omitempty"`
Encryption BackupEncryption `yaml:"encryption,omitempty"`
IncludeTenantData *bool `yaml:"includeTenantData,omitempty"`
Retention BackupRetention `yaml:"retention,omitempty"`
}
Stating any field pins the console's corresponding field.
type Component ¶
type Component struct {
Name string
Role string
State string // running, exited, …
Health string // healthy, unhealthy, starting, "" (no healthcheck)
Image string
ManagedBy string // compose | miabi | external | "" (an install predating labels)
Status string
}
Component is a running piece of the platform stack, as found on the engine.
type DNSSpec ¶ added in v1.10.1
type DNSSpec struct {
ReconcileMinutes int `yaml:"reconcileMinutes,omitempty"`
}
DNSSpec paces the managed-DNS re-assert sweep.
type Document ¶ added in v1.10.1
type Document struct {
APIVersion string `yaml:"apiVersion"`
Kind string `yaml:"kind"`
Metadata DocumentMeta `yaml:"metadata,omitempty"`
Spec Spec `yaml:"spec"`
}
Both this and the flat schema convert into Manifest, so nothing downstream learns which shape was read.
func NewDocument ¶ added in v1.10.1
NewDocument converts a manifest into its kinded form.
func ParseDocument ¶ added in v1.10.1
Unknown fields are refused: a silently ignored typo like `acme_emial:` would be an install with no ACME contact.
type DocumentMeta ¶ added in v1.10.1
type DocumentMeta struct {
Name string `yaml:"name,omitempty"`
}
type Endpoints ¶ added in v1.10.1
type Endpoints struct {
Web string `yaml:"web,omitempty"`
Control string `yaml:"control,omitempty"`
}
Control is separate from Web because a private-network node may reach the control plane at another address.
type ExternalSpec ¶ added in v1.10.1
type ExternalSpec struct {
BaseDomain string `yaml:"baseDomain,omitempty"`
CertProvider string `yaml:"certProvider,omitempty"`
}
Setting it here pins it; leave it empty to manage it from Clusters.
type Gateway ¶
type Gateway struct {
// Relative to the manifest's directory so it is backed up with it; empty means goma.yml.
Config string `yaml:"config,omitempty"`
// Lets an unmodified config receive upstream updates while a customized one is never clobbered.
ConfigSHA string `yaml:"config_sha,omitempty"`
// Variables Miabi sets itself are refused here, so there is never a second source of truth.
Env map[string]string `yaml:"env,omitempty"`
}
The config is a host file bind-mounted read-only; copying it into a volume would make the host file stale.
type GatewaySpec ¶ added in v1.10.1
type GatewaySpec struct {
Image string `yaml:"image,omitempty"`
Config string `yaml:"config,omitempty"`
// Written by Miabi only: the digest of the default config, which keeps a customized goma.yml from being overwritten.
ConfigSha string `yaml:"configSha,omitempty"`
Env map[string]string `yaml:"env,omitempty"`
// Only connections from these may set the client IP via forwarded headers; unset when facing the internet directly.
TrustedProxies []string `yaml:"trustedProxies,omitempty"`
// Needs a GeoIP database beside goma.yml; without one the header is never set.
CountryHeader bool `yaml:"countryHeader,omitempty"`
}
type HostPortsSpec ¶ added in v1.10.1
HostPortsSpec bounds the host ports an application may ask to publish.
type ImageSpec ¶ added in v1.10.1
type ImageSpec struct {
Image string `yaml:"image,omitempty"`
}
ImageSpec pins a component that has nothing to configure but the image it runs.
type Images ¶
type Images struct {
Miabi string `yaml:"miabi"`
Postgres string `yaml:"postgres"`
Redis string `yaml:"redis"`
Gateway string `yaml:"gateway"`
// Shown in the runner enrollment command, not run by the stack; the one image floating on :latest.
Runner string `yaml:"runner"`
}
Full refs, not bare tags, so `miabi setup` on two hosts a month apart produces the same stack.
type InstallSettings ¶ added in v1.10.1
type InstallSettings struct {
ACMEDirectoryURL string
RegistryStorage string
RegistryPlatformToken string
Pool PoolSpec
HostPorts HostPortsSpec
External ExternalSpec
DNS DNSSpec
Backup *BackupSpec
License LicenseSpec
GatewayTrustedProxies []string
GatewayCountryHeader bool
ServerTrustedProxies []string
}
Not serialized: the flat schema never had these, and the document writer maps them field by field.
type LicenseSpec ¶ added in v1.10.1
type LicenseSpec struct {
File string `yaml:"file,omitempty"`
}
Installed only when the database holds none: a console-added license takes precedence.
type Manifest ¶
type Manifest struct {
// Version is the manifest schema, not the Miabi version.
Version int `yaml:"version"`
Domain string `yaml:"domain"`
WebURL string `yaml:"web_url"`
ACMEEmail string `yaml:"acme_email"`
// Separate from WebURL because a private-network node may reach the control plane at another address.
ControlURL string `yaml:"control_url"`
Network NetworkConfig `yaml:"network"`
// A sibling key so pre-existing manifests keep parsing; nothing platform-internal may sit on the proxy network.
InternalNetwork NetworkConfig `yaml:"internal_network"`
Images Images `yaml:"images"`
Secrets Secrets `yaml:"secrets"`
Registry Registry `yaml:"registry"`
Gateway Gateway `yaml:"gateway"`
// May not contain a variable Miabi sets itself, or the loser of two sources of truth silently misconfigures.
Env map[string]string `yaml:"env,omitempty"`
DockerGID string `yaml:"docker_gid,omitempty"`
// A pointer because absent must mean "on"; turning it off is safe since /proc already reflects the host.
HostProc *bool `yaml:"host_proc"`
// Not serialized: the flat schema never had these, and the document writer maps them field by field.
Install InstallSettings `yaml:"-"`
// contains filtered or unexported fields
}
Manifest is the installed stack's desired state.
func (*Manifest) GenerateGatewayConfigKey ¶ added in v1.10.1
Called only for a fresh install.
func (*Manifest) GenerateSecrets ¶
Existing values are kept so a re-install never rotates live credentials and locks Miabi out of its database.
type NetworkConfig ¶
type NetworkingSpec ¶ added in v1.10.1
type NetworkingSpec struct {
Proxy NetworkConfig `yaml:"proxy,omitempty"`
Internal NetworkConfig `yaml:"internal,omitempty"`
Pool PoolSpec `yaml:"pool,omitempty"`
HostPorts HostPortsSpec `yaml:"hostPorts,omitempty"`
External ExternalSpec `yaml:"external,omitempty"`
DNS DNSSpec `yaml:"dns,omitempty"`
}
type PoolSpec ¶ added in v1.10.1
type PoolSpec struct {
CIDR string `yaml:"cidr,omitempty"`
SubnetPrefix int `yaml:"subnetPrefix,omitempty"`
IPv6ULAPrefix string `yaml:"ipv6UlaPrefix,omitempty"`
}
Explicit IPAM so Docker's small default pools cannot exhaust; must not overlap the proxy network, LAN or VPN.
type PortConflict ¶
type PortConflict struct {
Port int
// The host itself holds it when Docker can't see the process (system nginx, Apache, packaged Caddy).
Holder string
Container bool
}
PortConflict is something already holding a port the gateway needs.
func (PortConflict) String ¶
func (c PortConflict) String() string
type Registry ¶
type Registry struct {
Enabled bool `yaml:"enabled"`
// It gets its own DNS record and TLS certificate, separate from the panel's.
Host string `yaml:"host,omitempty"`
}
The manifest is the only home of enablement and host, so the admin UI shows them read-only.
type RegistrySpec ¶ added in v1.10.1
type RegistrySpec struct {
Enabled bool `yaml:"enabled"`
Host string `yaml:"host,omitempty"`
Storage string `yaml:"storage,omitempty"`
}
The host anchors every recorded image ref and decides workspace ownership, hence read-only in the console.
type SecretsSpec ¶ added in v1.10.1
type SecretsSpec struct {
DBPassword string `yaml:"dbPassword,omitempty"`
RedisPassword string `yaml:"redisPassword,omitempty"`
JWTSecret string `yaml:"jwtSecret,omitempty"`
EncryptionKey string `yaml:"encryptionKey,omitempty"`
AdminPassword string `yaml:"adminPassword,omitempty"`
// Safe to lose: the gateway config is re-rendered from the database on every sync.
GomaConfigEncryptionKey string `yaml:"gomaConfigEncryptionKey,omitempty"`
RegistryPlatformToken string `yaml:"registryPlatformToken,omitempty"`
}
Plaintext, but the file is 0600 and anyone who can read it already holds the Docker socket.
type ServerSpec ¶ added in v1.10.1
type ServerSpec struct {
Image string `yaml:"image,omitempty"`
// HostProc is a pointer because absent must mean on.
HostProc *bool `yaml:"hostProc,omitempty"`
DockerGid string `yaml:"dockerGid,omitempty"`
// Defaults to the private network, the only one the gateway reaches it on.
TrustedProxies []string `yaml:"trustedProxies,omitempty"`
Env map[string]string `yaml:"env,omitempty"`
}
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service installs and updates the stack.
func (*Service) AllowNetworkRecreate ¶ added in v1.10.22
func (s *Service) AllowNetworkRecreate()
Off by default since a recreate briefly detaches every container; only setup enables it after showing the plan.
func (*Service) CheckDaemon ¶ added in v1.10.22
The control plane hands containers /var/run/docker.sock, which a rootless daemon doesn't serve.
func (*Service) CheckOrphanedData ¶
Postgres honours POSTGRES_PASSWORD only on an empty data dir, and pg_isready doesn't check credentials.
func (*Service) CheckPorts ¶
func (s *Service) CheckPorts(ctx context.Context) ([]PortConflict, error)
Two passes: Docker's containers to name the culprit, then a real bind for processes Docker can't see.
func (*Service) Component ¶
Exported so the CLI can validate `miabi upgrade <component>` before touching anything.
func (*Service) ComponentNames ¶
ComponentNames lists the updatable components, in dependency order.
func (*Service) Converge ¶
Safe to re-run; Postgres and Redis must be healthy before the control plane, gateway last so it fails closed.
func (*Service) ConvergeData ¶
For disaster recovery: a control plane booting first would AutoMigrate and collide with the dump's CREATE TABLEs.
func (*Service) Discover ¶
By role, so `miabi system status` describes a Compose install as well as a CLI one.
func (*Service) DumpDatabase ¶ added in v1.10.21
Uses the manifest's Postgres image so pg_dump is never older than the server; renamed only on clean exit.
func (*Service) EnsureGatewayConfig ¶
A file that no longer matches the recorded default digest was edited by the operator and is never touched.
func (*Service) IPv6Upgrades ¶ added in v1.10.22
Docker cannot enable IPv6 on an existing network, so each must be recreated; see AllowNetworkRecreate.
func (*Service) NodeGatewayImageDrift ¶ added in v1.10.6
The value rides the control plane's env and is re-rendered only when that container is recreated.
func (*Service) Restart ¶
Restarts rather than recreates, so spec changes need `miabi setup`; stores first, gateway last.
func (*Service) RestoreDatabase ¶ added in v1.10.21
Loaded into a scratch DB and swapped in only on success, so a bad dump leaves the live database untouched.
func (*Service) StopControlPlane ¶ added in v1.10.21
The control plane is stateless; Converge recreates it from the manifest.
type Spec ¶ added in v1.10.1
type Spec struct {
Domain string `yaml:"domain"`
Endpoints Endpoints `yaml:"endpoints,omitempty"`
ACME ACME `yaml:"acme,omitempty"`
Server ServerSpec `yaml:"server,omitempty"`
Database ImageSpec `yaml:"database,omitempty"`
Cache ImageSpec `yaml:"cache,omitempty"`
Gateway GatewaySpec `yaml:"gateway,omitempty"`
Registry RegistrySpec `yaml:"registry,omitempty"`
Admin AdminSpec `yaml:"admin,omitempty"`
Secrets SecretsSpec `yaml:"secrets,omitempty"`
Networking NetworkingSpec `yaml:"networking,omitempty"`
Backup *BackupSpec `yaml:"backup,omitempty"`
License LicenseSpec `yaml:"license,omitempty"`
RunnerImage string `yaml:"runnerImage,omitempty"`
}
Pointers because an emitted env var locks the field in the UI, so "unset" and "zero" must differ.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package docker is the stack engine's Docker seam; no Docker SDK types cross it.
|
Package docker is the stack engine's Docker seam; no Docker SDK types cross it. |
|
Package saferollout tests a new image under a throwaway name before promoting, with rollback on failure.
|
Package saferollout tests a new image under a throwaway name before promoting, with rollback on failure. |
|
Package selfcontainer detects Miabi's own container ID so the admin UI can refuse to stop or delete it.
|
Package selfcontainer detects Miabi's own container ID so the admin UI can refuse to stop or delete it. |
|
Package stackcmd holds host-side verb behaviour shared by the cobra CLI and the image's okapicli, so they can't drift.
|
Package stackcmd holds host-side verb behaviour shared by the cobra CLI and the image's okapicli, so they can't drift. |