operate

package
v0.2.11 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package operate changes and waits on a PtahSchema or a PtahMigration the way kubectl ptah suspend, resume, refresh, set-source and wait do.

Every change is a JSON patch that first tests metadata.uid, so a resource deleted and created again under the same name between the read and the write is refused rather than changed. A change touches one field and nothing else, and is sent under the field manager kubectl-ptah. A change of source also carries the resourceVersion it read (SetSource says why).

Suspension prevents new Jobs and never cancels SQL that has started. An Apply already running is observed to its end; any proof still owed after an Apply waits for resume; a read under way, a migration's read of its history after a run included, is dropped. SuspendResult.Effect says which applies. A read request asks for a fresh read of the database; it starts no mutating operation and authorizes nothing.

A wait reads the resource until it reaches a target, and never counts state that was already there when the wait began: each target compares what it reads with a baseline document, using the timestamps the operator wrote rather than the clock of the process that waits.

Index

Constants

View Source
const DefaultInterval = 2 * time.Second

DefaultInterval is how often a wait reads the resource when the options name no interval.

View Source
const FieldManager = "kubectl-ptah"

FieldManager is the field manager every change is sent under.

Variables

View Source
var ErrReplaced = errors.New("the resource was deleted and created again under the same name")

ErrReplaced reports that the resource first read is not the one under its name now: it was deleted and created again. A change that returns it changed nothing, and a wait that returns it stopped reading.

Functions

func NextReadRequest

func NextReadRequest(now time.Time, current, answered string) string

NextReadRequest is the read request value Refresh writes at now: now in UTC, moved one nanosecond past current and answered whenever either is an RFC 3339 instant not earlier than now.

func ReadEndsIn

func ReadEndsIn(family Family, phase string) bool

ReadEndsIn reports whether a read cycle of family can end in phase: the phases in which the controller answers a pending read request and brings the next read forward, rather than leaving the request for a read that has not finished (internal/controller/read_request.go), plus Failed, where a failed cycle stops, and Suspended.

For a schema that is InSync, AwaitingApproval, ReadyToApply, Blocked, Failed and Suspended. Verifying, Observing, Planning and VerifyingConvergence are a cycle part way through; Pending, Resolving and Applying are work about to start or in flight.

For a migration it is InSync, AwaitingApproval, Planning, Blocked, Failed and Suspended. Planning ends a read only once its plan is published, which a document has to show as well (see snapshot.resting).

func Retryable

func Retryable(err error) bool

Retryable reports a failed read the API server may answer next time: a transport failure, a timeout, throttling or a server error. A kind the server does not serve, or one this client cannot encode, is not: the CRD is not installed, and waiting does not install it. Nor is a refusal, such as RBAC's. Wait retries what it reports until its timeout, and so does kubectl ptah approve while it waits for the approval gate.

Types

type Answer

type Answer string

Answer is what an error SetSuspend, Refresh or SetSource returned says about the change.

const (
	// NotRead is a resource that could not be read. Nothing was sent.
	NotRead Answer = "NotRead"
	// Absent is a resource that is not there, before the change was sent or
	// when it arrived. Nothing was changed.
	Absent Answer = "Absent"
	// Replaced is ErrReplaced: the resource under the name is another one
	// than the one read. Nothing was changed.
	Replaced Answer = "Replaced"
	// Forbidden is RBAC refusing the change to the identity that sent it.
	// Nothing was changed.
	Forbidden Answer = "Forbidden"
	// Refused is any other definite refusal of the change: admission, the
	// API schema, a credential the API server did not accept, or a request
	// it was too busy to take. Nothing was changed.
	Refused Answer = "Refused"
	// Unknown is a change that was sent and that no answer settled: a
	// timeout, a server error or a lost connection. It may have been
	// stored.
	Unknown Answer = "Unknown"
)

func Classify

func Classify(err error) Answer

Classify reads an error SetSuspend, Refresh or SetSource returned. It reads the API server's refusal the way kubectl ptah approve does (internal/apirefusal), so a person refused by RBAC is told so in the same terms by every command that writes.

type ApplyRunningError

type ApplyRunningError struct {
	Ref Ref
	Job string
}

ApplyRunningError is a resource with an Apply in flight whose Job may exist, by the rule the controller decides it with (mutationlifecycle.MayHaveDispatched). SetSource does not change its source.

A spec change moves the generation, which is one of the inputs an Apply claim was decided from. The operator drops a claim whose Job it has not created, and records one whose Job may exist as an outcome nobody established, without reading the result. For a migration that is a run nobody accounted for, and a reading clears that record only once nothing of the artifact is left to apply: with a new artifact's versions pending, it takes a person's acknowledgment. The Apply cannot take the new reference anyway; changing the source after it ends costs nothing.

