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
- Variables
- type ClusterCap
- type Failure
- type GitSourceInput
- type GitSources
- type NodeStatus
- type Options
- type Placer
- type Result
- type Service
- func (s *Service) Apply(ctx context.Context, workspaceID uint, manifests []byte, opts Options) (*Result, error)
- func (s *Service) ApplyResource(ctx context.Context, workspaceID uint, manifests []byte, opts Options, ...) (*Result, error)
- func (s *Service) Delete(ctx context.Context, workspaceID uint, manifests []byte, dryRun bool) (*Result, error)
- func (s *Service) DeleteResource(ctx context.Context, workspaceID uint, kind, name string) (*Result, error)
- func (s *Service) ExportApplication(ctx context.Context, workspaceID uint, name string, includeJobs bool) ([]byte, error)
- func (s *Service) LiveStatus(workspaceID uint) map[string]string
- func (s *Service) LiveTopology(ctx context.Context, workspaceID uint, syncError string) (*Topology, error)
- func (s *Service) Plan(ctx context.Context, workspaceID uint, manifests []byte, opts Options) (*declarative.Plan, *declarative.ResourceSet, error)
- func (s *Service) SetCertificates(c *certificatesvc.Service)
- func (s *Service) SetCluster(c ClusterCap)
- func (s *Service) SetConfigs(c *configsvc.Service)
- func (s *Service) SetGitRepositories(g *gitrepo.Service)
- func (s *Service) SetGitSources(g GitSources)
- func (s *Service) SetJobs(j *job.Service)
- func (s *Service) SetMiddlewares(m *middlewaresvc.Service)
- func (s *Service) SetPlacer(p Placer)
- func (s *Service) SetPortExposure(bindings *portbinding.Service)
- func (s *Service) SetUnsealer(u Unsealer)
- func (s *Service) Teardown(ctx context.Context, workspaceID uint, sourceID string) (*Result, error)
- func (s *Service) Topology(ctx context.Context, workspaceID uint, manifests []byte, opts Options) (*Topology, error)
- type Topology
- type TopologyNode
- type Unsealer
Constants ¶
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.
const ManagedByGitOps = models.ManagedByGitOps
ManagedByGitOps marks resources the declarative engine reconciles for a GitOps project.
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 ¶
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") )
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 (*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 (*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 ¶
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
SetConfigs wires the config service (kind: Config).
func (*Service) SetGitRepositories ¶ added in v1.10.20
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
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
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
SetUnsealer wires kind: SealedSecret.
func (*Service) Teardown ¶
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.