api

package
v0.5.0 Latest Latest
Warning

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

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

Documentation

Overview

Package api serves the read-only JSON API (design §7), the probes and the SPA.

Index

Constants

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

View Source
const (
	DelegationReported    = "reported"
	DelegationNotReported = "not-reported"
	DelegationNotFound    = "not-found"
	DelegationRestricted  = "restricted"
)

Delegation ref states (design §7.3), status-based, for name refs only.

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

func CheckExtMounts(m ...ExtMount) error

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

func CheckExtName(name string) error

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.

func (AllowAll) Authorize

func (AllowAll) Authorize(*http.Request, objects.Ref) bool

Authorize implements Authorizer.

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

type AuthorizerFunc func(r *http.Request, ref objects.Ref) bool

AuthorizerFunc adapts a function to Authorizer.

func (AuthorizerFunc) Authorize

func (f AuthorizerFunc) Authorize(r *http.Request, ref objects.Ref) bool

Authorize implements 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"`
	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).

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.
	Unavailable bool          `json:"unavailable,omitempty"`
	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"`
	Unavailable bool `json:"unavailable,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

type ExtMount struct {
	Name, Pattern string
	Handler       http.Handler
}

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"`
	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.

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"`
}

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 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.

const (
	// LinkDetail: admitted, and its kind has a detail view.
	LinkDetail Link = "detail"
	// LinkYAML: admitted without a detail view, or a no-parent row.
	LinkYAML Link = "yaml"
	// LinkNone: denied, absent, never served or not admitted (D-013).
	LinkNone Link = "none"
)

Links.

type LinkedRef

type LinkedRef struct {
	objects.Ref
	Link Link `json:"link"`
}

LinkedRef is a reference with its link.

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"`
	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"`
	// 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

type ModelSource interface {
	Current() *engine.Published
	Platform() platform.Info
}

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

type PathMatchDTO struct {
	Type  string `json:"type"`
	Value string `json:"value"`
}

PathMatchDTO is a path match after defaults.

type PathStepDTO

type PathStepDTO struct {
	Ref   LinkedRef `json:"ref"`
	Match MatchDTO  `json:"match"`
}

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"`
	Unavailable health.Availability `json:"unavailable,omitempty"`
	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"`
	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

type SpecParentRef struct {
	objects.ParentRef
	Target LinkedRef `json:"target"`
}

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 TrailRefs

type TrailRefs struct {
	Install string      `json:"install"`
	Refs    []LinkedRef `json:"refs"`
}

TrailRefs is GET …/refs: each requested ref with its link, in request order.

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.

Jump to

Keyboard shortcuts

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