func (*ApplyRunningError) Error

func (e *ApplyRunningError) Error() string

type Clock

type Clock interface {
	Now() time.Time
	After(d time.Duration) <-chan time.Time
}

Clock is the time a wait measures its timeout by and sleeps on. It decides nothing else: every comparison between two events uses the timestamps the operator wrote.

type Decision added in v0.2.10

type Decision struct {
	PlanName     string
	PlanUID      types.UID
	ApprovalName string
	ApprovalUID  types.UID
}

Decision is one approval of one plan, as a person reviewed it and admission stored it.

type Effect

type Effect string

Effect is what a suspension does to the work a resource has in flight, as the controller treats it once it sees spec.suspend: reconcileActive and reconcilePendingObservation, and the Authorize step that drops a claim before its Job is created, in each family (internal/controller).

const (
	// EffectNothing is a resource with nothing in flight and no proof owed.
	// No Job starts.
	EffectNothing Effect = "Nothing"
	// EffectApplyRuns is an Apply whose Job may exist. It runs to its end.
	// The suspension moves the generation the Apply was decided from, so the
	// operator records its outcome as unknown without reading its result: a
	// schema records no applied plan and owes a proof that waits for resume
	// and for the Apply's execution deadline, and keeps its database lock
	// until that proof ends; a migration records a run nobody accounted for.
	EffectApplyRuns Effect = "ApplyRuns"
	// EffectApplyDropped is an Apply claim whose Job was not created. The
	// operator drops it, and no SQL runs.
	EffectApplyDropped Effect = "ApplyDropped"
	// EffectReadDropped is a read of the source or of the database. The
	// operator drops the claim; a Job it started stops at its own deadline.
	EffectReadDropped Effect = "ReadDropped"
	// EffectReadBackDropped is a migration's read of its history after a
	// run. The operator drops it, and reads the history again after resume.
	EffectReadBackDropped Effect = "ReadBackDropped"
	// EffectProofWaits is a schema that owes the proof of an Apply and runs
	// no proof Job: a proof claim whose Job was not created is dropped, and
	// none starts until resume. The schema keeps its database lock until the
	// proof ends.
	EffectProofWaits Effect = "ProofWaits"
	// EffectProofObserveRuns is the Observe of a schema's proof, running. It
	// runs to its end, and the Plan that completes the proof waits for
	// resume.
	EffectProofObserveRuns Effect = "ProofObserveRuns"
	// EffectProofPlanRuns is the Plan that completes a schema's proof,
	// running. It runs to its end.
	EffectProofPlanRuns Effect = "ProofPlanRuns"
)

type Family

type Family string

Family is the resource family a command acts on.

const (
	// FamilySchema is a PtahSchema.
	FamilySchema Family = "schema"
	// FamilyMigration is a PtahMigration.
	FamilyMigration Family = "migration"
)

func ParseFamily

func ParseFamily(value string) (Family, error)

ParseFamily reads the family a command line names: schema or migration, or the kind's resource name, plural or short name as kubectl spells them.

type NoSettleValueError added in v0.2.11

type NoSettleValueError struct {
	Ref Ref
	// Problem says what the message prints instead.
	Problem string
	// contains filtered or unexported fields
}

NoSettleValueError is a stop whose condition prints no value Settle can read. Settle sends nothing: a value it worked out itself would not be one the stop printed, and the controller takes no other.

func (*NoSettleValueError) Error added in v0.2.11

func (e *NoSettleValueError) Error() string

func (*NoSettleValueError) Unwrap added in v0.2.11

func (e *NoSettleValueError) Unwrap() error

Unwrap is the refusal, so Classify reads the change as refused.

type NotPinnedError

type NotPinnedError struct {
	Value string
	// Tag is the tag the value names in place of a digest, when it names
	// one: a value ptah oci resolve can turn into a pinned reference.
	Tag     string
	Problem string
}

NotPinnedError is a value ParsePinnedReference refuses.

func (*NotPinnedError) Error

func (e *NotPinnedError) Error() string

type NotStoppedError added in v0.2.11

type NotStoppedError struct {
	Ref   Ref
	Phase string
	// Why says what the resource shows instead.
	Why string
	// contains filtered or unexported fields
}

NotStoppedError is a PtahSchema that has not stopped on a proof whose target moved, so a statement would settle nothing. Settle sends nothing.

func (*NotStoppedError) Error added in v0.2.11

func (e *NotStoppedError) Error() string

func (*NotStoppedError) Unwrap added in v0.2.11

func (e *NotStoppedError) Unwrap() error

Unwrap is the refusal, so Classify reads the change as refused.

type PinnedReference

