Documentation
¶
Overview ¶
Package extension is the public seam through which downstream distributions extend the UI backend without forking it (D-003). A downstream main calls app.Run with options from this package.
Compatibility ¶
API v1 (the /api/v1 paths and their JSON) and the SPA URLs are stable from the first release. This Go API (this package and the types it carries) changes only with a README upgrade note and a release-note entry. The 3.1 check-contract change is the last planned break; later additions are optional interfaces, detected by type assertion. When the provider seam arrives, a Kubernetes Detector keeps working as that provider's adapter (D-016).
Index ¶
- Constants
- type Collector
- type CollectorEnv
- type Deps
- type Impl
- type Option
- func WithAuthorizer(a api.Authorizer) Option
- func WithCapabilities(f func() []api.Capability) Option
- func WithChecks(prefix string, c ...health.Check) Option
- func WithCollectors(c ...Collector) Option
- func WithCommands(c diagnose.Commands) Option
- func WithComputedRules(f func(controllerVersion string) computed.Selection) Option
- func WithDetectors(d ...install.Detector) Option
- func WithHandlers(name string, f func(r Router, d Deps)) Option
- func WithKinds(d ...kinds.Descriptor) Option
- func WithPack(p Pack) Option
- func WithProcessSource(s process.Source) Option
- func WithProxyModeResolver(p proxymode.Resolver) Option
- func WithProxyStatsSource(s proxystats.Source) Option
- func WithScopeProvider(p install.ScopeProvider) Option
- func WithScopeVerifier(v scopeverify.Verifier) Option
- type Pack
- type Registry
- func (r *Registry) CapabilityStates() []api.Capability
- func (r *Registry) CheckCapabilities(platformNames []string) error
- func (r *Registry) ChecksFor(impl string) []health.Check
- func (r *Registry) Collectors() []Collector
- func (r *Registry) Err() error
- func (r *Registry) FeaturesFor(i install.Install) []string
- func (r *Registry) ImplFor(i install.Install) Impl
- func (r *Registry) KindAppliesTo(i install.Install, gk objects.GroupKind) bool
- func (r *Registry) Mounts(d Deps) ([]api.ExtMount, error)
- func (r *Registry) PackCollectors(env CollectorEnv) []Collector
- func (r *Registry) Packs() []string
- func (r *Registry) RunCollectors(ctx context.Context, d Deps, s *collect.Store)
- type Router
Constants ¶
const UpstreamPrefix = "KGWUI-"
UpstreamPrefix is the finding-code prefix reserved for upstream checks.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Collector ¶
type Collector interface {
Name() string
// Start runs until ctx is done, publishing through d.Publish and d.Fail.
// An error return is logged once; the collector is not restarted and its
// values turn unavailable.
Start(ctx context.Context, d Deps) error
}
Collector is a long-running source of values for checks (design §4.1 gap 2), such as a scraper or a prober. Name follows the WithHandlers rules.
type CollectorEnv ¶ added in v0.6.0
type CollectorEnv struct {
// Kube reads Pods, their logs and, outside the cluster, pods/proxy.
Kube kubernetes.Interface
// InCluster reads Pod IPs directly; otherwise through pods/proxy.
InCluster bool
// Scraper replaces the controller metrics scraper InCluster selects; nil keeps it.
Scraper ctrlmetrics.Scraper
// Interval is the collection interval; MaxAge, 3 × Interval, is when a value is stale.
Interval, MaxAge time.Duration
// Clock drives the collectors; nil means the real clock.
Clock clock.WithTicker
// Installs and Current return the published model's installs and the model.
Installs func() []install.Install
Current func() *engine.Published
// Discovered is closed after the first model with an install over a settled cache.
Discovered <-chan struct{}
// Collected is the store the collectors publish to; one may read another's values.
Collected *collect.Store
// NoProxyStats turns proxy stats off; ControllerLogs turns log reading on.
NoProxyStats, ControllerLogs bool
// Pack is the pack's name and Impl its hooks, read when the app is built.
Pack string
Impl Impl
}
CollectorEnv is what the app builds a pack's collectors with (Phase 5 design §7.1). A factory only builds, so it may get a zero CollectorEnv to tell its name; the collector starts in Start.
type Deps ¶
type Deps struct {
// Current returns the published model, nil before the first publication.
// A handler calls it once per request and serves from that value.
Current func() *engine.Published
// Authorizer is the registry's; filter objects with api.Visible.
Authorizer api.Authorizer
// Capabilities returns the states every WithCapabilities source reports now,
// in registration order; /api/v1/meta lists the same.
Capabilities func() []api.Capability
// Logger carries the extension's name.
Logger *slog.Logger
// Publish stores value under "<collector name>/<key>" and hands it over:
// the collector never mutates it afterwards. ttl 0 means no expiry. Nil for handlers.
Publish func(key string, value any, fingerprint uint64, ttl time.Duration)
// Fail marks a collector key failing or off with a reason. Nil for handlers.
Fail func(key string, st collect.State, reason string)
}
Deps is what the app gives an extension's handlers (design §4.1 gap 1).
type Impl ¶ added in v0.6.0
type Impl struct {
Scope install.ScopeProvider
Verifier scopeverify.Verifier
Settings func(install.Install) install.Settings
RulesFor func(version string) computed.Selection
// Version is the install's implementation version, the input of RulesFor.
Version func(install.Install) string
// Reported reads the version the controller reports from the collected
// values; false keeps the last one (engine.Hooks.Reported).
Reported func(install.Install, collect.Snapshot) (string, bool)
// ExperimentalOnly reports whether the controller watches served kind k only
// with experimental Gateway API features on.
ExperimentalOnly func(k kinds.Served, inst install.Install) bool
ProxyMode proxymode.Resolver
Process process.Source
ProxyStats proxystats.Source
Commands diagnose.Commands
// Conditions are the implementation's condition types beyond Gateway API's.
Conditions health.ConditionTypes
}
Impl is one pack's per-install hooks, used for the installs its detectors claim (Phase 5 design §4.2). A nil hook is the core's: all namespaces assumed in scope, no settings read, no version, no experimental-only kinds, no scope verification, no processes, every proxy managed and the API's default commands.
type Option ¶
type Option func(*Registry)
Option modifies a Registry.
func WithAuthorizer ¶
func WithAuthorizer(a api.Authorizer) Option
WithAuthorizer replaces the default api.AllowAll. Every API response with resources, findings or counts goes through it (D-013).
func WithCapabilities ¶
func WithCapabilities(f func() []api.Capability) Option
WithCapabilities adds a source of capability states for /api/v1/meta. A capability that is on is also listed in capabilities. Names must not collide with core, platform or other extension capabilities; app.Build calls each source once to check, so a source must report a stable set of names. Sources run on every /api/v1/meta request: keep them fast and safe for concurrent use.
func WithChecks ¶
WithChecks adds health checks to the default pack (kgateway in New, the core in NewCore); by convention their finding codes start with prefix, such as "ACME-". A reserved or repeated prefix adds nothing and Registry.Err reports it.
func WithCollectors ¶
WithCollectors adds collectors that the app starts after the cache. Names are unique among collectors; "proxy-stats" is the core collector's and app.Build rejects it. A rejected name is reported by Registry.Err.
func WithCommands ¶
WithCommands replaces diagnose.Kubectl, for a platform without kubectl or with its own commands. A method that returns "" hides that step.
func WithComputedRules ¶
WithComputedRules sets the rule-set choice of the default pack (in New, the kgateway pack's rulesets.Select). A downstream distribution maps its controller to a rule set; a build that is not the kgateway edition receives its BaseVersion, "" when unknown (D-018 §3).
func WithDetectors ¶
WithDetectors adds install detectors for the default pack. They are tried before the detectors already registered, so a downstream can claim Deployments the upstream one would also match.
func WithHandlers ¶
WithHandlers adds endpoints under /api/ext/{name}/; f registers them when the app is built. name is a lowercase letter, then up to 62 lowercase letters, digits or dashes, and registers once. A rejected name, and a pattern that is malformed or leaves the prefix, is reported by Registry.Err or app.Build.
func WithKinds ¶
func WithKinds(d ...kinds.Descriptor) Option
WithKinds adds kinds to watch, count and serve. Kinds are unique by group and kind: a descriptor for a registered kind replaces it in place.
func WithPack ¶ added in v0.6.0
WithPack adds p: its kinds, its detectors (tried before those already registered) and its checks. The first pack added becomes the default pack (kgateway in New): the old hook options, WithDetectors and the Registry hook fields set its hooks, whatever their order. A later pack keeps p.Impl. A pack name that is empty or already registered adds nothing, and a collector whose name is invalid or another pack's is dropped; Registry.Err reports both.
func WithProcessSource ¶
WithProcessSource replaces process.Kube, for example to add extension Pods or to report processes that do not run in Pods.
func WithProxyModeResolver ¶
WithProxyModeResolver replaces the upstream GatewayParameters resolution.
func WithProxyStatsSource ¶
func WithProxyStatsSource(s proxystats.Source) Option
WithProxyStatsSource replaces proxystats.Kube, for example for proxies that do not run in Pods or another stats format. The core collector keeps the interval, bounds, concurrency and publishing.
func WithScopeProvider ¶
func WithScopeProvider(p install.ScopeProvider) Option
WithScopeProvider replaces the scope provider.
func WithScopeVerifier ¶
func WithScopeVerifier(v scopeverify.Verifier) Option
WithScopeVerifier replaces the scope verifier.
type Pack ¶ added in v0.6.0
type Pack struct {
Name string
Kinds []kinds.Descriptor
Detectors []install.Detector
Impl Impl
Checks []health.Check
// Collectors build the pack's collectors when the app is built. Their names
// are reserved: a WithCollectors collector cannot take them.
Collectors []func(CollectorEnv) Collector
// Features are the UI features the pack's installs support (api.Feature*);
// the API drops computed and delegation where the rule set lacks them.
Features []string
}
Pack is one implementation's contributions to the core. Its Name is stamped on each install its detectors claim (install.Install.Impl).
type Registry ¶
type Registry struct {
Kinds []kinds.Descriptor
Detectors []install.Detector
Scope install.ScopeProvider
// Verifier checks scope against the controller. Nil means the upstream
// verifier for kgateway installs, which the app sizes from the metrics
// interval; any other install gets none.
Verifier scopeverify.Verifier
Checks []health.Check
// Authorizer decides per request what the caller may see (D-013).
Authorizer api.Authorizer
// ProxyMode decides whether a Gateway's proxy is self-managed. It mirrors
// controller logic, so a downstream with its own parameters kind replaces it.
ProxyMode proxymode.Resolver
// RulesFor selects the computed rule set for a controller's kgateway
// version, "" when unknown (D-020).
RulesFor func(controllerVersion string) computed.Selection
// Process reports each install's controller and proxy processes (D-016).
Process process.Source
// ProxyStats finds proxies and reads their stats (design §8.8); nil means
// proxystats.Kube over the app's clients.
ProxyStats proxystats.Source
// Commands fills in the next-step commands (design §8.5).
Commands diagnose.Commands
// contains filtered or unexported fields
}
Registry holds everything the backend is built from. Its hook fields (Scope, Verifier, ProxyMode, RulesFor, Process, ProxyStats, Commands) are the hooks of the default pack: kgateway in New, the core in NewCore (see WithPack).
func New ¶
New returns the core plus the kgateway pack, with opts applied. The kinds and checks keep the order of kinds.Upstream and health.Upstream.
func NewCore ¶ added in v0.6.0
NewCore returns the core alone, with opts applied: Gateway API kinds, no detectors, the core checks and no pack hooks.
func (*Registry) CapabilityStates ¶
func (r *Registry) CapabilityStates() []api.Capability
CapabilityStates returns what every source reports now, in registration order.
func (*Registry) CheckCapabilities ¶
CheckCapabilities reports a capability name that collides with a core one or the platform's platformNames, or another source.
func (*Registry) ChecksFor ¶ added in v0.6.0
ChecksFor returns the checks that run on installs of pack impl, in registration order: the core's and that pack's. WithChecks adds checks to the default pack, so they run on its installs.
func (*Registry) Collectors ¶
Collectors returns the registered collectors, in order.
func (*Registry) Err ¶
Err returns the registration errors joined, or nil. app.Build returns it before it starts anything.
func (*Registry) FeaturesFor ¶ added in v0.6.0
FeaturesFor returns the UI features of the pack that claimed i; none for the core.
func (*Registry) ImplFor ¶ added in v0.6.0
ImplFor returns the hooks of the pack that claimed i, read from the Registry fields for the default pack. An install no registered pack claims, such as a class-only install, gets the core's hooks.
func (*Registry) KindAppliesTo ¶ added in v0.6.0
KindAppliesTo reports whether served kind gk applies to install i: a pack's own kind applies only to that pack's installs, every other kind to all.
func (*Registry) Mounts ¶
Mounts runs every WithHandlers function with d, its Logger tagged with the extension's name, and returns the endpoints for api.WithExtMounts. It returns an error if any endpoint fails api.CheckExtMounts.
func (*Registry) PackCollectors ¶ added in v0.6.0
func (r *Registry) PackCollectors(env CollectorEnv) []Collector
PackCollectors builds every pack's collectors with env, in registration order, each with its pack's name and hooks.