provider

package
v0.0.0-...-7f1ac16 Latest Latest
Warning

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

Go to latest
Published: Oct 18, 2026 License: MIT Imports: 6 Imported by: 0

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

View Source
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

func DecodeSpec[T any](m map[string]any) (T, error)

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.

func OwnerLabels

func OwnerLabels(obj model.Object) map[string]string

OwnerLabels returns the standard ownership labels for an object.

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.

func (AllAtOnce) Execute

func (AllAtOnce) Execute(ctx context.Context, hosts []string, apply func(context.Context, string) error, health func(context.Context, string) error) error

Execute applies to all hosts, collecting the first error.

type Desugarer

type Desugarer interface {
	Desugar(obj model.Object) ([]model.Object, error)
}

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 NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty Registry.

func (*Registry) ByName

func (r *Registry) ByName(name string) (Provider, bool)

ByName returns a provider by its name.

func (*Registry) For

func (r *Registry) For(obj model.Object) (Provider, error)

For resolves the provider responsible for an object. Resolution order:

  1. object.Provider (explicit), else
  2. the single provider registered for the kind (error if ambiguous or none).

func (*Registry) Kinds

func (r *Registry) Kinds() []string

Kinds returns all registered kinds, sorted.

func (*Registry) Register

func (r *Registry) Register(p Provider)

Register adds a provider for all the kinds it declares.

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.

func (Sequential) Execute

func (s Sequential) Execute(ctx context.Context, hosts []string, apply func(context.Context, string) error, health func(context.Context, string) error) error

Execute rolls out sequentially with a health gate and optional rollback.

type Validator

type Validator interface {
	Validate(obj model.Object) error
}

Validator is optionally implemented by providers to validate a spec at load time.

Jump to

Keyboard shortcuts

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