Documentation
¶
Overview ¶
Package migrationview reads what the operator stored about one migration.
It is the read side of the migration path: what the database's own history said when it was last read, which sequence the operator would run next, and what the last run did. It connects to no database and reads no Secret.
Beside the migration it lists the PtahMigrationApprovals and the PtahMigrationRunAcknowledgments that name it: the decisions people made about its plans and about a run nobody accounted for. Listing them takes a permission reading the migration does not, so a reader without it still gets the migration, and a line that says why the decisions are missing.
Index ¶
- Variables
- func Render(out io.Writer, view View, format Format) error
- type AcknowledgmentView
- type ApprovalView
- type ArtifactView
- type ConditionView
- type Details
- type Format
- type HistoryView
- type PlanView
- type PlannedMigrationView
- type PolicyView
- type ResolvedRunView
- type RunView
- type UnresolvedRunView
- type View
Constants ¶
This section is empty.
Variables ¶
var ErrMigrationNotFound = errors.New("no PtahMigration by that name")
ErrMigrationNotFound is returned when the named PtahMigration is not there. It is separate from a read failure: "there is nothing by that name" is an answer.
var Formats = []Format{Text, JSON}
Formats are the accepted values, in the order the help lists them.
Functions ¶
Types ¶
type AcknowledgmentView ¶ added in v0.2.9
type AcknowledgmentView struct {
Name string `json:"name"`
CreatedAt metav1.Time `json:"createdAt"`
OperationID string `json:"operationID"`
// NamesUnresolvedRun says the acknowledgment names the run the migration
// records as unresolved now. One that names any other run settles nothing.
NamesUnresolvedRun bool `json:"namesUnresolvedRun"`
AcknowledgedBy operatorv1alpha1.ApprovalIdentity `json:"acknowledgedBy"`
AcknowledgedAt metav1.Time `json:"acknowledgedAt"`
Conditions []ConditionView `json:"conditions,omitempty"`
}
AcknowledgmentView is one PtahMigrationRunAcknowledgment that names this migration: the run it settles, who made the statement, and whether the controller took it.
type ApprovalView ¶ added in v0.2.9
type ApprovalView = statusview.Approval
ApprovalView is one PtahMigrationApproval that names this migration. A migration approval carries only Consumed, or Stale when a read withdrew it; whether it matches the plan is what CurrentPlan and the migration's own ApprovalRequired say.
type ArtifactView ¶
type ArtifactView = sourceview.View
ArtifactView is the resolved, credential-free source binding: an OCI artifact, a ConfigMap and its snapshot, or a Git commit.
type ConditionView ¶
type ConditionView = statusview.Condition
ConditionView is one published condition: what it says, and when and for which generation it was written.
type Details ¶ added in v0.2.11
type Details struct {
// ReadRequested is the operator.ptah.run/read-requested-at annotation as
// the migration holds it now. status.lastReadRequest is the last value
// the controller answered.
ReadRequested string `json:"readRequested,omitempty"`
Status operatorv1alpha1.PtahMigrationStatus `json:"status"`
}
Details is what --details adds: the status, and the read request the resource holds now, which the status answers.
Status is decoded into the API types this plugin was built with, so it holds every field this plugin's API version knows; a field a newer operator added to the stored object is not in it. The text prints every record of Status the view does not already print in full; the JSON carries Status as decoded, so a script reads the fields the API reference of this version documents.
type HistoryView ¶
type HistoryView struct {
ObservedAt metav1.Time `json:"observedAt"`
CurrentVersion int64 `json:"currentVersion"`
CheckpointVersion int64 `json:"checkpointVersion,omitempty"`
AppliedCount int32 `json:"appliedCount"`
PendingCount int32 `json:"pendingCount"`
Dirty bool `json:"dirty,omitempty"`
ModifiedVersions []int64 `json:"modifiedVersions,omitempty"`
// OutOfOrderVersions names migrations that sort below the current version.
// Linear execution refuses them, so a reader of this view has to see which
// ones rather than a phase that says the history is blocked.
OutOfOrderVersions []int64 `json:"outOfOrderVersions,omitempty"`
Fingerprint string `json:"fingerprint,omitempty"`
}
HistoryView is what the revision table said when it was last read.
type PlanView ¶
type PlanView struct {
Name string `json:"name"`
UID string `json:"uid,omitempty"`
Fingerprint string `json:"fingerprint"`
CurrentVersion int64 `json:"currentVersion"`
CreatedAt metav1.Time `json:"createdAt"`
Migrations []PlannedMigrationView `json:"migrations"`
}
PlanView is the sequence the operator would run next. A migration plan holds versions and checksums rather than SQL: the statements live in the artifact, and printing them here would mean fetching it.
type PlannedMigrationView ¶
type PlannedMigrationView struct {
Version int64 `json:"version"`
VersionKey string `json:"versionKey,omitempty"`
Description string `json:"description,omitempty"`
Checksum string `json:"checksum"`
Checkpoint bool `json:"checkpoint,omitempty"`
TransactionMode string `json:"transactionMode,omitempty"`
}
PlannedMigrationView is one migration of the sequence.
type PolicyView ¶ added in v0.2.9
type PolicyView struct {
Apply string `json:"apply,omitempty"`
}
PolicyView is the spec's apply mode: whether a planned sequence runs never, with an approval, or as soon as it is planned.
type ResolvedRunView ¶ added in v0.2.9
type ResolvedRunView struct {
OperationID string `json:"operationID"`
Outcome string `json:"outcome"`
Resolution string `json:"resolution"`
AcknowledgmentName string `json:"acknowledgmentName,omitempty"`
AcknowledgedBy string `json:"acknowledgedBy,omitempty"`
ResolvedAt metav1.Time `json:"resolvedAt"`
}
ResolvedRunView is how the most recent unresolved run was settled: by a history read, or by a person's acknowledgment.
type RunView ¶
type RunView struct {
Outcome string `json:"outcome"`
JobName string `json:"jobName,omitempty"`
JobUID string `json:"jobUID,omitempty"`
StartedAt metav1.Time `json:"startedAt"`
FinishedAt *metav1.Time `json:"finishedAt,omitempty"`
AppliedVersions []int64 `json:"appliedVersions,omitempty"`
Message string `json:"message,omitempty"`
// Failure is where a failed or partial run stopped, when a statement
// reached the database and failed there.
Failure *operatorv1alpha1.MigrationRunFailureStatus `json:"failure,omitempty"`
// MigrationLog is what the run's writes to schema_migrations_log came to,
// where the run reported it.
MigrationLog *operatorv1alpha1.MigrationLogStatus `json:"migrationLog,omitempty"`
// OperationID, PlanRef, PlanFingerprint, Authorization, ArtifactDigest,
// Source, TargetIdentityDigest, ExecutionBindingID and Verification are what
// the run's record says it carried out, who allowed it and what the reading
// after it found. Each is absent where the record does not hold it, which is
// every one of them on a run a release before those fields recorded.
OperationID string `json:"operationID,omitempty"`
PlanRef *operatorv1alpha1.ImmutableObjectReference `json:"planRef,omitempty"`
PlanFingerprint string `json:"planFingerprint,omitempty"`
Authorization *operatorv1alpha1.MigrationRunAuthorizationStatus `json:"authorization,omitempty"`
ArtifactDigest string `json:"artifactDigest,omitempty"`
Source *operatorv1alpha1.PlanSourceBinding `json:"source,omitempty"`
TargetIdentityDigest string `json:"targetIdentityDigest,omitempty"`
ExecutionBindingID string `json:"executionBindingID,omitempty"`
Verification *operatorv1alpha1.MigrationRunVerificationStatus `json:"verification,omitempty"`
}
RunView is what the database accounted for after the last execution, and which Job that execution was. The Job's UID is what tells a replacement Job with the same name apart from the run it replaced.
type UnresolvedRunView ¶ added in v0.2.9
type UnresolvedRunView struct {
Outcome string `json:"outcome"`
OperationID string `json:"operationID"`
// JobName and JobUID are empty where the API server never confirmed the
// Job was created: the reserved name is not evidence that anything ran.
JobName string `json:"jobName,omitempty"`
JobUID string `json:"jobUID,omitempty"`
PlanRef operatorv1alpha1.ImmutableObjectReference `json:"planRef"`
// TargetIdentityDigest is the credential-free identity of the database
// the run's result named, or the one its plan was computed against where
// it named none.
TargetIdentityDigest string `json:"targetIdentityDigest,omitempty"`
RecordedAt metav1.Time `json:"recordedAt"`
}
UnresolvedRunView is the execution whose effect on the database nobody has established. While it is recorded nothing is planned and nothing runs.
type View ¶
type View struct {
Namespace string `json:"namespace"`
Migration string `json:"migration"`
UID string `json:"uid,omitempty"`
// Generation is the spec's, and ObservedGeneration the one the status
// was written for. They differ while the controller has not yet acted
// on a spec change.
Generation int64 `json:"generation,omitempty"`
ObservedGeneration int64 `json:"observedGeneration,omitempty"`
Phase string `json:"phase,omitempty"`
Suspended bool `json:"suspended,omitempty"`
Policy *PolicyView `json:"policy,omitempty"`
Artifact *ArtifactView `json:"artifact,omitempty"`
History *HistoryView `json:"history,omitempty"`
Plan *PlanView `json:"plan,omitempty"`
// LastRun is the most recent execution. UnresolvedRun is a different
// record: the execution nobody has accounted for, which holds the
// resource whatever the last run or the conditions say. ResolvedRun is
// how the most recent such record was settled.
LastRun *RunView `json:"lastRun,omitempty"`
UnresolvedRun *UnresolvedRunView `json:"unresolvedRun,omitempty"`
ResolvedRun *ResolvedRunView `json:"resolvedRun,omitempty"`
Conditions []ConditionView `json:"conditions,omitempty"`
// Approvals and Acknowledgments are the newest decisions that name this
// migration, by name and UID. Each is absent when it could not be listed,
// and then its Unreadable field says why: no list is not an empty list.
Approvals *statusview.Decisions[ApprovalView] `json:"approvals,omitempty"`
ApprovalsUnreadable *statusview.Unreadable `json:"approvalsUnreadable,omitempty"`
Acknowledgments *statusview.Decisions[AcknowledgmentView] `json:"acknowledgments,omitempty"`
AcknowledgmentsUnreadable *statusview.Unreadable `json:"acknowledgmentsUnreadable,omitempty"`
// Details is the status as this plugin's API version decodes it, present
// only when it was asked for, so the view without it reads as it always
// has.
Details *Details `json:"details,omitempty"`
}
View is everything this command prints, resolved before anything is written.
func Load ¶
Load reads one migration, the plan it names, and the decisions that name it.
A plan the migration no longer names is not shown: the status reference is what makes a stored plan the current one, and a plan read by name alone could be one the operator already discarded. A decision list that cannot be read leaves the rest of the view as it was.