diagnose

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

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

View Source
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).

View Source
const (
	SortRank  = "rank"
	SortSince = "since"
	SortCode  = "code"
)

Finding list sort keys (design §13.1). Rank has no descending form.

View Source
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"
	StepShareNote     = "Log lines and admin output can contain configuration values, including secrets. Share them with care."
	// 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).

View Source
const SortGroups = "groups"

SortGroups is the sort of group pages: rank order, which has no descending form.

Variables

This section is empty.

Functions

func Quote

func Quote(s string) string

Quote returns s as one POSIX shell word: unchanged when every byte is in [A-Za-z0-9_./:=-] and s does not start with "-", else in single quotes with each quote escaped.

Types

type Claimed

type Claimed struct {
	Cause   *objects.Ref
	Key     []string
	Members []int
}

Claimed is one group of a family: its cause, cause key and member indexes.

type Class

type Class int

Class is a ranking class of findings (design §5.3); a lower class ranks first.

const (
	ClassDataPlane Class = 1 // data plane
	ClassProcesses Class = 2 // controller and proxy processes
	ClassTraffic   Class = 3 // traffic-affecting configuration
	ClassHygiene   Class = 4 // consistency and install hygiene
)

Classes, in rank order.

func ClassOf

func ClassOf(f health.Finding) Class

ClassOf returns f's class (design §5.3): KGWUI-003 is traffic once a warning (after grace), else hygiene; an unlisted code is hygiene.

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

func Build(rep *health.Report, in Input, families []Family) *Diagnosis

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.

func Families

func Families() []Family

Families returns the families in design §5.2 table order; "Other" is last.

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

func NewIndex(fs []health.Finding, groups []Group, rank []int) *Index

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) Find

func (ix *Index) Find(fs []health.Finding, id string) (int, bool)

Find returns the index in fs of the finding with id.

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.

func (*Index) Text

func (ix *Index) Text(fs []health.Finding) []Text

Text returns the search text of fs, the findings ix was built from, by finding index.

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
}

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

func (Kubectl) ControllerLog(pod objects.Ref, since time.Duration, grep ...string) string

ControllerLog implements Commands.

func (Kubectl) PreviousLog

func (Kubectl) PreviousLog(pod objects.Ref, container string) string

PreviousLog implements Commands.

func (Kubectl) ProxyCounters

func (Kubectl) ProxyCounters(proxy objects.Ref) string

ProxyCounters implements Commands.

func (Kubectl) ProxyLog

func (Kubectl) ProxyLog(proxy objects.Ref, since time.Duration, grep string) string

ProxyLog implements Commands.

type NextStep

type NextStep struct {
	Title, Command string
	Needs          []string
	Note           string
	Refs           []objects.Ref
}

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.

func Steps

func Steps(g Group, findings []health.Finding, in Input, c Commands, can func(objects.Ref) bool) []NextStep

Steps returns g's next steps, naming only objects can allows (nil allows all; design §14 rule 15). A step whose command c returns "" is left out.

type Page

type Page struct {
	Items      []int
	Total      int
	Next, Prev string
}

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 Sort

type Sort struct {
	Key  string
	Desc bool
}

Sort is a list order: a sort key, descending when Desc.

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.

type Text

type Text struct {
	Identity, Message, Detail string
}

Text is a finding's search fields, lower-cased. Identity is the resource's namespace/name, empty without one; callers decide which fields a caller may match.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL