install

package
v0.7.0 Latest Latest
Warning

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

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

Documentation

Overview

Package install discovers kgateway controller installs, resolves the namespace scope each one watches, and assigns resources to installs.

Index

Constants

View Source
const DiscoveryNamespaceSelectorsEnv = "KGW_DISCOVERY_NAMESPACE_SELECTORS"

DiscoveryNamespaceSelectorsEnv is the controller env var rendered from the Helm value discoveryNamespaceSelectors.

View Source
const ExperimentalEnv = "KGW_ENABLE_EXPERIMENTAL_GATEWAY_API_FEATURES"

ExperimentalEnv is the controller env var that enables experimental Gateway API features.

View Source
const GlobalPolicyEnv = "KGW_GLOBAL_POLICY_NAMESPACE"

GlobalPolicyEnv is the controller env var naming the namespace whose policies' targetSelectors match in every namespace.

View Source
const NotRead = "not read for this controller"

NotRead is the Setting.Reason of an install without a settings reader.

View Source
const SourceAssumed = "assumed"

SourceAssumed is the Scope.Source of an install without a scope provider.

View Source
const SourceDeploymentTemplate = "deployment template"

SourceDeploymentTemplate is the Scope.Source used when no controller Pod exists.

View Source
const SourceNotObserved = "controller not observed"

SourceNotObserved is the Scope.Source of an install whose controller a namespace-scoped snapshot does not show, as opposed to one known to be outside it.

View Source
const UpstreamControllerName = "kgateway.dev/kgateway"

UpstreamControllerName is the GatewayClass controllerName of upstream kgateway, used by both the "kgateway" and "kgateway-waypoint" classes.

View Source
const WildcardAll = "all"

WildcardAll is the wildcard namespace's default: no namespace is special.

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

func ClassOnlyID(controllerName string) string

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

func NamespaceLabels(snap *cache.Snapshot) (labels map[string]map[string]string, ok bool)

NamespaceLabels returns the labels of every cached Namespace by name; ok is false when the Namespaces could not be read.

func ParsePinned

func ParsePinned(s string) (string, error)

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

func UpstreamExperimentalOnly(k kinds.Served, inst Install) bool

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

func ValidateID(id string) error

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

type AmbiguousGateway struct {
	Gateway  objects.Ref
	Installs []string
}

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

func Assign

func Assign(snap *cache.Snapshot, served []kinds.Served, insts []Resolved, dec objects.Decoder) Assignment

Assign assigns the snapshot's resources to insts. References are resolved by full group/kind/namespace/name identity. HTTPRoutes are decoded through dec; nil decodes directly.

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

func Discover(snap *cache.Snapshot, detectors []Detector) (out []Install, errs []error)

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

func (i Install) ControllerVersion() string

ControllerVersion is the version the UI shows for the controller: for kgateway, KgatewayVersion; a downstream build shows its own Version.

func (Install) Display

func (i Install) Display() string

Display returns DisplayName, else "namespace/name", else the ID when there is no namespace or name to show.

func (Install) ID

func (i Install) ID() string

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

func (i Install) KgatewayVersion() string

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

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.

func (*Owned) Route

func (o *Owned) Route(ref objects.Ref) (*OwnedObject, bool)

Route returns the owned route ref, if any.

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

type ProxyPodDetector interface {
	ProxyPodSelector() labels.Selector
}

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.

func (Resolved) Experimental added in v0.6.0

func (r Resolved) Experimental(k kinds.Served) bool

Experimental reports whether r's controller watches served kind k only with experimental Gateway API features on.

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

func ParseSelectors(raw string) Scope

ParseSelectors parses the value of KGW_DISCOVERY_NAMESPACE_SELECTORS.

func (Scope) Contains

func (s Scope) Contains(nsName string, ns *corev1.Namespace) bool

Contains reports whether namespace nsName (with object ns, which may be nil if the namespace is not cached yet) is in scope.

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

type ScopeProvider interface {
	Name() string
	Scope(inst Install) Scope
}

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.

func (Setting) Bool

func (s Setting) Bool() (v, known bool)

Bool parses the value. An unknown or unparsable value is not known.

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

func ReadSettings(inst Install) Settings

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

Detect implements Detector.

func (UpstreamDetector) Name

func (UpstreamDetector) Name() string

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

Jump to

Keyboard shortcuts

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