workload

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 31 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 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 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 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 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