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 Clean(text string) string
- func Duration(d time.Duration) string
- func FieldWriter(text *strings.Builder, indent string, width int) func(name, value 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 WriteListHeading[T any](text *strings.Builder, title, resource, namespace string, ...) bool
- func WriteTable(text *strings.Builder, indent string, conditions []Condition, generation int64)
- type Approval
- type Condition
- type Decisions
- type Unreadable
Constants ¶
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 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 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 WriteListHeading ¶
func WriteListHeading[T any]( text *strings.Builder, title, resource, namespace 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 a reader passes to `kubectl get` to see them all, and namespace is where they live. That command lists every one in the namespace, whichever resource it names, and the line says so.
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.