Documentation
¶
Overview ¶
Package statusview holds what `kubectl ptah schema` and `kubectl ptah migration` print the same way: the conditions the operator published, the ones a reader reads first, the decisions people made about a resource, and a list the reader was not allowed to read.
Nothing here decides anything about a resource. Every value comes from a field the operator or admission wrote, and the only judgments made are which of those fields a reader sees first.
Index ¶
- Constants
- Variables
- func After(at *metav1.Time) string
- func Claimed(operationType string, attempt int32, startedAt metav1.Time) string
- func Clean(text string) string
- func Duration(d time.Duration) string
- func FieldWriter(text *strings.Builder, indent string, width int) func(name, value string)
- func JobLead(name string, uid types.UID, dispatchStarted, marksDispatch bool) string
- func Label(name string) string
- func ReadRequest(requested, answered string) string
- func ReadRequested(requested, answered string) string
- func StatusFor(observed, generation int64) string
- func Summary(condition Condition) string
- func Time(instant metav1.Time) string
- func WriteApproval(text *strings.Builder, approval Approval, none string)
- func WriteDecisionConditions(text *strings.Builder, conditions []Condition, none string)
- func WriteEveryHeading[T any](text *strings.Builder, title, resource string, decisions *Decisions[T], ...) bool
- func WriteFields(text *strings.Builder, indent string, record any)
- func WriteListHeading[T any](text *strings.Builder, title, resource, every string, decisions *Decisions[T], ...) bool
- func WriteRecord(text *strings.Builder, label, summary, lead string, record any)
- func WriteScalars(text *strings.Builder, indent string, record any)
- func WriteStatusScalars(text *strings.Builder, summary string, status any, extra ...string)
- func WriteTable(text *strings.Builder, indent string, conditions []Condition, generation int64)
- func WriteWrapped(text *strings.Builder, indent string, width int, paragraph string)
- type Approval
- type Condition
- type Decisions
- type Unreadable
Constants ¶
const DetailsHeading = "\nDetails, every status field this plugin's API version knows:\n"
DetailsHeading opens the part of a view --details adds, after everything the view prints without it. The status is decoded into the API types this plugin was built with, so a field a newer operator added is not among them.
const MaxDecisions = 5
MaxDecisions bounds how many approvals or acknowledgments one view prints. A resource collects one for every plan somebody approved, and a terminal is for the ones that explain where it stands now: the newest.
const TimeLayout = "2006-01-02T15:04:05Z"
TimeLayout is how every instant is printed: UTC, to the second.
Variables ¶
var LabelWidth = leadingLabelWidth()
LabelWidth is the column the schema and migration views pad every "Label:" to, so that every value starts in the same column. A condition read first is labeled by its type, and the longest of those types is longer than any label the views print of their own.
Functions ¶
func Claimed ¶ added in v0.2.11
Claimed is the summary of an operation claim: its type, its attempt, and when it was claimed, where the claim records that.
func Clean ¶
Clean makes free text safe to print on one terminal line.
A message, a reason or a user name reaches the screen from whoever wrote it: the operator, Ptah's report, an identity provider. A line break would split one row of a table into two that read as separate rows, and a control sequence or a bidirectional override can rewrite what the terminal shows. Line breaks and tabs become spaces; every other control character and every bidirectional control is printed as its escape, so a reader sees that it was there. Format characters -- zero-width spaces and joiners, a byte order mark, a soft hyphen -- are escaped too: they print as nothing, so a name that holds one reads exactly like a name that does not.
func Duration ¶
Duration prints a length of time the way the plugin's help writes one: 5m rather than 5m0s, 1h rather than 1h0m0s, and 90s as 1m30s.
func FieldWriter ¶
FieldWriter returns a function that writes "Label: value" lines, the label padded to width after indent, and skips a field with no value.
func JobLead ¶ added in v0.2.11
JobLead says what an operation claim knows about its Job. The claim names the Job before it creates it, so a name alone is a reservation; the UID, recorded once the Job exists, is what confirms which Job it is.
marksDispatch says the claim records dispatchStarted before its one create, as every claim that holds the database realm does. Only such a claim is known not to have created a Job it has no mark for. A claim that does not mark can have created its Job and then failed the read that confirms it, or stopped between the create and the write that records the UID; the next pass adopts that Job by name.
func Label ¶ added in v0.2.11
Label turns an API field name into the words a reader sees: jobUID is "Job UID", applyPodUIDs "Apply pod UIDs", dispatchNotAfter "Dispatch not after".
func ReadRequest ¶ added in v0.2.11
ReadRequest says whether the read a person asked for with the read-request annotation has been answered: requested is the annotation as the resource holds it now, answered is status.lastReadRequest. The status records an answer as operatorv1alpha1.ReadRequestToken of the value, which is a digest for a value longer than MaxReadRequestLength, so the annotation is compared through the same token.
func ReadRequested ¶ added in v0.2.11
ReadRequested is the line that says whether the read a person asked for has been answered, or nothing where none was ever asked for.
func Summary ¶
Summary is one condition on one line: its status, its reason and its message, cleaned for a terminal.
func WriteApproval ¶
WriteApproval writes one approval: who approved which plan when, which of the resource's plans that is, and every condition the controller wrote on it. none is what to say when there is no condition, which differs by family: the controller answers a schema approval as soon as it reads it, and writes nothing on a migration approval until its plan is dispatched or a read withdraws it.
func WriteDecisionConditions ¶
WriteDecisionConditions writes the conditions of one decision, or none when it has no condition.
func WriteEveryHeading ¶ added in v0.2.11
func WriteEveryHeading[T any]( text *strings.Builder, title, resource string, decisions *Decisions[T], unreadable *Unreadable, ) bool
WriteEveryHeading writes the line that opens a list of every decision that names a resource, oldest first, the way WriteListHeading opens the newest few. It reports whether entries follow.
func WriteFields ¶ added in v0.2.11
WriteFields writes every field a status record holds, one line each, under indent, labeled with its API name in words. A details view prints a record whole this way, so a field the API gains is printed without this code or its caller changing, and the label is the name the API reference lists it under.
A field the record leaves at its zero value is not printed when its JSON tag says omitempty, because the stored object does not hold it. A nested record is a label line with its fields indented under it, and a list of records is one indented block per item, each opened by "-". Every value passes through Clean.
func WriteListHeading ¶
func WriteListHeading[T any]( text *strings.Builder, title, resource, every string, decisions *Decisions[T], unreadable *Unreadable, ) bool
WriteListHeading writes the line that opens a list of decisions: how many follow, that there are none, or why they could not be read. It reports whether entries follow.
title names the list, resource is the plural whose list the API server was asked for, and every is the command that prints every one of them that names this resource: the line names it when the list was cut. It names no `kubectl get`, which lists every decision in the namespace, whichever resource it names, and leaves the reader to tell them apart.
func WriteRecord ¶ added in v0.2.11
WriteRecord writes one status record a details view prints: a "Label:" line with what the record is in a few words, a sentence that says what it means where the record alone does not, and then every field it holds. A record with no summary and no field set is not written at all.
func WriteScalars ¶ added in v0.2.11
WriteScalars writes the fields of record that are printed on one line, the way WriteFields does, and leaves out its nested records, lists and maps, which a details view prints as records of their own.
func WriteStatusScalars ¶ added in v0.2.11
WriteStatusScalars writes the status's own one-line fields as the first record of a details view: its generation, phase and times, with what the status was written for as the summary and extra lines after them.
func WriteTable ¶
WriteTable writes conditions as an aligned table under a heading, one row each, the message last so a long one runs off the end of its own row rather than pushing the others apart.
generation is the resource's metadata.generation. A condition written for another generation says so after its message, because it may describe a spec that has since changed. Zero turns the note off.
Types ¶
type Approval ¶
type Approval struct {
Name string `json:"name"`
CreatedAt metav1.Time `json:"createdAt"`
// PlanRef and PlanFingerprint are the exact plan the approval names.
PlanRef operatorv1alpha1.ImmutableObjectReference `json:"planRef"`
PlanFingerprint string `json:"planFingerprint"`
// CurrentPlan says the plan it names is the resource's current plan, by
// name, UID and fingerprint. An approval of any other plan cannot
// authorize anything, whatever its own conditions say.
CurrentPlan bool `json:"currentPlan"`
// AppliedPlan says the plan it names is the one the resource's last
// confirmed apply ran, by name, UID and fingerprint: the approval that
// apply consumed, once the plan is no longer current. A migration records
// no applied plan, so it is false for a migration approval.
AppliedPlan bool `json:"appliedPlan"`
// Approver and ApprovedAt are what admission stamped from the
// authenticated request.
Approver operatorv1alpha1.ApprovalIdentity `json:"approver"`
ApprovedAt metav1.Time `json:"approvedAt"`
Conditions []Condition `json:"conditions,omitempty"`
}
Approval is one approval of either family: the plan it names, the identity admission stamped on it, and what the controller answered.
type Condition ¶
type Condition struct {
Type string `json:"type"`
Status string `json:"status"`
Reason string `json:"reason,omitempty"`
Message string `json:"message,omitempty"`
// ObservedGeneration is the spec generation the condition was written for.
ObservedGeneration int64 `json:"observedGeneration,omitempty"`
// LastTransitionTime is when the status last changed, not when the
// condition was last written: a message rewritten under the same status
// keeps the older time.
LastTransitionTime *metav1.Time `json:"lastTransitionTime,omitempty"`
}
Condition is one published condition, with the two fields that say when and for which spec it was written.
func FromConditions ¶
FromConditions copies the conditions in the order the status holds them.
func Leading ¶
Leading is what a reader reads before the full table: Ready, whatever its status, because the API documents its reason as the one to read first, and then every condition that is True and holds the resource.
It is a selection and not a verdict. Nothing is derived from a combination of conditions, and a condition not chosen here is still in the table.
type Decisions ¶
type Decisions[T any] struct { // Total is how many name the resource. Items holds at most MaxDecisions // of them, so a Total above len(Items) is a list that was cut. Total int `json:"total"` Items []T `json:"items"` }
Decisions is the newest decisions that name one resource, newest first.
type Unreadable ¶
type Unreadable struct {
// Forbidden says the API server refused the list for want of permission.
// The plugin needs only get on the resource it reads, so a reader without
// list on the decisions is an expected reader, not a failure.
Forbidden bool `json:"forbidden"`
// Message is the error the list returned: the API server's answer, or the
// client's when no answer came.
Message string `json:"message"`
}
Unreadable is why a list the view asked for could not be read. The view is still printed: what the resource itself says does not depend on it.
func UnreadableFrom ¶
func UnreadableFrom(err error) *Unreadable
UnreadableFrom records why a list failed.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package statusviewtest fills a status record for the tests that hold a details view to printing all of it.
|
Package statusviewtest fills a status record for the tests that hold a details view to printing all of it. |