health

package
v0.8.2 Latest Latest
Warning

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

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

Documentation

Overview

Package health turns cluster state and controller signals into findings and a health state per install (design §5).

Index

Constants

View Source
const (
	// ListenerHostnameRule is HostnameConflict's: same port and the same hostname.
	ListenerHostnameRule = "listener port and hostname"
	// ListenerProtocolRule is ProtocolConflict's: same port and a different protocol.
	ListenerProtocolRule = "listener port and protocol"
)

Rules that find a conflict's other side, one per Conflicted reason (design §7.5, R94).

View Source
const (
	LogsRead    = "read"
	LogsNotRead = "not-read"
)

Whether an install's controller log was read (design §8.9). Not read is never "nothing found": the log events are then absent, not empty.

View Source
const (
	EvidenceFreshness        = own.EvidenceFreshness
	EvidenceRefs             = own.EvidenceRefs
	EvidenceRuleReplaced     = own.EvidenceRuleReplaced
	RefExplainKindNotServed  = own.RefExplainKindNotServed
	RefExplainServiceMissing = own.RefExplainServiceMissing
	RefExplainServicePort    = own.RefExplainServicePort
	RefExplainController     = own.RefExplainController
)

Kinds of the own-object evidence, and the explanations of KGWUI-013 and 014 (design §7.3).

View Source
const (
	CodeXDSRejected             = "KGWUI-001"
	CodeConditionFalse          = "KGWUI-002"
	CodeRouteUnattached         = "KGWUI-003"
	CodeNamespaceNotWatched     = "KGWUI-004"
	CodeControllerNotReady      = "KGWUI-005"
	CodeProxyNotReady           = "KGWUI-006"
	CodeScopeMismatch           = "KGWUI-007"
	CodeSignalUnavailable       = "KGWUI-008"
	CodeAmbiguousOwnership      = "KGWUI-009"
	CodeSelfManagedProxy        = "KGWUI-010"
	CodeDelegatedNotAttached    = "KGWUI-011"
	CodeComputedDisagrees       = "KGWUI-012"
	CodeRefUnresolved           = "KGWUI-013"
	CodeRefNotPermitted         = "KGWUI-014"
	CodeProcessRestarting       = "KGWUI-019"
	CodeProbeFailing            = "KGWUI-020"
	CodeRolloutStuck            = "KGWUI-021"
	CodeVersionSkew             = "KGWUI-022"
	CodeBackendNoReadyEndpoints = "KGWUI-023"
	CodeProxyConfigWarming      = "KGWUI-025"
	CodeProxyDisconnected       = "KGWUI-026"
)

Stable finding codes. Never reuse a code (design §5.1).

View Source
const (
	FreshnessNeverWritten = own.FreshnessNeverWritten
	FreshnessStale        = own.FreshnessStale
	FreshnessPending      = own.FreshnessPending
	FreshnessNoAncestor   = own.FreshnessNoAncestor
)

Freshness kinds of KGWUI-003 (design §10.1), in table order: an object that matches two takes the first.

View Source
const (
	// DelegatedNotAttachedMessage is KGWUI-011's message.
	DelegatedNotAttachedMessage = "No status for the named parent route"
	// DelegatedNotAttachedDetail is KGWUI-011's status-trigger detail; %s is the parent.
	DelegatedNotAttachedDetail = "No status entry for parent HTTPRoute %s"
	// DelegationNoChildMessage replaces "Backend not found" on a parent whose
	// backendRefs all delegate (D-021 item 9).
	DelegationNoChildMessage = own.DelegationNoChildMessage
	// DelegationNoChildDetail starts that finding's detail; the raw condition follows.
	DelegationNoChildDetail = own.DelegationNoChildDetail
	// ComputedNotAttachedMessage is the message of KGWUI-011's computed and orphan triggers (Task 67).
	ComputedNotAttachedMessage = "A parent route does not attach this route"
	// OrphanDetail is the orphan trigger's detail (Task 67).
	OrphanDetail = "The UI computes that no parent route in this install keeps this route. The route has no parentRefs."
)

Wording for delegation findings (design §6.2), from the wording pass (Task 31).

View Source
const (
	// ProcessWindow is how long a restart stays KGWUI-019 (design §9.3).
	ProcessWindow = 15 * time.Minute
	// MinProbeFailures is how many observed probe failures on one Pod raise KGWUI-020.
	MinProbeFailures = 3
)
View Source
const (
	// ReasonFinding: the row's own error or warning finding decides its state.
	ReasonFinding = "finding"
	// ReasonUnknown: a required check is not OK, which makes every row unknown.
	ReasonUnknown = "unknown"
	// ReasonGatewayRejecting: the row is warning only because its Gateway rejects config.
	ReasonGatewayRejecting = "gateway-rejecting"
	// ReasonBackendProblem: the route is warning only because a backend it sends to has a problem (D-082).
	ReasonBackendProblem = "backend-problem"
	// ReasonPathIncomplete: the viewer may not read everything the route's traffic path needs (design §8.1).
	ReasonPathIncomplete = "path-incomplete"
	// ReasonNotAttached: no parent accepted the route and it has no path rows (design §8.1).
	ReasonNotAttached = "not-attached"
	// ReasonNoPath: the route's status says accepted, yet the viewer has no path row of it,
	// such as when its Gateway lost the listener.
	ReasonNoPath = "no-path"
	// ReasonPathProblem: a signal on the route's path rows other than its Gateway's
	// rejection or a backend's, such as a listener condition; Code is the signal's code.
	ReasonPathProblem = "path-problem"
)

Row reason kinds (D-063).

View Source
const (
	// PolicyTargetNotFoundMessage is KGWUI-016's message, as for the controller's TargetNotFound.
	PolicyTargetNotFoundMessage = "Policy target not found"
	// TargetNotVerified labels a 016 whose ancestors cannot be tied to the missing target.
	TargetNotVerified = "Not verified: the controller's status cannot confirm this."
)

Wording for the computed KGWUI-016 and its verifier (design §7.6).

