Documentation
¶
Overview ¶
Package controller reconciles credential-isolated desired schema state.
Index ¶
- Constants
- func PolicyFingerprint(schema *operatorv1alpha1.PtahSchema) (string, error)
- func RegisterRealmIndexes(ctx context.Context, indexer client.FieldIndexer) error
- type ClientsetPodLogs
- type JobBuilder
- type MigrationJobBuilder
- type MigrationReconciler
- type OperationResults
- type PodLogReader
- type ResultCredentialIssuer
- type SchemaReconciler
Constants ¶
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.
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) 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) SetupWithManager ¶
func (r *SchemaReconciler) SetupWithManager(manager ctrl.Manager) error
Source Files
¶
- dispatch_state.go
- durable_results.go
- job_events.go
- lock_owner.go
- logs.go
- migration_apply.go
- migration_controller.go
- migration_dispatch.go
- migration_termination_summary.go
- migration_unresolved_run.go
- operation_type.go
- pod_admission.go
- realm.go
- result_arrival.go
- result_enrollment_hints.go
- result_issuance.go
- result_log_loss.go
- schema_binding_retirement.go
- schema_controller.go
- schema_dispatch.go