declarative

package
v1.10.26 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: AGPL-3.0 Imports: 27 Imported by: 0

Documentation

Overview

Package declarative is the miabi.io/v1 resource model shared by apply, GitOps, Terraform and marketplace templates.

Index

Constants

View Source
const (
	SecretLower   = "abcdefghijklmnopqrstuvwxyz"
	SecretUpper   = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
	SecretDigits  = "0123456789"
	SecretSymbols = "!#$%&()*+,-./:;<=>?@[]^_{|}~"
)

Must match the console generator's alphabet (useGenerator.ts); quotes, backslash and backtick break shells and YAML.

View Source
const (
	// RunOnChange fingerprint covers command, entrypoint, image, registry, runAsUser and timeout.
	RunOnChange = "onChange"
	// RunOnce runs the Job exactly once per name; later spec edits are refused. Rename it to run again.
	RunOnce = "once"
	// RunOnRelease fires however the deploy started (GitOps, console, pipeline, rollback).
	RunOnRelease = "onRelease"
)

Job run policies.

View Source
const (
	DeletePolicyOrphan  = "orphan"
	DeletePolicyCascade = "cascade"
)

GitSource delete policies.

View Source
const (
	MaxConfigFileBytes  = 256 * 1024
	MaxConfigTotalBytes = 512 * 1024
	DefaultFileMode     = "0644"
	ReloadRestart       = "restart"
	ReloadNone          = "none"
)

The per-file cap matters against Docker's 500 KB config-object limit, since projection is per file.

View Source
const APIVersion = "miabi.io/v1"

APIVersion is shared with the marketplace manifest engine so the two stay in lock-step.

View Source
const AnnotationSkipInitialRun = "miabi.io/skip-initial-run"

AnnotationSkipInitialRun adopts a job that has already run elsewhere without running it again.

View Source
const DefaultRegistryServer = "registry-1.docker.io"

DefaultRegistryServer duplicates registry.DefaultServer to avoid service deps; they must agree or registries diff.

View Source
const DefaultSecretLength = 32
View Source
const JobSpecField = "spec"

JobSpecField is the diff field a changed Job run template shows up as.

View Source
const LabelGitOpsSource = "miabi.io/gitops-source"

LabelGitOpsSource lets one GitOps project's resources be torn down without touching another's.

View Source
const LabelManagedBy = "miabi.io/managed-by"

LabelManagedBy keeps prune from ever deleting a resource the apply engine did not create.

View Source
const SchemaFileName = "miabi.io-v1.schema.json"

SchemaFileName is shared so the generator, docs site and editor extension cannot disagree.

View Source
const SchemaID = "https://docs.miabi.io/schema/miabi.io-v1.schema.json"

SchemaID must be the URL the file is served from, since editors resolve $ref against it.

Variables

View Source
var ErrNoResources = errors.New("no declarative resources found")

ErrNoResources is distinct from fs.ErrNotExist so callers can tell an intentional teardown from an error.

Functions

func CheckReferences added in v1.10.12

func CheckReferences(refs []Reference, known KnownNames) error

CheckReferences never flags an existing name, so it never blocks what apply would accept.

func GenerateSecret added in v1.9.0

func GenerateSecret(spec SecretSpec) string

GenerateSecret trims minimums that exceed the length (symbols first) rather than silently disobeying them.

func IsVaultSecret added in v1.10.15

func IsVaultSecret(k Kind) bool

IsVaultSecret: Secret and SealedSecret share one name space, so a name is either, never both.

func JSONSchema added in v1.8.2

func JSONSchema() ([]byte, error)

func Marshal

func Marshal(set *ResourceSet) ([]byte, error)

Marshal omits Project resources; their children are already first-class members of the set.

func NormalizeGitURL added in v1.10.20

func NormalizeGitURL(raw string) string

Matches the credential store's ".git" suffix so an unsuffixed URL converges.

func PlainSecrets added in v1.10.15

func PlainSecrets(set *ResourceSet) []string

PlainSecrets lists the Secrets in a set that carry a plaintext value. A generated Secret has none.

func RandAlphaNum

func RandAlphaNum(n int) string

func ValidPortName added in v1.10.26

func ValidPortName(name string) bool

ValidPortName refuses a digit-only name, which a Route would read as a port number.

Types

type Action

type Action string

Action is the operation a plan entry performs.

const (
	ActionCreate Action = "create"
	ActionUpdate Action = "update"
	ActionDelete Action = "delete"
	ActionNoop   Action = "noop"
)

type AppView added in v1.9.3

type AppView struct {
	Host   string
	Port   string
	Scheme string
	Alias  string
}

Host is the app's own name, aliased on every workspace network; Alias predates it and Config files use it.

func (AppView) URL added in v1.9.3

func (a AppView) URL() string

URL omits the port when none is declared, rather than emitting a trailing colon.

type ApplicationPlacementSpec added in v1.10.0

type ApplicationPlacementSpec struct {
	// Location defaults to the stack, a mounted volume or referenced databases, else the workspace default; fixed once created.
	Location string `yaml:"location,omitempty" json:"location,omitempty"`
	// Constraints use Swarm syntax (node.labels.disk==ssd); an empty list clears them, omitting keeps them.
	Constraints []string `yaml:"constraints,omitempty" json:"constraints,omitempty"`
}

ApplicationPlacementSpec is where an application runs.

type ApplicationSpec