type PinnedReference struct {
	// Reference is the reference as given.
	Reference string
	// Digest is the digest it selects, sha256:<64 lowercase hex>.
	Digest string
}

PinnedReference is an OCI reference that selects one manifest by its SHA-256 digest.

func ParsePinnedReference

func ParsePinnedReference(value string) (PinnedReference, error)

ParsePinnedReference reads an OCI reference that names its artifact by digest alone, as oci://HOST/REPOSITORY@sha256:<64 hex>.

It parses the value the way the operator does (internal/ocireference), which is stricter than the CRD's pattern, so a value it accepts is one the operator resolves. A tag is refused even beside a digest: the operator's parser drops such a tag unread, and a stored tag nothing checks would tell a reader of the spec which release runs without anything holding it true.

Beside a digest that parser drops everything from the first ":" to the "@" without reading it, so what sits there is named for what it is: a tag, or a repository path that is not one, such as another reference pasted after the registry. A scheme there is named even where the parser refuses the value, since its own message would call it a tag.

type Ref

type Ref struct {
	Family    Family
	Namespace string
	Name      string
}

Ref names one resource.

func ParseRef

func ParseRef(value, namespace string) (Ref, error)

ParseRef reads a family/name argument, such as schema/storefront, in namespace.

func (Ref) Kind

func (r Ref) Kind() string

Kind is the Kubernetes kind the family stands for.

func (Ref) String

func (r Ref) String() string

String is the resource as kubectl names it: ptahschema/storefront in namespace demo.

type RefreshResult

type RefreshResult struct {
	Ref Ref
	// Request is the annotation value written. A wait for the read it asks
	// for names it.
	Request string
	// Previous is the value the annotation held before, empty when none.
	Previous string
	UID      types.UID
	// Suspended reports spec.suspend: a suspended resource reads nothing, and
	// the request is answered after it is resumed.
	Suspended bool
	// Object is the resource as the answer carried it, the baseline a wait
	// for this request starts from.
	Object client.Object
}

RefreshResult is the read request Refresh wrote.

func Refresh

func Refresh(ctx context.Context, c client.Client, ref Ref, now time.Time) (RefreshResult, error)

Refresh asks the resource for a fresh read of its database by setting the operator.ptah.run/read-requested-at annotation, and changes nothing else.

The value is now in RFC 3339 with nanoseconds, in UTC, moved past the annotation's current value and past the request status last answered when either is not earlier. Two calls within one instant therefore write two requests, and a value status already records as answered is never written again: the controller would take it as no request at all.

The controller answers the request when no operation is running, the resource is not suspended and no retry delay is pending, and not while its engine is unsupported or its database realm does not admit it: those checks come before the request. A read-only operation that failed gives way to the request when its retry delay ends. A read that was already running when the request arrived does not answer it. That the annotation was written says nothing about whether the read completed; Wait with TargetRead does.

type Result

type Result struct {
	Ref                Ref
	Target             Target
	Phase              string
	Generation         int64
	ObservedGeneration int64
	// ObservedAt is when the database was last read, as the document says.
	ObservedAt time.Time
	// Reads is how many times the resource was read.
	Reads  int
	Object client.Object
	// Run is the run a wait narrowed to a plan ended on, which a later run may
	// have replaced in Object's status.lastRun. It is nil for any other wait.
	Run *RunReached
}

Result is the document that met the target.

func Wait

func Wait(ctx context.Context, reader client.Reader, ref Ref, options WaitOptions) (Result, error)

Wait reads the resource until it reaches options.Target, the timeout passes, or the resource records an outcome the target cannot follow.

It returns a *StopError for such an outcome or a resource being deleted or deleted since the baseline, a *TimeoutError on timeout, ErrReplaced when the name comes to hold another resource, and the API server's error for a resource that was not there to begin with, a kind the server does not serve, or a read it refuses. A failed read the server may answer next time is retried until the timeout.

The operator's timestamps are compared with each other for equality and are not ordered, since different managers' clocks write them (freshness). Status timestamps carry whole seconds, so a reading stamped in the same second as the one before it carries the same stamp and does not count as recorded since. That can only make a wait last longer, never end it early. One manager does not record two readings within one second, since a read cycle runs several Jobs, but another manager's clock can stamp a later reading with the second of an earlier one.

type RunReached added in v0.2.10

type RunReached struct {
	Outcome operatorv1alpha1.MigrationRunOutcome
	JobName string
	// Replaced reports that a later run has taken its place in status.lastRun,
	// and that only the journal still names it.
	Replaced bool
}

RunReached is a migration run that met a wait for its plan.

type SettleOptions added in v0.2.11

