upgradelifecycle

package
v0.46.5 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const (
	ExecutorStateSnapshotAPIVersion = "stackkit.executor-state-snapshot/v1"
)
View Source 
const (
	InspectionSchemaVersion = "stackkit.upgrade-inspection/v1"
)

Variables

This section is empty.

Functions

func GenerationTargetForPlan added in v0.46.5 

func GenerationTargetForPlan(plan generationartifact.VerifiedPlan) (string, error)

GenerationTargetForPlan returns the generation target a verified plan resolved from its StackSpec.

func ReleaseExecutablesFromVerifiedRelease added in v0.46.1 

func ReleaseExecutablesFromVerifiedRelease(
	proof releaseindex.VerifiedInstallation,
) (cli, server []byte, err error)

ReleaseExecutablesFromVerifiedRelease returns the exact stackkit and stackkit-server executables of an offline-verified installed release. The server is nil for a release that does not ship one. The v2 Core runs that server, so an upgrade stages it beside the target stackkit executable.

func SnapshotInventoryBlobPath 

func SnapshotInventoryBlobPath(snapshot ExecutorStateSnapshot) (string, error)

SnapshotInventoryBlobPath returns the content-addressed Inventory captured by a verified executor-state snapshot. Callers must load or verify the snapshot before handing this path to a release CLI.

func SnapshotRuntimeComposeBlobPath 

func SnapshotRuntimeComposeBlobPath(snapshot ExecutorStateSnapshot) (string, error)

SnapshotRuntimeComposeBlobPath returns the original, signed runtime Compose definition. During an upgrade, target Generate may replace the active file before Apply checks whether the old runtime owns its published ports.

Types

type ArtifactDiff 

type ArtifactDiff struct {
	ID              string `json:"id"`
	Path            string `json:"path"`
	Status          string `json:"status"`
	MetadataChanged bool   `json:"metadataChanged"`
	CurrentSHA256   string `json:"currentSha256,omitempty"`
	TargetSHA256    string `json:"targetSha256,omitempty"`
	CurrentKind     string `json:"currentKind,omitempty"`
	TargetKind      string `json:"targetKind,omitempty"`
	CurrentFormat   string `json:"currentFormat,omitempty"`
	TargetFormat    string `json:"targetFormat,omitempty"`
	CurrentMode     string `json:"currentMode,omitempty"`
	TargetMode      string `json:"targetMode,omitempty"`
}

type CurrentApplyResultVerifier 

type CurrentApplyResultVerifier struct {
	// contains filtered or unexported fields
}

CurrentApplyResultVerifier is an opaque adapter around the Architecture-v2 Apply verifier. Callers cannot substitute a verifier function.

func NewCurrentApplyResultVerifier 

func NewCurrentApplyResultVerifier(ctx context.Context, service *architecturev2.Service, journal *architecturev2.ProductApplyFileJournal) (CurrentApplyResultVerifier, error)

type CurrentSourceVerifier 

type CurrentSourceVerifier struct {
	// contains filtered or unexported fields
}

CurrentSourceVerifier re-resolves the exact recovery StackSpec and Inventory through a fresh Architecture-v2 CurrentResolution.

func NewCurrentSourceVerifier 

func NewCurrentSourceVerifier(service *architecturev2.Service) (CurrentSourceVerifier, error)

type CurrentStateAuthorityInput 

type CurrentStateAuthorityInput struct {
	WorkspaceRoot     string
	Plan              generationartifact.VerifiedPlan
	Manifest          generationartifact.ArtifactManifest
	GenerationReceipt generationartifact.GenerationReceipt
	Versions          generationartifact.ComponentVersions
	ApplyResult       []byte
	ApplyReceipt      []byte
	SourceVerifier    CurrentSourceVerifier
	ApplyVerifier     CurrentApplyResultVerifier
	Capture           ExecutorStateCaptureInput
	Legacy            *LegacyCurrentStateAuthorityInput
}

CurrentStateAuthorityInput contains the complete already-resolved current state. NewVerifiedExecutorStateCapture re-verifies every authority edge and returns the only handle accepted by ExecutorStateStore.

type CurrentStateCoreProfile 

type CurrentStateCoreProfile struct {
	ModuleRef             string
	ComposeArtifactID     string
	ComposeOutputRef      string
	CoreArtifactOutputRef string
	PolicyArtifactID      string
	PolicyOutputRef       string
}

CurrentStateCoreProfile is the exact Core profile and artifact pair used by the current Plan-owned recovery closure. The IDs come from ApplyRequirements; the stable profile identity and Compose output come from the existing local runtime profile registry.

