driver

Documentation

Overview

Package driver defines the orchestrator driver contract — the modularity seam that eliminates orchestration coupling (architecture.md; ADR-006).

A driver owns everything orchestrator-specific about running Applications on this server. The contract is pure desired-state (ADR-005): the agent hands a driver the full set of AppSpecs that should exist here, and the driver makes reality match — starting what's missing, replacing what changed (health-gated, zero-downtime), removing what's absent. There is no start/stop/exec verb vocabulary to drift into imperative scripts, and nothing outside a driver implementation may touch the orchestrator's API (project-structure rule 2: a feature needing `if swarm` is a design error).

The desired-state schema is the generated proto (pkg/proto — one source of truth shared with the wire, ENGINEERING rule 18). Drivers are constructed explicitly in main and injected (rule 5) — there is no global registry.

Index

• Constants
• func ParsePullMarker(ref string) (appID, source string, ok bool)
• func PullMarkerRef(appID, source string) (ref string, ok bool)
• type DbReconciler
• type Reconciler

Constants

const (
	// LabelManaged marks a resource as CypherPanel-managed; value is the
	// driver name that owns it.
	LabelManaged = "cypherpanel.managed"
	// LabelAppID carries the Application id the resource belongs to.
	LabelAppID = "cypherpanel.app-id"
	// LabelRevisionID carries the revision the resource was created from.
	LabelRevisionID = "cypherpanel.revision-id"
)

Management labels every driver stamps on the resources it creates. They are how a driver discovers its own managed set on a host it has never seen — which is what makes absence-means-remove convergence and desired-state GC (threat-model §5.9) possible after a crash or reinstall.

const PullMarkerPrefix = "cypher-pull/"

PullMarkerPrefix is the repository namespace of the marker reference that records "our own pull created this registry reference".

A pulled image cannot carry our labels — those are baked in by whoever built it — so a *reference* is the only thing a driver can attach to one. That is what this namespace is for: ownership of the floating reference a pull creates is knowable only at pull time (afterwards nothing distinguishes it from a tag the operator made), and it has to survive everything that can happen next — a container that is never created, a rollout discarded at the health gate, an agent restart, the application's own deletion. The image survives all of them, so the record lives on the image.

Functions

func ParsePullMarker

func ParsePullMarker(ref string) (appID, source string, ok bool)

ParsePullMarker recovers the application and the registry reference a marker records. Anything that is not one of ours returns ok=false and is left alone.

func PullMarkerRef

func PullMarkerRef(appID, source string) (ref string, ok bool)

PullMarkerRef is the marker reference recording that appID's pull created source. The reference itself is encoded into the repository path so the exact string to drop is recoverable from the daemon alone — with no spec to consult and no container to read a label off — which is what lets garbage collection finish the job for an application that no longer exists.

ok is false for a reference too long to encode within Docker's name limit (~151 bytes of reference); the caller drops it immediately and, failing that, leaves it, exactly as it would leave one the operator made.

Types

type DbReconciler

type DbReconciler interface {
	ReconcileDatabases(ctx context.Context, desired []*agentv1.DbSpec) ([]*agentv1.DbStatus, error)
	RemoveDatabase(ctx context.Context, dbID string, deleteVolume bool) error
}

DbReconciler manages database resource reconciliation on this server (managed-databases.md §6). Backup/restore execution is a separate follow-up (stripped first-cut recoverable at commit 1d83f0a) and will extend this seam then.

type Reconciler

type Reconciler interface {
	// Name identifies the driver ("docker", "swarm") — reported in heartbeats
	// and used to route work.
	Name() string

	// Reconcile converges local reality toward desired and reports what is
	// actually true afterward. A partial failure converges everything it can
	// and reports per-app state; the returned error is reserved for total
	// inability to reconcile (e.g. orchestrator unreachable).
	Reconcile(ctx context.Context, desired []*agentv1.AppSpec) ([]*agentv1.AppStatus, error)
}

Reconciler is the driver contract. Implementations: driver/docker (launch), driver/swarm (V1.x, ADR-006), k8s (post-v1).

Reconcile converges this server toward exactly the desired set:

• An app in desired but not running here is rolled out.
• An app whose running revision differs from desired is replaced with the zero-downtime sequence (start new → health-gate → flip route → drain old).
• A resource carrying this driver's management labels whose app is absent from desired is removed, and images no spec references become GC-eligible.

Reconcile is idempotent — converging twice equals converging once (rule 13; every driver ships that test) — and safe under work-item redelivery. It returns the observed status of every app it manages after convergence; the control plane asserts deployment outcomes only from these observations, never from work-item completion (ADR-005).