type ApplicationSpec struct {
	// Source and image are mutually exclusive: an app either builds or pulls.
	Source    *SourceSpec               `yaml:"source,omitempty" json:"source,omitempty"`
	Image     string                    `yaml:"image,omitempty" json:"image,omitempty"`
	Tag       string                    `yaml:"tag,omitempty" json:"tag,omitempty"`
	Digest    string                    `yaml:"digest,omitempty" json:"digest,omitempty"` // sha256:… (immutable pin)
	Command   []string                  `yaml:"command,omitempty" json:"command,omitempty"`
	Ports     []PortSpec                `yaml:"ports,omitempty" json:"ports,omitempty"`
	Env       map[string]string         `yaml:"env,omitempty" json:"env,omitempty"`
	SecretEnv []string                  `yaml:"secretEnv,omitempty" json:"secretEnv,omitempty"` // keys stored encrypted; vault references need none, apply-resolved credentials are added
	Mounts    []MountSpec               `yaml:"mounts,omitempty" json:"mounts,omitempty"`
	Resources *ResourceSpec             `yaml:"resources,omitempty" json:"resources,omitempty"`
	Placement *ApplicationPlacementSpec `yaml:"placement,omitempty" json:"placement,omitempty"`
	// Deployment is how the app runs and how a new release replaces the running one.
	Deployment *DeploymentSpec `yaml:"deployment,omitempty" json:"deployment,omitempty"`
	// Security is checked on apply the way the console checks it.
	Security *SecuritySpec `yaml:"security,omitempty" json:"security,omitempty"`
	// Healthcheck gates releases so a broken one never replaces a working one; omitted keeps the current check.
	Healthcheck *HealthcheckSpec `yaml:"healthcheck,omitempty" json:"healthcheck,omitempty"`
	// ContainerLabels reserved keys (io.miabi.*, com.docker.*) are stripped on apply rather than rejected.
	ContainerLabels map[string]string `yaml:"containerLabels,omitempty" json:"containerLabels,omitempty"`
	// Stack optionally names the owning Stack resource.
	Stack string `yaml:"stack,omitempty" json:"stack,omitempty"`
	// Registry empty means an anonymous pull; an undeclared name resolves against existing workspace credentials.
	Registry string `yaml:"registry,omitempty" json:"registry,omitempty"`
	// ExternalLabel is platform-wide unique; a claimed one is ignored for a generated label.
	ExternalLabel string `yaml:"externalLabel,omitempty" json:"externalLabel,omitempty"`
	// ReloadPolicy "restart" (default) redeploys on config change; "none" suits apps that watch their own config.
	ReloadPolicy string `yaml:"reloadPolicy,omitempty" json:"reloadPolicy,omitempty"`
	// Deprecated: use security.runAsUser. Still accepted; setting both is an error.
	DeprecatedRunAsUser string `yaml:"runAsUser,omitempty" json:"runAsUser,omitempty"`
	// Deprecated: use deployment.strategy. Still accepted; setting both is an error.
	DeprecatedStrategy string `yaml:"strategy,omitempty" json:"strategy,omitempty"`
	// ConfigFP is derived state filled on both sides of the diff, so a config content change converges.
	ConfigFP string `yaml:"-" json:"-"`
}

ApplicationSpec Digest is written by CI; GitOps converges runtime to it.

func (*ApplicationSpec) AddCapabilities added in v1.10.0

func (a *ApplicationSpec) AddCapabilities() []string

AddCapabilities are the capabilities the app is granted.

func (*ApplicationSpec) Constraints added in v1.10.0

func (a *ApplicationSpec) Constraints() []string

Constraints are the app's Swarm placement constraints; nil when unstated, empty when cleared.

func (*ApplicationSpec) Devices added in v1.10.0

func (a *ApplicationSpec) Devices() []string

Devices are the host devices exposed to the app.

func (*ApplicationSpec) DropCapabilities added in v1.10.0

func (a *ApplicationSpec) DropCapabilities() []string

DropCapabilities are the capabilities the app drops.

func (*ApplicationSpec) Location added in v1.10.0

func (a *ApplicationSpec) Location() string

Location is the location the app names, or "" when it names none.

func (*ApplicationSpec) NoNewPrivileges added in v1.10.0

func (a *ApplicationSpec) NoNewPrivileges() bool

NoNewPrivileges reports whether the app asks for no-new-privileges.

func (*ApplicationSpec) ReadOnlyRootFilesystem added in v1.10.0

func (a *ApplicationSpec) ReadOnlyRootFilesystem() bool

ReadOnlyRootFilesystem reports whether the container's root filesystem is read-only.

func (*ApplicationSpec) Replicas added in v1.10.0

func (a *ApplicationSpec) Replicas() int

Replicas is the replica count the app names, or 0 when it names none.

func (*ApplicationSpec) RunAsUser added in v1.8.3

func (a *ApplicationSpec) RunAsUser() string

RunAsUser is the account the container runs as, or "" for the image's own.

func (*ApplicationSpec) Runtime added in v1.10.0

func (a *ApplicationSpec) Runtime() string

Runtime is the runtime the app names, or "" when it names none.

func (*ApplicationSpec) Strategy added in v1.9.3

func (a *ApplicationSpec) Strategy() string

Strategy is the rollout strategy the app names, or "" when it names none.

func (*ApplicationSpec) Update added in v1.10.0

func (a *ApplicationSpec) Update() *UpdateSpec

Update is the service rollout tuning, or nil when unstated.

type CapabilitiesSpec added in v1.10.0

type CapabilitiesSpec struct {
	// Add refuses anything off the allow-list on apply rather than dropping it.
	Add []string `yaml:"add,omitempty" json:"add,omitempty"`
	// Drop removes capabilities from the default set. ALL removes every one, leaving only what add grants.
	Drop []string `yaml:"drop,omitempty" json:"drop,omitempty"`
}

CapabilitiesSpec changes the Linux capabilities a container starts with. The CAP_ prefix is optional.

type Change

type Change struct {
	Action Action      `json:"action"`
	Kind   Kind        `json:"kind"`
	Name   string      `json:"name"`
	Reason string      `json:"reason,omitempty"`
	Fields []FieldDiff `json:"fields,omitempty"`
}

Change is one entry in a plan: what happens to one resource.

type ConfigSpec added in v1.8.1