View Source
const (
	// RestartHold is how long a reject that disappears across a controller Pod
	// change is held before the Gateway reads clear (design §8.3).
	RestartHold = 60 * time.Second

	// RecentWindow is how long before a Gateway's first reject a change to an
	// object on it counts as recent (design §8.5).
	RecentWindow = 10 * time.Minute
	// MaxRecentlyChanged is how many recently changed objects 001 lists.
	MaxRecentlyChanged = 10
	// WithheldAfter is how long after the latest start a deferral line counts,
	// and how far apart two such lines must be (R105).
	WithheldAfter = 60 * time.Second
	// WithheldWindow is how long after the last such line the Gateway reads withheld.
	WithheldWindow = 15 * time.Minute
)
View Source
const BackendNoEvidenceDetail = "the controller does not report which Backend version it checked"

BackendNoEvidenceDetail is KGWUI-002's detail when a False Backend Accepted condition carries no observedGeneration (design §6.2). Draft wording, finalised in the wording pass.

View Source
const CodeConfigWithheld = "KGWUI-024"

CodeConfigWithheld is KGWUI-024: kgateway 2.5's per-client metrics show withheld or early-released proxy config (design §8.6).

View Source
const CodeListenerConflicted = "KGWUI-017"

CodeListenerConflicted is KGWUI-017: the controller reports a listener conflict (design §7.5).

View Source
const CodePolicyTargetNotFound = "KGWUI-016"

CodePolicyTargetNotFound is KGWUI-016: a policy target resolves to nothing (design §7.6).

View Source
const CodeRuleReplaced = "KGWUI-015"

CodeRuleReplaced is KGWUI-015: the controller replaced or dropped a route rule (design §7.4). Package own reports it (D-106) under the same code.

View Source
const CodeStatusNotProgressing = "KGWUI-018"

CodeStatusNotProgressing is KGWUI-018: status as a whole stopped moving (design §10.2).

View Source
const (
	// ComputedDisagreesMessage is KGWUI-012's message.
	ComputedDisagreesMessage = "The UI's computed view disagrees with the controller"
)

Wording for KGWUI-012 (design §6.2), from the wording passes (Tasks 48 and 67).

View Source
const EndpointsHold = 30 * time.Second

EndpointsHold is how long a Service port must have no ready endpoint before KGWUI-023 is raised (design §11).

View Source
const EvidenceEndpoints = "endpoints"

EvidenceEndpoints is the kind of EndpointsEvidence.

View Source
const EvidenceListenerConflict = "listener-conflict"

EvidenceListenerConflict is the kind of ListenerConflictEvidence.

View Source
const EvidenceProcess = "process"

EvidenceProcess is the kind of ProcessEvidence.

View Source
const EvidenceProxyStats = "proxy-stats"

EvidenceProxyStats is the kind of ProxyStatsEvidence.

View Source
const EvidenceStatusProgress = "status-progress"

EvidenceStatusProgress is the kind of StatusProgressEvidence.

View Source
const EvidenceVersionSkew = "version-skew"

EvidenceVersionSkew is the kind of VersionSkewEvidence.

View Source
const EvidenceWithheld = "withheld"

EvidenceWithheld is the kind of WithheldEvidence.

View Source
const EvidenceXDSRejects = "xds-rejects"

EvidenceXDSRejects is the kind of XDSRejectsEvidence.

View Source
const ExperimentalHint = "; the controller watches %s only when its experimental Gateway API features are on, and they may be off here"

ExperimentalHint is appended to the detail of a "not processed" finding on an experimental-only kind (D-018 §2); %s is the kind and served version.

View Source
const ExperimentalSentence = "The controller watches %s only with its experimental Gateway API features on. They may be off here."

ExperimentalSentence is the same hint as a page sentence, for an experimental-only object with no status (design §6.2); %s is the kind and served version.

View Source
const Grace = own.Grace

Grace is how long a resource may lack current status before it is reported as not yet processed.

View Source
const MaxStampedCollected = 61

MaxStampedCollected is how many declared collector keys can be restamp references; the engine never memoizes a check that declares more.

View Source
const NotForThisController = "Not available for this controller"

NotForThisController is the detail of a check whose input an install has none of, such as a class-only install's controller workload (Phase 5 design §5.2).

View Source
const ProxyConditionAge = 60 * time.Second

ProxyConditionAge is how long a Ready proxy must stay disconnected or warming before KGWUI-026 or 025 is raised (design §8.8).

View Source
const RuleReplacedHint = own.RuleReplacedHint

RuleReplacedHint ends a 015's detail once the rule has been replaced for longer than RuleReplacedHintAge (kgateway #14047).

View Source
const RuleReplacedHintAge = own.RuleReplacedHintAge

RuleReplacedHintAge is how long a rule stays replaced before the hint shows.

View Source
const (

	// SkewSettle is how long after a controller rollout KGWUI-022 stays suppressed (design §9.4).
	SkewSettle = 10 * time.Minute
)
View Source
const TargetHold = 30 * time.Second

TargetHold is how long a computed missing target must hold, after the policy's grace, before it is a KGWUI-016 (design §7.6).

View Source
const WithheldMessage = "Proxies may not be getting config updates"

WithheldMessage labels withheld config in a Gateway's Data plane section (R105).

View Source
const WithheldReleaseWindow = 15 * time.Minute

WithheldReleaseWindow is how long an alerting bounded publish keeps KGWUI-024's warning.

Variables

This section is empty.

Functions

func Desired

func Desired(d *appsv1.Deployment) int32

Desired returns d's desired replicas; an unset count defaults to 1.

func EndpointsRead added in v0.7.0

func EndpointsRead(snap *cache.Snapshot, ns string) bool

EndpointsRead reports whether snap holds the Services and EndpointSlices of namespace ns: always for a cluster-wide snapshot, else when it read both there.

func FindingID

func FindingID(installID, code string, resource *objects.Ref, key []string) string

FindingID returns "f1-" and 26 base32 characters of the SHA-256 of installID, code, the resource (four empty fields when nil) and key, NUL-joined (design §5.1).

func GatewayPending

