localbackuppolicy

package
v0.40.0 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package localbackuppolicy owns the secret-free, generated contract between the Basement renderer and the native local backup lifecycle.

Index

Constants

View Source 
const (
	APIVersion = "stackkit.local-kopia-runtime-policy/v1"
	Kind       = "LocalKopiaRuntimePolicy"

	// CoreModuleRef and CoreLiteModuleRef are the only runtime profiles that
	// may own the local Kopia source. An empty Source.CoreModuleRef is retained
	// solely for decoding pre-profile Full-Core policy artifacts.
	CoreModuleRef      = "stackkits-basement-core-runtime"
	CoreLiteModuleRef  = "stackkits-basement-core-lite-runtime"
	CloudCoreModuleRef = "stackkits-cloud-core-standalone-runtime"

	ServiceRef          = "kopia-agent"
	Hostname            = "stackkit-basement-backup"
	ImageRef            = "docker.io/kopia/kopia:0.18.2"
	ImageDigest         = "sha256:b6cb1f09a5fa832a320ee06d7803e82cdd7f69ac6f61d76a0d55fbbf1495c043"
	Mode                = "idle-until-owner-command"
	NetworkMode         = "internal-no-peer"
	NetworkRef          = "basement-backup"
	RequiredEvidenceRef = "basement-core-runtime-evidence"

	SourcePath               = "/source/docker-volumes"
	RepositoryPath           = "/app/repository"
	ConfigPath               = "/app/config"
	CachePath                = "/app/cache"
	RestoreStagingPath       = "/restore-staging"
	RestoreStagingMode       = "isolated-named-volume"
	RestoreStagingSourcePath = "/source/docker-volumes/stackkit-basement-core_kopia-restore-staging/_data"
	Custody                  = "owner-local"
	RuntimeMaterial          = "owner-command"
	DockerDaemonRef          = "docker-default"
	DockerDaemonEngine       = "docker"
	DockerDaemonSocketPath   = "/var/run/docker.sock"
	HostScope                = "exclusive-stack-per-daemon"
)
View Source 
const RecoveryObjectiveProjectionAPIVersion = "stackkit.recovery-objective-projection/v1"

RecoveryObjectiveProjectionAPIVersion identifies the optional, derived recovery-objective extension on the compiler-owned backup-source input.

Variables

This section is empty.

Functions

func ApplicationGraphDigest 

func ApplicationGraphDigest(source Source) (string, error)

ApplicationGraphDigest binds a persisted quiescence journal to the exact selected application graphs. Core-only policies intentionally return an empty digest and retain their legacy crash-consistent behavior.

func ApplicationRuntimeStartOrder 

func ApplicationRuntimeStartOrder(runtime ApplicationRuntime) ([]string, error)

ApplicationRuntimeStartOrder returns the dependency-first order derived from the selected graph. Callers must not replace it with label or ID order.

func ApplicationRuntimeStopOrder 

func ApplicationRuntimeStopOrder(runtime ApplicationRuntime) ([]string, error)

ApplicationRuntimeStopOrder returns the reverse dependency order used to stop application writers before their databases and infrastructure.

func ArtifactBytes 

func ArtifactBytes(policy Policy) ([]byte, error)

ArtifactBytes returns the single canonical artifact representation. The renderer contract includes exactly one final LF; Decode rejects its absence, CRLF, blank lines, and all other whitespace variations.

func Digest 

func Digest(raw []byte) (string, error)

Digest verifies the artifact before returning its content-addressed SHA-256.

func IsRecognizedSnapshotSelection 

func IsRecognizedSnapshotSelection(containerPath string, excludes []string) bool

IsRecognizedSnapshotSelection accepts the current governed backup selection and the immediately preceding v1 selection. The latter did not mention the restore-staging volume because that volume did not exist yet. Keeping this narrow compatibility rule allows pre-restore anchors to remain usable while every new snapshot excludes staged restore bytes.

func IsRecognizedSnapshotSelectionForCoreModule 

func IsRecognizedSnapshotSelectionForCoreModule(coreModuleRef, containerPath string, excludes []string) bool