ComposeArtifactID names the governed artifact that carries the Core Compose payload and CoreArtifactOutputRef is its recovery path: the Compose artifact itself under the compose target, the Core OpenTofu root main.tf (which embeds the same payload byte for byte) under the opentofu and terramate targets. Every other field is identical across the three targets.

func CurrentStateCoreProfileForPlan 

func CurrentStateCoreProfileForPlan(
	plan generationartifact.VerifiedPlan,
	siteRef string,
	nodeRef string,
) (CurrentStateCoreProfile, error)

CurrentStateCoreProfileForPlan selects the one Full or Lite Core runtime and its Compose/source-policy artifacts from the verified Apply requirements. It never derives a profile from an artifact filename or generated bytes.

func (CurrentStateCoreProfile) CoreComposePayload added in v0.46.5 

func (profile CurrentStateCoreProfile) CoreComposePayload(artifact []byte) ([]byte, error)

CoreComposePayload returns the Core Compose payload the profile's carrier artifact holds: the artifact itself under the compose target, or the payload extracted from the Core OpenTofu root under the opentofu and terramate targets.

type ExecRunner 

type ExecRunner struct{}

func (ExecRunner) Run 

func (ExecRunner) Run(ctx context.Context, binary string, args []string, dir string) ([]byte, error)

type ExecutorStateBlob 

type ExecutorStateBlob struct {
	ID     string `json:"id"`
	Path   string `json:"path"`
	Mode   string `json:"mode"`
	SHA256 string `json:"sha256"`
}

type ExecutorStateBlobInput 

type ExecutorStateBlobInput struct {
	ID   string
	Path string
	Mode string
	Data []byte
}

type ExecutorStateCaptureInput 

type ExecutorStateCaptureInput struct {
	OperationID           string
	GenerationTarget      string
	CoreModuleRef         string
	CoreComposeArtifactID string
	CorePolicyArtifactID  string
	Release               releaseindex.VerifiedInstallation
	Executable            ExecutorStateExecutableInput
	Lineage               backuplifecycle.AuthorityLineage
	StackSpec             ExecutorStateBlobInput
	Inventory             *ExecutorStateBlobInput
	Artifacts             []ExecutorStateBlobInput
	RuntimeCompose        ExecutorStateBlobInput
	// RuntimeOpenTofu replaces RuntimeCompose when the generation target
	// executes OpenTofu (opentofu or terramate).
	RuntimeOpenTofu     []ExecutorStateOpenTofuRootInput
	KopiaSnapshotAnchor backuplifecycle.SnapshotAnchor
}

type ExecutorStateExecutable 

type ExecutorStateExecutable struct {
	Version string             `json:"version"`
	Blob    ExecutorStateBlob  `json:"blob"`
	Server  *ExecutorStateBlob `json:"server,omitempty"`
}

type ExecutorStateExecutableInput 

type ExecutorStateExecutableInput struct {
	Blob ExecutorStateBlobInput
	// Server is the release's stackkit-server. The v2 Core stages it from
	// beside the executing stackkit, so a recovery Apply needs it too.
	// Releases that predate the Core server ship none.
	Server *ExecutorStateBlobInput
}

type ExecutorStateOpenTofuRoot added in v0.46.5 

type ExecutorStateOpenTofuRoot struct {
	ModuleRef   string            `json:"moduleRef"`
	Root        string            `json:"root"`
	State       ExecutorStateBlob `json:"state"`
	Config      ExecutorStateBlob `json:"config"`
	Compose     ExecutorStateBlob `json:"compose,omitzero"`
	Environment ExecutorStateBlob `json:"environment,omitzero"`
}

ExecutorStateOpenTofuRoot is the signed identity of one captured root.

type ExecutorStateOpenTofuRootInput added in v0.46.5 

type ExecutorStateOpenTofuRootInput struct {
	ModuleRef   string
	Root        string
	State       ExecutorStateBlobInput
	Config      ExecutorStateBlobInput
	Compose     ExecutorStateBlobInput
	Environment ExecutorStateBlobInput
}

ExecutorStateOpenTofuRootInput is one OpenTofu root captured when the generation target executes OpenTofu: its local-backend state and root configuration, plus the runtime Compose file its local_file resource writes one level up (Core and workload roots) and, for a workload root, the private .env its Compose project reads. Edge and federation contract roots (.stackkit/runtime/modules/<moduleRef>/opentofu) own no Compose file.

func CollectOpenTofuRootStates added in v0.46.5 

