workload

package
v0.2.13 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Overview

Package workload builds the bounded Kubernetes Jobs used by the schema controller. It is deliberately a pure builder: credentials are represented only by namespaced Kubernetes references and are never read into controller memory.

Index

Constants

View Source
const (

	// LabelManagedBy identifies Jobs managed by this operator.
	LabelManagedBy = "app.kubernetes.io/managed-by"
	// LabelComponent identifies the bounded schema-operation component.
	LabelComponent = "app.kubernetes.io/component"
	// LabelSchema associates a Job with its namespaced PtahSchema name.
	LabelSchema = "operator.ptah.run/schema"
	// LabelOperation identifies the fixed operation executed by a Job.
	LabelOperation = "operator.ptah.run/operation"
	// LabelOperationID carries a label-safe hash of the full operation ID.
	LabelOperationID = "operator.ptah.run/operation-id"

	// ComponentSchemaOperation and ComponentMigrationOperation are the two
	// values LabelComponent takes. They say which resource dispatched a Job,
	// and admission reads them to decide which claim judges it.
	ComponentSchemaOperation    = "schema-operation"
	ComponentMigrationOperation = "migration-operation"

	// AnnotationOperationID binds Pod logs to the full operation claim.
	AnnotationOperationID = "operator.ptah.run/operation-id"
	// AnnotationInputFingerprint records the operation's immutable input hash.
	AnnotationInputFingerprint = "operator.ptah.run/input-fingerprint"
	// AnnotationPtahVersion records the configured data-plane version.
	AnnotationPtahVersion = "operator.ptah.run/ptah-version"
	// AnnotationExecutionBindingID records the durable evidence epoch.
	AnnotationExecutionBindingID = "operator.ptah.run/execution-binding-id"
	// AnnotationControllerImage records the exact manager container content that
	// built and dispatched the Job. It is a record, not a binding: a later
	// manager that shares the execution binding adopts the Job as it stands.
	AnnotationControllerImage = "operator.ptah.run/controller-image"
	// AnnotationControllerRevision records the exact manager build that built
	// and dispatched the Job, on the same terms.
	AnnotationControllerRevision = "operator.ptah.run/controller-revision"
	// AnnotationControllerStateVersion records the manager-side state contract.
	AnnotationControllerStateVersion = "operator.ptah.run/controller-state-version"
	// AnnotationPlanFingerprint records the exact approved plan binding.
	AnnotationPlanFingerprint = "operator.ptah.run/plan-fingerprint"
	// AnnotationPlanContentDigest records the reconstructed plan byte digest.
	AnnotationPlanContentDigest = "operator.ptah.run/plan-content-digest"
	// AnnotationAdmissionSnapshotDigest binds the Job and every resulting Pod
	// to the credential-free admission envelope persisted before dispatch.
	AnnotationAdmissionSnapshotDigest = "operator.ptah.run/admission-snapshot-digest"
	// AnnotationSafeToEvict is the cluster autoscaler's own annotation. A Pod
	// that says "false" is not evicted to remove its node.
	//
	// Every mutating operation Pod says so. An Apply stopped part way is an
	// Apply the controller has to account for before anything else runs, and a
	// scale-down is not a reason to leave one. The annotation binds only the
	// autoscaler: a drain, a preemption and node pressure still stop the Pod,
	// which is what the runner's SIGTERM handling is for.
	AnnotationSafeToEvict = "cluster-autoscaler.kubernetes.io/safe-to-evict"
)
View Source
const (
	// EnvActor is how an Apply tells Ptah who it records: in
	// schema_migrations_log for a migration, and in ptah_schema_apply_log for
	// a schema. It fills `migrations up --actor` and `schema apply --actor`
	// through Ptah's own environment binding, so the name never reaches a
	// command line: it is not an argument the runner assembles, nothing can
	// read it as a flag, and no shell is involved.
	EnvActor = "PTAH_ACTOR"

	// EnvActorOrigin fills --actor-origin the same way. Ptah stores the word
	// in the actor_origin column beside the name, and refuses it without a
	// name, so a Job sets both or neither.
	EnvActorOrigin = "PTAH_ACTOR_ORIGIN"

	// ActorOriginAdmission says the name is the username admission stamped on
	// the approval the run consumed.
	ActorOriginAdmission = "admission"

	// ActorOriginPolicy says no person approved the run: apply: Always allowed
	// it, and the name is the fixed one under ReservedActorPrefix.
	ActorOriginPolicy = "policy"

	// MaxActorBytes bounds the name a run records, after encoding.
	//
	// Both of Ptah's actor columns are VARCHAR(256), and a value it refuses
	// costs more than the value: measured on Ptah v0.18.0, PostgreSQL 17 and
	// MySQL 8.4, the migration still applies and exits 0 and every one of its
	// log rows is lost, with only a warning on the executor's stderr. An
	// encoded name is ASCII, so its bytes and its characters are the same
	// number under every character set, and it holds no $, so the kubelet
	// cannot lengthen it on the way to the process.
	MaxActorBytes = 256

	// ReservedActorPrefix starts every name the operator records on its own
	// account. Admission refuses a migration approval from a username under it,
	// so the log cannot read a person's decision as a run nobody approved, or
	// the reverse. A schema approval is not refused, and the origin beside the
	// name is what tells the two apart there.
	ReservedActorPrefix = "system:ptah-operator:"
)
View Source
const CleanupTTLSeconds int32 = 300

