ownapplication

package
v0.57.11 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package ownapplication records node custody for Techstack-owned application intent. Catalog and own workloads share the native Compose executor.

Index

Constants

View Source
const (
	AdoptionResultVersion = "stackkit.own-application-adoption/v1"

	RowKept    = "kept"
	RowChanged = "changed"
	RowRefused = "refused"
)
View Source
const (
	CheckpointTaken     = "taken"
	CheckpointKept      = "kept"
	CheckpointRestoring = "restoring"
	CheckpointRetained  = "retained"
	CheckpointRestored  = "restored"
	CheckpointDiscarded = "discarded"
)

Checkpoint states (see DataCheckpoint).

View Source
const (
	UpdateReviewed       = "reviewed"
	UpdateUpdated        = "updated"
	UpdateRefused        = "refused"
	UpdateRolledBack     = "rolled_back"
	UpdateRollbackFailed = "rollback_failed"

	ReasonNotFound           = "application_not_found"
	ReasonProject            = "project_unsupported"
	ReasonPending            = "operation_pending"
	ReasonTagInvalid         = "tag_not_versioned"
	ReasonVariantChange      = "variant_change"
	ReasonVersionUnknown     = "current_version_unknown"
	ReasonNotNewer           = "not_newer"
	ReasonMajorChange        = "major_change"
	ReasonResolveFailed      = "resolve_failed"
	ReasonTagMoved           = "tag_moved"
	ReasonCheckpoint         = "checkpoint_failed"
	ReasonUpdateRefused      = "update_refused"
	ReasonUpdateFailed       = "update_failed"
	ReasonVerifyFailed       = "verify_failed"
	ReasonApprovalMissing    = "approval_missing"
	ReasonStopFailed         = "stop_failed"
	ReasonDataRestoreFailed  = "data_restore_failed"
	ReasonImageRollback      = "image_rollback_failed"
	ReasonRollbackVerify     = "rollback_verify_failed"
	ReasonCheckpointMissing  = "checkpoint_unavailable"
	ReasonCheckpointBlocks   = "checkpoint_unrestored"
	ReasonCheckpointSpace    = "checkpoint_space_insufficient"
	ReasonCheckpointInFlight = "checkpoint_in_flight"
	UpdateDiscarded          = "discarded"
)

Outcome and reason codes of a tag update and of a checkpoint rollback.

View Source
const ImageUpdateVersion = "stackkit.own-application-update/v1"

ImageUpdateVersion is the result of a tag update of one own application.

View Source
const TargetNotChecked = "not_checked_by_kombify"

TargetNotChecked is the only check state of a tag update target: kombify tests catalog releases, never the image of an own application.

Variables

View Source
var (
	UpdateStabilityWindow = 30 * time.Second
	UpdateHealthWindow    = 3 * time.Minute
	UpdateHealthPoll      = 5 * time.Second
	RollbackBudget        = 30 * time.Minute
)

UpdateStabilityWindow is how long an updated application must keep running before the update counts as verified; UpdateHealthWindow bounds the wait for an image healthcheck to report healthy; RollbackBudget bounds a rollback, which runs on its own context so a cancelled update still rolls back.

View Source
var ErrPending = errors.New("own application operation pending")

ErrPending marks a mutation whose runtime step failed after its signed write-ahead custody: its outcome is uncertain until status is inspected and a new reviewed operation reconciles it.

Functions

func AccessTable

func AccessTable(workspace string, base accessgatetable.Table) (accessgatetable.Table, error)

AccessTable extends only the server's already admitted table. Invalid or unsigned custody fails closed; names cannot replace an existing route.

func DiscardCommand

func DiscardCommand(name, operationID string) []string

RestoreCommand is the exact reviewed command sequence that restores the checkpoint of operationID and returns the application to its prior image. DiscardCommand is the exact reviewed command sequence that removes the retained copy of the checkpoint of operationID.

func ExtendBackupPolicy

func ExtendBackupPolicy(workspace string, p localbackuppolicy.Policy) (localbackuppolicy.Policy, error)

func Mutating

func Mutating(action string) bool

func RequireBackupCoverage

func RequireBackupCoverage(p localbackuppolicy.Policy) error

