v1alpha1

package
v0.2.12 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package v1alpha1 contains the first public API for the Ptah operator. +kubebuilder:object:generate=true +groupName=operator.ptah.run

Index

Constants

View Source
const (
	HTTPSHostSecretKey     = "host"
	HTTPSUsernameSecretKey = "username"
	HTTPSPasswordSecretKey = "password"
	HTTPSTokenSecretKey    = "token"
	HTTPSCASHA256SecretKey = "caSHA256"
)

The fixed keys of an HTTPS credential Secret. HTTPSHostSecretKey is the authority, host[:port], the credential owner grants the credential for; HTTPSCASHA256SecretKey is the "sha256:" digest of the CA it may be sent under. Username and password authenticate with Basic, a token with Bearer; a Secret holds one or the other. A resource's author selects the Secret, never the keys.

View Source
const (
	// ConditionMigrationReady reports that the history matches the artifact and
	// nothing is pending.
	ConditionMigrationReady = "Ready"
	// ConditionMigrationProgressing reports work in flight.
	ConditionMigrationProgressing = "Progressing"
	// ConditionMigrationBlocked reports what stopped the resource: a history
	// this artifact cannot continue, which the controller never resolves by
	// writing to the database, a run nobody accounted for, an unsupported engine,
	// a realm that does not admit it, or an artifact its verification policy
	// refused. The reason says which.
	ConditionMigrationBlocked = "Blocked"
	// ConditionMigrationApprovalRequired reports a plan waiting for the exact
	// approval its policy requires.
	ConditionMigrationApprovalRequired = "ApprovalRequired"
	// ConditionMigrationDatabaseReachable reports whether the target answered
	// the last operation that opened it, and why it did not.
	ConditionMigrationDatabaseReachable = "DatabaseReachable"
	// ConditionMigrationRunLogged reports whether the database accepted every
	// entry the last run that reported on schema_migrations_log wrote there.
	// It stays as it is until the next run that reports, so a run that left no
	// report does not clear a record another run left incomplete.
	ConditionMigrationRunLogged = "RunLogged"
)

Condition types a PtahMigration publishes.

View Source
const (
	// ConditionAcknowledgmentConsumed reports that the acknowledgment settled
	// the unresolved run it names.
	ConditionAcknowledgmentConsumed = "Consumed"
	// ConditionAcknowledgmentStale reports an acknowledgment that names a run
	// the migration is not waiting on, so it settled nothing.
	ConditionAcknowledgmentStale = "Stale"
)

Condition types a PtahMigrationRunAcknowledgment publishes.

View Source
const (
	RegistryAuthEnvironment      RegistryAuthMode = "Environment"
	RegistryAuthDockerConfigJSON RegistryAuthMode = "DockerConfigJSON"

	// RegistryAuthoritySecretKey is the fixed Secret key by which a credential
	// owner grants the operator permission to use either supported credential
	// representation for one exact OCI registry authority. It is intentionally
	// not selectable by a PtahSchema author.
	RegistryAuthoritySecretKey = "registry"
	// RegistryAllowPlainHTTPSecretKey is the fixed Secret key by which a
	// credential owner explicitly permits that credential to cross an
	// unencrypted registry connection. Its value must be exactly "true".
	RegistryAllowPlainHTTPSecretKey = "allowPlainHTTP"
	// RegistryCASHA256SecretKey is the fixed Secret key by which the same
	// credential owner grants one exact custom CA bundle. Its value must be the
	// lowercase SHA-256 digest of the selected ConfigMap bytes, and an HTTPS
	// source that names the Secret and selects no CA is refused. It is
	// intentionally not selectable by a PtahSchema author.
	RegistryCASHA256SecretKey = "caSHA256"

	// The fixed keys of a Git credential Secret. GitHostSecretKey is the
	// authority, host[:port], the credential owner grants the credential
	// for; GitCASHA256SecretKey and GitKnownHostsSHA256SecretKey are the
	// "sha256:" digests of the trust it may be sent under. A resource's
	// author selects the Secret, never the keys.
	GitUsernameSecretKey         = "username"
	GitPasswordSecretKey         = "password"
	GitSSHPrivateKeySecretKey    = "sshPrivateKey"
	GitHostSecretKey             = "host"
	GitCASHA256SecretKey         = "caSHA256"
	GitKnownHostsSHA256SecretKey = "knownHostsSHA256"
)
View Source
const (
	// MaxPodMetadataEntries bounds each of the two maps in PodMetadataSpec.
	MaxPodMetadataEntries = 16
	// MaxPodMetadataKeyLength is a qualified key at its longest: a 253-byte
	// prefix, the slash, and a 63-byte name.
	MaxPodMetadataKeyLength = 317
	// MaxPodLabelValueLength is what Kubernetes accepts for a label value.
	MaxPodLabelValueLength = 63
	// MaxPodAnnotationValueLength bounds one declared annotation value. With
	// MaxPodMetadataEntries and MaxPodMetadataKeyLength it bounds the whole
	// declaration to under 22 KiB of annotations and 6 KiB of labels.
	MaxPodAnnotationValueLength = 1024
)
View Source
const (
	ConditionArtifactResolved     = "ArtifactResolved"
	ConditionArtifactVerified     = "ArtifactVerified"
	ConditionEngineSupported      = "EngineSupported"
	ConditionDatabaseReachable    = "DatabaseReachable"
	ConditionDriftDetected        = "DriftDetected"
	ConditionPlanReady            = "PlanReady"
	ConditionApprovalRequired     = "ApprovalRequired"
	ConditionApplying             = "Applying"
	ConditionInSync               = "InSync"
	ConditionReady                = "Ready"
	ConditionSuspended            = "Suspended"
	ConditionReconciliationFailed = "ReconciliationFailed"
)
View Source
const (
	ConditionApprovalAccepted = "Accepted"
	ConditionApprovalConsumed = "Consumed"
	ConditionApprovalStale    = "Stale"
)
View Source
const ConditionMigrationArtifactVerified = "ArtifactVerified"

ConditionMigrationArtifactVerified reports that the resolved artifact satisfied its verification policy.

View Source
const ConditionPlanStorageReady = "Ready"
View Source
const MaxMigrationRevisions = 64

MaxMigrationRevisions bounds status.history.revisions.

View Source
const MaxReadRequestLength = 64

MaxReadRequestLength is the longest annotation value status records as given. A longer one is recorded as its SHA-256 digest, written "sha256:<hex>".

View Source
const ReadRequestAnnotation = "operator.ptah.run/read-requested-at"

ReadRequestAnnotation asks a PtahSchema or a PtahMigration to read its database now rather than at status.nextReconciliationTime, as after a person changed the database outside the operator. Its value is an RFC 3339 instant, so each request differs from the last:

kubectl annotate ptahschema storefront \
  operator.ptah.run/read-requested-at="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite

A value the status does not record as answered starts the read the resource would start at its next interval, once no operation is running and the resource is not waiting out a retry delay. It never starts a mutating operation, and it does not change the generation, so the current plan and its approval stay unless the reading retires them. A read that was already running when the request arrived does not answer it: it may have read the database before the change the request is about.

View Source
const SettledApplyAnnotation = "operator.ptah.run/settled-apply"

SettledApplyAnnotation is how a person settles the proof a PtahSchema owes an Apply when that proof cannot be read: the Secret it reads holds a URL of another target than the plan the Apply ran from, which status reports with reason TargetIdentityChanged. Its value is the one that status prints, the Apply's operation ID and the digest of the target the read named:

kubectl annotate ptahschema storefront \
  operator.ptah.run/settled-apply=sha256:.../sha256:... --overwrite

It says the person accounts for what that Apply did to the target it ran against. The operator gives up the proof at a read that names that target, once the resource has stopped there and printed that value, records no Apply and reads the database again under whatever the Secret holds. Under apply: Always the next plan then applies with no approval unless it is destructive or changes privileges. The value is a statement rather than a secret, and it holds until the proof ends, so a store that leaves the target and comes back settles there with no new write. Removing the annotation takes it back. It settles no other Apply and no other target, and it does nothing while the proof is failing for any other reason.

View Source
const UnresolvedRunAnnotation = "operator.ptah.run/unresolved-run"

UnresolvedRunAnnotation holds a copy of status.unresolvedRun, encoded as JSON, on the PtahMigration's own metadata.

A restore that drops status -- Velero's default -- keeps annotations, and the record is what refuses to replay a migration that may already have run. The manager writes the copy before the status field and removes it after, and restores the status field from it when status comes back without it. Only the manager's ServiceAccount may add, change or remove it once the resource exists; the chart's admission policy refuses anyone else.

Variables

View Source
var (
	// GroupVersion identifies this API group and version.
	GroupVersion = schema.GroupVersion{Group: "operator.ptah.run", Version: "v1alpha1"}

	// SchemeBuilder registers this package's API types.
	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}

	// AddToScheme adds this package's API types to a runtime Scheme.
	AddToScheme = SchemeBuilder.AddToScheme
)

Functions

func ReadRequestToken added in v0.2.9

func ReadRequestToken(value string) string

ReadRequestToken is how status.lastReadRequest records a value of the ReadRequestAnnotation: as given up to MaxReadRequestLength bytes, as its SHA-256 digest beyond, so any value can be recorded as answered and none is answered twice. A client that waits for its request compares this with status.lastReadRequest.

Types

type ActiveOperationStatus

type ActiveOperationStatus struct {
	// Type is the operation this claim authorizes: resolving the artifact,
	// verifying it, observing the database, planning, or applying.
	Type OperationType `json:"type"`
	// ID is this attempt's identity, distinct from every other attempt.
	ID string `json:"id"`
	// InputFingerprint is everything the claim was computed from. A changed
	// input produces a new claim rather than reusing this one.
	InputFingerprint string `json:"inputFingerprint"`
	// JobName is the Job this claim authorizes, named before it is created.
	JobName string `json:"jobName"`
	// JobUID is that Job's UID once it exists. A Job with the right name and
	// another UID is somebody else's.
	JobUID types.UID `json:"jobUID,omitempty"`
	// StartedAt is when the claim was written.
	StartedAt metav1.Time `json:"startedAt"`
	// Attempt counts this claim among the retries of the same operation.
	Attempt int32 `json:"attempt"`
	// ExecutionBindingID binds every Job and result to the durable evidence
	// epoch that authorized its claim.
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	ExecutionBindingID string `json:"executionBindingID"`

	// AdmissionSnapshot is persisted before dispatch and is bound into the Job
	// and Pod template annotations. It permits only modeled, safe built-in
	// admission mutations while retaining exact validation for executable and
	// security-sensitive Pod fields.
	AdmissionSnapshot *PodAdmissionSnapshot `json:"admissionSnapshot,omitempty"`
	// AdmissionSnapshotRefreshed records that this claim's admission snapshot
	// was resolved a second time, because the Job template this manager
	// builds differed from the one the snapshot recorded before anything was
	// dispatched. That happens once, when a manager release that shares the
	// execution binding takes over an undispatched claim. It happens at most
	// once per claim: a template that differs again comes from a builder that
	// does not build the same Job twice, and the claim is retired instead.
	AdmissionSnapshotRefreshed bool `json:"admissionSnapshotRefreshed,omitempty"`

	// DispatchStarted is persisted immediately before the one permitted Job
	// create attempt. A missing Apply Job after this boundary is outcome-unknown
	// and must never be recreated.
	DispatchStarted bool `json:"dispatchStarted,omitempty"`
	// DispatchNotAfter is the immutable last instant at which the Apply runner
	// may start its mutating child. Missing or untrusted terminal Pod evidence
	// keeps proof behind the complete execution horizon below.
	DispatchNotAfter *metav1.Time `json:"dispatchNotAfter,omitempty"`
	// ExecutionNotAfter is enforced by the runner as the mutating child context
	// deadline, independently of relative Job and Pod deadlines.
	ExecutionNotAfter *metav1.Time `json:"executionNotAfter,omitempty"`
	// TerminationGracePeriodSeconds is how long the operation Pod is given to
	// stop on its own before it is killed.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=300
	TerminationGracePeriodSeconds int64 `json:"terminationGracePeriodSeconds,omitempty"`

	// Plan and Apply operations persist their credential-free lock binding so
	// later spec changes cannot redirect or shorten protection for a running Job.
	CoordinationDigest string `json:"coordinationDigest,omitempty"`
	// TargetIdentityDigest is the database that claim is for.
	TargetIdentityDigest string `json:"targetIdentityDigest,omitempty"`
	// Target is the key-free binding the Job resolves its credential through.
	Target *DatabaseTargetBinding `json:"target,omitempty"`
	// ObservationExclude is the managed scope the operation was given, copied
	// so a later spec edit cannot change what a running Job was asked to read.
	ObservationExclude []string `json:"observationExclude,omitempty"`
	// +kubebuilder:validation:MaxItems=128
	// +listType=set
	// ObservationProtectedTables is the fence the operation was dispatched
	// under, so an edit to the policy cannot reach a Job already running.
	// +kubebuilder:validation:MaxItems=128
	// +listType=set
	ObservationProtectedTables []string `json:"observationProtectedTables,omitempty"`
	// ObservationSeverity is the drift severity it was asked to report.
	ObservationSeverity string `json:"observationSeverity,omitempty"`
	// ObservationDev is the scratch database it may use, where one is
	// configured.
	ObservationDev *DatabaseTargetRef `json:"observationDev,omitempty"`
	// ObservationConnectTimeout is the connect timeout it was dispatched with.
	ObservationConnectTimeout metav1.Duration `json:"observationConnectTimeout,omitempty"`
	// ObservationLockTimeout is the database lock timeout it was dispatched
	// with.
	ObservationLockTimeout metav1.Duration `json:"observationLockTimeout,omitempty"`
	// VerificationPolicyUID and VerificationPolicyDigest bind a Verify Job to
	// the immutable ConfigMap version inspected before dispatch.
	VerificationPolicyUID types.UID `json:"verificationPolicyUID,omitempty"`
	// VerificationPolicyDigest is that ConfigMap's content at dispatch.
	VerificationPolicyDigest string `json:"verificationPolicyDigest,omitempty"`
	// Source snapshots artifact access for mandatory post-Apply observation.
	// It contains Kubernetes selectors only, never Secret contents.
	Source *SourceAccessBinding `json:"source,omitempty"`
	// LeaseDurationSeconds is how long the database lock was taken for.
	// +kubebuilder:validation:Minimum=5
	// +kubebuilder:validation:Maximum=86460
	LeaseDurationSeconds int32 `json:"leaseDurationSeconds,omitempty"`
	// LeaseEpoch is persisted before dispatch. A different epoch invalidates
	// every result produced by this operation.
	LeaseEpoch string `json:"leaseEpoch,omitempty"`
	// LeaseContinuityLost is set before any result can be harvested when the
	// persisted epoch no longer owns an uninterrupted lock interval.
	LeaseContinuityLost bool `json:"leaseContinuityLost,omitempty"`

	// PlanSealPublicKeyDigest is the digest of the manager public key a Plan
	// Job's runner was given to seal its plan payload, persisted immediately
	// before the Job is created. A manager whose own current key no longer
	// matches this digest -- because it restarted and generated a new one --
	// cannot open that Job's result and retries instead of waiting: Plan is
	// read-only, so a fresh attempt sealed to the current key costs nothing
	// the first attempt did not already cost. Plan operations only.
	PlanSealPublicKeyDigest string `json:"planSealPublicKeyDigest,omitempty"`
}

ActiveOperationStatus makes controller restarts resume one deterministic Job.

