Documentation
¶
Overview ¶
Package declarative is the miabi.io/v1 resource model shared by apply, GitOps, Terraform and marketplace templates.
Index ¶
- Constants
- Variables
- func CheckReferences(refs []Reference, known KnownNames) error
- func GenerateSecret(spec SecretSpec) string
- func IsVaultSecret(k Kind) bool
- func JSONSchema() ([]byte, error)
- func Marshal(set *ResourceSet) ([]byte, error)
- func NormalizeGitURL(raw string) string
- func PlainSecrets(set *ResourceSet) []string
- func RandAlphaNum(n int) string
- func ValidPortName(name string) bool
- type Action
- type AppView
- type ApplicationPlacementSpec
- type ApplicationSpec
- func (a *ApplicationSpec) AddCapabilities() []string
- func (a *ApplicationSpec) Constraints() []string
- func (a *ApplicationSpec) Devices() []string
- func (a *ApplicationSpec) DropCapabilities() []string
- func (a *ApplicationSpec) Location() string
- func (a *ApplicationSpec) NoNewPrivileges() bool
- func (a *ApplicationSpec) ReadOnlyRootFilesystem() bool
- func (a *ApplicationSpec) Replicas() int
- func (a *ApplicationSpec) RunAsUser() string
- func (a *ApplicationSpec) Runtime() string
- func (a *ApplicationSpec) Strategy() string
- func (a *ApplicationSpec) Update() *UpdateSpec
- type CapabilitiesSpec
- type Change
- type ConfigSpec
- type ConnView
- type CronJobSpec
- type DatabasePlacementSpec
- type DatabaseResourcesSpec
- type DatabaseSpec
- type DeploymentSpec
- type DomainSpec
- type Edge
- type EdgeType
- type FieldDiff
- type GitRepositorySpec
- type GitSourceSpec
- type HealthcheckSpec
- type JobSpec
- type Kind
- type KnownNames
- type Meta
- type MiddlewareSpec
- type MountSpec
- type PlacementSpec
- type Plan
- type PlanOptions
- type PortSpec
- type ProjectSpec
- type Reference
- type RegistrySpec
- type RenderContext
- type Renderer
- func (r *Renderer) CredentialKeys() []string
- func (r *Renderer) RenderEnv(scope string, env map[string]string) (map[string]string, error)
- func (r *Renderer) RenderEnvLenient(scope string, env map[string]string) map[string]string
- func (r *Renderer) RenderFiles(scope string, files map[string]string, delimiters []string) (map[string]string, error)
- func (r *Renderer) RenderString(name, s string) (string, error)
- type Resource
- type ResourceSet
- func (s *ResourceSet) Add(r Resource)
- func (s *ResourceSet) All() []Resource
- func (s *ResourceSet) ByKind(k Kind) []Resource
- func (s *ResourceSet) Get(key string) (Resource, bool)
- func (s *ResourceSet) Has(k Kind, name string) bool
- func (s *ResourceSet) Len() int
- func (s *ResourceSet) References() []Reference
- type ResourceSpec
- type RouteMaintenanceSpec
- type RoutePort
- type RouteSecuritySpec
- type RouteSpec
- type RouteTLSSpec
- type SealedSecretSpec
- type SecretSpec
- type SecuritySpec
- type SourceSpec
- type StackSpec
- type UpdateSpec
- type VolumeSpec
Constants ¶
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.
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.
const ( DeletePolicyOrphan = "orphan" DeletePolicyCascade = "cascade" )
GitSource delete policies.
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.
const APIVersion = "miabi.io/v1"
APIVersion is shared with the marketplace manifest engine so the two stay in lock-step.
const AnnotationSkipInitialRun = "miabi.io/skip-initial-run"
AnnotationSkipInitialRun adopts a job that has already run elsewhere without running it again.
const DefaultRegistryServer = "registry-1.docker.io"
DefaultRegistryServer duplicates registry.DefaultServer to avoid service deps; they must agree or registries diff.
const DefaultSecretLength = 32
const JobSpecField = "spec"
JobSpecField is the diff field a changed Job run template shows up as.
const LabelGitOpsSource = "miabi.io/gitops-source"
LabelGitOpsSource lets one GitOps project's resources be torn down without touching another's.
const LabelManagedBy = "miabi.io/managed-by"
LabelManagedBy keeps prune from ever deleting a resource the apply engine did not create.
const SchemaFileName = "miabi.io-v1.schema.json"
SchemaFileName is shared so the generator, docs site and editor extension cannot disagree.
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 ¶
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
IsVaultSecret: Secret and SealedSecret share one name space, so a name is either, never both.
func JSONSchema ¶ added in v1.8.2
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
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 ValidPortName ¶ added in v1.10.26
ValidPortName refuses a digit-only name, which a Route would read as a port number.
Types ¶
type AppView ¶ added in v1.9.3
Host is the app's own name, aliased on every workspace network; Alias predates it and Config files use it.
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 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 ¶
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
Fingerprint covers what a run executes; policy, history and app are excluded.
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 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) HasChanges ¶
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 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.
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
CredentialKeys must be stored encrypted, whatever secretEnv says.
func (*Renderer) RenderEnv ¶
RenderEnv keeps secrets and database credentials as `${{ secrets.NAME }}` pointers resolved at deploy.
func (*Renderer) RenderEnvLenient ¶
RenderEnvLenient leaves unresolvable values as templates for plan/diff; apply re-renders strictly.
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.
type ResourceSet ¶
type ResourceSet struct {
// contains filtered or unexported fields
}
func Parse ¶
func Parse(data []byte) (*ResourceSet, error)
Parse rejects unknown spec fields so typos surface instead of being silently dropped.
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) 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
RoutePort also reads the name of a port the target application declares.
func (RoutePort) MarshalJSON ¶ added in v1.10.26
func (RoutePort) MarshalYAML ¶ added in v1.10.26
func (*RoutePort) UnmarshalJSON ¶ added in v1.10.26
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
TLSCertificate is the imported certificate the route serves, or "".
func (*RouteSpec) TLSMode ¶ added in v1.10.26
TLSMode is acme, custom or off, read from the block or its old string form.
func (*RouteSpec) TLSProvider ¶ added in v1.9.3
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.
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.