IsRecognizedSnapshotSelectionForCoreModule accepts the current or pre-staging selection for one supported Core profile. Empty moduleRef is the legacy Full-Core encoding and is intentionally never inferred as Lite.

func ManagedVolumeNames 

func ManagedVolumeNames() []string

ManagedVolumeNames returns the exact Compose-qualified persistent volume allowlist that the local Kopia source may observe. Repository, cache, and restore-staging volumes are intentionally absent.

func ManagedVolumeNamesForCoreModule 

func ManagedVolumeNamesForCoreModule(coreModuleRef string) ([]string, error)

ManagedVolumeNamesForCoreModule returns the exact profile-owned Core names.

func ManagedVolumeNamesWithApplicationVolumes 

func ManagedVolumeNamesWithApplicationVolumes(applicationVolumes []ApplicationVolume) ([]string, error)

ManagedVolumeNamesWithApplicationVolumes returns the canonical Core names followed by selected application volume names in stable order.

func ManagedVolumeNamesWithApplicationVolumesForCoreModule 

func ManagedVolumeNamesWithApplicationVolumesForCoreModule(coreModuleRef string, applicationVolumes []ApplicationVolume) ([]string, error)

ManagedVolumeNamesWithApplicationVolumesForCoreModule returns the exact selected Core profile names followed by compiler-owned application names.

func RestorePathForOperation 

func RestorePathForOperation(operationID string) string

RestorePathForOperation returns the non-caller-controlled staging directory for one portable lifecycle operation ID.

func SourceDigest 

func SourceDigest(source Source) (string, error)

SourceDigest binds restore execution to the exact historical/current volume selection without coupling it to unrelated runtime-policy revisions.

func StandaloneComposeLogicalVolumeName 

func StandaloneComposeLogicalVolumeName(componentRef, volumeRef string) string

StandaloneComposeLogicalVolumeName is the shared unqualified Compose volume name derivation for one component volume.

func StandaloneComposeProjectName 

func StandaloneComposeProjectName(workloadRef, nodeRef string) string

StandaloneComposeProjectName is the shared project-name derivation used by the runtime renderer, backup projection, and restore authority.

func StandaloneComposeVolumeName 

func StandaloneComposeVolumeName(workloadRef, nodeRef, componentRef, volumeRef string) string

StandaloneComposeVolumeName is the shared Docker Compose-qualified volume name derivation for one Standalone-Compose application volume.

func ValidComposeVolumeName 

func ValidComposeVolumeName(name string) bool

ValidComposeVolumeName reports whether name is a Compose-qualified volume identity the backup source may mount.

func ValidateRecoveryObjectives 

func ValidateRecoveryObjectives(objectives []RecoveryObjective) error

ValidateRecoveryObjectives checks the canonical target-local encoding used by the local Kopia policy artifact. Runtime evidence is deliberately outside this type; these values are goals, not proof that recovery is possible.

func ValidateSnapshotPolicy 

func ValidateSnapshotPolicy(policy Policy) error

ValidateSnapshotPolicy verifies a policy embedded in owner-signed snapshot evidence. New policy artifacts remain exact-current through Decode; this verifier additionally recognizes the pre-staging v1 snapshot selection so upgrades do not invalidate existing anchors.

func ValidateSourceProjection 

func ValidateSourceProjection(source Source) error

ValidateSourceProjection verifies the aggregate compiler projection before a renderer narrows it to one node-local policy instance.

Types

type ApplicationRuntime 

type ApplicationRuntime struct {
	WorkloadRef    string                        `json:"workloadRef"`
	SiteRef        string                        `json:"siteRef"`
	NodeRef        string                        `json:"nodeRef"`
	ComposeProject string                        `json:"composeProject"`
	Components     []ApplicationRuntimeComponent `json:"components"`
}

ApplicationRuntime is the compiler-owned component graph for one exact Standalone-Compose workload placement. The graph is retained in the source policy so lifecycle consumers cannot infer stop order from Docker names or mutable container labels.

func ApplicationRuntimesForTarget 