type SettleOptions struct {
	// Expect is the value the person read from the stop. When it is set, Settle
	// writes that value or nothing: a stop that prints another one is refused
	// with *UnexpectedSettleValueError. Without it, Settle settles the stop it
	// reads, whichever target that stop names.
	Expect string
}

SettleOptions narrows a settlement.

type SettleResult added in v0.2.11

type SettleResult struct {
	Ref Ref
	// Printed is the value the stop prints. The annotation holds it now.
	Printed SettleValue
	// PlanTarget is the digest of the target the Apply's plan was made for.
	PlanTarget string
	// Plan is the plan the Apply ran, and Approval the approval it consumed,
	// empty when none is recorded.
	Plan     string
	Approval string
	// Outcome is how the Apply ended, as status.pendingObservation records it.
	Outcome operatorv1alpha1.PendingObservationOutcome
	// Journal is the journal's ApplyFinished entry for that Apply, nil when the
	// journal holds none for its plan.
	Journal *operatorv1alpha1.JournalEntry
	// Previous is the value the annotation held before, and Held whether it held
	// one at all.
	Previous string
	Held     bool
	// Changed is false when the annotation already held the printed value and
	// nothing was sent.
	Changed bool
	// Apply is spec.policy.apply, which decides what the next plan may do.
	Apply operatorv1alpha1.ApplyPolicy
	// RetryInterval is spec.execution.failureRetryInterval, the pace of the reads
	// that take the statement.
	RetryInterval time.Duration
	// Suspended reports spec.suspend: a suspended resource starts no read, so the
	// statement is taken after it is resumed, or by a read already under way.
	Suspended bool
	Phase     string
	// ReadyReason is the reason of the Ready condition. Ready alone reports a Pod
	// that cannot start while the stop's condition keeps its command.
	ReadyReason string
	UID         types.UID
	// Object is the resource as the answer carried it, the baseline of a wait.
	Object client.Object
}

SettleResult is what Settle wrote and what the API server answered.

func Settle added in v0.2.11

func Settle(ctx context.Context, c client.Client, ref Ref, options SettleOptions) (SettleResult, error)

Settle gives up the post-Apply proof of the PtahSchema ref names, as a person does by running the command its stop prints: it sets the settled-apply annotation to the value the stop's condition prints and changes nothing else. The controller takes that statement at the next read of the target the value names, and then gives up the proof, its plan and its database lock and reads the database again under the URL the Secret holds.

It refuses a resource that has not stopped on a proof whose target moved (*NotStoppedError), a stop that prints no value it can read (*NoSettleValueError), and a printed value that names another Apply than the one whose proof is owed (*StaleSettleValueError), and, with options.Expect, a printed value other than the one expected (*UnexpectedSettleValueError). It sends nothing when the annotation already holds the value.

The patch tests metadata.uid and carries the resourceVersion of the read, as SetSource's does, since the value is decided from status: a read that named another target in between prints another value. A conflict is read again, and a stop that prints another value than the first read is refused rather than written, since the report describes the stop this command read. That binds the statement to this command's own read, not to whatever the person inspected before running it; options.Expect is what binds it to that. Anything else is decided again from the fresh read, three times at most.

type SettleValue added in v0.2.11

type SettleValue struct {
	// Value is what the settled-apply annotation has to hold.
	Value string
	// ApplyOperationID is the Apply whose proof it gives up.
	ApplyOperationID string
	// TargetDigest is the target the read named, the one the URL Secret holds.
	TargetDigest string
}

SettleValue is the value a stop prints and what it names.

func ParseSettleValue added in v0.2.11

func ParseSettleValue(value string) (SettleValue, error)

ParseSettleValue reads a settled-apply value a person gives, as a stop prints it: the Apply's operation ID, a slash, and the digest of a target.

func PrintedSettleValue added in v0.2.11

func PrintedSettleValue(message, name, namespace string) (SettleValue, error)

PrintedSettleValue reads the value a stop's message prints for the PtahSchema name names in namespace. The message has to end with the command the stop prints, as it prints it, for that resource and nothing else: a message cut short, a command for another resource, or words after it print no value a person could run.

type Source

type Source struct {
	// Field is where the spec names it: spec.desired for a schema,
	// spec.artifact for a migration.
	Field string
	Kind  SourceKind
	// Reference is the OCI reference the spec asks for, empty for another
	// kind.
	Reference string
	// Spec is the source as the spec holds it.
	Spec operatorv1alpha1.SourceSpec
	// Apply is spec.policy.apply.
	Apply operatorv1alpha1.ApplyPolicy
	// Resolved and Digest are the artifact the operator last resolved an OCI
	// source to, empty when it has resolved none.
	Resolved string
	Digest   string
	// Verified reports that the verification policy accepted Digest.
	Verified bool
	// PlanDigest is the artifact a schema's current plan was computed from.
	// A migration's status names its plan without one; the plan of a cycle
	// is computed from the artifact that cycle resolved, which is Digest.
	PlanDigest string
}

