Documentation
¶
Overview ¶
Package health turns cluster state and controller signals into findings and a health state per install (design §5).
Index ¶
- Constants
- func Desired(d *appsv1.Deployment) int32
- func EndpointsRead(snap *cache.Snapshot, ns string) bool
- func FindingID(installID, code string, resource *objects.Ref, key []string) string
- func GatewayPending(u *unstructured.Unstructured, cs []metav1.Condition) string
- func GroupID(installID, family string, cause *objects.Ref, causeKey []string) string
- func Load[T any](s *Store, key string) (T, bool)
- func PolicyPending(u *unstructured.Unstructured, cs []metav1.Condition) string
- func RefServiceSentence(explanation, name string, port int32, ports []int32) string
- func RoutePending(u *unstructured.Unstructured, cs []metav1.Condition) string
- func RoutePendingFor(u *unstructured.Unstructured, cs []metav1.Condition, ct ConditionTypes) string
- func RouteRefPath(rule, ref, filter int) string
- func ValidateOrder(checks []Check) error
- type Availability
- type Basis
- type CRDVersion
- type Check
- type CheckOutput
- type CheckResult
- type Class
- type ConditionTypes
- type ConflictingListener
- type DeployerError
- type EndpointsEvidence
- type Evidence
- type Finding
- type FreshnessCount
- type FreshnessEvidence
- type GatewayGap
- type Hold
- type IDs
- type Input
- type InputSet
- type ListenerConflictEvidence
- type NamedReadable
- type PanicFacts
- type ProbeFacts
- type ProcessData
- type ProcessEvidence
- type ProxyCount
- type ProxyPodStats
- type ProxyRejects
- type ProxyStatsEvidence
- type ProxyTypeRejects
- type RawEvidence
- type Readable
- type RefLocation
- type RefsEvidence
- type ReleaseModeCount
- type Report
- type RowReason
- type RuleReplacedEvidence
- type RunContext
- type Runtime
- type Severity
- type State
- type States
- type StatusProgressEvidence
- type Store
- type TerminationFacts
- type VersionPods
- type VersionSkewEvidence
- type WithheldEvidence
- type WithheldGateway
- type XDSLogEvent
- type XDSRejectsEvidence
- type XDSTypeRejects
Constants ¶
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).
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.
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).
const ( CodeXDSRejected = "KGWUI-001" CodeConditionFalse = "KGWUI-002" CodeRouteUnattached = "KGWUI-003" CodeNamespaceNotWatched = "KGWUI-004" CodeControllerNotReady = "KGWUI-005" CodeProxyNotReady = "KGWUI-006" CodeScopeMismatch = "KGWUI-007" 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).
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.
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).
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 )
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).
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).
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 )
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.
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).
const CodeListenerConflicted = "KGWUI-017"
CodeListenerConflicted is KGWUI-017: the controller reports a listener conflict (design §7.5).
const CodePolicyTargetNotFound = "KGWUI-016"
CodePolicyTargetNotFound is KGWUI-016: a policy target resolves to nothing (design §7.6).
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.
const CodeStatusNotProgressing = "KGWUI-018"
CodeStatusNotProgressing is KGWUI-018: status as a whole stopped moving (design §10.2).
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).
const EndpointsHold = 30 * time.Second
EndpointsHold is how long a Service port must have no ready endpoint before KGWUI-023 is raised (design §11).
const EvidenceEndpoints = "endpoints"
EvidenceEndpoints is the kind of EndpointsEvidence.
const EvidenceListenerConflict = "listener-conflict"
EvidenceListenerConflict is the kind of ListenerConflictEvidence.
const EvidenceProcess = "process"
EvidenceProcess is the kind of ProcessEvidence.
const EvidenceProxyStats = "proxy-stats"
EvidenceProxyStats is the kind of ProxyStatsEvidence.
const EvidenceStatusProgress = "status-progress"
EvidenceStatusProgress is the kind of StatusProgressEvidence.
const EvidenceVersionSkew = "version-skew"
EvidenceVersionSkew is the kind of VersionSkewEvidence.
const EvidenceWithheld = "withheld"
EvidenceWithheld is the kind of WithheldEvidence.
const EvidenceXDSRejects = "xds-rejects"
EvidenceXDSRejects is the kind of XDSRejectsEvidence.
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.
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.
const Grace = own.Grace
Grace is how long a resource may lack current status before it is reported as not yet processed.
const MaxStampedCollected = 61
MaxStampedCollected is how many declared collector keys can be restamp references; the engine never memoizes a check that declares more.
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).
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).
const RuleReplacedHint = own.RuleReplacedHint
RuleReplacedHint ends a 015's detail once the rule has been replaced for longer than RuleReplacedHintAge (kgateway #14047).
const RuleReplacedHintAge = own.RuleReplacedHintAge
RuleReplacedHintAge is how long a rule stays replaced before the hint shows.
const ( // SkewSettle is how long after a controller rollout KGWUI-022 stays suppressed (design §9.4). SkewSettle = 10 * time.Minute )
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).
const WithheldMessage = "Proxies may not be getting config updates"
WithheldMessage labels withheld config in a Gateway's Data plane section (R105).
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
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 ¶
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 ¶
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 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
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
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 ¶
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).
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 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 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 ¶
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
Class is f's class: ClassOwn only for a finding from package own.
func (Finding) Derived ¶ added in v0.8.0
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
FromEvents reports whether f comes from Kubernetes Events: KGWUI-020's probe failures.
func (*Finding) OnCRD ¶ added in v0.8.0
OnCRD reports whether f is on a CustomResourceDefinition: KGWUI-022's bundle skew quotes its annotations.
func (*Finding) ShownTo ¶ added in v0.8.0
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 ¶
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 ¶
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.
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.
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
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 ¶
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 ¶
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 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 ¶
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 ¶
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
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
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 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.
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.
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 ¶
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.
Source Files
¶
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. |