Documentation
¶
Overview ¶
Package approve turns a person's review of a stored plan into the approval the operator acts on.
An approval names three things a person should never have to copy by hand: the resource with its UID, the plan with its UID, and the plan's fingerprint. This package reads them from the cluster, shows the plan they identify, and creates the approval only while they still identify the plan that was shown. It decides nothing the operator does not: admission stamps the approver and checks the binding, Kubernetes RBAC decides who may create the object, and the operator decides when the approved plan runs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("no such resource")
ErrNotFound is returned when the named resource is not there.
var ErrNothingToApprove = errors.New("no plan to approve")
ErrNothingToApprove is returned when the resource has no current plan.
Functions ¶
func Manifest ¶
func Manifest(review Review, name string) *unstructured.Unstructured
Manifest is the approval of the reviewed plan as a repository holds it: the API version, the kind, the name and the namespace, and the three references that are the decision. Nothing else is written. Admission stamps the approver and the time from whoever creates the object, and an empty value written here would be sent back by a later apply as an edit of an approval, which is immutable.
It is named as Submit names what it sends, by approvalMeta. Without a name the API server generates one each time it is created, so one file can approve a plan again after an uncertain Apply consumed the first approval. kubectl apply refuses a generated name; a workflow that applies its files passes one.
func RenderReview ¶
RenderReview writes what a person is asked to approve: the identities the approval will carry, then the plan they identify. A schema plan is its verified SQL with each statement's severity and reason. A migration plan is its versions and checksums and the source its SQL is read from; the SQL is not in the plan, and this says so rather than leaving a reader to think it was shown.
Types ¶
type Family ¶
type Family string
Family is the kind of resource an approval is for. The two families approve different things: a schema plan is SQL, a migration plan is a sequence of versions whose SQL lives in the artifact.
func ParseTarget ¶
ParseTarget reads a target written as family/name, the way kubectl names a resource: schema/storefront or migration/shipments, or the kind's plural or short name, as in ptahschema/storefront. It reads the family the way suspend, resume, refresh and wait do (operate.ParseFamily). The family is required: a schema and a migration may share a name, and an approval for the wrong one is an approval nobody reviewed.
func (Family) ApprovalKind ¶
ApprovalKind is the kind of the approval the family takes.
type Options ¶
type Options struct {
// Name is the approval's name. Empty asks the API server to generate one
// from the resource's name.
Name string
// ServerDryRun asks admission to check the approval without storing it.
ServerDryRun bool
// Await is how long Submit waits for the operator to come back to the
// approval gate when it finds it reading the resource again
// (Review.Reading). Zero answers such a read at once, as Closed.
Await time.Duration
// CallTimeout bounds each request Submit sends, and zero leaves them to
// ctx. A wait spans many requests, so it does not bound the wait.
CallTimeout time.Duration
// Waiting, when set, is called once when Submit begins to wait, with
// what the operator is doing.
Waiting func(why string)
}
Options shape the approval Submit sends.
type Outcome ¶
type Outcome string
Outcome is what became of an approval this package was asked to submit.
const ( // Admitted means the API server stored the approval. Admission stamped // the approver; the operator decides when the plan runs. Admitted Outcome = "admitted" // Previewed means admission checked the approval in a server-side dry // run and nothing was stored. Previewed Outcome = "previewed" // Changed means the plan the person reviewed is no longer the current // plan, or the resource is another one now. Nothing was sent. Changed Outcome = "changed" // Closed means the operator would not admit an approval now. Nothing was // sent. Closed Outcome = "closed" // Forbidden means Kubernetes RBAC does not let this identity create the // approval. Forbidden Outcome = "forbidden" // Refused means the API server answered the create with a refusal that // is not RBAC's: admission, the API schema, a name already taken, a // credential it did not accept, or a request it was too busy to take. // Nothing was stored. Refused Outcome = "refused" // Unknown means the request was sent and no answer said whether the // approval was stored. Unknown Outcome = "unknown" // Failed means the cluster could not be read before anything was sent. Failed Outcome = "failed" )
type Result ¶
type Result struct {
Outcome Outcome
// Message is the API server's or admission's words, or this package's
// account of why nothing was sent, with what to do next.
Message string
// Approval is the object as the API server answered with it, carrying the
// identity admission stamped: nil unless admitted or previewed.
Approval client.Object
}
Result is the outcome of one submission and what it stored, if anything.
func Submit ¶
Submit creates the approval of the reviewed plan, if the cluster still names that plan and the operator would admit an approval now.
It reads the resource again first, by identity: a stored plan is immutable, so the same resource UID, plan UID and fingerprint are the plan that was verified and shown. A plan replaced while the person read the old one, a resource deleted and created again, or a spec changed since are all answered without sending anything: an approval is a decision about the plan that was shown, under the spec it was shown under, and no retry may carry it over to another one.
A resource the operator is reading again closes the gate only until that read ends, and admission refuses an approval meanwhile. With opts.Await Submit waits for the read to end, reading the resource at pollInterval and holding every read to the same identity, and sends the approval once the gate is open with the reviewed plan. A read that ends anywhere else is answered as it would have been at once.
type Review ¶
type Review struct {
Family Family
Namespace string
Name string
// ResourceUID is the schema's or migration's UID: a resource deleted and
// created again under the same name is another resource.
ResourceUID types.UID
// Spec is the resource's spec as the API server sent it, as canonical JSON
// without spec.suspend (desiredspec.Of): the fields this plugin's types
// know and those a newer API added, as admission compares them. A spec
// changed since, other than by a suspend or a resume, is not the one the
// person reviewed the plan under. Admission does not compare it, so this
// is the only check against a spec the person never saw.
Spec string
PlanName string
PlanUID types.UID
Fingerprint string
ContractVersion int32
// SchemaPlan is the verified plan of a schema: its statements with their
// severity and reason, read through the operator's own plan store.
SchemaPlan *planread.Plan
// MigrationPlan is the stored plan of a migration: versions, checksums
// and order. It holds no SQL, and nothing here claims to have shown any.
MigrationPlan *operatorv1alpha1.PtahMigrationPlan
// Open says whether the operator would admit an approval now. Closed
// carries why not, in words a person acts on.
Open bool
Closed string
// Reading says the operator is reading the resource again, which it does
// at its interval while a plan waits for a person, and on request. The
// gate is closed until that read ends and reopens by itself; Submit waits
// for it when asked to.
Reading bool
// Missing says the plan the status names is not stored: the object under
// its name is another plan, or another resource's. Nothing can approve it,
// in any mode, and Closed says why. The review then carries the identity
// the status names and no fingerprint, so nothing built from it binds the
// object that took the name.
Missing bool
}
Review is the plan a person is asked to approve and the identities an approval of it carries. It is read once and shown; Submit creates the approval only while the cluster still names the same plan.