Source is the source a resource's spec names, the settings that come with it, and what the operator last resolved it to.

func SourceOf

func SourceOf(object client.Object) (Source, error)

SourceOf reads the source of a PtahSchema or a PtahMigration.

type SourceChangedError

type SourceChangedError struct {
	Ref   Ref
	Field string
	// Was is the reference SetSource read.
	Was string
	// Now is the source the resource names now.
	Now Source
	// contains filtered or unexported fields
}

SourceChangedError is a source another writer changed between SetSource's read and its patch. SetSource does not replace it: the reference it would overwrite is one the person never saw.

func (*SourceChangedError) Error

func (e *SourceChangedError) Error() string

func (*SourceChangedError) Unwrap

func (e *SourceChangedError) Unwrap() error

Unwrap is the refusal, so Classify reads the change as refused: nothing was stored.

type SourceKind

type SourceKind string

SourceKind is the kind of source a resource's spec names.

const (
	// SourceOCI is an OCI artifact: spec.desired.ociRef of a schema,
	// spec.artifact.ociRef of a migration.
	SourceOCI SourceKind = "OCI"
	// SourceConfigMap is a ConfigMap in the resource's namespace.
	SourceConfigMap SourceKind = "ConfigMap"
	// SourceGit is one commit of a Git repository.
	SourceGit SourceKind = "Git"
	// SourceOther is a spec that names none of these, such as a kind of
	// source a newer API added.
	SourceOther SourceKind = "Other"
)

type SourceKindError

type SourceKindError struct {
	Ref   Ref
	Field string
	Kind  SourceKind
}

SourceKindError is a resource whose source is a ConfigMap or Git, which SetSource does not change: moving to an OCI artifact also takes a verification policy, which only the person editing the resource can name.

func (*SourceKindError) Error

func (e *SourceKindError) Error() string

type SourceResult

type SourceResult struct {
	Ref Ref
	// Reference is the pinned reference the spec now asks for.
	Reference string
	// Previous is the reference the spec asked for before the change; when
	// nothing was sent it is Reference.
	Previous string
	// Changed is false when the spec already asked for Reference and
	// nothing was sent, or nothing sent was stored.
	Changed bool
	// SetByAnother is a change another writer made first: the spec came to
	// ask for Reference between SetSource's read and its patch, which the
	// API server refused. Changed is false.
	SetByAnother       bool
	UID                types.UID
	Generation         int64
	ObservedGeneration int64
	Phase              string
	// Running is the operation in flight, if any. An Apply here is a claim
	// whose Job was not created: SetSource changes no source under an Apply
	// whose Job may exist, and the operator drops this one when it sees the
	// change, so its plan does not run.
	Running string
	// ProofOwed is a schema's post-Apply proof not yet taken. It outranks a
	// newer generation, so the new reference is resolved after it.
	ProofOwed bool
	// Unresolved is a migration with a run nobody accounted for. While the
	// record stands the migration publishes no plan.
	Unresolved bool
	// Suspended reports spec.suspend: a suspended resource starts no Job, so
	// nothing resolves the new reference until it is resumed.
	Suspended bool
	// Source is the source as the answer carried it.
	Source Source
	// Object is the resource as the answer carried it, a baseline for a
	// wait that follows.
	Object client.Object
}

SourceResult is what SetSource asked for and what the API server answered. Generation is the requested state, the one the operator has to observe; ObservedGeneration and Phase are what it had observed when the answer was written.

func SetSource

func SetSource(ctx context.Context, c client.Client, ref Ref, pinned PinnedReference) (SourceResult, error)

SetSource points the resource ref names at another OCI artifact: it sets spec.desired.ociRef of a schema or spec.artifact.ociRef of a migration to pinned and changes nothing else. The verification policy, the registry credential, the transport and the apply policy stay as they are, and the new artifact is held to them.

It sends nothing when the spec already asks for pinned. It refuses a resource whose source is a ConfigMap or Git (*SourceKindError) and one with an Apply in flight whose Job may exist (*ApplyRunningError).

The patch tests metadata.uid, as every change here does, and carries the resourceVersion of the read as well, which SetSuspend and Refresh do not. Both of those decide from nothing but the field they write, so another writer's change between the read and the patch takes nothing from them, and failing on the operator's own status writes would only make them retry. SetSource decides from the spec it read -- the kind of source and the reference it replaces -- and from status, where an Apply claim is, so its patch holds only while that document is still the stored one. A conflict is read again: another writer's reference, or another kind of source, is returned as *SourceChangedError rather than overwritten, a claimed Apply as *ApplyRunningError, and anything else is decided again from the fresh read, three times at most.