type ConfigSpec struct {
	Data map[string]string `yaml:"data" json:"data"`
	// Mode is the default octal file mode applied to every key ("0644" when empty).
	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`
	// Sensitive redacts content in API responses and diffs it by digest only.
	Sensitive bool `yaml:"sensitive,omitempty" json:"sensitive,omitempty"`
	// Delimiters must be exactly two distinct entries.
	Delimiters []string `yaml:"delimiters,omitempty" json:"delimiters,omitempty"`
	// DigestFP is derived state filled on both sides of the diff, never serialized.
	DigestFP string `yaml:"-" json:"-"`
}

ConfigSpec values are interpolated like env, so a config can carry a rendered database password.

type ConnView

type ConnView struct {
	Host     string
	Port     string
	User     string
	Password string
	Name     string
	URI      string
	// The read-only user, when the database has one (readOnlyUser: true); empty otherwise.
	ReadOnlyUser     string
	ReadOnlyPassword string
	ReadOnlyURI      string
	PasswordSecret   string
	URISecret        string
}

type CronJobSpec added in v1.10.13

type CronJobSpec struct {
	// App is immutable: moving a schedule to another app is a delete and a create.
	App string `yaml:"app" json:"app"`
	// Schedule is a standard 5-field cron expression, evaluated in UTC.
	Schedule string `yaml:"schedule" json:"schedule"`
	// Command is the command to run, as a list of arguments (no shell).
	Command []string `yaml:"command" json:"command"`
	// Entrypoint overrides the image's entrypoint.
	Entrypoint []string `yaml:"entrypoint,omitempty" json:"entrypoint,omitempty"`
	// Image runs a different image in the app's runtime context; omitted runs the app's active release.
	Image string `yaml:"image,omitempty" json:"image,omitempty"`
	// Registry names the Registry credential that pulls Image. Only valid with image.
	Registry string `yaml:"registry,omitempty" json:"registry,omitempty"`
	// TimeoutSeconds stops a run that takes longer; 0 uses the platform default.
	TimeoutSeconds int `yaml:"timeoutSeconds,omitempty" json:"timeoutSeconds,omitempty"`
	// ConcurrencyPolicy is allow (default), forbid (skip the fire) or replace (cancel the running one).
	ConcurrencyPolicy string `yaml:"concurrencyPolicy,omitempty" json:"concurrencyPolicy,omitempty"`
	// HistoryLimit is how many finished runs to keep; 0 keeps the default 20.
	HistoryLimit int `yaml:"historyLimit,omitempty" json:"historyLimit,omitempty"`
	// Suspend omitted leaves the live value alone, so a console pause survives a sync.
	Suspend *bool `yaml:"suspend,omitempty" json:"suspend,omitempty"`
	// Security pins the account runs use; omitted inherits the app's when each run fires.
	Security *SecuritySpec `yaml:"security,omitempty" json:"security,omitempty"`
}

CronJobSpec runs on the app's active release unless Image overrides it.

func (*CronJobSpec) RunAsUser added in v1.10.13

func (c *CronJobSpec) RunAsUser() string

RunAsUser returns the pinned account, or "".

type DatabasePlacementSpec added in v1.10.0

type DatabasePlacementSpec struct {
	// Location names where the database is created; omitted, the workspace default. Fixed once created.
	Location string `yaml:"location,omitempty" json:"location,omitempty"`
	// contains filtered or unexported fields
}

DatabasePlacementSpec also accepts the old string form (placement: dedicated) as instance.

func (*DatabasePlacementSpec) UnmarshalYAML added in v1.10.0

func (p *DatabasePlacementSpec) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML reads the block, or the bare string the field held before it became one.

type DatabaseResourcesSpec added in v1.10.0

type DatabaseResourcesSpec struct {
	Memory string `yaml:"memory,omitempty" json:"memory,omitempty"`
	CPU    string `yaml:"cpu,omitempty" json:"cpu,omitempty"`
	// Size names a database size the platform offers (Enterprise), instead of memory and cpu.
	Size string `yaml:"size,omitempty" json:"size,omitempty"`
}

DatabaseResourcesSpec memory accepts Ki/Mi/Gi, CPU is cores ("0.5"); "0" removes a limit.

func (*DatabaseResourcesSpec) MemoryBytes added in v1.10.0

func (r *DatabaseResourcesSpec) MemoryBytes() (int64, error)

MemoryBytes parses the memory limit into bytes; empty or "0" is unlimited.

func (*DatabaseResourcesSpec) NanoCPUs added in v1.10.0

func (r *DatabaseResourcesSpec) NanoCPUs() (int64, error)

NanoCPUs parses the CPU limit into nano-CPUs; empty or "0" is unlimited.

type DatabaseSpec

type DatabaseSpec struct {
	Engine  string `yaml:"engine" json:"engine"`                       // postgres|mysql|mariadb|redis|mongodb|libsql
	Version string `yaml:"version,omitempty" json:"version,omitempty"` // e.g. "16-alpine"
	// Instance is auto (reuse a compatible one, else provision), dedicated (always provision) or shared (must exist).
	Instance string `yaml:"instance,omitempty" json:"instance,omitempty"`
	// Placement's string form (placement: dedicated) is the deprecated spelling of instance.
	Placement *DatabasePlacementSpec `yaml:"placement,omitempty" json:"placement,omitempty"`
	// Resources give the database its own instance, since a reused one runs with another's size; omitted keeps limits.
	Resources *DatabaseResourcesSpec `yaml:"resources,omitempty" json:"resources,omitempty"`
	// ReadOnlyUser (PostgreSQL) grants SELECT on all tables; omitted keeps what it has, false removes it.
	ReadOnlyUser *bool `yaml:"readOnlyUser,omitempty" json:"readOnlyUser,omitempty"`
}

DatabaseSpec requests a logical database on a DatabaseInstance.

func (*DatabaseSpec) Location added in v1.10.0

func (d *DatabaseSpec) Location() string

Location is the location the database names, or "".

type DeploymentSpec added in v1.10.0

type DeploymentSpec struct {
	// Runtime service needs a location that runs a swarm; omitted, an existing app keeps its runtime.
	Runtime string `yaml:"runtime,omitempty" json:"runtime,omitempty"`
	// Replicas is 1 to 100; omitted keeps the current count, so a console scale is not undone.
	Replicas int `yaml:"replicas,omitempty" json:"replicas,omitempty"`
	// Strategy is recreate, rolling or canary; omitted keeps the configured strategy.
	Strategy string `yaml:"strategy,omitempty" json:"strategy,omitempty"`
	// Update tunes how Swarm rolls a new release of a service out.
	Update *UpdateSpec `yaml:"update,omitempty" json:"update,omitempty"`
}

DeploymentSpec is how an application runs and rolls out.

type DomainSpec

type DomainSpec struct {
	TLS      string `yaml:"tls,omitempty" json:"tls,omitempty"` // acme|custom (default acme)
	Wildcard bool   `yaml:"wildcard,omitempty" json:"wildcard,omitempty"`
}

DomainSpec wildcard also covers *.name; ownership verification is a runtime action.

type Edge

type Edge struct {
	From string   `json:"from"`
	To   string   `json:"to"`
	Type EdgeType `json:"type"`
}

func Edges

func Edges(set *ResourceSet) []Edge

Edges must run on the un-rendered set, where env templates still reveal soft references.

type EdgeType

type EdgeType string
const (
	EdgeMount    EdgeType = "mount"    // Application -> Volume (mounts[].volume)
	EdgeStack    EdgeType = "stack"    // Application -> Stack  (stack)
	EdgeRoute    EdgeType = "route"    // Route       -> Application (app)
	EdgeDomain   EdgeType = "domain"   // Route       -> Domain (host under the domain)
	EdgeDatabase EdgeType = "database" // Application -> Database (env {{ .databases.X }})
	EdgeSecret   EdgeType = "secret"   // Application -> Secret   (env {{ .secrets.X }})
	EdgeAppRef   EdgeType = "app-ref"  // Application -> Application (env {{ .applications.X }})
	EdgeRegistry EdgeType = "registry" // Application -> Registry (spec.registry)
	EdgeConfig   EdgeType = "config"   // Application -> Config   (mounts[].config)
	// Only drawn for a middleware in the same bundle; naming an existing workspace one is not a dangling reference.
	EdgeMiddleware EdgeType = "middleware"
	// EdgeSchedule is CronJob -> Application (spec.app).
	EdgeSchedule EdgeType = "schedule"
	// EdgeRun is Job -> Application (spec.app).
	EdgeRun EdgeType = "run"
	// EdgeRepository is Application or GitSource -> GitRepository (the credential it clones with).
	EdgeRepository EdgeType = "repository"
)

type FieldDiff

type FieldDiff struct {
	Field string `json:"field"`
	From  string `json:"from"`
	To    string `json:"to"`
}

FieldDiff is a single changed field in an update.

type GitRepositorySpec added in v1.10.20

type GitRepositorySpec struct {
	URL       string `yaml:"url" json:"url"`
	Auth      string `yaml:"auth,omitempty" json:"auth,omitempty"` // public|token|ssh (default token with a secretRef, else public)
	Username  string `yaml:"username,omitempty" json:"username,omitempty"`
	SecretRef string `yaml:"secretRef,omitempty" json:"secretRef,omitempty"`
}

GitRepositorySpec is safe to commit when the SecretRef vault entry is sealed.

type GitSourceSpec added in v1.10.20

type GitSourceSpec struct {
	Repo       string `yaml:"repo,omitempty" json:"repo,omitempty"`
	Repository string `yaml:"repository,omitempty" json:"repository,omitempty"`
	Ref        string `yaml:"ref,omitempty" json:"ref,omitempty"`               // branch, tag or commit (default main)
	Path       string `yaml:"path,omitempty" json:"path,omitempty"`             // manifest directory (default .)
	SyncPolicy string `yaml:"syncPolicy,omitempty" json:"syncPolicy,omitempty"` // manual|auto (default manual)
	Prune      bool   `yaml:"prune,omitempty" json:"prune,omitempty"`
	SelfHeal   bool   `yaml:"selfHeal,omitempty" json:"selfHeal,omitempty"`
	AllowEmpty bool   `yaml:"allowEmpty,omitempty" json:"allowEmpty,omitempty"`
	// RequireSealedSecrets refuses a sync whose manifests carry a plaintext Secret value.
	RequireSealedSecrets bool `yaml:"requireSealedSecrets,omitempty" json:"requireSealedSecrets,omitempty"`
	// DeletePolicy orphan (default) keeps a mistaken prune harmless; cascade tears resources down.
	DeletePolicy string `yaml:"deletePolicy,omitempty" json:"deletePolicy,omitempty"`
}

GitSourceSpec webhook secret is generated on create and never declared.

type HealthcheckSpec added in v1.10.12

type HealthcheckSpec struct {
	// Type is http, command, image (the image's HEALTHCHECK, default) or none (not even the image's).
	Type string `yaml:"type" json:"type"`
	// Path is the URL path an http check requests, e.g. /healthz.
	Path string `yaml:"path,omitempty" json:"path,omitempty"`
	// Port is the container port an http check probes. Omitted, the app's first port.
	Port int `yaml:"port,omitempty" json:"port,omitempty"`
	// Command needs a shell in the image; an http check does not.
	Command            string `yaml:"command,omitempty" json:"command,omitempty"`
	IntervalSeconds    int    `yaml:"intervalSeconds,omitempty" json:"intervalSeconds,omitempty"`
	TimeoutSeconds     int    `yaml:"timeoutSeconds,omitempty" json:"timeoutSeconds,omitempty"`
	Retries            int    `yaml:"retries,omitempty" json:"retries,omitempty"`
	StartPeriodSeconds int    `yaml:"startPeriodSeconds,omitempty" json:"startPeriodSeconds,omitempty"`
}

HealthcheckSpec applies only stated fields; the rest keep their current value.

type JobSpec added in v1.10.13

type JobSpec struct {
	// App is the Application the command runs in. Immutable.
	App string `yaml:"app" json:"app"`
	// Command is the command to run, as a list of arguments (no shell).
	Command []string `yaml:"command" json:"command"`
	// Entrypoint overrides the image's entrypoint.
	Entrypoint []string `yaml:"entrypoint,omitempty" json:"entrypoint,omitempty"`
	// Image runs a different image in the app's runtime context; omitted runs the app's active release.
	Image string `yaml:"image,omitempty" json:"image,omitempty"`
	// Registry names the Registry credential that pulls Image. Only valid with image.
	Registry string `yaml:"registry,omitempty" json:"registry,omitempty"`
	// TimeoutSeconds stops a run that takes longer; 0 uses the platform default.
	TimeoutSeconds int    `yaml:"timeoutSeconds,omitempty" json:"timeoutSeconds,omitempty"`
	RunPolicy      string `yaml:"runPolicy,omitempty" json:"runPolicy,omitempty"`
	// WaitForDeploy (onChange only) runs on the new release; a failed deploy marks the run skipped.
	WaitForDeploy *bool `yaml:"waitForDeploy,omitempty" json:"waitForDeploy,omitempty"`
	// HistoryLimit is how many finished runs to keep; 0 keeps the default 20.
	HistoryLimit int `yaml:"historyLimit,omitempty" json:"historyLimit,omitempty"`
	// BackoffLimit 0 never retries; retries start a new run, a sync never does.
	BackoffLimit int `yaml:"backoffLimit,omitempty" json:"backoffLimit,omitempty"`
	// Security pins the account runs use; omitted inherits the app's.
	Security *SecuritySpec `yaml:"security,omitempty" json:"security,omitempty"`
	// SpecFP is derived state filled on the live side, never serialized.
	SpecFP string `yaml:"-" json:"-"`
}

JobSpec never runs twice for the same commit; a failed run is not retried by the next sync.

func (*JobSpec) Fingerprint added in v1.10.13

func (j *JobSpec) Fingerprint() string

Fingerprint covers what a run executes; policy, history and app are excluded.

func (*JobSpec) Policy added in v1.10.13

func (j *JobSpec) Policy() string

Policy returns the run policy, defaulting to onChange.

func (*JobSpec) RunAsUser added in v1.10.13

func (j *JobSpec) RunAsUser() string

RunAsUser returns the pinned account, or "".

func (*JobSpec) Waits added in v1.10.13

func (j *JobSpec) Waits() bool

Waits reports whether a run is held while the app has a deploy in flight.

type Kind

type Kind string
const (
	KindApplication Kind = "Application"
	KindStack       Kind = "Stack"
	KindDatabase    Kind = "Database"
	KindVolume      Kind = "Volume"
	// KindRoute exposes an app on a hostname; KindDomain is the owned zone with ownership and default TLS.
	KindRoute  Kind = "Route"
	KindSecret Kind = "Secret"
	// KindSealedSecret is sealed to the workspace public key so it is safe to commit; same vault namespace as Secret.
	KindSealedSecret Kind = "SealedSecret"
	// KindDomain ownership verification is a runtime action, not a declarable field.
	KindDomain Kind = "Domain"
	// KindRegistry is not called a secret because Secret is the vault; apps reference it via spec.registry.
	KindRegistry Kind = "Registry"
	// KindProject bundles a set of resources living in one repo/namespace.
	KindProject Kind = "Project"
	// KindConfig carries named files projected read-only into containers; encrypted at rest like Secret.
	KindConfig Kind = "Config"
	// KindMiddleware is its own resource so one policy can be shared by many routes instead of copied.
	KindMiddleware Kind = "Middleware"
	// KindCronJob runs in the Application's runtime context (same image, env, networks and volumes).
	KindCronJob Kind = "CronJob"
	// KindJob runs only when its runPolicy says so, never again for an unchanged spec.
	KindJob Kind = "Job"
	// KindGitSource declared from a GitOps repository nests one project under another ("app of apps").
	KindGitSource Kind = "GitSource"
	// KindGitRepository never carries the token or SSH key; it is read from the vault.
	KindGitRepository Kind = "GitRepository"
)

type KnownNames added in v1.10.12

type KnownNames map[string]map[string]bool

type Meta

type Meta struct {
	Name string `yaml:"name" json:"name"`
	// UID survives restores and renames; when set it is matched ahead of name.
	UID         string            `yaml:"uid,omitempty" json:"uid,omitempty"`
	Labels      map[string]string `yaml:"labels,omitempty" json:"labels,omitempty"`
	Annotations map[string]string `yaml:"annotations,omitempty" json:"annotations,omitempty"`
}

Custom metadata belongs in Labels or Annotations, never as ad-hoc top-level keys.

type MiddlewareSpec added in v1.9.3

type MiddlewareSpec struct {
	Type string `yaml:"type" json:"type"`
	// Paths empty applies the middleware to everything the route serves.
	Paths []string `yaml:"paths,omitempty" json:"paths,omitempty"`
	// Rule is the type's configuration, passed through to the gateway.
	Rule   map[string]any `yaml:"rule,omitempty" json:"rule,omitempty"`
	RuleFP string         `yaml:"-" json:"-"`
}

MiddlewareSpec Rule is the gateway type's own configuration, passed through untranslated.

type MountSpec

type MountSpec struct {
	Volume string `yaml:"volume,omitempty" json:"volume,omitempty"`
	Config string `yaml:"config,omitempty" json:"config,omitempty"`
	// Key makes Path that file's exact location; empty projects every key under Path as a directory.
	Key      string `yaml:"key,omitempty" json:"key,omitempty"`
	Path     string `yaml:"path" json:"path"`
	Mode     string `yaml:"mode,omitempty" json:"mode,omitempty"`
	ReadOnly bool   `yaml:"readOnly,omitempty" json:"readOnly,omitempty"`
}

MountSpec attaches a managed Volume into the container filesystem.

type PlacementSpec added in v1.10.0

type PlacementSpec struct {
	// Location names where the resource is created; omitted, the workspace default. Fixed once created.
	Location string `yaml:"location,omitempty" json:"location,omitempty"`
}

PlacementSpec is where a stack or volume is created.

type Plan

type Plan struct {
	Changes []Change `json:"changes"`
}

func BuildPlan

func BuildPlan(desired, actual *ResourceSet, opts PlanOptions) *Plan

BuildPlan expects actual to hold only Miabi-managed resources when Prune is set.

func (*Plan) Counts

func (p *Plan) Counts() (create, update, del, noop int)

Counts tallies the plan by action.

func (*Plan) HasChanges

func (p *Plan) HasChanges() bool

HasChanges reports whether the plan mutates anything.

type PlanOptions

type PlanOptions struct {
	// Prune emits deletes for actual resources absent from desired.
	Prune bool
	// PruneManagedBy keeps a GitOps prune from deleting hand-created resources; empty prunes any orphan.
	PruneManagedBy string
	// PruneGitOpsSource scopes prune to one project; resources with no source label are never matched.
	PruneGitOpsSource string
	// IncludeNoop keeps in-sync resources in the plan (useful for status views).
	IncludeNoop bool
}

PlanOptions tunes plan generation.

type PortSpec

type PortSpec struct {
	// Name lets a Route target the port by name instead of its number.
	Name      string `yaml:"name,omitempty" json:"name,omitempty"`
	Container int    `yaml:"container" json:"container"`
	Protocol  string `yaml:"protocol,omitempty" json:"protocol,omitempty"` // tcp|udp (default tcp)
	Scheme    string `yaml:"scheme,omitempty" json:"scheme,omitempty"`     // http|https (default http)
	// ExternalAccess requires the base domain to be configured platform-wide.
	ExternalAccess bool `yaml:"externalAccess,omitempty" json:"externalAccess,omitempty"`
	// HostPort 0 auto-allocates from the pool.
	Publish  bool `yaml:"publish,omitempty" json:"publish,omitempty"`
	HostPort int  `yaml:"hostPort,omitempty" json:"hostPort,omitempty"`
}

PortSpec exposure knobs are orthogonal: externalAccess is a public HTTPS URL, publish binds a raw node port.

type ProjectSpec

type ProjectSpec struct {
	Description string     `yaml:"description,omitempty" json:"description,omitempty"`
	Resources   []Resource `yaml:"-" json:"resources,omitempty"`
}

type Reference added in v1.10.12

type Reference struct {
	// Where locates it for an error message, e.g. `application "web" env DATABASE_URL`.
	Where      string
	Collection string // databases | secrets | applications | inputs
	Name       string
	Field      string // empty when the reference names no field
}

Reference is one {{ .collection.name.field }} reference a bundle's templates make.

func (Reference) String added in v1.10.12

func (r Reference) String() string

type RegistrySpec added in v1.7.3

type RegistrySpec struct {
	Server   string `yaml:"server,omitempty" json:"server,omitempty"`
	Username string `yaml:"username,omitempty" json:"username,omitempty"`
	Password string `yaml:"password,omitempty" json:"password,omitempty"`
	// PasswordFP is derived state, so a Marshal->Parse round trip (GitOps canonicalization) recomputes it.
	PasswordFP string `yaml:"-" json:"-"`
}

RegistrySpec Password is write-only and never in a plan; rotation converges via PasswordFP.

type RenderContext

type RenderContext struct {
	Inputs    map[string]string
	Databases map[string]ConnView
	Apps      map[string]AppView // app name -> how a sibling addresses it
	Secrets   map[string]string  // secret name -> value
}

RenderContext adds secrets to the marketplace context so GitOps and apply share one interpolation surface.

type Renderer

type Renderer struct {
	// contains filtered or unexported fields
}

Renderer interpolates manifest strings against a RenderContext.

func NewRenderer

func NewRenderer(ctx RenderContext) *Renderer

NewRenderer builds a renderer (nil maps are tolerated).

func (*Renderer) CredentialKeys added in v1.10.25

func (r *Renderer) CredentialKeys() []string

CredentialKeys must be stored encrypted, whatever secretEnv says.

func (*Renderer) RenderEnv

func (r *Renderer) RenderEnv(scope string, env map[string]string) (map[string]string, error)

RenderEnv keeps secrets and database credentials as `${{ secrets.NAME }}` pointers resolved at deploy.

func (*Renderer) RenderEnvLenient

func (r *Renderer) RenderEnvLenient(scope string, env map[string]string) map[string]string

RenderEnvLenient leaves unresolvable values as templates for plan/diff; apply re-renders strictly.

func (*Renderer) RenderFiles added in v1.8.1

func (r *Renderer) RenderFiles(scope string, files map[string]string, delimiters []string) (map[string]string, error)

RenderFiles Delimiters replace the markers for this config only, so files using {{ }} are not mangled.

func (*Renderer) RenderString

func (r *Renderer) RenderString(name, s string) (string, error)

type Resource

type Resource struct {
	APIVersion string `yaml:"apiVersion" json:"apiVersion"`
	Kind       Kind   `yaml:"kind" json:"kind"`
	Metadata   Meta   `yaml:"metadata" json:"metadata"`

	Application   *ApplicationSpec   `yaml:"-" json:"application,omitempty"`
	Stack         *StackSpec         `yaml:"-" json:"stack,omitempty"`
	Database      *DatabaseSpec      `yaml:"-" json:"database,omitempty"`
	Volume        *VolumeSpec        `yaml:"-" json:"volume,omitempty"`
	Route         *RouteSpec         `yaml:"-" json:"route,omitempty"`
	Secret        *SecretSpec        `yaml:"-" json:"secret,omitempty"`
	SealedSecret  *SealedSecretSpec  `yaml:"-" json:"sealedSecret,omitempty"`
	Domain        *DomainSpec        `yaml:"-" json:"domain,omitempty"`
	Registry      *RegistrySpec      `yaml:"-" json:"registry,omitempty"`
	Project       *ProjectSpec       `yaml:"-" json:"project,omitempty"`
	Config        *ConfigSpec        `yaml:"-" json:"config,omitempty"`
	Middleware    *MiddlewareSpec    `yaml:"-" json:"middleware,omitempty"`
	CronJob       *CronJobSpec       `yaml:"-" json:"cronJob,omitempty"`
	Job           *JobSpec           `yaml:"-" json:"job,omitempty"`
	GitSource     *GitSourceSpec     `yaml:"-" json:"gitSource,omitempty"`
	GitRepository *GitRepositorySpec `yaml:"-" json:"gitRepository,omitempty"`
}

Exactly one typed spec pointer is set, determined by Kind.

func (Resource) Key

func (r Resource) Key() string

type ResourceSet

type ResourceSet struct {
	// contains filtered or unexported fields
}

func NewResourceSet

func NewResourceSet() *ResourceSet

NewResourceSet returns an empty set.

func Parse

func Parse(data []byte) (*ResourceSet, error)

Parse rejects unknown spec fields so typos surface instead of being silently dropped.

func ParseFS

func ParseFS(fsys fs.FS, dir string) (*ResourceSet, error)

func (*ResourceSet) Add

func (s *ResourceSet) Add(r Resource)

Add appends r. A later Add with the same Key replaces the earlier entry.

func (*ResourceSet) All

func (s *ResourceSet) All() []Resource

All returns the resources in insertion order.

func (*ResourceSet) ByKind

func (s *ResourceSet) ByKind(k Kind) []Resource

ByKind returns the resources of a given kind, in insertion order.

func (*ResourceSet) Get

func (s *ResourceSet) Get(key string) (Resource, bool)

Get returns the resource for key and whether it exists.

func (*ResourceSet) Has

func (s *ResourceSet) Has(k Kind, name string) bool

Has reports whether a resource of the given kind+name is present.

func (*ResourceSet) Len

func (s *ResourceSet) Len() int

Len reports the number of resources.

func (*ResourceSet) References added in v1.10.12

func (s *ResourceSet) References() []Reference

type ResourceSpec

type ResourceSpec struct {
	Memory string `yaml:"memory,omitempty" json:"memory,omitempty"` // e.g. "512Mi"
	CPU    string `yaml:"cpu,omitempty" json:"cpu,omitempty"`       // e.g. "0.5"
	// GPUKind narrows the request to a vendor/model ("nvidia", "NVIDIA A100-...").
	GPU     int    `yaml:"gpu,omitempty" json:"gpu,omitempty"`
	GPUKind string `yaml:"gpuKind,omitempty" json:"gpuKind,omitempty"`
}

ResourceSpec caps memory/CPU and requests GPUs. Empty/zero means unlimited/none.

func (*ResourceSpec) MemoryBytes

func (rs *ResourceSpec) MemoryBytes() (int64, error)

func (*ResourceSpec) NanoCPUs

func (rs *ResourceSpec) NanoCPUs() (int64, error)

type RouteMaintenanceSpec added in v1.8.3

type RouteMaintenanceSpec struct {
	Enabled bool `yaml:"enabled" json:"enabled"`
	// StatusCode must be 4xx or 5xx: a 2xx parked route reads as healthy to monitors and search engines.
	StatusCode int    `yaml:"statusCode,omitempty" json:"statusCode,omitempty"`
	Message    string `yaml:"message,omitempty" json:"message,omitempty"`
}

RouteMaintenanceSpec unset fields keep the gateway defaults (503 and a short notice).

type RoutePort added in v1.10.26

type RoutePort struct {
	Number int
	Name   string
}

RoutePort also reads the name of a port the target application declares.

func (RoutePort) IsZero added in v1.10.26

func (p RoutePort) IsZero() bool

IsZero lets omitempty drop an unset port.

func (RoutePort) MarshalJSON added in v1.10.26

func (p RoutePort) MarshalJSON() ([]byte, error)

func (RoutePort) MarshalYAML added in v1.10.26

func (p RoutePort) MarshalYAML() (any, error)

func (RoutePort) String added in v1.10.26

func (p RoutePort) String() string

func (*RoutePort) UnmarshalJSON added in v1.10.26

func (p *RoutePort) UnmarshalJSON(b []byte) error

func (*RoutePort) UnmarshalYAML added in v1.10.26

func (p *RoutePort) UnmarshalYAML(n *yaml.Node) error

type RouteSecuritySpec added in v1.8.3

type RouteSecuritySpec struct {
	ExploitProtection bool `yaml:"exploitProtection,omitempty" json:"exploitProtection,omitempty"`
}

type RouteSpec

type RouteSpec struct {
	Hosts []string `yaml:"hosts" json:"hosts"`
	App   string   `yaml:"app" json:"app"` // target application name
	// Port is a container port number, or the name of one of the app's ports.
	Port RoutePort `yaml:"port,omitempty" json:"port,omitzero"`
	Path string    `yaml:"path,omitempty" json:"path,omitempty"`
	// TLS omitted serves HTTPS with a certificate issued by ACME.
	TLS *RouteTLSSpec `yaml:"tls,omitempty" json:"tls,omitempty"`
	// Deprecated: use tls.certificate. Still accepted; setting both is an error.
	DeprecatedCertificate string `yaml:"certificate,omitempty" json:"certificate,omitempty"`
	// Deprecated: use tls.provider. Still accepted; setting both is an error.
	DeprecatedTLSProvider string   `yaml:"tlsProvider,omitempty" json:"tlsProvider,omitempty"`
	Rewrite               string   `yaml:"rewrite,omitempty" json:"rewrite,omitempty"`
	Methods               []string `yaml:"methods,omitempty" json:"methods,omitempty"`
	// AdvancedConfig is raw Goma route YAML that SUPERSEDES the structured fields above.
	AdvancedConfig string `yaml:"advancedConfig,omitempty" json:"advancedConfig,omitempty"`
	// Security carries the gateway's per-route switches.
	Security *RouteSecuritySpec `yaml:"security,omitempty" json:"security,omitempty"`
	// Maintenance omitted means serving, so removing the block resumes traffic.
	Maintenance *RouteMaintenanceSpec `yaml:"maintenance,omitempty" json:"maintenance,omitempty"`
	Middlewares []string              `yaml:"middlewares,omitempty" json:"middlewares,omitempty"`
}

func (*RouteSpec) TLSCertificate added in v1.10.26

func (r *RouteSpec) TLSCertificate() string

TLSCertificate is the imported certificate the route serves, or "".

func (*RouteSpec) TLSMode added in v1.10.26

func (r *RouteSpec) TLSMode() string

TLSMode is acme, custom or off, read from the block or its old string form.

func (*RouteSpec) TLSProvider added in v1.9.3

func (r *RouteSpec) TLSProvider() string

TLSProvider is the gateway certificate provider for an ACME route, or "" for the default.

type RouteTLSSpec added in v1.10.26

type RouteTLSSpec struct {
	// Enabled false serves plain HTTP; omitted means true.
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Provider is the gateway certificate provider that issues the ACME certificate; omitted, the gateway default.
	Provider string `yaml:"provider,omitempty" json:"provider,omitempty"`
	// Certificate serves an imported certificate instead of an ACME one.
	Certificate string `yaml:"certificate,omitempty" json:"certificate,omitempty"`
	// contains filtered or unexported fields
}

RouteTLSSpec also accepts the old string form (tls: acme|custom|off).

func RouteTLSOf added in v1.10.26

func RouteTLSOf(mode, provider, certificate string) *RouteTLSSpec

RouteTLSOf builds the block a stored route exports as, from its acme|custom|off mode.

func (*RouteTLSSpec) UnmarshalYAML added in v1.10.26

func (t *RouteTLSSpec) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML reads the block, or the bare acme|custom|off string the field held before it became one.

type SealedSecretSpec added in v1.10.15

type SealedSecretSpec struct {
	// Value is the output of `miabi secrets seal`: sealed:v1:<keyVersion>:<data>. Never plaintext.
	Value string `yaml:"value" json:"value"`
	// SealedFP is derived state stamped on both sides of the diff, never serialized.
	SealedFP string `yaml:"-" json:"-"`
}

SealedSecretSpec opens only in the workspace and name it was sealed for; compared by fingerprint.

type SecretSpec

type SecretSpec struct {
	Value    string `yaml:"value,omitempty" json:"value,omitempty"`
	Generate bool   `yaml:"generate,omitempty" json:"generate,omitempty"`
	Length   int    `yaml:"length,omitempty" json:"length,omitempty"`
	Symbols  *bool  `yaml:"symbols,omitempty" json:"symbols,omitempty"`
	// Asking for a minimum of symbols implies symbols.
	MinNumbers int `yaml:"minNumbers,omitempty" json:"minNumbers,omitempty"`
	MinSpecial int `yaml:"minSpecial,omitempty" json:"minSpecial,omitempty"`
}

SecretSpec generation options mirror the console generator so both mean the same thing.

func (SecretSpec) WantSymbols added in v1.9.0

func (s SecretSpec) WantSymbols() bool

type SecuritySpec added in v1.9.6

type SecuritySpec struct {
	// RunAsUser empty keeps the image user; restricted workspaces must use a non-root numeric uid or apply refuses.
	RunAsUser string `yaml:"runAsUser,omitempty" json:"runAsUser,omitempty"`
	// ReadOnlyRootFilesystem leaves volumes writable, so paths like /tmp need a volume.
	ReadOnlyRootFilesystem bool `yaml:"readOnlyRootFilesystem,omitempty" json:"readOnlyRootFilesystem,omitempty"`
	// NoNewPrivileges false is refused under the restricted profile rather than silently overridden.
	NoNewPrivileges *bool `yaml:"noNewPrivileges,omitempty" json:"noNewPrivileges,omitempty"`
	// Capabilities adds Linux capabilities beyond Docker's default set and drops any from it.
	Capabilities *CapabilitiesSpec `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
	// Devices are host device nodes exposed to the container, e.g. ["/dev/net/tun"].
	Devices []string `yaml:"devices,omitempty" json:"devices,omitempty"`
	// Deprecated: use capabilities.add. Still accepted; setting both is an error.
	DeprecatedAddCapabilities []string `yaml:"addCapabilities,omitempty" json:"addCapabilities,omitempty"`
}