RequireBackupCoverage preserves the installation's existing coverage grant; own application data never silently widens a paid or owner-selected policy.

func RestoreCommand

func RestoreCommand(name, operationID string) []string

func ReviewedFirewall

func ReviewedFirewall(workspace, network string) (ownappfirewall.Receipt, error)

ReviewedFirewall returns the firewall receipt of the signed operation record that owns network, for the boot-time restore. Only a running firewalled application (outbound Internet, published ports, or both) whose last reviewed operation succeeded and applied its rules qualifies; a pending, stopped, transitioning or ambiguous record refuses. Those refusals are permanent: no retry in this boot changes the signed record, so the restore unit stops retrying until a reviewed operation enables it again.

func SuspendOutboundForKitRollback

func SuspendOutboundForKitRollback(ctx context.Context, workspace string) error

SuspendOutboundForKitRollback runs before restoring any old executor or checkpoint authority, for every firewalled application (outbound Internet, published ports, or both). It revokes the runtime grant without deleting volumes or changing the desired v2 document. Old readers refuse that version; a new reader requires a reviewed update to recreate and restart it. This applies conservatively to every kit recovery, without guessing a release threshold.

Types

type AdoptionCheckpoint

type AdoptionCheckpoint struct {
	APIVersion            string    `json:"apiVersion"`
	Name                  string    `json:"name"`
	ContainerID           string    `json:"containerId"`
	PlanDigest            string    `json:"planDigest"`
	OperationID           string    `json:"operationId"`
	OriginalRunning       bool      `json:"originalRunning"`
	OriginalRestartPolicy string    `json:"originalRestartPolicy"`
	DataSource            string    `json:"dataSource,omitempty"`
	DataVolume            string    `json:"dataVolume,omitempty"`
	DataDigest            string    `json:"dataDigest,omitempty"`
	Phase                 string    `json:"phase"`
	Error                 string    `json:"error,omitempty"`
	At                    time.Time `json:"at"`
	// RetainUntil ends the --restore-original window of an adopted original.
	RetainUntil time.Time `json:"retainUntil,omitzero"`
}

type AdoptionData

type AdoptionData struct {
	Source    string `json:"source"`
	MountPath string `json:"mountPath"`
	Volume    string `json:"volume"`
	Measured  bool   `json:"measured"`
	Files     int64  `json:"files,omitempty"`
	Bytes     int64  `json:"bytes,omitempty"`
	FreeBytes int64  `json:"freeBytes,omitempty"`
	Digest    string `json:"digest,omitempty"`
}

type AdoptionHooks

type AdoptionHooks struct {
	BeforeCreate  func(contract.Application) error
	AfterMutation func()
}

AdoptionHooks lets the command layer apply the checks and follow-ups every own-application mutation already runs.

type AdoptionRequest

type AdoptionRequest struct {
	Phase     string // inspect, plan, adopt, verify, restore-original or release-original
	Container string
	// SecretEnv marks further variable names as credentials. Every value is
	// already hidden; a marked name is also classified as a secret.
	SecretEnv     []string
	Name          string
	HTTPPort      int
	NoOutbound    bool
	MemoryMiB     int
	CPUs          float64
	PlanDigest    string
	OperationID   string
	OwnerApproved bool
	// HelperImage is the installed, digest-pinned backup helper that measures,
	// copies and checksums data. Empty only for an offline plan.
	HelperImage  string
	Installation contract.Installation
	// Offline plans against an explicit installation file: no node custody,
	// no secret commitment and no data measurement.
	Offline bool
}

AdoptionRequest selects one phase of one adoption.

type AdoptionResult