func ApplicationRuntimesForTarget(runtimes []ApplicationRuntime, siteRef, nodeRef string) ([]ApplicationRuntime, error)

ApplicationRuntimesForTarget narrows the compiler aggregate to one exact node-local placement while preserving the canonical graph encoding.

type ApplicationRuntimeComponent 

type ApplicationRuntimeComponent struct {
	ComponentRef  string   `json:"componentRef"`
	Role          string   `json:"role"`
	Lifecycle     string   `json:"lifecycle"`
	HealthFailure string   `json:"healthFailure,omitempty"`
	ImageRef      string   `json:"imageRef"`
	ImageDigest   string   `json:"imageDigest"`
	DependsOn     []string `json:"dependsOn"`
}

ApplicationRuntimeComponent is one closed runtime graph node. ImageRef and ImageDigest are copied from the selected CUE runtime component; DependsOn is the only source used to derive quiescence order.

type ApplicationVolume 

type ApplicationVolume struct {
	WorkloadRef    string   `json:"workloadRef"`
	SiteRef        string   `json:"siteRef"`
	NodeRef        string   `json:"nodeRef"`
	ComposeProject string   `json:"composeProject"`
	ComponentRef   string   `json:"componentRef"`
	VolumeRef      string   `json:"volumeRef"`
	LogicalName    string   `json:"logicalName"`
	VolumeName     string   `json:"volumeName"`
	Target         string   `json:"target"`
	Class          string   `json:"class"`
	Backup         bool     `json:"backup"`
	DataClasses    []string `json:"dataClasses"`
	DataBindingRef string   `json:"dataBindingRef"`
}

ApplicationVolume is the canonical source-policy record for one persistent volume selected from a Standalone-Compose application workload. Identity and placement stay in the artifact so consumers cannot widen the source to a similarly named volume on another node.

func ApplicationVolumesForTarget 

func ApplicationVolumesForTarget(applicationVolumes []ApplicationVolume, siteRef, nodeRef string) ([]ApplicationVolume, error)

ApplicationVolumesForTarget narrows the compiler aggregate to one exact node-local policy target. It preserves the canonical order and deep-copy semantics used by the policy codec.

type BackupSourceProjection 

type BackupSourceProjection struct {
	Source
	RecoveryObjectiveProjection *RecoveryObjectiveProjection `json:"recoveryObjectiveProjection,omitempty"`
}

BackupSourceProjection is the existing flat Source input with an optional typed recovery extension. Embedding preserves the fieldless legacy JSON representation when the extension is absent.

type Document 

type Document struct {
	APIVersion string `json:"apiVersion"`
	Kind       string `json:"kind"`
	Policy     Policy `json:"policy"`
}

Document is the versioned on-disk local Kopia runtime policy artifact.

type Policy 

type Policy struct {
	StackID            string              `json:"stackId"`
	Target             Target              `json:"target"`
	Runtime            Runtime             `json:"runtime"`
	Source             Source              `json:"source"`
	Retention          *Retention          `json:"retention,omitempty"`
	Schedule           *Schedule           `json:"schedule,omitempty"`
	RecoveryObjectives []RecoveryObjective `json:"recoveryObjectives,omitempty"`
}

Policy binds the governed local Kopia runtime to one resolved Stack target.

func Decode 

func Decode(raw []byte) (Policy, error)

Decode verifies strict JSON shape, governed values, and byte-for-byte canonical encoding before returning a policy.

func New 

func New(stackID, siteRef, nodeRef string) (Policy, error)

New returns the exact governed policy for one resolved Basement target.

func NewForCoreModule 

func NewForCoreModule(coreModuleRef, stackID, siteRef, nodeRef string) (Policy, error)

NewForCoreModule returns a policy bound to one of the finite local Core runtime profiles. Full-Core uses the pre-profile fieldless encoding for compatibility; CoreLite carries its explicit module binding.

func NewWithApplicationVolumes 

func NewWithApplicationVolumes(stackID, siteRef, nodeRef string, applicationVolumes []ApplicationVolume) (Policy, error)