SecuritySpec omitted fields mean the container default, so removing one converges.

type SourceSpec added in v1.9.3

type SourceSpec struct {
	// Git is the repository URL (https or ssh). Required.
	Git string `yaml:"git" json:"git"`
	// Ref is the branch, tag or commit to build. Empty builds the repository's default branch.
	Ref string `yaml:"ref,omitempty" json:"ref,omitempty"`
	// BuildMethod empty means auto: Dockerfile if present, else buildpacks.
	BuildMethod string `yaml:"buildMethod,omitempty" json:"buildMethod,omitempty"`
	// Builder and Buildpacks apply to the buildpack path only.
	Builder    string   `yaml:"builder,omitempty" json:"builder,omitempty"`
	Buildpacks []string `yaml:"buildpacks,omitempty" json:"buildpacks,omitempty"`
	// BuildEnv is for the build only, not the running container; runtime env belongs in spec.env.
	BuildEnv map[string]string `yaml:"buildEnv,omitempty" json:"buildEnv,omitempty"`
	// Repository names a GitRepository in the bundle or one already in the workspace.
	Repository string `yaml:"repository,omitempty" json:"repository,omitempty"`
}

type StackSpec

type StackSpec struct {
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	// Placement is where the stack is created. Member applications that name no location follow it.
	Placement *PlacementSpec `yaml:"placement,omitempty" json:"placement,omitempty"`
	// Env is shared by every member application, injected on its next deploy; a member's own variable with the same key wins. Values interpolate like application env.
	Env       map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	SecretEnv []string          `yaml:"secretEnv,omitempty" json:"secretEnv,omitempty"` // keys stored encrypted; vault references need none, apply-resolved credentials are added
}

