apply

package
v1.10.21 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 32 Imported by: 0

Documentation

Overview

Package apply is the imperative, one-shot sibling of GitOps: it turns a bundle of miabi.io/v1 manifests into a plan or converges the workspace to them, by diffing desired state against a live snapshot and driving the existing services. GitOps reuses this engine, so both share one code path.

Index

Constants

View Source
const ManagedByApply = models.ManagedByApply

ManagedByApply marks resources the declarative engine created from a one-shot apply (CLI or API). Each run prunes only its own owner's resources, so a CLI prune never deletes a GitOps project's.

View Source
const ManagedByGitOps = models.ManagedByGitOps

ManagedByGitOps marks resources the declarative engine reconciles for a GitOps project.

View Source
const MetaDigest = models.MetaDigest

MetaDigest records the image digest a manifest pins an application to. Deploys pull image@digest while it is set, and the live snapshot reports the digest the active release runs, so a pin whose deploy failed shows as drift.

Variables

View Source
var (
	// ErrInvalidManifest signals a parse/validation failure (HTTP 400).
	ErrInvalidManifest = errors.New("invalid manifest")
	// ErrOwnedByGitOps refuses a one-shot apply that would change a GitOps project's resource (HTTP 409).
	ErrOwnedByGitOps = errors.New("owned by a GitOps project")
	// ErrPlainSecret refuses a Secret with a plaintext value where only sealed values are allowed.
	ErrPlainSecret = errors.New("this source only accepts sealed secrets, but these Secrets carry a plaintext value")
	// ErrUnsupportedKind is returned when a plan needs a mutation the v1 executor
	// does not perform. The plan still lists the change.
	ErrUnsupportedKind = errors.New("kind not yet supported by apply")
	// ErrResourceNotFound is returned by ApplyResource when the named resource is
	// not present in the desired manifest bundle (HTTP 404).
	ErrResourceNotFound = errors.New("resource not found in manifests")
)
View Source
var ErrNotExportable = errors.New("this application cannot be exported as a manifest")

snapshot builds the live ResourceSet for the workspace across every kind the executor manages. Each resource is labeled with its owner so prune stays safe. ErrNotExportable is returned for an application a manifest cannot faithfully describe.

Functions

This section is empty.

Types

type ClusterCap added in v1.9.3

type ClusterCap interface {
	IsSwarm(clusterID uint) bool
	ClusterOfServer(serverID uint) uint
	LocationLabel(clusterID uint) string
}

ClusterCap describes the clusters workloads run in, which decides whether a reference between two of them can resolve.

type Failure

type Failure struct {
	Kind   string `json:"kind"`
	Name   string `json:"name"`
	Action string `json:"action"`
	Error  string `json:"error"`
}

Failure records one change that could not be applied.

type GitSourceInput added in v1.10.20

type GitSourceInput struct {
	Name, Repo, Repository, Ref, Path, SyncPolicy, DeletePolicy string
	Prune, SelfHeal, AllowEmpty, RequireSealedSecrets           bool
	Metadata, Annotations                                       models.Metadata
}

GitSourceInput is a declared GitSource as the gitops service stores it.

type GitSources added in v1.10.20

type GitSources interface {
	List(workspaceID uint) ([]models.GitSource, error)
	RepositoryNames(workspaceID uint) (map[uint]string, error)
	// Declare creates the source when id is 0, else updates it.
	Declare(workspaceID, id uint, in GitSourceInput) (*models.GitSource, error)
	// Remove deletes a source, tearing its resources down only when its delete policy is cascade.
	Remove(ctx context.Context, workspaceID, id uint) error
}

GitSources converges kind: GitSource. Satisfied by the gitops service, which itself drives this package, hence the interface.

type NodeStatus

type NodeStatus string

NodeStatus is a resource's sync state relative to the desired manifests, derived from the convergence plan.

const (
	NodeSynced    NodeStatus = "synced"      // live state matches desired (noop)
	NodeOutOfSync NodeStatus = "out_of_sync" // exists but drifted (update)
	NodeMissing   NodeStatus = "missing"     // declared but not yet created (create)
	NodeOrphaned  NodeStatus = "orphaned"    // live + GitOps-owned but absent from desired (delete)
)

type Options

