controller

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 59 Imported by: 0

Documentation

Overview

Package controller reconciles credential-isolated desired schema state.

Index

Constants

View Source
const RealmDigestIndex = "spec.target.realmDigest"

RealmDigestIndex names both families by the coordination realm their spec claims, so a census reads the members of one realm rather than every resource in the cluster.

Without it each pass allocated and scanned both complete lists, and an idle sweep over N resources examined about N squared entries. Sharing one informer cache makes that cheap per entry and does not make it constant.

Variables

This section is empty.

Functions

func PolicyFingerprint

func PolicyFingerprint(schema *operatorv1alpha1.PtahSchema) (string, error)

PolicyFingerprint is the policy binding a plan records, exported for the end-to-end fixture that stands up a plan this controller must accept. A second spelling of it there would be a fixture that agrees with nothing.

func RegisterRealmIndexes

func RegisterRealmIndexes(ctx context.Context, indexer client.FieldIndexer) error

RegisterRealmIndexes indexes both kinds for the realm census.

Both are registered together, and from the manager rather than from either controller's own setup, because the census reads both kinds whichever controller asks for it. Registering each from its own controller would make a manager that runs one of them return "no index with name ..." for the other, and controller-runtime refuses a second registration of the same field, so they cannot each register both.

Types

type ClientsetPodLogs

type ClientsetPodLogs struct {
	Client kubernetes.Interface
}

ClientsetPodLogs reads exact container logs through the Kubernetes API.

func (ClientsetPodLogs) Read

func (r ClientsetPodLogs) Read(ctx context.Context, namespace, podName, containerName string) ([]byte, error)

type JobBuilder

type JobBuilder interface {
	NameFor(schema *operatorv1alpha1.PtahSchema, operation operatorv1alpha1.ActiveOperationStatus) (string, error)
	Build(schema *operatorv1alpha1.PtahSchema, operation operatorv1alpha1.ActiveOperationStatus, plan *operatorv1alpha1.PtahSchemaPlan) (*batchv1.Job, error)
	NameForMigration(migration *operatorv1alpha1.PtahMigration, operation operatorv1alpha1.MigrationOperationStatus) (string, error)
	BuildMigration(
		migration *operatorv1alpha1.PtahMigration,
		operation operatorv1alpha1.MigrationOperationStatus,
		plan *operatorv1alpha1.PtahMigrationPlan,
	) (*batchv1.Job, error)
	// ExecutionBinding is what this manager executes with: the components a
	// plan and an approval bind, and whose change starts a new epoch.
	ExecutionBinding() (
		controllerStateVersion int32,
		ptahVersion string,
		executorImage string,
		runnerProtocolVersion int32,
	)
	// ManagerIdentity is the manager's own release and the runner image built
	// beside it. What the manager publishes records it; nothing binds it.
	ManagerIdentity() (controllerImage, controllerRevision, runnerImage string)
}

JobBuilder turns one already-persisted operation claim into a deterministic Job. It must never read Secret content.

type MigrationJobBuilder

type MigrationJobBuilder interface {
	NameForMigration(
		migration *operatorv1alpha1.PtahMigration,
		operation operatorv1alpha1.MigrationOperationStatus,
	) (string, error)
	BuildMigration(
		migration *operatorv1alpha1.PtahMigration,
		operation operatorv1alpha1.MigrationOperationStatus,
		plan *operatorv1alpha1.PtahMigrationPlan,
	) (*batchv1.Job, error)
	// ExecutionBinding is what this manager executes with: the components a
	// plan and an approval bind, and whose change starts a new epoch.
	ExecutionBinding() (
		controllerStateVersion int32,
		ptahVersion string,
		executorImage string,
		runnerProtocolVersion int32,
	)
	// ManagerIdentity is the manager's own release and the runner image built
	// beside it. What the manager publishes records it; nothing binds it.
	ManagerIdentity() (controllerImage, controllerRevision, runnerImage string)
}

MigrationJobBuilder turns one already-persisted migration claim into a deterministic Job. It must never read Secret content.

type MigrationReconciler