type AdoptionResult struct {
	APIVersion    string                `json:"apiVersion"`
	Phase         string                `json:"phase"`
	ContainerID   string                `json:"containerId"`
	ContainerName string                `json:"containerName"`
	Name          string                `json:"name,omitempty"`
	Admissible    bool                  `json:"admissible"`
	PlanDigest    string                `json:"planDigest,omitempty"`
	Rows          []AdoptionRow         `json:"rows"`
	Application   *contract.Application `json:"application,omitempty"`
	// HiddenKeys names every environment variable whose value moved into
	// secret custody (all non-empty values); SecretKeys the ones classified as
	// credentials by name or --secret-env. Values never appear.
	HiddenKeys []string `json:"hiddenKeys"`
	SecretKeys []string `json:"secretKeys"`
	// Outcome is the machine outcome a control plane notifies on: inspected,
	// planned, refused, adopted, rolled_back, rollback_failed, verified,
	// unhealthy, restored, released.
	Outcome string `json:"outcome"`
	// RetainUntil is the end of the window in which --restore-original
	// returns to the original; the original is never deleted automatically.
	RetainUntil      *time.Time               `json:"retainUntil,omitempty"`
	OutboundInternet bool                     `json:"outboundInternet"`
	PublishedPorts   []contract.PublishedPort `json:"publishedPorts"`
	Data             *AdoptionData            `json:"data,omitempty"`
	// DowntimeSeconds estimates the downtime of the recreation (stop, copy,
	// start); the stability window follows it with the application running.
	DowntimeSeconds int64               `json:"downtimeSeconds,omitempty"`
	ReviewDigest    string              `json:"reviewDigest,omitempty"`
	Checkpoint      *AdoptionCheckpoint `json:"checkpoint,omitempty"`
	OwnApplication  *Result             `json:"ownApplication,omitempty"`
	OriginalState   string              `json:"originalState,omitempty"`
	PortProbes      map[string]string   `json:"portProbes,omitempty"`
	Notice          string              `json:"notice"`
}

func Adopt

func Adopt(ctx context.Context, workspace string, req AdoptionRequest, hooks AdoptionHooks) (AdoptionResult, error)

Adopt runs one phase of a container adoption.

type AdoptionRow

type AdoptionRow struct {
	// Code is the stable machine code of the row (docs/APPLICATION_ADOPTION.md
	// "Plan row codes"); Values carries its structured facts. Reason is the
	// English explanation of the same row.
	Code     string            `json:"code"`
	Values   map[string]string `json:"values,omitempty"`
	Field    string            `json:"field"`
	Status   string            `json:"status"`
	Observed string            `json:"observed,omitempty"`
	Adopted  string            `json:"adopted,omitempty"`
	Reason   string            `json:"reason,omitempty"`
	// contains filtered or unexported fields
}

AdoptionRow is one observed setting and what the adopted application does with it.

type CheckpointVolume

type CheckpointVolume struct {
	LiveName     string `json:"liveName"`
	RollbackName string `json:"rollbackName"`
	Files        int64  `json:"files"`
	Bytes        int64  `json:"bytes"`
	Digest       string `json:"digest"`
}

type DataCheckpoint

type DataCheckpoint struct {
	State         string             `json:"state"`
	OperationID   string             `json:"operationId"`
	Image         string             `json:"image"`
	ResolvedImage string             `json:"resolvedImage"`
	HelperImage   string             `json:"helperImage"`
	PlanHash      string             `json:"planHash"`
	Volumes       []CheckpointVolume `json:"volumes"`
	At            time.Time          `json:"at"`
}

DataCheckpoint is the application-scoped data checkpoint of one tag update: a retained, operation-bound copy of every named volume of the application, taken while it was stopped and read back as a file-tree digest. It lives in the signed own-application record, so only the operation that took it can restore it. State records whether the copy is still the only intact data:

  • taken: the update that took it has not finished verifying;
  • kept: a rollback did not restore it; the live data may be half restored and the copy is the only intact data;
  • retained: the update verified (or never ran); live data is good;
  • restoring: a rollback is copying it back into the live volumes;
  • restored: the rollback copied it back and read the live data back;
  • discarded: the owner removed the copy.

While a checkpoint is taken, restoring or kept no new tag update runs, and a new checkpoint removes an earlier copy only after it read back and only when the earlier one is retained, restored or discarded.

type ImageUpdateCheckpoint

type ImageUpdateCheckpoint struct {
	OperationID string   `json:"operationId"`
	Volumes     []string `json:"volumes"`
	// State is planned (dry run) or the recorded checkpoint state: taken,
	// restoring, retained (update verified; the copy stays until discarded or replaced by
	// the next checkpoint), restored, kept (a rollback did not restore it; the
	// copy is the only intact data and blocks new updates) or discarded.
	State string `json:"state"`
	// RetainedBytes is the size of the retained copy on the node.
	RetainedBytes  int64    `json:"retainedBytes,omitempty"`
	RestoreCommand []string `json:"restoreCommand,omitempty"`
	DiscardCommand []string `json:"discardCommand,omitempty"`
}