type StaleSettleValueError added in v0.2.11

type StaleSettleValueError struct {
	Ref     Ref
	Printed string
	// Why says what it no longer matches.
	Why string
	// contains filtered or unexported fields
}

StaleSettleValueError is a value the stop prints that no longer matches the resource: it names another Apply than the one whose proof is owed, or the target the plan was made for, or it is not the value Settle read before the API server refused its patch. Settle sends nothing, or nothing more.

func (*StaleSettleValueError) Error added in v0.2.11

func (e *StaleSettleValueError) Error() string

func (*StaleSettleValueError) Unwrap added in v0.2.11

func (e *StaleSettleValueError) Unwrap() error

Unwrap is the refusal, so Classify reads the change as refused.

type StopError

type StopError struct {
	Ref     Ref
	Target  Target
	Reason  StopReason
	Phase   string
	Message string
}

StopError is a wait that ended because the resource recorded an outcome that is not the target and will not become it.

func (*StopError) Error

func (e *StopError) Error() string

type StopReason

type StopReason string

StopReason is why a wait ended without reaching its target.

const (
	// StopProofEnded is a proof that ended without the statement: a read of the
	// target the plan was made for proved the Apply or found changes still to
	// make, or the proof settled under a newer generation, policy or execution
	// binding.
	StopProofEnded StopReason = "ProofEnded"
	// StopStatementWithdrawn is a settled-apply annotation that no longer holds
	// the value the wait is for while the proof is still owed: nothing settles it.
	StopStatementWithdrawn StopReason = "StatementWithdrawn"
)
const (
	// StopSourceChanged is a wait for the source SetSource wrote on a
	// resource whose spec now names another one.
	StopSourceChanged StopReason = "SourceChanged"
	// StopNothingPlanned is a wait for an approval of a plan from the new
	// reference on a resource that rests in sync from it: the operator read
	// the database after the change and found nothing to do, so no plan from
	// that change will wait.
	StopNothingPlanned StopReason = "NothingPlanned"
)
const (
	// StopReadReplaced is a read request another value replaced before the
	// operator took it.
	StopReadReplaced StopReason = "ReadRequestReplaced"
	// StopReadFailed is a read that failed after the operator took the
	// request, with no claim left to retry it: the operator starts another
	// read after its retry delay. An attempt the operator retries under the
	// same claim does not stop the wait; a timeout names its failure.
	StopReadFailed StopReason = "ReadFailed"
	// StopApplyFailed is an Apply or a run that failed, or an Apply whose
	// claim the operator gave up before it ran.
	StopApplyFailed StopReason = "ApplyFailed"
	// StopUnresolved is an Apply or a run whose effect on the database
	// nobody established.
	StopUnresolved StopReason = "OutcomeUnknown"
	// StopNotConverged is an Apply or a run the operator's reading of the
	// database afterwards did not confirm: a schema whose proof still found
	// changes or settled under newer inputs, a migration whose history read
	// back blocked.
	StopNotConverged StopReason = "NotConverged"
	// StopOtherPlanApplied is a resource that applied another plan than the
	// one the wait named.
	StopOtherPlanApplied StopReason = "OtherPlanApplied"
	// StopOtherApproval is a migration that ran the plan the wait named under
	// another approval than the one the wait named, or spent another approval of
	// it on a run, which leaves the one the wait named stale.
	StopOtherApproval StopReason = "OtherApprovalConsumed"
	// StopPlanSuperseded is a migration whose named plan will not run under the
	// approval the wait named: another plan took its place, a reading found
	// nothing left to apply, or the operator marked the approval stale.
	StopPlanSuperseded StopReason = "PlanSuperseded"
	// StopNotProved is a run that may be the one the wait named, or that was and
	// has no reading to show for it, with no record that says more: one that names
	// no plan, one that names this plan and not what allowed it or not the
	// fingerprint the wait named, one whose reading afterwards is no longer
	// recorded, one whose database moved before the next reading, or one that
	// applied and has no reading after it while a verification policy refuses the
	// artifact, which holds back every reading.
	StopNotProved StopReason = "CompletionNotProved"
	// StopNothingApplied is a migration run that found nothing to apply.
	StopNothingApplied StopReason = "NothingApplied"
	// StopNotSuspended is a wait for suspension on a resource whose spec
	// does not ask for it.
	StopNotSuspended StopReason = "NotSuspended"
	// StopPolicyBlocked is a resource whose current plan its own policy
	// holds: a schema plan that is destructive while
	// spec.policy.allowDestructive is false, or any plan of either family
	// under spec.policy.apply Never. No approval is asked for and no Apply
	// runs, and every later reading of the same database plans the same,
	// until the spec changes.
	StopPolicyBlocked StopReason = "PolicyBlocked"
	// StopPolicyRefused is a resource whose verification policy refused the
	// artifact it names now. No plan outlives the refusal, no approval does, and
	// the database is not read, until the operator reads an artifact the policy
	// accepts: at spec.interval, on a read request, or at once after a spec edit.
	// A wait for a migration run that has ended goes by the run's record instead,
	// and one that applied with no reading after it is StopNotProved. A wait for a
	// read stops on the refusal its own read ended in, and on no older one.
	StopPolicyRefused StopReason = "PolicyRefused"
	// StopDeleting is a resource that is being deleted.
	StopDeleting StopReason = "Deleting"
	// StopDeleted is a resource that was deleted while the wait read it.
	StopDeleted StopReason = "Deleted"
)

