Documentation
¶
Overview ¶
Package api serves the read-only JSON API (design §7), the probes and the SPA.
Index ¶
- Constants
- Variables
- func CheckCapabilities(platformNames []string, sources ...func() []Capability) error
- func CheckExtMounts(m ...ExtMount) error
- func CheckExtName(name string) error
- func HostGuard(allowed []string, next http.Handler) http.Handler
- func NewHandler(src ModelSource, ui fs.FS, authz Authorizer, opts ...HandlerOption) http.Handler
- func NoteAllow(r *http.Request, expires time.Time)
- func ProbeHandler(ready Ready, reg *obs.Registry) http.Handler
- func ReportAuthzError(r *http.Request, err error)
- func SpendCheck(r *http.Request) error
- func SpendCheckOn(r *http.Request, reason string, key any) error
- func Visible[T any](r *http.Request, a Authorizer, items []T, ref func(T) objects.Ref) (visible []T, hidden int)
- func VisibleTo[T any](v Viewer, items []T, ref func(T) objects.Ref) []T
- func WriteError(w http.ResponseWriter, code int, msg string)
- func WriteJSON(w http.ResponseWriter, v any)
- type Admitter
- type AllowAll
- type AllowedListenersDTO
- type AllowedRoutesDTO
- type AncestorPathDTO
- type AncestorStepDTO
- type Attachment
- type AuditEvent
- type AuditKind
- type Authorizer
- type AuthorizerFunc
- type BackendDetail
- type BackendFacetsDTO
- type BackendGatewayFacetDTO
- type BackendNamespaceFacetDTO
- type BackendRefDTO
- type BackendRowDTO
- type BackendStateDTO
- type BackendsResponse
- type BatchAuthorizer
- type Candidate
- type Capability
- type CapabilityState
- type Computed
- type Condition
- type ConflictEvidence
- type ConflictListener
- type ConsumerDTO
- type DataPlaneDTO
- type DataPlaneSummary
- type DataPlaneTypes
- type DelegationContext
- type DelegationObserved
- type DelegationRefDTO
- type DelegationRow
- type DenyAll
- type DetailReason
- type Diagnostics
- type EffectiveContext
- type EffectiveDTO
- type EffectiveRuleDTO
- type EndpointDTO
- type EndpointsDTO
- type ErrAuthorizer
- type ErrorResponse
- type ExtMount
- type FilterDTO
- type FindingDTO
- type FindingDetail
- type FindingRow
- type FractionDTO
- type FullReader
- type GRPCMatchDTO
- type GRPCMethodDTO
- type GatewayDetail
- type GatewayFacetDTO
- type GatewayListRow
- type GatewayProcesses
- type GrantShape
- type GroupRow
- type HandlerOption
- func WithAuthzAudit(audit func(r *http.Request, reason string)) HandlerOption
- func WithBackendConsumers(f func(install.Install, *install.Owned) []objects.Consumer) HandlerOption
- func WithCapabilitySources(f ...func() []Capability) HandlerOption
- func WithCheckCapHit(hit func(r *http.Request)) HandlerOption
- func WithCheckTrace(trace func(r *http.Request, build int, reason string, key any)) HandlerOption
- func WithCommands(c diagnose.Commands) HandlerOption
- func WithCommitCheck(check func(w http.ResponseWriter, r *http.Request) (*http.Request, error)) HandlerOption
- func WithCommitClock(now func() time.Time) 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
- func WithRequestAudit(hear func(AuditEvent), disclosure bool) HandlerOption
- func WithScopedReader(r endpoints.ScopedReader) HandlerOption
- func WithSecureMode() HandlerOption
- func WithSessionGate(gate func(http.Handler) http.Handler) HandlerOption
- type HealthResponse
- type HealthSummary
- type InstallSummary
- type KeyMatchDTO
- type Link
- type LinkedRef
- type ListAuthorizer
- type ListQuery
- type ListScanner
- type ListenerAttachment
- type ListenerDTO
- type ListenerSetDetail
- type ListenerSetRow
- type ListenerStatusDTO
- type ListenerTLSDTO
- type MatchDTO
- type MetaResponse
- type MirrorDTO
- type ModelSource
- type NamedAuthorizer
- type NamespaceFacetDTO
- type NamespacesResponse
- type Narrowed
- type NextStep
- type OverviewGatewayRow
- type OverviewResponse
- type Page
- type ParentStatus
- type ParentSummary
- type PathCountsDTO
- type PathFacetsDTO
- type PathListenerDTO
- type PathMatchDTO
- type PathRowDTO
- type PathSignal
- type PathStepDTO
- type PathSummaryDTO
- type PathsResponse
- type PortChainDTO
- type PortDTO
- type ProblemDTO
- type ProcessDTO
- type ProcessSetDTO
- type ProcessSummaries
- type ProcessSummary
- type ProcessesResponse
- type ProxyStatsDTO
- type ProxySummary
- type Ready
- type RefExplanationDTO
- type RolloutDTO
- type RouteAnnotations
- type RouteAttachment
- type RouteCounts
- type RouteDetail
- type RouteNamespacesDTO
- type RouteReason
- type RouteRow
- type RouteSignal
- type RuleDTO
- type RuleEvidence
- type RuntimeDTO
- type ServiceFactDTO
- type SignalDTO
- type SnapshotDTO
- type SpecParentRef
- type SuggestedFix
- type TraceAttachmentDTO
- type TrailRefs
- type Verdict
- type Viewer
- type WithheldDTO
- type XDSEvidence
Constants ¶
const ( // MissAbsent is a check with no cached answer: never asked, or evicted. MissAbsent = "absent" // MissAllowExpired and MissDenyExpired are checks whose cached allow or deny expired. MissAllowExpired = "allow-expired" MissDenyExpired = "deny-expired" )
Why an uncached check missed the cache, as an authoriser passes it to SpendCheckOn.
const ( AuditCheckFailed = "check-failed" AuditCheckLimit = "check-limit" AuditFullReadFailed = "full-read-failed" AuditExpired = "expired" AuditIdentity = "identity-stale" // AuditQueueFull is a request refused because too many were waiting for admission (D-116). AuditQueueFull = "queue-full" )
Reasons the commit wrapper passes to the WithAuthzAudit hook.
const ( RefAttributed = "attributed" RefCandidate = "candidate" RefWaiting = "waiting" )
Kinds of a reference explanation (design §10).
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 ( ActionBackend = "backend" ActionRedirect = "redirect" ActionDirectResponse = "direct-response" ActionNone = "none" ActionDelegate = "delegate" )
Path row actions (design §4.1): what a row's rule does with a request. A delegation row is the parent's rule handing requests to child routes.
const ( NoteUnknown = "unknown" NoteUnconfirmable = "unconfirmable" NoteNotComputed = "not-computed" )
Path row notes: a view C state that leaves the row's outcome open (design §4.2).
const CheckLimit = 1000
CheckLimit is the most uncached authorisation checks one request may make (design §6.4, R25). The global limiter protects the API server; this bounds one request's spend.
const ComputedBy = "ui"
ComputedBy marks a fact the UI computed (D-020).
const EndpointsSourceKubernetes = "kubernetes"
EndpointsSourceKubernetes is the endpoints source read from the cluster's EndpointSlices.
const MaxRequestBody = 1 << 20
MaxRequestBody bounds the body of a secure /api/ request other than GET or HEAD, which commit reads in full before admission; a larger one answers 413.
const NotComputedNoAttachments = "no-attachments"
NotComputedNoAttachments says the install has no computed views, so no path is derived.
Variables ¶
var ErrBusy = errors.New("authorisation: too many requests waiting for admission")
ErrBusy is an Admit error for a request refused because too many are waiting; the commit wrapper answers 503 authz-busy (D-116).
var ErrCheckLimit = errors.New("authorisation check limit reached")
ErrCheckLimit is the error of a request that needs more uncached checks than CheckLimit.
var ErrNotAdmitted = errors.New("authorisation: request not admitted")
ErrNotAdmitted is the error of an uncached check made before its request was admitted; the commit wrapper admits the request and builds it again (D-116).
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 HostGuard ¶ added in v0.8.0
HostGuard serves only requests whose Host is localhost, 127.0.0.1, [::1] (any port) or one of allowed (any port); others get 421. A request with an Origin that is not its own http(s) origin gets 403. It never sets CORS headers.
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), except in secure mode, where it means DenyAll. Options add extension endpoints. In secure mode every /api/ response goes through the commit wrapper (commit.go).
func NoteAllow ¶ added in v0.8.0
NoteAllow records that r's request used an allow valid until expires; the commit wrapper rebuilds a response whose earliest allow expired (D-100). Denials are not noted: a stale denial only hides. It is a no-op outside a committed request.
func ProbeHandler ¶ added in v0.8.0
ProbeHandler serves /healthz, /readyz and /metrics, and nothing else.
func ReportAuthzError ¶ added in v0.8.0
ReportAuthzError records the first authorisation error of r's request. It is a no-op outside a committed request.
func SpendCheck ¶ added in v0.8.0
SpendCheck counts one uncached check for r's request and returns ErrCheckLimit past the limit, or ErrNotAdmitted, counting nothing, before the request is admitted. It is nil outside a committed request.
func SpendCheckOn ¶ added in v0.8.0
SpendCheckOn is SpendCheck for a check the authoriser names by key, which missed for reason (a Miss constant); WithCheckTrace hears each counted one.
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 full read, it makes no calls and returns items, clipped so an append cannot alias it. A nil a is AllowAll, or DenyAll in secure mode. An ErrAuthorizer's error is recorded for the request and hides the ref; the API then answers 503. In secure mode hidden is always 0 (D-085); Deps.View with VisibleTo is the secure-mode form.
func VisibleTo ¶ added in v0.8.0
VisibleTo returns the items whose ref v may see as population members, in order. It sends no hidden count: in secure mode a hidden object leaves no trace (D-085). Its input must not depend on hidden objects: for Install.Owned.Backends use Viewer.Backends.
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 Admitter ¶ added in v0.8.0
type Admitter interface {
// Admit waits under r's context for admission and returns its release, or why it could not admit.
Admit(r *http.Request) (release func(), err error)
}
Admitter admits requests that need uncached checks a few at a time (D-116). The commit wrapper first builds a GET or HEAD without admission; a build that meets an uncached check is discarded, and the request waits in Admit and is built afresh. Other methods are admitted first. A request holds its admission until its response is final, not while it is written.
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 AuditEvent ¶ added in v0.8.0
type AuditEvent struct {
// Request is the request as its route saw it; Pattern is the route template, empty when no route ran.
Request *http.Request
// Route is the route template the path matches, or "unmatched"; never the path itself.
Route string
// Status is the answer's HTTP status.
Status int
Kind AuditKind
// Install is the install the path names, or empty.
Install string
// Subject is the object a read names: the path's object, or a finding's resource; nil for other routes.
Subject *objects.Ref
// Denied is set when the Authorizer refused Subject by name and the read answered 404.
Denied bool
// Filters are the filters a list's endpoint takes, each with its well-formed values joined by commas.
Filters map[string]string
// Returned are the typed object references in a successful response, with Subject; set only with disclosure.
Returned []objects.Ref
}
AuditEvent is what the API knows about one answered /api/ request.
type AuditKind ¶ added in v0.8.0
type AuditKind uint8
AuditKind is how the audit stream treats an /api/ route (design §9.2).
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 BackendDetail ¶ added in v0.7.0
type BackendDetail struct {
Install string `json:"install"`
Ref LinkedRef `json:"ref"`
Kind string `json:"kind"`
Type string `json:"type,omitempty"`
Problem ProblemDTO `json:"problem"`
Status []SignalDTO `json:"status"`
Exposure PathsResponse `json:"exposure"`
Consumers []ConsumerDTO `json:"consumers"`
Sources []EndpointsDTO `json:"sources"`
PortChain []PortChainDTO `json:"portChain"`
Explanations []RefExplanationDTO `json:"explanations"`
Service *ServiceFactDTO `json:"service,omitempty"`
Conditions []Condition `json:"conditions,omitempty"`
// DelegationNotChecked says the caller gets no paths through parent routes (D-114).
DelegationNotChecked bool `json:"delegationNotChecked,omitempty"`
CollectedAt time.Time `json:"collectedAt"`
}
BackendDetail is GET …/backends/{group}/{kind}/{ns}/{name} (design §8.2). Status is the backend's own signals, which the status line phrases; Problem also covers its paths. Exposure is the first page of its paths. Sources has one kubernetes entry per referenced Service port, with the scoped read's endpoints when it has them. Service holds a Service's cached facts and Conditions a Backend's.
type BackendFacetsDTO ¶ added in v0.7.0
type BackendFacetsDTO struct {
Gateways []BackendGatewayFacetDTO `json:"gateways"`
Namespaces []BackendNamespaceFacetDTO `json:"namespaces"`
}
BackendFacetsDTO lists the gateway and namespace filter values, sorted by name.
type BackendGatewayFacetDTO ¶ added in v0.7.0
BackendGatewayFacetDTO is a Gateway and the backends it has a visible path to.
type BackendNamespaceFacetDTO ¶ added in v0.7.0
BackendNamespaceFacetDTO is a namespace and the backends in it.
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"`
Problem *ProblemDTO `json:"problem,omitempty"`
Endpoints *EndpointsDTO `json:"endpoints,omitempty"`
}
BackendRefDTO is one rule backendRef. An absent weight is 1 with WeightDefaulted; an absent port is omitted. Share, ShareState, Problem and Endpoints come from the ref's visible paths, absent without one: Problem is the worst across the route's attachments.
type BackendRowDTO ¶ added in v0.7.0
type BackendRowDTO struct {
Ref LinkedRef `json:"ref"`
Kind string `json:"kind"`
Endpoints []EndpointsDTO `json:"endpoints"`
Routes int `json:"routes"`
Gateways int `json:"gateways"`
Consumers int `json:"consumers"`
Confirmed int `json:"confirmed"`
Problem ProblemDTO `json:"problem"`
}
BackendRowDTO is one backend of the Backends list (design §8.1). Kind is "Service", "Backend · <spec.type>" or the ref's kind. Endpoints has one entry per referenced Service port, or one not-applicable entry for a Backend. Routes, Gateways and Consumers count what the caller may see; Confirmed counts its paths on an attachment the route's status accepts.
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 BackendsResponse ¶ added in v0.7.0
type BackendsResponse struct {
Install string `json:"install"`
Rows []BackendRowDTO `json:"rows"`
Next string `json:"next,omitempty"`
Prev string `json:"prev,omitempty"`
Hidden bool `json:"hidden,omitempty"`
// Facets are the Gateways and namespaces of the visible backends, each
// counted with every filter but its own.
Facets *BackendFacetsDTO `json:"facets,omitempty"`
// DelegationNotChecked says the caller gets no paths through parent routes (D-114).
DelegationNotChecked bool `json:"delegationNotChecked,omitempty"`
CollectedAt time.Time `json:"collectedAt"`
}
BackendsResponse is GET …/backends. Hidden says a backend, path, route or consumer was left out for the caller (design §13); secure mode never sets it, since the permissions note replaces it (design §7.5).
type BatchAuthorizer ¶ added in v0.8.0
type BatchAuthorizer interface {
// ResolveLists answers qs in order, or why it could not tell.
ResolveLists(r *http.Request, qs []ListQuery) ([]bool, error)
}
BatchAuthorizer resolves many population list questions at once, in parallel, before a handler renders (D-100 item 6). Each answer is the list half of ErrAuthorizer's: a namespaced kind without a namespace is false.
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 ConsumerDTO ¶ added in v0.7.0
type ConsumerDTO struct {
Consumer LinkedRef `json:"consumer"`
Role string `json:"role"`
Field string `json:"field"`
Port int `json:"port,omitempty"`
}
ConsumerDTO is a non-route object that uses the backend (design §8.3): its role, such as ext-auth, the JSON path of its reference and the port written there.
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. A viewer without the full read in secure mode gets no data plane: every fact in it is derived.
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 DenyAll ¶ added in v0.8.0
type DenyAll struct{}
DenyAll denies every ref; secure mode uses it until a real authoriser is wired.
type DetailReason ¶ added in v0.7.1
type DetailReason struct {
health.RowReason
Finding string `json:"finding,omitempty"`
Backend *LinkedRef `json:"backend,omitempty"`
}
DetailReason is a detail page's reason: the list row's (D-063) plus, for kind finding, the deciding finding's id, so the page can open it. Backend is as on RouteReason.
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 EndpointDTO ¶ added in v0.7.0
type EndpointDTO struct {
Address string `json:"address"`
Port int32 `json:"port,omitempty"`
Ready bool `json:"ready"`
Serving bool `json:"serving"`
Terminating bool `json:"terminating"`
Pod string `json:"pod,omitempty"`
}
EndpointDTO is one endpoint of a backend detail read (design §9.3).
type EndpointsDTO ¶ added in v0.7.0
type EndpointsDTO struct {
Source string `json:"source"`
Port *PortDTO `json:"port,omitempty"`
Runtime *RuntimeDTO `json:"runtime,omitempty"`
// ReadAt is meaningless when Complete is not-applicable or not-permitted: nothing was read.
ReadAt time.Time `json:"readAt"`
// Complete is complete, partial, failed, unavailable, stale, not-applicable
// or not-permitted (the caller may not list the Service's EndpointSlices);
// a backend detail's scoped read may also be timed-out or busy.
Complete string `json:"complete"`
// Ready and Total are absent unless the read establishes a count.
Ready *int `json:"ready,omitempty"`
Total *int `json:"total,omitempty"`
Items []EndpointDTO `json:"items,omitempty"`
// CachedReady is the cache's ready count, set only when a complete read
// finds none ready while the cache counts some: the two sources disagree.
CachedReady *int `json:"cachedReady,omitempty"`
}
EndpointsDTO is one backend port's endpoints from one source (design §9.5).
type ErrAuthorizer ¶ added in v0.8.0
type ErrAuthorizer interface {
// AuthorizeErr reports whether the caller of r may view ref, or why it could not tell.
AuthorizeErr(r *http.Request, ref objects.Ref) (bool, error)
}
ErrAuthorizer can say that it could not decide (design §6.3). The API then answers 503 "authz-unavailable" instead of an empty or partial view.
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 FullReader ¶ added in v0.8.0
type FullReader interface {
// FullRead reports whether the caller of r reads everything, or why it could not tell.
FullRead(r *http.Request) (bool, error)
}
FullReader answers the full-read fast path (design §6.4): whether the caller may list every served kind cluster-wide and so sees the allow-all view.
type GRPCMatchDTO ¶ added in v0.7.0
type GRPCMatchDTO struct {
Method *GRPCMethodDTO `json:"method,omitempty"`
Headers []KeyMatchDTO `json:"headers,omitempty"`
}
GRPCMatchDTO is one GRPCRouteMatch as written.
type GRPCMethodDTO ¶ added in v0.7.0
type GRPCMethodDTO struct {
Type string `json:"type,omitempty"`
Service string `json:"service,omitempty"`
Method string `json:"method,omitempty"`
}
GRPCMethodDTO is a GRPCRoute method match as written.
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"`
Reason *DetailReason `json:"reason,omitempty"`
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 GatewayFacetDTO ¶ added in v0.7.0
GatewayFacetDTO is a Gateway and the paths through it.
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"`
NotAssessed bool `json:"notAssessed,omitempty"`
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). NotAssessed is as on ProcessSummary: Health is then unknown.
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 WithAuthzAudit ¶ added in v0.8.0
func WithAuthzAudit(audit func(r *http.Request, reason string)) HandlerOption
WithAuthzAudit calls audit once for each secure /api/ request answered 503 authz-unavailable, with AuditCheckFailed, AuditCheckLimit, AuditFullReadFailed, AuditExpired or AuditIdentity, or 503 authz-busy, with AuditQueueFull.
func WithBackendConsumers ¶ added in v0.7.0
WithBackendConsumers gives each install's non-route backend consumers, such as GatewayExtensions (design §8.3). Without it there are none.
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 WithCheckCapHit ¶ added in v0.8.0
func WithCheckCapHit(hit func(r *http.Request)) HandlerOption
WithCheckCapHit calls hit once for each secure /api/ request that passes CheckLimit, whatever it is answered, before the answer is chosen.
func WithCheckTrace ¶ added in v0.8.0
WithCheckTrace calls trace for each uncached check a secure /api/ request counts, with the build it was counted in (1-based, discarded builds included), why the check was a miss (a Miss reason, or "" when the authoriser gives none) and the authoriser's key for the check. It runs while the authoriser holds its locks, so it must be quick and must not call back.
func WithCommands ¶
func WithCommands(c diagnose.Commands) HandlerOption
WithCommands sets the next-step commands; the default is diagnose.Kubectl.
func WithCommitCheck ¶ added in v0.8.0
func WithCommitCheck(check func(w http.ResponseWriter, r *http.Request) (*http.Request, error)) HandlerOption
WithCommitCheck runs check on every secure /api/ request r after its handler and before its response is written. Answering r commits; nil means check wrote its own response, which replaces the handler's; another request rebuilds the response with it; an error answers 503 authz-unavailable.
func WithCommitClock ¶ added in v0.8.0
func WithCommitClock(now func() time.Time) HandlerOption
WithCommitClock sets the clock commit compares allow expiries with; without it, time.Now.
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.
func WithRequestAudit ¶ added in v0.8.0
func WithRequestAudit(hear func(AuditEvent), disclosure bool) HandlerOption
WithRequestAudit calls hear once for each /api/ request, after its answer is written. With disclosure, each successful answer reports the object references its response value holds; the body is never parsed.
func WithScopedReader ¶ added in v0.7.0
func WithScopedReader(r endpoints.ScopedReader) HandlerOption
WithScopedReader reads one Service's endpoints for backend detail (design §9.3). Without it, or with nil, those endpoints are unavailable.
func WithSecureMode ¶ added in v0.8.0
func WithSecureMode() HandlerOption
WithSecureMode marks the handler secure: every /api/ response goes through the per-viewer projection and the commit wrapper.
func WithSessionGate ¶ added in v0.8.0
func WithSessionGate(gate func(http.Handler) http.Handler) HandlerOption
WithSessionGate wraps the handler in gate, inside the request audit and outside the commit wrapper, so a request gate refuses is still heard.
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; in secure mode without
// the full read it is the confirmation time (D-109). 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"`
// DetailsHidden is set when the caller may not read the source of every
// metadata field, which is then empty (design §7.4).
DetailsHidden bool `json:"detailsHidden,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 ¶
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" // LinkBackend: not detail, and the backend detail serves it to the caller, absent or not (D-079). LinkBackend Link = "backend" // LinkNone: denied, absent, never served or not admitted (D-013). LinkNone Link = "none" )
Links.
type ListAuthorizer ¶ added in v0.8.0
type ListAuthorizer interface {
// CanList reports whether the caller of r may list gk in namespace.
CanList(r *http.Request, gk objects.GroupKind, namespace string) (bool, error)
}
ListAuthorizer answers population checks (design §7.6, §8.1): whether the caller may list a kind in a namespace, "" meaning cluster-wide.
type ListQuery ¶ added in v0.8.0
ListQuery is one population list question: may the caller list Kind in Namespace. A cluster-scoped kind is listed cluster-wide whatever Namespace says.
type ListScanner ¶ added in v0.8.0
type ListScanner interface {
// NamedGetScan reports whether a member the list denies is still asked by named get.
NamedGetScan() bool
}
ListScanner says whether a list denial is final for a population member (D-100). Without it, a denied member is asked again through ErrAuthorizer.
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"`
Reason *DetailReason `json:"reason,omitempty"`
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"`
GRPCMethod *GRPCMethodDTO `json:"grpcMethod,omitempty"`
}
MatchDTO is one HTTPRouteMatch after defaults, or one GRPCRouteMatch as written: its headers and GRPCMethod. Method is the HTTP method only.
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"`
// AuthMode is "secure" when the server was built with WithSecureMode, else "local" (no sign-in).
AuthMode string `json:"authMode"`
// LimitedView is set in secure mode when the caller may not list every
// served kind cluster-wide; only the caller's own rights decide it (design §7.5).
LimitedView bool `json:"limitedView,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 NamedAuthorizer ¶ added in v0.8.0
type NamedAuthorizer interface {
// AuthorizeNamedErr reports whether the caller of r may view the named ref, or why it could not tell.
AuthorizeNamedErr(r *http.Request, ref objects.Ref) (bool, error)
}
NamedAuthorizer answers named-ref checks (D-100): a detail page's subject, or an object named in a readable object. Without it a named ref is checked as a population member.
type NamespaceFacetDTO ¶ added in v0.7.0
NamespaceFacetDTO is a route namespace and the paths with a route in it.
type NamespacesResponse ¶ added in v0.8.0
type NamespacesResponse struct {
Install string `json:"install"`
Namespaces []string `json:"namespaces"`
CollectedAt time.Time `json:"collectedAt"`
}
NamespacesResponse is GET …/namespaces: the sorted namespaces of the install's route, Gateway and ListenerSet rows the caller can see.
type Narrowed ¶ added in v0.8.0
type Narrowed struct {
Base, Policy Authorizer
}
Narrowed allows only what both Base and Policy allow: secure mode puts a build's own authoriser behind SAR this way. The API uses Base's list, batch, full-read and admission answers and ANDs Policy into each decision.
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"` // DelegationNotChecked says the caller gets no delegation analysis here (D-114). DelegationNotChecked bool `json:"delegationNotChecked,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 PathCountsDTO ¶ added in v0.7.0
type PathCountsDTO struct {
Paths int `json:"paths"`
Routes int `json:"routes"`
Gateways int `json:"gateways"`
Backends int `json:"backends"`
}
PathCountsDTO counts filtered visible paths and the distinct routes, Gateways and backends they reach.
type PathFacetsDTO ¶ added in v0.7.0
type PathFacetsDTO struct {
Gateways []GatewayFacetDTO `json:"gateways"`
Namespaces []NamespaceFacetDTO `json:"namespaces"`
}
PathFacetsDTO lists the gateway and namespace filter values, sorted by name.
type PathListenerDTO ¶ added in v0.7.0
type PathListenerDTO struct {
Name string `json:"name"`
Protocol string `json:"protocol,omitempty"`
Port int32 `json:"port,omitempty"`
}
PathListenerDTO is a path row's listener. Protocol and port are absent when the spec has no listener of that name.
type PathMatchDTO ¶
PathMatchDTO is a path match after defaults.
type PathRowDTO ¶ added in v0.7.0
type PathRowDTO struct {
ID string `json:"id,omitempty"`
Gateway LinkedRef `json:"gateway"`
ListenerSet *LinkedRef `json:"listenerSet,omitempty"`
Listener PathListenerDTO `json:"listener"`
Hostnames []string `json:"hostnames"`
// Routes are the route chain, root first.
Routes []LinkedRef `json:"routes"`
Delegated bool `json:"delegated"`
Rule int `json:"rule"`
Matches []MatchDTO `json:"matches"`
GRPCMatches []GRPCMatchDTO `json:"grpcMatches,omitempty"`
Action string `json:"action"`
Delegation *DelegationRefDTO `json:"delegation,omitempty"`
Backend *LinkedRef `json:"backend,omitempty"`
Port int32 `json:"port,omitempty"`
Weight int32 `json:"weight"`
Mirror bool `json:"mirror"`
// MirrorPercent is the mirror's written percent, not a share.
MirrorPercent *float64 `json:"mirrorPercent,omitempty"`
Problem ProblemDTO `json:"problem"`
Endpoints *EndpointsDTO `json:"endpoints,omitempty"`
Note string `json:"note,omitempty"`
}
PathRowDTO is one path (design §4.1). Matches applies to HTTPRoute rows and GRPCMatches to GRPCRoute rows; TCPRoute and TLSRoute rows have neither. Matches is null on a delegated row whose view C match is unknown. Share is set for shown, failing, may-fail and no-traffic shares; MirrorPercent only on a mirror row. ID is the row's identity, unique among the rows of one Revision: its attachment, path context, rule, ref and mirror.
type PathSignal ¶ added in v0.8.0
type PathSignal struct {
State health.State `json:"state"`
Reason *RouteReason `json:"reason,omitempty"`
Incomplete bool `json:"incomplete"`
}
PathSignal is a route's traffic path signal. Reason is as on RouteRow; Incomplete says the caller may not read everything the path needs (design §8.1).
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 PathSummaryDTO ¶ added in v0.7.0
type PathSummaryDTO struct {
PathCountsDTO
ByState map[string]PathCountsDTO `json:"byState"`
NotComputed string `json:"notComputed,omitempty"`
EndpointsNotRead bool `json:"endpointsNotRead,omitempty"`
Hidden bool `json:"hidden,omitempty"`
Unmemoised bool `json:"unmemoised,omitempty"`
// Facets are the Gateways and route namespaces of the visible rows,
// each counted with every filter but its own.
Facets PathFacetsDTO `json:"facets"`
}
PathSummaryDTO summarises the whole filtered result the caller may see (design §5, §13). Hidden says some paths were left out for the caller; secure mode never sets it, since the permissions note replaces it (design §7.5). Unmemoised says the topology was over the memo cap and derived per request; a viewer without the full read in secure mode is never told. NotComputed says why there are no paths to compute, such as no computed views.
type PathsResponse ¶ added in v0.7.0
type PathsResponse struct {
Install string `json:"install"`
Revision string `json:"revision,omitempty"`
Rows []PathRowDTO `json:"rows"`
Next string `json:"next,omitempty"`
Prev string `json:"prev,omitempty"`
Summary PathSummaryDTO `json:"summary"`
// DelegationNotChecked says the caller gets no paths through parent routes (D-114).
DelegationNotChecked bool `json:"delegationNotChecked,omitempty"`
CollectedAt time.Time `json:"collectedAt"`
}
PathsResponse is GET …/paths. Revision is a digest of the whole ordered result the page was cut from, visible rows only: pages of one walk agree on it while the result holds, and a walk whose pages differ must restart.
type PortChainDTO ¶ added in v0.7.0
type PortChainDTO struct {
RefPort int32 `json:"refPort"`
ServicePort *int32 `json:"servicePort,omitempty"`
ServicePortName string `json:"servicePortName,omitempty"`
TargetPort string `json:"targetPort,omitempty"`
TargetName string `json:"targetName,omitempty"`
SlicePorts []int32 `json:"slicePorts"`
NoSuchPort bool `json:"noSuchPort,omitempty"`
NoSlicePort bool `json:"noSlicePort,omitempty"`
}
PortChainDTO is one referenced port's chain as written and observed (design §9.4): the Service port it matches, its numeric target or target name, and the slice ports observed for that port's name. NoSuchPort is set when the cached Service has no such port, NoSlicePort only when a complete read found no slice port for the name.
type ProblemDTO ¶ added in v0.7.0
ProblemDTO is a row's worst state and its signals that are not healthy (design §4.5).
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"`
NotAssessed bool `json:"notAssessed,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) and is unset in secure mode, where a set the caller may not read is NotAssessed with no counts.
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"`
NotAssessed bool `json:"notAssessed,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) and is unset in secure mode. NotAssessed marks a state from derived findings, which a viewer without the full read is not shown (D-106): its State is unknown, and its counts are absent when the Deployment is hidden.
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"`
NotAssessed bool `json:"notAssessed,omitempty"`
Gateways int `json:"gateways"`
Ready int `json:"ready"`
Rejecting int `json:"rejecting"`
Skew int `json:"skew"`
Restarting int `json:"restarting"`
NotObserved int `json:"notObserved"`
SelfManaged int `json:"selfManaged"`
}
ProxySummary counts the visible Gateways: those with every proxy ready, with a reject, with version skew, with a restart, whose proxies are not observed, and whose proxies are self-managed (KGWUI-010; also counted in NotObserved). State is the worst known health of those Gateways; unknown when none is known.
NotAssessed is as on ProcessSummary; then Ready and NotObserved count only the Gateways whose proxy Deployments and Pods the viewer may list.
type Ready ¶ added in v0.8.0
Ready reports whether the process can serve; the reason is for the log only.
func ModelReady ¶ added in v0.8.0
func ModelReady(src ModelSource) Ready
ModelReady is ready once the model is synced and no install was rejected (D-016). A rejected install's ID goes in the reason, never into a response.
type RefExplanationDTO ¶ added in v0.7.0
type RefExplanationDTO struct {
Route LinkedRef `json:"route"`
Rule int `json:"rule"`
Ref int `json:"ref"`
Path string `json:"path"`
Kind string `json:"kind"`
Reason string `json:"reason,omitempty"`
Explanation string `json:"explanation,omitempty"`
Fix *SuggestedFix `json:"fix,omitempty"`
}
RefExplanationDTO explains one route ref to the backend that does not resolve (design §10). Kind is attributed, candidate or waiting. Ref is the backendRefs index, which a backendRef's own mirror shares, and -1 for a rule filter's mirror; Path, where the route writes the ref, tells them apart.
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"`
Reason *DetailReason `json:"reason,omitempty"`
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"`
Serves []TraceAttachmentDTO `json:"serves,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"`
// DelegationNotChecked says the caller gets no delegation analysis (D-114).
DelegationNotChecked bool `json:"delegationNotChecked,omitempty"`
CollectedAt time.Time `json:"collectedAt"`
// Config and Path are as on RouteRow; Health is their summary.
Config RouteSignal `json:"config"`
Path PathSignal `json:"path"`
}
RouteDetail is GET …/routes/{group}/{kind}/{ns}/{name} for HTTPRoute, GRPCRoute, TCPRoute and TLSRoute. 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. Serves are the attachments the route's visible paths run through (design §7.1), in the path model's attachment order; look-alike ones merge, worst state first.
type RouteNamespacesDTO ¶
type RouteNamespacesDTO struct {
From string `json:"from"`
Selector *metav1.LabelSelector `json:"selector,omitempty"`
}
RouteNamespacesDTO is allowedRoutes.namespaces.
type RouteReason ¶ added in v0.7.1
RouteReason is a route row's reason plus, on kind backend-problem, the backend when the caller may view it; else that kind keeps only its code (D-082).
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 is the summary of Config and Path (design §8.3).
Health health.State `json:"health"`
// Reason says why Health is not healthy (D-063).
Reason *RouteReason `json:"reason,omitempty"`
Mirror bool `json:"mirror,omitempty"`
// Config and Path are the route's two signals (design §8.1).
Config RouteSignal `json:"config"`
Path PathSignal `json:"path"`
}
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 RouteSignal ¶ added in v0.8.0
type RouteSignal struct {
State health.State `json:"state"`
Reason *health.RowReason `json:"reason,omitempty"`
}
RouteSignal is a route's configuration signal: its own findings.
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"`
EffectiveFilters []FilterDTO `json:"effectiveFilters,omitempty"`
}
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". A TCPRoute or TLSRoute rule has no matches: []. EffectiveFilters is reserved and never set.
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 RuntimeDTO ¶ added in v0.7.0
type RuntimeDTO struct {
Install string `json:"install"`
Gateway LinkedRef `json:"gateway"`
Proxy string `json:"proxy"`
Instance string `json:"instance"`
}
RuntimeDTO names the proxy process a per-proxy endpoints source reads (#35). Instance changes when the proxy is replaced.
type ServiceFactDTO ¶ added in v0.7.0
ServiceFactDTO is what the cache keeps of a Service: its type and ports.
type SignalDTO ¶ added in v0.7.0
type SignalDTO struct {
Kind string `json:"kind"`
Code string `json:"code,omitempty"`
Title string `json:"title,omitempty"`
Ref *LinkedRef `json:"ref,omitempty"`
State health.State `json:"state"`
Attachment *int `json:"attachment,omitempty"`
Listener string `json:"listener,omitempty"`
}
SignalDTO is one existing signal on a row's chain: its kind, its code (a finding code, condition type, capability state or view C reason) and object. Title is a finding signal's message, as the findings API shows it. Attachment, on a route detail backendRef only, indexes the serves entry an attachment's Gateway, listener or parent status signal came from. Listener names the listener of Ref a listener's signal is about, waiting ones included.
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 TraceAttachmentDTO ¶ added in v0.7.0
type TraceAttachmentDTO struct {
Gateway LinkedRef `json:"gateway"`
ListenerSet *LinkedRef `json:"listenerSet,omitempty"`
Listener PathListenerDTO `json:"listener"`
Hostnames []string `json:"hostnames"`
State health.State `json:"state"`
}
TraceAttachmentDTO is one attachment a route serves through, with the state of its own Gateway, listener and parent status signals.
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 Viewer ¶ added in v0.8.0
type Viewer interface {
// Secure reports whether the request runs in secure mode.
Secure() bool
// ReadsAll reports whether the caller has the full read (design §6.4).
ReadsAll() bool
// Can reports whether the caller may see ref as a population member: a row, count or aggregate.
Can(objects.Ref) bool
// CanNamed reports whether the caller may see ref by name: a detail page's subject.
CanNamed(objects.Ref) bool
// CanList reports whether the caller may list gk in namespace, "" meaning cluster-wide.
CanList(gk objects.GroupKind, namespace string) bool
// Shown reports whether the caller sees f: always outside secure mode and
// under the full read; else only an own-object finding on readable objects (D-106).
Shown(*health.Finding) bool
// Backends are install i's Backends the caller may see. In secure mode
// without the full read, only those a readable route of i names (D-107).
Backends(i *engine.InstallModel) []*unstructured.Unstructured
}
Viewer is what the caller of one request may see, for extension handlers that serve cluster objects (design §7.2). It answers as the core handlers do, so an extension applies the same rule (D-085). One request uses it, on one goroutine. Install.Owned.Backends depends on hidden consumer routes: use Backends instead. Only pkg/api implements it, so methods may be added.
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.
Source Files
¶
- audit.go
- authz.go
- backends.go
- backends_types.go
- capability.go
- commit.go
- details.go
- diag_types.go
- diagnostics.go
- explain.go
- explore_types.go
- ext.go
- features.go
- findings.go
- guard.go
- handlers.go
- incomplete.go
- link.go
- lists.go
- namespaces.go
- params.go
- paths.go
- paths_types.go
- probe.go
- processes.go
- refs.go
- routepath.go
- trace.go
- types.go
- viewer.go
- visible.go