ImageUpdateCheckpoint reports the application-scoped data checkpoint.

type ImageUpdateImage

type ImageUpdateImage struct {
	Image    string `json:"image"`
	Version  string `json:"version,omitempty"`
	Resolved string `json:"resolvedImage,omitempty"`
}

type ImageUpdateRequest

type ImageUpdateRequest struct {
	Name          string
	Tag           string
	AllowMajor    bool
	DryRun        bool
	ResolvedImage string
	OperationID   string
	ReviewDigest  string
	OwnerApproved bool
	HelperImage   string
	PlanHash      string
}

ImageUpdateRequest updates a one-container own application to a newer tag of its own image repository. The dry run resolves the tag to its registry digest and returns the review digest; the execution names both again. HelperImage (the installed digest-pinned backup helper) and PlanHash (the applied plan) bind the data checkpoint of an application with a volume.

type ImageUpdateResult

type ImageUpdateResult struct {
	APIVersion   string                 `json:"apiVersion"`
	Name         string                 `json:"name"`
	Outcome      string                 `json:"outcome"`
	Reason       string                 `json:"reasonCode,omitempty"`
	Message      string                 `json:"message,omitempty"`
	TargetCheck  string                 `json:"targetCheck"`
	AllowMajor   bool                   `json:"allowMajor"`
	Prior        ImageUpdateImage       `json:"prior"`
	Target       ImageUpdateImage       `json:"target"`
	ReviewDigest string                 `json:"reviewDigest,omitempty"`
	OperationID  string                 `json:"operationId,omitempty"`
	Checkpoint   *ImageUpdateCheckpoint `json:"checkpoint,omitempty"`
	// ReplacesCheckpoint is the retained copy a tag update's dry run will
	// replace once its own checkpoint reads back: its state and size.
	ReplacesCheckpoint *ImageUpdateCheckpoint `json:"replacesCheckpoint,omitempty"`
	Update             *Result                `json:"update,omitempty"`
	Rollback           *Result                `json:"rollback,omitempty"`
}

ImageUpdateResult carries the outcome code (reviewed, updated, refused, rolled_back, rollback_failed) and the reason code of every other outcome. rolled_back means both the prior image and the checkpoint data are back.

func DiscardCheckpoint

func DiscardCheckpoint(ctx context.Context, workspace string, req Request) (ImageUpdateResult, error)

DiscardCheckpoint is the owner's explicit decision to remove the retained copy of a checkpoint, also one a failed rollback kept: the live data then stays as it is. The dry run returns the review digest; the execution names it.

func RollbackWithCheckpoint

func RollbackWithCheckpoint(ctx context.Context, workspace string, installation contract.Installation, req Request) (ImageUpdateResult, error)

RollbackWithCheckpoint is the reviewed manual form of the automatic rollback: it restores the data checkpoint that operation took and returns the application to the prior image recorded with it. The dry run returns the review digest; the execution names it.

func UpdateImage

func UpdateImage(ctx context.Context, workspace string, installation contract.Installation, req ImageUpdateRequest) (ImageUpdateResult, error)

UpdateImage reviews or runs a tag update: the same repository, a newer version with the same major (unless AllowMajor) and the same variant suffix. The execution re-resolves the tag and refuses a moved tag before anything stops, stops the application and takes the application-scoped data checkpoint, runs the reviewed own-application update and verifies it. Any failure stops the application, restores the checkpoint data, rolls back to the prior image and verifies again.

type Operation

type Operation struct {
	Firewall       *ownappfirewall.Receipt `json:"firewall,omitempty"`
	FirewallAction string                  `json:"firewallAction,omitempty"`
	ID             string                  `json:"id"`
	Action         string                  `json:"action"`
	RequestDigest  string                  `json:"requestDigest"`
	ReviewDigest   string                  `json:"reviewDigest"`
	Status         string                  `json:"status"`
	At             time.Time               `json:"at"`
}

type Record

type Record struct {
	TransitionFrom        *contract.Bundle `json:"transitionFrom,omitempty"`
	SecretsKept           bool             `json:"secretsKept,omitempty"`
	Generation            string           `json:"generation"`
	Bundle                contract.Bundle  `json:"bundle"`
	PreviousImage         string           `json:"previousImage,omitempty"`
	PreviousResolvedImage string           `json:"previousResolvedImage,omitempty"`
	// PreviousImages and PreviousResolvedImages carry the rollback custody of a
	// project, keyed by service name.
	PreviousImages         map[string]string `json:"previousImages,omitempty"`
	PreviousResolvedImages map[string]string `json:"previousResolvedImages,omitempty"`
	State                  string            `json:"state"`
	// Checkpoint is the data checkpoint of the latest tag update; its retained
	// copies stay until a later checkpoint or a data-deleting removal.
	Checkpoint *DataCheckpoint `json:"checkpoint,omitempty"`
	Revision   string          `json:"revision"`
	Operation  Operation       `json:"operation"`
}

type Request

type Request struct {
	Action           string                `json:"action"`
	Name             string                `json:"name"`
	Application      *contract.Application `json:"application,omitempty"`
	KeepSecrets      bool                  `json:"keepSecrets,omitempty"`
	ResolvedImage    string                `json:"resolvedImage,omitempty"`
	ResolvedImages   map[string]string     `json:"resolvedImages,omitempty"`
	SecretMaterial   map[string]string     `json:"-"`
	SecretCommitment string                `json:"secretCommitment,omitempty"`
	DeleteData       bool                  `json:"deleteData,omitempty"`
	OperationID      string                `json:"operationId,omitempty"`
	ReviewDigest     string                `json:"reviewDigest,omitempty"`
	DryRun           bool                  `json:"dryRun,omitempty"`
	OwnerApproved    bool                  `json:"-"`
	// ImageTag and AllowMajor name a tag update (UpdateImage); Checkpoint names
	// the data checkpoint a rollback restores (RollbackWithCheckpoint). Each is
	// part of the request and so of the review digest.
	ImageTag   string `json:"imageTag,omitempty"`
	AllowMajor bool   `json:"allowMajor,omitempty"`
	Checkpoint string `json:"checkpoint,omitempty"`
}

type Result

type Result struct {
	FirewallRulesetDigest string                 `json:"firewallRulesetDigest,omitempty"`
	FirewallPolicyDigest  string                 `json:"firewallPolicyDigest,omitempty"`
	APIVersion            string                 `json:"apiVersion"`
	NetworkNotice         string                 `json:"networkNotice"`
	Action                string                 `json:"action"`
	DryRun                bool                   `json:"dryRun"`
	ReviewDigest          string                 `json:"reviewDigest,omitempty"`
	Record                Record                 `json:"record"`
	Compose               string                 `json:"compose,omitempty"`
	Route                 *accessgatetable.Route `json:"route,omitempty"`
	BackupVolumes         []string               `json:"backupVolumes"`
	Observation           json.RawMessage        `json:"observation,omitempty"`
	ObservationError      string                 `json:"observationError,omitempty"`
	// Outcome is the stable outcome code of this call: reviewed (dry run or
	// render), observed or observation_unavailable (status, logs), and for an
	// executed mutation created, updated, rolled_back, started, stopped,
	// restarted or removed. A refused, pending or denied call carries that
	// outcome with a stable reasonCode and the message in reason (OutcomeFor).
	Outcome    string `json:"outcome,omitempty"`
	ReasonCode string `json:"reasonCode,omitempty"`
	Reason     string `json:"reason,omitempty"`
}

func Execute

func Execute(ctx context.Context, workspace string, installation contract.Installation, req Request) (Result, error)

func OutcomeFor

func OutcomeFor(action, code string, err error) Result

OutcomeFor is the result a failed call reports: pending (reasonCode operation_pending) when signed custody already records the mutation as started, refused with the given reason code when nothing changed.

type State

type State struct {
	APIVersion   string                                        `json:"apiVersion"`
	Applications map[string]Record                             `json:"applications"`
	Signature    localevidence.OwnerLifecycleMutationSignature `json:"signature"`
}

func Load

func Load(workspace string) (State, error)

Jump to

Keyboard shortcuts

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