func CollectOpenTofuRootStates(workspaceRoot string) ([]ExecutorStateOpenTofuRootInput, error)

CollectOpenTofuRootStates reads every materialized OpenTofu root below .stackkit/runtime as capture input: Core roots (<runtime>/opentofu), workload roots (applications/<project>/opentofu) and edge and federation contract roots (modules/<moduleRef>/opentofu), the runtime roots of every stack in the Terramate stack graph. A root is identified by the marker the runtime executor writes; roots are returned in path order.

type ExecutorStateRecoveryResult 

type ExecutorStateRecoveryResult struct {
	SnapshotID          string                         `json:"snapshotId"`
	OperationID         string                         `json:"operationId"`
	Release             ExecutorStateRelease           `json:"release"`
	KopiaSnapshotAnchor backuplifecycle.SnapshotAnchor `json:"kopiaSnapshotAnchor"`
	RestoredPaths       []string                       `json:"restoredPaths"`
}

ExecutorStateRecoveryResult is the secret-free projection of one verified executor-state recovery handoff. Kopia data remains an owner-signed anchor; Recover never promotes staged backup data into live volumes.

type ExecutorStateRelease 

type ExecutorStateRelease struct {
	Kit                    string                `json:"kit"`
	Version                string                `json:"version"`
	Channel                releaseindex.Channel  `json:"channel"`
	Platform               releaseindex.Platform `json:"platform"`
	ArchiveSHA256          string                `json:"archiveSha256"`
	SBOMSHA256             string                `json:"sbomSha256"`
	AttestationSHA256      string                `json:"attestationSha256"`
	TrustedRootSHA256      string                `json:"trustedRootSha256"`
	IndexSHA256            string                `json:"indexSha256"`
	IndexAttestationSHA256 string                `json:"indexAttestationSha256"`
	AttestationIssuer      string                `json:"attestationIssuer"`
	CertificateIdentity    string                `json:"certificateIdentity"`
	AttestationSubject     string                `json:"attestationSubject"`
	PredicateType          string                `json:"predicateType"`
}

type ExecutorStateRollbackCustody added in v0.46.5 

type ExecutorStateRollbackCustody struct {
	Snapshot  ExecutorStateSnapshot
	Roots     []ExecutorStateRootPayload
	Artifacts map[string][]byte
}

ExecutorStateRollbackCustody is the verified content of one checkpoint that the Advanced coordinated rollback restores per stack: every captured OpenTofu root and every captured artifact by ID (the Terramate stack graph and stack files among them).

type ExecutorStateRootPayload added in v0.46.5 

type ExecutorStateRootPayload struct {
	ModuleRef      string
	Root           string
	State          []byte
	Config         []byte
	Compose        []byte
	HasCompose     bool
	Environment    []byte
	HasEnvironment bool
}

ExecutorStateRootPayload is the verified bytes of one captured OpenTofu root.

type ExecutorStateSnapshot 

type ExecutorStateSnapshot struct {
	APIVersion            string                                    `json:"apiVersion"`
	ID                    string                                    `json:"id"`
	RequestHash           string                                    `json:"requestHash"`
	OwnerRef              string                                    `json:"ownerRef"`
	OperationID           string                                    `json:"operationId"`
	GenerationTarget      string                                    `json:"generationTarget"`
	CoreModuleRef         string                                    `json:"coreModuleRef,omitempty"`
	CoreComposeArtifactID string                                    `json:"coreComposeArtifactId,omitempty"`
	CorePolicyArtifactID  string                                    `json:"corePolicyArtifactId,omitempty"`
	Release               ExecutorStateRelease                      `json:"release"`
	Executable            ExecutorStateExecutable                   `json:"executable"`
	Lineage               backuplifecycle.AuthorityLineage          `json:"lineage"`
	StackSpec             ExecutorStateBlob                         `json:"stackSpec"`
	Inventory             *ExecutorStateBlob                        `json:"inventory,omitempty"`
	Artifacts             []ExecutorStateBlob                       `json:"artifacts"`
	RuntimeCompose        ExecutorStateBlob                         `json:"runtimeCompose,omitzero"`
	RuntimeOpenTofu       []ExecutorStateOpenTofuRoot               `json:"runtimeOpenTofu,omitempty"`
	KopiaSnapshotAnchor   backuplifecycle.SnapshotAnchor            `json:"kopiaSnapshotAnchor"`
	CapturedAt            time.Time                                 `json:"capturedAt"`
	Signature             localevidence.OwnerExecutorStateSignature `json:"signature"`
}

type ExecutorStateStore 