type SuspendResult

type SuspendResult struct {
	Ref Ref
	// Suspend is the value spec.suspend was asked to hold.
	Suspend bool
	// Changed is false when spec.suspend already held it and nothing was
	// sent.
	Changed bool
	UID     types.UID
	// Generation is the spec generation after the change.
	Generation         int64
	ObservedGeneration int64
	Phase              string
	// Running is the operation in flight, if any. Effect says what
	// suspension does to it: an Apply already running is observed to its
	// end, any proof still owed after an Apply waits for resume, and a read
	// under way is dropped.
	Running string
	// Object is the resource as the answer carried it, a baseline for a
	// wait that follows.
	Object client.Object
}

SuspendResult is what SetSuspend asked for and what the API server answered. Generation is the requested state, the one the controller has to observe; ObservedGeneration and Phase are what it had observed when the answer was written.

func SetSuspend

func SetSuspend(ctx context.Context, c client.Client, ref Ref, suspend bool) (SuspendResult, error)

SetSuspend sets spec.suspend on the resource ref names and nothing else. Suspending prevents new Jobs; it does not cancel an Apply already running, which the controller observes to its end before the resource reads Suspended, and SuspendResult.Effect says what it does to anything else in flight. Resuming lets the controller read the database again and decide from what it finds.

When spec.suspend already holds the value nothing is sent and Changed is false. Otherwise one JSON patch tests metadata.uid and adds spec.suspend, so a resource replaced under the name since it was read returns ErrReplaced and is not changed.

func (SuspendResult) Effect

func (r SuspendResult) Effect() Effect

Effect says what suspending the resource does to what it had in flight when the API server answered. A claim's Job may exist when the claim records a dispatch or a Job UID, the rule the controller decides it by (mutationlifecycle.MayHaveDispatched).

type Target

type Target string

Target is the state a wait is for.

const (
	// TargetRead is the end of the read a read request asked for: the request
	// answered, a read of the database that began after it, and nothing in
	// flight. A read that ends where the verification policy refuses the
	// artifact stops the wait with StopPolicyRefused.
	TargetRead Target = "read"
	// TargetInSync is a resource that rests in sync at the required
	// generation, by a read of the database that began after the baseline.
	TargetInSync Target = "in-sync"
	// TargetApproval is a resource waiting at the approval gate in the state
	// approval admission requires of its status. With a baseline, its plan has
	// to come from a read of the database that began after that baseline. With
	// none, the gate as the wait finds it counts. Admission also checks the plan
	// object and its bindings, which a wait does not read.
	TargetApproval Target = "approval"
	// TargetApplied is an Apply or a migration run that ended after the
	// baseline, recorded applied and settled by the operator's own reading of
	// the database. One that ended before it does not count even when its
	// proof or read-back ends after it. Any other ending of an Apply that
	// ended after the baseline stops the wait with a StopError. WaitOptions.Plan
	// and WaitOptions.Decision narrow it to one plan and one approval.
	TargetApplied Target = "applied"
	// TargetSuspended is a resource the controller reports Suspended at the
	// required generation, with nothing in flight: for a schema, its
	// Suspended condition at that generation. A schema whose post-Apply proof
	// is still owed reaches it with the proof owed: the proof waits for
	// resume, and no Job runs meanwhile.
	TargetSuspended Target = "suspended"
)
const TargetPlanned Target = "approval or in-sync"

TargetPlanned is the end of a change of source: a plan from the new reference waits for an approval, or the resource rests in sync from it, whichever the operator reaches. It is waited on only with WaitOptions.Source; a command line names approval or in-sync, and a Result names the one that was met.

const TargetSettled Target = "settled"

