Documentation
¶
Overview ¶
Package computed is the seam for the UI's computed views (D-020): the rule interface, its inputs and results, and the states a cross-check reports. The version-specific rule sets live in subpackages; rulesets selects one.
Index ¶
- Constants
- Variables
- func ClipDisplay(p string, limit int) string
- func DecodeTargets(u *unstructured.Unstructured) ([]TargetRef, []TargetSelector)
- func DeployerLogClass(c string) bool
- func KnownLogClass(c string) bool
- func Subject(parts ...string) string
- type Acceptance
- type Allows
- type AttachmentInput
- type AttachmentResult
- type Bounds
- type CheckKind
- type CheckResult
- type ChildEffective
- type Class
- type Completeness
- type Context
- type ContextHasher
- type Coverage
- type DelegRoute
- type DelegationInput
- type DelegationResult
- type Delegator
- type DepAcc
- type DepSets
- type Edge
- type EffectiveEdge
- type EffectiveRule
- type EnvoyNamer
- type Fact
- type FactCode
- type FitClause
- type FitFailure
- type Identity
- type Labeler
- type ListenerCount
- type LogFields
- type LogParser
- type LogWindow
- type Member
- type Outcome
- type ParentSignal
- type Path
- type PathStep
- type PolicyTargeter
- type RefOutcome
- type ReportKey
- type Resource
- type Root
- type Route
- type RouteKey
- type Row
- type RowKey
- type RowMeta
- type RowOutcome
- type Rules
- type Selection
- type State
- type StatusTarget
- type TargetInput
- type TargetRef
- type TargetResult
- type TargetSelector
- type TargetStatusReporter
- type Uncertain
- type UnknownReason
- type Unresolved
- type Views
Constants ¶
const ( ModeDefault = "default" ModeInherit = "inherit" )
Effective matcher modes (rules §6).
const ( CapEdges = "edges" CapContexts = "contexts" CapMatchers = "matchers" CapDepth = "depth" )
Compute caps, as DelegationResult.Cap names them (rules §5.7).
const ( ReasonBackendNotFound = "BackendNotFound" ReasonRefNotPermitted = "RefNotPermitted" )
Parent signal reasons: ResolvedRefs=False reasons a delegation failure writes on the parent (ProcessBackendError, pkg/kgateway/query/utils.go V3:37-50).
const ( // UncertainRoot: an owned top-level route whose root eligibility is unknown. UncertainRoot = -1 // UncertainPossible: a route an uncertain selection might select. UncertainPossible = -2 )
Uncertain point rule indexes besides a real rule index (rules §8.5).
const ( LogClassRegex = "regex" LogClassTLS = "tls" LogClassDuplicate = "duplicate" LogClassBind = "bind" LogClassValidation = "validation" LogClassUnknownExtension = "unknown-extension" LogClassApply = "apply" LogClassParameters = "parameters" LogClassRender = "render" LogClassNoValidPorts = "no-valid-ports" LogClassStatusUpdate = "status-update" LogClassPrune = "prune" LogClassPanic = "panic" LogClassOther = "other" )
Error classes of derived log events (design §8.9): Envoy's reject reasons, the deployer's failures, a Go panic and other.
const ( TargetFound = "found" TargetNotFound = "not-found" TargetSectionNotFound = "section-not-found" TargetMatchesNothing = "matches-nothing" TargetUnknown = "unknown" )
Target outcomes, as TargetResult.Outcome carries them.
const MaxDisplayBytes = 256
MaxDisplayBytes bounds one value inside a display string such as a reason.
const MaxLogWindow = 8
MaxLogWindow is how many following lines a LogWindow marker may ask for.
const MaxPathBytes = 4096
MaxPathBytes bounds a generated path. A longer one is never cut: the context is unknown, too-large.
const MaxStatusBytes = 1024
MaxStatusBytes bounds a status message quoted in evidence (design §18.2).
Variables ¶
var DefaultBounds = Bounds{Edges: 10_000, Contexts: 20_000, Matchers: 200_000,
ContextsPerRow: 20, ContextsPerInstall: 30_000, EffectiveEdges: 20, ContextsPerEdge: 20, Depth: 100}
DefaultBounds are the caps of rules §5.7. ContextsPerInstall is 30,000 (our call, 2.4; D-022 retained heap). Edges is 10,000 (user, 2026-10-27; D-025): dense delegation must stay inside the chart's 512Mi memory limit. Depth is 100 (our call, 2.4; D-025): deep chains stay linear in memory.
Functions ¶
func ClipDisplay ¶
ClipDisplay cuts a display string to limit bytes at a UTF-8 boundary and adds a marker. Computed paths never pass through it.
func DecodeTargets ¶
func DecodeTargets(u *unstructured.Unstructured) ([]TargetRef, []TargetSelector)
DecodeTargets returns a policy's spec.targetRefs and spec.targetSelectors as written. Entries that are not objects are skipped.
func DeployerLogClass ¶
DeployerLogClass reports whether c is one of the deployer's error classes, which only deployer lines carry.
func KnownLogClass ¶
KnownLogClass reports whether c is on the fixed list of error classes.
Types ¶
type Acceptance ¶
type Acceptance int
Acceptance is a listener-bearing resource's own acceptance (rules §3.1).
const ( Accepted Acceptance = iota Denied NoStatus )
Acceptance values. A Gateway is always Accepted.
type AttachmentInput ¶
type AttachmentInput struct {
Resources []Resource
Routes []Route
// NamespaceLabels holds each Namespace's labels; it is only meaningful when NamespacesOK.
NamespaceLabels map[string]map[string]string
NamespacesOK bool
Experimental install.Setting
ControllerNames []string
// ScopeUnknown makes every count and outcome unknown: the candidates are a guess (rules §3.3).
ScopeUnknown bool
}
AttachmentInput is everything view A reads for one install (rules §4.6).
type AttachmentResult ¶
type AttachmentResult struct {
Members []Member
Outcomes []RefOutcome
Counts []ListenerCount
}
AttachmentResult is view A for one install. Its Deps slices are read-only and may be shared between entries: never sort or append to them in place.
type Bounds ¶
type Bounds struct {
// Compute caps per install.
Edges, Contexts, Matchers int
// Retention caps: contexts per row and per install.
ContextsPerRow, ContextsPerInstall int
// Projection caps: parent edges per route, contexts per edge.
EffectiveEdges, ContextsPerEdge int
// Depth caps the routes on one path, which bounds each context's deps.
Depth int
}
Bounds are the compute and retention caps of views B and C (rules §5.7).
type CheckKind ¶
type CheckKind string
CheckKind names what a cross-check compares (rules §9.1).
const ( KindListenerCount CheckKind = "listener-count" KindRouteAccepted CheckKind = "route-accepted" )
Check kinds of view A.
const ( KindChildEntry CheckKind = "child-entry" KindParentResolvedRefs CheckKind = "parent-resolvedrefs" )
Check kinds of views B and C.
const ( KindDelegatedNotAttached CheckKind = "delegated-not-attached" KindOrphan CheckKind = "orphan-not-attached" )
Trigger kinds of KGWUI-011 (rules §9.1): the computed trigger per (route, parent) and the orphan trigger per route.
const KindPolicyTarget CheckKind = "policy-target"
KindPolicyTarget is the policy targets verifier: a current ancestor for a target the rule called missing (design §7.6).
type CheckResult ¶
type CheckResult struct {
ID Identity
Class Class
// Unknown says why a ClassUnknown check could not be made, when a reason applies.
Unknown UnknownReason
Verified bool
Coverage []Coverage
// Fingerprint hashes the inputs and evidence of rules §9.2.
Fingerprint uint64
// On is the object whose status disagrees (rules §9.3 step 5).
On objects.Ref
Listener string
Key ReportKey
Expected string
Observed string
// Deps and Contributors are read-only and may be shared.
Deps []objects.Ref
Contributors []objects.Ref
ParentCurrent bool
Note string
// State, Mature and Since (the window start) are set by the engine.
State State
Mature bool
Since time.Time
}
CheckResult is one cross-check of a computed result against status.
func CheckAttachment ¶
func CheckAttachment(install string, sel Selection, in AttachmentInput, r AttachmentResult) []CheckResult
CheckAttachment cross-checks view A against the controller's status (rules §8.1–§8.4): one listener-count check per listener count, and one route-accepted check per (route, report key). It never modifies r.
func CheckDelegation ¶
func CheckDelegation(install string, sel Selection, in DelegationInput, r *DelegationResult) []CheckResult
CheckDelegation cross-checks views B and C against the controller's status (rules §8.1–§8.5): one child-entry check per (child, parent, report key), including entries no row expects, and one parent-resolvedrefs check per (parent, reporter key). Completeness comes from r.Complete. It sets each row's Unconfirmable and otherwise never modifies r.
func (CheckResult) Candidate ¶
func (c CheckResult) Candidate() bool
Candidate reports whether c can mature into KGWUI-012 (rules §9.3 step 1).
type ChildEffective ¶
type ChildEffective struct {
Edges []EffectiveEdge
Truncated bool
}
ChildEffective is one child's effective edges, sorted by parent, at most Bounds.EffectiveEdges; Truncated is set when more parents had one.
type Class ¶
type Class string
Class is a cross-check's evidence class (rules §8.1, §8.3).
const ( ClassContradicting Class = "contradicting" ClassStale Class = "stale" ClassMissing Class = "missing" ClassUnexpected Class = "unexpected" ClassCompatible Class = "compatible" ClassNotObservable Class = "not-observable" ClassInconclusive Class = "inconclusive" ClassUnknown Class = "unknown" // ClassTrigger is a KGWUI-011 trigger whose predicate holds (our call: // rules §8.3 gives it no class). It matures but never makes a check pending. ClassTrigger Class = "trigger" )
Evidence classes.
type Completeness ¶
type Completeness struct {
// contains filtered or unexported fields
}
Completeness says which aggregates of a delegation result are complete (rules §8.5). An aggregate on a route in a reach closure is incomplete: the missing work may reach it. The zero value has every route complete.
func NewCompleteness ¶
func NewCompleteness(r DelegationResult) Completeness
NewCompleteness computes r's reach closures: from every uncertain point's route over r.Reach, transitively (rules §8.5). Each edge is walked once.
func (Completeness) Incomplete ¶
func (c Completeness) Incomplete(route objects.Ref) bool
Incomplete reports whether route is in a reach closure.
func (Completeness) IncompleteKey ¶
func (c Completeness) IncompleteKey(route objects.Ref, key ReportKey) bool
IncompleteKey reports whether a check on route under key is incomplete: route is in a reach closure, or key is one of route's Root.UncertainKeys. An uncertain key does not seed a closure, since the evaluation below a root is the same under every key; only the root's own report under it is uncertain.
type Context ¶
type Context struct {
ParentMatch objects.Match
Path *Path
// Reporter is the report key of the parent's reporter (rules §7).
Reporter ReportKey
// Outcome must be set by the caller; an empty or unknown value counts as unknown.
Outcome RowOutcome
Unknown UnknownReason
Reason *FitFailure
Rules []EffectiveRule
Deps []objects.Ref
}
Context is one evaluation of a row under one incoming parent match (rules §5.1). Its slices are read-only once added to a row, so they may be shared.
type ContextHasher ¶
type ContextHasher struct {
// contains filtered or unexported fields
}
ContextHasher hashes contexts for the row digests with the fingerprint encoding (rules §9.2). It reuses its buffers, so one hasher serves one caller.
func NewContextHasher ¶
func NewContextHasher() *ContextHasher
NewContextHasher returns a ContextHasher.
func (*ContextHasher) Sum ¶
func (h *ContextHasher) Sum(c *Context) uint64
Sum hashes c's incoming match, path, reporter and outcome.
type Coverage ¶
type Coverage string
Coverage says what a passing cross-check verified (rules §8.4).
type DelegRoute ¶
type DelegRoute struct {
Ref objects.Ref
Generation int64
View *objects.HTTPRouteView
// Owned is true for a route of the install; TopLevel for an owned route
// that has a Gateway or ListenerSet parent.
Owned, TopLevel bool
}
DelegRoute is an in-scope HTTPRoute as views B and C read it.
type DelegationInput ¶
type DelegationInput struct {
// Routes are every in-scope HTTPRoute, sorted by (namespace, name).
Routes []DelegRoute
// Unwatched are the HTTPRoutes outside the scope.
Unwatched map[objects.Ref]bool
Roots []Root
// Wildcard is the delegation wildcard namespace setting (rules §5.2).
Wildcard install.Setting
ControllerNames []string
Bounds Bounds
// ScopeUnknown makes views B and C scope-unknown: the candidates are a guess (D-024).
ScopeUnknown bool
}
DelegationInput is everything views B and C read for one install.
type DelegationResult ¶
type DelegationResult struct {
// Rows are in RowKey order.
Rows []Row
// Signals are the parents' ResolvedRefs failures, by (Parent, Key).
Signals []ParentSignal
// Reach is (route → permitted selected child) for every in-scope route
// with delegation refs, from selection and permission alone (rules §8.5).
// It is sorted by (Parent, Child).
Reach []Edge
// Uncertain are the uncertain points of rules §8.5, sorted by (Route, Rule, Ref).
Uncertain []Uncertain
// UncertainKeys are each root's Root.UncertainKeys, sorted: a check under
// one of them makes no negative expectation (rules §8.5).
UncertainKeys []RouteKey
// Cap names the first compute cap hit: "", "edges", "contexts", "matchers" or "depth".
Cap string
// Complete says which routes are in a reach closure (rules §8.5).
Complete Completeness
// Effective is view C per child, projected from the retained contexts (rules §5.7, §6).
Effective map[objects.Ref]ChildEffective
}
DelegationResult is views B and C for one install (rules §5, §6, §8.5).
type Delegator ¶ added in v0.6.0
type Delegator interface {
Delegation(in DelegationInput) DelegationResult
}
Delegator is an optional interface of a Rules: it computes views B and C (rules §5, §6). A rule set without it has no delegation; view A stays.
type DepAcc ¶
type DepAcc struct {
// contains filtered or unexported fields
}
DepAcc gathers the sets of one growing aggregate; DepSets.Finish unites them.
type DepSets ¶
type DepSets struct {
// contains filtered or unexported fields
}
DepSets hash-conses the finished dependency sets of one delegation run, so equal sets share one backing slice however often rows and contexts hold them (rules §5.7). Aggregates grow in a DepAcc and are interned only when finished, so their superseded prefixes are never kept. Interned slices are read-only. The zero value is not usable; call NewDepSets.
type EffectiveEdge ¶
type EffectiveEdge struct {
Parent objects.Ref
// Mode is ModeDefault or ModeInherit, from the child's annotation.
Mode string
Contexts []Context
ContextsTruncated bool
Deps []objects.Ref
}
EffectiveEdge is view C for one (parent, child) edge: the union of the retained contexts of every row with that parent and child whose fit ran, in traversal order, at most Bounds.ContextsPerEdge (rules §5.7). Contexts is non-nil; ContextsTruncated is set when any contributing row was truncated or the union passed the cap. Deps cover every contributing row.
type EffectiveRule ¶
type EffectiveRule struct {
Index int
Kept bool
Matches []objects.Match
Reason *FitFailure
}
EffectiveRule is one child rule under one parent match (view C, rules §6). A kept rule has its effective matches; a dropped one has Reason.
type EnvoyNamer ¶
EnvoyNamer maps an Envoy resource name, such as a cluster or route config name from proxy stats, back to its Gateway API object (design §8.8). It is pinned per kgateway version and ships only with per-version fixtures.
type FitClause ¶
type FitClause string
FitClause names the clause of the default-mode fit that dropped a child rule (rules §6).
const ( // ClausePathType: the parent path type is not PathPrefix. ClausePathType FitClause = "path-type" // ClausePathPrefix: the child path does not start with the parent's. ClausePathPrefix FitClause = "path-prefix" // ClauseHeader and ClauseQuery: a parent header or query param is missing from the child. ClauseHeader FitClause = "header" ClauseQuery FitClause = "query" // ClauseMethod: the child does not have the parent's method. ClauseMethod FitClause = "method" // ClauseDefaultSlash: omitted matches default to PathPrefix /, outside a parent prefix other than /. ClauseDefaultSlash FitClause = "default-slash" // ClauseNoMatches: an explicit empty match list in default mode (our call). ClauseNoMatches FitClause = "no-matches" )
Fit clauses (rules §6).
type FitFailure ¶
FitFailure is why a child rule was dropped: the clause its first match failed. Match is -1 for an explicit empty list. Parent and Child are the values the clause compared; Child is empty when the child has none.
type Labeler ¶ added in v0.6.0
type Labeler interface {
Label() string
}
Labeler is an optional interface of a Rules: its display name, such as "kgateway 2.4".
type ListenerCount ¶
type ListenerCount struct {
Resource objects.Ref
Listener string
Count int
Unknown UnknownReason
// Error is the listener's selector error. It is computed only: kgateway
// never reports it, and the §8 cross-check never compares it.
Error string
// IsolationNote marks a count that plain-HTTP listener isolation may not program (rules §4.5).
IsolationNote bool
}
ListenerCount is a listener's computed attachedRoutes (rule listener-count).
type LogFields ¶
type LogFields struct {
// Time is when the controller logged the line; zero means the reader's clock.
Time time.Time
// Marker is which of the parser's Markers the line is; empty means the one the reader found first.
Marker string
// Gateway is the Gateway the line names, by namespace and name; zero when none.
Gateway objects.Ref
// TypeURL is the xDS type URL of a reject.
TypeURL string
// Names are candidate Envoy resource names from Envoy's fixed NACK shapes.
Names []string
// Class is an error class; one KnownLogClass does not report becomes LogClassOther.
Class string
// Object is the object a deployer error names, nil when none.
Object *objects.Ref
// Frame is a panic's top frame function, from the previous container only.
Frame string
}
LogFields are the fixed fields one controller log line yields (design §8.9). The reader keeps a value only when it is in a closed set, so a parser that returns log text loses it there.
type LogParser ¶
type LogParser interface {
// Markers are the fixed substrings of the lines Parse reads; a line without one is never parsed.
Markers() []string
// Parse reads one line, valid only during the call. ok false with a nil
// error means the line is not one it reads; an error means it failed, in a fixed text without log content.
Parse(line []byte) (fields LogFields, ok bool, err error)
}
LogParser is an optional interface of a Rules: it reads the controller log lines of its kgateway version. A rule set without it reads no logs.
type LogWindow ¶
type LogWindow interface {
// Window is how many lines after line, which holds marker m, ParseWindow reads,
// at most MaxLogWindow; previous reports a read of the previous container. 0 means none.
Window(line []byte, m string, previous bool) int
// ParseWindow reads a marked line and the lines after it, fewer at the end
// of the read; all are valid only during the call. Results are as for Parse.
ParseWindow(line []byte, next [][]byte, previous bool) (fields LogFields, ok bool, err error)
}
LogWindow is an optional interface of a LogParser whose marker needs the lines after it, such as a Go panic's top frame (R102).
type Member ¶
type Member struct {
Resource objects.Ref
Listener string
Route objects.Ref
ParentRef int
// Hostnames are the effective hostnames on this listener.
Hostnames []string
Deps []objects.Ref
}
Member is a route attached to a listener through one parentRef.
type Outcome ¶
type Outcome string
Outcome is a parentRef's attachment outcome; rejections use the controller's reasons.
type ParentSignal ¶
ParentSignal is the ResolvedRefs=False a delegating parent's reporter receives (rules §5.4 parentSignal). Reasons are in first-seen order; Deps cover every context that recorded a failure.
type Path ¶
type Path struct {
// contains filtered or unexported fields
}
Path is a context's path, held as its last step and a link to the path before it. Paths are immutable, so the contexts under one parent share its prefix and retained paths grow linearly with depth. A nil Path is empty.
func (*Path) AppendSteps ¶
AppendSteps appends the steps, root first, to dst.
func (*Path) MarshalJSON ¶
MarshalJSON encodes the steps root first, as a slice would be.
type PolicyTargeter ¶
type PolicyTargeter interface {
PolicyTargets(in TargetInput) []TargetResult
}
PolicyTargeter is an optional interface of a Rules: it resolves a policy's targets for the computed KGWUI-016. A rule set without it raises no computed 016.
type RefOutcome ¶
type RefOutcome struct {
Route objects.Ref
ParentRef int
Resource objects.Ref
Outcome Outcome
Listeners []string
Facts []Fact
Unknown UnknownReason
Rule string
Deps []objects.Ref
}
RefOutcome is the computed outcome of one parentRef. Rule names the deciding stage: allowed-routes, section-and-port or hostname-intersection.
type ReportKey ¶
type ReportKey struct {
Group, Kind, Namespace, Name, SectionName string
}
ReportKey is kgateway's status report key: a parentRef as written, with empty strings for omitted fields and no port (rules §7).
func KeyOf ¶
func KeyOf(w objects.WrittenRef) ReportKey
KeyOf is w's report key. An omitted namespace stays empty, so it differs from an explicit one; the port is dropped.
type Resource ¶
type Resource struct {
Ref objects.Ref
// Parent is a ListenerSet's Gateway; zero for a Gateway.
Parent objects.Ref
Generation int64
Listeners []objects.Listener
ListenerStatus []objects.ListenerStatus
Acceptance Acceptance
}
Resource is a Gateway or ListenerSet whose listeners routes attach to.
type Root ¶
type Root struct {
Route objects.Ref
FromStatus, Unknown bool
// Deps are the root's eligibility dependencies (rules §5.6).
Deps []objects.Ref
// Keys are the report keys, as written, of the parentRefs view A accepted,
// or of the status entry a status root used: the keys the root's
// delegation failures are written under. Rejected parentRefs and those of
// other controllers' Gateways have none.
Keys []ReportKey
// UncertainKeys are the keys of parentRefs whose view A outcome is
// unknown, not in Keys: the controller may or may not write under them.
UncertainKeys []ReportKey
}
Root is a route delegation is evaluated from (rules §5.1). FromStatus marks a root taken from the controller's status because view A is unknown for it; Unknown marks a route that may be a root but cannot be told.
func Roots ¶
func Roots(routes []DelegRoute, att AttachmentResult, status StatusTarget) []Root
Roots takes the roots of views B and C from view A att (rules §5.1, §5.6). A top-level route is a root when an outcome is accepted. Otherwise, with every outcome unknown, a status entry found by status makes it a status root. Any other route with an unknown outcome is an unknown root; one with only known rejections is not a root (rules §5.1, §8.5).
type Route ¶
type Route struct {
Ref objects.Ref
Generation int64
Hostnames []string
ParentRefs []objects.ParentRef
Written []objects.WrittenRef
Parents []objects.RouteParentStatus
// ExperimentalOnly is true when the controller watches this route only with experimental features on.
ExperimentalOnly bool
}
Route is a route as view A reads it. Written is index-aligned with ParentRefs.
type Row ¶
type Row struct {
Key RowKey
RefAsWritten objects.DelegationRef
Allows Allows
Outcome RowOutcome
Unknown UnknownReason
// SomeNotComputed: a positive outcome (attached, partial or
// rejected-hostnames) while some paths were not computed.
// Unconfirmable: status cannot confirm this row's own outcome.
SomeNotComputed, Unconfirmable bool
Reason *FitFailure
Unresolved Unresolved
Contexts []Context
ContextsTruncated bool
Deps []objects.Ref
Reporters []ReportKey
ChildKey ReportKey
WritesEntry bool
// ContextDigest is an order-independent digest of every contributing
// context's incoming match, path, reporter and outcome; KeyDigests is the
// same digest per reporter, index-aligned with Reporters. Fingerprints
// read them (rules §9.2).
ContextDigest uint64
KeyDigests []uint64
// KeyDeps are Deps per reporter, index-aligned with Reporters: the sorted
// union of the deps of every context under that key. Its slices are
// read-only and may be shared.
KeyDeps [][]objects.Ref
}
Row is one delegation row aggregated over its contexts (rules §5.5). Deps, Reporters and the digests cover every context, retained or not (rules §5.7).
type RowKey ¶
RowKey identifies a delegation row: a parent, its rule and ref indexes and the selected child. A ref that selects nothing has one row with a zero Child (rules §5.5).
type RowMeta ¶
type RowMeta struct {
RefAsWritten objects.DelegationRef
Allows Allows
Unresolved Unresolved
ScopeUnknown bool
}
RowMeta is what a row knows before its contexts: the ref as written, the child's permission and, for a zero-child row, why the ref selected nothing. ScopeUnknown makes the row unknown/scope-unknown even with no contexts (D-024).
type RowOutcome ¶
type RowOutcome string
RowOutcome is a delegation row's outcome, per context or aggregated (rules §5.5).
const ( OutcomeAttached RowOutcome = "attached" OutcomePartial RowOutcome = "partial" OutcomeDropped RowOutcome = "dropped" OutcomeForbidden RowOutcome = "forbidden" OutcomeRejectedHostnames RowOutcome = "rejected-hostnames" OutcomeCycle RowOutcome = "cycle" OutcomeUnresolved RowOutcome = "unresolved" OutcomeUnknown RowOutcome = "unknown" )
Row outcomes. Partial is only ever an aggregate.
type Rules ¶
type Rules interface {
// Version names the rule set, such as "kgateway-2.4".
Version() string
// Attachment computes view A (rules §4).
Attachment(in AttachmentInput) AttachmentResult
}
Rules computes the views for one controller rule set (design §3.4). A rule set that computes delegation also implements Delegator.
type Selection ¶
type Selection struct {
Rules Rules
// Note is the selection label; it is part of every result's check note. Empty when the set matches.
Note string
// GatewayAPI maps a kgateway minor to its Gateway API bundle minor; nil means rulesets.ExpectedGatewayAPI.
GatewayAPI func(kgatewayMinor string) (bundle string, ok bool)
}
Selection is the rule set chosen for a controller, with its label (rules §2).
func (Selection) Delegator ¶ added in v0.6.0
Delegator returns the selected rule set's delegator, or nil when it has none. A wrapping rule set forwards it to keep delegation.
func (Selection) EnvoyNamer ¶
func (s Selection) EnvoyNamer() EnvoyNamer
EnvoyNamer returns the selected rule set's namer, or nil when it has none: Envoy names are then shown as Envoy names only. kgw23 and kgw24 have none.
func (Selection) Label ¶ added in v0.6.0
Label is the selected rule set's display name: its Label, else its Version; "" without one.
func (Selection) LogParser ¶
LogParser returns the selected rule set's log parser, or nil when it has none.
func (Selection) PolicyTargeter ¶
func (s Selection) PolicyTargeter() PolicyTargeter
PolicyTargeter returns the selected rule set's targeter, or nil when it has none.
func (Selection) TargetStatusReporter ¶
func (s Selection) TargetStatusReporter() TargetStatusReporter
TargetStatusReporter returns the selected rule set's reporter, or nil when it has none. A wrapping rule set forwards it to keep the status 016.
type StatusTarget ¶
type StatusTarget func(r DelegRoute) (objects.Ref, ReportKey, bool)
StatusTarget finds a route's status root (rules §5.1): the target and report key, as written, of its first current Accepted=True entry from the install's controllers for one of its Gateway or ListenerSet parents.
type TargetInput ¶
type TargetInput struct {
Policy objects.Ref
TargetRefs []TargetRef
Selectors []TargetSelector
// Lookup returns the cached object of a kind by namespace and name.
Lookup func(gk objects.GroupKind, ns, name string) (*unstructured.Unstructured, bool)
// Labelled reports whether some cached object of a kind in ns has every label in sel;
// an empty ns means every namespace.
Labelled func(gk objects.GroupKind, ns string, sel map[string]string) bool
// Served reports whether a kind is served by the API server and watched by the UI.
Served func(gk objects.GroupKind) bool
// ScopeKnown is false when the install's discovery scope is unknown (D-024).
ScopeKnown bool
// GlobalPolicyNamespace is the controller's KGW_GLOBAL_POLICY_NAMESPACE, empty when unset.
// GlobalPolicyNamespaceKnown is false when the UI cannot read it.
GlobalPolicyNamespace string
GlobalPolicyNamespaceKnown bool
}
TargetInput is one policy's targets and the lookups the rule may use (computed-rules "Policy targets").
type TargetRef ¶
type TargetRef struct {
Group, Kind, Name string
// SectionName is empty when not written.
SectionName string
}
TargetRef is a policy's spec.targetRefs entry as written. Its namespace is the policy's (GEP-713).
type TargetResult ¶
type TargetResult struct {
Index int
Ref TargetRef
Outcome string
// Verifiable is true when a current ancestor can be tied to this target alone (design §7.6).
Verifiable bool
}
TargetResult is one target's outcome. Index counts TargetRefs first, then Selectors; a selector's Ref carries its group, kind and section, with no name.
type TargetSelector ¶
type TargetSelector struct {
Group, Kind string
MatchLabels map[string]string
// SectionName is empty when not written.
SectionName string
}
TargetSelector is a policy's spec.targetSelectors entry as written.
type TargetStatusReporter ¶
type TargetStatusReporter interface {
ReportsTargetNotFound() bool
}
TargetStatusReporter is an optional interface of a Rules. ReportsTargetNotFound true means the controller writes TargetNotFound on policy ancestors, so KGWUI-016 comes from status, not PolicyTargeter.
type Uncertain ¶
type Uncertain struct {
Route objects.Ref
Rule, Ref int
Reason UnknownReason
}
Uncertain is an uncertain point (rules §8.5): a (route, rule, ref) that was cut by a bound or whose selection or context is unknown, or a route with Rule UncertainRoot or UncertainPossible, where Ref is -1.
type UnknownReason ¶
type UnknownReason string
UnknownReason says why a result could not be computed (rules §3.3).
const ( UnknownNamespaceLabels UnknownReason = "namespace-labels-unavailable" UnknownListenerSetStatus UnknownReason = "listenerset-no-status" UnknownSetting UnknownReason = "setting-unknown" UnknownNotReached UnknownReason = "not-reached" UnknownContext UnknownReason = "context-unknown" UnknownTooLarge UnknownReason = "too-large" // UnknownScope: the install's discovery scope is unknown (user, 2026-10-24). UnknownScope UnknownReason = "scope-unknown" )
Unknown reasons, as served on the wire.
type Unresolved ¶
type Unresolved string
Unresolved says why a delegation ref selects no routes (rules §5.2). It is a code; pkg/api renders the text.
const ( // UnresolvedMissing: no in-scope route matches the ref. UnresolvedMissing Unresolved = "missing" // UnresolvedUnwatched: a name ref's target exists outside the controller's scope. UnresolvedUnwatched Unresolved = "unwatched" )
Unresolved codes.
type Views ¶
type Views struct {
// RuleSet is the rule set's Version, Label its display name and Note its selection label.
RuleSet, Label, Note string
Attachment AttachmentResult
// Delegation is views B and C (rules §5, §6).
Delegation DelegationResult
Checks []CheckResult
}
Views are one install's computed views and their cross-checks (D-020). The engine sets each check's State, Mature and Since.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package kgw23 is the rule set for kgateway 2.3 controllers (rules §2).
|
Package kgw23 is the rule set for kgateway 2.3 controllers (rules §2). |
|
Package kgw24 is the rule set for kgateway 2.4 controllers (rules §2).
|
Package kgw24 is the rule set for kgateway 2.4 controllers (rules §2). |
|
Package kgw25 is the rule set for kgateway 2.5 controllers (rules §2).
|
Package kgw25 is the rule set for kgateway 2.5 controllers (rules §2). |
|
Package rulesets selects the computed rule set for a controller version (rules §2).
|
Package rulesets selects the computed rule set for a controller version (rules §2). |
|
Package viewa computes view A, spec-level Gateway API attachment (D-020 (A), rules §4): sectionName and port, allowedRoutes namespaces and kinds, and hostname intersection.
|
Package viewa computes view A, spec-level Gateway API attachment (D-020 (A), rules §4): sectionName and port, allowedRoutes namespaces and kinds, and hostname intersection. |