func GatewayPending(u *unstructured.Unstructured, cs []metav1.Condition) string

GatewayPending is RoutePending for a Gateway or ListenerSet status block.

func GroupID

func GroupID(installID, family string, cause *objects.Ref, causeKey []string) string

GroupID returns the ID of the group of family whose cause is cause and causeKey: FindingID with code "G" and the family before the cause key (design §5.2).

func Load

func Load[T any](s *Store, key string) (T, bool)

Load returns the value under key as a T; false when it is absent or not a T.

func PolicyPending

func PolicyPending(u *unstructured.Unstructured, cs []metav1.Condition) string

PolicyPending is RoutePending for one status.ancestors entry of policy u.

func RefServiceSentence added in v0.7.0

func RefServiceSentence(explanation, name string, port int32, ports []int32) string

RefServiceSentence is explanation 2 or 3 in plain words for Service name ("namespace/name"): it does not exist, or has no port among ports.

func RoutePending

func RoutePending(u *unstructured.Unstructured, cs []metav1.Condition) string

RoutePending returns why one status.parents entry of route u is not current under the rules the resource status check applies to a kgateway install, or "" when it is. RoutePendingFor takes the install's own types.

func RoutePendingFor added in v0.6.0

func RoutePendingFor(u *unstructured.Unstructured, cs []metav1.Condition, ct ConditionTypes) string

RoutePendingFor is RoutePending for an install whose condition types are ct.

func RouteRefPath added in v0.7.0

func RouteRefPath(rule, ref, filter int) string

RouteRefPath is where a route writes a ref, as KGWUI-013/014 candidates name it: backendRefs[ref] of rule, or with filter >= 0 that filter's mirror, on the rule itself when ref is -1.

func ValidateOrder

func ValidateOrder(checks []Check) error

ValidateOrder reports a check whose Inputs().Checks names a check not registered before it, and two checks with one name, which would share a Store.

Types

type Availability

type Availability string

Availability says why a check's optional input is missing (D-034).

const (
	// AvailOff: the input's toggle is off.
	AvailOff Availability = "off"
	// AvailDenied: RBAC refused the watch or read.
	AvailDenied Availability = "denied"
	// AvailFailing: the watch or scrape errors.
	AvailFailing Availability = "failing"
	// AvailNotOnVersion: this controller version does not expose the input.
	AvailNotOnVersion Availability = "not-on-version"
	// AvailNotObserved: nothing to observe, such as a self-managed Gateway's proxies.
	AvailNotObserved Availability = "not-observed"
)

The reasons a check is not available.

func AccessAvailability

func AccessAvailability(a cache.Access) Availability

AccessAvailability returns why an optional watch with access a cannot feed its checks; "" when a is OK or still syncing.

type Basis added in v0.8.0

type Basis struct {
	// Collection marks a finding decided only by Snellius's own collection and access state.
	Collection bool
	// Refs are the objects an own-object analyzer named, present or absent.
	Refs []objects.Ref
	// contains filtered or unexported fields
}

Basis is what decided a finding, for who may see it (D-106).

type CRDVersion

type CRDVersion struct {
	Name          string `json:"name"`
	BundleVersion string `json:"bundleVersion,omitempty"`
	Channel       string `json:"channel,omitempty"`
}

CRDVersion is a Gateway API CRD's bundle annotations.

type Check

type Check interface {
	// Name identifies the check and its Store; it is unique among the registered checks.
	Name() string
	// Inputs names what Run reads. Reading an undeclared input is a bug.
	Inputs() InputSet
	Run(ctx RunContext) ([]Finding, CheckResult)
}

Check produces findings for one concern. Evaluate runs checks in registration order.

func Core added in v0.6.0

func Core() []Check

Core returns the checks that read only Gateway API status, the cluster and process data, in Upstream's order (Phase 5 design §6).

func Kgateway added in v0.6.0

func Kgateway() []Check

Kgateway returns the checks that read kgateway metrics, proxy stats, version tables, computed views or kgateway Backends, in Upstream's order (Phase 5 design §6).

func Upstream

func Upstream() []Check

Upstream returns every check, core and kgateway, in their run order (design §5.2, Phase 3 §9.3).

type CheckOutput

type CheckOutput struct {
	Findings []Finding
	Result   CheckResult
}

CheckOutput is what a check returned in this evaluation; its data is read-only.

type CheckResult

type CheckResult struct {
	Name        string    `json:"name"`
	OK          bool      `json:"ok"`
	Required    bool      `json:"required"`
	CollectedAt time.Time `json:"collectedAt"`
	Error       string    `json:"error,omitempty"`
	// Detail is extra context for an OK check, such as where a scope was read from.
	Detail string `json:"detail,omitempty"`
	// Pending marks a check that is not OK only because resources are still
	// being processed inside the grace period.
	Pending bool `json:"pending,omitempty"`
	// Unavailable says why the check's optional input is missing; RollUp ignores it.
	Unavailable Availability `json:"unavailable,omitempty"`
	// Gaps are the Gateways a per-Gateway input has nothing for, in Ref order.
	// Never serialised: a Gateway page reads its own entry after authorizing it.
	Gaps []GatewayGap `json:"-"`
	// Withheld are the Gateways whose proxies may get no config updates, in Ref order (R105).
	// Never serialised: a Gateway page reads its own entry after authorizing it.
	Withheld []WithheldGateway `json:"-"`
	// ControllerLogs says whether a check that reads the controller log read it
	// (LogsRead or LogsNotRead); empty for other checks. Never serialised.
	ControllerLogs string `json:"-"`
	// Hold says the check is still deciding on some items; nil when it waits on none.
	// Evaluate sets it from the run's RunContext.Hold calls (D-068).
	Hold *Hold `json:"hold,omitempty"`
	// NotAssessed marks a result shown as "Not checked" to a viewer without the full read.
	NotAssessed bool `json:"notAssessed,omitempty"`
	// Collection marks a collection or access failure (a watch denied, the
	// cache not synced). Every viewer sees it, Error replaced by fixed text
	// that names no object. Never serialised.
	Collection bool `json:"-"`
	// contains filtered or unexported fields
}