type MigrationReconciler struct {
	client.Client
	APIReader         client.Reader
	Scheme            *runtime.Scheme
	Recorder          record.EventRecorder
	Logs              PodLogReader
	Results           OperationResults
	ResultCredentials ResultCredentialIssuer

	// ResultReadTimeout bounds the pod/log read of one terminal operation.
	// Zero means defaultResultReadTimeout, which is what the manager runs.
	ResultReadTimeout time.Duration

	Jobs  MigrationJobBuilder
	Locks *targetlock.Locker
	// LockNamespace is one shared coordination namespace for every managed
	// resource, including resources that live in different namespaces: two
	// namespaces that address the same database must not run at the same time.
	LockNamespace    string
	Clock            func() time.Time
	Telemetry        telemetry.Observer
	AdmissionOptions podintent.Options
	// contains filtered or unexported fields
}

MigrationReconciler carries one PtahMigration through Resolve -> Verify -> History -> Apply, and reads the history back afterwards to confirm what the run did.

Only the Apply mutates a database, and only what an approved plan named. The three readings before it are what that plan is computed from, so the evidence and the decision stay separable: a plan is published from a reading the resource persisted, and an Apply executes a plan somebody or some policy authorized.

func (*MigrationReconciler) Reconcile

func (r *MigrationReconciler) Reconcile(ctx context.Context, request ctrl.Request) (result ctrl.Result, err error)

func (*MigrationReconciler) SetupWithManager

func (r *MigrationReconciler) SetupWithManager(manager ctrl.Manager) error

SetupWithManager registers the migration controller. Jobs are watched by owner so a terminal Job wakes its migration instead of waiting for the poll, an approval wakes the migration it names for the same reason, and the verification policy ConfigMap wakes every migration that names it.

Without the second watch an approval waited for the migration's next scheduled reading, up to spec.interval, before the controller so much as looked at it, while the schema controller acts on its approvals at once. The wake does not skip the evidence: a migration whose reading is due still refreshes the whole chain first, and one that is not due checks the approval against the plan, history, artifact and binding it was written for.

The third watch is how soon a replaced policy is noticed, and nothing more. It decides nothing: the plan and the undispatched claim are each re-checked against the live policy where they are acted on, so a wake that never arrives -- a missed event, a restarted manager, a cache that lagged -- delays the refusal to the next reading rather than losing it.

type OperationResults

type OperationResults interface {
	Poll(context.Context, resultconsumer.Request) (resultconsumer.Result, error)
}

OperationResults polls bounded background reads; it must never perform a blocking payload read in the reconcile worker. The manager supplies a Reader.

type PodLogReader

type PodLogReader interface {
	Read(ctx context.Context, namespace, podName, containerName string) ([]byte, error)
}

PodLogReader isolates the pod/log subresource from the reconciliation logic.

type ResultCredentialIssuer

type ResultCredentialIssuer interface {
	Ensure(context.Context, resultdelivery.Identity) (resultcredentials.Credential, error)
}

type SchemaReconciler

type SchemaReconciler struct {
	client.Client
	APIReader         client.Reader
	Scheme            *runtime.Scheme
	Recorder          record.EventRecorder
	Logs              PodLogReader
	Results           OperationResults
	ResultCredentials ResultCredentialIssuer

	// ResultReadTimeout bounds the pod/log read of one terminal operation.
	// Zero means defaultResultReadTimeout, which is what the manager runs.
	ResultReadTimeout time.Duration

	Jobs JobBuilder
	// SealKey is this manager process's key pair. The Plan Job builder is
	// given its public half; this reconciler opens the Plan payload sealed
	// to it. The private half is never persisted, so a process that
	// generated a different key pair before a restart cannot open a Plan
	// result it dispatched before that restart, and re-plans instead.
	SealKey planseal.KeyPair
	Plans   planstore.Store
	Locks   *targetlock.Locker
	// LockNamespace is one shared coordination namespace for every managed
	// PtahSchema, including schemas that live in different namespaces.
	LockNamespace string
	Clock         func() time.Time
	Telemetry     telemetry.Observer
	// AdmissionOptions must match cluster-wide built-in Pod admission settings.
	// The exact values are copied into each durable operation snapshot.
	AdmissionOptions podintent.Options
	// contains filtered or unexported fields
}

SchemaReconciler implements the Resolve -> Verify -> Observe -> Plan -> Approval -> Apply -> Observe convergence state machine.

func (*SchemaReconciler) Reconcile

func (r *SchemaReconciler) Reconcile(ctx context.Context, request ctrl.Request) (result ctrl.Result, err error)

func (*SchemaReconciler) SetupWithManager

func (r *SchemaReconciler) SetupWithManager(manager ctrl.Manager) error

Jump to

Keyboard shortcuts

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