CleanupTTLSeconds is the ttlSecondsAfterFinished a read-only operation Job is created with, and the one the manager gives every other Job once it has finished with it (jobclaim.CleanupTTLSeconds). Kubernetes counts it from the moment the Job finishes, so it ends nothing that is running: a read Job runs until it stops or reaches its deadline, and is collected five minutes later, whichever claim let go of it. An Apply Job is created with no TTL, because how long its Pod log is kept depends on what the run reported.

View Source
const JobDeadlineGrace = time.Minute

boundedDeadline returns the Job deadline. A mutating operation carries an absolute instant after which its child may not still be running, and the Job deadline is what remains of it, so a Pod scheduled late inherits the original bound rather than a fresh one.

A window that has already closed yields no Job: Kubernetes refuses a non-positive activeDeadlineSeconds, and a claim whose execution bound passed before dispatch is one the controller has to retire rather than send. JobDeadlineGrace is how long a migration Apply Job outlives the window that authorized it.

Without it the two die together. The window ends at startedAt plus the deadline, and the Job's own relative deadline runs from its status.startTime, which is later by the snapshot and dispatch boundaries -- so a Pod that starts near the end of the window is killed by Kubernetes on DeadlineExceeded at very nearly the instant the runner would have refused it, and the Job ends with no runner frame at all.

With the grace the Pod starts, and the runner refuses on dispatch_deadline_expired before it opens the database and says so in its frame. That does not settle the run: a refusal is the runner's account, and what clears an unresolved record is a reading of the database, so the run is still recorded as one nobody accounted for. What changes is the evidence the record carries -- the refusal, named, instead of nothing -- and that the refusal can be observed at all, which a Pod killed at the same instant never allowed.

The value is the margin this operator already uses for the same kind of boundary: the Lease outlives the window by a minute, and the Lease duration now covers this grace as well, so a Job bounded by it cannot still be running when the Lease has gone to another operation. The child's context deadline is the window itself, so the extra life is refusal time and the time a child asked to stop at the window takes to do so (runner.ChildStopDelay, twenty seconds of the Pod's default grace), not execution time.

A schema Apply takes no grace. Its Job ends with its window, and the fault suite proves what Kubernetes' DeadlineExceeded leaves behind on that path; a runner deadline a minute ahead of the Job's would make that proof one nothing can reach. The late start the grace makes observable is #182's, a migration's.

View Source
const (

	// LabelMigration associates a Job with its namespaced PtahMigration name,
	// as LabelSchema does for a schema operation.
	LabelMigration = "operator.ptah.run/migration"
)
View Source
const MaxEncodedMigrationSequence = 120 << 10