func (*ActiveOperationStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ActiveOperationStatus.

func (*ActiveOperationStatus) DeepCopyInto

func (in *ActiveOperationStatus) DeepCopyInto(out *ActiveOperationStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type AdmissionObjectBinding

type AdmissionObjectBinding struct {
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// Name of the cluster object this snapshot was read from.
	Name string `json:"name"`
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	// UID it had, so a recreated object is a different one.
	UID string `json:"uid"`
	// ResourceVersion is opaque, but bounded here so hostile metadata cannot
	// make the status object grow without limit.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	ResourceVersion string `json:"resourceVersion"`
}

AdmissionObjectBinding identifies one API object whose credential-free contents contributed to the resolved Pod admission envelope.

func (*AdmissionObjectBinding) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new AdmissionObjectBinding.

func (*AdmissionObjectBinding) DeepCopyInto

func (in *AdmissionObjectBinding) DeepCopyInto(out *AdmissionObjectBinding)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type AppliedStatus

type AppliedStatus struct {
	// ArtifactDigest is the OCI artifact that was applied.
	// +optional
	ArtifactDigest string `json:"artifactDigest,omitempty"`
	// Source is the source that was applied, for a plan computed from a
	// ConfigMap or a Git commit.
	// +optional
	Source *PlanSourceBinding `json:"source,omitempty"`
	// PlanRef names the stored plan this apply ran. It is what a reader
	// addresses to see the SQL that was applied. It does not replace
	// PlanFingerprint: the reference says which object to read and the
	// fingerprint says whether the object read is the one this record was
	// written for.
	PlanRef ImmutableObjectReference `json:"planRef"`
	// PlanFingerprint says whether the plan object read today is the one this
	// record was written for.
	PlanFingerprint string `json:"planFingerprint"`
	// CoordinationDigest is the realm the apply held while it ran.
	CoordinationDigest string `json:"coordinationDigest"`
	// TargetIdentityDigest is the database it converged.
	TargetIdentityDigest string `json:"targetIdentityDigest"`
	// ExecutionBindingID is the epoch the apply ran under.
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	ExecutionBindingID string `json:"executionBindingID"`
	// ControllerImage is the digest-pinned manager that published the plan
	// this apply ran. The manager that dispatched the Job is DispatchedBy.
	// +kubebuilder:validation:Pattern=`^[^[:space:]@]+@sha256:[0-9a-f]{64}$`
	ControllerImage string `json:"controllerImage"`
	// ControllerRevision is that manager's revision.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	// +kubebuilder:validation:Pattern=`^[^[:space:][:cntrl:]]([^[:cntrl:]]*[^[:space:][:cntrl:]])?$`
	ControllerRevision string `json:"controllerRevision"`
	// ControllerStateVersion is the state semantics it wrote.
	// +kubebuilder:validation:Minimum=1
	ControllerStateVersion int32 `json:"controllerStateVersion"`
	// PtahVersion is the Ptah build that executed the statements.
	PtahVersion string `json:"ptahVersion"`
	// ExecutorImage is the digest-pinned image it ran in.
	ExecutorImage string `json:"executorImage"`
	// RunnerImage is the runner image of the manager that published the plan.
	RunnerImage string `json:"runnerImage"`
	// RunnerProtocolVersion is the runner protocol the apply ran under.
	RunnerProtocolVersion int32 `json:"runnerProtocolVersion"`
	// DispatchedBy is the manager that built and dispatched the Apply Job,
	// read from the Job's Pod template when the Apply was harvested. It can
	// differ from the publisher above: a later release of the manager that
	// shares the execution binding applies the plans an earlier one
	// published. It is absent when the Apply was settled without its Job.
	// +optional
	DispatchedBy *ManagerRecord `json:"dispatchedBy,omitempty"`
	// CompletedAt is when convergence was independently observed, not when the
	// Job exited.
	CompletedAt metav1.Time `json:"completedAt"`
}

AppliedStatus is written only after post-apply observation proves convergence.

func (*AppliedStatus) DeepCopy

func (in *AppliedStatus) DeepCopy() *AppliedStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new AppliedStatus.

func (*AppliedStatus) DeepCopyInto

func (in *AppliedStatus) DeepCopyInto(out *AppliedStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ApplyPolicy

type ApplyPolicy string

ApplyPolicy controls when a current, non-stale plan may execute. +kubebuilder:validation:Enum=Never;OnApproval;Always

const (
	ApplyPolicyNever      ApplyPolicy = "Never"
	ApplyPolicyOnApproval ApplyPolicy = "OnApproval"
	ApplyPolicyAlways     ApplyPolicy = "Always"
)

type ApprovalIdentity

type ApprovalIdentity struct {
	// Username the API server authenticated the request as.
	Username string `json:"username"`
	// UID of that user, where the authenticator provides one.
	UID string `json:"uid,omitempty"`
	// Groups the authenticated user belonged to at that moment.
	// +kubebuilder:validation:MaxItems=64
	Groups []string `json:"groups,omitempty"`
}

ApprovalIdentity is stamped from the authenticated admission request. The API client does not choose these fields.

func (*ApprovalIdentity) DeepCopy

func (in *ApprovalIdentity) DeepCopy() *ApprovalIdentity

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ApprovalIdentity.

func (*ApprovalIdentity) DeepCopyInto

func (in *ApprovalIdentity) DeepCopyInto(out *ApprovalIdentity)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type BindingRetirementStatus

type BindingRetirementStatus struct {
	// RetiredEpoch is the epoch the rotation replaced. The plan and the Job
	// this record names belong to it, and the controller touches a Job only
	// when the Job carries this epoch.
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	RetiredEpoch string `json:"retiredEpoch"`

	// Plan is the retired epoch's plan, while approvals that name it are
	// still to be marked stale.
	// +optional
	Plan *RetiredPlanReference `json:"plan,omitempty"`

	// Job is the Job the retired epoch's claim dispatched, while its cleanup
	// is still to be scheduled.
	// +optional
	Job *RetiredJobStatus `json:"job,omitempty"`
}

BindingRetirementStatus is what retiring one execution-binding epoch still owes. Each optional field is one obligation and is removed when it is met, so what is present is the state of the cleanup: a plan whose approvals are still to be marked stale, a Job whose UID is still to be adopted, a Job whose cleanup TTL is still to be set.

Nothing here authorizes anything. The write that created the record also moved the epoch every plan, approval and claim is checked against, so the record only says which leftovers of the old epoch are this resource's to tidy.

func (*BindingRetirementStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BindingRetirementStatus.

func (*BindingRetirementStatus) DeepCopyInto

func (in *BindingRetirementStatus) DeepCopyInto(out *BindingRetirementStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ConditionReason

type ConditionReason string

ConditionReason is the stable, machine-readable reason vocabulary emitted by the schema controller. Messages may gain detail, but these values are API contracts and must not be repurposed.

const (
	// ReasonHistoryMatched means the artifact and the revision table agree and
	// nothing is pending.
	ReasonHistoryMatched ConditionReason = "HistoryMatched"
	// ReasonMigrationsPending means the artifact has migrations the database
	// does not.
	ReasonMigrationsPending ConditionReason = "MigrationsPending"
	// ReasonHistoryDirty means a failed or interrupted run left a revision row
	// behind. Nothing applies while one exists, and the controller never
	// removes it: what a half-applied migration did is a question for a person
	// with the database in front of them.
	ReasonHistoryDirty ConditionReason = "HistoryDirty"
	// ReasonHistoryModified means an applied migration's file no longer
	// accounts for it. This is the refusal a versioned workflow exists to make.
	ReasonHistoryModified ConditionReason = "HistoryModified"
	// ReasonHistoryOutOfOrder means the artifact carries a migration below a
	// version the database has already applied. Linear execution refuses the
	// whole run, so the operator refuses before it publishes a plan nobody
	// could execute.
	ReasonHistoryOutOfOrder ConditionReason = "HistoryOutOfOrder"
	// ReasonHistoryAhead means the database records a migration this artifact
	// does not carry. Nothing about it is repairable from here: the operator
	// never rolls a database back to match an older artifact, and which of the
	// two is wrong is not a question a controller can answer.
	ReasonHistoryAhead ConditionReason = "HistoryAhead"
	// ReasonLogWritten means the database accepted every entry the last run
	// that reported on schema_migrations_log wrote there.
	ReasonLogWritten ConditionReason = "LogWritten"
	// ReasonLogEntriesLost means the database refused entries that run wrote
	// to schema_migrations_log, so its record of the run is incomplete. The
	// run's outcome is unchanged: the migrations it applied are applied.
	ReasonLogEntriesLost ConditionReason = "LogEntriesLost"
)

Condition reasons a PtahMigration publishes in addition to the shared ones.

const (
	// ReasonRunAcknowledged means the acknowledgment settled the run it names.
	ReasonRunAcknowledged ConditionReason = "RunAcknowledged"
	// ReasonRunNotUnresolved means the run the acknowledgment names is not the
	// one the migration records as unresolved: another acknowledgment or a
	// reading of the database settled it first, or it was never this
	// migration's.
	ReasonRunNotUnresolved ConditionReason = "RunNotUnresolved"
)

Condition reasons a PtahMigrationRunAcknowledgment publishes.

const (
	ReasonActive                       ConditionReason = "Active"
	ReasonApplyDisabled                ConditionReason = "ApplyDisabled"
	ReasonApplyOutcomeUnknown          ConditionReason = "ApplyOutcomeUnknown"
	ReasonApplyPending                 ConditionReason = "ApplyPending"
	ReasonApprovalRevoked              ConditionReason = "ApprovalRevoked"
	ReasonApprovedPlan                 ConditionReason = "ApprovedPlan"
	ReasonArtifactUnverified           ConditionReason = "ArtifactUnverified"
	ReasonAwaitingApproval             ConditionReason = "AwaitingApproval"
	ReasonCommitResolved               ConditionReason = "CommitResolved"
	ReasonConfigurationError           ConditionReason = "ConfigurationError"
	ReasonConvergedAfterUnknownOutcome ConditionReason = "ConvergedAfterUnknownOutcome"
	ReasonCurrentPlan                  ConditionReason = "CurrentPlan"
	ReasonDesiredStateChanged          ConditionReason = "DesiredStateChanged"
	ReasonDestructiveChangesDisabled   ConditionReason = "DestructiveChangesDisabled"
	ReasonDigestPinned                 ConditionReason = "DigestPinned"
	ReasonDispatchCommitted            ConditionReason = "DispatchCommitted"
	ReasonDownloadVerified             ConditionReason = "DownloadVerified"
	ReasonExecutionBindingChanged      ConditionReason = "ExecutionBindingChanged"
	ReasonInputsChanged                ConditionReason = "InputsChanged"
	ReasonInSync                       ConditionReason = "InSync"
	ReasonJobCompleted                 ConditionReason = "JobCompleted"
	ReasonLeaseContinuityLost          ConditionReason = "LeaseContinuityLost"
	ReasonNoChanges                    ConditionReason = "NoChanges"
	ReasonNotRequired                  ConditionReason = "NotRequired"
	ReasonObserved                     ConditionReason = "Observed"
	ReasonOperationFailed              ConditionReason = "OperationFailed"
	ReasonOperationInProgress          ConditionReason = "OperationInProgress"
	ReasonOutcomeUnknown               ConditionReason = "OutcomeUnknown"
	ReasonPending                      ConditionReason = "Pending"
	ReasonPlanNoLongerCurrent          ConditionReason = "PlanNoLongerCurrent"
	ReasonPlanPublicationRefused       ConditionReason = "PlanPublicationRefused"
	ReasonPlanReady                    ConditionReason = "PlanReady"
	ReasonPodAdmissionRefused          ConditionReason = "PodAdmissionRefused"
	ReasonPodConfigurationError        ConditionReason = "PodConfigurationError"
	ReasonPolicyBlocked                ConditionReason = "PolicyBlocked"
	ReasonPolicyChanged                ConditionReason = "PolicyChanged"
	ReasonPolicyRefused                ConditionReason = "PolicyRefused"
	ReasonPolicySatisfied              ConditionReason = "PolicySatisfied"
	ReasonPrivilegeChanges             ConditionReason = "PrivilegeChanges"
	ReasonProofInputsChanged           ConditionReason = "ProofInputsChanged"
	ReasonProofSettled                 ConditionReason = "ProofSettled"
	ReasonProtectedTable               ConditionReason = "ProtectedTable"
	ReasonPublished                    ConditionReason = "Published"
	ReasonRealmConflict                ConditionReason = "RealmConflict"
	ReasonRealmNotAuthorized           ConditionReason = "RealmNotAuthorized"
	ReasonRefreshFailed                ConditionReason = "RefreshFailed"
	ReasonRefreshing                   ConditionReason = "Refreshing"
	ReasonRefreshSuspended             ConditionReason = "RefreshSuspended"
	ReasonRequested                    ConditionReason = "Requested"
	ReasonResolveFailed                ConditionReason = "ResolveFailed"
	ReasonRunnerProtocolMismatch       ConditionReason = "RunnerProtocolMismatch"
	ReasonSatisfied                    ConditionReason = "Satisfied"
	// ReasonSnapshotTaken says a ConfigMap source was read and its selected
	// files copied into the snapshot every later operation reads.
	ReasonSnapshotTaken           ConditionReason = "SnapshotTaken"
	ReasonScopedChanges           ConditionReason = "ScopedChanges"
	ReasonScopedConverged         ConditionReason = "ScopedConverged"
	ReasonScopedPlanPending       ConditionReason = "ScopedPlanPending"
	ReasonSourceFreshnessUnknown  ConditionReason = "SourceFreshnessUnknown"
	ReasonSourceRefreshPending    ConditionReason = "SourceRefreshPending"
	ReasonSourceResolutionUnknown ConditionReason = "SourceResolutionUnknown"
	ReasonSourceUnresolved        ConditionReason = "SourceUnresolved"
	ReasonStale                   ConditionReason = "Stale"
	ReasonStaleObservation        ConditionReason = "StaleObservation"
	ReasonStalePlan               ConditionReason = "StalePlan"
	ReasonSucceeded               ConditionReason = "Succeeded"
	ReasonSupersededApproval      ConditionReason = "SupersededApproval"
	ReasonSupportedEngine         ConditionReason = "SupportedEngine"
	ReasonSuspended               ConditionReason = "Suspended"
	ReasonTargetIdentityChanged   ConditionReason = "TargetIdentityChanged"
	ReasonUnsupportedEngine       ConditionReason = "UnsupportedEngine"
	ReasonVerifyingConvergence    ConditionReason = "VerifyingConvergence"
	ReasonWaiting                 ConditionReason = "Waiting"
	ReasonWaitingForDatabaseLock  ConditionReason = "WaitingForDatabaseLock"
	// The reasons DatabaseReachable carries when an operation could not open
	// its target database, one for each kind of failure Ptah reports.
	ReasonDatabaseUnreachable  ConditionReason = "DatabaseUnreachable"
	ReasonAuthenticationFailed ConditionReason = "AuthenticationFailed"
	ReasonDatabaseNotFound     ConditionReason = "DatabaseNotFound"
	ReasonPermissionDenied     ConditionReason = "PermissionDenied"
	ReasonTLSFailed            ConditionReason = "TLSFailed"
)

type ConfigMapSourceItem added in v0.2.7

type ConfigMapSourceItem struct {
	// Key in the ConfigMap's data or binaryData.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[-._a-zA-Z0-9]+$`
	Key string `json:"key"`

	// Path is the file the key becomes: relative, separated by "/", with no
	// empty, "." or ".." element, no backslash and no control character. An
	// element longer than 255 bytes, or a path that is a file and a directory
	// at once, is refused when the source is read.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=1024
	// +kubebuilder:validation:Pattern=`^(?:[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.\.[^/\\\x00-\x1f\x7f]+)(?:/(?:[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.\.[^/\\\x00-\x1f\x7f]+))*$`
	Path string `json:"path"`
}

ConfigMapSourceItem maps one ConfigMap key to one file.

func (*ConfigMapSourceItem) DeepCopy added in v0.2.7

func (in *ConfigMapSourceItem) DeepCopy() *ConfigMapSourceItem

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ConfigMapSourceItem.

func (*ConfigMapSourceItem) DeepCopyInto added in v0.2.7

func (in *ConfigMapSourceItem) DeepCopyInto(out *ConfigMapSourceItem)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ConfigMapSourceRevision added in v0.2.7

type ConfigMapSourceRevision struct {
	// Name of the ConfigMap.
	Name string `json:"name"`
	// UID of the ConfigMap. Another ConfigMap under the same name is another
	// source, and retires a plan computed from this one.
	UID types.UID `json:"uid"`
	// ResourceVersion is the version that was read. An edit to a key the
	// source does not select moves it and changes no content.
	ResourceVersion string `json:"resourceVersion"`
}

ConfigMapSourceRevision is the ConfigMap a source was last read from.

func (*ConfigMapSourceRevision) DeepCopy added in v0.2.7

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ConfigMapSourceRevision.

func (*ConfigMapSourceRevision) DeepCopyInto added in v0.2.7

func (in *ConfigMapSourceRevision) DeepCopyInto(out *ConfigMapSourceRevision)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ConfigMapSourceSpec added in v0.2.7

type ConfigMapSourceSpec struct {
	// Name of the ConfigMap, in this resource's namespace.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
	Name string `json:"name"`

	// Items are the keys that become files, and the file each one becomes. A
	// key cannot hold "/", so a nested directory is spelled out here. A key
	// the list does not name is not part of the source, and editing it
	// changes nothing. A schema selects exactly one file, whose extension
	// tells Ptah its format; a migration directory selects up to 1,000.
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=1000
	// +listType=map
	// +listMapKey=path
	Items []ConfigMapSourceItem `json:"items"`
}

ConfigMapSourceSpec selects files from one ConfigMap.

func (*ConfigMapSourceSpec) DeepCopy added in v0.2.7

func (in *ConfigMapSourceSpec) DeepCopy() *ConfigMapSourceSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ConfigMapSourceSpec.

func (*ConfigMapSourceSpec) DeepCopyInto added in v0.2.7

func (in *ConfigMapSourceSpec) DeepCopyInto(out *ConfigMapSourceSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ConsumedApprovalStatus

type ConsumedApprovalStatus struct {
	// Name of the approval that authorized the apply.
	Name string `json:"name"`
	// UID it had, so a recreated approval is not read as the same decision.
	UID types.UID `json:"uid"`
	// Approver is who the API server authenticated.
	Approver ApprovalIdentity `json:"approver"`
	// ApprovedAt is when the decision was stamped.
	ApprovedAt metav1.Time `json:"approvedAt"`
}

ConsumedApprovalStatus records the immutable approval object and identity.

func (*ConsumedApprovalStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ConsumedApprovalStatus.

func (*ConsumedApprovalStatus) DeepCopyInto

func (in *ConsumedApprovalStatus) DeepCopyInto(out *ConsumedApprovalStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type CurrentPlanStatus

type CurrentPlanStatus struct {
	// Name of the PtahSchemaPlan this record is about.
	Name string `json:"name"`
	// UID it had when this record was written.
	UID types.UID `json:"uid"`

	// Fingerprint is the plan's complete approval identity, and the fields
	// below are that identity spelled out. They are copied here so a reader --
	// and an audit -- can see what is waiting without fetching the plan.
	Fingerprint string `json:"fingerprint"`
	// ContentDigest is the digest of the plan bytes.
	ContentDigest string `json:"contentDigest"`
	// ArtifactDigest is the OCI artifact the plan was computed from. A plan
	// computed from another source binds source instead.
	// +optional
	ArtifactDigest string `json:"artifactDigest,omitempty"`
	// Source is the source a plan computed from a ConfigMap or a Git commit
	// binds in place of artifactDigest.
	// +optional
	Source *PlanSourceBinding `json:"source,omitempty"`
	// CoordinationDigest is the database realm it takes its turn in.
	CoordinationDigest string `json:"coordinationDigest"`
	// TargetIdentityDigest is the database it was computed against.
	TargetIdentityDigest string `json:"targetIdentityDigest"`
	// ActualStateFingerprint is the observed state it was planned from.
	ActualStateFingerprint string `json:"actualStateFingerprint"`
	// DesiredStateFingerprint is the state the artifact declared.
	DesiredStateFingerprint string `json:"desiredStateFingerprint"`
	// PolicyFingerprint is the spec.policy it was computed under.
	PolicyFingerprint string `json:"policyFingerprint"`
	// VerificationPolicyUID is the policy object that accepted the artifact,
	// for an OCI plan.
	// +optional
	VerificationPolicyUID types.UID `json:"verificationPolicyUID,omitempty"`
	// VerificationPolicyDigest is that policy's content at the time.
	// +optional
	VerificationPolicyDigest string `json:"verificationPolicyDigest,omitempty"`
	// ExecutionBindingID is the execution epoch it belongs to.
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	ExecutionBindingID string `json:"executionBindingID"`
	// ControllerImage is the digest-pinned manager that published it,
	// recorded and not bound.
	// +kubebuilder:validation:Pattern=`^[^[:space:]@]+@sha256:[0-9a-f]{64}$`
	ControllerImage string `json:"controllerImage"`
	// ControllerRevision is that manager's revision.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	// +kubebuilder:validation:Pattern=`^[^[:space:][:cntrl:]]([^[:cntrl:]]*[^[:space:][:cntrl:]])?$`
	ControllerRevision string `json:"controllerRevision"`
	// ControllerStateVersion is the state semantics it writes.
	// +kubebuilder:validation:Minimum=1
	ControllerStateVersion int32 `json:"controllerStateVersion"`
	// PtahVersion is the Ptah build that computed the plan.
	PtahVersion string `json:"ptahVersion"`
	// ExecutorImage is the digest-pinned image that ran it.
	ExecutorImage string `json:"executorImage"`
	// RunnerImage is the runner image of the manager that published it,
	// recorded and not bound.
	RunnerImage string `json:"runnerImage"`
	// RunnerProtocolVersion is the runner protocol the plan binds.
	RunnerProtocolVersion int32 `json:"runnerProtocolVersion"`
	// Destructive says the plan drops or rewrites something.
	Destructive bool `json:"destructive"`
	// PrivilegeChanges names the kinds of authority the plan changes, as the
	// plan records them. Any entry means an approval is required even when
	// spec.policy.apply is Always.
	// +optional
	// +listType=set
	// +kubebuilder:validation:MaxItems=16
	PrivilegeChanges []PrivilegeChange `json:"privilegeChanges,omitempty"`
	// StatementCount is how many statements it holds. The statements
	// themselves are not here: read them with kubectl ptah plan.
	StatementCount int32 `json:"statementCount"`
	// CreatedAt is the plan object's own creation time, copied like every
	// other field here, so an audit of this record and of the plan it names
	// cannot disagree about when the plan came into being.
	CreatedAt metav1.Time `json:"createdAt"`

	// Approval is the decision that authorized this plan, where one was made.
	Approval *ConsumedApprovalStatus `json:"approval,omitempty"`
}

CurrentPlanStatus is a compact reference to an immutable PtahSchemaPlan.

func (*CurrentPlanStatus) DeepCopy

func (in *CurrentPlanStatus) DeepCopy() *CurrentPlanStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CurrentPlanStatus.

func (*CurrentPlanStatus) DeepCopyInto

func (in *CurrentPlanStatus) DeepCopyInto(out *CurrentPlanStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type DatabaseEngine

type DatabaseEngine string

DatabaseEngine names a database family. The API accepts bounded engine names so the controller can report unsupported families through status instead of turning a durable desired-state object into an admission-time dead end. +kubebuilder:validation:MinLength=1 +kubebuilder:validation:MaxLength=63 +kubebuilder:validation:Pattern=`^[A-Za-z][A-Za-z0-9._-]*$`

const (
	DatabaseEnginePostgreSQL DatabaseEngine = "PostgreSQL"
	DatabaseEngineMySQL      DatabaseEngine = "MySQL"
)

type DatabaseTargetBinding

type DatabaseTargetBinding struct {
	// Engine is the database this binding speaks.
	Engine DatabaseEngine `json:"engine"`
	// URLFrom is the Secret key the operation Pod reads the URL from.
	URLFrom corev1.SecretKeySelector `json:"urlFrom"`
}

DatabaseTargetBinding is the key-free immutable target snapshot stored in status. CoordinationKey must never be copied into status; its digest is persisted separately.

func (*DatabaseTargetBinding) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DatabaseTargetBinding.

func (*DatabaseTargetBinding) DeepCopyInto

func (in *DatabaseTargetBinding) DeepCopyInto(out *DatabaseTargetBinding)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type DatabaseTargetRef

type DatabaseTargetRef struct {
	// URLFrom names the Secret key holding this database's connection URL.
	URLFrom corev1.SecretKeySelector `json:"urlFrom"`
}

DatabaseTargetRef is a database URL reference used for optional rehearsal.

func (*DatabaseTargetRef) DeepCopy

func (in *DatabaseTargetRef) DeepCopy() *DatabaseTargetRef

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DatabaseTargetRef.

func (*DatabaseTargetRef) DeepCopyInto

func (in *DatabaseTargetRef) DeepCopyInto(out *DatabaseTargetRef)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type DatabaseTargetSpec

type DatabaseTargetSpec struct {
	// Engine is the database this target speaks. An engine outside the
	// supported set is refused with a condition rather than attempted.
	Engine DatabaseEngine `json:"engine"`

	// CoordinationKey is a non-secret, stable identifier for the physical
	// database, scoped to this resource's namespace. Every resource in the
	// namespace that can reach the same database through an alias, proxy, or
	// different credential must use exactly the same key.
	//
	// The same key in another namespace is another realm: a resource elsewhere
	// can neither block this one nor take turns with it by choosing the same
	// string. A database more than one namespace manages is named with
	// realmRef instead, which an administrator has to grant.
	//
	// Exactly one of coordinationKey and realmRef is set.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[a-z0-9](?:[a-z0-9._:/-]{0,251}[a-z0-9])?$`
	CoordinationKey string `json:"coordinationKey,omitempty"`

	// RealmRef names the cluster-scoped PtahRealm this database belongs to.
	// The realm, not this resource, decides whether the claim is allowed: a
	// resource whose namespace the realm does not list, or whose engine it
	// does not name, is refused with reason RealmNotAuthorized and runs
	// nothing, and it is not counted against the resources the realm does
	// admit.
	//
	// Exactly one of coordinationKey and realmRef is set.
	// +optional
	RealmRef *PtahRealmReference `json:"realmRef,omitempty"`

	// SharedRealm declares that this resource manages only part of the database
	// its realm names, and that every other resource managing that database
	// has declared the same.
	//
	// It defaults to false. A realm more than one resource claims is refused
	// while any claimant leaves it false -- including the resource that did
	// declare it. A PtahRealm with sharing Exclusive refuses a second claimant
	// whatever this says.
	//
	// Deleting a resource leaves the realm, and so does suspending it;
	// resuming puts it back, and the conflict is refused then, before any Job.
	//
	// What is verified is the declaration, never the disjointness: nothing can
	// tell whether two sets of arbitrary SQL touch the same rows. The
	// concurrency section of the architecture reference says why taking turns
	// is not enough.
	// +kubebuilder:default=false
	SharedRealm bool `json:"sharedRealm,omitempty"`

	// URLFrom names the Secret key holding the connection URL. The manager has
	// no permission to read it: the operation Pod resolves it, and the URL
	// never reaches status, an Event or a command line.
	URLFrom corev1.SecretKeySelector `json:"urlFrom"`
}

DatabaseTargetSpec identifies a supported engine, a namespaced Secret key, and the coordination realm of the physical database: a key this namespace owns, or a PtahRealm an administrator admitted this namespace to. There is deliberately no namespace field. +kubebuilder:validation:XValidation:rule="has(self.coordinationKey) != has(self.realmRef)",message="set exactly one of coordinationKey and realmRef"

func (*DatabaseTargetSpec) DeepCopy

func (in *DatabaseTargetSpec) DeepCopy() *DatabaseTargetSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DatabaseTargetSpec.

func (*DatabaseTargetSpec) DeepCopyInto

func (in *DatabaseTargetSpec) DeepCopyInto(out *DatabaseTargetSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type DriftFindingStatus

type DriftFindingStatus struct {
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=153
	// +kubebuilder:validation:Pattern=`^(async_replications_added|async_replications_modified|async_replications_removed|column_identities_removed|column_types_narrowed|columns_added|columns_modified|columns_removed|comments_changed|constraints_added|constraints_removed|constraints_validated|coordination_nodes_added|coordination_nodes_modified|coordination_nodes_removed|data_rows_deleted|data_rows_inserted|data_rows_updated|enum_values_added|enum_values_removed|enums_added|enums_removed|extensions_added|extensions_modified|extensions_removed|external_data_sources_added|external_data_sources_changed|external_data_sources_removed|external_tables_added|external_tables_changed|external_tables_removed|functions_added|functions_modified|functions_removed|grant_options_added|grant_options_removed|grants_added|grants_removed|index_visibility_changed|indexes_added|indexes_removed|indexes_renamed|materialized_views_added|materialized_views_modified|materialized_views_removed|resource_pool_classifiers_added|resource_pool_classifiers_modified|resource_pool_classifiers_removed|resource_pools_added|resource_pools_modified|resource_pools_removed|rls_enabled_tables_added|rls_enabled_tables_removed|rls_force_added|rls_force_removed|rls_policies_added|rls_policies_modified|rls_policies_removed|role_memberships_added|role_memberships_removed|roles_added|roles_modified|roles_removed|schemas_added|schemas_modified|schemas_removed|secrets_added|secrets_removed|secrets_rotated|sequences_added|sequences_modified|sequences_removed|table_constraints_added|table_constraints_removed|tables_added|tables_removed|topic_consumers_removed|topics_added|topics_modified|topics_removed|transfers_added|transfers_modified|transfers_removed|triggers_added|triggers_modified|triggers_removed|undecided|unique_protections_removed|vector_dimension_changed|views_added|views_modified|views_removed|feature_(changes|access_(widened|narrowed|unchanged|unknown))(:[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+(/[A-Za-z0-9_-][A-Za-z0-9._-]*)+)?)$`
	// Category is the kind of difference, never the object it was found in:
	// a table name is part of the schema, and the status does not carry it.
	// A feature category may name the type of object after a colon, as in
	// feature_changes:ptah.run/pgextension/extension-change; a type is not an
	// object either. The pattern admits every category an earlier release
	// stored, so a summary written before an upgrade still validates.
	Category string `json:"category"`
	// +kubebuilder:validation:Minimum=1
	// Count is how many differences of that kind the report held.
	Count int32 `json:"count"`
	// +kubebuilder:validation:Enum=safe;info;warning;error;destructive
	// Severity is how the category rates.
	Severity string `json:"severity"`
}

DriftFindingStatus is a bounded aggregate from the native drift report. It intentionally excludes object names, SQL, schema literals, and raw diffs.

The data_rows_ categories say that declared reference rows differ and by how many, and that is all a row contributes to this object: no key, no column name and no value. A reader who needs to know which rows reads the plan, which is data access and documented as such.

func (*DriftFindingStatus) DeepCopy

func (in *DriftFindingStatus) DeepCopy() *DriftFindingStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DriftFindingStatus.

func (*DriftFindingStatus) DeepCopyInto

func (in *DriftFindingStatus) DeepCopyInto(out *DriftFindingStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ExecutionBindingStatus

type ExecutionBindingStatus struct {
	// Epoch is this binding's identity. It changes whenever a component below
	// changes, a rollback to identical versions included, so evidence from
	// before such a rollout is historical rather than current.
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	Epoch string `json:"epoch"`

	// ControllerStateVersion versions manager-side reconciliation semantics
	// independently of the data-plane runner protocol.
	// +kubebuilder:validation:Minimum=1
	ControllerStateVersion int32 `json:"controllerStateVersion"`

	// PtahVersion is the Ptah build this epoch executes with.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	PtahVersion string `json:"ptahVersion"`
	// ExecutorImage is the digest-pinned image carrying that build.
	// +kubebuilder:validation:MinLength=1
	ExecutorImage string `json:"executorImage"`
	// RunnerProtocolVersion is the runner protocol this epoch binds: what the
	// runner enforces inside the Pod and the result frame it returns.
	// +kubebuilder:validation:Minimum=1
	RunnerProtocolVersion int32 `json:"runnerProtocolVersion"`
}

ExecutionBindingStatus identifies one uninterrupted execution epoch: the components that decide what a plan means when it runs. The explicit component fields are audit evidence; Epoch prevents approvals from becoming current again after a later rollback.

The manager's own image and revision, and the runner image built beside it, are deliberately absent. They are recorded on every Job and plan, and a release that changes only them -- a patch or security fix -- keeps the epoch, so a pending approval stays valid and a plan stays applicable. What the runner enforces is bound through RunnerProtocolVersion instead, which changes whenever that enforcement does.

func (*ExecutionBindingStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ExecutionBindingStatus.

func (*ExecutionBindingStatus) DeepCopyInto

func (in *ExecutionBindingStatus) DeepCopyInto(out *ExecutionBindingStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ExecutionSpec

type ExecutionSpec struct {
	// ActiveDeadlineSeconds is how long one operation Job may run before
	// Kubernetes ends it. An apply that hits this leaves an uncertain outcome,
	// which returns to observation rather than to a replay.
	// +kubebuilder:validation:Minimum=30
	// +kubebuilder:validation:Maximum=86400
	// +kubebuilder:default=900
	ActiveDeadlineSeconds int64 `json:"activeDeadlineSeconds,omitempty"`

	// FailureRetryInterval is how long the controller waits after a failed
	// operation before trying the same one again.
	// +kubebuilder:default="30s"
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MaxLength=32
	// +kubebuilder:validation:XValidation:rule="duration(self) >= duration('5s') && duration(self) <= duration('1h')",message="failureRetryInterval must be between 5s and 1h"
	FailureRetryInterval metav1.Duration `json:"failureRetryInterval,omitempty"`

	// ConnectTimeout bounds opening the database connection, so an unreachable
	// database fails in seconds rather than holding the Job to its deadline.
	// +kubebuilder:default="10s"
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MaxLength=32
	// +kubebuilder:validation:XValidation:rule="duration(self) >= duration('1s') && duration(self) <= duration('10m')",message="connectTimeout must be between 1s and 10m"
	ConnectTimeout metav1.Duration `json:"connectTimeout,omitempty"`

	// Resources are the requests and limits of the container that runs SQL.
	Resources corev1.ResourceRequirements `json:"resources,omitempty"`

	// ServiceAccountName is the identity operation Pods run as. It is theirs
	// rather than the manager's, and it needs no Kubernetes permission at all.
	ServiceAccountName string `json:"serviceAccountName,omitempty"`
	// ImagePullSecrets are the pull Secrets those Pods use.
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`
	// NodeSelector restricts where operation Pods may be scheduled.
	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
	// Tolerations are the taints those Pods tolerate.
	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
	// Affinity is scheduling affinity for those Pods.
	Affinity *corev1.Affinity `json:"affinity,omitempty"`
	// RuntimeClassName selects the container runtime they use. The admission
	// snapshot records what the cluster resolved, so a class that changed under
	// a claim is refused rather than run.
	RuntimeClassName *string `json:"runtimeClassName,omitempty"`
	// PriorityClassName is the scheduling priority they run at.
	PriorityClassName string `json:"priorityClassName,omitempty"`
	// PodMetadata is what an operation Pod carries for the cluster around it:
	// a service mesh's opt-out annotation, the label a policy engine
	// requires, a team's own bookkeeping. Every operation Pod this resource
	// dispatches carries exactly these labels and annotations beside the
	// operator's own, and the admission snapshot binds them: a Pod that
	// arrives with more, fewer or different metadata is refused, so nothing
	// unplanned runs beside the database credential. Keys under ptah.run,
	// kubernetes.io and k8s.io are refused, so the operator's own labels, the
	// Job controller's and the built-in admission plugins' cannot be
	// redeclared, and nothing here can select an operation Pod into an
	// object the operator owns. Unset, nothing changes.
	// +optional
	PodMetadata *PodMetadataSpec `json:"podMetadata,omitempty"`
}

ExecutionSpec exposes bounded scheduling and resource controls while withholding arbitrary Pod/container command customization.

func (*ExecutionSpec) DeepCopy

func (in *ExecutionSpec) DeepCopy() *ExecutionSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ExecutionSpec.

func (*ExecutionSpec) DeepCopyInto

func (in *ExecutionSpec) DeepCopyInto(out *ExecutionSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type GitAuthSource added in v0.2.7

type GitAuthSource struct {
	// Name of the Secret, in this resource's namespace.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
}

GitAuthSource names the Secret a Git fetch authenticates with. Its keys are fixed: username and password for https:// (a token goes in password), sshPrivateKey for ssh://, and host, the authority host[:port] the credential is for, which the fetch holds the URL to. caSHA256 or knownHostsSHA256, when present, is the SHA-256 of the trust the transport selects: the Secret's owner, not the resource's author, decides whom the credential is sent to.

func (*GitAuthSource) DeepCopy added in v0.2.7

func (in *GitAuthSource) DeepCopy() *GitAuthSource

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GitAuthSource.

func (*GitAuthSource) DeepCopyInto added in v0.2.7

func (in *GitAuthSource) DeepCopyInto(out *GitAuthSource)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type GitRef added in v0.2.7

type GitRef struct {
	// Branch is read at its tip, again at every interval.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=255
	// +kubebuilder:validation:Pattern=`^[^[:space:][:cntrl:]~^:?*\[\\]+$`
	Branch string `json:"branch,omitempty"`
	// Tag is read at the commit it names, again at every interval.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=255
	// +kubebuilder:validation:Pattern=`^[^[:space:][:cntrl:]~^:?*\[\\]+$`
	Tag string `json:"tag,omitempty"`
	// Commit is one commit, by its full 40-character id, which Ptah asks the
	// server for by that id. Unless a branch or tag points at it, Ptah asks
	// only a server that says it gives commits by id; on any other, Resolve
	// refuses the commit once its branch moves past it. A tag holds one
	// commit on every server.
	// +optional
	// +kubebuilder:validation:Pattern=`^[0-9a-f]{40}$`
	Commit string `json:"commit,omitempty"`
}

GitRef names one commit: exactly one of a branch, a tag and a commit id. +kubebuilder:validation:XValidation:rule="[has(self.branch), has(self.tag), has(self.commit)].filter(set, set).size() == 1",message="set exactly one of branch, tag and commit"

func (*GitRef) DeepCopy added in v0.2.7

func (in *GitRef) DeepCopy() *GitRef

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GitRef.

func (*GitRef) DeepCopyInto added in v0.2.7

func (in *GitRef) DeepCopyInto(out *GitRef)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type GitSourceBinding added in v0.2.7

type GitSourceBinding struct {
	// URL of the repository.
	URL string `json:"url"`
	// Ref is the branch or tag that named the commit when it resolved, or
	// the commit itself. A fetch reads the commit by the ref while the ref
	// still points at it.
	Ref GitRef `json:"ref"`
	// Commit is the full id of the commit.
	// +kubebuilder:validation:Pattern=`^[0-9a-f]{40}$`
	Commit string `json:"commit"`
	// Path is what the commit's tree selects.
	Path string `json:"path"`
	// ContentDigest is the content digest of the selected files.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	ContentDigest string `json:"contentDigest"`
	// AuthFrom names the credential Secret. It is a selector, never the
	// credential.
	// +optional
	AuthFrom *GitAuthSource `json:"authFrom,omitempty"`
	// Transport pins the server.
	// +optional
	Transport GitTransportSpec `json:"transport,omitempty"`
}

GitSourceBinding is what an operation fetches a Git source by: the repository, the ref that named the commit, the commit, the selected path, and the selectors of the credential and the trust. The operation fetches that commit again and refuses content other than ContentDigest.

func (*GitSourceBinding) DeepCopy added in v0.2.7

func (in *GitSourceBinding) DeepCopy() *GitSourceBinding

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GitSourceBinding.

func (*GitSourceBinding) DeepCopyInto added in v0.2.7

func (in *GitSourceBinding) DeepCopyInto(out *GitSourceBinding)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type GitSourceRevision added in v0.2.7

type GitSourceRevision struct {
	// URL of the repository.
	URL string `json:"url"`
	// Ref is the branch, tag or commit that was resolved.
	Ref GitRef `json:"ref"`
	// Path is what the commit's tree selects.
	Path string `json:"path"`
	// Commit is the full id of the commit the ref named.
	// +kubebuilder:validation:Pattern=`^[0-9a-f]{40}$`
	Commit string `json:"commit"`
	// ContentDigest is the content digest of the selected files at that
	// commit.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	ContentDigest string `json:"contentDigest"`
}

GitSourceRevision is the commit a Git source last resolved to, and what was asked for: another repository, ref or path in the spec is another source, and is resolved before anything reads it.

func (*GitSourceRevision) DeepCopy added in v0.2.7

func (in *GitSourceRevision) DeepCopy() *GitSourceRevision

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GitSourceRevision.

func (*GitSourceRevision) DeepCopyInto added in v0.2.7

func (in *GitSourceRevision) DeepCopyInto(out *GitSourceRevision)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type GitSourceSpec added in v0.2.7

type GitSourceSpec struct {
	// URL of the repository: https:// or ssh://, with no credential, query or
	// fragment.
	// +kubebuilder:validation:MinLength=9
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:Pattern=`^(https://[^@/[:space:]?#]+|ssh://([^:@/[:space:]?#]+@)?[^@/[:space:]?#]+)/[^[:space:]?#]+$`
	URL string `json:"url"`

	// Ref says which commit: a branch or a tag, polled at the resource's
	// interval, or a commit.
	Ref GitRef `json:"ref"`

	// Path is what the commit's tree selects: the schema file, or the
	// migration directory, where "." is the root. Relative, separated by
	// "/", with no empty or ".." element, no backslash and no control
	// character.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=1024
	// +kubebuilder:validation:Pattern=`^(\.|(?:[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.\.[^/\\\x00-\x1f\x7f]+)(?:/(?:[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.\.[^/\\\x00-\x1f\x7f]+))*)$`
	Path string `json:"path"`

	// AuthFrom names the Secret the fetch container reads the credential
	// from. The manager never reads it.
	// +optional
	AuthFrom *GitAuthSource `json:"authFrom,omitempty"`

	// Transport pins whom the fetch talks to: the CA an https:// server's
	// certificate chains to, or the host keys an ssh:// server presents.
	// +optional
	Transport GitTransportSpec `json:"transport,omitempty"`
}

GitSourceSpec selects a file or a directory of a Git repository. +kubebuilder:validation:XValidation:rule="!self.url.startsWith('ssh://') || (has(self.transport) && has(self.transport.knownHostsFrom))",message="an ssh:// repository needs transport.knownHostsFrom" +kubebuilder:validation:XValidation:rule="self.url.startsWith('ssh://') || !has(self.transport) || !has(self.transport.knownHostsFrom)",message="transport.knownHostsFrom is for an ssh:// repository" +kubebuilder:validation:XValidation:rule="!self.url.startsWith('ssh://') || !has(self.transport) || !has(self.transport.caFrom)",message="transport.caFrom is for an https:// repository"

func (*GitSourceSpec) DeepCopy added in v0.2.7

func (in *GitSourceSpec) DeepCopy() *GitSourceSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GitSourceSpec.

func (*GitSourceSpec) DeepCopyInto added in v0.2.7

func (in *GitSourceSpec) DeepCopyInto(out *GitSourceSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type GitTransportSpec added in v0.2.7

type GitTransportSpec struct {
	// CAFrom selects the only roots an https:// server's certificate may
	// chain to. With authFrom, its Secret must hold caSHA256 with the
	// selected bytes' digest, and an https:// source whose Secret holds
	// caSHA256 is refused without it.
	// +optional
	CAFrom *corev1.ConfigMapKeySelector `json:"caFrom,omitempty"`
	// KnownHostsFrom selects the host keys an ssh:// server may present; a
	// fetch never trusts a key on first use. With authFrom, its Secret must
	// hold knownHostsSHA256 with the selected bytes' digest.
	// +optional
	KnownHostsFrom *corev1.ConfigMapKeySelector `json:"knownHostsFrom,omitempty"`
}

GitTransportSpec pins the server a Git fetch talks to. +kubebuilder:validation:XValidation:rule="!has(self.caFrom) || (self.caFrom.name.size() > 0 && self.caFrom.key.size() > 0 && (!has(self.caFrom.optional) || !self.caFrom.optional))",message="caFrom must name a required ConfigMap key" +kubebuilder:validation:XValidation:rule="!has(self.knownHostsFrom) || (self.knownHostsFrom.name.size() > 0 && self.knownHostsFrom.key.size() > 0 && (!has(self.knownHostsFrom.optional) || !self.knownHostsFrom.optional))",message="knownHostsFrom must name a required ConfigMap key"

func (*GitTransportSpec) DeepCopy added in v0.2.7

func (in *GitTransportSpec) DeepCopy() *GitTransportSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GitTransportSpec.

func (*GitTransportSpec) DeepCopyInto added in v0.2.7

func (in *GitTransportSpec) DeepCopyInto(out *GitTransportSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HTTPSAuthSource added in v0.2.12

type HTTPSAuthSource struct {
	// Name of the Secret, in this resource's namespace.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
}

HTTPSAuthSource names the Secret an HTTPS fetch authenticates with. Its keys are fixed: username and password for Basic, or token for Bearer, and host, the authority host[:port] the credential is for, which the fetch holds the URL to. caSHA256 is the SHA-256 of the CA the credential may be sent under, which transport.caFrom has to select: the Secret's owner, not the resource's author, decides whom the credential is sent to.

func (*HTTPSAuthSource) DeepCopy added in v0.2.12

func (in *HTTPSAuthSource) DeepCopy() *HTTPSAuthSource

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HTTPSAuthSource.

func (*HTTPSAuthSource) DeepCopyInto added in v0.2.12

func (in *HTTPSAuthSource) DeepCopyInto(out *HTTPSAuthSource)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HTTPSFormat added in v0.2.12

type HTTPSFormat string

HTTPSFormat says how a download carries the selected files. +kubebuilder:validation:Enum=File;TarGzip;Zip

const (
	// HTTPSFormatFile is one file, the download itself. Only a schema reads
	// one.
	HTTPSFormatFile HTTPSFormat = "File"
	// HTTPSFormatTarGzip is a tar archive compressed with gzip.
	HTTPSFormatTarGzip HTTPSFormat = "TarGzip"
	// HTTPSFormatZip is a zip archive.
	HTTPSFormatZip HTTPSFormat = "Zip"
)

type HTTPSSourceBinding added in v0.2.12

type HTTPSSourceBinding struct {
	// URL of the download.
	URL string `json:"url"`
	// Digest is the SHA-256 of the bytes the URL served.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	Digest string `json:"digest"`
	// Format says how the download carries the files.
	Format HTTPSFormat `json:"format"`
	// Path is what the download selects.
	Path string `json:"path"`
	// ContentDigest is the content digest of the selected files.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	ContentDigest string `json:"contentDigest"`
	// AuthFrom names the credential Secret. It is a selector, never the
	// credential.
	// +optional
	AuthFrom *HTTPSAuthSource `json:"authFrom,omitempty"`
	// Transport pins the server.
	// +optional
	Transport HTTPSTransportSpec `json:"transport,omitempty"`
}

HTTPSSourceBinding is what an operation fetches an HTTPS source by: the download, its digest, how it carries the files, the selected path, the content digest a resolution found there, and the selectors of the credential and the trust. The operation downloads it again and refuses other bytes or other content.

func (*HTTPSSourceBinding) DeepCopy added in v0.2.12

func (in *HTTPSSourceBinding) DeepCopy() *HTTPSSourceBinding

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HTTPSSourceBinding.

func (*HTTPSSourceBinding) DeepCopyInto added in v0.2.12

func (in *HTTPSSourceBinding) DeepCopyInto(out *HTTPSSourceBinding)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HTTPSSourceRevision added in v0.2.12

type HTTPSSourceRevision struct {
	// URL of the download.
	URL string `json:"url"`
	// Format says how the download carries the files.
	Format HTTPSFormat `json:"format"`
	// Path is what the download selects.
	Path string `json:"path"`
	// Digest is the SHA-256 of the bytes the URL served.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	Digest string `json:"digest"`
	// ContentDigest is the content digest of the selected files.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	ContentDigest string `json:"contentDigest"`
}

HTTPSSourceRevision is the download an HTTPS source last resolved, and what it selected: another URL, digest, format or path in the spec is another source, and is resolved before anything reads it.

func (*HTTPSSourceRevision) DeepCopy added in v0.2.12

func (in *HTTPSSourceRevision) DeepCopy() *HTTPSSourceRevision

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HTTPSSourceRevision.

func (*HTTPSSourceRevision) DeepCopyInto added in v0.2.12

func (in *HTTPSSourceRevision) DeepCopyInto(out *HTTPSSourceRevision)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HTTPSSourceSpec added in v0.2.12

type HTTPSSourceSpec struct {
	// URL of the download: https://, with no credential, query or fragment.
	// The host is ASCII letters, digits, dots and hyphens, or an IPv6 address
	// in brackets, with an optional port: write an internationalized name in
	// its xn-- form.
	// +kubebuilder:validation:MinLength=11
	// +kubebuilder:validation:MaxLength=2048
	// +kubebuilder:validation:Pattern=`^https://([A-Za-z0-9.-]+|\[[0-9A-Fa-f.]*:[0-9A-Fa-f:.]*\])(:[0-9]{1,5})?/[^[:space:]?#]+$`
	URL string `json:"url"`

	// Digest is "sha256:" and the SHA-256 of the exact bytes the URL serves,
	// the number sha256sum prints for the file. Nothing in the download is
	// read before it matches. It is not the content digest: an archive packed
	// again with the same selected files has another digest and the same
	// content.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	Digest string `json:"digest"`

	// Format says how the download carries the files: File, the schema file
	// itself; TarGzip or Zip, an archive.
	Format HTTPSFormat `json:"format"`

	// Path is what the download selects. With File it is the one name the
	// download is given, whose extension tells a schema's format. In an
	// archive it is the schema file, or the migration directory, where "."
	// is the root. Relative, separated by "/", with no empty or ".." element,
	// no backslash and no control character.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=1024
	// +kubebuilder:validation:Pattern=`^(\.|(?:[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.\.[^/\\\x00-\x1f\x7f]+)(?:/(?:[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.[^./\\\x00-\x1f\x7f][^/\\\x00-\x1f\x7f]*|\.\.[^/\\\x00-\x1f\x7f]+))*)$`
	Path string `json:"path"`

	// AuthFrom names the Secret the fetch container reads the credential
	// from. The manager never reads it.
	// +optional
	AuthFrom *HTTPSAuthSource `json:"authFrom,omitempty"`

	// Transport pins the server: the CA its certificate chains to.
	// +optional
	Transport HTTPSTransportSpec `json:"transport,omitempty"`
}

HTTPSSourceSpec selects a file or a directory of one download, pinned by the SHA-256 of the bytes the URL serves. +kubebuilder:validation:XValidation:rule="self.format != 'File' || (self.path != '.' && !self.path.contains('/'))",message="with format File, path is the one name the download is given"

func (*HTTPSSourceSpec) DeepCopy added in v0.2.12

func (in *HTTPSSourceSpec) DeepCopy() *HTTPSSourceSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HTTPSSourceSpec.

func (*HTTPSSourceSpec) DeepCopyInto added in v0.2.12

func (in *HTTPSSourceSpec) DeepCopyInto(out *HTTPSSourceSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HTTPSTransportSpec added in v0.2.12

type HTTPSTransportSpec struct {
	// CAFrom selects the only roots the server's certificate may chain to.
	// With authFrom, its Secret must hold caSHA256 with the selected bytes'
	// digest, and a source whose Secret holds caSHA256 is refused without
	// it.
	// +optional
	CAFrom *corev1.ConfigMapKeySelector `json:"caFrom,omitempty"`
}

HTTPSTransportSpec pins the server an HTTPS fetch talks to. +kubebuilder:validation:XValidation:rule="!has(self.caFrom) || (self.caFrom.name.size() > 0 && self.caFrom.key.size() > 0 && (!has(self.caFrom.optional) || !self.caFrom.optional))",message="caFrom must name a required ConfigMap key"

func (*HTTPSTransportSpec) DeepCopy added in v0.2.12

func (in *HTTPSTransportSpec) DeepCopy() *HTTPSTransportSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HTTPSTransportSpec.

func (*HTTPSTransportSpec) DeepCopyInto added in v0.2.12

func (in *HTTPSTransportSpec) DeepCopyInto(out *HTTPSTransportSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ImmutableObjectReference

type ImmutableObjectReference struct {
	// Name of the referenced object in the same namespace.
	Name string `json:"name"`
	// UID the object had when the reference was written. An object deleted and
	// recreated under the same name is a different object, and this says so.
	UID types.UID `json:"uid"`
}

ImmutableObjectReference binds a name to the UID that existed when the reference was created, preventing delete-and-recreate aliasing.

func (*ImmutableObjectReference) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ImmutableObjectReference.

func (*ImmutableObjectReference) DeepCopyInto

func (in *ImmutableObjectReference) DeepCopyInto(out *ImmutableObjectReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type JobConditionType

type JobConditionType = batchv1.JobConditionType

JobConditionType is retained as an alias for consumers that need to compare terminal execution state without importing the batch API separately.

type JournalEntry added in v0.2.7

type JournalEntry struct {
	// Type is the kind of event.
	Type JournalEntryType `json:"type"`

	// At is when the event happened. For an Apply, a run or a failed attempt
	// it is when that ended.
	At metav1.Time `json:"at"`

	// StartedAt is when an Apply or a run began.
	// +optional
	StartedAt *metav1.Time `json:"startedAt,omitempty"`

	// LastAt is the latest attempt an OperationFailed entry folds. A single
	// failure has none.
	// +optional
	LastAt *metav1.Time `json:"lastAt,omitempty"`
	// Count is how many attempts an OperationFailed entry stands for. A single
	// failure has none.
	// +kubebuilder:validation:Minimum=2
	// +optional
	Count int32 `json:"count,omitempty"`

	// OperationID is the Apply claim an entry concerns: a PtahSchema's
	// ApplyFinished and the Verified entry of the proof after it, or a
	// PtahMigration's RunFinished, Verified or RunAcknowledged. It is what joins
	// them: entries of one execution carry the same one, and neither their order
	// nor their times are the join. ApprovalUID is what joins an
	// ApprovalAccepted entry to the Apply or the run that consumed it, since a
	// claim withdrawn before dispatch leaves the approval to the next one. An
	// entry a release before this field wrote has none.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	// +optional
	OperationID string `json:"operationID,omitempty"`

	// Plan names the plan the event concerns.
	// +kubebuilder:validation:MaxLength=253
	// +optional
	Plan string `json:"plan,omitempty"`
	// PlanUID is the UID of the plan an Apply or a run carried out, or of the
	// plan a PtahMigration's approval was accepted for.
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MaxLength=128
	// +optional
	PlanUID types.UID `json:"planUID,omitempty"`
	// PlanFingerprint is the spec.fingerprint of the plan an Apply or a run
	// carried out, when the claim recorded it.
	// +kubebuilder:validation:MaxLength=128
	// +optional
	PlanFingerprint string `json:"planFingerprint,omitempty"`

	// Statements is how many statements a published PtahSchema plan holds.
	// +kubebuilder:validation:Minimum=0
	// +optional
	Statements int32 `json:"statements,omitempty"`
	// Destructive reports a published PtahSchema plan that destroys data.
	// +optional
	Destructive bool `json:"destructive,omitempty"`
	// ApprovalRequired reports a published PtahSchema plan that asked for a
	// person's approval when it was published.
	// +optional
	ApprovalRequired bool `json:"approvalRequired,omitempty"`
	// Replaced names the plan a published PtahSchema plan took the place of: one
	// a person could approve, or had approved, and that never ran. A PlanStale
	// Warning reports the same replacement, and an Event can be lost.
	// +kubebuilder:validation:MaxLength=253
	// +optional
	Replaced string `json:"replaced,omitempty"`

	// Authorization is what allowed a PtahMigration's run.
	// +optional
	Authorization MigrationRunAuthorizationKind `json:"authorization,omitempty"`
	// Approval names the approval an Apply consumed. A name can be used again by
	// a later decision, so it does not say which object it was: ApprovalUID does.
	// +kubebuilder:validation:MaxLength=253
	// +optional
	Approval string `json:"approval,omitempty"`
	// ApprovalUID is the UID of that approval. An entry a release before this
	// field wrote has none: it is incomplete evidence, and is not to be joined
	// to an object that holds the name today.
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MaxLength=128
	// +optional
	ApprovalUID types.UID `json:"approvalUID,omitempty"`
	// Approver is the user admission stamped on that approval, cut to the first
	// 512 characters where the name is longer.
	// +kubebuilder:validation:MaxLength=512
	// +optional
	Approver string `json:"approver,omitempty"`

	// Outcome is how an Apply, a proof or a run ended. On a PtahMigration's
	// Verified entry it is what the reading after the run found, and on a
	// RunAcknowledged entry how the run that person settled ended.
	// +optional
	Outcome JournalOutcome `json:"outcome,omitempty"`

	// Operation is the operation that failed, when one was claimed.
	// +kubebuilder:validation:Enum=Resolve;Verify;Observe;Plan;History;Apply
	// +optional
	Operation string `json:"operation,omitempty"`
	// Reason is the condition reason the failure set. It is a code, never the
	// message: a message can carry what status must not.
	// +kubebuilder:validation:MaxLength=128
	// +kubebuilder:validation:Pattern=`^[A-Z][A-Za-z0-9]*$`
	// +optional
	Reason string `json:"reason,omitempty"`

	// JobName is the Job an Apply or a run ran as. It is absent when no Job
	// was confirmed.
	// +kubebuilder:validation:MaxLength=253
	// +optional
	JobName string `json:"jobName,omitempty"`
	// JobUID is that Job's UID, which outlives the Job and tells it from a later
	// Job that takes the name.
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MaxLength=128
	// +optional
	JobUID types.UID `json:"jobUID,omitempty"`

	// AppliedVersions is how many migrations a run recorded applied.
	// +kubebuilder:validation:Minimum=0
	// +optional
	AppliedVersions int32 `json:"appliedVersions,omitempty"`
	// Failure is where a PtahMigration's run stopped, as
	// status.lastRun.failure said.
	// +optional
	Failure *MigrationRunFailureStatus `json:"failure,omitempty"`
	// MigrationLog is what a PtahMigration's run wrote to the database's own
	// record of migrations, as status.lastRun.migrationLog said. A run whose
	// lost count is not zero left that record incomplete.
	// +optional
	MigrationLog *MigrationLogStatus `json:"migrationLog,omitempty"`
	// ApplyFailure is where a PtahSchema's Apply stopped, as
	// status.pendingObservation.applyFailure said. An Apply that ends Unknown
	// carries it when the run named the statement it stopped at.
	// +optional
	ApplyFailure *SchemaApplyFailureStatus `json:"applyFailure,omitempty"`

	// Acknowledgment names the acknowledgment that settled an unresolved run.
	// +kubebuilder:validation:MaxLength=253
	// +optional
	Acknowledgment string `json:"acknowledgment,omitempty"`
	// AcknowledgedBy is the user admission stamped on that acknowledgment, cut to
	// the first 512 characters where the name is longer.
	// +kubebuilder:validation:MaxLength=512
	// +optional
	AcknowledgedBy string `json:"acknowledgedBy,omitempty"`
}

JournalEntry is one event. Which fields it carries depends on its type, and every name it carries is an object in the resource's namespace.

func (*JournalEntry) DeepCopy added in v0.2.7

func (in *JournalEntry) DeepCopy() *JournalEntry

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new JournalEntry.

func (*JournalEntry) DeepCopyInto added in v0.2.7

func (in *JournalEntry) DeepCopyInto(out *JournalEntry)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type JournalEntryType added in v0.2.7

type JournalEntryType string

JournalEntryType is the kind of event a journal entry records. +kubebuilder:validation:Enum=PlanPublished;ApprovalAccepted;ApplyFinished;Verified;RunFinished;RunAcknowledged;OperationFailed

const (
	// JournalPlanPublished is a new plan in status.plan.
	JournalPlanPublished JournalEntryType = "PlanPublished"
	// JournalApprovalAccepted is the approval an Apply consumed: the one a
	// PtahSchema's plan recorded, or the one a PtahMigration's Apply claim
	// names. One entry stands for one decision, told apart by the approval's UID:
	// a later decision may take the same name.
	JournalApprovalAccepted JournalEntryType = "ApprovalAccepted"
	// JournalApplyFinished is a PtahSchema Apply that ended: one entry per
	// execution.
	JournalApplyFinished JournalEntryType = "ApplyFinished"
	// JournalVerified is the post-Apply observation of a PtahSchema settling, or
	// the first reading of a PtahMigration's history after a run.
	JournalVerified JournalEntryType = "Verified"
	// JournalRunFinished is a PtahMigration run that ended: one entry per
	// execution. A run that ends Partial or Unknown also holds the resource in
	// status.unresolvedRun, and that hold writes no entry of its own. A hold
	// restored without the status that held its run is that run's entry, with
	// the outcome the hold recorded.
	JournalRunFinished JournalEntryType = "RunFinished"
	// JournalRunAcknowledged is an unresolved run a person acknowledged.
	JournalRunAcknowledged JournalEntryType = "RunAcknowledged"
	// JournalOperationFailed is a failed attempt. Attempts that fail with the
	// same operation and reason in a row are one entry with a count.
	JournalOperationFailed JournalEntryType = "OperationFailed"
)

type JournalOutcome added in v0.2.7

type JournalOutcome string

JournalOutcome is how an Apply, a proof or a run ended. +kubebuilder:validation:Enum=Succeeded;Failed;Partial;Unknown;UpToDate;InSync;DriftRemains;Superseded;Pending;Blocked

const (
	// JournalSucceeded is an Apply that completed, or a run that applied what
	// it selected.
	JournalSucceeded JournalOutcome = "Succeeded"
	// JournalFailed is an Apply or a run that failed and committed nothing.
	JournalFailed JournalOutcome = "Failed"
	// JournalPartial is a run that committed part of a migration.
	JournalPartial JournalOutcome = "Partial"
	// JournalUnknown is an Apply or a run whose effect on the database nobody
	// established.
	JournalUnknown JournalOutcome = "Unknown"
	// JournalUpToDate is a run that found nothing to apply.
	JournalUpToDate JournalOutcome = "UpToDate"
	// JournalInSync is a proof that found the database matching the plan.
	JournalInSync JournalOutcome = "InSync"
	// JournalDriftRemains is a proof that still found changes to make.
	JournalDriftRemains JournalOutcome = "DriftRemains"
	// JournalSuperseded is a proof that settled under a newer generation or
	// policy, which decides what follows.
	JournalSuperseded JournalOutcome = "Superseded"
	// JournalPending is a reading after a migration run that found the artifact
	// has more to apply.
	JournalPending JournalOutcome = "Pending"
	// JournalBlocked is a reading after a migration run of a history nothing may
	// run against.
	JournalBlocked JournalOutcome = "Blocked"
)

type LifecycleJournal added in v0.2.7

type LifecycleJournal struct {
	// CoveredSince is the instant from which the journal is complete: when a
	// manager that keeps a journal first wrote this resource's status, moved
	// forward past the newest entry a bound has since dropped. A reader states
	// the period the journal covers from it and assumes nothing before, though
	// the entries of a plan nothing has carried out yet can be older.
	CoveredSince metav1.Time `json:"coveredSince"`

	// Entries are the events, oldest first. There are at most 64, and none is
	// more than 30 days older than the newest, apart from the plan nothing has
	// carried out yet: the entry that published it and the newest approval of it
	// stay until something carries it out or another plan is published.
	// +listType=atomic
	// +kubebuilder:validation:MaxItems=64
	// +optional
	Entries []JournalEntry `json:"entries,omitempty"`
}

LifecycleJournal is the bounded record of a resource's significant lifecycle events: a plan published, an approval accepted, an Apply or a run and how it ended, the proof that followed, and failed attempts. A read-only cycle that changes nothing writes nothing here. The manager derives every entry from the status write that records the transition, so the journal costs no request of its own.

func (*LifecycleJournal) DeepCopy added in v0.2.7

func (in *LifecycleJournal) DeepCopy() *LifecycleJournal

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LifecycleJournal.

func (*LifecycleJournal) DeepCopyInto added in v0.2.7

func (in *LifecycleJournal) DeepCopyInto(out *LifecycleJournal)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type LimitRangeAdmissionSnapshot

type LimitRangeAdmissionSnapshot struct {
	// Object is the LimitRange this was read from.
	Object AdmissionObjectBinding `json:"object"`
	// +kubebuilder:validation:MaxProperties=64
	// DefaultRequests are the requests it would add to a container that asks
	// for none.
	DefaultRequests map[corev1.ResourceName]resource.Quantity `json:"defaultRequests,omitempty"`
	// +kubebuilder:validation:MaxProperties=64
	// DefaultLimits are the limits it would add.
	DefaultLimits map[corev1.ResourceName]resource.Quantity `json:"defaultLimits,omitempty"`
}

LimitRangeAdmissionSnapshot contains only the container defaults that can legitimately fill resource keys absent from the submitted Job template.

func (*LimitRangeAdmissionSnapshot) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LimitRangeAdmissionSnapshot.

func (*LimitRangeAdmissionSnapshot) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ManagerRecord

type ManagerRecord struct {
	// ControllerImage is the digest-pinned manager image.
	// +kubebuilder:validation:Pattern=`^[^[:space:]@]+@sha256:[0-9a-f]{64}$`
	// +kubebuilder:validation:MaxLength=512
	ControllerImage string `json:"controllerImage"`
	// ControllerRevision is the source revision the manager was built from.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	// +kubebuilder:validation:Pattern=`^[^[:space:][:cntrl:]]([^[:cntrl:]]*[^[:space:][:cntrl:]])?$`
	ControllerRevision string `json:"controllerRevision"`
	// RunnerImage is the digest-pinned runner image the manager installed in
	// the task Pod.
	// +kubebuilder:validation:Pattern=`^[^[:space:]@]+@sha256:[0-9a-f]{64}$`
	// +kubebuilder:validation:MaxLength=512
	RunnerImage string `json:"runnerImage"`
}

ManagerRecord names one release of the manager: its image, its revision and the runner image built from the same source. It is audit evidence and binds nothing -- a release that changes only these values keeps every plan and approval -- so it is written where a reader needs to know which build did something after the Job that ran it has been collected.

func (*ManagerRecord) DeepCopy

func (in *ManagerRecord) DeepCopy() *ManagerRecord

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ManagerRecord.

func (*ManagerRecord) DeepCopyInto

func (in *ManagerRecord) DeepCopyInto(out *ManagerRecord)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type MigrationHistoryStatus

type MigrationHistoryStatus struct {
	// ObservedAt is when the history was read.
	ObservedAt metav1.Time `json:"observedAt"`

	// ContractVersion is the version of Ptah's status document this summary was
	// read from. A version the controller does not know is refused before the
	// database is touched rather than read as if it meant the same thing.
	// +kubebuilder:validation:Minimum=1
	ContractVersion int32 `json:"contractVersion"`

	// CurrentVersion is the highest version the revision table records.
	// +kubebuilder:validation:Minimum=0
	CurrentVersion int64 `json:"currentVersion"`

	// CheckpointVersion is the checkpoint covering the versions below it, and
	// zero where none applies. It stays set after the bootstrap has run: the
	// coverage is what keeps those versions applied rather than pending.
	// +kubebuilder:validation:Minimum=0
	CheckpointVersion int64 `json:"checkpointVersion,omitempty"`

	// AppliedCount and PendingCount describe the artifact against this history.
	// +kubebuilder:validation:Minimum=0
	AppliedCount int32 `json:"appliedCount"`
	// PendingCount is how many the artifact still has to apply, as Ptah selects
	// them rather than as a subtraction of the two counts.
	// +kubebuilder:validation:Minimum=0
	PendingCount int32 `json:"pendingCount"`

	// Fingerprint is this exact reading of the revision table. A plan names it
	// as its premise, and a history that moved between planning and execution
	// invalidates the plan rather than being applied to.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	Fingerprint string `json:"fingerprint"`

	// TargetIdentityDigest is the credential-free identity of the database this
	// history was read from, as the executor derived it. A plan that was made
	// against one database is never executed against another.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	TargetIdentityDigest string `json:"targetIdentityDigest"`

	// Dirty reports a revision row a failed or interrupted run left behind.
	// Nothing applies while one exists.
	Dirty bool `json:"dirty,omitempty"`

	// ModifiedVersions names applied migrations whose files no longer account
	// for them. It is the refusal a versioned workflow exists to make, so the
	// versions are published rather than summarized.
	// +listType=set
	// +kubebuilder:validation:MaxItems=64
	ModifiedVersions []int64 `json:"modifiedVersions,omitempty"`

	// OutOfOrderVersions names migrations the artifact carries below a version
	// the database has already applied. Linear execution refuses them, so the
	// versions are published rather than counted: what a person decides here
	// depends on which migration arrived late.
	// +listType=set
	// +kubebuilder:validation:MaxItems=64
	OutOfOrderVersions []int64 `json:"outOfOrderVersions,omitempty"`

	// Revisions are the newest rows of the revision table, newest first: which
	// migration each records, the checksum it recorded, when it was written
	// and how long the migration ran. At most MaxMigrationRevisions are kept,
	// so a list that long may leave older rows out. No SQL and no error text
	// is read into them.
	// +optional
	// +listType=map
	// +listMapKey=version
	// +kubebuilder:validation:MaxItems=64
	Revisions []MigrationRevisionStatus `json:"revisions,omitempty"`
}

MigrationHistoryStatus is what the database's own revision table said when the controller last read it.

It is a summary of evidence, not a decision: the counts and flags let a reader see why the controller is planning, blocked, or idle without reading the database itself.

func (*MigrationHistoryStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MigrationHistoryStatus.

func (*MigrationHistoryStatus) DeepCopyInto

func (in *MigrationHistoryStatus) DeepCopyInto(out *MigrationHistoryStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type MigrationLogEntryState added in v0.2.12

type MigrationLogEntryState string

MigrationLogEntryState is what a migration log entry records. +kubebuilder:validation:Enum=Started;Applied;Failed

const (
	// MigrationLogEntryStarted is the entry written before a migration runs.
	MigrationLogEntryStarted MigrationLogEntryState = "Started"
	// MigrationLogEntryApplied is the entry written after it applied.
	MigrationLogEntryApplied MigrationLogEntryState = "Applied"
	// MigrationLogEntryFailed is the entry written after it failed.
	MigrationLogEntryFailed MigrationLogEntryState = "Failed"
)

type MigrationLogLossStatus added in v0.2.12

type MigrationLogLossStatus struct {
	// Version is the migration the entry is about.
	// +kubebuilder:validation:Minimum=1
	Version int64 `json:"version"`
	// State is what the entry would have recorded.
	State MigrationLogEntryState `json:"state"`
	// SQLState is the SQLSTATE the database answered with, empty when it gave
	// none.
	// +kubebuilder:validation:Pattern=`^[0-9A-Z]{5}$`
	// +optional
	SQLState string `json:"sqlState,omitempty"`
	// ErrorNumber is MySQL's own error number, such as 1406 for a value too
	// long for its column, and zero on every other protocol.
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=65535
	// +optional
	ErrorNumber int32 `json:"errorNumber,omitempty"`
}

MigrationLogLossStatus is one entry the database refused.

func (*MigrationLogLossStatus) DeepCopy added in v0.2.12

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MigrationLogLossStatus.

func (*MigrationLogLossStatus) DeepCopyInto added in v0.2.12

func (in *MigrationLogLossStatus) DeepCopyInto(out *MigrationLogLossStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type MigrationLogStatus added in v0.2.12

type MigrationLogStatus struct {
	// Written is how many of the run's entries the database accepted.
	// +kubebuilder:validation:Minimum=0
	Written int32 `json:"written"`
	// Lost is how many it refused. The record of the run is incomplete when
	// it is not zero.
	// +kubebuilder:validation:Minimum=0
	Lost int32 `json:"lost"`
	// Losses are the first sixteen entries the database refused, in the order
	// the run tried them.
	// +listType=atomic
	// +kubebuilder:validation:MaxItems=16
	// +optional
	Losses []MigrationLogLossStatus `json:"losses,omitempty"`
}

MigrationLogStatus is what a run's writes to schema_migrations_log came to: the table Ptah keeps beside the revision table, with an entry before each migration a run starts and one after it applied or failed, naming the actor, the approver for a run a person approved. It is the record of the run that stays with the database after the cluster is gone.

The database can refuse an entry and keep the migration, as MySQL refuses a value longer than the table's column holds. The run carries on, so its outcome, which Ptah reads from the revision table, is unchanged, and nothing writes the entry later. This says how many entries the record lacks and why, with the code the database answered and none of its message, which can quote the value it refused. +kubebuilder:validation:XValidation:rule="has(self.losses) ? size(self.losses) == (self.lost < 16 ? self.lost : 16) : self.lost == 0",message="losses lists the first lost entries, up to 16, and lost counts them all"

func (*MigrationLogStatus) DeepCopy added in v0.2.12

func (in *MigrationLogStatus) DeepCopy() *MigrationLogStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MigrationLogStatus.

func (*MigrationLogStatus) DeepCopyInto added in v0.2.12

func (in *MigrationLogStatus) DeepCopyInto(out *MigrationLogStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type MigrationOperationStatus

type MigrationOperationStatus struct {
	// Type is the operation this claim authorizes.
	Type MigrationOperationType `json:"type"`

	// ID is this attempt's identity, distinct from every other attempt of the
	// same operation.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	ID string `json:"id"`

	// InputFingerprint is what the operation was decided from. An input that
	// changed while the Job ran is what makes its result stale rather than
	// wrong.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	InputFingerprint string `json:"inputFingerprint"`

	// JobName is the deterministic name this claim's Job takes. It is written
	// before the Job is created.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	JobName string `json:"jobName"`

	// JobUID is the exact Job the claim is bound to, once one exists. A Job
	// with the right name and another UID is a different Job.
	JobUID types.UID `json:"jobUID,omitempty"`

	// StartedAt is when the claim was written, which is before the Job exists.
	StartedAt metav1.Time `json:"startedAt"`

	// RetryNotBefore is when a retried attempt may be dispatched. A retry
	// carries the delay the resource asked for, and carrying it here rather
	// than in a requeue is what makes it survive a restart and an early Job or
	// watch event: those re-enter reconciliation at once, and a delay that
	// lived only in a requeue would be lost with the queue.
	//
	// Absent on a first attempt, which waits for nothing.
	RetryNotBefore *metav1.Time `json:"retryNotBefore,omitempty"`

	// Attempt counts this claim among the retries of the same operation.
	// +kubebuilder:validation:Minimum=1
	Attempt int32 `json:"attempt"`

	// ExecutionBindingID is the epoch this claim was authorized under. A
	// rollout that changes a bound execution component retires the claim
	// rather than letting its Job finish under new semantics.
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	ExecutionBindingID string `json:"executionBindingID"`

	// Source is the credential-free artifact binding this operation uses:
	// the resolved digest and the selectors needed to fetch it. Every operation
	// after Resolve carries one, so a newer generation cannot send newly
	// selected credentials to the old artifact's registry.
	Source *SourceAccessBinding `json:"source,omitempty"`

	// Target is the key-free database binding, and CoordinationDigest the realm
	// the operation serializes against.
	Target *DatabaseTargetBinding `json:"target,omitempty"`
	// CoordinationDigest is that realm, hashed.
	CoordinationDigest string `json:"coordinationDigest,omitempty"`

	// PlanRef is the immutable plan an Apply carries out.
	PlanRef *ImmutableObjectReference `json:"planRef,omitempty"`
	// PlanFingerprint is that plan's spec.fingerprint, copied when the claim is
	// written so the record of the run can name it after the plan is gone. A
	// claim written by a release without this field has none.
	// +kubebuilder:validation:MaxLength=128
	// +optional
	PlanFingerprint string `json:"planFingerprint,omitempty"`

	// DispatchStarted records that the one permitted Job create attempt was
	// made. An Apply that crossed this boundary is never recreated, because
	// whether it ran is a question for the database rather than for a retry.
	DispatchStarted bool `json:"dispatchStarted,omitempty"`

	// DispatchNotAfter and ExecutionNotAfter bound the claim in time.
	DispatchNotAfter *metav1.Time `json:"dispatchNotAfter,omitempty"`
	// ExecutionNotAfter is when the authorized run itself expires.
	ExecutionNotAfter *metav1.Time `json:"executionNotAfter,omitempty"`

	// LeaseEpoch is the database lock acquisition this claim was authorized
	// under, and LeaseDurationSeconds how long that acquisition was taken for.
	// A result produced across an epoch change is discarded rather than read:
	// the lock it held was somebody else's by then.
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	LeaseEpoch string `json:"leaseEpoch,omitempty"`
	// LeaseDurationSeconds is how long that acquisition was taken for.
	// +kubebuilder:validation:Minimum=1
	LeaseDurationSeconds int32 `json:"leaseDurationSeconds,omitempty"`
	// LeaseContinuityLost records that the epoch changed under this claim.
	LeaseContinuityLost bool `json:"leaseContinuityLost,omitempty"`

	// ApprovalRef is the approval that authorized this Apply, recorded before
	// dispatch so the run is attributable to the decision that permitted it.
	ApprovalRef *ImmutableObjectReference `json:"approvalRef,omitempty"`
	// ApprovedBy is the identity admission stamped on that approval, copied when
	// the claim is written so the record of the run can name it after the
	// approval is gone. A claim written by a release without this field has none.
	// +optional
	ApprovedBy *ApprovalIdentity `json:"approvedBy,omitempty"`
	// ApprovedAt is when admission stamped it.
	// +optional
	ApprovedAt *metav1.Time `json:"approvedAt,omitempty"`

	// Actor is the name this Apply writes to the database's own migration log:
	// the username admission stamped on the approval ApprovalRef names, or,
	// under apply: Always, a fixed name that says no person approved. The value
	// is personal data when it names a person, and the run writes it to the
	// target database.
	//
	// It is percent-encoded so that every character set stores it and the kubelet
	// expands nothing in it: each byte outside 0x20-0x7E, and % and $, are %XX,
	// and a name over the bound is cut between characters and ends in "...". The
	// rest of printable ASCII reads unchanged, and the schema refuses any other
	// form.
	//
	// The claim keeps its own copy so the Job it builds stays the same whatever
	// happens to the approval afterwards. A claim written by a release without
	// this field has none, and its Job sets no actor, so a later manager still
	// builds the Job that release dispatched and adopts it.
	// +kubebuilder:validation:MaxLength=256
	// +kubebuilder:validation:Pattern=`^([ -#&-~]|%([01][0-9A-F]|2[45]|7F|[89A-F][0-9A-F]))*$`
	Actor string `json:"actor,omitempty"`

	// AdmissionSnapshot is the Pod envelope resolved before dispatch and bound
	// into the Job and its Pod template. It is what lets Pod admission permit
	// the built-in mutations that are modeled and safe while refusing any other
	// change to what the Pod executes. A migration Pod is judged by the same
	// envelope as a schema Pod, because it is the same kind of Pod.
	AdmissionSnapshot *PodAdmissionSnapshot `json:"admissionSnapshot,omitempty"`
	// AdmissionSnapshotRefreshed records that this claim's admission snapshot
	// was resolved a second time, because the Job template this manager
	// builds differed from the one the snapshot recorded before anything was
	// dispatched. That happens once, when a manager release that shares the
	// execution binding takes over an undispatched claim. It happens at most
	// once per claim: a template that differs again comes from a builder that
	// does not build the same Job twice, and the claim is retired instead.
	AdmissionSnapshotRefreshed bool `json:"admissionSnapshotRefreshed,omitempty"`
}

MigrationOperationStatus is one durable claim: the work the controller decided on, before the Job that carries it exists.

It is durable because the Job is not the record. A claim written first, with the Job's deterministic name in it, is what lets a controller that restarts mid-dispatch tell the Job it created from one it has not created yet -- and what lets admission refuse a Job that no claim asked for.

func (*MigrationOperationStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MigrationOperationStatus.

func (*MigrationOperationStatus) DeepCopyInto

func (in *MigrationOperationStatus) DeepCopyInto(out *MigrationOperationStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type MigrationOperationType

type MigrationOperationType string

MigrationOperationType is one step of a migration lifecycle. Each one is a Job, and each Job belongs to exactly one claim. +kubebuilder:validation:Enum=Resolve;Verify;History;Apply

const (
	// MigrationOperationResolve turns the artifact reference into a digest.
	MigrationOperationResolve MigrationOperationType = "Resolve"
	// MigrationOperationVerify checks the resolved artifact against its policy.
	MigrationOperationVerify MigrationOperationType = "Verify"
	// MigrationOperationHistory reads the database's own revision table against
	// the artifact and changes nothing.
	MigrationOperationHistory MigrationOperationType = "History"
	// MigrationOperationApply runs the planned sequence.
	MigrationOperationApply MigrationOperationType = "Apply"
)

type MigrationPhase

type MigrationPhase string

MigrationPhase is the coarse state of one PtahMigration, for a person reading `kubectl get`. Conditions carry the machine-readable account. +kubebuilder:validation:Enum=Pending;Resolving;Verifying;Reading;Planning;AwaitingApproval;Blocked;Applying;VerifyingHistory;InSync;Suspended;Failed

const (
	// MigrationPhasePending is a migration the controller has not yet acted on.
	MigrationPhasePending MigrationPhase = "Pending"
	// MigrationPhaseResolving is resolving the artifact reference to a digest.
	MigrationPhaseResolving MigrationPhase = "Resolving"
	// MigrationPhaseVerifying is verifying the artifact against its policy.
	MigrationPhaseVerifying MigrationPhase = "Verifying"
	// MigrationPhaseReading is reading the database's own migration history.
	MigrationPhaseReading MigrationPhase = "Reading"
	// MigrationPhasePlanning is selecting the pending sequence.
	MigrationPhasePlanning MigrationPhase = "Planning"
	// MigrationPhaseAwaitingApproval is a published plan waiting for the exact
	// approval its policy requires.
	MigrationPhaseAwaitingApproval MigrationPhase = "AwaitingApproval"
	// MigrationPhaseBlocked is a resource the controller stopped: a history this
	// artifact cannot continue, such as a modified applied migration or a dirty
	// row, which it never resolves by writing to the database, a run nobody
	// accounted for, an unsupported engine, a realm that does not admit it, or
	// an artifact its verification policy refused, which it reads again at its
	// interval.
	MigrationPhaseBlocked MigrationPhase = "Blocked"
	// MigrationPhaseApplying is an execution Job in flight.
	MigrationPhaseApplying MigrationPhase = "Applying"
	// MigrationPhaseVerifyingHistory is reading the history back to confirm
	// what the run did.
	MigrationPhaseVerifyingHistory MigrationPhase = "VerifyingHistory"
	// MigrationPhaseInSync is a history that matches the artifact with nothing
	// pending.
	MigrationPhaseInSync MigrationPhase = "InSync"
	// MigrationPhaseSuspended is a resource whose spec asked for no new work.
	MigrationPhaseSuspended MigrationPhase = "Suspended"
	// MigrationPhaseFailed is a run that failed and may be retried once its
	// cause is fixed.
	MigrationPhaseFailed MigrationPhase = "Failed"
)

type MigrationPolicy

type MigrationPolicy struct {
	// Apply defaults to OnApproval. A migration artifact carries arbitrary SQL,
	// and no analyzer classifies arbitrary SQL as safe, so the conservative
	// setting is the default one rather than the one an operator opts into.
	// +kubebuilder:default=OnApproval
	Apply ApplyPolicy `json:"apply,omitempty"`

	// LockTimeout bounds the wait for the database's own migration lock. It is
	// the lock the engine takes, not the Kubernetes Lease: two controllers that
	// never run at the same time still need the database to serialize them.
	// +kubebuilder:default="5m"
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MaxLength=32
	// +kubebuilder:validation:XValidation:rule="duration(self) >= duration('1s') && duration(self) <= duration('1h')",message="policy.lockTimeout must be between 1s and 1h"
	LockTimeout metav1.Duration `json:"lockTimeout,omitempty"`

	// TransactionMode is how Ptah is asked to wrap the run: "file" for one
	// transaction per migration file, "none" to wrap nothing. The spellings are
	// Ptah's own.
	//
	// Unset passes no mode and Ptah chooses. There is no default here on
	// purpose: one would change how every stored resource already runs, and
	// would pin this API to a value Ptah is free to move.
	//
	// A MySQL-family database refuses "file" whenever an interceptor is
	// installed, so this is a requirement to check against the target rather
	// than a preference. The migration lifecycle section of the architecture
	// reference says what the operator does with the answer.
	// +kubebuilder:validation:Enum=file;none
	TransactionMode string `json:"transactionMode,omitempty"`
}

MigrationPolicy decides when a planned sequence may execute.

func (*MigrationPolicy) DeepCopy

func (in *MigrationPolicy) DeepCopy() *MigrationPolicy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MigrationPolicy.

func (*MigrationPolicy) DeepCopyInto

func (in *MigrationPolicy) DeepCopyInto(out *MigrationPolicy)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type MigrationRevisionState added in v0.2.7

type MigrationRevisionState string

MigrationRevisionState is Ptah's verdict on one revision row. +kubebuilder:validation:Enum=applied;modified;dirty

const (
	// MigrationRevisionApplied is a row whose file still accounts for it.
	MigrationRevisionApplied MigrationRevisionState = "applied"
	// MigrationRevisionModified is a row whose file no longer accounts for it.
	MigrationRevisionModified MigrationRevisionState = "modified"
	// MigrationRevisionDirty is the row a failed or interrupted run left.
	MigrationRevisionDirty MigrationRevisionState = "dirty"
)

type MigrationRevisionStatus added in v0.2.7

type MigrationRevisionStatus struct {
	// Version is the migration the row records.
	// +kubebuilder:validation:Minimum=1
	Version int64 `json:"version"`

	// Description is the migration's own, from its file name.
	// +optional
	// +kubebuilder:validation:MaxLength=255
	Description string `json:"description,omitempty"`

	// Checksum is what the row recorded when the migration ran. A dirty row
	// records none.
	// +optional
	// +kubebuilder:validation:MaxLength=128
	Checksum string `json:"checksum,omitempty"`

	// State is applied, modified when the file no longer accounts for the
	// row, or dirty when a run left it unfinished.
	State MigrationRevisionState `json:"state"`

	// AppliedAt is when the row was written.
	// +optional
	AppliedAt *metav1.Time `json:"appliedAt,omitempty"`

	// ExecutionMillis is how long the migration ran, in whole milliseconds.
	// A revision table too old to record a duration leaves it absent rather
	// than zero.
	// +optional
	// +kubebuilder:validation:Minimum=0
	ExecutionMillis *int64 `json:"executionMillis,omitempty"`
}

MigrationRevisionStatus is one row of the revision table, as the history read found it.

func (*MigrationRevisionStatus) DeepCopy added in v0.2.7

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MigrationRevisionStatus.

func (*MigrationRevisionStatus) DeepCopyInto added in v0.2.7

func (in *MigrationRevisionStatus) DeepCopyInto(out *MigrationRevisionStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type MigrationRunAuthorizationKind added in v0.2.10

type MigrationRunAuthorizationKind string

MigrationRunAuthorizationKind says what allowed a run. +kubebuilder:validation:Enum=Approval;Policy

const (
	// MigrationRunAuthorizedByApproval is a run a person's approval allowed.
	MigrationRunAuthorizedByApproval MigrationRunAuthorizationKind = "Approval"
	// MigrationRunAuthorizedByPolicy is a run spec.policy.apply Always allowed,
	// with nobody's decision in it.
	MigrationRunAuthorizedByPolicy MigrationRunAuthorizationKind = "Policy"
)

type MigrationRunAuthorizationStatus added in v0.2.10

type MigrationRunAuthorizationStatus struct {
	// Kind is Approval or Policy.
	Kind MigrationRunAuthorizationKind `json:"kind"`
	// ApprovalRef is the approval the run consumed.
	// +optional
	ApprovalRef *ImmutableObjectReference `json:"approvalRef,omitempty"`
	// Approver is the identity admission stamped on it.
	// +optional
	Approver *ApprovalIdentity `json:"approver,omitempty"`
	// ApprovedAt is when admission stamped it.
	// +optional
	ApprovedAt *metav1.Time `json:"approvedAt,omitempty"`
}

MigrationRunAuthorizationStatus is what allowed a run. An approval's name and UID are always known. The identity and time admission stamped on it are absent for a claim a release without those fields wrote: they stay unknown, since reading them back from an approval that holds the name today would be a guess. +kubebuilder:validation:XValidation:rule="self.kind == 'Approval' ? has(self.approvalRef) : !has(self.approvalRef) && !has(self.approver) && !has(self.approvedAt)",message="an approval authorization names its approval, and a policy authorization names no decision"

func (*MigrationRunAuthorizationStatus) DeepCopy added in v0.2.10

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MigrationRunAuthorizationStatus.

func (*MigrationRunAuthorizationStatus) DeepCopyInto added in v0.2.10

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type MigrationRunFailureStatus added in v0.2.7

type MigrationRunFailureStatus struct {
	// Version is the migration the run stopped in.
	// +kubebuilder:validation:Minimum=0
	Version int64 `json:"version"`
	// Statement is the position of the failed statement in that migration,
	// counting from one.
	// +kubebuilder:validation:Minimum=1
	Statement int32 `json:"statement"`
	// Statements is how many statements that migration has.
	// +kubebuilder:validation:Minimum=1
	Statements int32 `json:"statements"`
	// SQLState is the SQLSTATE the database answered with, empty when it gave
	// none.
	// +kubebuilder:validation:Pattern=`^[0-9A-Z]{5}$`
	// +optional
	SQLState string `json:"sqlState,omitempty"`
	// ErrorNumber is MySQL's own error number, zero on every other protocol.
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=65535
	// +optional
	ErrorNumber int32 `json:"errorNumber,omitempty"`
}

MigrationRunFailureStatus is the statement a run stopped at and the code the database answered with. Like the run report it comes from, it carries no text: the database's message can name a row.

func (*MigrationRunFailureStatus) DeepCopy added in v0.2.7

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MigrationRunFailureStatus.

func (*MigrationRunFailureStatus) DeepCopyInto added in v0.2.7

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type MigrationRunOutcome

type MigrationRunOutcome string

MigrationRunOutcome is what a finished execution's own evidence said, read from the database rather than from the Job's exit status.

The values are Ptah's, because the controller reports the verdict of the engine that was present for the run rather than deriving a second one. +kubebuilder:validation:Enum=UpToDate;Applied;Failed;Partial;Unknown

const (
	// MigrationRunOutcomeUpToDate means the run selected nothing.
	MigrationRunOutcomeUpToDate MigrationRunOutcome = "UpToDate"
	// MigrationRunOutcomeApplied means every selected migration is recorded
	// applied and no revision row is dirty.
	MigrationRunOutcomeApplied MigrationRunOutcome = "Applied"
	// MigrationRunOutcomeFailed means the run stopped and the migration that
	// failed committed nothing. It may be retried once its cause is fixed.
	MigrationRunOutcomeFailed MigrationRunOutcome = "Failed"
	// MigrationRunOutcomePartial means the migration that failed committed some
	// of its statements and not the rest. Retrying the file would run them
	// twice, so recovery is Ptah's own resume path.
	MigrationRunOutcomePartial MigrationRunOutcome = "Partial"
	// MigrationRunOutcomeUnknown means the evidence could not be read, or a
	// dirty row does not say how far it got. Nothing may conclude from this
	// that the migration did or did not run.
	MigrationRunOutcomeUnknown MigrationRunOutcome = "Unknown"
)

type MigrationRunResolution

type MigrationRunResolution string

MigrationRunResolution is what settled an unresolved run. +kubebuilder:validation:Enum=HistoryRead;Acknowledged

const (
	// MigrationRunResolvedByHistoryRead means a read-only reading of the
	// database the run addressed found nothing of the artifact left to apply.
	MigrationRunResolvedByHistoryRead MigrationRunResolution = "HistoryRead"
	// MigrationRunResolvedByAcknowledgment means a person created a
	// PtahMigrationRunAcknowledgment naming the run.
	MigrationRunResolvedByAcknowledgment MigrationRunResolution = "Acknowledged"
)

type MigrationRunStatus

type MigrationRunStatus struct {
	// Outcome is the verdict Ptah read from the revision table.
	Outcome MigrationRunOutcome `json:"outcome"`

	// JobName and JobUID identify the execution this evidence came from. The
	// UID is what makes a replacement Job with the same name a different run.
	JobName string `json:"jobName,omitempty"`
	// JobUID is that Job's UID.
	JobUID types.UID `json:"jobUID,omitempty"`

	// OperationID is the Apply claim that ran. It is what makes two executions
	// of a byte-identical plan two runs. A run a release without this field
	// recorded has none, and neither that nor anything else below is guessed
	// for it.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	// +optional
	OperationID string `json:"operationID,omitempty"`

	// PlanRef is the immutable plan the run carried out. The plan store reuses a
	// byte-identical plan, so it says what was planned and not which execution
	// this was: OperationID does. It pins the plan, as the pruning guide lists: it
	// outlives a plan somebody deleted, or a prune with a list of pins from before
	// this field, and then names bytes nothing holds, which a retention audit
	// reports as a missing plan.
	// +optional
	PlanRef *ImmutableObjectReference `json:"planRef,omitempty"`
	// PlanFingerprint is that plan's spec.fingerprint when the claim was written,
	// which binds the sequence, the history it was computed against, the source,
	// the policy, the target and the execution binding. It is absent for a claim
	// a release without the field wrote.
	// +kubebuilder:validation:MaxLength=128
	// +optional
	PlanFingerprint string `json:"planFingerprint,omitempty"`

	// Authorization is what allowed the run: a person's approval, or the
	// resource's own policy.
	// +optional
	Authorization *MigrationRunAuthorizationStatus `json:"authorization,omitempty"`

	// ArtifactDigest is the OCI artifact the run read its files from.
	// +optional
	ArtifactDigest string `json:"artifactDigest,omitempty"`
	// Source is the source the run read its files from, for a ConfigMap, a Git
	// commit or an HTTPS download.
	// +optional
	Source *PlanSourceBinding `json:"source,omitempty"`
	// TargetIdentityDigest is the credential-free identity of the database the
	// run's result named. That is the database it opened, unless it refused before
	// its child started because its Secret had moved: then it is the one the Secret
	// held, which the run did not touch. A run that left no result names none, since
	// it may have run nowhere, or against whatever its Secret held by then.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	// +optional
	TargetIdentityDigest string `json:"targetIdentityDigest,omitempty"`
	// ExecutionBindingID is the execution epoch the claim was authorized under.
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	// +optional
	ExecutionBindingID string `json:"executionBindingID,omitempty"`

	// Verification is the first reading of this run's database after the run
	// ended. What a run claims and what the revision table holds are two
	// statements, and this records the second. It is absent until that reading,
	// for a run that named no database, since no reading can then be said to be of
	// it, and for a run a release without this field recorded.
	// +optional
	Verification *MigrationRunVerificationStatus `json:"verification,omitempty"`

	// StartedAt is when the run began.
	StartedAt metav1.Time `json:"startedAt"`
	// FinishedAt is when its result was read. An unfinished run has none.
	FinishedAt *metav1.Time `json:"finishedAt,omitempty"`

	// AppliedVersions names the selected migrations the history recorded
	// afterwards, so a migration the history already held is not reported as
	// this run's work.
	// +listType=set
	// +kubebuilder:validation:MaxItems=256
	AppliedVersions []int64 `json:"appliedVersions,omitempty"`

	// DispatchedBy is the manager that built and dispatched the run's Job,
	// read from the Job's Pod template when the run was harvested. The plan
	// the run carried out names the manager that published it, which a later
	// release sharing the execution binding need not be. It is absent when
	// the run was settled without its Job.
	// +optional
	DispatchedBy *ManagerRecord `json:"dispatchedBy,omitempty"`

	// Message is a safe explanation. It never carries database rows, and never
	// carries the SQL a migration ran.
	// +kubebuilder:validation:MaxLength=1024
	Message string `json:"message,omitempty"`

	// Failure is where a failed or partial run stopped, when a statement
	// reached the database and failed there. It is what Message says in words,
	// for a reader that should not depend on their wording.
	// +optional
	Failure *MigrationRunFailureStatus `json:"failure,omitempty"`

	// MigrationLog is what the run's writes to the database's own record of
	// migrations came to, when the run reported it. It is absent for a run
	// that left no readable report, for one that stopped before it selected
	// anything, and for one a release without this field recorded: none of
	// them says whether the record is complete.
	// +optional
	MigrationLog *MigrationLogStatus `json:"migrationLog,omitempty"`
}

MigrationRunStatus is the evidence of the last execution, as the database accounted for it.

func (*MigrationRunStatus) DeepCopy

func (in *MigrationRunStatus) DeepCopy() *MigrationRunStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MigrationRunStatus.

func (*MigrationRunStatus) DeepCopyInto

func (in *MigrationRunStatus) DeepCopyInto(out *MigrationRunStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type MigrationRunVerificationResult added in v0.2.10

type MigrationRunVerificationResult string

MigrationRunVerificationResult is what the reading after a run found. +kubebuilder:validation:Enum=InSync;Pending;Blocked

const (
	// MigrationRunVerifiedInSync is a database with every migration the artifact
	// carries.
	MigrationRunVerifiedInSync MigrationRunVerificationResult = "InSync"
	// MigrationRunVerifiedPending is a database the artifact has more to apply
	// to, as when a source moved on while the run ran.
	MigrationRunVerifiedPending MigrationRunVerificationResult = "Pending"
	// MigrationRunVerifiedBlocked is a history nothing may run against.
	MigrationRunVerifiedBlocked MigrationRunVerificationResult = "Blocked"
)

type MigrationRunVerificationStatus added in v0.2.10

type MigrationRunVerificationStatus struct {
	// ObservedAt is when the history was read.
	ObservedAt metav1.Time `json:"observedAt"`
	// HistoryFingerprint is that reading of the revision table.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	HistoryFingerprint string `json:"historyFingerprint"`
	// CurrentVersion is the highest version that reading recorded.
	// +kubebuilder:validation:Minimum=0
	CurrentVersion int64 `json:"currentVersion"`
	// Result is what the reading found.
	Result MigrationRunVerificationResult `json:"result"`
}

MigrationRunVerificationStatus is the first reading of a run's database after the run ended.

func (*MigrationRunVerificationStatus) DeepCopy added in v0.2.10

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MigrationRunVerificationStatus.

func (*MigrationRunVerificationStatus) DeepCopyInto added in v0.2.10

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type OCITransportSpec

type OCITransportSpec struct {
	// PlainHTTP is intended only for explicitly trusted test or air-gapped
	// networks. HTTPS remains the default. When registryAuthFrom is present, its
	// Secret must also contain allowPlainHTTP with the exact value "true".
	// +kubebuilder:default=false
	PlainHTTP bool `json:"plainHTTP,omitempty"`

	// CAFrom selects a custom CA bundle. When registryAuthFrom is present, that
	// same Secret must contain caSHA256 with the exact lowercase SHA-256 digest
	// of the selected bytes, and an HTTPS source whose Secret holds caSHA256
	// is refused without it.
	CAFrom *corev1.ConfigMapKeySelector `json:"caFrom,omitempty"`
}

OCITransportSpec configures private and air-gapped registries without allowing arbitrary files or commands into the execution Pod. +kubebuilder:validation:XValidation:rule="!self.plainHTTP || !has(self.caFrom)",message="caFrom cannot be used with plainHTTP"

func (*OCITransportSpec) DeepCopy

func (in *OCITransportSpec) DeepCopy() *OCITransportSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new OCITransportSpec.

func (*OCITransportSpec) DeepCopyInto

func (in *OCITransportSpec) DeepCopyInto(out *OCITransportSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ObjectInventoryStatus added in v0.2.8

type ObjectInventoryStatus struct {
	// Kind is the stem of the kind's fixed drift finding categories, such as
	// tables or rls_policies, or the kind a feature owner's qualified
	// categories carry after the colon, such as
	// ptah.run/pgextension/extension-change. A stem joins `<stem>_added` and
	// `<stem>_removed`, and a feature kind joins `feature_changes:<kind>` and
	// `feature_access_*:<kind>`. Either names a type of object, never an object.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	// +kubebuilder:validation:Pattern=`^([a-z]([a-z_]*[a-z])?|[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+(/[A-Za-z0-9_-][A-Za-z0-9._-]*)+)$`
	Kind string `json:"kind"`
	// Desired is how many objects of the kind the desired schema declares.
	// +kubebuilder:validation:Minimum=0
	Desired int32 `json:"desired"`
	// Observed is how many the comparison found in the database.
	// +kubebuilder:validation:Minimum=0
	Observed int32 `json:"observed"`
}

ObjectInventoryStatus counts one kind of object on both sides of an observation.

func (*ObjectInventoryStatus) DeepCopy added in v0.2.8

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ObjectInventoryStatus.

func (*ObjectInventoryStatus) DeepCopyInto added in v0.2.8

func (in *ObjectInventoryStatus) DeepCopyInto(out *ObjectInventoryStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type OperationType

type OperationType string

OperationType identifies one serialized execution Job. +kubebuilder:validation:Enum=Resolve;Verify;Observe;Plan;Apply

const (
	OperationResolve OperationType = "Resolve"
	OperationVerify  OperationType = "Verify"
	OperationObserve OperationType = "Observe"
	OperationPlan    OperationType = "Plan"
	OperationApply   OperationType = "Apply"
)

type PendingObservationOutcome

type PendingObservationOutcome string

PendingObservationOutcome records why read-only convergence proof is mandatory before another mutation may be considered. +kubebuilder:validation:Enum=ApplySucceeded;OutcomeUnknown

const (
	PendingObservationApplySucceeded PendingObservationOutcome = "ApplySucceeded"
	PendingObservationOutcomeUnknown PendingObservationOutcome = "OutcomeUnknown"
)

type PendingObservationStatus

type PendingObservationStatus struct {
	// Outcome is what is known about the apply this proof is for: that it
	// succeeded, or that nobody can say.
	Outcome PendingObservationOutcome `json:"outcome"`
	// ApplyOperationID is the apply attempt this proof belongs to.
	ApplyOperationID string `json:"applyOperationID"`
	// ApplyJobName and ApplyJobUID identify the Kubernetes Job independently
	// of mutable labels so every exact-owner Pod can be tracked until the
	// immutable execution horizon has elapsed.
	// +kubebuilder:validation:MaxLength=253
	ApplyJobName string `json:"applyJobName,omitempty"`
	// ApplyJobUID is that Job's UID.
	ApplyJobUID types.UID `json:"applyJobUID,omitempty"`
	// AdmissionSnapshot retains the exact pre-admission Pod template identity
	// after ActiveOperation is cleared. Apply Job cleanup after an
	// execution-binding change fails closed when this evidence is absent.
	AdmissionSnapshot *PodAdmissionSnapshot `json:"admissionSnapshot,omitempty"`
	// ApplyPodUIDs and ApplyPodCount preserve the terminal Pod evidence seen at
	// the mutation boundary. More than one Pod always forces outcome-unknown
	// proof even for a one-shot Job.
	// +kubebuilder:validation:MaxItems=8
	ApplyPodUIDs []types.UID `json:"applyPodUIDs,omitempty"`
	// +kubebuilder:validation:Minimum=0
	// ApplyPodCount is how many of them there were.
	ApplyPodCount int32 `json:"applyPodCount,omitempty"`
	// ApplyGeneration is the spec generation the apply was dispatched for, so
	// a newer desired state does not inherit this proof.
	ApplyGeneration int64 `json:"applyGeneration"`
	// ObserveAfter delays proof when the Kubernetes Job identity or create
	// result is uncertain. Until this time, the original mutating Pod could
	// still be within its immutable active deadline.
	ObserveAfter *metav1.Time `json:"observeAfter,omitempty"`
	// ApplyFailure is the statement the apply stopped at, as the run's own
	// report named it. It is absent when the run named none: it succeeded, it
	// stopped before a statement was sent or at the commit after them, or its
	// report could not be read. An apply that names one is OutcomeUnknown all
	// the same: where it stopped does not say what the database kept.
	// +optional
	ApplyFailure *SchemaApplyFailureStatus `json:"applyFailure,omitempty"`

	// Plan is the plan the apply carried out, kept here after the active
	// operation is cleared so the proof knows what it is proving. Its manager
	// fields name the manager that published it.
	Plan CurrentPlanStatus `json:"plan"`
	// DispatchedBy is the manager that built and dispatched the Apply Job,
	// read from the Job's Pod template when the Apply was harvested, and
	// carried into status.applied when the proof completes. It is absent when
	// the Apply was settled without its Job.
	// +optional
	DispatchedBy *ManagerRecord `json:"dispatchedBy,omitempty"`
	// Target is the key-free binding the proof reads the database through.
	Target DatabaseTargetBinding `json:"target"`
	// CoordinationDigest is the realm the apply held, kept so the proof runs
	// under the same lock rather than racing somebody else's turn.
	CoordinationDigest string `json:"coordinationDigest"`
	// Source is the artifact access the proof needs to re-read the desired
	// state. It holds Kubernetes selectors, never Secret contents.
	Source SourceAccessBinding `json:"source"`
	// Dev is the scratch database the proof may use.
	Dev *DatabaseTargetRef `json:"dev,omitempty"`
	// PlanRequired records that the raw drift read completed and the same
	// immutable proof inputs now require authoritative managed-scope planning.
	PlanRequired bool `json:"planRequired,omitempty"`

	// Exclude is the managed scope the apply was computed under.
	Exclude []string `json:"exclude,omitempty"`
	// ProtectedTables is the fence the in-flight plan was computed under. A
	// policy edit while a plan is pending must not let it execute against a
	// fence it never saw.
	// +kubebuilder:validation:MaxItems=128
	// +listType=set
	ProtectedTables []string `json:"protectedTables,omitempty"`
	// DriftSeverity is the severity the proof reads at.
	DriftSeverity string `json:"driftSeverity,omitempty"`
	// ConnectTimeout is the connect timeout the proof is dispatched with.
	ConnectTimeout metav1.Duration `json:"connectTimeout,omitempty"`
	// LockTimeout is the database lock timeout it is dispatched with.
	LockTimeout metav1.Duration `json:"lockTimeout,omitempty"`

	// LeaseDurationSeconds is the immutable duration claimed for the Apply
	// operation. The same holder remains active through convergence proof.
	// +kubebuilder:validation:Minimum=5
	// +kubebuilder:validation:Maximum=86460
	LeaseDurationSeconds int32 `json:"leaseDurationSeconds"`
	// LeaseEpoch identifies the uninterrupted database-realm lock acquisition
	// carried from Apply through its complete read-only convergence proof.
	LeaseEpoch string `json:"leaseEpoch,omitempty"`
}

PendingObservationStatus binds post-apply proof to the immutable plan, target, policy, and lock holder that existed at the mutation boundary.

func (*PendingObservationStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PendingObservationStatus.

func (*PendingObservationStatus) DeepCopyInto

func (in *PendingObservationStatus) DeepCopyInto(out *PendingObservationStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PlanChunkReference

type PlanChunkReference struct {
	// Name of the PtahSchemaPlanChunk holding this chunk. An Apply projects
	// the chunk into its Pod through an immutable ConfigMap of the same name.
	Name string `json:"name"`
	// Index of this chunk in the plan, counting from zero. The chunks are
	// concatenated in this order and in no other.
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=15
	Index int32 `json:"index"`
	// Digest of this chunk's bytes, checked when the plan is read back.
	Digest string `json:"digest"`
	// Size of this chunk in bytes, checked with the digest.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=524288
	Size int32 `json:"size"`
}

PlanChunkReference identifies one ordered immutable PtahSchemaPlanChunk.

func (*PlanChunkReference) DeepCopy

func (in *PlanChunkReference) DeepCopy() *PlanChunkReference

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PlanChunkReference.

func (*PlanChunkReference) DeepCopyInto

func (in *PlanChunkReference) DeepCopyInto(out *PlanChunkReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PlanSourceBinding added in v0.2.7

type PlanSourceBinding struct {
	// Kind of source the plan was computed from.
	Kind SourceKind `json:"kind"`
	// Revision is the source object the files were read from. For a ConfigMap
	// it is the ConfigMap's UID: an edit to a key the source does not select
	// keeps the plan, while another ConfigMap, or the same name deleted and
	// created again, retires it even when the files match. For Git it is
	// "sha256:" and the SHA-256 of the repository URL and the selected path,
	// joined by a newline: another repository or another path retires the
	// plan even when the files match, while a commit that leaves the
	// selected files as they were keeps it, as an edit to an unselected key
	// keeps a ConfigMap's. For HTTPS it is "sha256:" and the SHA-256 of the
	// URL and the selected path, joined by a newline, and never the download
	// digest: an archive published again as other bytes keeps the plan once
	// the spec names its digest, if the selected files did not change.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	Revision string `json:"revision"`
	// ContentDigest is the content digest of the files the plan was computed
	// from.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	ContentDigest string `json:"contentDigest"`
	// Policy is the source policy the source was checked against, when the
	// resource names one.
	// +optional
	Policy *SourcePolicyBinding `json:"policy,omitempty"`
}

PlanSourceBinding is what a plan computed from a source other than an OCI artifact binds in place of artifactDigest.

func (*PlanSourceBinding) DeepCopy added in v0.2.7

func (in *PlanSourceBinding) DeepCopy() *PlanSourceBinding

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PlanSourceBinding.

func (*PlanSourceBinding) DeepCopyInto added in v0.2.7

func (in *PlanSourceBinding) DeepCopyInto(out *PlanSourceBinding)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PlannedMigration

type PlannedMigration struct {
	// Version is the migration's numeric version.
	// +kubebuilder:validation:Minimum=1
	Version int64 `json:"version"`

	// VersionKey is the exact revision identity. A version does not identify a
	// row on its own: an Atlas repeatable migration carries an opaque token
	// rather than a decimal spelling.
	// +kubebuilder:validation:MaxLength=128
	VersionKey string `json:"versionKey,omitempty"`

	// Description is the migration's own description, as the artifact spells it.
	// +kubebuilder:validation:MaxLength=128
	Description string `json:"description,omitempty"`

	// Checksum is what the file hashes to under the rule that decides what a
	// revision row records. It is what makes a plan refuse an artifact whose
	// bytes changed after the plan was published.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	Checksum string `json:"checksum"`

	// Checkpoint marks a migration whose up body is the cumulative schema at
	// its version.
	Checkpoint bool `json:"checkpoint,omitempty"`

	// TransactionMode is the file's declared mode, resolved for this dialect:
	// "file", "none", or empty where the file declares none and the engine's
	// own mode decides. A run that stops halfway is read differently depending
	// on it, so the plan records what was true when it was made.
	// +kubebuilder:validation:Enum=file;none
	TransactionMode string `json:"transactionMode,omitempty"`
}

PlannedMigration is one migration a plan selected, as the artifact declares it and the database will record it.

func (*PlannedMigration) DeepCopy

func (in *PlannedMigration) DeepCopy() *PlannedMigration

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PlannedMigration.

func (*PlannedMigration) DeepCopyInto

func (in *PlannedMigration) DeepCopyInto(out *PlannedMigration)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PodAdmissionSnapshot

type PodAdmissionSnapshot struct {
	// +kubebuilder:validation:Enum=v1
	// Version is the snapshot format this record was written in.
	Version string `json:"version"`
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	// Digest covers this whole snapshot, so a Pod can be checked against it
	// without re-reading the cluster objects it describes.
	Digest string `json:"digest"`
	// TemplateDigest binds the canonical, API-defaulted pre-admission Job Pod
	// template. The self-referential snapshot annotation and four exact
	// API-server-generated Job identity labels are omitted and validated
	// separately against the current Job name and UID.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	// TemplateDigest covers the Pod template the operator asked for, before the
	// cluster's own admission had a chance to change it.
	TemplateDigest string `json:"templateDigest"`

	// ServiceAccount is the identity the Pod runs as, as it resolved.
	ServiceAccount ServiceAccountAdmissionSnapshot `json:"serviceAccount"`
	// +kubebuilder:validation:MaxItems=32
	// LimitRanges are the namespace defaults that would be applied to the Pod.
	LimitRanges []LimitRangeAdmissionSnapshot `json:"limitRanges,omitempty"`
	// RuntimeClass is the container runtime it resolved to, where one is named.
	RuntimeClass *RuntimeClassAdmissionSnapshot `json:"runtimeClass,omitempty"`
	// PriorityClass is the scheduling priority it resolved to.
	PriorityClass PriorityClassAdmissionSnapshot `json:"priorityClass"`
	// DefaultTolerationsEnabled records whether kube-apiserver runs the
	// DefaultTolerationSeconds admission plugin. It and the two values below
	// say what that plugin does, so a toleration the Pod did not ask for is
	// recognized rather than refused.
	DefaultTolerationsEnabled bool `json:"defaultTolerationsEnabled"`
	// +kubebuilder:validation:Minimum=0
	// DefaultNotReadyTolerationSeconds is that plugin's not-ready value.
	DefaultNotReadyTolerationSeconds int64 `json:"defaultNotReadyTolerationSeconds"`
	// +kubebuilder:validation:Minimum=0
	// DefaultUnreachableTolerationSeconds is that plugin's unreachable value.
	DefaultUnreachableTolerationSeconds int64 `json:"defaultUnreachableTolerationSeconds"`
	// ExtendedResourceTolerationEnabled records whether kube-apiserver runs the
	// ExtendedResourceToleration admission plugin, which adds a toleration per
	// extended resource a Pod requests.
	ExtendedResourceTolerationEnabled bool `json:"extendedResourceTolerationEnabled"`
	// AlwaysPullImagesEnabled records whether kube-apiserver runs the
	// AlwaysPullImages admission plugin, which rewrites every imagePullPolicy
	// to Always.
	AlwaysPullImagesEnabled bool `json:"alwaysPullImagesEnabled"`
}

PodAdmissionSnapshot is the bounded, credential-free mutation envelope for one active operation. Digest covers every other field using canonical JSON. A controller restart validates this persisted snapshot instead of rereading resources whose later mutations must not reinterpret the operation.

func (*PodAdmissionSnapshot) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PodAdmissionSnapshot.

func (*PodAdmissionSnapshot) DeepCopyInto

func (in *PodAdmissionSnapshot) DeepCopyInto(out *PodAdmissionSnapshot)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PodAnnotationValue

type PodAnnotationValue string

PodAnnotationValue is one declared annotation value, bounded in length and otherwise free, as Kubernetes leaves it. +kubebuilder:validation:MaxLength=1024

type PodLabelValue

type PodLabelValue string

PodLabelValue is one declared label value: what Kubernetes accepts for a label value, bounded in the schema so a bad value is refused on the resource rather than on the Job the controller would have built from it. +kubebuilder:validation:MaxLength=63 +kubebuilder:validation:Pattern=`^(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])?$`

type PodMetadataSpec

type PodMetadataSpec struct {
	// Labels are added to every operation Pod beside the operator's own.
	// +optional
	// +kubebuilder:validation:MaxProperties=16
	// +kubebuilder:validation:XValidation:rule=`self.all(key, key.size() <= 317 && (key.contains('/') ? (key.indexOf('/') <= 253 && key.size() - key.indexOf('/') <= 64) : key.size() <= 63) && key.matches('^([a-z0-9]([-a-z0-9]*[a-z0-9])?([.][a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?[A-Za-z0-9]([-A-Za-z0-9_.]*[A-Za-z0-9])?$'))`,message="podMetadata.labels keys must be valid Kubernetes label keys"
	// +kubebuilder:validation:XValidation:rule=`self.all(key, !(key.startsWith('ptah.run/') || key.contains('.ptah.run/') || key.startsWith('kubernetes.io/') || key.contains('.kubernetes.io/') || key.startsWith('k8s.io/') || key.contains('.k8s.io/') || key == 'controller-uid' || key == 'job-name'))`,message="podMetadata.labels keys under ptah.run, kubernetes.io and k8s.io are reserved, and so are controller-uid and job-name"
	Labels map[string]PodLabelValue `json:"labels,omitempty"`
	// Annotations are added to every operation Pod beside the operator's
	// own.
	// +optional
	// +kubebuilder:validation:MaxProperties=16
	// +kubebuilder:validation:XValidation:rule=`self.all(key, key.size() <= 317 && (key.contains('/') ? (key.indexOf('/') <= 253 && key.size() - key.indexOf('/') <= 64) : key.size() <= 63) && key.matches('^([a-z0-9]([-a-z0-9]*[a-z0-9])?([.][a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?[A-Za-z0-9]([-A-Za-z0-9_.]*[A-Za-z0-9])?$'))`,message="podMetadata.annotations keys must be valid Kubernetes annotation keys"
	// +kubebuilder:validation:XValidation:rule=`self.all(key, !(key.startsWith('ptah.run/') || key.contains('.ptah.run/') || key.startsWith('kubernetes.io/') || key.contains('.kubernetes.io/') || key.startsWith('k8s.io/') || key.contains('.k8s.io/') || key == 'controller-uid' || key == 'job-name'))`,message="podMetadata.annotations keys under ptah.run, kubernetes.io and k8s.io are reserved, and so are controller-uid and job-name"
	Annotations map[string]PodAnnotationValue `json:"annotations,omitempty"`
}

PodMetadataSpec is the bounded metadata operation Pods carry for a service mesh or a policy engine. Each map takes at most 16 entries. A key is a Kubernetes qualified name; a label value is what Kubernetes accepts for one, and an annotation value is at most 1024 bytes. Keys whose prefix is ptah.run, kubernetes.io or k8s.io, or a subdomain of one, are refused, and so are the bare controller-uid and job-name keys the Job controller sets.

func (*PodMetadataSpec) DeepCopy

func (in *PodMetadataSpec) DeepCopy() *PodMetadataSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PodMetadataSpec.

func (*PodMetadataSpec) DeepCopyInto

func (in *PodMetadataSpec) DeepCopyInto(out *PodMetadataSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PriorityClassAdmissionSnapshot

type PriorityClassAdmissionSnapshot struct {
	// Object is the PriorityClass this was read from, where a class was named.
	Object *AdmissionObjectBinding `json:"object,omitempty"`
	// +kubebuilder:validation:MaxLength=253
	// Name is that class, as the Pod requests it.
	Name string `json:"name,omitempty"`
	// Value is the priority it resolved to.
	Value int32 `json:"value"`
	// +kubebuilder:validation:Enum=Never;PreemptLowerPriority
	// PreemptionPolicy is what that class says about preempting others.
	PreemptionPolicy *corev1.PreemptionPolicy `json:"preemptionPolicy,omitempty"`
}

PriorityClassAdmissionSnapshot records the exact values injected by the Priority admission plugin. Object is absent only when the cluster has no global default and the Job does not request a named PriorityClass.

func (*PriorityClassAdmissionSnapshot) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PriorityClassAdmissionSnapshot.

func (*PriorityClassAdmissionSnapshot) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PrivilegeChange

type PrivilegeChange string

PrivilegeChange is one kind of authority a plan statement grants, revokes, delegates or rebinds. It names the kind of change, never the object, the role or the statement.

  • Grant: a privilege granted on an object, default privileges included.
  • Revoke: a privilege revoked from an object.
  • RoleMembership: a role granted to or revoked from a role or user.
  • Role: a role, user or group created, altered or dropped, or assumed for the rest of the session with SET ROLE or SET SESSION AUTHORIZATION.
  • Ownership: an object given to another owner.
  • RowSecurityPolicy: a row-security policy created, altered or dropped, or row security switched off or unforced on a table.
  • SecurityDefiner: code set to run with its owner's rights rather than its caller's, which a MySQL or MariaDB routine does unless it says SQL SECURITY INVOKER, or a change to the rights an existing PostgreSQL view reads with.
  • Definer: a MySQL DEFINER clause naming the account a view, routine, trigger or event runs as.
  • FunctionReplacement: CREATE OR REPLACE of a function or procedure, which can rewrite code that policies, triggers and other roles already call.

+kubebuilder:validation:Enum=Grant;Revoke;RoleMembership;Role;Ownership;RowSecurityPolicy;SecurityDefiner;Definer;FunctionReplacement

const (
	PrivilegeChangeGrant               PrivilegeChange = "Grant"
	PrivilegeChangeRevoke              PrivilegeChange = "Revoke"
	PrivilegeChangeRoleMembership      PrivilegeChange = "RoleMembership"
	PrivilegeChangeRole                PrivilegeChange = "Role"
	PrivilegeChangeOwnership           PrivilegeChange = "Ownership"
	PrivilegeChangeRowSecurityPolicy   PrivilegeChange = "RowSecurityPolicy"
	PrivilegeChangeSecurityDefiner     PrivilegeChange = "SecurityDefiner"
	PrivilegeChangeDefiner             PrivilegeChange = "Definer"
	PrivilegeChangeFunctionReplacement PrivilegeChange = "FunctionReplacement"
)

type PtahMigration

type PtahMigration struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   PtahMigrationSpec   `json:"spec"`
	Status PtahMigrationStatus `json:"status,omitempty"`
}

+kubebuilder:validation:XValidation:rule="oldSelf.hasValue() || self.metadata.name.size() <= 63",message="metadata.name must be at most 63 bytes, because it is carried whole in the labels of the Jobs this resource dispatches",optionalOldSelf=true +kubebuilder:object:root=true +kubebuilder:subresource:status +kubebuilder:resource:shortName=ptahm +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase` +kubebuilder:printcolumn:name="Current",type=integer,JSONPath=`.status.history.currentVersion` +kubebuilder:printcolumn:name="Pending",type=integer,JSONPath=`.status.history.pendingCount` +kubebuilder:printcolumn:name="Outcome",type=string,JSONPath=`.status.lastRun.outcome` +kubebuilder:printcolumn:name="Digest",type=string,JSONPath=`.status.artifact.digest`,priority=1 +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

func (*PtahMigration) DeepCopy

func (in *PtahMigration) DeepCopy() *PtahMigration

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigration.

func (*PtahMigration) DeepCopyInto

func (in *PtahMigration) DeepCopyInto(out *PtahMigration)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahMigration) DeepCopyObject

func (in *PtahMigration) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahMigrationApproval

type PtahMigrationApproval struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   PtahMigrationApprovalSpec   `json:"spec"`
	Status PtahMigrationApprovalStatus `json:"status,omitempty"`
}

+kubebuilder:object:root=true +kubebuilder:subresource:status +kubebuilder:resource:shortName=ptahmapprove +kubebuilder:printcolumn:name="Migration",type=string,JSONPath=`.spec.migrationRef.name` +kubebuilder:printcolumn:name="Plan",type=string,JSONPath=`.spec.planRef.name` +kubebuilder:printcolumn:name="Approver",type=string,JSONPath=`.spec.approver.username` +kubebuilder:printcolumn:name="Accepted",type=string,JSONPath=`.status.conditions[?(@.type=='Accepted')].status` +kubebuilder:printcolumn:name="Stale",type=string,JSONPath=`.status.conditions[?(@.type=='Stale')].status` +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

func (*PtahMigrationApproval) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationApproval.

func (*PtahMigrationApproval) DeepCopyInto

func (in *PtahMigrationApproval) DeepCopyInto(out *PtahMigrationApproval)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahMigrationApproval) DeepCopyObject

func (in *PtahMigrationApproval) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahMigrationApprovalList

type PtahMigrationApprovalList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PtahMigrationApproval `json:"items"`
}

+kubebuilder:object:root=true

func (*PtahMigrationApprovalList) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationApprovalList.

func (*PtahMigrationApprovalList) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahMigrationApprovalList) DeepCopyObject

func (in *PtahMigrationApprovalList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahMigrationApprovalSpec

type PtahMigrationApprovalSpec struct {
	// MigrationRef is the resource the approved sequence belongs to.
	MigrationRef ImmutableObjectReference `json:"migrationRef"`
	// PlanRef is the exact plan being approved.
	PlanRef ImmutableObjectReference `json:"planRef"`
	// PlanFingerprint is the plan's spec.fingerprint: its complete identity,
	// checked against the live plan before anything runs.
	PlanFingerprint string `json:"planFingerprint"`

	// Approver is stamped by the mutating webhook from the authenticated
	// request; whatever a client writes here is replaced.
	Approver ApprovalIdentity `json:"approver"`
	// ApprovedAt is when that stamp was made.
	ApprovedAt metav1.Time `json:"approvedAt"`
	// MutationRequestUID records the mutating AdmissionReview that stamped the
	// authenticated identity, exactly as a schema approval does.
	MutationRequestUID string `json:"mutationRequestUID"`
}

PtahMigrationApprovalSpec binds one authenticated decision to one exact migration plan.

The decision is three identifiers: the migration, the plan, and the plan's fingerprint. A migration plan's fingerprint binds the history it was computed against as well as the sequence, the artifact, the policy, the target and the execution binding, so an approval that names the plan by UID and fingerprint is retired by somebody else's run moving the database underneath it, without carrying a copy of the history it was given under. +kubebuilder:validation:XValidation:rule="self == oldSelf",message="an approval is immutable; create a new approval instead"

func (*PtahMigrationApprovalSpec) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationApprovalSpec.

func (*PtahMigrationApprovalSpec) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahMigrationApprovalStatus

type PtahMigrationApprovalStatus struct {
	// ObservedGeneration is the approval generation this status was written
	// for. An approval is immutable, so it moves once.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Conditions say whether the binding was Accepted, has been Consumed by a
	// run, or went Stale because the history, the artifact or the policy moved
	// first.
	// +listType=map
	// +listMapKey=type
	// +kubebuilder:validation:MaxItems=16
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

PtahMigrationApprovalStatus tells an approver whether the exact binding was accepted, consumed, or made stale by a later reading of the history.

func (*PtahMigrationApprovalStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationApprovalStatus.

func (*PtahMigrationApprovalStatus) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahMigrationList

type PtahMigrationList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PtahMigration `json:"items"`
}

+kubebuilder:object:root=true

func (*PtahMigrationList) DeepCopy

func (in *PtahMigrationList) DeepCopy() *PtahMigrationList

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationList.

func (*PtahMigrationList) DeepCopyInto

func (in *PtahMigrationList) DeepCopyInto(out *PtahMigrationList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahMigrationList) DeepCopyObject

func (in *PtahMigrationList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahMigrationPlan

type PtahMigrationPlan struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   PtahMigrationPlanSpec   `json:"spec"`
	Status PtahMigrationPlanStatus `json:"status,omitempty"`
}

+kubebuilder:object:root=true +kubebuilder:subresource:status +kubebuilder:resource:shortName=ptahmplan +kubebuilder:printcolumn:name="Migration",type=string,JSONPath=`.spec.migrationRef.name` +kubebuilder:printcolumn:name="From",type=integer,JSONPath=`.spec.currentVersion` +kubebuilder:printcolumn:name="Steps",type=integer,JSONPath=`.spec.migrations.length()` +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

func (*PtahMigrationPlan) DeepCopy

func (in *PtahMigrationPlan) DeepCopy() *PtahMigrationPlan

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationPlan.

func (*PtahMigrationPlan) DeepCopyInto

func (in *PtahMigrationPlan) DeepCopyInto(out *PtahMigrationPlan)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahMigrationPlan) DeepCopyObject

func (in *PtahMigrationPlan) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahMigrationPlanList

type PtahMigrationPlanList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PtahMigrationPlan `json:"items"`
}

+kubebuilder:object:root=true

func (*PtahMigrationPlanList) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationPlanList.

func (*PtahMigrationPlanList) DeepCopyInto

func (in *PtahMigrationPlanList) DeepCopyInto(out *PtahMigrationPlanList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahMigrationPlanList) DeepCopyObject

func (in *PtahMigrationPlanList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahMigrationPlanSpec

type PtahMigrationPlanSpec struct {
	// ContractVersion versions plan publication separately from the Kubernetes
	// API version. Version 1 is a plan computed from an OCI artifact, and
	// binds artifactDigest and the verification policy. Version 2 is a plan
	// computed from a ConfigMap or a Git commit, and binds source instead. A
	// manager that knows only version 1 refuses a version 2 plan.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=2
	ContractVersion int32 `json:"contractVersion"`

	// MigrationRef is the PtahMigration this plan was computed for.
	MigrationRef ImmutableObjectReference `json:"migrationRef"`

	// Fingerprint binds this plan to everything that decided it. An approval
	// names it, and a changed input produces a different plan rather than a
	// changed one.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	Fingerprint string `json:"fingerprint"`

	// Migrations is the exact sequence, in execution order, and the order is
	// the content: a plan that applies the same migrations in another order is
	// a different plan. So the list is atomic rather than a map keyed by
	// version -- a map declares the order insignificant, and it would also
	// require the version to be unique, which is the thing VersionKey exists
	// to say it is not.
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=256
	Migrations []PlannedMigration `json:"migrations"`

	// HistoryFingerprint is the history this plan was computed against. A
	// history that changed between planning and execution invalidates the plan
	// rather than being applied to.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	HistoryFingerprint string `json:"historyFingerprint"`

	// CurrentVersion is the version the history stood at when the plan was
	// made, published so an operator can read the plan's premise.
	// +kubebuilder:validation:Minimum=0
	CurrentVersion int64 `json:"currentVersion"`

	// ArtifactDigest is the OCI migration artifact this plan reads its files
	// from, pinned to content rather than to the tag it was resolved through.
	// +optional
	ArtifactDigest string `json:"artifactDigest,omitempty"`
	// Source is the ConfigMap source this plan reads its files from: the
	// ConfigMap's UID and the content digest of the selected files.
	// +optional
	Source *PlanSourceBinding `json:"source,omitempty"`
	// CoordinationDigest is the database realm this plan takes its turn in.
	CoordinationDigest string `json:"coordinationDigest"`
	// TargetIdentityDigest identifies the database it was computed against
	// without carrying anything that could reach it.
	TargetIdentityDigest string `json:"targetIdentityDigest"`
	// PolicyFingerprint is the spec.policy the plan was computed under, so an
	// edited policy retires a plan waiting for a person.
	PolicyFingerprint string `json:"policyFingerprint"`

	// VerificationPolicyUID is the policy object that accepted the artifact.
	// +optional
	VerificationPolicyUID types.UID `json:"verificationPolicyUID,omitempty"`
	// VerificationPolicyDigest is that policy's content at the time.
	// +optional
	VerificationPolicyDigest string `json:"verificationPolicyDigest,omitempty"`

	// ExecutionBindingID is the execution epoch the plan was computed under. It
	// changes whenever a component that decides what the run means changes --
	// the controller-state version, the Ptah version, the executor image or
	// the runner protocol -- even when a rollout returns to byte-identical
	// versions. A manager upgrade that changes none of them keeps it.
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	ExecutionBindingID string `json:"executionBindingID"`
	// ControllerImage is the digest-pinned manager that published this plan.
	// It is a record, not a binding: the fingerprint leaves it out, and a
	// later manager may apply the plan.
	// +kubebuilder:validation:Pattern=`^[^[:space:]@]+@sha256:[0-9a-f]{64}$`
	ControllerImage string `json:"controllerImage"`
	// ControllerRevision is that manager's revision, recorded the same way.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	// +kubebuilder:validation:Pattern=`^[^[:space:][:cntrl:]]([^[:cntrl:]]*[^[:space:][:cntrl:]])?$`
	ControllerRevision string `json:"controllerRevision"`
	// ControllerStateVersion is the state semantics that manager writes.
	// +kubebuilder:validation:Minimum=1
	ControllerStateVersion int32 `json:"controllerStateVersion"`
	// PtahVersion is the Ptah build that computed the sequence.
	PtahVersion string `json:"ptahVersion"`
	// ExecutorImage is the digest-pinned image that ran Ptah.
	ExecutorImage string `json:"executorImage"`
	// RunnerImage is the digest-pinned runner image of the manager that
	// published this plan, recorded and not bound.
	RunnerImage string `json:"runnerImage"`
	// RunnerProtocolVersion is the runner protocol the plan binds: what the
	// runner enforces inside the Pod and the result frame it returns.
	// +kubebuilder:validation:Minimum=1
	RunnerProtocolVersion int32 `json:"runnerProtocolVersion"`

	// CreatedAt is when the controller published this plan.
	CreatedAt metav1.Time `json:"createdAt"`
}

PtahMigrationPlanSpec is generated by the controller and immutable thereafter.

It is a separate kind from PtahSchemaPlan rather than a mode of it: a schema plan binds a fingerprint of the observed schema and one of the desired schema, and a migration plan binds a version sequence, per-migration checksums and the history it was computed against. One kind carrying both would make every field optional and dependent on which controller wrote it. +kubebuilder:validation:XValidation:rule="self == oldSelf",message="a plan is immutable; generate a new plan instead" +kubebuilder:validation:XValidation:rule="self.contractVersion == 1 ? (has(self.artifactDigest) && has(self.verificationPolicyUID) && has(self.verificationPolicyDigest) && !has(self.source)) : (has(self.source) && !has(self.artifactDigest) && !has(self.verificationPolicyUID) && !has(self.verificationPolicyDigest))",message="contract version 1 binds artifactDigest and a verification policy; contract version 2 binds source"

func (*PtahMigrationPlanSpec) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationPlanSpec.

func (*PtahMigrationPlanSpec) DeepCopyInto

func (in *PtahMigrationPlanSpec) DeepCopyInto(out *PtahMigrationPlanSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahMigrationPlanStatus

type PtahMigrationPlanStatus struct {
	// ObservedGeneration is the plan generation this status was written for.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Conditions is empty. The operator publishes no Condition on a migration
	// plan: a plan is an immutable artifact, and whether it is still the one to
	// apply is a fact about the PtahMigration, which reports it there. The field
	// stays so a later Condition about the plan itself has somewhere to go.
	// +listType=map
	// +listMapKey=type
	// +kubebuilder:validation:MaxItems=16
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

PtahMigrationPlanStatus is the status subresource of a migration plan. The operator writes nothing to it: a plan is an immutable artifact, and the state a reader wants -- whether it is still the plan to apply -- is reported on the PtahMigration that published it.

func (*PtahMigrationPlanStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationPlanStatus.

func (*PtahMigrationPlanStatus) DeepCopyInto

func (in *PtahMigrationPlanStatus) DeepCopyInto(out *PtahMigrationPlanStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahMigrationRunAcknowledgment

type PtahMigrationRunAcknowledgment struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   PtahMigrationRunAcknowledgmentSpec   `json:"spec"`
	Status PtahMigrationRunAcknowledgmentStatus `json:"status,omitempty"`
}

PtahMigrationRunAcknowledgment settles one run a PtahMigration could not account for, in the name of the person who created it.

+kubebuilder:object:root=true +kubebuilder:subresource:status +kubebuilder:resource:shortName=ptahmack +kubebuilder:printcolumn:name="Migration",type=string,JSONPath=`.spec.migrationRef.name` +kubebuilder:printcolumn:name="Acknowledged By",type=string,JSONPath=`.spec.acknowledgedBy.username` +kubebuilder:printcolumn:name="Consumed",type=string,JSONPath=`.status.conditions[?(@.type=='Consumed')].status` +kubebuilder:printcolumn:name="Stale",type=string,JSONPath=`.status.conditions[?(@.type=='Stale')].status` +kubebuilder:printcolumn:name="Operation",type=string,JSONPath=`.spec.operationID`,priority=1 +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

func (*PtahMigrationRunAcknowledgment) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationRunAcknowledgment.

func (*PtahMigrationRunAcknowledgment) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahMigrationRunAcknowledgment) DeepCopyObject

func (in *PtahMigrationRunAcknowledgment) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahMigrationRunAcknowledgmentList

type PtahMigrationRunAcknowledgmentList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PtahMigrationRunAcknowledgment `json:"items"`
}

+kubebuilder:object:root=true

func (*PtahMigrationRunAcknowledgmentList) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationRunAcknowledgmentList.

func (*PtahMigrationRunAcknowledgmentList) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahMigrationRunAcknowledgmentList) DeepCopyObject

func (in *PtahMigrationRunAcknowledgmentList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahMigrationRunAcknowledgmentSpec

type PtahMigrationRunAcknowledgmentSpec struct {
	// MigrationRef is the resource whose unresolved run this settles.
	MigrationRef ImmutableObjectReference `json:"migrationRef"`
	// OperationID is the status.unresolvedRun.operationID this acknowledges:
	// one Apply attempt, and no other.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	OperationID string `json:"operationID"`

	// AcknowledgedBy is stamped by the mutating webhook from the authenticated
	// request. Whatever an API client writes here is replaced.
	AcknowledgedBy ApprovalIdentity `json:"acknowledgedBy"`
	// AcknowledgedAt is when that stamp was made, by the same webhook.
	AcknowledgedAt metav1.Time `json:"acknowledgedAt"`
	// MutationRequestUID records the mutating AdmissionReview that stamped the
	// identity, exactly as an approval does.
	MutationRequestUID string `json:"mutationRequestUID"`
}

PtahMigrationRunAcknowledgmentSpec is a person's statement that the run a PtahMigration recorded in status.unresolvedRun has been accounted for.

The decision is two identifiers: the migration, by name and UID, and the Apply attempt the record names. An attempt's ID is never reused, so an acknowledgment cannot carry over to a later run, and a migration rebuilt under the same name is another object with another UID.

It is a separate object rather than a status write so that the decision carries the identity that made it. Status is written by the manager alone; an acknowledgment is written by a person, and admission stamps who. +kubebuilder:validation:XValidation:rule="self == oldSelf",message="an acknowledgment is immutable; create a new acknowledgment instead"

func (*PtahMigrationRunAcknowledgmentSpec) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationRunAcknowledgmentSpec.

func (*PtahMigrationRunAcknowledgmentSpec) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahMigrationRunAcknowledgmentStatus

type PtahMigrationRunAcknowledgmentStatus struct {
	// ObservedGeneration is the generation this status was written for. An
	// acknowledgment is immutable, so it moves once.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Conditions say whether the acknowledgment settled the run it names
	// (Consumed), or named a run the migration was not waiting on (Stale).
	// +listType=map
	// +listMapKey=type
	// +kubebuilder:validation:MaxItems=16
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

PtahMigrationRunAcknowledgmentStatus says what the controller did with the acknowledgment.

func (*PtahMigrationRunAcknowledgmentStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationRunAcknowledgmentStatus.

func (*PtahMigrationRunAcknowledgmentStatus) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahMigrationSpec

type PtahMigrationSpec struct {
	// Target is the database this sequence runs against, named through a Secret
	// the manager never reads.
	Target DatabaseTargetSpec `json:"target"`

	// Artifact is the migration directory this history is matched against:
	// an OCI artifact, a ConfigMap, a Git repository or an HTTPS archive. It
	// reuses the schema path's source contract: fetching it never hands a
	// registry, Git or HTTPS credential to the process that runs SQL.
	Artifact SourceSpec `json:"artifact"`

	// Policy decides what may run without a person: the apply mode, the
	// approval requirement, and the locks a run takes.
	// +kubebuilder:default={}
	Policy MigrationPolicy `json:"policy,omitempty"`

	// Interval is the cadence for resolving a mutable tag and re-reading the
	// history.
	// +kubebuilder:default="10m"
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MaxLength=32
	// +kubebuilder:validation:XValidation:rule="duration(self) >= duration('10s') && duration(self) <= duration('24h')",message="interval must be between 10s and 24h"
	Interval metav1.Duration `json:"interval,omitempty"`

	// Execution shapes the Job a run happens in: its deadlines, its resources
	// and the scheduling it inherits.
	// +kubebuilder:default={}
	Execution ExecutionSpec `json:"execution,omitempty"`

	// Suspend prevents new Jobs. A Job already applying is observed to a
	// terminal result: a migration that is running is never abandoned, because
	// the database would be left in a state nothing recorded.
	// +kubebuilder:default=false
	Suspend bool `json:"suspend,omitempty"`
}

PtahMigrationSpec declares a database, a migration artifact, and the terms under which its pending migrations may run.

It is deliberately not a mode of PtahSchema. A schema resource reconciles a desired structure; this one executes a prepared sequence and matches a history. The two have different state models, and a single resource carrying both would have fields that mean nothing in one of them. +kubebuilder:validation:XValidation:rule="!has(self.execution) || !has(self.execution.connectTimeout) || !has(self.execution.activeDeadlineSeconds) || duration(self.execution.connectTimeout).getMilliseconds() <= self.execution.activeDeadlineSeconds * 1000",message="execution.connectTimeout must not exceed execution.activeDeadlineSeconds" +kubebuilder:validation:XValidation:rule="!has(self.policy) || !has(self.policy.lockTimeout) || !has(self.execution) || !has(self.execution.activeDeadlineSeconds) || duration(self.policy.lockTimeout).getMilliseconds() <= self.execution.activeDeadlineSeconds * 1000",message="policy.lockTimeout must not exceed execution.activeDeadlineSeconds" +kubebuilder:validation:XValidation:rule="self.target.urlFrom.name.size() > 0 && self.target.urlFrom.key.size() > 0 && (!has(self.target.urlFrom.optional) || !self.target.urlFrom.optional)",message="target.urlFrom must name a required Secret key" +kubebuilder:validation:XValidation:rule="!has(self.artifact.verificationPolicyFrom) || (self.artifact.verificationPolicyFrom.name.size() > 0 && self.artifact.verificationPolicyFrom.key.size() > 0 && (!has(self.artifact.verificationPolicyFrom.optional) || !self.artifact.verificationPolicyFrom.optional))",message="artifact.verificationPolicyFrom must name a required ConfigMap key" +kubebuilder:validation:XValidation:rule="!has(self.artifact.transport) || !has(self.artifact.transport.caFrom) || (self.artifact.transport.caFrom.name.size() > 0 && self.artifact.transport.caFrom.key.size() > 0 && (!has(self.artifact.transport.caFrom.optional) || !self.artifact.transport.caFrom.optional))",message="artifact.transport.caFrom must name a required ConfigMap key" +kubebuilder:validation:XValidation:rule="!has(self.artifact.https) || self.artifact.https.format != 'File'",message="artifact.https.format is TarGzip or Zip: a migration directory comes in an archive"

func (*PtahMigrationSpec) DeepCopy

func (in *PtahMigrationSpec) DeepCopy() *PtahMigrationSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationSpec.

func (*PtahMigrationSpec) DeepCopyInto

func (in *PtahMigrationSpec) DeepCopyInto(out *PtahMigrationSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahMigrationStatus

type PtahMigrationStatus struct {
	// ObservedGeneration is the spec generation this status describes.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Phase is where the resource stands. It is a summary for a reader: the
	// conditions below are what a decision reads.
	Phase MigrationPhase `json:"phase,omitempty"`

	// Conditions are the readable verdicts: whether the artifact resolved and
	// verified, whether the database was reachable, whether a plan is ready,
	// whether an approval is required, and whether the sequence is in sync.
	// +listType=map
	// +listMapKey=type
	// +kubebuilder:validation:MaxItems=16
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Artifact is the resolved, credential-free artifact binding every later
	// operation of this cycle uses. A tag resolves once; the digest is what
	// travels.
	Artifact *SourceAccessBinding `json:"artifact,omitempty"`

	// ConfigMap is the source ConfigMap status.artifact.snapshot was copied
	// from, for a ConfigMap source: its name, UID and the resourceVersion
	// that was read.
	// +optional
	ConfigMap *ConfigMapSourceRevision `json:"configMap,omitempty"`

	// SourcePolicy is the source policy the last resolution was checked
	// against, when the spec names one.
	// +optional
	SourcePolicy *SourcePolicyBinding `json:"sourcePolicy,omitempty"`

	// ExecutionBinding is what this resource's plans and approvals are bound
	// to: the components that decide what a run means. It is the same contract
	// the schema path publishes, because the question it answers is the same
	// one: a rollout that changed any of them has to invalidate a plan rather
	// than execute it under new semantics. A manager upgrade that changes none
	// of them leaves it, and every plan and approval, as they were.
	ExecutionBinding *ExecutionBindingStatus `json:"executionBinding,omitempty"`

	// ActiveOperation is the claim the controller is currently carrying out,
	// and nil when nothing is in flight.
	ActiveOperation *MigrationOperationStatus `json:"activeOperation,omitempty"`

	// History is the last reading of the database's own revision table.
	History *MigrationHistoryStatus `json:"history,omitempty"`

	// Plan names the immutable plan object the controller published for the
	// current pending sequence, and is cleared once that sequence is gone.
	Plan *ImmutableObjectReference `json:"plan,omitempty"`

	// LastRun is the evidence of the most recent execution, kept across later
	// reconciliations so an operator can see what happened without the Job.
	LastRun *MigrationRunStatus `json:"lastRun,omitempty"`

	// UnresolvedRun is the execution nobody could account for, and is absent
	// while there is none. It is written when a run ends Partial or Unknown,
	// and removed only when a read-only reading of the same database finds
	// nothing of this artifact left to apply, or when a
	// PtahMigrationRunAcknowledgment names its operationID. While it is here
	// nothing is planned and nothing runs, whatever the conditions happen to
	// say.
	//
	// The manager keeps a copy in the operator.ptah.run/unresolved-run
	// annotation, written before this field and removed after it, so a
	// restore that drops status restores the record from metadata.
	UnresolvedRun *UnresolvedMigrationRunStatus `json:"unresolvedRun,omitempty"`

	// ResolvedRun is how the most recent unresolved run was settled, and who
	// settled it when a person did. It stays until the next one is settled.
	ResolvedRun *ResolvedMigrationRunStatus `json:"resolvedRun,omitempty"`

	// Journal is the bounded record of this migration's significant lifecycle
	// events.
	// +optional
	Journal *LifecycleJournal `json:"journal,omitempty"`

	// PendingLockRelease is a database-realm Lease this resource still owes
	// back, kept whole so the release survives the process that owed it. The
	// release is written here in the same status patch that clears the claim
	// holding the Lease, and removed only once a release has succeeded, so a
	// manager that stops in between hands the realm back on its next pass
	// instead of leaving every other claimant to wait out the full lease.
	//
	// It is never written for a run that may still be executing. A Lease under
	// a live executor is the one thing the Lease exists to prevent, and such a
	// Lease is left to expire rather than recorded as owed.
	PendingLockRelease *TargetLockReleaseStatus `json:"pendingLockRelease,omitempty"`

	// NextReconciliationTime is when the controller intends to look again.
	NextReconciliationTime *metav1.Time `json:"nextReconciliationTime,omitempty"`

	// LastReadRequest is the last value of the operator.ptah.run/read-requested-at
	// annotation the controller answered, so an answered request is not
	// answered again. A value longer than MaxReadRequestLength is recorded as
	// its SHA-256 digest, and a value that is not an RFC 3339 instant is
	// recorded with a Warning Event and starts nothing.
	// +optional
	// +kubebuilder:validation:MaxLength=71
	LastReadRequest string `json:"lastReadRequest,omitempty"`
}

PtahMigrationStatus is the controller's account of one migration resource.

func (*PtahMigrationStatus) DeepCopy

func (in *PtahMigrationStatus) DeepCopy() *PtahMigrationStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahMigrationStatus.

func (*PtahMigrationStatus) DeepCopyInto

func (in *PtahMigrationStatus) DeepCopyInto(out *PtahMigrationStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahRealm

type PtahRealm struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// Spec is the administrator's grant.
	Spec PtahRealmSpec `json:"spec"`
}

PtahRealm names one physical database at cluster scope and says which namespaces may manage it.

A coordination key in spec.target is scoped to its resource's namespace, so a database managed from more than one namespace needs a realm, and only an administrator can create one. The manager reads realms and never writes them.

+kubebuilder:object:root=true +kubebuilder:resource:scope=Cluster,shortName=ptahr +kubebuilder:printcolumn:name="Engine",type=string,JSONPath=`.spec.engine` +kubebuilder:printcolumn:name="Sharing",type=string,JSONPath=`.spec.sharing` +kubebuilder:printcolumn:name="Namespaces",type=string,JSONPath=`.spec.namespaces` +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

func (*PtahRealm) DeepCopy

func (in *PtahRealm) DeepCopy() *PtahRealm

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahRealm.

func (*PtahRealm) DeepCopyInto

func (in *PtahRealm) DeepCopyInto(out *PtahRealm)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahRealm) DeepCopyObject

func (in *PtahRealm) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahRealmList

type PtahRealmList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PtahRealm `json:"items"`
}

PtahRealmList contains a list of PtahRealm. +kubebuilder:object:root=true

func (*PtahRealmList) DeepCopy

func (in *PtahRealmList) DeepCopy() *PtahRealmList

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahRealmList.

func (*PtahRealmList) DeepCopyInto

func (in *PtahRealmList) DeepCopyInto(out *PtahRealmList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahRealmList) DeepCopyObject

func (in *PtahRealmList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahRealmReference

type PtahRealmReference struct {
	// Name is the PtahRealm's name.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
	Name string `json:"name"`
}

PtahRealmReference names a cluster-scoped PtahRealm.

func (*PtahRealmReference) DeepCopy

func (in *PtahRealmReference) DeepCopy() *PtahRealmReference

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahRealmReference.

func (*PtahRealmReference) DeepCopyInto

func (in *PtahRealmReference) DeepCopyInto(out *PtahRealmReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahRealmSpec

type PtahRealmSpec struct {
	// Engine is the database family of this realm. A resource that names the
	// realm with another engine is refused. It cannot change: a realm is one
	// physical database, and a database does not change engine.
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="engine is immutable; a realm is one physical database"
	Engine DatabaseEngine `json:"engine"`

	// Namespaces are the namespaces whose resources may claim this realm,
	// written out by name.
	//
	// There is deliberately no selector. Namespace labels are often writable
	// by whoever administers the namespace, and a selector would let that
	// person admit their own namespace to a database somebody else runs.
	//
	// A name is a grant to whoever holds the namespace of that name, now or
	// later. A name listed before its namespace exists, or left listed after
	// the namespace is deleted, belongs to whoever creates it next, and where
	// tenants choose their own namespace names that is anybody. Remove a
	// namespace from every realm before deleting it.
	//
	// Removing a namespace does not stop an operation already running there,
	// the same as a conflict does not: the resource is refused at its next
	// claim, before any Job.
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=256
	// +listType=set
	// +kubebuilder:validation:items:MinLength=1
	// +kubebuilder:validation:items:MaxLength=63
	// +kubebuilder:validation:items:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	Namespaces []string `json:"namespaces"`

	// Sharing is whether more than one resource may manage the database at
	// once.
	//
	// Exclusive admits one claimant. A second one, in any listed namespace,
	// is a conflict that refuses every claimant, whatever each declared.
	//
	// Shared admits several, on the rule a namespace-local key has: every
	// claimant sets spec.target.sharedRealm, and one that has not refuses them
	// all. Sharing is a statement both the administrator and each claimant
	// make; neither can make it for the other.
	Sharing RealmSharing `json:"sharing"`
}

PtahRealmSpec is an administrator's statement about one physical database: the engine it speaks, the namespaces whose resources may manage it, and whether more than one resource may manage it at once.

It is the authorization for a claim. A PtahSchema or PtahMigration names a realm through spec.target.realmRef, and that names nothing the realm has not granted: a resource in a namespace the realm does not list is refused itself and is not counted against the resources the realm does admit.

func (*PtahRealmSpec) DeepCopy

func (in *PtahRealmSpec) DeepCopy() *PtahRealmSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahRealmSpec.

func (*PtahRealmSpec) DeepCopyInto

func (in *PtahRealmSpec) DeepCopyInto(out *PtahRealmSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahResultRecord

type PtahResultRecord struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`
	Spec              PtahResultRecordSpec `json:"spec"`
}

PtahResultRecord stores one part of a durable runner result or a delivery credential. It has its own RBAC resource so the control plane can read these records without permission to read database Secrets. It has no status or mutable payload. A small result commits atomically in its intent; a chunked result commits through a separate completion record. Records belong to their exact operation resource or publication intent. They are internal transport objects, not desired database configuration. +kubebuilder:object:root=true +kubebuilder:resource:shortName=ptahresult +kubebuilder:printcolumn:name="Type",type=string,JSONPath=`.spec.type`

func (*PtahResultRecord) DeepCopy

func (in *PtahResultRecord) DeepCopy() *PtahResultRecord

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahResultRecord.

func (*PtahResultRecord) DeepCopyInto

func (in *PtahResultRecord) DeepCopyInto(out *PtahResultRecord)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahResultRecord) DeepCopyObject

func (in *PtahResultRecord) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahResultRecordList

type PtahResultRecordList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PtahResultRecord `json:"items"`
}

+kubebuilder:object:root=true

func (*PtahResultRecordList) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahResultRecordList.

func (*PtahResultRecordList) DeepCopyInto

func (in *PtahResultRecordList) DeepCopyInto(out *PtahResultRecordList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahResultRecordList) DeepCopyObject

func (in *PtahResultRecordList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahResultRecordSpec

type PtahResultRecordSpec struct {
	// Type identifies the record's role in credential or result publication.
	// Credential records contain delivery key material; intent, chunk, and
	// completion records contain authenticated operation evidence. Retired
	// records fence delivery and start the evidence retention window.
	// +kubebuilder:validation:Enum=credential;intent;chunk;complete;retired
	Type string `json:"type"`

	// Data is the record's exact bytes, base64-encoded on the wire. Readers must
	// validate its protocol and digest before using it. Treat every role as
	// confidential: payloads may contain SQL and credentials contain private keys.
	// MaxLength is the base64 length of the 512 KiB record ceiling.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=699052
	Data []byte `json:"data"`
}

PtahResultRecordSpec is an immutable record in the runner result transport. The transport validates the record's protocol, owner, binding, and digest. This schema bounds the stored bytes and prevents changing a published record. +kubebuilder:validation:XValidation:rule="self == oldSelf",message="a result record is immutable; create a new operation instead"

func (*PtahResultRecordSpec) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahResultRecordSpec.

func (*PtahResultRecordSpec) DeepCopyInto

func (in *PtahResultRecordSpec) DeepCopyInto(out *PtahResultRecordSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahSchema

type PtahSchema struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   PtahSchemaSpec   `json:"spec"`
	Status PtahSchemaStatus `json:"status,omitempty"`
}

+kubebuilder:validation:XValidation:rule="oldSelf.hasValue() || self.metadata.name.size() <= 63",message="metadata.name must be at most 63 bytes, because it is carried whole in the labels of the Jobs this resource dispatches",optionalOldSelf=true +kubebuilder:object:root=true +kubebuilder:subresource:status +kubebuilder:resource:shortName=ptahs +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase` +kubebuilder:printcolumn:name="Digest",type=string,JSONPath=`.status.source.digest`,priority=1 +kubebuilder:printcolumn:name="Drift",type=string,JSONPath=`.status.conditions[?(@.type=='DriftDetected')].status` +kubebuilder:printcolumn:name="Approval",type=string,JSONPath=`.status.conditions[?(@.type=='ApprovalRequired')].status` +kubebuilder:printcolumn:name="In Sync",type=string,JSONPath=`.status.conditions[?(@.type=='InSync')].status` +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=='Ready')].status` +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

func (*PtahSchema) DeepCopy

func (in *PtahSchema) DeepCopy() *PtahSchema

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchema.

func (*PtahSchema) DeepCopyInto

func (in *PtahSchema) DeepCopyInto(out *PtahSchema)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahSchema) DeepCopyObject

func (in *PtahSchema) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahSchemaApproval

type PtahSchemaApproval struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   PtahSchemaApprovalSpec   `json:"spec"`
	Status PtahSchemaApprovalStatus `json:"status,omitempty"`
}

+kubebuilder:object:root=true +kubebuilder:subresource:status +kubebuilder:resource:shortName=ptahapprove +kubebuilder:printcolumn:name="Schema",type=string,JSONPath=`.spec.schemaRef.name` +kubebuilder:printcolumn:name="Plan",type=string,JSONPath=`.spec.planRef.name` +kubebuilder:printcolumn:name="Approver",type=string,JSONPath=`.spec.approver.username` +kubebuilder:printcolumn:name="Accepted",type=string,JSONPath=`.status.conditions[?(@.type=='Accepted')].status` +kubebuilder:printcolumn:name="Stale",type=string,JSONPath=`.status.conditions[?(@.type=='Stale')].status` +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

func (*PtahSchemaApproval) DeepCopy

func (in *PtahSchemaApproval) DeepCopy() *PtahSchemaApproval

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaApproval.

func (*PtahSchemaApproval) DeepCopyInto

func (in *PtahSchemaApproval) DeepCopyInto(out *PtahSchemaApproval)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahSchemaApproval) DeepCopyObject

func (in *PtahSchemaApproval) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahSchemaApprovalList

type PtahSchemaApprovalList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PtahSchemaApproval `json:"items"`
}

+kubebuilder:object:root=true

func (*PtahSchemaApprovalList) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaApprovalList.

func (*PtahSchemaApprovalList) DeepCopyInto

func (in *PtahSchemaApprovalList) DeepCopyInto(out *PtahSchemaApprovalList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahSchemaApprovalList) DeepCopyObject

func (in *PtahSchemaApprovalList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahSchemaApprovalSpec

type PtahSchemaApprovalSpec struct {
	// SchemaRef is the resource the approved change belongs to.
	SchemaRef ImmutableObjectReference `json:"schemaRef"`
	// PlanRef is the exact plan being approved. A plan is immutable, so this
	// names bytes rather than an intention.
	PlanRef ImmutableObjectReference `json:"planRef"`
	// PlanFingerprint is the plan's spec.fingerprint: its complete approval
	// identity. A plan under a different binding has a different fingerprint,
	// so an approval that names this one cannot carry over to it.
	PlanFingerprint string `json:"planFingerprint"`

	// Approver is stamped by the mutating webhook from the authenticated
	// request. Whatever an API client writes here is replaced.
	Approver ApprovalIdentity `json:"approver"`
	// ApprovedAt is when that stamp was made, by the same webhook.
	ApprovedAt metav1.Time `json:"approvedAt"`
	// MutationRequestUID records the mutating AdmissionReview that stamped the
	// authenticated identity. Kubernetes creates a distinct AdmissionReview UID
	// for the later validating webhook, so the validator checks this field is
	// present while matching identity against its own authenticated UserInfo.
	MutationRequestUID string `json:"mutationRequestUID"`
}

PtahSchemaApprovalSpec binds one authenticated decision to one exact plan.

The decision is three identifiers: the schema, the plan, and the plan's fingerprint. The fingerprint is the plan's complete identity -- the artifact, the observed and desired state, the policy, the verification policy, the target, the execution binding and what the manager read out of the plan bytes -- and a plan is immutable, so an approval that names a plan by UID and fingerprint names every one of those without carrying a copy. Admission checks the three against the live plan; the controller checks them again before Apply. +kubebuilder:validation:XValidation:rule="self == oldSelf",message="an approval is immutable; create a new approval instead"

func (*PtahSchemaApprovalSpec) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaApprovalSpec.

func (*PtahSchemaApprovalSpec) DeepCopyInto

func (in *PtahSchemaApprovalSpec) DeepCopyInto(out *PtahSchemaApprovalSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahSchemaApprovalStatus

type PtahSchemaApprovalStatus struct {
	// ObservedGeneration is the approval generation this status was written
	// for. An approval is immutable, so it moves only when the object is first
	// reconciled.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Conditions say whether the binding was Accepted, has been Consumed by an
	// apply, or went Stale because the database, the artifact or the policy
	// moved before it could run.
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

PtahSchemaApprovalStatus tells an approver whether the exact binding was accepted, consumed, or made stale by a later observation.

func (*PtahSchemaApprovalStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaApprovalStatus.

func (*PtahSchemaApprovalStatus) DeepCopyInto

func (in *PtahSchemaApprovalStatus) DeepCopyInto(out *PtahSchemaApprovalStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahSchemaList

type PtahSchemaList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PtahSchema `json:"items"`
}

+kubebuilder:object:root=true

func (*PtahSchemaList) DeepCopy

func (in *PtahSchemaList) DeepCopy() *PtahSchemaList

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaList.

func (*PtahSchemaList) DeepCopyInto

func (in *PtahSchemaList) DeepCopyInto(out *PtahSchemaList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahSchemaList) DeepCopyObject

func (in *PtahSchemaList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahSchemaPlan

type PtahSchemaPlan struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   PtahSchemaPlanSpec   `json:"spec"`
	Status PtahSchemaPlanStatus `json:"status,omitempty"`
}

+kubebuilder:object:root=true +kubebuilder:subresource:status +kubebuilder:resource:shortName=ptahplan +kubebuilder:printcolumn:name="Schema",type=string,JSONPath=`.spec.schemaRef.name` +kubebuilder:printcolumn:name="Fingerprint",type=string,JSONPath=`.spec.fingerprint` +kubebuilder:printcolumn:name="Statements",type=integer,JSONPath=`.spec.statementCount` +kubebuilder:printcolumn:name="Destructive",type=boolean,JSONPath=`.spec.destructive` +kubebuilder:printcolumn:name="Privileges",type=string,JSONPath=`.spec.privilegeChanges` +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

func (*PtahSchemaPlan) DeepCopy

func (in *PtahSchemaPlan) DeepCopy() *PtahSchemaPlan

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaPlan.

func (*PtahSchemaPlan) DeepCopyInto

func (in *PtahSchemaPlan) DeepCopyInto(out *PtahSchemaPlan)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahSchemaPlan) DeepCopyObject

func (in *PtahSchemaPlan) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahSchemaPlanChunk

type PtahSchemaPlanChunk struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec PtahSchemaPlanChunkSpec `json:"spec"`
}

PtahSchemaPlanChunk holds one ordered piece of a PtahSchemaPlan's bytes. The controller writes the chunks a plan names before it marks the plan Ready, and they are deleted with it.

A chunk is its own kind so that reading a plan takes one RBAC rule on this resource, granted per namespace, and nothing that also reads the namespace's ConfigMaps. There is no status: a chunk reports nothing, and the plan's status records which chunk objects were verified. +kubebuilder:object:root=true +kubebuilder:resource:shortName=ptahchunk +kubebuilder:printcolumn:name="Plan",type=string,JSONPath=`.metadata.ownerReferences[?(@.kind=='PtahSchemaPlan')].name` +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

func (*PtahSchemaPlanChunk) DeepCopy

func (in *PtahSchemaPlanChunk) DeepCopy() *PtahSchemaPlanChunk

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaPlanChunk.

func (*PtahSchemaPlanChunk) DeepCopyInto

func (in *PtahSchemaPlanChunk) DeepCopyInto(out *PtahSchemaPlanChunk)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahSchemaPlanChunk) DeepCopyObject

func (in *PtahSchemaPlanChunk) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahSchemaPlanChunkList

type PtahSchemaPlanChunkList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PtahSchemaPlanChunk `json:"items"`
}

+kubebuilder:object:root=true

func (*PtahSchemaPlanChunkList) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaPlanChunkList.

func (*PtahSchemaPlanChunkList) DeepCopyInto

func (in *PtahSchemaPlanChunkList) DeepCopyInto(out *PtahSchemaPlanChunkList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahSchemaPlanChunkList) DeepCopyObject

func (in *PtahSchemaPlanChunkList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahSchemaPlanChunkSpec

type PtahSchemaPlanChunkSpec struct {
	// Data is this chunk's bytes, base64-encoded on the wire. A plan is the
	// concatenation of its chunks' data in the order its spec.chunks gives,
	// and a chunk boundary falls wherever the byte count does, which may be
	// inside a statement or a character. Read a whole plan with kubectl ptah
	// plan rather than by decoding chunks.
	//
	// MaxLength is the base64 length of the 512 KiB chunk ceiling.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=699052
	Data []byte `json:"data"`
}

PtahSchemaPlanChunkSpec is one piece of a schema plan's bytes, written by the controller with the plan and never changed afterwards.

It carries the bytes and nothing else. The plan that owns the chunk records its index, size and digest in spec.chunks, and every reader checks the bytes against that record, so a copy here would be a second answer to the same question and would have to be held to the first. +kubebuilder:validation:XValidation:rule="self == oldSelf",message="a plan chunk is immutable; generate a new plan instead"

func (*PtahSchemaPlanChunkSpec) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaPlanChunkSpec.

func (*PtahSchemaPlanChunkSpec) DeepCopyInto

func (in *PtahSchemaPlanChunkSpec) DeepCopyInto(out *PtahSchemaPlanChunkSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahSchemaPlanList

type PtahSchemaPlanList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []PtahSchemaPlan `json:"items"`
}

+kubebuilder:object:root=true

func (*PtahSchemaPlanList) DeepCopy

func (in *PtahSchemaPlanList) DeepCopy() *PtahSchemaPlanList

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaPlanList.

func (*PtahSchemaPlanList) DeepCopyInto

func (in *PtahSchemaPlanList) DeepCopyInto(out *PtahSchemaPlanList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*PtahSchemaPlanList) DeepCopyObject

func (in *PtahSchemaPlanList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type PtahSchemaPlanSpec

type PtahSchemaPlanSpec struct {
	// ContractVersion versions plan publication and reconstruction separately
	// from the Kubernetes API version. Version 1 is a plan computed from an OCI
	// artifact, and binds artifactDigest and the verification policy. Version
	// 2 is a plan computed from a ConfigMap or a Git commit, and binds source
	// instead. A manager that knows only version 1 refuses a version 2 plan.
	// +kubebuilder:validation:Enum=1;2
	ContractVersion int32 `json:"contractVersion"`

	// SchemaRef is the PtahSchema this plan was computed for.
	SchemaRef ImmutableObjectReference `json:"schemaRef"`

	// Fingerprint is the complete approval identity of this plan: every binding
	// below hashed together. An approval names this value, and an apply runs
	// only while the live bindings still produce it.
	Fingerprint string `json:"fingerprint"`
	// ContentDigest is the digest of the plan bytes the chunks reconstruct.
	ContentDigest string `json:"contentDigest"`
	// Size is the length of those bytes, summed across the chunks.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=8388608
	Size int64 `json:"size"`

	// ArtifactDigest is the OCI artifact this plan was computed from, pinned to
	// content rather than to the tag it was resolved through.
	// +optional
	ArtifactDigest string `json:"artifactDigest,omitempty"`
	// Source is the ConfigMap source this plan was computed from: the
	// ConfigMap's UID and the content digest of the selected files.
	// +optional
	Source *PlanSourceBinding `json:"source,omitempty"`
	// CoordinationDigest is the database realm this plan takes its turn in: the
	// engine and the coordination key, hashed. Resources that share it never
	// run against the database at the same time.
	CoordinationDigest string `json:"coordinationDigest"`
	// TargetIdentityDigest identifies the database this plan was computed
	// against without carrying anything that could reach it.
	TargetIdentityDigest string `json:"targetIdentityDigest"`
	// ActualStateFingerprint is the observed database state the plan was
	// computed from. Drift since then retires the plan rather than applying it.
	ActualStateFingerprint string `json:"actualStateFingerprint"`
	// DesiredStateFingerprint is the state the verified artifact declared when
	// the plan was computed.
	DesiredStateFingerprint string `json:"desiredStateFingerprint"`
	// PolicyFingerprint is the spec.policy the plan was computed under. Editing
	// the policy -- a protected table included -- retires a plan waiting for a
	// person rather than letting it apply under rules nobody approved.
	PolicyFingerprint string `json:"policyFingerprint"`
	// VerificationPolicyUID is the policy object that accepted the artifact.
	// +optional
	VerificationPolicyUID types.UID `json:"verificationPolicyUID,omitempty"`
	// VerificationPolicyDigest is that policy's content, so replacing the
	// object or editing it in place both retire the plan.
	// +optional
	VerificationPolicyDigest string `json:"verificationPolicyDigest,omitempty"`
	// ExecutionBindingID is the execution epoch the plan was computed under. It
	// changes whenever a component that decides what the plan means when it
	// runs changes -- the controller-state version, the Ptah version, the
	// executor image or the runner protocol -- even when a rollout returns to
	// byte-identical versions. A manager upgrade that changes none of them
	// keeps it, and the plan stays applicable.
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	ExecutionBindingID string `json:"executionBindingID"`
	// ControllerImage is the digest-pinned manager that published this plan.
	// It is a record, not a binding: the fingerprint leaves it out, and a
	// later manager may apply the plan.
	// +kubebuilder:validation:Pattern=`^[^[:space:]@]+@sha256:[0-9a-f]{64}$`
	ControllerImage string `json:"controllerImage"`
	// ControllerRevision is that manager's revision, recorded the same way.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	// +kubebuilder:validation:Pattern=`^[^[:space:][:cntrl:]]([^[:cntrl:]]*[^[:space:][:cntrl:]])?$`
	ControllerRevision string `json:"controllerRevision"`
	// ControllerStateVersion is the state semantics that manager writes, so a
	// plan is never applied by a controller that reads status differently.
	// +kubebuilder:validation:Minimum=1
	ControllerStateVersion int32 `json:"controllerStateVersion"`
	// PtahVersion is the Ptah build that computed this plan, as the executor
	// image reports it.
	PtahVersion string `json:"ptahVersion"`
	// ExecutorImage is the digest-pinned image that ran Ptah.
	ExecutorImage string `json:"executorImage"`
	// RunnerImage is the digest-pinned runner image of the manager that
	// published this plan. Like the manager's own identity it is recorded and
	// not bound: the runner is built from the operator's source, and what it
	// enforces is versioned by RunnerProtocolVersion.
	RunnerImage string `json:"runnerImage"`
	// RunnerProtocolVersion is the runner protocol the plan binds: what the
	// runner enforces inside the Pod and the result frame it returns. A runner
	// answering in another version has its result rejected rather than
	// interpreted.
	RunnerProtocolVersion int32 `json:"runnerProtocolVersion"`

	// Dialect is the SQL dialect the statements are written in.
	Dialect string `json:"dialect"`
	// Destructive says the plan drops or rewrites something. Such a plan needs
	// spec.policy.allowDestructive and an approval naming these exact bytes.
	Destructive bool `json:"destructive"`
	// PrivilegeChanges names the kinds of authority the plan's statements
	// change: privileges granted or revoked, role membership, roles, owners,
	// row-security policies and definer rights. A plan that lists any needs an
	// approval naming these exact bytes whatever spec.policy.apply says, so
	// apply: Always does not grant access on its own.
	//
	// The operator reads the kinds from the statements themselves,
	// independently of the severity Ptah gave each one. A PostgreSQL view's
	// security_invoker comes from the effect Ptah recorded for its statement
	// where one is readable, so a statement that restates the option raises
	// nothing; anything else is read from the SQL. It names kinds and nothing
	// else: no object, no role and no text. Read the statements with kubectl
	// ptah plan.
	// +optional
	// +listType=set
	// +kubebuilder:validation:MaxItems=16
	PrivilegeChanges []PrivilegeChange `json:"privilegeChanges,omitempty"`
	// StatementCount is how many statements the plan holds. Read them with
	// kubectl ptah plan rather than by fetching the chunks.
	StatementCount int32 `json:"statementCount"`

	// Chunks are the PtahSchemaPlanChunk objects the plan bytes are stored in.
	// The plan is the concatenation of their data in index order, and nothing
	// reads them without checking each digest and size.
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=16
	// +listType=map
	// +listMapKey=index
	Chunks []PlanChunkReference `json:"chunks"`
}

PtahSchemaPlanSpec is generated by the controller and immutable thereafter. +kubebuilder:validation:XValidation:rule="self == oldSelf",message="a plan is immutable; generate a new plan instead" +kubebuilder:validation:XValidation:rule="self.contractVersion == 1 ? (has(self.artifactDigest) && has(self.verificationPolicyUID) && has(self.verificationPolicyDigest) && !has(self.source)) : (has(self.source) && !has(self.artifactDigest) && !has(self.verificationPolicyUID) && !has(self.verificationPolicyDigest))",message="contract version 1 binds artifactDigest and a verification policy; contract version 2 binds source"

func (*PtahSchemaPlanSpec) DeepCopy

func (in *PtahSchemaPlanSpec) DeepCopy() *PtahSchemaPlanSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaPlanSpec.

func (*PtahSchemaPlanSpec) DeepCopyInto

func (in *PtahSchemaPlanSpec) DeepCopyInto(out *PtahSchemaPlanSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahSchemaPlanStatus

type PtahSchemaPlanStatus struct {
	// ObservedGeneration is the plan generation this status was written for.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// PublishedChunks are the PtahSchemaPlanChunk objects that were found to
	// exist, by UID, before Ready became true. Chunk publication is not
	// transactional, so this is the record that every chunk the manifest names
	// was really written.
	// +kubebuilder:validation:MaxItems=16
	// +listType=map
	// +listMapKey=index
	PublishedChunks []PublishedPlanChunkStatus `json:"publishedChunks,omitempty"`
	// Conditions carry Ready, which is what approval and apply require.
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

PtahSchemaPlanStatus is the commit record for non-transactional chunk publication. Approval and apply require Ready=True.

func (*PtahSchemaPlanStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaPlanStatus.

func (*PtahSchemaPlanStatus) DeepCopyInto

func (in *PtahSchemaPlanStatus) DeepCopyInto(out *PtahSchemaPlanStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahSchemaSpec

type PtahSchemaSpec struct {
	// Target is the database to converge, named through a Secret the manager
	// itself has no permission to read.
	Target DatabaseTargetSpec `json:"target"`
	// Desired is the source that declares the schema, and the rows a
	// declaration names, to converge it to: an OCI artifact, a ConfigMap, a
	// Git repository or an HTTPS download.
	Desired SourceSpec `json:"desired"`
	// Dev is a scratch database Ptah may use where a comparison needs one. It
	// is never the target, and nothing it holds is kept.
	Dev *DatabaseTargetRef `json:"dev,omitempty"`
	// Policy decides what may happen without a person: whether a plan applies
	// itself, whether a destructive one is permitted at all, what counts as
	// drift, and which tables are fenced off entirely.
	// +kubebuilder:default={}
	Policy ReconciliationPolicy `json:"policy,omitempty"`

	// Interval is the cadence for resolving mutable tags and observing drift.
	// +kubebuilder:default="10m"
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MaxLength=32
	// +kubebuilder:validation:XValidation:rule="duration(self) >= duration('10s') && duration(self) <= duration('24h')",message="interval must be between 10s and 24h"
	Interval metav1.Duration `json:"interval,omitempty"`

	// Default the object itself so the API server also applies the nested
	// execution defaults when a manifest omits the whole block.
	// +kubebuilder:default={}
	Execution ExecutionSpec `json:"execution,omitempty"`

	// Suspend prevents new Jobs. A Job already applying is observed to a
	// terminal result and is never replaced by a destructive cleanup action.
	// +kubebuilder:default=false
	Suspend bool `json:"suspend,omitempty"`
}

PtahSchemaSpec declares one desired schema and one database target. +kubebuilder:validation:XValidation:rule="!has(self.execution) || !has(self.execution.connectTimeout) || !has(self.execution.activeDeadlineSeconds) || duration(self.execution.connectTimeout).getMilliseconds() <= self.execution.activeDeadlineSeconds * 1000",message="execution.connectTimeout must not exceed execution.activeDeadlineSeconds" +kubebuilder:validation:XValidation:rule="!has(self.policy) || !has(self.policy.lockTimeout) || !has(self.execution) || !has(self.execution.activeDeadlineSeconds) || duration(self.policy.lockTimeout).getMilliseconds() <= self.execution.activeDeadlineSeconds * 1000",message="policy.lockTimeout must not exceed execution.activeDeadlineSeconds" +kubebuilder:validation:XValidation:rule="self.target.urlFrom.name.size() > 0 && self.target.urlFrom.key.size() > 0 && (!has(self.target.urlFrom.optional) || !self.target.urlFrom.optional)",message="target.urlFrom must name a required Secret key" +kubebuilder:validation:XValidation:rule="!has(self.desired.verificationPolicyFrom) || (self.desired.verificationPolicyFrom.name.size() > 0 && self.desired.verificationPolicyFrom.key.size() > 0 && (!has(self.desired.verificationPolicyFrom.optional) || !self.desired.verificationPolicyFrom.optional))",message="desired.verificationPolicyFrom must name a required ConfigMap key" +kubebuilder:validation:XValidation:rule="!has(self.desired.configMap) || self.desired.configMap.items.size() == 1",message="desired.configMap selects exactly one file for a schema" +kubebuilder:validation:XValidation:rule="!has(self.desired.git) || self.desired.git.path != '.'",message="desired.git.path selects one file for a schema" +kubebuilder:validation:XValidation:rule="!has(self.desired.https) || self.desired.https.path != '.'",message="desired.https.path selects one file for a schema" +kubebuilder:validation:XValidation:rule="!has(self.dev) || (self.dev.urlFrom.name.size() > 0 && self.dev.urlFrom.key.size() > 0 && (!has(self.dev.urlFrom.optional) || !self.dev.urlFrom.optional))",message="dev.urlFrom must name a required Secret key" +kubebuilder:validation:XValidation:rule="!has(self.desired.transport) || !has(self.desired.transport.caFrom) || (self.desired.transport.caFrom.name.size() > 0 && self.desired.transport.caFrom.key.size() > 0 && (!has(self.desired.transport.caFrom.optional) || !self.desired.transport.caFrom.optional))",message="desired.transport.caFrom must name a required ConfigMap key"

func (*PtahSchemaSpec) DeepCopy

func (in *PtahSchemaSpec) DeepCopy() *PtahSchemaSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaSpec.

func (*PtahSchemaSpec) DeepCopyInto

func (in *PtahSchemaSpec) DeepCopyInto(out *PtahSchemaSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PtahSchemaStatus

type PtahSchemaStatus struct {
	// ObservedGeneration is the spec generation this status describes.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Phase is where the resource stands, as one word for a reader. The
	// conditions below are what a decision reads: a resource legitimately
	// passes through several phases while one refusal stays true.
	Phase ReconciliationPhase `json:"phase,omitempty"`

	// ExecutionBinding is the durable identity of the execution epoch
	// authorized to produce new reconciliation evidence. Retained evidence stays
	// historical until refreshed. Epoch changes whenever a bound component
	// changes, including a rollback to identical values; a manager upgrade
	// that changes no bound component keeps it.
	ExecutionBinding *ExecutionBindingStatus `json:"executionBinding,omitempty"`

	// Source is what the desired artifact resolved and verified to.
	Source SchemaSourceStatus `json:"source,omitempty"`
	// Target is what the last observation found in the database.
	Target TargetStatus `json:"target,omitempty"`
	// Plan is the published plan waiting to run, where there is one.
	Plan *CurrentPlanStatus `json:"plan,omitempty"`
	// Applied is the last apply that was independently observed to have
	// converged, which is a different claim from a Job that exited zero.
	Applied *AppliedStatus `json:"applied,omitempty"`

	// PendingObservation is durable proof work created after an Apply Job may
	// have mutated the database. It is independent of Phase so retries and
	// suspension cannot accidentally permit another mutation first.
	PendingObservation *PendingObservationStatus `json:"pendingObservation,omitempty"`
	// PendingLockRelease keeps the exact Lease owner and epoch durable until an
	// idempotent release succeeds. It closes the manager-crash window between a
	// terminal status transition and clearing the owner-neutral Lease.
	PendingLockRelease *TargetLockReleaseStatus `json:"pendingLockRelease,omitempty"`
	// PendingBindingRetirement is the cleanup an execution-binding rotation
	// still owes the epoch it replaced. The status write that installs the new
	// epoch writes it, and it is removed once nothing in it is left. Another
	// rotation waits until it is gone.
	PendingBindingRetirement *BindingRetirementStatus `json:"pendingBindingRetirement,omitempty"`

	// ActiveOperation is the claim for the operation in flight. It is written
	// before the Job exists, which is what lets the controller tell a Job it
	// created from one it has not created yet.
	ActiveOperation *ActiveOperationStatus `json:"activeOperation,omitempty"`

	// LastAttemptTime is when the controller last tried to do something.
	LastAttemptTime *metav1.Time `json:"lastAttemptTime,omitempty"`
	// LastSuccessfulReconciliation is when it last completed a cycle with
	// nothing left to do.
	LastSuccessfulReconciliation *metav1.Time `json:"lastSuccessfulReconciliation,omitempty"`
	// NextReconciliationTime is the durable earliest time for the next
	// scheduled read-only reconciliation. Event-driven safety work may run
	// sooner.
	NextReconciliationTime *metav1.Time `json:"nextReconciliationTime,omitempty"`

	// LastReadRequest is the last value of the operator.ptah.run/read-requested-at
	// annotation the controller answered, so an answered request is not
	// answered again. A value longer than MaxReadRequestLength is recorded as
	// its SHA-256 digest, and a value that is not an RFC 3339 instant is
	// recorded with a Warning Event and starts nothing.
	// +optional
	// +kubebuilder:validation:MaxLength=71
	LastReadRequest string `json:"lastReadRequest,omitempty"`

	// Conditions are the readable verdicts: whether the engine is supported,
	// the artifact resolved and verified, the database was reachable, drift was
	// found, a plan is ready, an approval is required, the schema is in sync,
	// and whether the last reconciliation failed.
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Journal is the bounded record of this schema's significant lifecycle
	// events.
	// +optional
	Journal *LifecycleJournal `json:"journal,omitempty"`
}

PtahSchemaStatus records only credential-free reconciliation evidence.

func (*PtahSchemaStatus) DeepCopy

func (in *PtahSchemaStatus) DeepCopy() *PtahSchemaStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PtahSchemaStatus.

func (*PtahSchemaStatus) DeepCopyInto

func (in *PtahSchemaStatus) DeepCopyInto(out *PtahSchemaStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PublishedPlanChunkStatus

type PublishedPlanChunkStatus struct {
	// Name of the PtahSchemaPlanChunk that was verified.
	Name string `json:"name"`
	// UID it had when it was verified, so a chunk deleted and recreated is not
	// mistaken for the one the plan was published with.
	UID types.UID `json:"uid"`
	// Index of the chunk this record is for.
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=15
	Index int32 `json:"index"`
}

PublishedPlanChunkStatus binds the immutable manifest to the concrete PtahSchemaPlanChunk instances verified before Ready became true.

func (*PublishedPlanChunkStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PublishedPlanChunkStatus.

func (*PublishedPlanChunkStatus) DeepCopyInto

func (in *PublishedPlanChunkStatus) DeepCopyInto(out *PublishedPlanChunkStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type RealmSharing

type RealmSharing string

RealmSharing says whether more than one resource may manage a realm's database at the same time. +kubebuilder:validation:Enum=Exclusive;Shared

const (
	// RealmSharingExclusive admits one claimant at a time. A second one, in
	// any listed namespace, refuses every claimant until one of them leaves.
	RealmSharingExclusive RealmSharing = "Exclusive"
	// RealmSharingShared admits several claimants, provided each of them sets
	// spec.target.sharedRealm.
	RealmSharingShared RealmSharing = "Shared"
)

type ReconciliationPhase

type ReconciliationPhase string

ReconciliationPhase is the externally visible state-machine phase. +kubebuilder:validation:Enum=Pending;Resolving;Verifying;Observing;Planning;ReadyToApply;AwaitingApproval;Blocked;Applying;VerifyingConvergence;InSync;Suspended;Failed

const (
	PhasePending              ReconciliationPhase = "Pending"
	PhaseResolving            ReconciliationPhase = "Resolving"
	PhaseVerifying            ReconciliationPhase = "Verifying"
	PhaseObserving            ReconciliationPhase = "Observing"
	PhasePlanning             ReconciliationPhase = "Planning"
	PhaseReadyToApply         ReconciliationPhase = "ReadyToApply"
	PhaseAwaitingApproval     ReconciliationPhase = "AwaitingApproval"
	PhaseBlocked              ReconciliationPhase = "Blocked"
	PhaseApplying             ReconciliationPhase = "Applying"
	PhaseVerifyingConvergence ReconciliationPhase = "VerifyingConvergence"
	PhaseInSync               ReconciliationPhase = "InSync"
	PhaseSuspended            ReconciliationPhase = "Suspended"
	PhaseFailed               ReconciliationPhase = "Failed"
)

type ReconciliationPolicy

type ReconciliationPolicy struct {
	// Apply decides when a current plan may run: never, only with an approval
	// naming its exact bytes, or as soon as it is ready. Always still waits for
	// an approval when the plan is destructive or changes privileges: grants,
	// role membership, owners, row-security policies or definer rights.
	// +kubebuilder:default=OnApproval
	Apply ApplyPolicy `json:"apply,omitempty"`

	// AllowDestructive permits a plan that drops or rewrites something. It is
	// permission for the category, not for a plan: a destructive plan still
	// needs an approval where the apply policy asks for one.
	// +kubebuilder:default=false
	AllowDestructive bool `json:"allowDestructive,omitempty"`

	// DriftSeverity decides which differences count as drift worth applying:
	// every difference, or only the destructive ones.
	// +kubebuilder:validation:Enum=all;destructive
	// +kubebuilder:default=all
	DriftSeverity string `json:"driftSeverity,omitempty"`

	// Exclude defines the single authoritative managed scope. Raw drift is
	// observed without exclusions, then a read-only plan classifies this exact
	// scope as changed or converged.
	// +kubebuilder:validation:MaxItems=128
	// +listType=set
	// +kubebuilder:validation:items:MinLength=1
	// +kubebuilder:validation:items:MaxLength=256
	// +kubebuilder:validation:items:Pattern=`^[^\p{Z}\x00-\x20\x7f\x{0085}](?:[^\x00-\x1f\x7f]*[^\p{Z}\x00-\x20\x7f\x{0085}])?$`
	// Exclude is the managed scope the apply was computed under.
	Exclude []string `json:"exclude,omitempty"`

	// LockTimeout is how long an operation waits for the database's own lock
	// before giving up, so a busy database delays a run rather than stalling it
	// for the Job's whole deadline.
	// +kubebuilder:default="30s"
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MaxLength=32
	// +kubebuilder:validation:XValidation:rule="duration(self) >= duration('1s') && duration(self) <= duration('10m')",message="lockTimeout must be between 1s and 10m"
	LockTimeout metav1.Duration `json:"lockTimeout,omitempty"`

	// TransactionMode is how the statements are wrapped: all in one
	// transaction, one per file, or none at all. An engine that refuses a mode
	// decides over this rather than around it.
	// +kubebuilder:validation:Enum=all;file;none
	// +kubebuilder:default=file
	TransactionMode string `json:"transactionMode,omitempty"`

	// ProtectedTables fences declared row sets off from the declarative path.
	// A plan that would change a listed table is refused rather than rated, and
	// there is no override: an approval, allowDestructive and a permissive
	// severity are all answers to "how risky is this", and a fence is the
	// statement that no such answer exists for these rows. Where the change is
	// wanted, the entry goes, or the rows are written as a migration.
	//
	// An entry names a table, or a schema and a table, the way the declaration
	// does. Matching is Ptah's, which is case-insensitive, and an entry on a
	// table the artifact already agrees with refuses nothing -- which is what
	// lets a fence sit in a policy permanently.
	//
	// +kubebuilder:validation:MaxItems=128
	// +listType=set
	// +kubebuilder:validation:items:MinLength=1
	// +kubebuilder:validation:items:MaxLength=256
	// +kubebuilder:validation:items:Pattern=`^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$`
	ProtectedTables []string `json:"protectedTables,omitempty"`
}

ReconciliationPolicy defines safety decisions. Destructive plans always need both allowDestructive=true and a matching approval, even in Always mode, and a plan that changes privileges needs a matching approval in every mode.

func (*ReconciliationPolicy) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ReconciliationPolicy.

func (*ReconciliationPolicy) DeepCopyInto

func (in *ReconciliationPolicy) DeepCopyInto(out *ReconciliationPolicy)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type RegistryAuthMode

type RegistryAuthMode string

RegistryAuthMode selects one standard Kubernetes Secret representation. +kubebuilder:validation:Enum=Environment;DockerConfigJSON

type RegistryAuthSource

type RegistryAuthSource struct {
	// Name of the Secret the registry credential is read from. The manager
	// never reads it; the operation Pod does.
	Name string `json:"name"`

	// +kubebuilder:default=Environment
	// Mode says how the credential reaches the executor: as environment
	// variables, or as a Docker config file.
	Mode RegistryAuthMode `json:"mode,omitempty"`

	// Environment mode supports username/password or an identity token. Keys
	// are optional so a single Secret shape can use either credential form.
	// +kubebuilder:default=username
	// UsernameKey is the Secret key holding the username.
	UsernameKey string `json:"usernameKey,omitempty"`
	// +kubebuilder:default=password
	// PasswordKey is the Secret key holding the password.
	PasswordKey string `json:"passwordKey,omitempty"`
	// +kubebuilder:default=token
	// TokenKey is the Secret key holding a bearer token, where one is used
	// instead of a username and password.
	TokenKey string `json:"tokenKey,omitempty"`

	// +kubebuilder:default=.dockerconfigjson
	// DockerConfigJSONKey is the Secret key holding a Docker config document.
	DockerConfigJSONKey string `json:"dockerConfigJSONKey,omitempty"`
}

RegistryAuthSource describes a Secret without requiring the controller to read it. The kubelet projects only the selected credential representation into a Job, while every mode also projects the fixed registry authority grant to the runner. That grant is the Secret's `registry` key, holding the authority-only host[:port] the credential is for. The key is fixed so the Secret owner, rather than a resource author, controls the grant.

func (*RegistryAuthSource) DeepCopy

func (in *RegistryAuthSource) DeepCopy() *RegistryAuthSource

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RegistryAuthSource.

func (*RegistryAuthSource) DeepCopyInto

func (in *RegistryAuthSource) DeepCopyInto(out *RegistryAuthSource)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ResolvedMigrationRunStatus

type ResolvedMigrationRunStatus struct {
	// OperationID is the Apply attempt the settled record named.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	OperationID string `json:"operationID"`
	// Outcome is what that record said.
	Outcome MigrationRunOutcome `json:"outcome"`
	// Resolution is what settled it.
	Resolution MigrationRunResolution `json:"resolution"`
	// AcknowledgmentRef is the PtahMigrationRunAcknowledgment that settled it,
	// when a person did.
	// +optional
	AcknowledgmentRef *ImmutableObjectReference `json:"acknowledgmentRef,omitempty"`
	// AcknowledgedBy is the identity admission stamped on that
	// acknowledgment.
	// +optional
	AcknowledgedBy *ApprovalIdentity `json:"acknowledgedBy,omitempty"`
	// ResolvedAt is when the controller settled it.
	ResolvedAt metav1.Time `json:"resolvedAt"`
}

ResolvedMigrationRunStatus is how an unresolved run was settled.

It is also what lets the manager tell a copy of the record left behind by an interrupted removal from a record a restore brought back: the first names a run this field says was settled, and the second names one status knows nothing about. +kubebuilder:validation:XValidation:rule="self.resolution == 'Acknowledged' ? has(self.acknowledgmentRef) && has(self.acknowledgedBy) : !has(self.acknowledgmentRef) && !has(self.acknowledgedBy)",message="an acknowledged resolution names its acknowledgment and the identity that made it, and a resolution by reading names neither"

func (*ResolvedMigrationRunStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ResolvedMigrationRunStatus.

func (*ResolvedMigrationRunStatus) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type RetiredJobStatus

type RetiredJobStatus struct {
	// Operation is the claim that dispatched the Job.
	// +kubebuilder:validation:Enum=Resolve;Verify;Observe;Plan;Apply
	Operation OperationType `json:"operation"`
	// Name is the Job's deterministic name.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
	// UID is the Job's UID once it is known. It is absent while a create the
	// retired claim started may still commit; the controller adopts it from a
	// Job under Name that carries the claim's exact envelope.
	// +optional
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MaxLength=128
	UID types.UID `json:"uid,omitempty"`
}

RetiredJobStatus is the Job a retired epoch's claim dispatched. The claim that holds the rest of its identity stays where it was: an Apply in status.pendingObservation, a read-only operation in status.activeOperation until its Job is cleaned up.

func (*RetiredJobStatus) DeepCopy

func (in *RetiredJobStatus) DeepCopy() *RetiredJobStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RetiredJobStatus.

func (*RetiredJobStatus) DeepCopyInto

func (in *RetiredJobStatus) DeepCopyInto(out *RetiredJobStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type RetiredPlanReference

type RetiredPlanReference struct {
	// Name of the PtahSchemaPlan.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
	// UID it had.
	// +kubebuilder:validation:Type=string
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	UID types.UID `json:"uid"`
	// Fingerprint is its approval identity.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	Fingerprint string `json:"fingerprint"`
}

RetiredPlanReference names a retired PtahSchemaPlan the way an approval names it: by name, UID and fingerprint.

func (*RetiredPlanReference) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RetiredPlanReference.

func (*RetiredPlanReference) DeepCopyInto

func (in *RetiredPlanReference) DeepCopyInto(out *RetiredPlanReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type RuntimeClassAdmissionSnapshot

type RuntimeClassAdmissionSnapshot struct {
	// Object is the RuntimeClass this was read from, by name and UID.
	Object AdmissionObjectBinding `json:"object"`
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// Handler is the runtime handler it names.
	Handler string `json:"handler"`
	// OverheadDefined distinguishes an absent RuntimeClass overhead stanza from
	// a present but empty one; Kubernetes admission preserves that distinction.
	// OverheadDefined separates a class with no overhead from one whose
	// overhead is zero.
	OverheadDefined bool `json:"overheadDefined,omitempty"`
	// +kubebuilder:validation:MaxProperties=64
	// Overhead is the per-Pod resource overhead the class adds.
	Overhead map[corev1.ResourceName]resource.Quantity `json:"overhead,omitempty"`
	// +kubebuilder:validation:MaxProperties=64
	// NodeSelector is the scheduling the class forces.
	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
	// +kubebuilder:validation:MaxItems=64
	// Tolerations are the tolerations it adds.
	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
}

RuntimeClassAdmissionSnapshot records the exact scheduling and overhead mutation selected before dispatch. Handler is deliberately retained as credential-free audit evidence even though it is not copied into PodSpec.

func (*RuntimeClassAdmissionSnapshot) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RuntimeClassAdmissionSnapshot.

func (*RuntimeClassAdmissionSnapshot) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type SchemaApplyFailureStatus added in v0.2.11

type SchemaApplyFailureStatus struct {
	// Statement is the position of the failed statement in the plan,
	// counting from one.
	// +kubebuilder:validation:Minimum=1
	Statement int32 `json:"statement"`
	// Statements is how many statements the plan has.
	// +kubebuilder:validation:Minimum=1
	Statements int32 `json:"statements"`
	// SQLState is the SQLSTATE the database answered with, empty when it gave
	// none.
	// +kubebuilder:validation:Pattern=`^[0-9A-Z]{5}$`
	// +optional
	SQLState string `json:"sqlState,omitempty"`
	// ErrorNumber is MySQL's own error number, zero on every other protocol.
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=65535
	// +optional
	ErrorNumber int32 `json:"errorNumber,omitempty"`
}

SchemaApplyFailureStatus is where a PtahSchema's Apply stopped: the statement it stopped at, and the code the database answered with, when it answered. The database's message is not kept, because it can quote a row.

func (*SchemaApplyFailureStatus) DeepCopy added in v0.2.11

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SchemaApplyFailureStatus.

func (*SchemaApplyFailureStatus) DeepCopyInto added in v0.2.11

func (in *SchemaApplyFailureStatus) DeepCopyInto(out *SchemaApplyFailureStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type SchemaSourceStatus

type SchemaSourceStatus struct {
	// RequestedReference is what spec.desired asked for, tag and all.
	RequestedReference string `json:"requestedReference,omitempty"`
	// ResolvedReference is the same artifact with the tag replaced by the
	// digest it resolved to. Every later read uses this.
	ResolvedReference string `json:"resolvedReference,omitempty"`
	// Digest is that digest on its own.
	Digest string `json:"digest,omitempty"`
	// MediaType is the manifest's media type.
	MediaType string `json:"mediaType,omitempty"`
	// ArtifactType says which format this is: a declared schema or a versioned
	// migration directory.
	ArtifactType string `json:"artifactType,omitempty"`
	// Size is the manifest's size in bytes.
	Size int64 `json:"size,omitempty"`
	// Verified says the verification policy accepted it. It goes false again
	// when the policy changes, because the old answer was about the old rules.
	Verified bool `json:"verified,omitempty"`

	// VerificationPolicyUID is the policy object that accepted it.
	VerificationPolicyUID types.UID `json:"verificationPolicyUID,omitempty"`
	// VerificationPolicyDigest is that policy's content at the time.
	VerificationPolicyDigest string `json:"verificationPolicyDigest,omitempty"`
	// ResolvedAt is when the tag was last resolved.
	ResolvedAt *metav1.Time `json:"resolvedAt,omitempty"`
	// VerifiedAt is when the policy last accepted it.
	VerifiedAt *metav1.Time `json:"verifiedAt,omitempty"`

	// ConfigMap is the source ConfigMap the files were last read from, for a
	// ConfigMap source. A ConfigMap source has no verification policy, so
	// verified stays false; the snapshot below is what later operations read.
	// +optional
	ConfigMap *ConfigMapSourceRevision `json:"configMap,omitempty"`
	// Snapshot is the immutable copy of the selected files, and their content
	// digest, for a ConfigMap source.
	// +optional
	Snapshot *SourceSnapshotBinding `json:"snapshot,omitempty"`
	// Git is the commit a Git source last resolved to, and the content
	// digest of the selected files there. A Git source has no verification
	// policy, so verified stays false.
	// +optional
	Git *GitSourceRevision `json:"git,omitempty"`
	// HTTPS is the download an HTTPS source last resolved, and the content
	// digest of the selected files in it. An HTTPS source has no verification
	// policy, so verified stays false.
	// +optional
	HTTPS *HTTPSSourceRevision `json:"https,omitempty"`
	// SourcePolicy is the source policy the last resolution was checked
	// against, when the spec names one.
	// +optional
	SourcePolicy *SourcePolicyBinding `json:"sourcePolicy,omitempty"`
}

SchemaSourceStatus binds the requested reference to verified immutable data.

func (*SchemaSourceStatus) DeepCopy

func (in *SchemaSourceStatus) DeepCopy() *SchemaSourceStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SchemaSourceStatus.

func (*SchemaSourceStatus) DeepCopyInto

func (in *SchemaSourceStatus) DeepCopyInto(out *SchemaSourceStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ServiceAccountAdmissionSnapshot

type ServiceAccountAdmissionSnapshot struct {
	// Object is the ServiceAccount the Pod runs as.
	Object AdmissionObjectBinding `json:"object"`
	// +kubebuilder:validation:MaxItems=64
	// ImagePullSecrets are the pull Secrets it contributes to the Pod.
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`
}

ServiceAccountAdmissionSnapshot binds the non-secret ServiceAccount fields that built-in admission may copy into a Pod.

func (*ServiceAccountAdmissionSnapshot) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ServiceAccountAdmissionSnapshot.

func (*ServiceAccountAdmissionSnapshot) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type SourceAccessBinding added in v0.2.7

type SourceAccessBinding struct {
	// ResolvedReference is the artifact with its tag replaced by a digest.
	// +optional
	ResolvedReference string `json:"resolvedReference,omitempty"`
	// Digest is that digest on its own.
	// +optional
	Digest string `json:"digest,omitempty"`
	// RegistryAuthFrom names the Secret an operation Pod reads the registry
	// credential from. It is a selector, never the credential.
	RegistryAuthFrom *RegistryAuthSource `json:"registryAuthFrom,omitempty"`
	// Transport is how the registry is reached: plain HTTP, a custom CA.
	Transport OCITransportSpec `json:"transport,omitempty"`
	// Snapshot is the immutable ConfigMap a ConfigMap source's files were
	// copied into, and the content it must hold.
	// +optional
	Snapshot *SourceSnapshotBinding `json:"snapshot,omitempty"`
	// Git is the commit a Git source resolved to, where to fetch it from,
	// and the content it must give.
	// +optional
	Git *GitSourceBinding `json:"git,omitempty"`
	// HTTPS is the download an HTTPS source resolved, where to fetch it
	// from, and the content it must give.
	// +optional
	HTTPS *HTTPSSourceBinding `json:"https,omitempty"`
}

SourceAccessBinding is the credential-free, immutable account of how an operation reads the desired files: an OCI artifact pinned by digest with the Kubernetes selectors needed to fetch it, or the snapshot a ConfigMap source was copied into. It is persisted across post-Apply proof so a newer generation cannot send newly selected credentials to the old artifact's registry, or read files the plan was not computed from. +kubebuilder:validation:XValidation:rule="[has(self.resolvedReference), has(self.snapshot), has(self.git), has(self.https)].filter(set, set).size() == 1",message="set exactly one of resolvedReference, snapshot, git and https"

func (*SourceAccessBinding) DeepCopy added in v0.2.7

func (in *SourceAccessBinding) DeepCopy() *SourceAccessBinding

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SourceAccessBinding.

func (*SourceAccessBinding) DeepCopyInto added in v0.2.7

func (in *SourceAccessBinding) DeepCopyInto(out *SourceAccessBinding)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type SourceKind added in v0.2.7

type SourceKind string

SourceKind names a kind of source a plan can be bound to besides an OCI artifact, which plans bind through artifactDigest. +kubebuilder:validation:Enum=ConfigMap;Git;HTTPS

const (
	// SourceKindConfigMap is a ConfigMap in the resource's namespace.
	SourceKindConfigMap SourceKind = "ConfigMap"
	// SourceKindGit is one commit of a Git repository.
	SourceKindGit SourceKind = "Git"
	// SourceKindHTTPS is one download pinned by its digest.
	SourceKindHTTPS SourceKind = "HTTPS"
)

type SourcePolicyBinding added in v0.2.7

type SourcePolicyBinding struct {
	// UID of the policy ConfigMap. Another ConfigMap under the same name is
	// another policy.
	UID types.UID `json:"uid"`
	// Digest is "sha256:" and the SHA-256 of the policy document.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	Digest string `json:"digest"`
}

SourcePolicyBinding is the source policy a resolution was checked against: the ConfigMap's UID and the digest of the selected bytes.

func (*SourcePolicyBinding) DeepCopy added in v0.2.7

func (in *SourcePolicyBinding) DeepCopy() *SourcePolicyBinding

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SourcePolicyBinding.

func (*SourcePolicyBinding) DeepCopyInto added in v0.2.7

func (in *SourcePolicyBinding) DeepCopyInto(out *SourcePolicyBinding)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type SourceSnapshotBinding added in v0.2.7

type SourceSnapshotBinding struct {
	// Name of the snapshot ConfigMap, in the resource's namespace.
	// +kubebuilder:validation:Pattern=`^ptah-src-[0-9a-f]{24}$`
	Name string `json:"name"`
	// UID the snapshot had when it was bound. A snapshot deleted and written
	// again under the same name is another object.
	UID types.UID `json:"uid"`
	// ContentDigest is the content digest of the selected files: the SHA-256
	// of a manifest with one line per file, sorted by path, naming the
	// file's SHA-256, its size and its path.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	ContentDigest string `json:"contentDigest"`
	// SchemaFile is the path, inside the snapshot, of the one file a schema
	// reads. A migration reads the whole directory and leaves it empty.
	// +optional
	// +kubebuilder:validation:MaxLength=1024
	SchemaFile string `json:"schemaFile,omitempty"`
}

SourceSnapshotBinding names the snapshot an operation reads a ConfigMap source through, and the content it has to hold. The operation Pod checks every file and the manifest against the content digest before the operation starts, and refuses a snapshot that no longer gives it.

func (*SourceSnapshotBinding) DeepCopy added in v0.2.7

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SourceSnapshotBinding.

func (*SourceSnapshotBinding) DeepCopyInto added in v0.2.7

func (in *SourceSnapshotBinding) DeepCopyInto(out *SourceSnapshotBinding)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type SourceSpec added in v0.2.7

type SourceSpec struct {
	// OCIRef is a desired-schema artifact reference. It may name a tag or a
	// digest; every later operation receives only the resolved digest.
	// +optional
	// +kubebuilder:validation:MinLength=7
	// +kubebuilder:validation:Pattern=`^oci://[^[:space:]?#]+$`
	OCIRef string `json:"ociRef,omitempty"`

	// ConfigMap selects files from a ConfigMap in this resource's namespace.
	// Whoever may write that ConfigMap may change the desired state, exactly
	// as whoever may write this resource can: Kubernetes RBAC on the
	// namespace is what this source is trusted by. The manager copies the
	// selected files into an immutable snapshot, and every operation reads
	// the snapshot.
	// +optional
	ConfigMap *ConfigMapSourceSpec `json:"configMap,omitempty"`

	// Git selects a file or a directory of one commit of a Git repository.
	// The manager never reads the repository or its credential: a Job's fetch
	// container fetches the commit through Ptah, and every later operation
	// fetches the same commit again and refuses any other content.
	// +optional
	Git *GitSourceSpec `json:"git,omitempty"`

	// HTTPS selects a file or a directory of one download, pinned by the
	// SHA-256 of the bytes the URL serves. The manager never reads the
	// download or its credential: a Job's fetch container downloads it
	// through Ptah, and every later operation downloads it again and refuses
	// other bytes or other content. Nothing is stored in the cluster.
	// +optional
	HTTPS *HTTPSSourceSpec `json:"https,omitempty"`

	// RegistryAuthFrom names the Secret an operation Pod reads the registry
	// credential from. The process that runs SQL never receives it.
	RegistryAuthFrom *RegistryAuthSource `json:"registryAuthFrom,omitempty"`

	// VerificationPolicyFrom names the immutable ConfigMap holding the policy
	// the artifact must satisfy. Editing it retires the plans computed under
	// the previous version rather than letting them apply. It is required
	// with ociRef and refused with configMap, git and https: its rules are
	// about OCI artifacts, and a policy nothing evaluates would read as a
	// gate.
	// +optional
	VerificationPolicyFrom *corev1.ConfigMapKeySelector `json:"verificationPolicyFrom,omitempty"`

	// SourcePolicyFrom names the immutable ConfigMap holding what a team
	// refuses for a ConfigMap, Git or HTTPS source: the hosts a Git or an
	// HTTPS source may name, the ConfigMaps a ConfigMap source may name, and
	// the most the selected files may hold. A plan binds the policy's object
	// and bytes,
	// so another policy retires it. An OCI source has its verification
	// policy instead, and the API refuses this beside ociRef.
	// +optional
	SourcePolicyFrom *corev1.ConfigMapKeySelector `json:"sourcePolicyFrom,omitempty"`

	// Transport is how the registry is reached: plain HTTP, a custom CA.
	Transport OCITransportSpec `json:"transport,omitempty"`
}

SourceSpec names where the desired files come from: an OCI artifact, a ConfigMap in the resource's own namespace, one commit of a Git repository, or one HTTPS download pinned by its digest. The schema and the migration APIs share it, and keep their reconciliation lifecycles separate. +kubebuilder:validation:XValidation:rule="[has(self.ociRef), has(self.configMap), has(self.git), has(self.https)].filter(set, set).size() == 1",message="set exactly one of ociRef, configMap, git and https" +kubebuilder:validation:XValidation:rule="has(self.ociRef) == has(self.verificationPolicyFrom)",message="verificationPolicyFrom is required with ociRef and refused with configMap, git and https" +kubebuilder:validation:XValidation:rule="has(self.ociRef) || !has(self.registryAuthFrom)",message="registryAuthFrom is refused with configMap, git and https" +kubebuilder:validation:XValidation:rule="has(self.ociRef) || !has(self.transport) || (!has(self.transport.caFrom) && (!has(self.transport.plainHTTP) || !self.transport.plainHTTP))",message="transport is refused with configMap, git and https" +kubebuilder:validation:XValidation:rule="!has(self.sourcePolicyFrom) || !has(self.ociRef)",message="sourcePolicyFrom is for configMap, git and https sources" +kubebuilder:validation:XValidation:rule="!has(self.sourcePolicyFrom) || (self.sourcePolicyFrom.name.size() > 0 && self.sourcePolicyFrom.key.size() > 0 && (!has(self.sourcePolicyFrom.optional) || !self.sourcePolicyFrom.optional))",message="sourcePolicyFrom must name a required ConfigMap key"

func (*SourceSpec) DeepCopy added in v0.2.7

func (in *SourceSpec) DeepCopy() *SourceSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SourceSpec.

func (*SourceSpec) DeepCopyInto added in v0.2.7

func (in *SourceSpec) DeepCopyInto(out *SourceSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type TargetLockReleaseStatus

type TargetLockReleaseStatus struct {
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	// CoordinationDigest is the realm whose lock is still to be released.
	CoordinationDigest string `json:"coordinationDigest"`
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=256
	// OperationID is the operation that took it.
	OperationID string `json:"operationID"`
	// +kubebuilder:validation:Minimum=5
	// +kubebuilder:validation:Maximum=86460
	// LeaseDurationSeconds is how long it was taken for.
	LeaseDurationSeconds int32 `json:"leaseDurationSeconds"`
	// +kubebuilder:validation:Pattern=`^v1-[0-9a-f]{32}$`
	// LeaseEpoch identifies that acquisition, so a release cannot free a lock
	// somebody else acquired in the meantime.
	LeaseEpoch string `json:"leaseEpoch"`
}

TargetLockReleaseStatus is the complete credential-free request required to retry one exact database-realm Lease release after a manager restart.

func (*TargetLockReleaseStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TargetLockReleaseStatus.

func (*TargetLockReleaseStatus) DeepCopyInto

func (in *TargetLockReleaseStatus) DeepCopyInto(out *TargetLockReleaseStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type TargetStatus

type TargetStatus struct {
	// Engine is the database engine this target speaks.
	Engine DatabaseEngine `json:"engine,omitempty"`
	// CoordinationDigest is the realm this target serializes against, so two
	// resources pointed at one database take turns.
	CoordinationDigest string `json:"coordinationDigest,omitempty"`
	// IdentityDigest identifies the database without carrying anything that
	// could reach it.
	IdentityDigest string `json:"identityDigest,omitempty"`
	// DriftReportDigest is the observed state the last plan was computed from.
	DriftReportDigest string `json:"driftReportDigest,omitempty"`
	// LastObservedAt is when that observation ran.
	LastObservedAt *metav1.Time `json:"lastObservedAt,omitempty"`
	// HighestDriftSeverity is the worst category the report found. It is set
	// whenever the report found drift and empty when it found none, so it also
	// says which. Should a report find drift it lists under no category, that
	// reads safe here, with no findings and a zero count; the plan says what it
	// changes.
	HighestDriftSeverity string `json:"highestDriftSeverity,omitempty"`
	// DriftFindingCount is how many findings the report held: the sum of the
	// counts below. Drift in no category counts none.
	DriftFindingCount int32 `json:"driftFindingCount,omitempty"`
	// DriftFindings contains only category-level aggregates, one per category
	// the report found. The list is never truncated: it is keyed by category,
	// and the bound holds every category in the vocabulary.
	// +kubebuilder:validation:MaxItems=128
	// +listType=map
	// +listMapKey=category
	DriftFindings []DriftFindingStatus `json:"driftFindings,omitempty"`
	// Inventory counts each kind of object that observation compared: how
	// many the desired schema declares and how many the comparison found in
	// the database, in the compared scope. A kind names the findings it joins,
	// so tables counts what tables_added and tables_removed are found among,
	// and ptah.run/pgextension/extension-change what
	// feature_changes:ptah.run/pgextension/extension-change is. A kind neither
	// side holds is left out. Counts only, written and replaced with the
	// findings. A Ptah that does not count leaves it absent.
	// +optional
	// +kubebuilder:validation:MaxItems=128
	// +listType=map
	// +listMapKey=kind
	Inventory []ObjectInventoryStatus `json:"inventory,omitempty"`
}

TargetStatus identifies the Secret value and observed schema without disclosing either the connection string or its credentials.

func (*TargetStatus) DeepCopy

func (in *TargetStatus) DeepCopy() *TargetStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TargetStatus.

func (*TargetStatus) DeepCopyInto

func (in *TargetStatus) DeepCopyInto(out *TargetStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type UnresolvedMigrationRunStatus

type UnresolvedMigrationRunStatus struct {

	// Outcome is what the run's own evidence said, and is always Partial or
	// Unknown: Partial committed some of a migration's statements and not the
	// rest, and Unknown could not be read at all. No other outcome leaves the
	// database in a state nobody can name, so no other outcome is recorded
	// here.
	Outcome MigrationRunOutcome `json:"outcome"`

	// OperationID is the Apply claim that ran, so this record names one attempt
	// rather than the resource in general.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	OperationID string `json:"operationID"`

	// JobName and JobUID identify the execution. The UID is what makes a
	// replacement Job with the same name a different run.
	// +kubebuilder:validation:MaxLength=253
	JobName string `json:"jobName,omitempty"`
	// JobUID is that Job's UID.
	JobUID types.UID `json:"jobUID,omitempty"`

	// PlanRef names the plan the run was carrying out, which is the work that
	// may have reached the database.
	PlanRef ImmutableObjectReference `json:"planRef"`

	// TargetIdentityDigest is the credential-free identity of the database this
	// run's result named. Where no result frame was read at all -- which is most
	// of the ways a run becomes unresolved -- it is the database its plan was
	// computed against instead. That is the only database the run can have
	// changed: the runner refuses an Apply whose URL names another target before
	// Ptah starts, so a result that names another one reports a run that
	// changed nothing.
	//
	// The reading that settles this record has to be of that database: a
	// history read somewhere else says nothing about what this run did.
	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
	TargetIdentityDigest string `json:"targetIdentityDigest,omitempty"`

	// DispatchedBy is the manager that built and dispatched the run's Job, as
	// status.lastRun recorded it. It is absent when the run was settled
	// without its Job.
	// +optional
	DispatchedBy *ManagerRecord `json:"dispatchedBy,omitempty"`

	// RecordedAt is when the controller wrote this record.
	RecordedAt metav1.Time `json:"recordedAt"`
}

UnresolvedMigrationRunStatus is the execution whose effect on the database nobody has established, and the evidence a person needs to go and establish it.

It exists because a condition cannot hold this. A condition says why the resource is refused right now, and every later refusal -- a realm a second resource claimed, a dirty revision, an applied migration whose file moved -- legitimately writes its own reason over it. Whether a mutation that may have run was ever accounted for is a different question, and no refusal answers it, so it is recorded rather than inferred.

func (*UnresolvedMigrationRunStatus) DeepCopy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new UnresolvedMigrationRunStatus.

func (*UnresolvedMigrationRunStatus) DeepCopyInto

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

Jump to

Keyboard shortcuts

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