CheckResult records whether a check could collect current input. A Required check that is not OK forces the state to unknown, unless Unavailable is set.

func NotAvailable

func NotAvailable(name string, why Availability, detail string, at time.Time) CheckResult

NotAvailable returns a not-OK, not-required result with no finding; detail is the reason "What was checked" shows.

type Class added in v0.8.0

type Class uint8

Class says who may see a finding (D-106).

const (
	// ClassDerived findings are shown only to a viewer with the full read.
	ClassDerived Class = iota
	// ClassOwn findings come from package own and are shown per finding.
	ClassOwn
)

Classes. The zero value is derived, so every finding is derived unless runOwn marks it.

type ConditionTypes added in v0.6.0

type ConditionTypes = own.ConditionTypes

ConditionTypes are an implementation's route condition types beyond Gateway API's (Phase 5 design §9).

func KgatewayConditions added in v0.6.0

func KgatewayConditions() ConditionTypes

KgatewayConditions are kgateway's: kgateway.dev/Programmed, and the replaced rule on Accepted (2.3) or kgateway.dev/Programmed (2.4 on).

type ConflictingListener

type ConflictingListener struct {
	Owner    objects.Ref `json:"owner"`
	Name     string      `json:"name"`
	Protocol string      `json:"protocol,omitempty"`
	Hostname string      `json:"hostname,omitempty"`
}

ConflictingListener is another listener on the same Gateway that the rule finds. Owner is its Gateway or ListenerSet.

type DeployerError

type DeployerError struct {
	Class string `json:"class"`
	// Object is filtered on its own for the caller (design §14).
	Object *objects.Ref `json:"object,omitempty"`
	Last   time.Time    `json:"last"`
}

DeployerError is one kind of deployer error on a Gateway: its class, the object it names when the UI knows it, and when it was last logged.

type EndpointsEvidence

type EndpointsEvidence struct {
	// Service is the Service's name; Port the port as the backendRef writes it, PortName its Service port name.
	Service  string `json:"service"`
	Port     int32  `json:"port"`
	PortName string `json:"portName,omitempty"`
	Ready    int    `json:"ready"`
	Total    int    `json:"total"`
	Slices   int    `json:"slices"`
	// Routes are the routes naming the port, the group's affected list. Never serialised.
	Routes []objects.Ref `json:"-"`
}

EndpointsEvidence is a Service port behind KGWUI-023: its ready and total endpoints summed over the Service's EndpointSlices, and how many slices.

func PortEndpoints added in v0.7.0

func PortEndpoints(svc *cache.ServiceFact, slices []*cache.SliceFact, port int32) (ev *EndpointsEvidence, anyReady bool)

PortEndpoints counts the ready and total endpoints of svc's port numbered port in slices, the Service's slices, as KGWUI-023 does. It returns nil for a nil or ExternalName Service, or a port the Service lacks.

func (*EndpointsEvidence) EvidenceKind

func (*EndpointsEvidence) EvidenceKind() string

EvidenceKind implements Evidence.

func (*EndpointsEvidence) MarshalJSON

