Documentation
¶
Overview ¶
Package planstore publishes immutable executable plans without placing SQL in a custom-resource status or controller log.
A plan's bytes live in PtahSchemaPlanChunk objects the plan owns, so reading a plan takes one RBAC rule on that kind. An Apply Pod holds no Kubernetes credential and the kubelet projects no custom resource into a volume, so the Apply reads the same bytes through immutable ConfigMaps of the same names, which Project writes from verified chunks just before the Apply Job is created. The ConfigMaps exist only for plans that reached an Apply.
Index ¶
- Constants
- Variables
- func Binding(schemaUID types.UID, spec operatorv1alpha1.PtahSchemaPlanSpec) fingerprint.PlanBinding
- func DesiredChunk(plan *operatorv1alpha1.PtahSchemaPlan, ref operatorv1alpha1.PlanChunkReference, ...) *operatorv1alpha1.PtahSchemaPlanChunk
- func DesiredProjection(plan *operatorv1alpha1.PtahSchemaPlan, ref operatorv1alpha1.PlanChunkReference, ...) *corev1.ConfigMap
- func Name(planFingerprint string) (string, error)
- func Prepare(schema *operatorv1alpha1.PtahSchema, spec operatorv1alpha1.PtahSchemaPlanSpec, ...) (*operatorv1alpha1.PtahSchemaPlan, [][]byte, error)
- func VerifyProjection(plan *operatorv1alpha1.PtahSchemaPlan, ref operatorv1alpha1.PlanChunkReference, ...) error
- func VolumeSources(plan *operatorv1alpha1.PtahSchemaPlan) ([]corev1.VolumeProjection, error)
- type Store
- func (s Store) Load(ctx context.Context, plan *operatorv1alpha1.PtahSchemaPlan) ([]byte, error)
- func (s Store) Project(ctx context.Context, plan *operatorv1alpha1.PtahSchemaPlan, content []byte) error
- func (s Store) Publish(ctx context.Context, desired *operatorv1alpha1.PtahSchemaPlan, chunks [][]byte) (*operatorv1alpha1.PtahSchemaPlan, error)
Constants ¶
const ( // ChunkBytes leaves headroom below the Kubernetes object-size limit. ChunkBytes = plancontract.ChunkBytes // MaxChunks bounds projected-volume fan-out and API-server load. MaxChunks = plancontract.MaxChunks MaxPlanBytes = int(plancontract.MaxExecutableBytes) // ProjectionDataKey is the one key an Apply's projection ConfigMap holds // its chunk under. ProjectionDataKey = "chunk" LabelPlan = "operator.ptah.run/plan" LabelSchema = "operator.ptah.run/schema" )
Variables ¶
var ErrProjectionConflict = errors.New("plan projection conflicts with an existing ConfigMap")
ErrProjectionConflict reports a ConfigMap under a projection name that is not the projection this plan needs. A retry cannot fix it: the name is derived from the plan, so only another plan, with another name, can.
var ErrVerification = errors.New("stored plan failed verification")
ErrVerification marks a stored plan that Load refused: a manifest, ordering, UID, size or digest that does not hold, or a committed chunk that is gone. The refusal keeps its own message; this only lets a caller tell it from an error the API returned.
Functions ¶
func Binding ¶
func Binding(schemaUID types.UID, spec operatorv1alpha1.PtahSchemaPlanSpec) fingerprint.PlanBinding
Binding returns the approval identity a plan spec stands for, read from the spec as published. The manager computes a plan's fingerprint from it before publishing, and the controller-write webhook recomputes it before admitting the plan, so the two cannot disagree about what a field means.
func DesiredChunk ¶
func DesiredChunk( plan *operatorv1alpha1.PtahSchemaPlan, ref operatorv1alpha1.PlanChunkReference, content []byte, ) *operatorv1alpha1.PtahSchemaPlanChunk
DesiredChunk is the exact PtahSchemaPlanChunk the store writes for one chunk of a persisted plan.
func DesiredProjection ¶
func DesiredProjection( plan *operatorv1alpha1.PtahSchemaPlan, ref operatorv1alpha1.PlanChunkReference, content []byte, ) *corev1.ConfigMap
DesiredProjection is the exact ConfigMap Project writes for one chunk of a persisted plan.
func Name ¶
Name is the plan's deterministic object name. Two publications of the same plan are the same object, so a controller that restarted mid-publication cannot leave a second copy of one decision.
func Prepare ¶
func Prepare( schema *operatorv1alpha1.PtahSchema, spec operatorv1alpha1.PtahSchemaPlanSpec, content []byte, ) (*operatorv1alpha1.PtahSchemaPlan, [][]byte, error)
Prepare creates the deterministic manifest and chunks for exact plan bytes. The caller supplies every plan binding except the content-derived fields.
func VerifyProjection ¶
func VerifyProjection( plan *operatorv1alpha1.PtahSchemaPlan, ref operatorv1alpha1.PlanChunkReference, configMap *corev1.ConfigMap, ) error
VerifyProjection holds an Apply's projection ConfigMap to the chunk it carries: immutable, named, labeled and owned the way Project writes it, and holding exactly the bytes the plan's manifest records for that chunk.
func VolumeSources ¶
func VolumeSources(plan *operatorv1alpha1.PtahSchemaPlan) ([]corev1.VolumeProjection, error)
VolumeSources returns a deterministic read-only projection for an apply Job. It names the ConfigMaps Project writes.
Types ¶
type Store ¶
Store uses direct API reads through Reader and mutating calls through Client. The distinction lets controllers bypass a stale cache before apply.
func (Store) Load ¶
func (s Store) Load(ctx context.Context, plan *operatorv1alpha1.PtahSchemaPlan) ([]byte, error)
Load reconstructs a Ready plan after checking manifest, object UIDs, sizes, and every digest through direct API reads.
A refusal on any of those checks carries ErrVerification, and so does a committed chunk that is no longer there. An error the API returned for a read, such as Forbidden, is returned as it is and does not.
func (Store) Project ¶
func (s Store) Project(ctx context.Context, plan *operatorv1alpha1.PtahSchemaPlan, content []byte) error
Project writes the immutable ConfigMaps an Apply Pod mounts the plan through, one per chunk and under the chunk's own name, from content that Load returned for the same plan. It resumes: a projection an earlier attempt wrote is read back and must match byte for byte.
The ConfigMaps are owned by the plan and deleted with it. The Pod's runner checks the whole document against the plan's content digest before it runs anything, so a projection is a transport rather than a second store: what it carries is decided by the chunks and the digest, not by the ConfigMap.
An error wrapping ErrProjectionConflict means a ConfigMap under one of the names is not this plan's projection. Any other error is the API's and may clear on a retry.
func (Store) Publish ¶
func (s Store) Publish( ctx context.Context, desired *operatorv1alpha1.PtahSchemaPlan, chunks [][]byte, ) (*operatorv1alpha1.PtahSchemaPlan, error)
Publish resumes or completes the non-transactional Plan -> chunks -> Ready commit sequence. Existing objects must match byte-for-byte.