type Options struct {
	Prune bool
	// OwnerSource, when set, is the GitOps project id that owns this apply. Every
	// resource created/updated in the run is labeled with it (miabi.io/gitops-source)
	// so the project's resources can later be listed or torn down on their own.
	OwnerSource string
	// Admin marks an apply run by a platform admin, who may create in restricted locations. GitOps never
	// sets it: a sync acts on nobody's behalf.
	Admin bool
	// CheckReferences fails the plan on a {{ … }} reference to something that exists neither in the
	// bundle nor in the workspace. For previews: a real apply still converges everything else and
	// records the app that cannot render as a failure.
	CheckReferences bool
	// RequireSealedSecrets refuses the bundle when a Secret carries a plaintext value.
	RequireSealedSecrets bool
	// Force lets a one-shot apply change resources a GitOps project owns. They stay the project's,
	// so its next sync reverts the change.
	Force bool
}

Options tunes a plan/apply.

type Placer added in v1.10.0

type Placer interface {
	Place(req placement.Request) (placement.Result, error)
	LocationName(clusterID uint) string
	ResolveLocation(workspaceID uint, location string, admin bool) (*models.Cluster, error)
}

Placer resolves where a created resource lands. Satisfied by the placement service.

type Result

type Result struct {
	Plan        *declarative.Plan `json:"plan"`
	Applied     int               `json:"applied"`
	DryRun      bool              `json:"dry_run"`
	Failures    []Failure         `json:"failures,omitempty"`
	WorkspaceID uint              `json:"workspace_id"`
	// FailedJobs names the declared Jobs of the run's source whose last run
	// failed or was skipped; a sync that converged is still degraded by them.
	FailedJobs []string `json:"failed_jobs,omitempty"`
}

Result is the outcome of an apply run.

type Service

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

Service computes and executes declarative plans for a workspace.

func NewService

func NewService(apps *application.Service, storage *storage.Service, dbs *database.Service, stacks *stack.Service, secrets *secret.Service, routes *route.Service, domains *domain.Service, registries *registry.Service) *Service

NewService wires the apply engine over the existing resource services.

func (*Service) Apply

func (s *Service) Apply(ctx context.Context, workspaceID uint, manifests []byte, opts Options) (*Result, error)

Apply computes the plan and executes it. A change that fails is recorded in Result.Failures; the run continues so independent resources still converge.

func (*Service) ApplyResource added in v1.6.5

func (s *Service) ApplyResource(ctx context.Context, workspaceID uint, manifests []byte, opts Options, kind, name string) (*Result, error)

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, workspaceID uint, manifests []byte, dryRun bool) (*Result, error)

Delete removes exactly the resources a manifest bundle names — the inverse of Apply. It matches each entry by kind+name and deletes in dependency-safe order, skipping entries that don't exist. Unlike a pruning Apply it deletes regardless of which subsystem owns it, since the caller named it explicitly.

func (*Service) DeleteResource added in v1.6.5

func (s *Service) DeleteResource(ctx context.Context, workspaceID uint, kind, name string) (*Result, error)

func (*Service) ExportApplication added in v1.9.3

func (s *Service) ExportApplication(ctx context.Context, workspaceID uint, name string, includeJobs bool) ([]byte, error)

ExportApplication renders one application, and the volumes it mounts, as a miabi.io/v1 bundle — the starting point for moving an app that was created in the console into Git.

It reuses the snapshot the plan engine already builds, rather than projecting the app a second time: an export that drifted from what apply reads back would hand someone a manifest that plans changes the moment they applied it.

Only the volumes this app mounts are included. A workspace's other resources are not this app's to describe, and a bundle that carried them would prune them if applied elsewhere with --prune.

func (*Service) LiveStatus

func (s *Service) LiveStatus(workspaceID uint) map[string]string

LiveStatus returns the current runtime status of the workspace's stateful resources, keyed by topology node key ("<Kind>/<slug>"). It is cheap — no git clone, no container inspection — so the detail page can poll it to keep node health live between full topology loads.

func (*Service) LiveTopology

func (s *Service) LiveTopology(ctx context.Context, workspaceID uint, syncError string) (*Topology, error)

LiveTopology builds the graph from live state only, as a graceful fallback when the desired manifests cannot be loaded. It shows the GitOps-owned resources still running and surfaces syncError, so the view explains why it is degraded. Edges come from live specs, so env-template links do not survive.

func (*Service) Plan

func (s *Service) Plan(ctx context.Context, workspaceID uint, manifests []byte, opts Options) (*declarative.Plan, *declarative.ResourceSet, error)

Plan parses the manifests and diffs them against live state, returning the convergence plan without mutating anything.

func (*Service) SetCertificates added in v1.9.3

func (s *Service) SetCertificates(c *certificatesvc.Service)

SetCertificates wires the certificate service, so a Route may name the stored certificate it serves with tls: custom.

func (*Service) SetCluster added in v1.9.3