NewWithApplicationVolumes returns the governed local Kopia policy with the selected Standalone-Compose application volumes attached to the target. Application records remain in the signed policy artifact so the runtime and restore authorities retain the CUE-derived ownership binding.

func NewWithApplicationVolumesAndRuntimes 

func NewWithApplicationVolumesAndRuntimes(stackID, siteRef, nodeRef string, applicationVolumes []ApplicationVolume, applicationRuntimes []ApplicationRuntime) (Policy, error)

NewWithApplicationVolumesAndRuntimes returns the governed policy with the exact selected application volumes and their compiler-owned runtime graphs.

func NewWithApplicationVolumesAndRuntimesForCoreModule 

func NewWithApplicationVolumesAndRuntimesForCoreModule(coreModuleRef, stackID, siteRef, nodeRef string, applicationVolumes []ApplicationVolume, applicationRuntimes []ApplicationRuntime) (Policy, error)

NewWithApplicationVolumesAndRuntimesForCoreModule returns a policy bound to one of the finite local Core runtime profiles. The profile controls the governed Core volume set; application volumes remain compiler-selected. Full-Core intentionally retains the fieldless legacy wire encoding so a profile-aware regeneration does not change an otherwise identical artifact; CoreLite remains explicitly identified in the source.

func (Policy) RuntimeProjection 

func (policy Policy) RuntimeProjection() Runtime

RuntimeProjection returns a detached runtime projection suitable for execution adapters without allowing callers to mutate the decoded authority.

func (Policy) SourceProjection 

func (policy Policy) SourceProjection() Source

SourceProjection returns a detached source projection suitable for lifecycle translation without allowing callers to mutate the decoded authority.

type RecoveryObjective 

type RecoveryObjective struct {
	BindingRef          string   `json:"bindingRef"`
	WorkloadRefs        []string `json:"workloadRefs"`
	MaxDataLossSeconds  int      `json:"maxDataLossSeconds"`
	RecoveryTimeSeconds int      `json:"recoveryTimeSeconds"`
}

RecoveryObjective is the target-local projection of one CUE DataBinding recovery objective. WorkloadRefs are derived from the selected application volumes; callers must not treat them as an independent source of authority.

func RecoveryObjectivesForTarget 

func RecoveryObjectivesForTarget(projection *RecoveryObjectiveProjection, sourceApplications []ApplicationVolume, siteRef, nodeRef string) ([]RecoveryObjective, error)

RecoveryObjectivesForTarget narrows the logical-unit projection to the exact node-local application volumes selected by the runtime renderer.

type RecoveryObjectiveProjection 

type RecoveryObjectiveProjection struct {
	APIVersion string              `json:"apiVersion"`
	Objectives []RecoveryObjective `json:"objectives"`
}

RecoveryObjectiveProjection carries only target-local recovery goals. It deliberately sits outside Source so SourceDigest remains bound to the physical data selection alone.

type Retention 

type Retention struct {
	KeepDaily   int `json:"keepDaily"`
	KeepWeekly  int `json:"keepWeekly"`
	KeepMonthly int `json:"keepMonthly"`
	KeepYearly  int `json:"keepYearly"`
}

Retention carries the resolved foundation.#BackupRetentionV1 contract. Defaults are supplied by CUE. Nil preserves the historical manual policy; it must never be interpreted as a newly selected retention schedule.

func (Retention) Validate 

func (retention Retention) Validate() error

Validate bounds the runtime lowering of an already CUE-resolved policy.

type Runtime 

type Runtime struct {
	ServiceRef          string   `json:"serviceRef"`
	Hostname            string   `json:"hostname"`
	Image               string   `json:"image"`
	Mode                string   `json:"mode"`
	NetworkMode         string   `json:"networkMode"`
	NetworkRef          string   `json:"networkRef"`
	HealthCommand       []string `json:"healthCommand"`
	RequiredEvidenceRef string   `json:"requiredEvidenceRef"`
}

func GovernedRuntime 

func GovernedRuntime() Runtime

GovernedRuntime returns a detached copy of the exact local Kopia runtime.

type Schedule 