func (e *EndpointsEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

type Evidence

type Evidence interface {
	EvidenceKind() string
}

Evidence is a finding's typed evidence (design §13.3), tagged by its JSON "kind"; the objects it quotes are in Finding.Evidence (§14 rule 12).

func DecodeEvidence

func DecodeEvidence(b []byte) (Evidence, error)

DecodeEvidence decodes the JSON of an Evidence by its kind; nil for null or empty input.

type Finding

type Finding struct {
	// ID is stable across recomputes and restarts and unique within the
	// install; Evaluate sets it from Code, Resource and Key (design §5.1).
	ID       string       `json:"id,omitempty"`
	Code     string       `json:"code"`
	Slug     string       `json:"slug"`
	Severity Severity     `json:"severity"`
	Install  string       `json:"install"`
	Resource *objects.Ref `json:"resource,omitempty"`
	Message  string       `json:"message"`
	Detail   string       `json:"detail,omitempty"`
	// Since is when the problem started: a condition's lastTransitionTime, or
	// for a finding returned without one, when the UI first saw its ID.
	Since *time.Time `json:"since,omitempty"`
	// Group is the ID of the group whose cause explains the finding (design §5.2).
	Group string `json:"group,omitempty"`
	// Key is the code's discriminator among findings on one resource (design
	// §5.1); Evaluate hashes it into ID and clears it. Never serialised.
	Key []string `json:"-"`
	// Restricted marks a finding on a resource the caller may not view. The
	// API keeps its code, severity and resource and empties Message, Detail
	// and Since (D-013). Checks never set it.
	Restricted bool `json:"restricted,omitempty"`
	// Evidence are the objects, other than Resource, whose data Detail or
	// Facts quote (KGWUI-011: the parent route). Never serialised.
	Evidence []objects.Ref `json:"-"`
	// Facts are the typed evidence; the API drops them for a caller who may
	// not view Resource and all of Evidence (design §14 rule 12).
	Facts Evidence `json:"evidence,omitempty"`
	// ResourceSince is when the engine first saw Resource's current
	// generation. It replaces Since for a caller who may not view all of
	// Evidence, so Since tells that caller nothing about it. Never serialised.
	ResourceSince *time.Time `json:"-"`

	// Basis is what decided the finding, nil when nothing did; runOwn sets its
	// Refs. A pointer keeps the other findings small. Never serialised.
	Basis *Basis `json:"-"`
	// contains filtered or unexported fields
}

Finding is one problem or notable fact about an install.

func (*Finding) Class added in v0.8.0

func (f *Finding) Class() Class

Class is f's class: ClassOwn only for a finding from package own.

func (Finding) Derived added in v0.8.0

func (f Finding) Derived() Finding

Derived is f without its visibility marks: derived, with no basis. It only hides f from more viewers, so any caller may use it.

func (*Finding) FromEvents added in v0.8.0

func (f *Finding) FromEvents() bool

FromEvents reports whether f comes from Kubernetes Events: KGWUI-020's probe failures.

func (*Finding) OnCRD added in v0.8.0

func (f *Finding) OnCRD() bool

OnCRD reports whether f is on a CustomResourceDefinition: KGWUI-022's bundle skew quotes its annotations.

func (*Finding) ShownTo added in v0.8.0

func (f *Finding) ShownTo(rd Readable) bool

ShownTo reports whether a viewer without the full read sees f (D-106): an own-object finding when its resource and every object it named are readable, a collection finding when its resource, if any, is. A named object also counts when a NamedReadable may read it by name. A derived finding needs the full read, under which Project is not called.

type FreshnessCount

type FreshnessCount struct {
	Freshness string `json:"freshness"`
	Objects   int    `json:"objects"`
}

FreshnessCount is how many stuck objects have one §10.1 kind; an object with several 003s counts under its first kind in table order.

type FreshnessEvidence

type FreshnessEvidence = own.FreshnessEvidence

FreshnessEvidence is why KGWUI-003 judges a status not current (design §10.1).

type GatewayGap

type GatewayGap struct {
	Gateway     objects.Ref
	Unavailable Availability
	Reason      string
}

GatewayGap says why a check's input is not available for one Gateway.

type Hold added in v0.7.0

type Hold struct {
	// Until is the earliest moment a held item is decided.
	Until time.Time `json:"until"`
	// Count is how many items are held, in the unit the check raises its finding on.
	Count int `json:"count"`
	// Reason is generic text that never names an object.
	Reason string `json:"reason"`
}

Hold is what a check waits on before it decides: counts and a time, never object refs, so every caller may see it (D-068).

type IDs

type IDs struct {
	// contains filtered or unexported fields
}

IDs memoises IDs by their identity bytes across recomputes, so an unchanged finding or group is not hashed again. A nil *IDs computes every ID. A key is the identity with its first four fields (install, code, group, kind) replaced by their index in prefixes, so the many keys sharing them stay short.

func (*IDs) FindingID

func (x *IDs) FindingID(installID, code string, resource *objects.Ref, key []string) string

FindingID is FindingID, memoised.

func (*IDs) GroupID

func (x *IDs) GroupID(installID, family string, cause *objects.Ref, causeKey []string) string

GroupID is GroupID, memoised.

func (*IDs) Sweep

func (x *IDs) Sweep()

Sweep ends a recompute: once unused entries outnumber used ones, it drops them.

type Input

type Input struct {
	Install    install.Resolved
	Owned      *install.Owned
	Assignment install.Assignment
	Snapshot   *cache.Snapshot
	// Served are the served kinds; they map a parentRef's kind to its Access.
	Served []kinds.Served
	// KindsChange is how the kinds served now differ from Served, which the cache watches.
	KindsChange kinds.Change
	// Catalog is every kind the API server serves; the zero Catalog knows none.
	Catalog kinds.Catalog
	// FirstSeen returns when the engine first saw u's current generation; the
	// grace period runs from it. Nil means u's creation time.
	FirstSeen func(u *unstructured.Unstructured) time.Time
	Verify    scopeverify.Result
	Now       time.Time
	// Platform decides the wording of readiness findings; zero means Kubernetes.
	Platform platform.Info
	// ProxyMode decides whether a Gateway is self-managed; nil means proxymode.GatewayParameters{}.
	ProxyMode proxymode.Resolver
	// Computed are the install's computed views with their check states; nil means none.
	Computed *computed.Views
	// Views decodes Gateways, ListenerSets and routes; nil means objects.Direct.
	// Its views are shared and read-only.
	Views objects.Decoder
	// Process is the install's process data; a check declares InputSet.Process to read it.
	Process *ProcessData
	// GatewayAPI is the rule-set selection's Gateway API table (design §9.4); nil means none.
	GatewayAPI func(kgatewayMinor string) (bundle string, ok bool)
	// Rules is the install's rule set; one without a PolicyTargeter raises no computed KGWUI-016.
	Rules computed.Selection
	// Conditions are the install's condition types beyond Gateway API's; nil
	// means KgatewayConditions, as for a caller that builds Input itself.
	Conditions *ConditionTypes
}

Input is everything a check may look at for one install.

type InputSet

type InputSet struct {
	// Kinds are kinds read beyond Owned, such as core Pod and Namespace or apps Deployment.
	Kinds []objects.GroupKind
	// Owned is the install's assignment: every served kind and Namespaces.
	Owned bool
	// Verify is the scope verifier result.
	Verify bool
	// Computed are the install's computed views.
	Computed bool
	// KindsChange is how the served kinds differ from the watched ones.
	KindsChange bool
	// Catalog is every kind the API server serves.
	Catalog bool
	// Process is process data.
	Process bool
	// Clock marks a check that reads Now beyond its WakeAt deadlines; it is never memoized.
	Clock bool
	// Checks are the earlier checks whose output Run reads through RunContext.Output.
	Checks []string
	// Collected are collector keys, "<collector>/<key>".
	Collected []string
}

InputSet names what a check reads; the engine fingerprints exactly these. Install, Platform and ProxyMode are always inputs.

func AllInputs

func AllInputs() InputSet

AllInputs declares every input a Phase 1 or 2 check may read: Owned, Verify, Computed, KindsChange and Clock. It names no collector keys, so controller metrics (ctrlmetrics.Key) are declared separately.

type ListenerConflictEvidence

type ListenerConflictEvidence struct {
	Listener string `json:"listener"`
	Port     int32  `json:"port"`
	Protocol string `json:"protocol,omitempty"`
	Hostname string `json:"hostname,omitempty"`
	Reason   string `json:"reason"`
	Message  string `json:"message"`
	Rule     string `json:"rule,omitempty"`
	// Others holds the first maxConflictOthers; OthersTotal counts them all.
	Others      []ConflictingListener `json:"others,omitempty"`
	OthersTotal int                   `json:"othersTotal"`
}

ListenerConflictEvidence is what KGWUI-017 quotes: the controller's condition on the listener, and the other listeners the UI computes by Rule. Rule is empty for a reason no rule covers, such as a reserved port.

func (*ListenerConflictEvidence) EvidenceKind

func (*ListenerConflictEvidence) EvidenceKind() string

EvidenceKind implements Evidence.

func (*ListenerConflictEvidence) MarshalJSON

func (e *ListenerConflictEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

type NamedReadable added in v0.8.0

type NamedReadable interface {
	Named(objects.Ref) bool
}

NamedReadable is a Readable that also says which objects a viewer may read by name: an object named in a readable one, present or absent (D-100 item 1).

type PanicFacts

type PanicFacts struct {
	Class  string    `json:"class"`
	Frame  string    `json:"frame,omitempty"`
	ReadAt time.Time `json:"readAt"`
}

PanicFacts are a Go panic's class and top frame. A trace has no time, so ReadAt is when the UI read the previous container's log.

type ProbeFacts

type ProbeFacts struct {
	Type     string    `json:"type,omitempty"`
	Failures int       `json:"failures"`
	Last     time.Time `json:"last"`
	// HistoryUnknown marks failures before the UI saw the Event, which are not counted.
	HistoryUnknown bool `json:"historyUnknown,omitempty"`
}

ProbeFacts are a Pod's observed probe failures in the Events window. Type is empty when the Pod defines more than one probe type ("a probe").

type ProcessData

type ProcessData struct {
	Controller process.Set
	Proxies    map[objects.Ref]process.Set
	Print      uint64
}

ProcessData is one install's controller and per-Gateway proxy processes (§9.1); Print hashes both, and process.PodRef gives each Pod's ref.

type ProcessEvidence

type ProcessEvidence struct {
	Pod string `json:"pod,omitempty"`
	// Restarts are the restarts observed in the window; nil when none was observed.
	Restarts    *int32            `json:"restarts,omitempty"`
	Termination *TerminationFacts `json:"termination,omitempty"`
	Waiting     string            `json:"waiting,omitempty"`
	Probe       *ProbeFacts       `json:"probe,omitempty"`
	// ControllerLogs says whether the controller log was read, on the codes it informs (019, 021).
	ControllerLogs string `json:"controllerLogs,omitempty"`
	// Panic is the controller's last panic in the window, from the previous container's log.
	Panic *PanicFacts `json:"panic,omitempty"`
	// Deployer are the deployer errors for the Gateway in the window, newest first.
	Deployer []DeployerError `json:"deployer,omitempty"`
}

ProcessEvidence is one Pod's facts behind KGWUI-005, 006 and 019–021. Pod is empty on a 021 whose only facts come from the controller log.

func (*ProcessEvidence) EvidenceKind

func (*ProcessEvidence) EvidenceKind() string

EvidenceKind implements Evidence.

func (*ProcessEvidence) MarshalJSON

func (e *ProcessEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

type ProxyCount

type ProxyCount struct {
	Ready   int32 `json:"ready"`
	Desired int32 `json:"desired"`
}

ProxyCount is a Gateway's ready and desired proxy replicas.

type ProxyPodStats

type ProxyPodStats struct {
	Pod              string `json:"pod"`
	Connected        *bool  `json:"connected,omitempty"`
	WarmingListeners *int64 `json:"warmingListeners,omitempty"`
	WarmingClusters  *int64 `json:"warmingClusters,omitempty"`
	ServerState      string `json:"serverState,omitempty"`
}

ProxyPodStats is one proxy's Envoy stats; nil fields were not reported.

type ProxyRejects

type ProxyRejects struct {
	Pod   string             `json:"pod"`
	Types []ProxyTypeRejects `json:"types"`
}

ProxyRejects is one proxy Pod's rejects observed per xDS type.

type ProxyStatsEvidence

type ProxyStatsEvidence struct {
	Pods []ProxyPodStats `json:"pods"`
}

ProxyStatsEvidence is the Ready proxy Pods behind KGWUI-025 or 026.

func (*ProxyStatsEvidence) EvidenceKind

func (*ProxyStatsEvidence) EvidenceKind() string

EvidenceKind implements Evidence.

func (*ProxyStatsEvidence) MarshalJSON

func (e *ProxyStatsEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

type ProxyTypeRejects

type ProxyTypeRejects struct {
	TypeURL        string     `json:"typeUrl"`
	Rejecting      bool       `json:"rejecting"`
	RejectingSince *time.Time `json:"rejectingSince,omitempty"`
	// EnvoyResources are Envoy names, never Gateway API objects.
	EnvoyResources          []string `json:"envoyResources,omitempty"`
	EnvoyResourcesTruncated bool     `json:"envoyResourcesTruncated,omitempty"`
	// Objects are the objects the rule set maps names to; each name is filtered as its object (§14). Never serialised.
	Objects map[string]objects.Ref `json:"-"`
}

ProxyTypeRejects says whether a type's update_rejected grew since the Pod's previous scrape, since when, and the Envoy names whose counter grew.

type RawEvidence

type RawEvidence struct {
	Kind string
	JSON json.RawMessage
}

RawEvidence is evidence of a kind this build does not know, kept as sent.

func (*RawEvidence) EvidenceKind

func (e *RawEvidence) EvidenceKind() string

EvidenceKind implements Evidence.

func (*RawEvidence) MarshalJSON

func (e *RawEvidence) MarshalJSON() ([]byte, error)

MarshalJSON returns the evidence as sent.

type Readable added in v0.8.0

type Readable interface {
	Ref(objects.Ref) bool
}

Readable says which objects a viewer may read.

type RefLocation

type RefLocation = own.RefLocation

RefLocation is one ref and where its referrer writes it.

type RefsEvidence

type RefsEvidence = own.RefsEvidence

RefsEvidence is why KGWUI-013 or 014 names its refs.

type ReleaseModeCount

type ReleaseModeCount struct {
	Mode  string `json:"mode"`
	Count int    `json:"count"`
}

ReleaseModeCount is how many bounded publishes of one mode a Gateway had.

type Report

type Report struct {
	// Install is the install ID, so a client can reject a response for another install.
	Install     string           `json:"install"`
	State       State            `json:"state"`
	Findings    []Finding        `json:"findings"`
	Checks      []CheckResult    `json:"checks"`
	Counts      map[Severity]int `json:"counts"`
	CollectedAt time.Time        `json:"collectedAt"`
	// Next is the earliest time after CollectedAt at which a check's output
	// may change; zero means none.
	Next time.Time `json:"-"`
}

Report is the evaluated health of one install.

func Evaluate

func Evaluate(in Input, checks []Check, rt Runtime) Report

Evaluate runs checks and assembles a Report. Findings are in a fixed order (severity, code, resource, parentRef, message, detail), so a list does not reorder between polls. A finding with a severity outside error, warning and info becomes a warning whose detail names the original, so a check can neither hide a problem from the roll-up nor invent a severity. Checks run in order, each with its Store from rt.States; a grace read inside the grace period wakes the report at the grace end (Report.Next). A check without Clock reuses its memo while its input print holds and its wake time is not due (§16.2). Every finding gets its ID; one without Since gets its first-seen time from its check's Store (design §5.1). When every check returns the same findings slice as in the last Evaluate (a memo hit, or a rerun with equal findings), the findings are that report's slice, shared and with the Group values diagnose.Build set on it.

func Project added in v0.8.0

func Project(rep Report, rd Readable) Report

Project is rep as a viewer without the full read sees it: the findings ShownTo them, in order and without Group, counted again; each check result whole when it is a collection failure, else "Not checked"; and the state rolled up from those. So install-wide unknown comes only from collection failures. A nil rd is the full read and returns rep unchanged.

func Withhold added in v0.8.0

func Withhold(rep Report, events, crds bool) Report

Withhold is rep for a full reader who may not list Events or CRDs, as events and crds say (D-110): without findings from them and, for Events, the probe check "Not checked" unless a collection failure, as Project shows them, and for CRDs no CRD comparison note; counted and rolled up again.

type RowReason

type RowReason struct {
	Kind    string `json:"kind"`
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
	More    int    `json:"more,omitempty"`
}

RowReason says why a list or overview row is not healthy; healthy rows have none. Kind finding carries the deciding finding's code and message, never its detail or evidence, and More counts the object's other findings, all of which are of that severity or lower. Kind backend-problem carries the backend's deciding finding's code and message. The other kinds carry nothing else.

type RuleReplacedEvidence

type RuleReplacedEvidence = own.RuleReplacedEvidence

RuleReplacedEvidence is what KGWUI-015 quotes.

type RunContext

type RunContext struct {
	Input
	// State is engine-owned per (install, check); it survives recomputes and
	// is cleared on restart.
	State *Store
	// contains filtered or unexported fields
}

RunContext is what a check runs with: the install's Input and its own Store.

func (RunContext) Collected

func (c RunContext) Collected(key string) (collect.Value, bool)

Collected returns the collector value under key, "<collector>/<key>". It is false unless Inputs().Collected declares key and the collector has published it. The value's Data is read-only.

func (RunContext) Hold added in v0.7.0

func (c RunContext) Hold(until time.Time, count int, reason string)

Hold says the check decides on count items at until, and why; reason must never name an object (D-068). It wakes the engine at until. Evaluate puts the run's holds on its CheckResult: the earliest until, the summed count and the distinct reasons. A time not after Now is ignored.

func (RunContext) Output

func (c RunContext) Output(check string) (CheckOutput, bool)

Output returns the output of check in this evaluation. It is false unless Inputs().Checks declares check and check ran before this one.

func (RunContext) Retain

func (c RunContext) Retain(findingID string)

Retain keeps the since entry of findingID although this run does not return it.

func (RunContext) WakeAt

func (c RunContext) WakeAt(at time.Time)

WakeAt says the check's output may change at at; the engine recomputes by then. A time not after Now is ignored.

type Runtime

type Runtime struct {
	States    *States
	Print     func(InputSet) (uint64, bool)
	Collected collect.Snapshot
}

Runtime is what Evaluate keeps across recomputes; nil States gives fresh Stores. Print keys a check's memo (false: always run); nil Print turns memoization off.

type Severity

type Severity string

Severity of a finding.

const (
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
	SeverityInfo    Severity = "info"
)

Severities.

type State

type State string

State is the rolled-up health of an install.

const (
	StateError   State = "error"
	StateUnknown State = "unknown"
	StateWarning State = "warning"
	StateHealthy State = "healthy"
)

States, from worst to best: error, unknown, warning, healthy.

func BackendState

func BackendState(b *unstructured.Unstructured) (State, *metav1.Condition)

BackendState returns a Backend's state from the kgateway pack's judgement of its Accepted condition's own evidence, never from the controller version, with that condition (nil when absent). Without current evidence the state is unknown, never healthy. Core code reads computed.BackendJudge.

func RollUp

func RollUp(fs []Finding, cs []CheckResult) State

RollUp computes the state: error > unknown > warning > healthy (design §5.3). A not-available check result never makes the state unknown.

type States

type States struct {
	// contains filtered or unexported fields
}

States holds one install's check Stores and memos, keyed by check name.

func NewStates

func NewStates() *States

NewStates returns States with no Stores.

func (*States) GroupIDs

func (s *States) GroupIDs() *IDs

GroupIDs returns the install's memoised group IDs; nil for nil s.

func (*States) SeedSince

func (s *States) SeedSince(check, id string, at time.Time)

SeedSince sets finding id's first-seen time in check's Store, as if it were first seen at at.

type StatusProgressEvidence

type StatusProgressEvidence struct {
	Kinds  []FreshnessCount `json:"kinds"`
	Oldest time.Time        `json:"oldest"`
}

StatusProgressEvidence is what KGWUI-018 quotes: the stuck objects per §10.1 kind and the oldest KGWUI-003 warning's since.

func (*StatusProgressEvidence) EvidenceKind

func (*StatusProgressEvidence) EvidenceKind() string

EvidenceKind implements Evidence.

func (*StatusProgressEvidence) MarshalJSON

func (e *StatusProgressEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store is a check's state across recomputes for one install. The engine owns it: it survives recomputes and is empty after a restart. It is not safe for concurrent use; the engine runs one check at a time. Reads of a nil Store find nothing; Set on a nil Store panics.

func NewStore

func NewStore() *Store

NewStore returns an empty Store.

func (*Store) Delete

func (s *Store) Delete(key string)

Delete removes key.

func (*Store) Get

func (s *Store) Get(key string) (any, bool)

Get returns the value under key.

func (*Store) Len

func (s *Store) Len() int

Len returns the number of keys.

func (*Store) Set

func (s *Store) Set(key string, v any)

Set stores v under key.

type TerminationFacts

type TerminationFacts struct {
	Reason   string    `json:"reason,omitempty"`
	ExitCode int32     `json:"exitCode"`
	At       time.Time `json:"at"`
}

TerminationFacts are how a process last ended; never its message.

type VersionPods

type VersionPods struct {
	Version string   `json:"version"`
	Pods    []string `json:"pods"`
	Total   int      `json:"total"`
}

VersionPods are the Pods running one version, empty when the tag is not one. Pods holds the first few names; Total counts them all.

type VersionSkewEvidence

type VersionSkewEvidence struct {
	Controller string        `json:"controller,omitempty"`
	Proxies    []VersionPods `json:"proxies,omitempty"`
	Replicas   []VersionPods `json:"replicas,omitempty"`
	CRDs       []CRDVersion  `json:"crds,omitempty"`
	// Expected is the Gateway API bundle minor the controller is built against.
	Expected string `json:"expected,omitempty"`
}

VersionSkewEvidence is the versions behind KGWUI-022: the controller's, and the proxies', controller replicas' or CRDs' that differ.

func (*VersionSkewEvidence) EvidenceKind

func (*VersionSkewEvidence) EvidenceKind() string

EvidenceKind implements Evidence.

func (*VersionSkewEvidence) MarshalJSON

func (e *VersionSkewEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

type WithheldEvidence

type WithheldEvidence struct {
	// Withheld counts the Gateway's warm proxies still withheld after the publish budget.
	Withheld int `json:"withheld,omitempty"`
	// Releases are the alerting bounded publishes in the last 15 minutes, by mode.
	Releases []ReleaseModeCount `json:"releases,omitempty"`
	// ReportedBy are the controller Pods behind Withheld and Releases, sorted.
	ReportedBy []string `json:"reportedBy"`
}

WithheldEvidence is one Gateway's per-client publication metrics behind KGWUI-024, summed over controller Pods.

func (*WithheldEvidence) EvidenceKind

func (*WithheldEvidence) EvidenceKind() string

EvidenceKind implements Evidence.

func (*WithheldEvidence) MarshalJSON

func (e *WithheldEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

type WithheldGateway

type WithheldGateway struct {
	Gateway     objects.Ref
	First, Last time.Time
}

WithheldGateway is a Gateway whose snapshot deferral recurred after its proxies and the controller started: the first and last such line.

type XDSLogEvent

type XDSLogEvent struct {
	TypeURL        string    `json:"typeUrl"`
	Since          time.Time `json:"since"`
	Classes        []string  `json:"classes"`
	EnvoyResources []string  `json:"envoyResources,omitempty"`
	// Objects are the objects the rule set maps names to; each name is filtered as its object (§14). Never serialised.
	Objects map[string]objects.Ref `json:"-"`
}

XDSLogEvent is one rejected type's "xds error" lines: the earliest, the error classes and the Envoy names known from proxy stats.

type XDSRejectsEvidence

type XDSRejectsEvidence struct {
	Types []XDSTypeRejects `json:"types"`
	// Proxies is nil when the Gateway has no proxy Deployment.
	Proxies           *ProxyCount `json:"proxies,omitempty"`
	StatusSaysHealthy bool        `json:"statusSaysHealthy"`
	// ProxyStats are the Gateway's scraped proxy Pods: rejects observed since
	// their previous scrape, never "rejecting now" (design §8.8).
	ProxyStats []ProxyRejects `json:"proxyStats,omitempty"`
	// RecentlyChanged are objects on the Gateway changed shortly before the first
	// reject, newest first. Not in Finding.Evidence: each is authorized on its own (§14 rule 14).
	RecentlyChanged []objects.Ref `json:"recentlyChanged,omitempty"`
	// ControllerLogs says whether the controller log was read; LogEvents are absent when not.
	ControllerLogs string `json:"controllerLogs"`
	// LogEvents are the log's rejects per rejected type, one per type whichever replica logged it.
	LogEvents []XDSLogEvent `json:"logEvents,omitempty"`
}

XDSRejectsEvidence is what KGWUI-001 quotes: the rejected types, the Gateway's proxies, and whether its status contradicts the rejects (§8.3).

func (*XDSRejectsEvidence) EvidenceKind

func (*XDSRejectsEvidence) EvidenceKind() string

EvidenceKind implements Evidence.

func (*XDSRejectsEvidence) MarshalJSON

func (e *XDSRejectsEvidence) MarshalJSON() ([]byte, error)

MarshalJSON adds the kind tag.

type XDSTypeRejects

type XDSTypeRejects struct {
	TypeURL             string    `json:"typeUrl"`
	Streams             int       `json:"streams"`
	ReportedBy          []string  `json:"reportedBy"`
	FirstSeen           time.Time `json:"firstSeen"`
	TotalSinceFirstSeen int       `json:"totalSinceFirstSeen"`
}

XDSTypeRejects is one rejected xDS type: rejecting streams summed over the controller Pods that report them, and rejects_total growth since FirstSeen.

Directories

Path Synopsis
internal
twin/health
Package health holds a type whose short name matches one in the health package's tests, so deepPrint's type identity can be tested.
Package health holds a type whose short name matches one in the health package's tests, so deepPrint's type identity can be tested.
Package own produces own-object findings (D-106): findings decided only by their resource and the objects it names, given the install context.
Package own produces own-object findings (D-106): findings decided only by their resource and the objects it names, given the install context.

Jump to

Keyboard shortcuts

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