MaxEncodedMigrationSequence is the most bytes the approved sequence may take in the Apply Job's environment. The kernel refuses to start a process with any one environment string over 128 KiB, and a Job whose container cannot start leaves a run nobody can account for, so the bound sits below that with room for the variable's name. A plan is refused at publication rather than here, by EncodeMigrationSequence.

View Source
const ProtocolVersion = runner.ProtocolVersion

ProtocolVersion exposes the runner binding used when a plan is constructed.

Variables

This section is empty.

Functions

func CarryCredentialDelivery added in v0.2.11

func CarryCredentialDelivery(expected, live *batchv1.Job) bool

CarryCredentialDelivery rewrites an expected Job into the shape a release before file delivery built, when live has that shape, and reports whether it did. It is CarryManagerIdentity's counterpart for the one other difference between a Job 0.2.10 dispatched and the Job this release rebuilds from the same claim: where each credential sits.

A Job 0.2.10 built reads every credential from a secretKeyRef in its container's environment and runs the OCI fetch as Ptah itself. This release builds the same Job with each credential in a Secret volume, a variable naming the file, and the runner in front of the OCI fetch. The rewrite puts back the reference each file came from -- the same Secret, key and optional flag -- removes the volumes and mounts that only carried those files, and gives the fetch container back to Ptah. Nothing else is touched, so any other difference still fails the comparison that follows.

What that comparison accepts is still pinned to the claim: the live Pod template has to digest to what the claim's admission snapshot recorded, and this release records the digest of the file-delivery template. A Job in the old shape therefore matches only a claim a release that built that shape made, which is the Job an upgrade finds running.

The callers are the comparisons that hold a live Job to its claim after a restart or an upgrade. A Job this manager submits is never rewritten: it has to be the shape this release builds.

func CarryManagerIdentity

func CarryManagerIdentity(expected, live *batchv1.Job) bool

CarryManagerIdentity rewrites the manager identity of an expected Job to the one the live Job's Pod template was built with: the two annotations that record the manager, on the Job and on its Pod template, and the image of the container that installs the runner. It reports whether anything changed.

A manager rebuilds a Job to check that the live one is what its claim authorized. A Job dispatched by an earlier manager of the same execution binding differs from that rebuild in exactly these values and in nothing a plan or an approval binds, so the comparison takes them from the live Job. Both levels are taken from the live template, which the admission snapshot pins, and never from the Job's own annotations, which nothing pins: a live Job whose own annotations disagree with its template then fails the comparison instead of carrying the edit into it. A caller that carried anything must still hold the live Pod template to the digest its claim persisted before dispatch.

func CarrySealedPlanKey

func CarrySealedPlanKey(expected, live *batchv1.Job, operation operatorv1alpha1.ActiveOperationStatus) error

CarrySealedPlanKey is CarryManagerIdentity's counterpart for the one value a rebuild cannot simply trust from the live Job: the public key a Plan Job's runner seals its plan payload to.

Every process generates its own key pair at startup and never persists it (internal/planseal), so a live Plan Job may have been built, and its Pod admission snapshot resolved, by a different process of the same execution binding -- another replica validating the same webhook request, or the same replica after a restart -- than the one rebuilding expected to check it. Unlike the manager image and revision, which are the same across every replica of one release and so need no proof beyond what the live Job already says, a key is proof of nothing by itself: any 32 bytes decode as one. What makes carrying it safe is checking it first, against the digest recorded on the operation claim before the one Job this key could belong to was ever created.

Called only for a Plan operation; every other operation type carries no seal key, and both sides have none to disagree about.

func EncodeMigrationSequence

func EncodeMigrationSequence(planned []operatorv1alpha1.PlannedMigration) (string, error)

EncodeMigrationSequence is the approved sequence as the Apply Job carries it, or an error when it would not fit. Plan publication calls it so a sequence no Job could carry never becomes a plan anyone approves.

func ManagerIdentityOf