type ExecutorStateStore struct {
	Now func() time.Time
}

func (ExecutorStateStore) Capture 

func (store ExecutorStateStore) Capture(
	workspaceRoot string,
	verified VerifiedExecutorStateCapture,
) (ExecutorStateSnapshot, error)

func (ExecutorStateStore) Load 

func (store ExecutorStateStore) Load(workspaceRoot, snapshotID string) (ExecutorStateSnapshot, error)

func (ExecutorStateStore) LoadRollbackCustody added in v0.46.5 

func (store ExecutorStateStore) LoadRollbackCustody(
	workspaceRoot, snapshotID string,
) (custody ExecutorStateRollbackCustody, returnErr error)

LoadRollbackCustody verifies a committed snapshot and returns its OpenTofu roots and artifacts. It writes nothing. Only OpenTofu-executing generation targets carry roots.

func (ExecutorStateStore) Recover 

func (store ExecutorStateStore) Recover(
	ctx context.Context,
	workspaceRoot string,
	snapshotID string,
	invoke RecoveryCommand,
) (ExecutorStateRecoveryResult, error)

Recover verifies a committed executor-state snapshot and every retained blob before restoring its StackSpec, optional Inventory, and, for an OpenTofu generation target, every captured OpenTofu root. It invokes the caller with the exact captured executable and removes that temporary executable when the callback returns.

func (ExecutorStateStore) RecoverWith added in v0.46.5 

func (store ExecutorStateStore) RecoverWith(
	ctx context.Context,
	workspaceRoot string,
	snapshotID string,
	options RecoveryOptions,
	invoke RecoveryCommand,
) (ExecutorStateRecoveryResult, error)

RecoverWith is Recover with explicit options.

func (ExecutorStateStore) Verify 

func (store ExecutorStateStore) Verify(workspaceRoot string, snapshot ExecutorStateSnapshot) error

func (ExecutorStateStore) WithRuntimeCustody 

func (store ExecutorStateStore) WithRuntimeCustody(
	ctx context.Context,
	workspaceRoot, snapshotID string,
	use func(context.Context, MaterializedRuntimeCustody) error,
) (returnErr error)

WithRuntimeCustody verifies a committed owner-signed checkpoint and all its blobs, then copies the recorded runtime closure without generating artifacts or overwriting workspace files. The callback sees only a complete private view. That view is removed on success, failure, or context cancellation.

type Inspection 

type Inspection struct {
	SchemaVersion string              `json:"schemaVersion"`
	Target        Target              `json:"target"`
	Plan          PlanDiff            `json:"plan"`
	Artifacts     []ArtifactDiff      `json:"artifacts"`
	Execution     InspectionExecution `json:"execution"`
}

func (Inspection) MarshalCanonical 

func (inspection Inspection) MarshalCanonical() ([]byte, error)

type InspectionExecution 

type InspectionExecution struct {
	Mode            string `json:"mode"`
	TargetBinary    string `json:"targetBinary"`
	GenerateInvoked bool   `json:"generateInvoked"`
	ApplyInvoked    bool   `json:"applyInvoked"`
	SnapshotCreated bool   `json:"snapshotCreated"`
}

type Inspector 

type Inspector struct {
	Source            releaseindex.Source
	Attestations      releaseindex.AttestationVerifier
	Runner            Runner
	InventoryPath     string
	MaxBlobBytes      int64
	MaxExtractBytes   int64
	MaxWorkspaceBytes int64
	MaxFiles          int
	Timeout           time.Duration
}

func (Inspector) Inspect 

func (inspector Inspector) Inspect(ctx context.Context, resolution releaseindex.Resolution, workspace, specFile string, current generationartifact.PlanInspection) (Inspection, error)

type LegacyCurrentStateAuthorityInput 

type LegacyCurrentStateAuthorityInput struct {
	WorkspaceRoot     string
	Inspection        generationartifact.PlanInspection
	Manifest          generationartifact.ArtifactManifest
	GenerationReceipt generationartifact.GenerationReceipt
	ApplyResult       []byte
	ApplyReceipt      []byte
	Capture           ExecutorStateCaptureInput
}

LegacyCurrentStateAuthorityInput is intentionally limited to the exact published beta.4 through v0.12.0 authority discontinuities. The caller must still supply the immutable installed-release proof, owner-signed Apply evidence, complete generated artifact closure, and the candidate-created Kopia snapshot.

type MaterializedRuntimeCustody 

type MaterializedRuntimeCustody struct {
	// contains filtered or unexported fields
}

