Documentation
¶
Overview ¶
Package provider defines the Provider interface that every backend implements, the registry that maps kinds to providers, decode helpers, and rollout strategies.
Index ¶
Constants ¶
const ( LabelManaged = "io.craneops.managed" LabelOwner = "io.craneops.owner" LabelSpecHash = "io.craneops.spec-hash" // DetailPendingRewrite, in Observed.Details, says the live object was written by // an older version of the provider's output, so its next write will also apply // those changes (for a swarm service: a restart). The engine surfaces it as the // PendingRewrite condition. DetailPendingRewrite = "pendingRewrite" // DetailTaskFailures (int) counts a Service's task failures inside the // recent window; DetailTaskLastError (string) is the newest failure's // message. Present only when the service looks like it is crash-looping. DetailTaskFailures = "taskFailures" DetailTaskLastError = "taskLastError" )
Ownership labels applied to managed objects so prune is stateless and safe.
Variables ¶
This section is empty.
Functions ¶
func DecodeSpec ¶
DecodeSpec decodes an unstructured spec map into a typed struct T using the struct's `yaml` tags. Providers call this in Observe/Plan/Apply to obtain a typed spec.
Types ¶
type Action ¶
type Action struct {
Type ActionType
Ref model.Ref
Object model.Object // desired object (for create/update)
Reason string // why this action is needed
Diff map[string]any // human-readable diff details
}
Action is a single planned change. Plan produces these; Apply executes them.
type ActionType ¶
type ActionType string
ActionType enumerates the kinds of change an Apply can perform.
const ( ActionCreate ActionType = "create" ActionUpdate ActionType = "update" ActionDelete ActionType = "delete" ActionNoop ActionType = "noop" )
type AllAtOnce ¶
type AllAtOnce struct{}
AllAtOnce applies to every host concurrently is overkill for the small edge fleet; here it applies sequentially with no health gating between hosts.
type Desugarer ¶
Desugarer is optionally implemented by providers serving high-level kinds. It expands one high-level object (e.g. App) into multiple core objects (Service, DNSRecord, Ingress). Returned objects are reconciled by their own providers.
type Observed ¶
type Observed struct {
Exists bool // does the live resource exist?
SpecHash string // io.craneops.spec-hash recorded on the live resource, if any
Details map[string]any // provider-specific observed details
Err string // non-fatal backend error (e.g. swarm unavailable)
}
Observed is the result of reading the live world for an object.
type Provider ¶
type Provider interface {
// Name is the unique provider name (e.g. "docker", "caddy", "gcore").
Name() string
// Kinds are the object kinds this provider can reconcile.
Kinds() []string
// Observe reads the live state for the desired object.
Observe(ctx context.Context, obj model.Object) (Observed, error)
// Plan is pure: given desired + observed, return the actions needed (possibly none).
Plan(ctx context.Context, obj model.Object, obs Observed) ([]Action, error)
// Apply executes a single action and returns provider status details.
Apply(ctx context.Context, a Action) (map[string]any, error)
// Delete removes the live resource for an object (used by prune and explicit delete).
Delete(ctx context.Context, obj model.Object) (map[string]any, error)
}
Provider reconciles one or more kinds against a backend.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry maps object kinds to the providers that serve them. A kind may be served by more than one provider; in that case the object must disambiguate via its Provider field (top-level provider: or spec.provider).
func (*Registry) For ¶
For resolves the provider responsible for an object. Resolution order:
- object.Provider (explicit), else
- the single provider registered for the kind (error if ambiguous or none).
type Rollout ¶
type Rollout interface {
// Execute applies to each host. apply performs the change on a host; health checks
// that the host is healthy afterwards (may be nil).
Execute(ctx context.Context, hosts []string, apply func(ctx context.Context, host string) error, health func(ctx context.Context, host string) error) error
}
Rollout fans an apply function across a set of hosts/targets using some strategy (used by archetype-B providers such as caddy and coredns).
type Sequential ¶
type Sequential struct {
// Rollback is invoked on a host when its apply or health check fails (optional).
Rollback func(ctx context.Context, host string) error
}
Sequential rolls out one host at a time, health-checking each before proceeding and invoking Rollback on the failed host. This is the productised form of edge/rebuild.