func ManagerIdentityOf(job *batchv1.Job) (controllerImage, controllerRevision, runnerImage string)

ManagerIdentityOf reads the manager identity a live operation Job records, from its Pod template: the manager image and revision annotations and the image of the container that installs the runner. A value the template does not carry reads as empty.

The template is the part of the Job the claim's admission snapshot digests, so a caller that holds the template to that digest holds this identity to it too. The Job's own annotations carry the same two values, and nothing pins them.

func MarkMutatingOperation

func MarkMutatingOperation(annotations map[string]string)

MarkMutatingOperation adds what a mutating operation Job and its Pod carry beyond the operation envelope. The builder writes the marks through it, and every check that holds a Job to an exact annotation set adds them through it too, so no check can fall behind the builder on which keys an Apply Job has.

func MigrationActor added in v0.2.10

func MigrationActor(
	migration *operatorv1alpha1.PtahMigration,
	approval *operatorv1alpha1.PtahMigrationApproval,
) string

MigrationActor is the name a migration Apply records in the database's own log: the username admission stamped on the approval it consumes, which is a field only the webhook writes, or, when no approval authorized the run because the policy is apply: Always, a fixed name that says so and names the resource. Either way it is encoded by encodedActor.

The claim persists the result, so this runs once per claim. Reading the approval again at build time would make a deleted approval unbuildable, and a run the manager could no longer account for.

func MigrationActorOrigin added in v0.2.13

func MigrationActorOrigin(operation operatorv1alpha1.MigrationOperationStatus) string

MigrationActorOrigin is the word a migration Apply records beside its actor: admission when the claim names the approval it consumed, policy when it names none. The claim records both, so the Job a claim builds does not move with anything that happens to the approval afterwards.

func MigrationSequenceDigest

func MigrationSequenceDigest(planned []operatorv1alpha1.PlannedMigration) (string, error)

MigrationSequenceDigest is fingerprint.MigrationSequenceDigest over a plan's sequence.

It lives here rather than beside the rest of the plan derivation because the Job that executes a plan has to carry this digest, and internal/migrationplan is built on top of this package. That package's SequenceDigest calls this, and the runner digests the sequence it receives with the same function, so there is one rule rather than copies that can drift.

func NameFor

NameFor returns the Job name bound to every field that distinguishes an active operation attempt. The status claim can persist this name before the controller creates the Job.

func NameForMigration

func NameForMigration(
	migration *operatorv1alpha1.PtahMigration,
	operation operatorv1alpha1.MigrationOperationStatus,
) (string, error)

NameForMigration returns the Job name bound to every field that distinguishes one migration operation attempt from another.

The claim persists this name before the Job exists, which is what lets a controller that restarted mid-dispatch tell the Job it created from one it has not created yet.

func OperationIDLabelValue

func OperationIDLabelValue(value string) string

OperationIDLabelValue returns the bounded label value placed on every Pod for one full operation ID. Controllers must still verify AnnotationOperationID after selecting by this collision-resistant hash.

func ReservedPodMetadataKey

func ReservedPodMetadataKey(key string) bool

ReservedPodMetadataKey reports whether key is one spec.execution.podMetadata may not declare. It is the CRD's rule written once more in Go, for the readers that judge a Job after the API server admitted the resource: the builder, and ValidateClaimedMetadata, by which the controller-write validator and the controller judge a dispatched Job without rebuilding it.

The reserved namespaces are the operator's own (ptah.run and every subdomain of it), and the ones Kubernetes keeps for its components (kubernetes.io and k8s.io, with their subdomains). The first holds the labels and annotations the builder writes; the second holds the Job controller's tracking labels, app.kubernetes.io, which every object the chart owns selects on, the LimitRanger annotation the Pod-intent webhook treats specially, and the annotations the API server still translates into a Pod's security context. controller-uid and job-name are the Job controller's legacy tracking labels, which carry no prefix.

func SchemaApplyActor added in v0.2.13

func SchemaApplyActor(schema *operatorv1alpha1.PtahSchema) (string, string)