TargetSettled is the end of a settlement: the operator took the statement Settle wrote and gave the proof up, which the journal records as a Verified entry for the Apply's plan with outcome Unknown. It is waited on only with WaitOptions.Settlement and a baseline that still owes the proof, such as SettleResult.Object.

func ParseTarget

func ParseTarget(value string) (Target, error)

ParseTarget reads a target as a command line names it.

type TimeoutError

type TimeoutError struct {
	Ref    Ref
	Target Target
	Waited time.Duration
	// Phase is empty when the resource was never read.
	Phase string
	// Blocker is a copy of the condition that says what holds the resource:
	// a failure or refusal the operator recorded, or Ready when it is not
	// True.
	Blocker *metav1.Condition
	// Waiting is what the target still needed in the last document read.
	Waiting string
	// LastError is the error of the last read, when it failed and was
	// retried. A read the wait's own deadline cut short is not counted: the
	// deadline is the timeout this error reports, not news about the
	// resource. When no read answered at all, LastError says so.
	LastError error
	// ReadUnderWay reports that the last document read showed a read of the
	// database in flight. A wait for TargetInSync begun after it skips that
	// read's harvest, because it may have read the database before the wait
	// began; a read request is what asks for one that begins later.
	ReadUnderWay bool
}

TimeoutError is a wait whose timeout passed first. It names the phase the last read found, the condition that best says what holds the resource, and what the target still needed.

func (*TimeoutError) Error

func (e *TimeoutError) Error() string

type UnexpectedSettleValueError added in v0.2.11

type UnexpectedSettleValueError struct {
	Ref      Ref
	Printed  string
	Expected string
	// contains filtered or unexported fields
}

UnexpectedSettleValueError is a stop that prints another value than the one the person expected, as when the URL Secret moved again after they read the stop. Settle sends nothing: the statement is about one target, and the person read about another.

func (*UnexpectedSettleValueError) Error added in v0.2.11

func (*UnexpectedSettleValueError) Unwrap added in v0.2.11

func (e *UnexpectedSettleValueError) Unwrap() error

Unwrap is the refusal, so Classify reads the change as refused.

type WaitOptions

type WaitOptions struct {
	Target Target
	// Timeout bounds the wait. It is required.
	Timeout time.Duration
	// Interval is the time between reads; DefaultInterval when zero.
	Interval time.Duration
	// Clock is the real clock when nil. With the real clock each read also
	// carries the wait's deadline, so a read that hangs cannot outlive the
	// timeout.
	Clock Clock
	// Since is the baseline: the resource as it was before the change the
	// wait is about, such as SuspendResult.Object or RefreshResult.Object.
	// Nothing it already shows counts. When nil the wait's first read is the
	// baseline, which can miss a change that completes before it, except for
	// TargetApproval: a person who starts that wait asks whether a plan waits
	// for them, and a first read that shows one answers it.
	//
	// For TargetRead it has to have been read after the request was written,
	// and a document whose annotation does not hold ReadRequest is refused:
	// one read before lets a read that started in between count as the answer.
	Since client.Object
	// Generation is the least status.observedGeneration the target needs,
	// such as SuspendResult.Generation. When zero, TargetInSync,
	// TargetApproval and TargetSuspended need the baseline's generation, and
	// TargetRead and TargetApplied need none: a read request and an approval
	// leave the generation where it was.
	Generation int64
	// ReadRequest is the annotation value TargetRead waits on, as
	// RefreshResult.Request returned it. It is required for TargetRead and
	// refused for any other target.
	ReadRequest string
	// Plan narrows TargetApplied to the plan of that name or fingerprint.
	// Another plan applied first stops the wait.
	Plan string
	// Decision narrows TargetApplied, for a PtahMigration, to the run that carried
	// out one approval of one plan. The run has to name both, and a run that
	// names either differently, a plan that replaces this one, or a run that
	// names neither stops the wait: nothing else can say this plan completed.
	// The wait also reads that approval, by name and UID, and an approval the
	// operator marked stale stops it: nothing runs under one. A read of the
	// approval that the API server refuses, or that fails, leaves the wait to
	// the resource alone.
	Decision *Decision
	// Settlement is the value Settle wrote, which TargetSettled waits on. It
	// is required for TargetSettled and refused for any other target.
	Settlement string
	// Source narrows TargetInSync and TargetApproval to the OCI reference
	// SetSource wrote, pinned by digest. A document counts only while the
	// spec still asks for it, and only once the operator worked from it: a
	// schema waiting for approval with a plan computed from its digest, and
	// otherwise the artifact the operator resolved. A spec that names another
	// source stops the wait.
	Source string
}

WaitOptions says what a wait is for and how long it may take.

Jump to

Keyboard shortcuts

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