Documentation
¶
Overview ¶
Package declarative is the shared declarative resource model for Miabi: a family of miabi.io/v1 kinds with one parse/validate/render path and one plan/diff engine. Four consumers speak the same kinds — the apply API, GitOps, the Terraform provider, and marketplace templates.
Index ¶
- Constants
- Variables
- func JSONSchema() ([]byte, error)
- func Marshal(set *ResourceSet) ([]byte, error)
- func RandAlphaNum(n int) string
- type Action
- type ApplicationSpec
- type Change
- type ConfigSpec
- type ConnView
- type DatabaseSpec
- type DomainSpec
- type Edge
- type EdgeType
- type FieldDiff
- type Kind
- type Meta
- type MountSpec
- type Plan
- type PlanOptions
- type PortSpec
- type ProjectSpec
- type RegistrySpec
- type RenderContext
- type Renderer
- 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
- type ResourceSpec
- type RouteMaintenanceSpec
- type RouteSecuritySpec
- type RouteSpec
- type SecretSpec
- type StackSpec
- type VolumeSpec
Constants ¶
const ( MaxConfigFileBytes = 256 * 1024 MaxConfigTotalBytes = 512 * 1024 DefaultFileMode = "0644" ReloadRestart = "restart" ReloadNone = "none" )
Config limits and defaults. The per-file cap is what matters against Docker's 500 KB config-object limit, since projection is always per file.
const APIVersion = "miabi.io/v1"
APIVersion is the only accepted apiVersion. It is shared with the marketplace manifest engine so the two families stay in lock-step.
const DefaultRegistryServer = "registry-1.docker.io"
DefaultRegistryServer is the implicit registry host when a manifest names none. It mirrors registry.DefaultServer — duplicated rather than imported so this package stays free of service dependencies, and both sides must agree or a converged registry would diff.
const LabelGitOpsSource = "miabi.io/gitops-source"
LabelGitOpsSource is the Meta.Labels key recording which GitOps project (source id) created an actual resource, so a single project's resources can be listed or torn down without touching another project's.
const LabelManagedBy = "miabi.io/managed-by"
LabelManagedBy is the Meta.Labels key that records which subsystem owns an actual resource. The plan engine uses it to keep prune from ever deleting a resource the apply engine did not create.
const SchemaFileName = "miabi.io-v1.schema.json"
SchemaFileName is the published file name, kept here so the generator, the docs site and the editor extension cannot disagree about it.
const SchemaID = "https://docs.miabi.io/schema/miabi.io-v1.schema.json"
SchemaID is where the generated schema is published. Editors resolve $ref against it, so it must be the URL the file is actually served from.
Variables ¶
var ErrNoResources = errors.New("no declarative resources found")
ErrNoResources reports that a manifest source parsed with zero resources: the path exists but holds no miabi.io/v1 documents. Callers distinguish it from a missing path (fs.ErrNotExist) to decide whether an empty result is an intentional teardown or an error.
Functions ¶
func JSONSchema ¶ added in v1.8.2
func Marshal ¶
func Marshal(set *ResourceSet) ([]byte, error)
Marshal serializes a resource set into a single multi-document YAML bundle that Parse round-trips. Project resources are organizational and omitted — their children are already first-class members of the set.
func RandAlphaNum ¶
RandAlphaNum returns a cryptographically-random alphanumeric string of length n (used to satisfy secrets with generate: true).
Types ¶
type ApplicationSpec ¶
type ApplicationSpec struct {
Image string `yaml:"image" json:"image"`
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"`
Mounts []MountSpec `yaml:"mounts,omitempty" json:"mounts,omitempty"`
Resources *ResourceSpec `yaml:"resources,omitempty" json:"resources,omitempty"`
// RunAsUser pins the container to an account — "1000", "1000:1000", "node", "node:node" — like
// `docker run --user`. Empty keeps the image's own user. A workspace under the restricted security
// profile must give a non-root numeric uid; anything else is refused on apply, not silently
// dropped, since the manifest is the source of truth for what should be running.
RunAsUser string `yaml:"runAsUser,omitempty" json:"runAsUser,omitempty"`
// ContainerLabels are user-defined Docker labels stamped on the app's container(s), for
// label-driven tools like Traefik. Reserved keys (io.miabi.*, com.docker.*) are stripped on apply
// — a manifest is machine-authored, so import is fail-soft rather than erroring.
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 names the Registry credential used to pull this image; empty means an anonymous public
// pull. It need not be declared in the same bundle: a name not in the manifest resolves against
// the workspace's existing credentials, so a token created once in the UI can be reused.
Registry string `yaml:"registry,omitempty" json:"registry,omitempty"`
// ExternalLabel pins the subdomain used for external access (`<label>.<base-domain>`). When unset
// Miabi generates a stable label. The label is platform-wide unique: if already claimed it is
// ignored and a generated one is used, so a copy-pasted manifest never fails on a clash.
ExternalLabel string `yaml:"externalLabel,omitempty" json:"externalLabel,omitempty"`
// ReloadPolicy decides what a mounted config's content change does: "restart"
// (default) redeploys the app, "none" leaves it running for apps that watch
// their own config file.
ReloadPolicy string `yaml:"reloadPolicy,omitempty" json:"reloadPolicy,omitempty"`
// ConfigFP fingerprints every mounted config's digest, filled by the apply engine
// on both sides of the diff so a content change converges as an app update.
// Not serialized: derived state, like RegistrySpec.PasswordFP.
ConfigFP string `yaml:"-" json:"-"`
}
ApplicationSpec is a long-running container workload. CI writes the immutable Digest; GitOps converges runtime to it.
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 maps a file key (a relative filename, "/" permitted for subdirectories)
// to its content.
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 overrides the interpolation delimiters for every value, so a file
// whose own syntax uses {{ }} is not mangled. Exactly two distinct entries.
Delimiters []string `yaml:"delimiters,omitempty" json:"delimiters,omitempty"`
// DigestFP fingerprints the rendered data, filled by the apply engine on both
// sides of the diff. Not serialized: derived state, like RegistrySpec.PasswordFP.
DigestFP string `yaml:"-" json:"-"`
}
ConfigSpec is a set of named files projected into containers at mount time. Values are interpolated exactly like application env, so a config can carry a rendered database password without a bootstrap script.
type ConnView ¶
ConnView is a resolved database's connection detail, exposed to env interpolation as {{ .databases.<name>.* }}.
type DatabaseSpec ¶
type DatabaseSpec struct {
Engine string `yaml:"engine" json:"engine"` // postgres|mysql|mariadb|redis
Version string `yaml:"version,omitempty" json:"version,omitempty"` // e.g. "16-alpine"
Placement string `yaml:"placement,omitempty" json:"placement,omitempty"`
}
DatabaseSpec requests a logical database on a DatabaseInstance.
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 declares an owned hostname/zone; the hostname is the resource's metadata.name (a real FQDN). tls is the default certificate policy routes under it inherit, and wildcard covers *.name too. Ownership verification is a runtime action.
type Edge ¶
Edge is a directed dependency from one resource to another, keyed by Resource Key() ("<Kind>/<name>"). From depends on / targets To.
func Edges ¶
func Edges(set *ResourceSet) []Edge
Edges derives the cross-resource dependency edges within a set. It must run on the parsed (un-rendered) set, where env still carries the "{{ .databases.X }}" templates that reveal soft references. Only edges whose target is in the set are emitted; the result is deduplicated.
type EdgeType ¶
type EdgeType string
EdgeType classifies a dependency between two resources, so a topology view can label and style the link.
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) )
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 Kind ¶
type Kind string
Kind enumerates the declarative resource kinds. They map 1:1 to the resources the platform manages and the Terraform provider exposes.
const ( KindApplication Kind = "Application" KindStack Kind = "Stack" KindDatabase Kind = "Database" KindVolume Kind = "Volume" // KindRoute is an HTTP routing rule (host/path -> app:port + TLS), distinct from KindDomain: a // Route exposes an app on a hostname, while a Domain is the owned hostname/zone tracking DNS // ownership and the default TLS policy routes under it inherit. KindRoute Kind = "Route" KindSecret Kind = "Secret" // KindDomain is an owned hostname (or zone) a workspace controls: its default // TLS policy and (optional) wildcard coverage. DNS-ownership verification is a // runtime action, not a declarable field. KindDomain Kind = "Domain" // KindRegistry is a container-registry credential used to pull private images. // It is deliberately not called a "secret": Miabi's Secret kind is the vault, // and an Application references this one by name through spec.registry. KindRegistry Kind = "Registry" // KindProject bundles a set of resources living in one repo/namespace. KindProject Kind = "Project" // KindConfig is a set of named configuration files projected into containers as // read-only files. Secret carries one opaque value consumed as env; Config // carries named text payloads consumed as files. Both are encrypted at rest. KindConfig Kind = "Config" )
type Meta ¶
type Meta struct {
Name string `yaml:"name" json:"name"`
// UID is the resource's portable identifier (its Miabi uid). Written on
// export so a restore into another install — or a rename in a manifest — keeps
// identity. Optional in hand-authored manifests; matched ahead of name when set.
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"`
}
Meta is the identity block shared by every kind. Labels are short and identifying (for selection and grouping); Annotations hold descriptive data the engine stores but never queries. Custom metadata belongs in one of these maps, never as ad-hoc top-level keys.
type MountSpec ¶
type MountSpec struct {
Volume string `yaml:"volume,omitempty" json:"volume,omitempty"`
Config string `yaml:"config,omitempty" json:"config,omitempty"`
// Key selects one file from the config, making Path that file's exact location.
// Empty projects every key under Path as a directory prefix.
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 Plan ¶
type Plan struct {
Changes []Change `json:"changes"`
}
Plan is an ordered set of changes that converges actual state to desired. Creates/updates run in dependency order (volumes/dbs before apps before domains); deletes run in reverse.
func BuildPlan ¶
func BuildPlan(desired, actual *ResourceSet, opts PlanOptions) *Plan
BuildPlan diffs desired against actual and returns an ordered convergence plan. actual should contain only Miabi-managed resources when Prune is set, so unmanaged resources are never deleted.
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, when non-empty, restricts prune to actual resources whose
// LabelManagedBy label equals it — so a GitOps prune never deletes a
// hand-created or otherwise-owned resource. Empty prunes any orphan.
PruneManagedBy string
// PruneGitOpsSource, when non-empty, restricts prune to actual resources whose LabelGitOpsSource
// equals it, so one project's reconcile never prunes another's. Empty leaves prune unscoped.
// Resources with no source label are never matched, so a scoped prune never deletes them.
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 {
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 publishes this port on `<externalLabel>.<base-domain>` over
// HTTPS via the reverse proxy (the base domain must be configured platform-wide).
ExternalAccess bool `yaml:"externalAccess,omitempty" json:"externalAccess,omitempty"`
// Publish binds this container port to a host port on the node (raw TCP/UDP).
// HostPort requests a specific host port; 0 auto-allocates from the pool.
Publish bool `yaml:"publish,omitempty" json:"publish,omitempty"`
HostPort int `yaml:"hostPort,omitempty" json:"hostPort,omitempty"`
}
PortSpec is a container port and how it is reached. The two exposure knobs are orthogonal: externalAccess gives it a public HTTPS URL through the reverse proxy, while publish/hostPort binds it to a raw port on the node, like `docker -p`.
type ProjectSpec ¶
type ProjectSpec struct {
Description string `yaml:"description,omitempty" json:"description,omitempty"`
Resources []Resource `yaml:"-" json:"resources,omitempty"`
}
ProjectSpec bundles a set of resources authored in one place. Child resources may be inlined; the parser flattens them into the document set.
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 the fingerprint of the *rendered* password, filled in by the apply engine on both
// sides of the diff. Deliberately not serialized: it is derived state, so a Marshal->Parse round
// trip (how GitOps canonicalizes a bundle) simply recomputes it.
PasswordFP string `yaml:"-" json:"-"`
}
RegistrySpec is a container-registry credential; an Application selects one via spec.registry. Password is write-only and never appears in a plan — prefer a vault reference over an inline literal. A rotation still converges via an unreadable fingerprint (see PasswordFP).
type RenderContext ¶
type RenderContext struct {
Inputs map[string]string
Databases map[string]ConnView
Apps map[string]string // app name -> network alias
Secrets map[string]string // secret name -> value
}
RenderContext is the read-only data env interpolation resolves against. It mirrors the marketplace renderer's context but adds secrets, 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) RenderEnvLenient ¶
RenderEnvLenient interpolates every value best-effort: a value whose references cannot resolve yet is left as its original template instead of failing. Used for plan/diff, where a not-yet-created dependency must not abort the plan; 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 interpolates a config's files. Delimiters, when set, replaces the interpolation markers for this config only, so a file whose own syntax uses {{ }} is not mangled. Strict: an unresolvable reference fails the render rather than storing a broken file.
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"`
Domain *DomainSpec `yaml:"-" json:"domain,omitempty"`
Registry *RegistrySpec `yaml:"-" json:"registry,omitempty"`
Project *ProjectSpec `yaml:"-" json:"project,omitempty"`
Config *ConfigSpec `yaml:"-" json:"config,omitempty"`
}
Resource is one parsed declarative object. Exactly one of the typed spec pointers is set, determined by Kind.
type ResourceSet ¶
type ResourceSet struct {
// contains filtered or unexported fields
}
ResourceSet is an ordered, key-indexed collection of resources. It is the shape both desired state (parsed manifests) and actual state (a workspace snapshot) take so the plan engine can diff them generically.
func Parse ¶
func Parse(data []byte) (*ResourceSet, error)
Parse decodes a single- or multi-document YAML stream into a normalized, validated set of resources. Unknown spec fields are rejected so typos surface rather than being silently dropped. A Project's inline resources are flattened into the set.
func ParseFS ¶
func ParseFS(fsys fs.FS, dir string) (*ResourceSet, error)
ParseFS walks an fs.FS rooted at dir, parsing every .yaml/.yml file in lexical order into one combined set. It is the entry point GitOps uses over a cloned repo's manifest path.
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.
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"
// GPU is the number of whole GPU units the app requests (0 = none). 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)
MemoryBytes parses the memory cap (e.g. "512Mi", "1Gi") into bytes. Empty or "0" means unlimited (0).
func (*ResourceSpec) NanoCPUs ¶
func (rs *ResourceSpec) NanoCPUs() (int64, error)
NanoCPUs parses the CPU cap (a core fraction, e.g. "0.5", "2") into nano-CPUs (1 core = 1e9). Empty or "0" means unlimited (0).
type RouteMaintenanceSpec ¶ added in v1.8.3
type RouteMaintenanceSpec struct {
Enabled bool `yaml:"enabled" json:"enabled"`
// StatusCode must be 4xx or 5xx: a parked route answering 2xx reads as
// healthy to uptime monitors and search engines.
StatusCode int `yaml:"statusCode,omitempty" json:"statusCode,omitempty"`
Message string `yaml:"message,omitempty" json:"message,omitempty"`
}
RouteMaintenanceSpec is the response a parked route answers with. An unset statusCode or message leaves the gateway's defaults (503 and a short notice).
type RouteSecuritySpec ¶ added in v1.8.3
type RouteSecuritySpec struct {
// ExploitProtection has the gateway reject requests carrying common injection
// and traversal signatures before the backend sees them.
ExploitProtection bool `yaml:"exploitProtection,omitempty" json:"exploitProtection,omitempty"`
}
RouteSecuritySpec holds a route's gateway security switches, mirroring Goma's own security block so the manifest reads like the gateway config it produces.
type RouteSpec ¶
type RouteSpec struct {
Hosts []string `yaml:"hosts" json:"hosts"`
App string `yaml:"app" json:"app"` // target application name
Port int `yaml:"port,omitempty" json:"port,omitempty"`
Path string `yaml:"path,omitempty" json:"path,omitempty"`
TLS string `yaml:"tls,omitempty" json:"tls,omitempty"` // acme|custom|off (default acme)
// Security carries the gateway's per-route switches.
Security *RouteSecuritySpec `yaml:"security,omitempty" json:"security,omitempty"`
// Maintenance parks the route at the gateway. Omitting it means "serving",
// so removing the block from a manifest resumes traffic.
Maintenance *RouteMaintenanceSpec `yaml:"maintenance,omitempty" json:"maintenance,omitempty"`
}
RouteSpec binds one or more hostnames (and an optional path) to an application's port with a TLS mode — an HTTP routing rule. List every hostname the route should answer on, e.g. both example.com and www.example.com.
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"`
}
SecretSpec is a write-only secret value. Value is never read back; the diff engine treats secrets as opaque (presence/absence only).
type StackSpec ¶
type StackSpec struct {
Description string `yaml:"description,omitempty" json:"description,omitempty"`
}
StackSpec groups applications into one logical unit / network.
type VolumeSpec ¶
type VolumeSpec struct {
Size string `yaml:"size,omitempty" json:"size,omitempty"` // e.g. "5Gi" (0/empty = unbounded)
}
VolumeSpec declares persistent storage.