func (s *Service) SetCluster(c ClusterCap)

SetCluster wires cluster detection, used to decide whether a reference across two nodes or two locations can resolve.

func (*Service) SetConfigs added in v1.8.1

func (s *Service) SetConfigs(c *configsvc.Service)

SetConfigs wires the config service (kind: Config).

func (*Service) SetGitRepositories added in v1.10.20

func (s *Service) SetGitRepositories(g *gitrepo.Service)

SetGitRepositories wires kind: GitRepository.

func (*Service) SetGitSources added in v1.10.20

func (s *Service) SetGitSources(g GitSources)

SetGitSources wires kind: GitSource.

func (*Service) SetJobs added in v1.10.13

func (s *Service) SetJobs(j *job.Service)

SetJobs wires the job service (kinds CronJob and Job). Nil leaves a manifest declaring either failing with ErrUnsupportedKind.

func (*Service) SetMiddlewares added in v1.9.3

func (s *Service) SetMiddlewares(m *middlewaresvc.Service)

SetMiddlewares wires the gateway-middleware service (kind: Middleware).

func (*Service) SetPlacer added in v1.10.0

func (s *Service) SetPlacer(p Placer)

SetPlacer wires spec.location. Without it every resource is created on the local node.

func (*Service) SetPortExposure

func (s *Service) SetPortExposure(bindings *portbinding.Service)

SetPortExposure wires the reconcilers for an Application's per-port exposure: externalAccess (reverse-proxy URLs) and publish/hostPort (host-port bindings). Nil-safe: when unset, those manifest fields are ignored.

func (*Service) SetUnsealer added in v1.10.15

func (s *Service) SetUnsealer(u Unsealer)

SetUnsealer wires kind: SealedSecret.

func (*Service) Teardown

func (s *Service) Teardown(ctx context.Context, workspaceID uint, sourceID string) (*Result, error)

Teardown deletes every resource owned by a single GitOps source — those tagged with its gitops-source label — in dependency-safe order. Used for a cascade project delete, so one project's resources go without touching another's. Resources predating per-source labeling are left untouched.

func (*Service) Topology

func (s *Service) Topology(ctx context.Context, workspaceID uint, manifests []byte, opts Options) (*Topology, error)

Topology parses the manifests, diffs them against live state, and returns the resource graph for the project-detail view: every declared resource as a node with its sync status, plus the dependency edges. Orphaned GitOps-owned resources are included, so the graph shows prune candidates too.

type Topology

type Topology struct {
	Nodes  []TopologyNode     `json:"nodes"`
	Edges  []declarative.Edge `json:"edges"`
	Counts map[NodeStatus]int `json:"counts"`
	// Error, when set, means the desired manifests could not be loaded or parsed. Nodes and Edges then
	// reflect the last-known live state instead of the desired graph, so the view degrades to "what is
	// still running, plus why the latest sync failed" rather than going blank.
	Error string `json:"error,omitempty"`
	// Live is true when Nodes/Edges came from the live fallback rather than the
	// desired manifests, so the UI can label statuses as last-known rather than
	// authoritative.
	Live bool `json:"live,omitempty"`
}

Topology is the resource graph of a manifest bundle: the nodes (resources) and the directed edges (dependencies) between them, plus a per-status tally.

type TopologyNode

type TopologyNode struct {
	Key    string     `json:"key"`  // "<Kind>/<name>" — stable node id, matches edge endpoints
	Kind   string     `json:"kind"` // Application, Database, Volume, Route, Stack, Secret, Domain
	Name   string     `json:"name"`
	Status NodeStatus `json:"status"`
	// LiveID/Slug point at the live resource so the UI can deep-link to its detail
	// page. LiveID is 0 when the resource is not yet created (missing).
	LiveID uint   `json:"live_id,omitempty"`
	Slug   string `json:"slug,omitempty"`
	// Health is a kind-specific runtime status (e.g. an application's "running"),
	// empty when the kind has no meaningful runtime state or is not live yet.
	Health string `json:"health,omitempty"`
	// URL is the public address a resource is reachable at, when it has one (a
	// Route's host/path with its scheme). Empty for kinds with no public URL.
	URL string `json:"url,omitempty"`
}

TopologyNode is one resource in the project graph: its declarative identity, sync status, a link to the live resource (when it exists), and an optional runtime health string.

type Unsealer added in v1.10.15

type Unsealer interface {
	Unseal(workspaceID uint, name, value string) (plain string, keyVersion int, err error)
}

Unsealer opens sealed secret values with the workspace's sealing keys. Satisfied by the sealing service.

Jump to

Keyboard shortcuts

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