SchemaApplyActor is the name and the origin a schema Apply records in ptah_schema_apply_log, chosen as MigrationActor chooses: the username admission stamped on the approval the run consumed, which status.plan copies when the approval is consumed, or the fixed name under apply: Always when no approval was. An empty name means none is known, and the Job then sets neither variable.

It reads status.plan at build time, unlike a migration, whose claim keeps its own copy. The builder refuses an Apply of anything but status.plan, and a plan that needs an approval without one, so every Job an Apply claim can build reads the same approval.

func ValidateClaimedMetadata

func ValidateClaimedMetadata(actual, claimed map[string]string) error

ValidateClaimedMetadata holds one of a Job's metadata maps to the claim without rebuilding the Job: every key the claim fixes carries the claim's value, and every other key is one spec.execution.podMetadata may declare, in number and in namespace. What those declared keys were when the Job was dispatched is not re-derived from the spec, which may have changed since; the caller pins them through the template digest the claim's admission snapshot recorded.

jobclaim.Match applies it for both the controller-write validator and the controller, so the controller never refuses to recognize a Job the validator would let it touch, nor the other way round.

Types

type Builder

type Builder struct {
	// ResultEndpoint selects durable delivery when installation wiring is ready.
	// Empty retains the legacy log path during development integration.
	ResultEndpoint string
	// ResultServerTrust supplies the current public CA bundle for a new Job.
	// When set, durable delivery uses the explicit receiver-audience Pod token.
	ResultServerTrust      func() []byte
	ExecutorImage          string
	RunnerImage            string
	PtahVersion            string
	ControllerImage        string
	ControllerRevision     string
	ControllerStateVersion int32
	// PlanSealPublicKey is this manager process's current public key. A Plan
	// Job's runner seals its plan payload to it; nothing else reads it. It
	// travels as an ordinary literal environment variable, so the Pod
	// admission snapshot that binds the rest of the Job template binds this
	// value too -- a tampered Job that carries a different key fails
	// admission the same way a tampered coordination digest does.
	PlanSealPublicKey planseal.PublicKey
}

Builder contains the manager's immutable execution configuration. Every image must be content-addressed so a resumed operation cannot silently run new code.

Two parts of it play different roles. PtahVersion, ExecutorImage, ControllerStateVersion and the runner protocol decide what a plan means when it runs, and a plan and its approval bind them. ControllerImage, ControllerRevision and RunnerImage identify the manager's own release: a Job and a plan record them, and nothing is invalidated when only they change.

func (Builder) Build

Build creates one immutable-intent Job. plan must be nil except for Apply, where it must be the committed current plan.

func (Builder) BuildMigration

BuildMigration creates the Job for one already-persisted migration claim.

It reads no Secret. Every credential reaches the Pod as a selector the kubelet projects, and the container holding the database URL holds no registry credentials: what it reads was written by the fetch container beside it.

func (Builder) ExecutionBinding

func (b Builder) ExecutionBinding() (
	controllerStateVersion int32,
	ptahVersion string,
	executorImage string,
	runnerProtocolVersion int32,
)

ExecutionBinding returns what this manager executes with: the components a plan fingerprint and an approval bind, and whose change starts a new execution epoch.

func (Builder) ManagerIdentity

func (b Builder) ManagerIdentity() (controllerImage, controllerRevision, runnerImage string)

ManagerIdentity returns the manager's own release: its image, its revision and the runner image built from the same source. Jobs and plans record it; nothing binds it.

func (Builder) NameFor

NameFor delegates to the package-level deterministic naming contract.

func (Builder) NameForMigration

func (b Builder) NameForMigration(
	migration *operatorv1alpha1.PtahMigration,
	operation operatorv1alpha1.MigrationOperationStatus,
) (string, error)

NameForMigration delegates to the package-level deterministic naming contract.

func (Builder) Validate

func (b Builder) Validate() error

Validate checks the immutable execution configuration before the manager starts accepting reconciliation work.

Jump to

Keyboard shortcuts

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