MaterializedRuntimeCustody identifies exact checkpoint files within a private workspace directory. It is valid only during WithRuntimeCustody's callback. It neither starts services nor authorizes a live data cutover.

func (MaterializedRuntimeCustody) BindRestore 

func (custody MaterializedRuntimeCustody) BindRestore(result backuplifecycle.RestoreResult) (restoreactivation.Authority, error)

BindRestore verifies the real owner-signed staging result against this exact checkpoint, then projects the historical runtime into the private file view. The upgrade controller still owns target admission and the mutation journal.

func (MaterializedRuntimeCustody) Graph 

func (custody MaterializedRuntimeCustody) Graph() restoreactivation.RuntimeRecoveryGraph

Graph returns historical, defensively copied data, never a fresh CUE plan.

func (MaterializedRuntimeCustody) OperationID 

func (custody MaterializedRuntimeCustody) OperationID() string

func (MaterializedRuntimeCustody) Path 

func (custody MaterializedRuntimeCustody) Path(original string) (string, error)

Path maps one recorded workspace-relative path to its private materialized copy. Callers retain the original workspace as the owner-custody root.

func (MaterializedRuntimeCustody) ReadArtifact 

func (custody MaterializedRuntimeCustody) ReadArtifact(id string) ([]byte, error)

ReadArtifact reads exact retained bytes by their checkpoint artifact identity. It rechecks the CAS digest and is valid only inside WithRuntimeCustody.

func (MaterializedRuntimeCustody) SnapshotID 

func (custody MaterializedRuntimeCustody) SnapshotID() string

type PlanDiff 

type PlanDiff struct {
	Changed             bool   `json:"changed"`
	CurrentPlanHash     string `json:"currentPlanHash"`
	TargetPlanHash      string `json:"targetPlanHash"`
	CurrentManifestHash string `json:"currentManifestHash"`
	TargetManifestHash  string `json:"targetManifestHash"`
}

type RecoveryCommand 

type RecoveryCommand func(
	context.Context,
	string,
	ExecutorStateSnapshot,
) error

RecoveryCommand receives the exact captured executable in a private, process-owned temporary directory after the captured StackSpec and optional Inventory have been restored atomically.

type RecoveryOptions added in v0.46.5 

type RecoveryOptions struct {
	// ReplaceAuthority restores the captured StackSpec and Inventory even
	// when they changed after the checkpoint. Only an Owner-approved
	// rollback to this exact checkpoint sets it; a change set promotes its
	// candidate StackSpec before its target runs, so the current StackSpec
	// is expected to differ.
	ReplaceAuthority bool
	// SkipOpenTofuRoots leaves the OpenTofu roots to the caller. The
	// coordinated rollback restores and converges them per stack, and a
	// second restore here would overwrite the state its forced apply wrote.
	SkipOpenTofuRoots bool
}

RecoveryOptions narrows Recover for the Advanced coordinated rollback (docs/ARCHITECTURE.md "Coordinated rollback across stacks (Stage 1)").

type Runner 

type Runner interface {
	Run(context.Context, string, []string, string) ([]byte, error)
}

type Target 

type Target struct {
	Kit           string                `json:"kit"`
	Version       string                `json:"version"`
	Channel       releaseindex.Channel  `json:"channel"`
	Platform      releaseindex.Platform `json:"platform"`
	Asset         string                `json:"asset"`
	ArchiveSHA256 string                `json:"archiveSha256"`
}

type VerifiedExecutorStateCapture 

type VerifiedExecutorStateCapture struct {
	// contains filtered or unexported fields
}

VerifiedExecutorStateCapture is an immutable authority handle created only after re-verifying the exact current Plan/Generation/Apply/Owner/Backup closure. No package outside upgradelifecycle can invoke state persistence from caller-assembled inputs.

func NewVerifiedExecutorStateCapture 

func NewVerifiedExecutorStateCapture(input CurrentStateAuthorityInput) (VerifiedExecutorStateCapture, error)

NewVerifiedExecutorStateCapture is the production authority constructor for one immutable current-state recovery closure. It performs no persistence.

func NewVerifiedLegacyExecutorStateCapture 

func NewVerifiedLegacyExecutorStateCapture(
	input LegacyCurrentStateAuthorityInput,
) (VerifiedExecutorStateCapture, error)

NewVerifiedLegacyExecutorStateCapture is the only cross-release constructor. It does not run the current CUE contract: the attested historical binary already supplied the exact PlanInspection and offline Verify proof. Everything that survives into rollback remains independently content-, release-, Owner-, and snapshot-bound here.

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.