StackSpec groups applications into one logical unit / network.

func (*StackSpec) Location added in v1.10.0

func (s *StackSpec) Location() string

Location is the location the stack names, or "".

type UpdateSpec added in v1.10.0

type UpdateSpec struct {
	Parallelism  int `yaml:"parallelism,omitempty" json:"parallelism,omitempty"`
	DelaySeconds int `yaml:"delaySeconds,omitempty" json:"delaySeconds,omitempty"`
}

UpdateSpec is a service rollout: how many tasks are replaced at once, and the pause between batches.

type VolumeSpec

type VolumeSpec struct {
	Size string `yaml:"size,omitempty" json:"size,omitempty"` // e.g. "5Gi" (0/empty = unbounded)
	// StorageClass is immutable, so apply refuses an edit; omit it to keep the manifest portable across installs.
	StorageClass string `yaml:"storageClass,omitempty" json:"storageClass,omitempty"`
	// Placement is where the volume is created.
	Placement *PlacementSpec `yaml:"placement,omitempty" json:"placement,omitempty"`
}

VolumeSpec declares persistent storage.

func (*VolumeSpec) Location added in v1.10.0

func (v *VolumeSpec) Location() string

Location is the location the volume names, or "".

func (*VolumeSpec) SizeBytes added in v1.10.2

func (v *VolumeSpec) SizeBytes() (int64, error)

SizeBytes parses the declared capacity (e.g. "5Gi") into bytes. Empty or "0" means unbounded.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL