Documentation
¶
Overview ¶
Package ownapplication records node custody for Techstack-owned application intent. Catalog and own workloads share the native Compose executor.
Index ¶
- Constants
- Variables
- func AccessTable(workspace string, base accessgatetable.Table) (accessgatetable.Table, error)
- func DiscardCommand(name, operationID string) []string
- func ExtendBackupPolicy(workspace string, p localbackuppolicy.Policy) (localbackuppolicy.Policy, error)
- func Mutating(action string) bool
- func RequireBackupCoverage(p localbackuppolicy.Policy) error
- func RestoreCommand(name, operationID string) []string
- func ReviewedFirewall(workspace, network string) (ownappfirewall.Receipt, error)
- func SuspendOutboundForKitRollback(ctx context.Context, workspace string) error
- type AdoptionCheckpoint
- type AdoptionData
- type AdoptionHooks
- type AdoptionRequest
- type AdoptionResult
- type AdoptionRow
- type CheckpointVolume
- type DataCheckpoint
- type ImageUpdateCheckpoint
- type ImageUpdateImage
- type ImageUpdateRequest
- type ImageUpdateResult
- func DiscardCheckpoint(ctx context.Context, workspace string, req Request) (ImageUpdateResult, error)
- func RollbackWithCheckpoint(ctx context.Context, workspace string, installation contract.Installation, ...) (ImageUpdateResult, error)
- func UpdateImage(ctx context.Context, workspace string, installation contract.Installation, ...) (ImageUpdateResult, error)
- type Operation
- type Record
- type Request
- type Result
- type State
Constants ¶
const ( AdoptionResultVersion = "stackkit.own-application-adoption/v1" RowKept = "kept" RowChanged = "changed" RowRefused = "refused" )
const ( CheckpointTaken = "taken" CheckpointKept = "kept" CheckpointRestoring = "restoring" CheckpointRetained = "retained" CheckpointRestored = "restored" CheckpointDiscarded = "discarded" )
Checkpoint states (see DataCheckpoint).
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.
const ImageUpdateVersion = "stackkit.own-application-update/v1"
ImageUpdateVersion is the result of a tag update of one own application.
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 ¶
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.
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 ¶
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 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 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 ¶
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 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 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 OutcomeFor ¶
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.