Documentation
¶
Overview ¶
Package api serves the read-only JSON API (design §7), the probes and the SPA.
Index ¶
- Constants
- func CheckCapabilities(platformNames []string, sources ...func() []Capability) error
- func CheckExtMounts(m ...ExtMount) error
- func CheckExtName(name string) error
- func NewHandler(src ModelSource, ui fs.FS, authz Authorizer, opts ...HandlerOption) http.Handler
- func Visible[T any](r *http.Request, a Authorizer, items []T, ref func(T) objects.Ref) (visible []T, hidden int)
- func WriteError(w http.ResponseWriter, code int, msg string)
- func WriteJSON(w http.ResponseWriter, v any)
- type AllowAll
- type AllowedListenersDTO
- type AllowedRoutesDTO
- type AncestorPathDTO
- type AncestorStepDTO
- type Attachment
- type Authorizer
- type AuthorizerFunc
- type BackendRefDTO
- type BackendStateDTO
- type Candidate
- type Capability
- type CapabilityState
- type Computed
- type Condition
- type ConflictEvidence
- type ConflictListener
- type DataPlaneDTO
- type DataPlaneSummary
- type DataPlaneTypes
- type DelegationContext
- type DelegationObserved
- type DelegationRefDTO
- type DelegationRow
- type Diagnostics
- type EffectiveContext
- type EffectiveDTO
- type EffectiveRuleDTO
- type ErrorResponse
- type ExtMount
- type FilterDTO
- type FindingDTO
- type FindingDetail
- type FindingRow
- type FractionDTO
- type GatewayDetail
- type GatewayListRow
- type GatewayProcesses
- type GrantShape
- type GroupRow
- type HandlerOption
- func WithCapabilitySources(f ...func() []Capability) HandlerOption
- func WithCommands(c diagnose.Commands) HandlerOption
- func WithCoreCapabilities(f func() []Capability) HandlerOption
- func WithExtMounts(m ...ExtMount) HandlerOption
- func WithInstallCommands(f func(install.Install) diagnose.Commands) HandlerOption
- func WithInstallFeatures(f func(install.Install) []string) HandlerOption
- func WithInstallKinds(f func(install.Install, objects.GroupKind) bool) HandlerOption
- func WithPacks(names ...string) HandlerOption
- type HealthResponse
- type HealthSummary
- type InstallSummary
- type KeyMatchDTO
- type Link
- type LinkedRef
- type ListenerAttachment
- type ListenerDTO
- type ListenerSetDetail
- type ListenerSetRow
- type ListenerStatusDTO
- type ListenerTLSDTO
- type MatchDTO
- type MetaResponse
- type MirrorDTO
- type ModelSource
- type NextStep
- type OverviewGatewayRow
- type OverviewResponse
- type Page
- type ParentStatus
- type ParentSummary
- type PathMatchDTO
- type PathStepDTO
- type ProcessDTO
- type ProcessSetDTO
- type ProcessSummaries
- type ProcessSummary
- type ProcessesResponse
- type ProxyStatsDTO
- type ProxySummary
- type RolloutDTO
- type RouteAnnotations
- type RouteAttachment
- type RouteCounts
- type RouteDetail
- type RouteNamespacesDTO
- type RouteRow
- type RuleDTO
- type RuleEvidence
- type SnapshotDTO
- type SpecParentRef
- type SuggestedFix
- type TrailRefs
- type Verdict
- type WithheldDTO
- type XDSEvidence
Constants ¶
const ( // DataPlaneOK: the xDS rejects check ran and found no reject for the Gateway. DataPlaneOK = "ok" // DataPlaneRejects: the Gateway has a KGWUI-001. DataPlaneRejects = "rejects" // DataPlaneWithheld: no KGWUI-001, but a KGWUI-024 error: the proxies get no config updates. DataPlaneWithheld = "withheld" // DataPlaneUnknown: no reject, but the xDS rejects check is not OK or did not run. DataPlaneUnknown = "unknown" )
The values of OverviewGatewayRow.DataPlane.
const ( DelegationReported = "reported" DelegationNotReported = "not-reported" DelegationNotFound = "not-found" DelegationRestricted = "restricted" )
Delegation ref states (design §7.3), status-based, for name refs only.
const ( FeatureDelegation = "delegation" FeatureComputed = "computed" FeatureDataPlane = "dataplane" FeatureProcesses = "processes" )
Install features, as InstallSummary.Features lists them (Phase 5 design §10).
const ComputedBy = "ui"
ComputedBy marks a fact the UI computed (D-020).
Variables ¶
This section is empty.
Functions ¶
func CheckCapabilities ¶
func CheckCapabilities(platformNames []string, sources ...func() []Capability) error
CheckCapabilities calls each source once and reports a name that is empty, repeated, or reserved by the core or the platform, and an unknown state.
func CheckExtMounts ¶
CheckExtMounts reports every mount whose name or pattern is invalid, whose path leaves /api/ext/{name}/, or that the mux rejects, such as two patterns it cannot tell apart.
func CheckExtName ¶
CheckExtName reports whether name can name an extension: a lowercase letter, then up to 62 lowercase letters, digits or dashes.
func NewHandler ¶
func NewHandler(src ModelSource, ui fs.FS, authz Authorizer, opts ...HandlerOption) http.Handler
NewHandler returns the HTTP handler for the API, the probes and the SPA in ui. Every response with resources, findings or counts goes through authz; a nil authz means AllowAll (D-013). Options add extension endpoints.
func Visible ¶
func Visible[T any](r *http.Request, a Authorizer, items []T, ref func(T) objects.Ref) (visible []T, hidden int)
Visible returns the items whose ref the caller of r may view, in order, and the number hidden, asking a about each ref once (D-013). Under AllowAll, or a nil a, it makes no calls and returns items, clipped so an append cannot alias it.
func WriteError ¶
func WriteError(w http.ResponseWriter, code int, msg string)
WriteError writes the API's JSON error body with status code.
func WriteJSON ¶
func WriteJSON(w http.ResponseWriter, v any)
WriteJSON writes v as an uncached JSON response, as core handlers do.
Types ¶
type AllowAll ¶
type AllowAll struct{}
AllowAll lets every caller see everything the UI can read: the Phase 1 trust model, in which whoever reaches the UI may view all it shows.
type AllowedListenersDTO ¶
type AllowedListenersDTO struct {
Set bool `json:"set"`
Value map[string]any `json:"value,omitempty"`
CRDHint bool `json:"crdHint"`
CRDField string `json:"crdField,omitempty"`
CRDChannel string `json:"crdChannel,omitempty"`
CRDBundleVersion string `json:"crdBundleVersion,omitempty"`
}
AllowedListenersDTO is the parent Gateway's spec.allowedListeners as written; CRDHint is set whenever it is absent, and CRDField says whether the Gateway CRD defines it ("defined", "missing").
type AllowedRoutesDTO ¶
type AllowedRoutesDTO struct {
Namespaces RouteNamespacesDTO `json:"namespaces"`
Kinds []objects.GroupKind `json:"kinds"`
}
AllowedRoutesDTO is a listener's allowedRoutes.
type AncestorPathDTO ¶
type AncestorPathDTO struct {
Steps []AncestorStepDTO `json:"steps"`
Cycle bool `json:"cycle"`
}
AncestorPathDTO is one up-chain path, root first.
type AncestorStepDTO ¶
type AncestorStepDTO struct {
Ref *LinkedRef `json:"ref,omitempty"`
Matches []MatchDTO `json:"matches,omitempty"`
Restricted bool `json:"restricted,omitempty"`
}
AncestorStepDTO is one up-chain step: a ref, or Restricted with no identity. A hidden ancestor route has link none and Matches, the matches it delegated under in view B, and nothing else (design §7.4 rule 3, D-024).
type Attachment ¶
type Attachment struct {
Outcome string `json:"outcome,omitempty"`
Listeners []ListenerAttachment `json:"listeners"`
Explanation string `json:"explanation,omitempty"`
Computed Computed `json:"computed"`
}
Attachment is view A's outcome of one parentRef. Outcome is absent when the outcome is unknown or restricted; Explanation is set on a rejection.
type Authorizer ¶
type Authorizer interface {
// Authorize reports whether the caller of r may view the object ref.
Authorize(r *http.Request, ref objects.Ref) bool
}
Authorizer decides, per request, which objects the caller may see (D-013). Findings are filtered by applying it to each finding's resource. Phase 1 ships AllowAll; per-user authorisation plugs in here later.
type AuthorizerFunc ¶
AuthorizerFunc adapts a function to Authorizer.
type BackendRefDTO ¶
type BackendRefDTO struct {
Ref LinkedRef `json:"ref"`
Port int32 `json:"port,omitempty"`
Weight int32 `json:"weight"`
WeightDefaulted bool `json:"weightDefaulted,omitempty"`
Filters []FilterDTO `json:"filters"`
Delegation *DelegationRefDTO `json:"delegation,omitempty"`
Backend *BackendStateDTO `json:"backend,omitempty"`
}
BackendRefDTO is one rule backendRef. An absent weight is 1 with WeightDefaulted; an absent port is omitted.
type BackendStateDTO ¶
type BackendStateDTO struct {
State health.State `json:"state,omitempty"`
Accepted *Condition `json:"accepted,omitempty"`
Restricted bool `json:"restricted,omitempty"`
}
BackendStateDTO is a Backend's state and Accepted condition, or only Restricted when the caller may not view the Backend (design §7.4 rule 3).
type Candidate ¶
type Candidate struct {
Reason explore.CandidateReason `json:"reason"`
By *LinkedRef `json:"by,omitempty"`
}
Candidate says why an object the install does not own has a detail page. By is the visible owned object that names a referenced candidate.
type Capability ¶
type Capability struct {
Name string `json:"name"`
State CapabilityState `json:"state"`
Reason string `json:"reason,omitempty"`
}
Capability is one named capability and its state; Reason says why it is not on.
type CapabilityState ¶
type CapabilityState string
CapabilityState is whether a capability works for this caller and install.
const ( CapOn CapabilityState = "on" CapOff CapabilityState = "off" CapDenied CapabilityState = "denied" CapFailing CapabilityState = "failing" )
The capability states. Only CapOn also appears in MetaResponse.Capabilities.
type Computed ¶
type Computed struct {
By string `json:"by"`
Rules string `json:"rules"`
Label string `json:"label,omitempty"`
Rule string `json:"rule,omitempty"`
State string `json:"state"`
Coverage []string `json:"coverage,omitempty"`
Reason string `json:"reason,omitempty"`
Note string `json:"note,omitempty"`
}
Computed labels a computed fact with its rule set, rule and check state (design §7.3, rules §8.4). By is always ComputedBy. Reason is the unknown reason; a restricted fact carries no Rule, Reason or Note (design §7.4 rule 4). Label is the rule set's display name, such as "kgateway 2.4".
type Condition ¶
type Condition struct {
Type string `json:"type"`
Status string `json:"status"`
Reason string `json:"reason"`
Message string `json:"message"`
ObservedGeneration int64 `json:"observedGeneration"`
LastTransitionTime time.Time `json:"lastTransitionTime"`
Stale bool `json:"stale"`
}
Condition is a status condition on the wire. Stale marks one whose observedGeneration is below the object's generation (Phase 1 freshness).
type ConflictEvidence ¶
type ConflictEvidence struct {
Others []ConflictListener `json:"others,omitempty"`
// contains filtered or unexported fields
}
ConflictEvidence is KGWUI-017's evidence on the wire: each other listener's owner carries its link.
func (*ConflictEvidence) EvidenceKind ¶
func (*ConflictEvidence) EvidenceKind() string
EvidenceKind implements health.Evidence.
func (*ConflictEvidence) MarshalJSON ¶
func (e *ConflictEvidence) MarshalJSON() ([]byte, error)
MarshalJSON adds the kind tag.
type ConflictListener ¶
type ConflictListener struct {
Owner LinkedRef `json:"owner"`
Name string `json:"name"`
Protocol string `json:"protocol,omitempty"`
Hostname string `json:"hostname,omitempty"`
}
ConflictListener is a health.ConflictingListener whose owner carries its link.
type DataPlaneDTO ¶
type DataPlaneDTO struct {
Rejecting bool `json:"rejecting"`
Rejects []DataPlaneTypes `json:"rejects"`
StatusSaysHealthy bool `json:"statusSaysHealthy"`
Snapshot *SnapshotDTO `json:"snapshot,omitempty"`
NextSteps []NextStep `json:"nextSteps"`
RecentlyChanged []LinkedRef `json:"recentlyChanged"`
EvidenceRestricted bool `json:"evidenceRestricted,omitempty"`
// Unavailable is set while the xDS rejects check is not OK: Rejecting false then means unknown.
ProxyStats ProxyStatsDTO `json:"proxyStats"`
// Withheld is set when the controller log shows the Gateway's proxies may get no config updates (R105).
Withheld *WithheldDTO `json:"withheld,omitempty"`
// ConfigWithheld is set while the Gateway has a KGWUI-024 error: its proxies get no config updates.
ConfigWithheld bool `json:"configWithheld,omitempty"`
// ControllerLogs says whether the install's controller log was read; without it, no withheld means unobserved (D-006).
ControllerLogs string `json:"controllerLogs"`
}
DataPlaneDTO is a Gateway's data plane (design §13.3). Rejecting says a KGWUI-001 is active; its Rejects and RecentlyChanged need every evidence dependency (§14 rule 12), else EvidenceRestricted.
type DataPlaneSummary ¶
type DataPlaneSummary struct {
Gateways int `json:"gateways"`
Rejecting int `json:"rejecting"`
// Withheld counts Gateways with a KGWUI-024 error: their proxies get no config updates.
Withheld int `json:"withheld,omitempty"`
}
DataPlaneSummary counts Gateways with a KGWUI-001 over every finding, beside the visible Gateways and those a rejecting row names; Unavailable is set while the xDS rejects check is not OK.
type DataPlaneTypes ¶
type DataPlaneTypes struct {
TypeURL string `json:"typeUrl"`
Streams int `json:"streams"`
FirstSeen time.Time `json:"firstSeen"`
}
DataPlaneTypes is one rejected xDS type: the rejecting streams and when the UI first saw them.
type DelegationContext ¶
type DelegationContext struct {
Restricted bool `json:"restricted,omitempty"`
ParentMatch *MatchDTO `json:"parentMatch,omitempty"`
Path []PathStepDTO `json:"path,omitempty"`
Outcome string `json:"outcome,omitempty"`
Reason string `json:"reason,omitempty"`
}
DelegationContext is one retained context of a row, or only Restricted when a dependency other than the routes on its path is hidden (design §7.4 rules 4, 4b).
type DelegationObserved ¶
type DelegationObserved struct {
Entry *ParentStatus `json:"entry,omitempty"`
ParentCondition *Condition `json:"parentCondition,omitempty"`
}
DelegationObserved is what the controller wrote for a row: the child's status entry under the row's report key, and the parent's ResolvedRefs condition under one of its reporter keys.
type DelegationRefDTO ¶
type DelegationRefDTO struct {
Mode objects.DelegationMode `json:"mode"`
Namespace string `json:"namespace"`
Name string `json:"name,omitempty"`
Label string `json:"label,omitempty"`
State string `json:"state,omitempty"`
Selected *int `json:"selected,omitempty"`
Attached *int `json:"attached,omitempty"`
Computed *Computed `json:"computed,omitempty"`
}
DelegationRefDTO is a delegation backendRef as classified. Selected and Attached count the visible children of view B's rows (2.4, design §7.4 rule 5); each is nil when the count is not known to the caller. Computed merges the rows' checks worst first (D-023 decision 2, PF14).
type DelegationRow ¶
type DelegationRow struct {
Rule int `json:"rule"`
Ref int `json:"ref"`
RefAsWritten DelegationRefDTO `json:"refAsWritten"`
Child *LinkedRef `json:"child,omitempty"`
Allows string `json:"allows,omitempty"`
Outcome string `json:"outcome,omitempty"`
Reason string `json:"reason,omitempty"`
Contexts []DelegationContext `json:"contexts"`
ContextsTruncated bool `json:"contextsTruncated,omitempty"`
Computed Computed `json:"computed"`
Observed DelegationObserved `json:"observed"`
}
DelegationRow is one view B row of GET …/delegation (design §7.3). Child is absent on a row whose ref selected no route. A restricted row has no Outcome and no Reason (design §7.4 rule 4).
type Diagnostics ¶
type Diagnostics struct {
Install string `json:"install"`
Verdict Verdict `json:"verdict"`
// Groups are the first maxGroups of the GroupTotal ranked groups with a problem.
Groups []GroupRow `json:"groups"`
GroupTotal int `json:"groupTotal"`
Processes ProcessSummaries `json:"processes"`
DataPlane DataPlaneSummary `json:"dataPlane"`
Checks []health.CheckResult `json:"checks"`
CollectedAt time.Time `json:"collectedAt"`
}
Diagnostics is GET …/diagnostics (design §13.3): the verdict, the top groups of "Needs attention" and the process and data-plane summaries.
type EffectiveContext ¶
type EffectiveContext struct {
Restricted bool `json:"restricted,omitempty"`
ParentMatch *MatchDTO `json:"parentMatch,omitempty"`
Rules []EffectiveRuleDTO `json:"rules,omitempty"`
}
EffectiveContext is the route's rules under one parent match, or only Restricted (design §7.4 rule 4).
type EffectiveDTO ¶
type EffectiveDTO struct {
Parent LinkedRef `json:"parent"`
Mode string `json:"mode"`
ContextsTruncated bool `json:"contextsTruncated,omitempty"`
Contexts []EffectiveContext `json:"contexts"`
Computed Computed `json:"computed"`
}
EffectiveDTO is view C for one parent edge of a route (computed-rules §5.7, §6). Contexts is sent as [] when none was kept; ContextsTruncated says contexts were cut.
type EffectiveRuleDTO ¶
type EffectiveRuleDTO struct {
Index int `json:"index"`
Kept bool `json:"kept"`
Matches []MatchDTO `json:"matches"`
Reason string `json:"reason,omitempty"`
}
EffectiveRuleDTO is one rule under a parent match: kept with its effective matches, or dropped with Reason.
type ErrorResponse ¶
type ErrorResponse struct {
Error string `json:"error"`
}
ErrorResponse is the body of every non-2xx API response.
type ExtMount ¶
ExtMount is one extension endpoint (design §4.1 gap 1). Pattern is "[METHOD ]/path" relative to /api/ext/{Name}, so the endpoint never collides with API v1, another extension or the SPA.
type FilterDTO ¶
type FilterDTO struct {
Type string `json:"type"`
ExtensionRef *LinkedRef `json:"extensionRef,omitempty"`
Mirror *MirrorDTO `json:"mirror,omitempty"`
Config map[string]any `json:"config,omitempty"`
}
FilterDTO is one filter in written order; Config is the filter as written.
type FindingDTO ¶
type FindingDTO struct {
health.Finding
Resource *LinkedRef `json:"resource,omitempty"`
EvidenceRestricted bool `json:"evidenceRestricted,omitempty"`
}
FindingDTO is a finding on the wire: its resource carries a link, and EvidenceRestricted marks a detail replaced because it quotes a hidden object.
func (*FindingDTO) UnmarshalJSON ¶
func (d *FindingDTO) UnmarshalJSON(b []byte) error
UnmarshalJSON decodes the typed evidence by its kind, which encoding/json cannot do for the Evidence interface; Go clients decode /health with it.
type FindingDetail ¶
type FindingDetail struct {
Install string `json:"install"`
Finding FindingRow `json:"finding"`
Evidence health.Evidence `json:"evidence,omitempty"`
SuggestedFix *SuggestedFix `json:"suggestedFix,omitempty"`
NextSteps []NextStep `json:"nextSteps,omitempty"`
Affected Page[LinkedRef] `json:"affected"`
CollectedAt time.Time `json:"collectedAt"`
}
FindingDetail is GET …/findings/{findingId}; Affected pages through the visible objects of its group (§14 rule 13). A restricted or evidence-restricted finding has no Evidence (rule 12).
func (*FindingDetail) UnmarshalJSON ¶
func (d *FindingDetail) UnmarshalJSON(b []byte) error
UnmarshalJSON decodes the typed evidence by its kind; Go clients decode a detail with it.
type FindingRow ¶
type FindingRow struct {
ID string `json:"id"`
Code string `json:"code"`
Slug string `json:"slug"`
Severity health.Severity `json:"severity"`
Resource *LinkedRef `json:"resource,omitempty"`
Message string `json:"message,omitempty"`
Detail string `json:"detail,omitempty"`
Since *time.Time `json:"since,omitempty"`
Group string `json:"group,omitempty"`
Restricted bool `json:"restricted,omitempty"`
EvidenceRestricted bool `json:"evidenceRestricted,omitempty"`
}
FindingRow is one finding of GET …/findings (design §13.3); restricted rows keep identity only (§14 rule 11), EvidenceRestricted hides the detail (rule 12). It has no docs link: the SPA builds the docs/findings.md anchor from Code.
type FractionDTO ¶
type FractionDTO struct {
Numerator int32 `json:"numerator"`
Denominator int32 `json:"denominator"`
}
FractionDTO is a mirror fraction; the denominator defaults to 100.
type GatewayDetail ¶
type GatewayDetail struct {
Install string `json:"install"`
Ref LinkedRef `json:"ref"`
Generation int64 `json:"generation"`
Class string `json:"class"`
Health health.State `json:"health"`
Candidate *Candidate `json:"candidate,omitempty"`
RuleSet string `json:"ruleSet,omitempty"`
RuleSetLabel string `json:"ruleSetLabel,omitempty"`
Conditions []Condition `json:"conditions"`
Addresses []string `json:"addresses"`
Listeners []ListenerDTO `json:"listeners"`
AttachedListenerSets *int32 `json:"attachedListenerSets,omitempty"`
ListenerSets int `json:"listenerSets"`
RouteCounts RouteCounts `json:"routeCounts"`
// DataPlane and Proxies are sent for a Gateway the install owns (design §13.1).
DataPlane *DataPlaneDTO `json:"dataPlane,omitempty"`
Proxies *ProcessSetDTO `json:"proxies,omitempty"`
CollectedAt time.Time `json:"collectedAt"`
}
GatewayDetail is GET …/gateways/{ns}/{name}. Its ListenerSets are paged through the ListenerSets list, never embedded; ListenerSets is that list's total for the caller (design §7.4 rule 5).
type GatewayListRow ¶
type GatewayListRow struct {
Ref LinkedRef `json:"ref"`
Class string `json:"class"`
Health health.State `json:"health"`
// Reason is as on RouteRow.
Reason *health.RowReason `json:"reason,omitempty"`
Listeners int `json:"listeners"`
AttachedRoutes int32 `json:"attachedRoutes"`
NotAccepted int `json:"notAccepted"`
// Routes is view A's distinct routes on the Gateway's own listeners,
// hidden ones too; nil when a count is unknown (rule 5).
Routes *int `json:"routes,omitempty"`
ListenerSets int `json:"listenerSets"`
// Disagreements counts the Gateway's checks in state disagrees. Like
// health it is not filtered per caller (rule 9).
Disagreements int `json:"disagreements,omitempty"`
Addresses []string `json:"addresses"`
}
GatewayListRow is one row of the Gateways list (the design's GatewayRow2). AttachedRoutes is the status sum as written; NotAccepted and ListenerSets count visible rows only.
type GatewayProcesses ¶
type GatewayProcesses struct {
Gateway LinkedRef `json:"gateway"`
Health health.State `json:"health"`
Set ProcessSetDTO `json:"set"`
Rejects *int `json:"rejects,omitempty"`
Skew bool `json:"skew,omitempty"`
}
GatewayProcesses is one Gateway's proxies: Health is its worst process or data-plane finding, Rejects its rejecting streams, Skew a proxy on another controller version, patches included (never a finding).
type GrantShape ¶
type GrantShape struct {
FromNamespace string `json:"fromNamespace"`
ToNamespace string `json:"toNamespace"`
ToGroup string `json:"toGroup"`
ToKind string `json:"toKind"`
}
GrantShape is the (from namespace, to namespace, to group and kind) one ReferenceGrant allows; ToGroup is "" for the core group.
type GroupRow ¶
type GroupRow struct {
ID string `json:"id"`
Title string `json:"title"`
Code string `json:"code"`
Severity health.Severity `json:"severity"`
Class diagnose.Class `json:"class"`
Cause *LinkedRef `json:"cause,omitempty"`
Members int `json:"members"`
Affected []LinkedRef `json:"affected"`
AffectedTotal int `json:"affectedTotal"`
Since *time.Time `json:"since,omitempty"`
NextSteps []NextStep `json:"nextSteps,omitempty"`
Restricted bool `json:"restricted,omitempty"`
// Grant is the shape of a "Not permitted" group, which has no cause object (design §5.2).
Grant *GrantShape `json:"grant,omitempty"`
}
GroupRow is one ranked group with its rank keys (design §13.2); Code and Title are its top member's, and a restricted row has no title, affected list, since or steps (§14 rule 13).
type HandlerOption ¶
type HandlerOption func(*handlerConfig)
HandlerOption configures NewHandler.
func WithCapabilitySources ¶
func WithCapabilitySources(f ...func() []Capability) HandlerOption
WithCapabilitySources adds sources of capability states for /api/v1/meta. Each source runs on every /api/v1/meta request, so it must be fast, safe for concurrent use and report a stable set of names.
func WithCommands ¶
func WithCommands(c diagnose.Commands) HandlerOption
WithCommands sets the next-step commands; the default is diagnose.Kubectl.
func WithCoreCapabilities ¶
func WithCoreCapabilities(f func() []Capability) HandlerOption
WithCoreCapabilities sets the source of the core names' states; it runs on every /api/v1/meta request, and any other name it reports is dropped.
func WithExtMounts ¶
func WithExtMounts(m ...ExtMount) HandlerOption
WithExtMounts serves m under /api/ext/{name}/. Callers check them with CheckExtMounts first; NewHandler logs and skips a mount that fails it.
func WithInstallCommands ¶ added in v0.6.0
func WithInstallCommands(f func(install.Install) diagnose.Commands) HandlerOption
WithInstallCommands sets each install's next-step commands, such as its pack's; a nil result keeps WithCommands'.
func WithInstallFeatures ¶ added in v0.6.0
func WithInstallFeatures(f func(install.Install) []string) HandlerOption
WithInstallFeatures sets each install's pack features. The API drops FeatureComputed without a rule set and FeatureDelegation without a Delegator.
func WithInstallKinds ¶ added in v0.6.0
WithInstallKinds reports whether a served kind applies to an install, such as a pack's kind to that pack's installs; overview counts keep only those.
func WithPacks ¶ added in v0.6.0
func WithPacks(names ...string) HandlerOption
WithPacks names the packs this server runs, for MetaResponse.Packs.
type HealthResponse ¶
type HealthResponse struct {
health.Report
Findings []FindingDTO `json:"findings"`
}
HealthResponse is GET …/health. It carries the install ID. Findings shadows the report's, so the change from health.Report is additive.
type HealthSummary ¶
type HealthSummary struct {
State health.State `json:"state"`
Counts map[health.Severity]int `json:"counts"`
}
HealthSummary is the state and per-severity counts.
type InstallSummary ¶
type InstallSummary struct {
ID string `json:"id"`
DisplayName string `json:"displayName"`
Namespace string `json:"namespace,omitempty"`
Name string `json:"name,omitempty"`
Version string `json:"version"`
Edition string `json:"edition"`
ControllerNames []string `json:"controllerNames"`
Readiness overview.Readiness `json:"readiness"`
Scope *overview.ScopeSummary `json:"scope,omitempty"`
Health HealthSummary `json:"health"`
// GroupRows is the number of groups diagnostics lists: the install page
// reserves that many Needs attention rows while diagnostics load.
GroupRows int `json:"groupRows"`
// ComputedAt is when the model behind Health was computed. Clients fall back
// to it when ConfirmedAt is absent.
ComputedAt time.Time `json:"computedAt"`
// ConfirmedAt is when the model was last confirmed to match the cluster
// (D-019); clients apply the stale rule to it.
ConfirmedAt *time.Time `json:"confirmedAt,omitempty"`
// Features are the install's UI features (Feature*); always sent, so an
// absent list means an older server (Phase 5 design §10).
Features []string `json:"features"`
}
InstallSummary is one entry of GET /api/v1/installs. Namespace, Name and Scope are absent where the platform has no such notion (D-016).
type KeyMatchDTO ¶
type KeyMatchDTO struct {
Type string `json:"type"`
Name string `json:"name"`
Value string `json:"value"`
}
KeyMatchDTO is a header or query parameter match after defaults.
type Link ¶
type Link string
Link is how the SPA may open a reference (design §7.1). Clients render it as given and never derive one from a kind.
type ListenerAttachment ¶
type ListenerAttachment struct {
Resource LinkedRef `json:"resource"`
Listener string `json:"listener"`
EffectiveHostnames []string `json:"effectiveHostnames,omitempty"`
Computed Computed `json:"computed"`
}
ListenerAttachment is one listener a parentRef attaches to (view A). EffectiveHostnames is sent only in state checked or disagrees.
type ListenerDTO ¶
type ListenerDTO struct {
Name string `json:"name"`
Port int32 `json:"port,omitempty"`
Protocol string `json:"protocol"`
Hostname string `json:"hostname,omitempty"`
TLS *ListenerTLSDTO `json:"tls,omitempty"`
AllowedRoutes AllowedRoutesDTO `json:"allowedRoutes"`
Status *ListenerStatusDTO `json:"status,omitempty"`
// ComputedRoutes is view A's count, hidden members too; nil when unknown (rule 5).
ComputedRoutes *int `json:"computedRoutes,omitempty"`
Computed *Computed `json:"computed,omitempty"`
// IsolationNote: Envoy may serve fewer hostnames on this listener (rules §4.5).
IsolationNote bool `json:"isolationNote,omitempty"`
}
ListenerDTO is one spec listener with its status block, when there is one.
type ListenerSetDetail ¶
type ListenerSetDetail struct {
Install string `json:"install"`
Ref LinkedRef `json:"ref"`
Generation int64 `json:"generation"`
Health health.State `json:"health"`
Candidate *Candidate `json:"candidate,omitempty"`
RuleSet string `json:"ruleSet,omitempty"`
RuleSetLabel string `json:"ruleSetLabel,omitempty"`
Parent LinkedRef `json:"parent"`
ParentFound bool `json:"parentFound"`
Conditions []Condition `json:"conditions"`
Listeners []ListenerDTO `json:"listeners"`
ExperimentalHint string `json:"experimentalHint,omitempty"`
RouteCounts RouteCounts `json:"routeCounts"`
ParentAllowedListeners *AllowedListenersDTO `json:"parentAllowedListeners,omitempty"`
CollectedAt time.Time `json:"collectedAt"`
}
ListenerSetDetail is GET …/listenersets/{group}/{kind}/{ns}/{name}. ParentFound is false when the parent does not open for the caller (absent, hidden or unadmitted). ParentAllowedListeners is sent only while the ListenerSet's current Accepted condition is False with reason NotAllowed and its parent is found.
type ListenerSetRow ¶
type ListenerSetRow struct {
Ref LinkedRef `json:"ref"`
Parent LinkedRef `json:"parent"`
Health health.State `json:"health"`
// Reason is as on RouteRow.
Reason *health.RowReason `json:"reason,omitempty"`
Listeners int `json:"listeners"`
AcceptedReason string `json:"acceptedReason,omitempty"`
// Routes and Disagreements are as on GatewayListRow.
Routes *int `json:"routes,omitempty"`
Disagreements int `json:"disagreements,omitempty"`
}
ListenerSetRow is one row of the ListenerSets list.
type ListenerStatusDTO ¶
type ListenerStatusDTO struct {
AttachedRoutes int32 `json:"attachedRoutes"`
SupportedKinds []objects.GroupKind `json:"supportedKinds"`
Conditions []Condition `json:"conditions"`
}
ListenerStatusDTO is a listener's status block as written.
type ListenerTLSDTO ¶
type ListenerTLSDTO struct {
Mode string `json:"mode"`
CertificateRefs []LinkedRef `json:"certificateRefs"`
}
ListenerTLSDTO is a listener's TLS block. Certificate refs always link none: Secrets are never read (design §11).
type MatchDTO ¶
type MatchDTO struct {
Path *PathMatchDTO `json:"path,omitempty"`
Headers []KeyMatchDTO `json:"headers,omitempty"`
QueryParams []KeyMatchDTO `json:"queryParams,omitempty"`
Method string `json:"method,omitempty"`
}
MatchDTO is one HTTPRouteMatch after defaults.
type MetaResponse ¶
type MetaResponse struct {
Version string `json:"version"`
Pinned string `json:"pinned,omitempty"`
Synced bool `json:"synced"`
// Platform names the platform for display, for example "Kubernetes".
Platform string `json:"platform"`
// Capabilities are what the platform offers (platform.Scope,
// platform.Workloads). Clients branch on these, never on Platform.
Capabilities []string `json:"capabilities"`
// CapabilityStates lists the core and extension capabilities with their state, by name.
// Those that are on are also in Capabilities.
CapabilityStates []Capability `json:"capabilityStates,omitempty"`
// Kinds are the kinds the resource endpoint can serve: the served kinds,
// plus apps/Deployment under the workloads capability. The frontend links only these.
Kinds []kinds.Served `json:"kinds"`
// Views are the group/kinds with a detail view; informational only.
Views []objects.GroupKind `json:"views,omitempty"`
// Packs names the implementation packs this server runs, such as
// "kgateway"; always sent, so an absent list means an older server.
Packs []string `json:"packs"`
// Filters lists, per list, the filters added after v1, so a client sends
// one only when this backend applies it (design §7.2).
Filters map[string][]string `json:"filters,omitempty"`
}
MetaResponse is GET /api/v1/meta.
type MirrorDTO ¶
type MirrorDTO struct {
BackendRef LinkedRef `json:"backendRef"`
Port int32 `json:"port,omitempty"`
Percent *int32 `json:"percent,omitempty"`
Fraction *FractionDTO `json:"fraction,omitempty"`
}
MirrorDTO is a RequestMirror filter's target. Port is omitted when absent.
type ModelSource ¶
ModelSource provides the current publication and the platform it is computed for.
type NextStep ¶
type NextStep struct {
Title string `json:"title"`
Command string `json:"command"`
Needs []string `json:"needs,omitempty"`
Note string `json:"note,omitempty"`
}
NextStep is one command a user can run to learn more. Needs names the permissions it requires, for example "pods/log".
type OverviewGatewayRow ¶
type OverviewGatewayRow struct {
overview.GatewayRow
Link Link `json:"link,omitempty"`
DataPlane string `json:"dataPlane,omitempty"`
}
OverviewGatewayRow is an overview Gateway row with its link and its Data plane column (design §6).
type OverviewResponse ¶
type OverviewResponse struct {
overview.Overview
Gateways []OverviewGatewayRow `json:"gateways"`
CollectedAt time.Time `json:"collectedAt"`
}
OverviewResponse is GET …/overview. Gateways shadows the overview's rows, so adding their link is additive on the wire.
type Page ¶
type Page[T any] struct { Install string `json:"install"` Items []T `json:"items"` Total int `json:"total"` Next string `json:"next,omitempty"` Prev string `json:"prev,omitempty"` DeniedInInstall int `json:"deniedInInstall,omitempty"` CollectedAt time.Time `json:"collectedAt"` }
Page is one page of a list (design §7.3). Total counts the visible rows that match; DeniedInInstall is the unfiltered number of the install's rows of the listed kinds the caller may not view (design §7.4 rule 2).
type ParentStatus ¶
type ParentStatus struct {
ParentRef objects.ParentRef `json:"parentRef"`
Target LinkedRef `json:"target"`
ControllerName string `json:"controllerName"`
Ours bool `json:"ours"`
Conditions []Condition `json:"conditions"`
}
ParentStatus is one status.parents entry of a route. Ours marks an entry written by one of the install's controllers.
type ParentSummary ¶
type ParentSummary struct {
Ref LinkedRef `json:"ref"`
SectionName string `json:"sectionName,omitempty"`
Port int32 `json:"port,omitempty"`
Via *LinkedRef `json:"via,omitempty"`
ViaRestricted bool `json:"viaRestricted,omitempty"`
Attachment explore.Attachment `json:"attachment"`
ConditionType string `json:"conditionType,omitempty"`
Reason string `json:"reason,omitempty"`
Message string `json:"message,omitempty"`
// Computed is view A's outcome for this parentRef (2.3); nil when none was computed.
Computed *Attachment `json:"computed,omitempty"`
}
ParentSummary is one parent of a route row, from status. Via is the Gateway of a ListenerSet parent; ViaRestricted replaces it when the caller may not view that Gateway. ConditionType, Reason and Message are the deciding condition; a pending parent has only Reason, the pending reason.
type PathMatchDTO ¶
PathMatchDTO is a path match after defaults.
type PathStepDTO ¶
PathStepDTO is a route on a context's path and the match it delegated under. A hidden ancestor has link none and nothing else (D-024).
type ProcessDTO ¶
type ProcessDTO struct {
Name string `json:"name"`
Ready *bool `json:"ready,omitempty"`
Restarts *int32 `json:"restarts,omitempty"`
RestartsRecent *int32 `json:"restartsRecent,omitempty"`
LastStart *time.Time `json:"lastStart,omitempty"`
Termination *health.TerminationFacts `json:"termination,omitempty"`
Waiting string `json:"waiting,omitempty"`
Version string `json:"version,omitempty"`
Probe *health.ProbeFacts `json:"probe,omitempty"`
}
ProcessDTO is one replica or proxy; an absent field was not observed. RestartsRecent are the restarts its KGWUI-019 counts in the window.
type ProcessSetDTO ¶
type ProcessSetDTO struct {
Observed bool `json:"observed"`
Desired *int32 `json:"desired,omitempty"`
Ready *int32 `json:"ready,omitempty"`
Processes []ProcessDTO `json:"processes"`
Rollout *RolloutDTO `json:"rollout,omitempty"`
Restricted bool `json:"restricted,omitempty"`
}
ProcessSetDTO is the processes behind one role; Observed false is "not observed", never failing. Processes lists the Pods the caller may view; Restricted keeps the counts only (§14 rule 16).
type ProcessSummaries ¶
type ProcessSummaries struct {
Controller ProcessSummary `json:"controller"`
Proxies ProxySummary `json:"proxies"`
}
ProcessSummaries are the Processes lines of the overview (design §6).
type ProcessSummary ¶
type ProcessSummary struct {
State health.State `json:"state"`
Observed bool `json:"observed"`
Ready *int32 `json:"ready,omitempty"`
Desired *int32 `json:"desired,omitempty"`
// Version is the version every visible replica runs; empty when they differ.
Version string `json:"version,omitempty"`
Restricted bool `json:"restricted,omitempty"`
}
ProcessSummary is the controller line. State is the worst controller finding, unknown when not observed and none fired; Restricted keeps the counts and state only (§14 rule 16).
type ProcessesResponse ¶
type ProcessesResponse struct {
Install string `json:"install"`
Controller ProcessSetDTO `json:"controller"`
Proxies Page[GatewayProcesses] `json:"proxies"`
CollectedAt time.Time `json:"collectedAt"`
}
ProcessesResponse is GET …/processes: the controller's processes and a page of the Gateways' proxy processes (design §13.1).
type ProxyStatsDTO ¶
type ProxyStatsDTO struct {
Available bool `json:"available"`
Reason string `json:"reason,omitempty"`
}
ProxyStatsDTO says whether proxy stats feed a Gateway; Unavailable and Reason say why not (D-034).
type ProxySummary ¶
type ProxySummary struct {
State health.State `json:"state"`
Gateways int `json:"gateways"`
Ready int `json:"ready"`
Rejecting int `json:"rejecting"`
Skew int `json:"skew"`
Restarting int `json:"restarting"`
NotObserved int `json:"notObserved"`
}
ProxySummary counts the visible Gateways: those with every proxy ready, with a reject, with version skew, with a restart, and whose proxies are not observed. State is the worst known health of those Gateways; unknown when none is known.
type RolloutDTO ¶
type RolloutDTO struct {
Progressing bool `json:"progressing"`
Reason string `json:"reason,omitempty"`
}
RolloutDTO is a workload's last rollout; Reason is a stuck one's.
type RouteAnnotations ¶
type RouteAnnotations struct {
InheritParentMatcher *bool `json:"inheritParentMatcher,omitempty"`
}
RouteAnnotations are the route annotations the UI reads. A nil field is an absent annotation.
type RouteAttachment ¶
type RouteAttachment struct {
ParentRef objects.ParentRef `json:"parentRef"`
Index int `json:"index"`
Target LinkedRef `json:"target"`
Result Attachment `json:"result"`
}
RouteAttachment is view A for one Gateway or ListenerSet parentRef of a route, by its index in spec.parentRefs.
type RouteCounts ¶
type RouteCounts struct {
Accepted int `json:"accepted"`
NotAccepted int `json:"notAccepted"`
Pending int `json:"pending"`
Unwatched int `json:"unwatched"`
}
RouteCounts counts the visible routes under a parent per attachment, as the routes list with that parent and attachment totals them.
type RouteDetail ¶
type RouteDetail struct {
Install string `json:"install"`
Ref LinkedRef `json:"ref"`
Generation int64 `json:"generation"`
Health health.State `json:"health"`
Candidate *Candidate `json:"candidate,omitempty"`
RuleSet string `json:"ruleSet,omitempty"`
RuleSetLabel string `json:"ruleSetLabel,omitempty"`
Hostnames []string `json:"hostnames"`
Annotations RouteAnnotations `json:"annotations"`
ParentRefs []SpecParentRef `json:"parentRefs"`
Parents []ParentStatus `json:"parents"`
Attachments []RouteAttachment `json:"attachments,omitempty"`
Rules []RuleDTO `json:"rules"`
Effective []EffectiveDTO `json:"effective,omitempty"`
EffectiveTruncated bool `json:"effectiveTruncated,omitempty"`
Ancestors []AncestorPathDTO `json:"ancestors"`
AncestorsTruncated bool `json:"ancestorsTruncated"`
ChildCount int `json:"childCount"`
DeclaredCount int `json:"declaredCount"`
CollectedAt time.Time `json:"collectedAt"`
}
RouteDetail is GET …/routes/{group}/{kind}/{ns}/{name}, HTTPRoute only. ChildCount and DeclaredCount count visible routes only. Effective is view C per parent edge (2.4); EffectiveTruncated says the route had more parent edges than were kept.
type RouteNamespacesDTO ¶
type RouteNamespacesDTO struct {
From string `json:"from"`
Selector *metav1.LabelSelector `json:"selector,omitempty"`
}
RouteNamespacesDTO is allowedRoutes.namespaces.
type RouteRow ¶
type RouteRow struct {
Ref LinkedRef `json:"ref"`
Hostnames []string `json:"hostnames"`
Parents []ParentSummary `json:"parents"`
ParentRoutes []LinkedRef `json:"parentRoutes"`
Children int `json:"children"`
Flags []string `json:"flags"`
Health health.State `json:"health"`
// Reason says why Health is not healthy (D-063).
Reason *health.RowReason `json:"reason,omitempty"`
Mirror bool `json:"mirror,omitempty"`
}
RouteRow is one row of the routes list. Mirror is set only under a backend filter, when every matched use of the row is a RequestMirror.
type RuleDTO ¶
type RuleDTO struct {
Index int `json:"index"`
Name string `json:"name,omitempty"`
Matches []MatchDTO `json:"matches"`
Filters []FilterDTO `json:"filters"`
BackendRefs []BackendRefDTO `json:"backendRefs"`
}
RuleDTO is one spec rule. Omitted matches carry the CRD default, one PathPrefix "/" match. An explicit empty list stays [] as written; kgateway treats it as match-all (or, for an inheriting child, the parent's match), so clients must not render it as "matches nothing".
type RuleEvidence ¶
type RuleEvidence struct {
Policy *LinkedRef `json:"policy,omitempty"`
// contains filtered or unexported fields
}
RuleEvidence is KGWUI-015's evidence on the wire: the policy carries its link.
func (*RuleEvidence) EvidenceKind ¶
func (*RuleEvidence) EvidenceKind() string
EvidenceKind implements health.Evidence.
func (*RuleEvidence) MarshalJSON ¶
func (e *RuleEvidence) MarshalJSON() ([]byte, error)
MarshalJSON adds the kind tag.
type SnapshotDTO ¶
type SnapshotDTO struct {
By string `json:"by"`
Listeners int `json:"listeners"`
Routes int `json:"routes"`
Clusters int `json:"clusters"`
Endpoints int `json:"endpoints"`
Secrets int `json:"secrets"`
}
SnapshotDTO is kgateway_xds_snapshot_resources for one Gateway. By is always "controller": what it built, not what proxies accepted; never a finding.
type SpecParentRef ¶
SpecParentRef is a spec parentRef with its target's link, so a parent without a status entry still links through admission (design §7.1).
type SuggestedFix ¶
type SuggestedFix struct {
Title string `json:"title"`
Target LinkedRef `json:"target"`
Create bool `json:"create"`
Path string `json:"path,omitempty"`
YAML string `json:"yaml"`
Basis string `json:"basis"`
}
SuggestedFix is the one change the evidence leaves (design §7.7). Path is the fragment's location when Create is false.
type Verdict ¶
type Verdict struct {
State health.State `json:"state"`
Problems int `json:"problems"`
Counts map[health.Severity]int `json:"counts"`
OldestSince *time.Time `json:"oldestSince,omitempty"`
Reason string `json:"reason,omitempty"`
}
Verdict is the install's state over every finding (§14 rule 18); Reason names the required check that made it unknown, and OldestSince is the oldest since the caller may see.
type WithheldDTO ¶
type WithheldDTO struct {
Message string `json:"message"`
First time.Time `json:"first"`
Last time.Time `json:"last"`
}
WithheldDTO is the snapshot deferral that recurred after the proxies connected: the first and last such line (kgateway 2.3 and 2.4).
type XDSEvidence ¶
type XDSEvidence struct {
RecentlyChanged []LinkedRef `json:"recentlyChanged,omitempty"`
// contains filtered or unexported fields
}
XDSEvidence is KGWUI-001's evidence on the wire: recently changed objects are those the caller may view, each with its link (§14 rule 14).
func (*XDSEvidence) EvidenceKind ¶
func (*XDSEvidence) EvidenceKind() string
EvidenceKind implements health.Evidence.
func (*XDSEvidence) MarshalJSON ¶
func (e *XDSEvidence) MarshalJSON() ([]byte, error)
MarshalJSON adds the kind tag.