Documentation
¶
Overview ¶
Package diagnose groups an install's findings by shared cause and ranks the groups, so the worst and widest problem comes first (design §5.2, §5.3).
Index ¶
- Constants
- func Quote(s string) string
- type Claimed
- type Class
- type Commands
- type Diagnosis
- type Family
- type Group
- type Index
- func (ix *Index) Find(fs []health.Finding, id string) (int, bool)
- func (ix *Index) Page(fs []health.Finding, install string, s Sort, limit int, cursor string, ...) (Page, error)
- func (ix *Index) PageGroups(install string, limit int, cursor string, match func(g int) bool) (Page, error)
- func (ix *Index) Text(fs []health.Finding) []Text
- type Input
- type Kubectl
- type NextStep
- type Page
- type Sort
- type SuggestedFix
- type Text
Constants ¶
const ( // FixGrantTitle names the grant's namespace. FixGrantTitle = "Create a ReferenceGrant in `%s`" FixGrantBasis = "Gateway API: a ref to another namespace needs a ReferenceGrant in that namespace." // FixGroupTitle names the group to use. FixGroupTitle = "Set the group to `%s`" // FixGroupBasis names the group and the kind. FixGroupBasis = "" /* 128-byte string literal not displayed */ // FixPortTitle names the port to use. FixPortTitle = "Set the port to `%d`" // FixPortBasis names the Service. FixPortBasis = "Service `%s` has exactly one port. This sets only group, kind, name, namespace and port; keep the other fields." )
Wording of the suggested fixes (design §7.7).
const ( SortRank = "rank" SortSince = "since" SortCode = "code" )
Finding list sort keys (design §13.1). Rank has no descending form.
const ( StepEnvoyReason = "See the reason in the controller log" StepProxyLog = "See the reject in the proxy log" StepProxyCounters = "Read the proxy's update counters" StepPanicTrace = "Read the panic's stack trace" StepStatusLog = "See status errors in the controller log" // StepPortForwardNote leads the counters step's note: it is the one command that opens a connection (§12). StepPortForwardNote = "This command opens a connection to the proxy's admin port." )
Wording of the next steps (design §8.5).
const SortGroups = "groups"
SortGroups is the sort of group pages: rank order, which has no descending form.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Class ¶
type Class int
Class is a ranking class of findings (design §5.3); a lower class ranks first.
type Commands ¶
type Commands interface {
// ControllerLog reads a controller Pod's log since a duration ago, filtered by each grep.
ControllerLog(pod objects.Ref, since time.Duration, grep ...string) string
// ProxyLog reads a proxy's log since a duration ago, filtered case-insensitively by grep.
ProxyLog(proxy objects.Ref, since time.Duration, grep string) string
// ProxyCounters port-forwards to a proxy's admin port and reads its update counters.
ProxyCounters(proxy objects.Ref) string
// PreviousLog reads the previous container's log of a Pod.
PreviousLog(pod objects.Ref, container string) string
}
Commands fills in the next-step commands (design §8.5). A method that returns "" hides its step, so a platform without kubectl overrides or hides them.
type Diagnosis ¶
type Diagnosis struct {
// Groups are in rank order.
Groups []Group
// Rank are the report's finding indexes in rank order.
Rank []int
// Index serves the findings list in each order (design §13.1).
Index *Index
}
Diagnosis is an install's findings grouped and ranked.
func Build ¶
Build sets each finding's Group, trying families in order (first claim wins, else "Other" on its resource), and ranks the groups; findings keep their order. It reads only rep's findings and in's Install, Owned, Views and IDs: the engine reuses a diagnosis on exactly those, so a family must not read Snapshot or Served (Steps may).
type Family ¶
type Family interface {
// Name identifies the family; it is part of its groups' IDs.
Name() string
// Claim returns the cause of f in this family, or ok false.
Claim(f health.Finding, in Input) (cause *objects.Ref, causeKey []string, ok bool)
// Affected returns, index-aligned with gs, each group's affected objects; it runs once
// per Build with the family's groups (valid only during the call), Members indexing fs.
Affected(gs []Claimed, fs []health.Finding, in Input) [][]objects.Ref
}
Family is one kind of shared cause, a row of the design §5.2 table. Upstream families claim a finding's own resource as its cause; the API still checks a title's member.
type Group ¶
type Group struct {
// ID is health.GroupID of the family, cause and cause key.
ID, Family string
// Cause is the group subject; nil for an install-wide cause.
Cause *objects.Ref
// Members are indexes into the report's findings, in report order.
Members []int
// Severity is the worst member's.
Severity health.Severity
// Class is the lowest class of any member.
Class Class
Affected []objects.Ref
// Since is the oldest member's since; nil when no member has one.
Since *time.Time
// Ranked is false for a group of KGWUI-008 findings, which sorts last
// and is left out of the diagnostics groups.
Ranked bool
}
Group is one cause with the findings it explains.
type Index ¶
type Index struct {
// contains filtered or unexported fields
}
Index holds an install's findings in each list order (design §13.1), as indexes into the report's findings. Build makes one per model; it is read-only but for the orders other than rank and the search text, each built on first use.
func NewIndex ¶
NewIndex returns the index of fs grouped into groups, whose rank order is rank, as Build makes them. Since and code orders, either direction, break ties by rank; a nil since sorts last.
func (*Index) Page ¶
func (ix *Index) Page(fs []health.Finding, install string, s Sort, limit int, cursor string, match func(i int) bool) (Page, error)
Page returns up to limit findings of fs that match, in s's order, after or before cursor. A cursor opens only for the install it was minted for. A cursor resumes at its anchor's ordering tuple, so a vanished anchor skips nothing. Bad sorts are explore.ErrBadQuery, bad cursors explore.ErrBadCursor (design §14 rules 17, 18).
func (*Index) PageGroups ¶
func (ix *Index) PageGroups(install string, limit int, cursor string, match func(g int) bool) (Page, error)
PageGroups returns up to limit groups that match, as indexes into the diagnosis groups in rank order, after or before cursor. Cursors are sealed as findings cursors are, under their own sort, so neither list opens the other's.
type Input ¶
type Input struct {
Install install.Resolved
Owned *install.Owned
Snapshot *cache.Snapshot
Served []kinds.Served
Views objects.Decoder
// IDs, if set, memoises group IDs across recomputes.
IDs *health.IDs
// Readable, if set, says which objects the viewer may read: Build rejects
// a claim whose cause it denies and drops the affected objects it denies.
// Nil admits every object.
Readable func(objects.Ref) bool
}
Input is what a Family may look at to find a cause and its affected objects.
type Kubectl ¶
type Kubectl struct{}
Kubectl is the upstream Commands: the kubectl commands of design §8.5, every value passed through Quote.
func (Kubectl) ControllerLog ¶
ControllerLog implements Commands.
func (Kubectl) PreviousLog ¶
PreviousLog implements Commands.
func (Kubectl) ProxyCounters ¶
ProxyCounters implements Commands.
type NextStep ¶
NextStep is one command a user can run to learn more (design §13.3). Needs names the permissions it requires; Refs are the objects its command names.
type Page ¶
Page is one page of findings or groups: indexes into the report's findings, or the diagnosis groups. Total counts every item that matches, not only this page.
type SuggestedFix ¶
type SuggestedFix struct {
Title string
Target objects.Ref
Create bool
Path string
YAML string
Basis string
Names []objects.Ref
}
SuggestedFix is the one change a finding's evidence leaves (design §7.7). Create marks a new Target; otherwise YAML is the fragment at Path of Target. Names are every object the fix names: a caller who may not view one gets no fix.
func Fix ¶
func Fix(f *health.Finding) *SuggestedFix
Fix returns f's suggested fix from its evidence alone, or nil. Only an attributed KGWUI-013 or 014 has one: the corrected group when discovery left one group with the kind, else for 014 the ReferenceGrant the spec requires, unless the ref's group has an unknown served state.