Documentation
¶
Overview ¶
Package install discovers kgateway controller installs, resolves the namespace scope each one watches, and assigns resources to installs.
Index ¶
- Constants
- func ClassOnlyID(controllerName string) string
- func NamespaceLabels(snap *cache.Snapshot) (labels map[string]map[string]string, ok bool)
- func ParsePinned(s string) (string, error)
- func ReportedEdge(child *objects.HTTPRouteView, parent objects.Ref, controllers []string) ([]*objects.RouteParentStatus, bool)
- func UpstreamExperimentalOnly(k kinds.Served, inst Install) bool
- func ValidateID(id string) error
- type AmbiguousGateway
- type Assignment
- type DeclaredCandidate
- type Detector
- type Install
- type NamespaceSelectorScope
- type Owned
- type OwnedObject
- type ProxyPodDetector
- type Resolved
- type Scope
- type ScopeMode
- type ScopeProvider
- type Setting
- type Settings
- type UnattachedRoute
- type UnwatchedRoute
- type UpstreamDetector
- func (UpstreamDetector) ControllerPodSelector() labels.Selector
- func (UpstreamDetector) ControllerSelector() labels.Selector
- func (UpstreamDetector) Detect(d *appsv1.Deployment) (Install, bool)
- func (UpstreamDetector) Name() string
- func (UpstreamDetector) ProxyPodSelector() labels.Selector
- func (UpstreamDetector) ProxySelector() labels.Selector
Constants ¶
const DiscoveryNamespaceSelectorsEnv = "KGW_DISCOVERY_NAMESPACE_SELECTORS"
DiscoveryNamespaceSelectorsEnv is the controller env var rendered from the Helm value discoveryNamespaceSelectors.
const ExperimentalEnv = "KGW_ENABLE_EXPERIMENTAL_GATEWAY_API_FEATURES"
ExperimentalEnv is the controller env var that enables experimental Gateway API features.
const GlobalPolicyEnv = "KGW_GLOBAL_POLICY_NAMESPACE"
GlobalPolicyEnv is the controller env var naming the namespace whose policies' targetSelectors match in every namespace.
const NotRead = "not read for this controller"
NotRead is the Setting.Reason of an install without a settings reader.
const SourceAssumed = "assumed"
SourceAssumed is the Scope.Source of an install without a scope provider.
const SourceDeploymentTemplate = "deployment template"
SourceDeploymentTemplate is the Scope.Source used when no controller Pod exists.
const UpstreamControllerName = "kgateway.dev/kgateway"
UpstreamControllerName is the GatewayClass controllerName of upstream kgateway, used by both the "kgateway" and "kgateway-waypoint" classes.
const WildcardAll = "all"
WildcardAll is the wildcard namespace's default: no namespace is special.
const WildcardEnv = "DELEGATION_WILDCARD_NAMESPACE"
WildcardEnv is the controller env var that names the namespace whose delegation label selects routes in every namespace.
Variables ¶
This section is empty.
Functions ¶
func ClassOnlyID ¶ added in v0.6.0
ClassOnlyID is the install ID of controllerName's class-only install: every byte outside A-Z a-z 0-9 . - becomes "~" and two hex digits, so distinct names get distinct IDs. "example.com/gateway" → "example.com~2Fgateway".
func NamespaceLabels ¶
NamespaceLabels returns the labels of every cached Namespace by name; ok is false when the Namespaces could not be read.
func ParsePinned ¶
ParsePinned turns an --install value into an install ID. It accepts the ID itself or "namespace/name", which becomes "<namespace>.<name>"; empty pins nothing.
func ReportedEdge ¶
func ReportedEdge(child *objects.HTTPRouteView, parent objects.Ref, controllers []string) ([]*objects.RouteParentStatus, bool)
ReportedEdge returns child's status entries that give it a reported edge to the HTTPRoute parent (design §4.2 conditions 2 and 3): each is from one of controllers, its parentRef resolves to parent, and it is eligible: a current spec parentRef equals it after defaults, or the spec list is empty. A child naming parent twice (by section or port) has one entry per ref. Freshness does not matter. Scope and ownership are the caller's to check.
func UpstreamExperimentalOnly ¶ added in v0.6.0
UpstreamExperimentalOnly is kgateway's experimental-only classification of served kind k for inst, from the table in pkg/kinds at inst's KgatewayVersion.
func ValidateID ¶
ValidateID reports whether id may be an install ID (D-016): one URL path segment of unreserved characters (A-Z a-z 0-9 . _ ~ -), and neither "." nor "..", which URL normalisation would remove.
Types ¶
type AmbiguousGateway ¶
AmbiguousGateway is a Gateway claimed by more than one install (KGWUI-009).
type Assignment ¶
type Assignment struct {
PerInstall map[string]*Owned
Ambiguous []AmbiguousGateway
Unwatched []UnwatchedRoute
}
Assignment maps resources to installs (design §4.3).
type DeclaredCandidate ¶
type DeclaredCandidate struct {
Route OwnedObject
Parent objects.ParentRef
}
DeclaredCandidate is an in-scope route whose current spec parentRef names an HTTPRoute of the install with no eligible status entry, current or stale (design §4.2). It is a diagnostic candidate, never a child.
type Detector ¶
type Detector interface {
Name() string
// ControllerSelector selects controller Deployments; the cache watches only these.
ControllerSelector() labels.Selector
// ControllerPodSelector selects the controller Pods the cache watches. It may
// be broader than the Pod labels of one chart version: Discover attributes
// Pods to an install through the Deployment's spec.selector.
ControllerPodSelector() labels.Selector
// ProxySelector selects the gateway proxy Deployments of this distribution.
ProxySelector() labels.Selector
// Detect returns the Install for d, or false if d is not this distribution's controller.
Detect(d *appsv1.Deployment) (Install, bool)
}
Detector recognises the controller Deployments of one distribution. Detectors are tried in order; the first that matches wins.
type Install ¶
type Install struct {
Namespace string
Name string
// CustomID, when set, is the install ID; empty means "<namespace>.<name>".
// It must pass ValidateID, or Discover leaves the install out (D-016).
CustomID string
// DisplayName names the install in the UI; empty means "namespace/name".
DisplayName string
Version string
// BaseVersion is the kgateway version a downstream build is based on, set by
// its detector; empty means unknown. Rule-set selection reads it.
BaseVersion string
// ReportedVersion is the version the controller reports in
// kgateway_build_info, without a leading "v"; empty when not reported.
// The engine sets it from the controller metrics.
ReportedVersion string
Edition string
ControllerNames []string
// Container is the name of the controller container (the source of the env-based settings).
Container string
Deployment *appsv1.Deployment
Pods []*corev1.Pod
MetricsPort int32
// ProxySelector selects this distribution's gateway proxy Deployments; Discover
// fills it from the detector when Detect leaves it nil.
ProxySelector labels.Selector
// Impl names the pack whose detector claimed the install; "" is the core.
Impl string
}
Install is one kgateway controller deployment and what the UI knows about it.
func ClassOnly ¶ added in v0.6.0
func ClassOnly(classes []*unstructured.Unstructured, claimed []Install) []Install
ClassOnly returns one class-only install per GatewayClass controllerName that no install in claimed lists: an install of a controller no pack recognises, known only from its classes (Phase 5 design §5). It has no workload, edition or version, and its Impl is "" (the core). Sorted by ID.
func Discover ¶
Discover returns one Install per controller Deployment in snap, sorted by ID. An install whose ID fails ValidateID is left out and reported in errs.
func (Install) ControllerVersion ¶
ControllerVersion is the version the UI shows for the controller: for kgateway, KgatewayVersion; a downstream build shows its own Version.
func (Install) Display ¶
Display returns DisplayName, else "namespace/name", else the ID when there is no namespace or name to show.
func (Install) ID ¶
ID returns the opaque install ID: CustomID, else "<namespace>.<name>". Namespace names hold no dots, so the Kubernetes ID is unique; clients must not rely on its structure (D-016).
func (Install) KgatewayVersion ¶
KgatewayVersion returns the kgateway version the controller runs, or "" when unknown: ReportedVersion when the controller reports one, else Version. Other distributions number their own releases (D-018 §3), so they report BaseVersion, which their detector may leave empty.
type NamespaceSelectorScope ¶
type NamespaceSelectorScope struct{}
NamespaceSelectorScope mirrors kgateway's discoveryNamespaceSelectors: a JSON list of label selectors read from the controller Pod env, OR'ed, where an empty or absent list means all namespaces.
func (NamespaceSelectorScope) Name ¶
func (NamespaceSelectorScope) Name() string
Name implements ScopeProvider.
func (NamespaceSelectorScope) Scope ¶
func (NamespaceSelectorScope) Scope(inst Install) Scope
Scope implements ScopeProvider. It reads the env from, in order: a Ready controller Pod, any controller Pod, then the Deployment's Pod template when no Pod exists (for example scaled to zero). A Pod comes first because it reflects what is running during a rollout; the template is only what will run.
type Owned ¶
type Owned struct {
GatewayClasses []*unstructured.Unstructured
Gateways []*unstructured.Unstructured
ListenerSets []*unstructured.Unstructured
Routes []OwnedObject
Policies []OwnedObject
// Listed are the in-scope objects of list-only kinds: counted and shown, never judged.
Listed []OwnedObject
Unattached []UnattachedRoute
// Declared holds one candidate per (route, parent HTTPRoute).
Declared []DeclaredCandidate
// NoParent are in-scope HTTPRoutes with empty spec.parentRefs and no
// status entry from the install's controllers. Not counted.
NoParent []OwnedObject
// Backends are the in-scope Backends that a backendRef of an owned route
// names by full identity ("in use", design §4.3).
Backends []*unstructured.Unstructured
// ReferencedBackends are the Backend refs of owned routes, in scope or
// not and whether they exist or not, once each.
ReferencedBackends []objects.Ref
// contains filtered or unexported fields
}
Owned is everything assigned to one install.
type OwnedObject ¶
type OwnedObject struct {
Kind kinds.Served
Obj *unstructured.Unstructured
// Parents are the route's current spec.parentRefs that resolve to a Gateway
// or ListenerSet of this install. Only their status entries
// are evaluated. Empty for policies.
Parents []objects.ParentRef
// RouteParents are the status parentRefs (after defaults) of the route's
// reported edges to HTTPRoutes of this install (design §4.2).
RouteParents []objects.ParentRef
}
OwnedObject is a route or policy together with its kind.
type ProxyPodDetector ¶
ProxyPodDetector is a Detector that selects its proxy Pods; without it the cache starts no proxy Pod watch for that distribution.
type Resolved ¶
type Resolved struct {
Install
Scope Scope
Settings Settings
// ExperimentalOnly is the install's pack hook for Experimental; nil marks no kind.
ExperimentalOnly func(k kinds.Served, inst Install) bool
// NoDelegation is set when the install's rule set computes no delegation:
// no route is a delegated child or a declared candidate, and a backendRef
// to an HTTPRoute is an ordinary ref (Phase 5 design §8.3).
NoDelegation bool
}
Resolved is an Install with its resolved Scope.
func Resolve ¶
func Resolve(insts []Install, p ScopeProvider) []Resolved
Resolve applies p, ReadSettings and UpstreamExperimentalOnly to every install: the kgateway resolution of callers from before packs.
func ResolveWith ¶ added in v0.6.0
func ResolveWith(insts []Install, implFor func(Install) (ScopeProvider, func(Install) Settings)) []Resolved
ResolveWith resolves each install with the scope provider and settings reader implFor returns for it. A nil provider assumes all namespaces; a nil reader leaves every setting unknown (Phase 5 design §5.3). ExperimentalOnly is left nil: no experimental-only kinds.
type Scope ¶
type Scope struct {
Mode ScopeMode `json:"mode"`
Selectors []metav1.LabelSelector `json:"selectors,omitempty"`
Err string `json:"error,omitempty"`
// Source says where the scope was read from, such as "pod <name>" or
// "deployment template"; empty for a hand-built Scope.
Source string `json:"source,omitempty"`
// contains filtered or unexported fields
}
Scope is the set of namespaces a controller install watches. A Scope built by hand (for example by a downstream ScopeProvider) needs only Mode and Selectors.
func ParseSelectors ¶
ParseSelectors parses the value of KGW_DISCOVERY_NAMESPACE_SELECTORS.
type ScopeMode ¶
type ScopeMode string
ScopeMode says how a Scope decides namespace membership.
const ( ScopeAll ScopeMode = "all" ScopeSelectors ScopeMode = "selectors" // ScopeUnknown means the scope could not be determined. Contains then // answers as if all namespaces were in scope so the UI still shows data, // and the health report is forced to "unknown" (design §5.3). ScopeUnknown ScopeMode = "unknown" )
Scope modes.
type ScopeProvider ¶
ScopeProvider resolves the scope of an install (D-009). Downstreams may register their own.
type Setting ¶
type Setting struct {
Value string
// Known is false when the UI cannot tell the value; Reason then says why.
Known bool
Reason string
// Source is where the value was read, as in Scope.Source.
Source string
}
Setting is one controller setting as read from its container env.
type Settings ¶
type Settings struct {
Experimental Setting
// WildcardNamespace is the delegation wildcard namespace; "all" when absent or empty.
WildcardNamespace Setting
// GlobalPolicyNamespace is the global policy namespace; "" when absent or empty: none.
GlobalPolicyNamespace Setting
}
Settings are the controller settings the UI reads.
func ReadSettings ¶
ReadSettings reads the controller settings from the same source as Scope (D-015). An absent experimental entry means "true", the controller's default; an absent or empty wildcard entry means "all"; an absent global policy namespace means none.
type UnattachedRoute ¶
type UnattachedRoute struct {
Route OwnedObject
Parent objects.ParentRef
}
UnattachedRoute is a route in an install's scope whose parentRef names a Gateway or ListenerSet that does not exist. It is a diagnostic candidate for KGWUI-003 and is not counted as owned.
type UnwatchedRoute ¶
type UnwatchedRoute struct {
Install string
Route objects.Ref
// Gateway is the owned parent named: a Gateway, ListenerSet or HTTPRoute.
Gateway objects.Ref
}
UnwatchedRoute is a route that targets a parent of Install from a namespace that Install does not watch (KGWUI-004).
type UpstreamDetector ¶
type UpstreamDetector struct{}
UpstreamDetector recognises upstream kgateway controllers: Helm labels kgateway=kgateway and app.kubernetes.io/component=controller, and an image whose repository name is "kgateway" (mirrors keep that name).
func (UpstreamDetector) ControllerPodSelector ¶
func (UpstreamDetector) ControllerPodSelector() labels.Selector
ControllerPodSelector implements Detector. Controller Pods carry the component label only from chart v2.3.0 on, so the watch uses kgateway=kgateway.
func (UpstreamDetector) ControllerSelector ¶
func (UpstreamDetector) ControllerSelector() labels.Selector
ControllerSelector implements Detector.
func (UpstreamDetector) Detect ¶
func (UpstreamDetector) Detect(d *appsv1.Deployment) (Install, bool)
Detect implements Detector.
func (UpstreamDetector) ProxyPodSelector ¶
func (UpstreamDetector) ProxyPodSelector() labels.Selector
ProxyPodSelector implements ProxyPodDetector with the proxy Pod template's labels; the Deployment's managed-by label is not on the Pods.
func (UpstreamDetector) ProxySelector ¶
func (UpstreamDetector) ProxySelector() labels.Selector
ProxySelector implements Detector.