type Schedule struct {
	Cadence       string `json:"cadence"`
	MinuteUTC     int    `json:"minuteUTC"`
	HourUTC       *int   `json:"hourUTC,omitempty"`
	WeekdayUTC    string `json:"weekdayUTC,omitempty"`
	JitterSeconds int    `json:"jitterSeconds"`
}

Schedule is the resolved foundation.#BackupScheduleV1 UTC intent. It grants no execution authority; local scheduling requires separate Owner approval. Nil preserves historical policies that have no executable schedule intent.

func (Schedule) MaximumTriggerIntervalSeconds 

func (schedule Schedule) MaximumTriggerIntervalSeconds() (int, error)

MaximumTriggerIntervalSeconds bounds adjacent scheduled UTC trigger slots, including jitter. It does not include backup duration or prove an RPO.

func (Schedule) Validate 

func (schedule Schedule) Validate() error

type Source 

type Source struct {
	Kind                string               `json:"kind"`
	HostPath            string               `json:"hostPath"`
	ContainerPath       string               `json:"containerPath"`
	ReadOnly            bool                 `json:"readOnly"`
	CoreModuleRef       string               `json:"coreModuleRef,omitempty"`
	ManagedVolumeNames  []string             `json:"managedVolumeNames"`
	ApplicationVolumes  []ApplicationVolume  `json:"applicationVolumes,omitempty"`
	ApplicationRuntimes []ApplicationRuntime `json:"applicationRuntimes,omitempty"`
	ExcludePaths        []string             `json:"excludePaths"`
	RepositoryPath      string               `json:"repositoryPath"`
	ConfigPath          string               `json:"configPath"`
	CachePath           string               `json:"cachePath"`
	Custody             string               `json:"custody"`
	RuntimeMaterial     string               `json:"runtimeMaterial"`
}

func GovernedSource 

func GovernedSource() Source

GovernedSource returns a detached copy of the exact read-only backup source. Exclusion order is a canonical contract: repository, config, then cache.

func GovernedSourceForCoreModule 

func GovernedSourceForCoreModule(coreModuleRef string) (Source, error)

GovernedSourceForCoreModule returns the exact source for a supported Core runtime profile. New artifacts carry the selected module explicitly so the source allowlist cannot be widened by a consumer.

func GovernedSourceWithApplicationVolumes 

func GovernedSourceWithApplicationVolumes(applicationVolumes []ApplicationVolume) (Source, error)

GovernedSourceWithApplicationVolumes extends the CUE-owned Core source with exactly the selected application volumes. The static Core list and exclusion topology remain unchanged.

func GovernedSourceWithApplicationVolumesAndRuntimes 

func GovernedSourceWithApplicationVolumesAndRuntimes(applicationVolumes []ApplicationVolume, applicationRuntimes []ApplicationRuntime) (Source, error)

GovernedSourceWithApplicationVolumesAndRuntimes extends the CUE-owned Core source with selected application volumes and their closed runtime graphs.

func GovernedSourceWithApplicationVolumesAndRuntimesForCoreModule 

func GovernedSourceWithApplicationVolumesAndRuntimesForCoreModule(coreModuleRef string, applicationVolumes []ApplicationVolume, applicationRuntimes []ApplicationRuntime) (Source, error)

GovernedSourceWithApplicationVolumesAndRuntimesForCoreModule extends the selected finite Core profile with compiler-owned application volumes and runtime graphs.

func (Source) ComposeProject 

func (source Source) ComposeProject() string

ComposeProject returns the finite runtime identity carried by an admitted source profile. Unknown profiles are rejected by ValidateSourceProjection.

func (Source) RuntimeProfile 

func (source Source) RuntimeProfile() Runtime

type Target 

type Target struct {
	SiteRef          string `json:"siteRef"`
	NodeRef          string `json:"nodeRef"`
	DaemonRef        string `json:"daemonRef,omitempty"`
	DaemonEngine     string `json:"daemonEngine,omitempty"`
	DaemonSocketPath string `json:"daemonSocketPath,omitempty"`
	HostScope        string `json:"hostScope,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.