cache

package
v0.0.0-...-8cfec81 Latest Latest
Warning

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

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

Documentation

Overview

Package cache manages Envoy xDS snapshot resources for the agent.

It wraps go-control-plane's SnapshotCache and maintains a map-based cache of Envoy resources (listeners, clusters, endpoints, virtual hosts) with per-resource-type locking for thread-safe incremental updates. When the cache is modified, snapshots are regenerated and pushed to the xDS server.

The cache organizes listeners by pod container network namespace and clusters by service name. Each listener entry holds inbound and outbound listeners for a pod. Each cluster entry holds the cluster definition, pre-built load assignment (with endpoints keyed by IP for granular add/remove), and virtual host for routing.

Snapshot generation is incremental: listeners and clusters maintain separate snapshot versions. The version string format is "timestamp.counter.label" (e.g., "1704067200000.42.listener"), where timestamp is Unix milliseconds, counter is an atomic increment, and label identifies the resource type.

Index

Constants

View Source
const (
	QUICRefusedMalformed       = "malformed_name"
	QUICRefusedNotInDependency = "destination_not_in_dependency_set"
	QUICRefusedSourceNotOnNode = "source_not_local"
)

Refusal reasons for an on-demand `quic:` request, as logged and counted.

View Source
const (
	// CaptureInputProjection is the mesh-Service projection (CaptureProjected).
	CaptureInputProjection = "projection"
	// CaptureInputServiceRange is the Service range (ServiceRangeDelivered).
	CaptureInputServiceRange = "service_range"
)

The capture-listener inputs MissingCaptureInputs names.

View Source
const DefaultQUICPairFetchWindow = time.Hour

DefaultQUICPairFetchWindow is how long after an agent start a persisted QUIC pair with no evidence of use may stay before it is pruned (issues #1033, #1073; --east-west-quic-pair-fetch-window).

View Source
const ObservedUpstreamsFile = "state/observed-upstreams.json"

ObservedUpstreamsFile is the path of the persisted observed demand set (issue #701), RELATIVE to the agent's local storage directory (--mounted-registry-dir, the same host-persistent directory the CNI pod records live in).

It sits in a subdirectory on purpose: the storage package treats every top-level "*.json" in that directory as one CNI pod record (loadAll) and the ghost sweep prunes pod records it cannot match to a live container, so a file dropped beside them would be parsed as an empty pod and then deleted.

Variables

View Source
var ErrWatchNotAnswered = errors.New("an open watch was not answered from it")

ErrWatchNotAnswered is what a snapshot build returns when the snapshot is INSTALLED, and is the one every later request is answered from, but handing its changes to a watch that was open did not finish in watchAnswerWait (generateSnapshot says when). The cache's state and its reports are those of a build that returned nil; what differs is that a proxy may not have been sent the change yet. Every mutator that returns a build's error returns this one wrapped, so a caller can tell it from a snapshot that was not built:

if err := c.AddPod(ctx, pod, td); err != nil && !errors.Is(err, cache.ErrWatchNotAnswered) { ... }

Functions

This section is empty.

Types

type EdgeGatewayEntry

type EdgeGatewayEntry struct {
	// Namespace is the Gateway's Kubernetes namespace.
	Namespace string
	// Name is the Gateway's name.
	Name string
	// Listeners is the per-listener port allocations and TLS config.
	Listeners []EdgeGatewayListenerEntry
	// VirtualHosts are the HTTPRoute virtual hosts attached to this Gateway.
	VirtualHosts []VirtualHost
	// EdgeConfig is the effective edge-hardening/HTTP3 config for THIS Gateway
	// (proposal 029): GatewayClass.parametersRef default ⊕ Gateway
	// infrastructure.parametersRef override, resolved by the reconciler. Nil = the
	// compiled best-practice defaults (ApplyEdgeHardening handles nil).
	EdgeConfig *configv1.EdgeConfigSpec
}

EdgeGatewayEntry is the cache's per-Gateway routing data for proposal 021 Phase 2. Each entry maps to one per-Gateway LoadBalancer Service and a set of per-listener Envoy listeners bound on InternalPorts.

type EdgeGatewayListenerEntry

type EdgeGatewayListenerEntry struct {
	// ExternalPort is the Gateway listener's declared external port (e.g. 80, 443).
	ExternalPort uint32
	// InternalPort is the unique container port allocated for this (Gateway, listener).
	InternalPort uint32
	// TLSSecretNames are the SDS cert names for downstream TLS (empty = plain HTTP).
	TLSSecretNames []string
	// HTTPRedirect when true means this listener emits an HTTP→HTTPS 301 redirect
	// instead of serving routes directly.
	HTTPRedirect bool
}

EdgeGatewayListenerEntry describes one listener port within a per-Gateway entry. ExternalPort is the Gateway listener's declared port (e.g. 80 or 443). InternalPort is the container port allocated by the port allocator that the per-Gateway LoadBalancer Service maps ExternalPort → InternalPort.

type EdgeTLSCert

type EdgeTLSCert struct {
	Cert []byte
	Key  []byte
}

EdgeTLSCert is raw certificate material for an edge downstream TLS secret, keyed by its provider-prefixed SDS name.

type QUICTwinDecision

type QUICTwinDecision int

QUICTwinDecision is what the agent did with an on-demand request for a `quic:` twin.

const (
	// QUICTwinRefused: the name is malformed, or names a destination that is
	// not in the dependency set, or a source that is not a local
	// ServiceAccount. Nothing is recorded; the proxy's paused request
	// fails at the on_demand timeout (503 NC).
	QUICTwinRefused QUICTwinDecision = iota
	// QUICTwinKnown: the pair was already observed; the twin is (or is about
	// to be) in the snapshot.
	QUICTwinKnown
	// QUICTwinAdded: a new pair; a snapshot carrying its twin and the twin's
	// load assignment is being generated.
	QUICTwinAdded
)

type Route

type Route struct {
	Prefix           string
	Exact            string
	Service          string
	Port             uint32
	BackendNamespace string
	// DialPort is the cleartext STRICT_DNS dial port for the legacy single-backend
	// path (mirrors RouteBackend.DialPort). Zero = dial Port. See RouteBackend.DialPort.
	DialPort uint32
	// Backends is the weighted backend list for this rule. A single-element list
	// is equivalent to the legacy Service/Port/BackendNamespace fields. An empty
	// Backends with a non-empty Service falls back to the legacy single-backend
	// path so old callers remain compatible.
	Backends       []RouteBackend
	HeaderMutation *proxy.GammaHeaderMutation
	Redirect       *proxy.GammaRedirect
	URLRewrite     *proxy.GammaURLRewrite

	// Headers are the per-header exact/regex predicates for this match.
	// All entries must match (AND semantics within one HTTPRouteMatch).
	Headers []proxy.RouteHeaderMatch
	// Method is the HTTP method that must match (e.g. "GET"). Empty = any method.
	Method string
	// QueryParams are the per-parameter exact/regex predicates for this match.
	QueryParams []proxy.RouteQueryParamMatch

	// DirectResponseStatus, when non-zero, causes the route to emit a fixed
	// HTTP direct_response with this status (no backend routing). Set to 500
	// for rules whose backendRef(s) cannot be resolved (BackendNotFound /
	// InvalidKind / RefNotPermitted per Gateway API).
	DirectResponseStatus uint32

	// Timeout is the per-route request timeout from the HTTPRoute rule's
	// timeouts.request field (GEP-2257 duration). Nil means no timeout is applied
	// on this route (Envoy inherits the listener/cluster default). When set it is
	// applied as RouteAction.timeout on the forwarding route.
	Timeout *durationpb.Duration
}

Route is one path-match -> backend rule within a VirtualHost. Exactly one of Prefix/Exact is set. HeaderMutation carries the merged request/response header modifier filters for this rule (nil = no header mutations). When Redirect is non-nil the route returns a redirect response (no backend). When URLRewrite is non-nil the route rewrites the request URL before forwarding.

Backends holds the weighted backend list for this rule. When populated, BuildEdgeRoute emits a weighted_clusters action (multiple backends) or a plain single-cluster action (one backend). Backends supersedes the legacy Service/Port/BackendNamespace fields; all three are populated for backward compatibility when there is exactly one backend so existing single-backend code paths continue to work.

BackendNamespace is the namespace of the (first) backendRef (defaults to the route's own namespace when not set by the reconciler). Used to build the k8s- Service FQDN for non-mesh (cleartext) backends when Backends is not set.

Headers, Method, QueryParams carry the additional match predicates from Gateway API HTTPRouteMatch: within one Match all predicates are ANDed. Headers maps to Envoy RouteMatch.headers; Method maps to a :method header matcher; QueryParams maps to RouteMatch.query_parameters.

DirectResponseStatus, when non-zero, causes the route to emit a fixed direct_response with that HTTP status code (no backend). Used to implement Gateway API semantics for rules whose all backends are unresolvable (ResolvedRefs=False): the data plane must return 500.

type RouteBackend

type RouteBackend struct {
	Service          string
	BackendNamespace string
	Port             uint32
	// Weight is the Gateway API backendRef weight. Defaults to 1 when unset.
	// The Envoy weighted_clusters total_weight is the sum of all backend weights
	// within the rule. Weight 0 = backend receives no traffic.
	Weight uint32
	// DialPort is the TCP port a non-mesh (cleartext STRICT_DNS) cluster actually
	// connects to. It differs from Port for a HEADLESS Service: the Service FQDN
	// resolves directly to pod IPs (no kube-proxy in the path to remap the port), so
	// the edge must dial the Service's numeric targetPort, not its service port.
	// For a ClusterIP Service the FQDN resolves to the ClusterIP and kube-proxy
	// DNATs port->targetPort, so DialPort == Port. Zero means "same as Port" (the
	// reconciler leaves it 0 when no Service-type-specific remap is needed); the
	// cluster builder falls back to Port. The cluster NAME stays keyed by Port so
	// route->cluster names remain stable regardless of the resolved dial port.
	DialPort uint32
}

RouteBackend is one weighted backend within an HTTPRoute rule. It corresponds to one element of backendRefs with its resolved service name, namespace, port, and weight. Weight 0 means the backend receives no traffic but is still a valid entry (per Gateway API — a zero-weight backend is not an error).

type SnapshotCache

type SnapshotCache struct {
	cachev3.SnapshotCache
	// contains filtered or unexported fields
}

SnapshotCache wraps go-control-plane's SnapshotCache and manages Envoy xDS resources for a single node agent. It maintains separate maps of listeners (keyed by pod container network namespace) and clusters (keyed by service name) with per-resource-type RWMutex locks for thread-safe incremental updates.

Listeners and clusters are cached separately to allow independent snapshot generation. Snapshots are versioned using timestamps and atomic counters to track changes. SnapshotCache is safe for concurrent use.

func NewSnapshotCache

func NewSnapshotCache(nodeName string, log *slog.Logger) *SnapshotCache

NewSnapshotCache creates and returns a new SnapshotCache for the given node. The nodeName is used as the xDS node identifier when updating snapshots.

func (*SnapshotCache) AddPod

func (c *SnapshotCache) AddPod(ctx context.Context, cniPod *cniv1.CNIPod, trustDomain string) error

func (*SnapshotCache) AwaitingClientCertificates

func (c *SnapshotCache) AwaitingClientCertificates() int

AwaitingClientCertificates is how many local workload identities the most recently BUILT snapshot held out of east-west QUIC -- no selection arm, no `quic:` twin -- because SPIRE had not delivered their client certificate yet (issue #1049). 0 before the first build.

The xDS server's first serve after an agent restart waits (bounded) for it to reach 0 (issue #1103): a proxy reconnecting to a snapshot built before the SPIRE bridge caught up is told to REMOVE every twin it holds, and routes into the gap until the certificate's snapshot re-adds them.

func (*SnapshotCache) CaptureInputsReady

func (c *SnapshotCache) CaptureInputsReady() <-chan struct{}

CaptureInputsReady returns a channel closed once every input the capture listener is built from has been delivered at least once: the mesh-Service projection (CaptureProjected) and the Service range (ServiceRangeDelivered). The xDS server holds its first serve on it (bounded; AgentXdsServer.SetCaptureGate).

The range is part of it because the listener's cap_passthrough_svc chain (proposal 044) exists only while a range is known. A restarted agent that served before its ServiceCIDR reconciler had run would publish a listener without that chain over the proxy's listener that has it: the chain is drained, and every connection on it closed when the drain ends.

func (*SnapshotCache) CaptureProjected

func (c *SnapshotCache) CaptureProjected() <-chan struct{}

CaptureProjected returns a channel closed once the mesh-Service reconciler has delivered its first SetCaptureTCPServices projection (#1094).

That projection defines which per-VIP and per-port TCP chains the capture listener carries. A snapshot served before it would replace a restarted agent's still-correct listener in Envoy with one that has none of them, so the xDS server holds its first serve on this (bounded; see AgentXdsServer.SetCaptureGate). Closed, not sent on: any number of waiters.

func (*SnapshotCache) CloseOnDemandStream

func (c *SnapshotCache) CloseOnDemandStream(streamID int64)

CloseOnDemandStream drops every on-demand subscription held by a delta stream that ended. The proxy re-establishes the ones it still needs from real demand on the new stream; anything nobody asks for again ages out on the idle TTL, which is what keeps demand scoping honest across a proxy or agent restart.

func (*SnapshotCache) CloseQUICStream

func (c *SnapshotCache) CloseQUICStream(ctx context.Context, streamID int64) int

CloseQUICStream is the end of an xDS stream (issue #1052). If another stream is live, the ended one was a proxy generation that exited -- the draining parent of a hot restart, which after an agent restart may well have re-subscribed twins the child never held -- so the subscriptions it vouched for are dropped, not kept, and a dormant pair no live stream holds is pruned. If it was the last live stream nothing is concluded (the proxy may be reconnecting); the next fresh stream's re-statement decides. Returns how many dormant pairs were pruned.

func (*SnapshotCache) ClustersAccepted

func (c *SnapshotCache) ClustersAccepted(ctx context.Context, accepted ack.Accepted)

ClustersAccepted records what one answered cluster (CDS) response says the proxy holds, and writes the pin state of the clusters the proxy has accepted as the aether.agent.xds.acked_tls_clusters gauge (#1425, #1508).

reportClusterPins says what the agent PUBLISHED. This says what a proxy accepted, which is the closest the agent gets to what the proxy holds without asking its admin interface. The two differ while an update is in flight, and they stay different for as long as the proxy rejects a cluster.

It is kept per cluster (ackedPins), from two things a proxy says:

  • An ACK is about the clusters its response carried, and no other: each is now held at the version it was sent at, each removed one is gone. A cluster the proxy REJECTED stays at the version it last accepted, or at none, through every later ACK, until a response that carries it is acknowledged. The pinned go-control-plane does not send it again on that stream unless it changes (#1510).
  • The first cluster request of a stream states every cluster the proxy holds, by version, and the answer to the first response settles the whole set (ack.Accepted). That is what gives a restarted agent its sample from a proxy that is already in sync (#1483), and what corrects the record after a stream is lost with an answer in flight.

A version is a hash of the cluster's bytes, so "the proxy accepted version V" is "the proxy accepted exactly the cluster this agent published as V", and its pin class is the one the last snapshot that published V counted it under.

What it cannot know, by construction:

  • Nothing is written until a proxy answers this agent process: absent means "not known since this agent started".
  • The class of a version this process never published. A proxy that was rejecting a cluster update when the agent restarted states the cluster it held BEFORE that update; the new process sends the update again and it is rejected again. The gauge is then NOT written (a count without that cluster would say the proxy holds fewer unpinned clusters than it may), the agent says so once (ackedClusterPinsUnknownMsg), and the NACK counter moves. It is written again when every held version is known. "Not written" is absent, also for a gauge that was written before: it is an observable gauge and has no sample while this lasts.
  • The class of a cluster the proxy states and the agent neither publishes nor has a record of (restateLocked): the same, "not written", unless its name is of a family the pin gauges do not count. A cluster the agent does publish that is not a cluster entry is in no count.
  • What the proxy states is what it ACCEPTED, not what it runs. Envoy applies the valid clusters of a response it then rejects as a whole, and keeps stating their old versions. They are counted at the old version here; a proxy generation that rejected its first response has accepted nothing, and counts nothing, although it runs them.
  • With two proxy generations connected during a hot restart there is one record per cluster, not one per generation: each cluster shows the last answer from either, and a generation's opening answer replaces the set.

An entry with no cluster in the snapshot (a TCP floor that is not captured) is published as an entry, in the published gauge. It is in this one only while a proxy holds its cluster from an earlier snapshot: a floor that was published, left the capture set, and whose removal the proxy has not accepted stays counted at the version the proxy accepted (TestAckedPinGaugeKeepsAFloorWhoseRemovalWasRejected). One whose cluster was never published, or whose removal the proxy accepted, is not in this gauge.

It logs when the acknowledged counts CHANGE, and when the state becomes unknown or known again; a steady state is silent however many updates are acknowledged in it.

Safe to call from the xDS stream's goroutine: it takes the acknowledged state's own mutex and, under it, only the gauge's leaf mutex and the log handler; never snapshotMu or clusterMu. It walks every cluster record once (BenchmarkAckedPinsAccept measures it: tens of microseconds at 2,000 cluster entries on a workstation, growing with the number of entries).

The state change and its report are one critical section, so that the gauge is written in the order the state changed (ackedPins).

func (*SnapshotCache) ConfirmHeldQUICTwins

func (c *SnapshotCache) ConfirmHeldQUICTwins(ctx context.Context, names []string) int

ConfirmHeldQUICTwins handles the `quic:` twins a fresh xDS stream's first CDS request re-stated as HELD without an on-demand subscription (quicdemand.Classification's HeldOnly; issue #1073), and returns how many of them the agent serves.

A held twin of a pair the agent serves stays served -- the proxy holds it and traffic may well be flowing on it -- and counts as evidence of use at this moment: its pair is confirmed, which exempts it from the fetch-window prune for good (PruneUnfetchedQUICPairs). This is the #1073 case: after a proxy restart every twin reaches the new generation through the wildcard, with no on-demand fetch and no subscription, and carries its traffic that way; an agent-only restart then re-states all of them as held-only, and the pre-#1073 prune removed every one of them one window later (~200 x 503 NC per burst fleet-wide, and an Envoy SIGBUS in QuicConnection::OnCanWrite on one node, #1074).

A held twin whose pair the agent does NOT serve admits nothing (issue #1033): it is answered absent and the proxy drops it -- it holds no subscription for it, so its next request is real first use.

func (*SnapshotCache) CreateDeltaWatch

func (c *SnapshotCache) CreateDeltaWatch(req *cachev3.DeltaRequest, sub cachev3.Subscription, value chan cachev3.DeltaResponse) (func(), error)

CreateDeltaWatch answers an on-demand subscription for a `quic:` twin the stream already holds (issue #1049).

Envoy's ODCDS manager opens one singleton subscription per cluster name, on the same delta ADS stream as the wildcard CDS subscription, and a request that routes to a twin opens it whenever the twin is not an ACTIVE cluster -- including when the wildcard has already delivered it and it is still warming. go-control-plane answers a named subscribe only when the resource's version differs from what the stream was last sent, so a twin the wildcard delivered earlier gets no response at all. The per-name subscription then waits out its initial-fetch timeout (15 s) and Envoy reports the twin missing: `cm odcds: cluster quic:... not found during on-demand discovery` on node C at 15:45:04.7, 15.0 s after the k6 loader's first request at 15:44:49.7, while the agent served that twin continuously from 15:44:46.1. A request still waiting on the name at that moment is failed as missing.

So every `quic:` name a request newly subscribes to is treated as unsent: its returned version is blanked for the response computation, exactly as go-control-plane itself does for a name explicitly unsubscribed from a wildcard stream. The twin, when the snapshot carries it, goes out in the response to the subscribe itself, which is the answer the subscription is waiting for. When the snapshot does not carry it nothing changes: a name the stream was never sent stays unanswered (held until the twin is published), and one it was sent is already in removed_resources from the snapshot that dropped it. This never adds an absent answer.

The stream's own subscription state is not touched: the wrapper gives the cache a private copy of the returned-version map (the Subscription contract forbids altering the original), and the server records the versions the response actually carried as usual.

func (*SnapshotCache) DependencyChanges

func (c *SnapshotCache) DependencyChanges() <-chan struct{}

DependencyChanges returns a channel receiving a (coalesced) signal whenever the node dependency set changes — a pod was added or removed, or its declared upstreams differ. Consumers treat each receive as "the dependency set changed, rebuild the scoped snapshot".

func (*SnapshotCache) DependencySet

func (c *SnapshotCache) DependencySet() map[string]struct{}

DependencySet returns the node dependency set: the union of all local pods' declared upstreams, their own services, and live (non-expired) observed dependencies. LoadClustersFromRegistry scopes the cluster/endpoint/route snapshot to this set (demand-scoped distribution, proposal 004).

func (*SnapshotCache) DormantQUICPairs

func (c *SnapshotCache) DormantQUICPairs() []string

DormantQUICPairs returns the dormant pairs (issue #1036) as sorted twin names. For tests and debugging.

func (*SnapshotCache) EnableObservedUpstreamsStore

func (c *SnapshotCache) EnableObservedUpstreamsStore(ctx context.Context, path string)

EnableObservedUpstreamsStore turns on persistence of the OBSERVED half of the node dependency set at path and restores whatever a previous agent on this node left there. Call once, before the first snapshot is generated — the point of the restore is that the very first push already carries the clusters the node's traffic was using when the previous agent stopped.

Why (issue #701): the observed set is process-local memory. An agent-only restart is repaired by the proxy's held-cluster inventory (RestoreDependency, #698), but a FULL agent+proxy replacement — every Helm upgrade — leaves a fresh proxy with nothing to report and a fresh agent with nothing observed, so on a node with no local replica of an upstream the first requests take the cold ODCDS path: ~one bucket of 503s (+57/+65 prober http_error, ~5s) per such node per roll on the reference cluster (rev195, 2026-09-05). Declared upstreams never pay this because an annotation survives the restart; this makes an observation survive it too.

Restored entries are ordinary TTL'd observations — never live-subscription pins, and their original deadline carries over — so the demand set still shrinks exactly as it would have without the restart. A missing, corrupt or unreadable file logs and falls back to the cold path; it never fails the agent.

func (*SnapshotCache) Endpoints

func (c *SnapshotCache) Endpoints(clusterName string) []types.Resource

Endpoints returns the pre-built load assignment (cluster endpoints) for the given cluster name as a resource slice. Returns nil if the cluster does not exist or has no load assignment. Thread-safe.

func (*SnapshotCache) FlushObservedUpstreams

func (c *SnapshotCache) FlushObservedUpstreams()

FlushObservedUpstreams writes the observed set now if a change is pending, short-circuiting the debounce. For shutdown: a change made in the last debounce window before SIGTERM would otherwise be lost.

func (*SnapshotCache) HasQUICPair

func (c *SnapshotCache) HasQUICPair(name string) bool

HasQUICPair reports whether the pair behind a `quic:` twin name is in the observed set, i.e. whether the agent serves that twin. It records nothing.

func (*SnapshotCache) HasRegistryService

func (c *SnapshotCache) HasRegistryService(name string) bool

HasRegistryService reports whether the named service is currently known to the mesh registry. It delegates to the registry's ServiceCatalog.HasService when available; returns false if the registry does not implement ServiceCatalog or no registry has been set (safe default = treat as not a registry service). Used by the edge reconciler's backend-existence check to distinguish mesh services (namespace-blind, registry-resolved) from k8s Services.

func (*SnapshotCache) Listeners

func (c *SnapshotCache) Listeners() []types.Resource

Listeners returns all cached inbound and outbound listener resources plus the health gateway listener (per-pod health_check filters over the health_<namespace>_<pod> clusters, probed by the liveness loop) as a flat slice. Thread-safe.

func (*SnapshotCache) LoadClustersFromRegistry

func (c *SnapshotCache) LoadClustersFromRegistry(ctx context.Context, clusterName string, nodeName string, reg registry.Registry) error

LoadClustersFromRegistry fetches the HTTP service endpoints from the registry for the node dependency set (local pods' declared upstreams + their own services — demand-scoped distribution, proposal 004), generates Envoy clusters and load assignments for each in-scope service, and populates the cache. The outbound RDS virtual-host set shrinks identically (vhosts are derived from the cluster entries). After populating the cache, it generates and sets a new cluster snapshot. Returns an error if registry listing fails or snapshot generation fails.

func (*SnapshotCache) LoadListenersFromStorage

func (c *SnapshotCache) LoadListenersFromStorage(ctx context.Context, store storage.Storage[*cniv1.CNIPod], trustDomain string) error

LoadListenersFromStorage retrieves all pods from the given storage backend, generates the inbound and outbound Envoy listeners and per-pod clusters for each pod, and populates the cache keyed by container network namespace. After populating the cache, it generates and sets a new listener snapshot.

The trustDomain is the SPIFFE trust domain used for SDS secret naming.

If listener generation fails for any pod, it logs the error and continues processing other pods. Returns an error with all accumulated errors if at least one pod failed, or if snapshot generation fails.

func (*SnapshotCache) MeshDomain

func (c *SnapshotCache) MeshDomain() string

MeshDomain returns the configured mesh domain.

func (*SnapshotCache) MissingCaptureInputs

func (c *SnapshotCache) MissingCaptureInputs() []string

MissingCaptureInputs names the capture-listener inputs not delivered yet, CaptureInputProjection and CaptureInputServiceRange; empty once CaptureInputsReady is closed.

func (*SnapshotCache) ObserveDependency

func (c *SnapshotCache) ObserveDependency(ctx context.Context, service string) bool

ObserveDependency records an on-demand (ODCDS) request for a service that is not in the node dependency set: the observed cold path. The service joins the set with a TTL'd membership (refreshed on re-request) and a change signal triggers the scoped reload that delivers the cluster, resuming the paused request. A request for an already-known service only refreshes its observation timestamp. Returns true when the dependency is new (a miss).

The observer pairs this with TrackOnDemandCluster: the subscription the request arrived on is what keeps the entry alive past the idle TTL while the proxy is still routing to it (issue #682).

func (*SnapshotCache) ObserveQUICTwin

func (c *SnapshotCache) ObserveQUICTwin(ctx context.Context, streamID int64, name string) (QUICTwinDecision, string)

ObserveQUICTwin handles the node proxy's on-demand CDS request for a `quic:<svc>.<ns>.<domain>@<ns>/<sa>` twin (issue #1020).

Every local ServiceAccount has a selection arm on every eligible destination's routes (east-west QUIC is unconditional, #979), but the twin behind the arm is built only once that source has actually dialled the destination: the first request finds no such cluster and Envoy's on_demand filter asks for it by name. This validates the name -- the destination must be in the dependency set, the source must be a ServiceAccount with a pod on this node -- records the pair in the persisted demand set and regenerates the snapshot, which then carries the twin and its own load assignment together (the #1008 rule), answering the subscription.

The regeneration runs off the caller's goroutine and is COALESCED with the other admissions of the same burst (issue #1086, requestQUICPublish): this is called from the xDS stream's request callback, publishing a snapshot from inside it could block on the very stream whose request is being processed, and a full rebuild per admitted pair is what pushed a 10-destination first use past the on_demand timeout.

streamID is the xDS stream that asked: the proxy generation that now holds the name's on-demand subscription (issue #1052).

func (*SnapshotCache) OnDemandServices

func (c *SnapshotCache) OnDemandServices() map[string]struct{}

OnDemandServices returns the services the node's proxy currently holds a live on-demand subscription for — the observed-use set that exempts an observed dependency from the idle TTL. External callers get a fresh map.

func (*SnapshotCache) OnPodPortsChanged

func (c *SnapshotCache) OnPodPortsChanged(fn func())

OnPodPortsChanged registers fn to be called whenever a registry refresh changes what PodPortClasses answers for any service: a service's rows were held for the first time, were dropped, or declare other ports.

A route's status is judged by that answer, and nothing the route reconciler watches changes when it does. In particular the reconcile of a route event makes the route's services dependencies of this node, and the refresh that then loads their rows comes after it: the status written by that reconcile said "not checked" of a reference the tables answered 500 for a moment later, until a timer came round. The reconciler is told instead, by this.

fn is called with the cache's cluster lock held: it must not block and must not call the cache. Register before the first refresh; there is one hook.

func (*SnapshotCache) PodPortClasses

func (c *SnapshotCache) PodPortClasses(_ context.Context, service string) (map[uint32]registryv1.PortProtocol, bool)

PodPortClasses returns the class of every port of a service as this node's route tables serve it, and whether the node knows the service's ports from registry rows at all.

It is the answer the tables themselves are built from (servicePorts: one class per port number, the one most pods declare when they disagree), handed out for a route's status, so that the status and the table cannot be built from different facts: a backendRef the table answers 500 for, because the port's class here is not HTTP or the port is not one of these, is one the status says False of (agent/internal/gamma, PodPorts).

func (*SnapshotCache) PruneObservedDependencies

func (c *SnapshotCache) PruneObservedDependencies()

PruneObservedDependencies expires observed dependencies idle past the TTL and signals a dependency change when any were dropped. The refresher calls it periodically; the subsequent scoped reload removes the expired clusters (after the retention grace), and Envoy re-fetches via ODCDS on next use.

An entry the node's proxy still holds a live on-demand subscription for is REFRESHED rather than expired (issue #682): that subscription is the agent's evidence the upstream is still in use, and dropping it would be unrecoverable — Envoy dedupes a re-subscribe for a name it already believes it is waiting on, so no ODCDS request would ever come back to re-warm it. Genuinely idle upstreams — no traffic, hence no live subscription once the stream turns over — still expire, which is the demand scoping.

func (*SnapshotCache) PruneUnfetchedQUICPairs

func (c *SnapshotCache) PruneUnfetchedQUICPairs()

PruneUnfetchedQUICPairs drops the persisted QUIC pairs no agent generation has seen evidence of use for, once the fetch window after this agent's start has elapsed (issues #1033, #1073). Called from the refresher's prune tick.

Why it exists: the #1032 agent admitted a pair for every twin the proxy re-stated on a fresh stream, so the first reference-cluster deploy persisted the whole SAs x destinations fan-out on every node, and pairs prune otherwise only on removal evidence (source left the node, destination left the dependency set). This drains that, and anything else persisted without evidence.

What "in use" means (issue #1073). The agent has no traffic signal -- it makes no admin calls -- and a twin the proxy already holds is never fetched again, however much traffic it carries. After a proxy restart every twin reaches the new generation through the wildcard CDS subscription, with no fetch and no on-demand subscription, and carries its traffic that way. So the pre-#1073 rule, "fetched since agent start", pruned every live twin one window after any agent-only restart: the next requests paid 503 NC while the twin was re-fetched, and removing a QUIC cluster that has live connections can crash Envoy (#1074). The costs are asymmetric -- a wrongly kept pair is one idle cluster until its source leaves the node or its destination leaves the dependency set; a wrongly pruned one is 503s and a possible proxy crash -- so a pair is kept on ANY evidence of use, ever:

  • a live stream holds an on-demand subscription for its twin (the ledger's Subscribed; removing it would also strand it, #1036);
  • it is confirmed (quicConfirmed): fetched on demand, re-subscribed, or its twin re-stated as HELD on a fresh stream while the agent served it (ConfirmHeldQUICTwins) -- by this agent or, through the persisted demand_confirmed bit, any earlier one.

"Held by a live stream" needs no per-stream holding set beyond the ledger's subscriptions: the proxy keeps every twin the agent serves, so a pair a fresh stream re-stated as held is held by every later generation too, and its confirmation is sticky for the same reason. It also covers the node reboot (agent AND proxy fresh): the restored pairs carry their confirmation from the previous agent, so the twins the new proxy uses without ever fetching them are not pruned an hour later.

What is left is a restored pair no generation has vouched for: one persisted before #1073 whose twin no fresh stream has re-stated since this agent started, or the #1032 fan-out. Envoy drops such a cluster outright (it holds no subscription for it), so a pruned pair that still has traffic re-fetches on its next request and is re-admitted, confirmed -- at most once per pair.

Logs one line per node with the count when it prunes anything.

func (*SnapshotCache) QUICPairs

func (c *SnapshotCache) QUICPairs() []string

QUICPairs returns the observed pairs as sorted twin names -- what an operator compares with the proxy's `quic:` cluster count. For tests and debugging.

func (*SnapshotCache) ReloadNodeState

func (c *SnapshotCache) ReloadNodeState(ctx context.Context) error

ReloadNodeState merges what the previous owner of the node persisted after this agent started — its observed upstreams, QUIC pairs and their confirmations, including the final flush it made on exit — into this cache. A takeover step (proposal 041): it runs after the node lock is held, so that flush has landed, and before ownership is announced, so the first write this agent makes is the union. The merge is the restore's own union semantics: nothing this agent observed itself is overridden.

It also restarts the QUIC pair fetch window (#1033): the window is "how long this agent has SERVED without seeing a pair used", and a standby serves nothing.

func (*SnapshotCache) RemoveCluster

func (c *SnapshotCache) RemoveCluster(ctx context.Context, clusterName string) error

RemoveCluster removes the cluster, its endpoints, and its virtual host associated with the given name, then regenerates the snapshot.

func (*SnapshotCache) RemoveEndpoint

func (c *SnapshotCache) RemoveEndpoint(ctx context.Context, clusterName string, ip string) error

RemoveEndpoint removes a single endpoint by IP from the given cluster's load assignment and regenerates the cluster snapshot. If the cluster does not exist or the IP is not found in the endpoint map, it returns nil without regenerating the snapshot. The cluster itself is kept even if the endpoint map becomes empty.

func (*SnapshotCache) RemovePod

func (c *SnapshotCache) RemovePod(ctx context.Context, netns string) error

RemovePod removes the inbound and outbound listeners for the pod with the given container network namespace, then regenerates the listener snapshot. If the pod does not exist in the cache, it returns nil without error. Returns an error if snapshot generation fails.

func (*SnapshotCache) ResponseAccepted

func (c *SnapshotCache) ResponseAccepted(ctx context.Context, accepted ack.Accepted)

ResponseAccepted is the cache's ack.AckObserver: it is told what every answered delta response says the proxy holds and acts on the cluster ones (ClustersAccepted). The other types change no pin: the pin lives in the cluster's transport socket, not in its endpoints or its secrets.

func (*SnapshotCache) ResponseDelivery

func (c *SnapshotCache) ResponseDelivery(_ context.Context, delivery ack.Delivery)

ResponseDelivery is the cache's ack.DeliveryObserver: the clusters of a response entering or leaving flight. The other types carry no pin.

func (*SnapshotCache) RestateQUICSubscriptions

func (c *SnapshotCache) RestateQUICSubscriptions(ctx context.Context, streamID int64, names []string) int

RestateQUICSubscriptions is a fresh xDS stream's first CDS request (issue #1036): names -- quicdemand's Resubscribed, possibly empty -- is then exactly the set of on-demand subscriptions that stream's proxy process holds. They are recorded for streamID alone (issue #1052): across a hot restart the draining parent and the child are two live streams, and only the stream that re-subscribed a twin vouches for its subscription. A dormant pair NO live stream holds -- the proxy restarted, or the only live stream is a new generation's, whose child holds no ODCDS subscriptions -- is pruned: the next request that routes to its twin opens a subscription, real first use. One that another live generation still holds stays dormant until that stream ends (CloseQUICStream). The named twins are then resumed (ResumeQUICSubscriptions), which keeps a named pair that is not servable right now dormant. Called on EVERY fresh stream. Returns how many pairs were new.

func (*SnapshotCache) RestoreDependency

func (c *SnapshotCache) RestoreDependency(ctx context.Context, service string) bool

RestoreDependency re-admits a service the node's proxy ALREADY holds a cluster for, as reported in the initial_resource_versions of the first delta request on a fresh xDS stream. Returns true when the dependency is new to this process. Same TTL'd membership as an observation, but it is deliberately NOT a miss: the proxy is not asking for something new, the agent is recovering demand it had already granted.

Why this exists (issue #682, the ~20s post-restart echo outage on nodes with no local replica, 2026-09-05 rev194): the observed half of the dependency set is process-local memory, so a restarted agent's first snapshot legitimately drops every ODCDS-acquired upstream, and Envoy 503s (NC) on the next request. The cold path is supposed to repair that in one round trip — except a reconnecting Envoy never re-asks. On a fresh stream Envoy marks every requested resource "waiting for server", and its first request carries initial_resource_versions for the resources it HOLDS plus resource_names_subscribe for names newly added since — which, after markStreamFresh clears the pending-add set, is nothing. A name it is still waiting on appears in NEITHER field, and its on_demand filter dedupes every later re-subscribe for a name already in that state, so no ODCDS request reaches the new agent at all. On the reference cluster the outage ended only when Envoy's 15s init-fetch timeout tore that subscription state down and the next request re-subscribed from scratch: 14.05s (node A) / 14.67s (node C) of 503s, ~7 rounds of the 2s on-demand timeout, with the agent logging nothing.

The held-resource inventory is the evidence the agent was missing: it is the proxy stating, in the protocol, exactly which clusters it is still running on. Restoring from it re-seeds the demand set in the first request of the stream — before the first snapshot push — so the upstream never leaves the snapshot. Restored entries are plain observations, NOT live-subscription pins: anything the proxy no longer routes to decays on the ordinary idle TTL, so demand scoping still shrinks after a restart.

func (*SnapshotCache) ResumeQUICSubscriptions

func (c *SnapshotCache) ResumeQUICSubscriptions(ctx context.Context, streamID int64, names []string) int

ResumeQUICSubscriptions admits the pairs behind twins the node proxy re-subscribed by name (issue #1033): names it holds a live on-demand subscription for, each opened by a request that routed to the twin. Envoy's ODCDS manager keeps such a subscription for the life of the process and never re-sends it, so a valid pair that is not served here is stranded -- every request 503s at the on_demand timeout -- rather than re-fetched. Same validation as ObserveQUICTwin, silent on refusal; admitted and known pairs are confirmed (issue #1073), so the fetch-window prune keeps them, and a refused well-formed name is kept dormant (issue #1036) so it is republished when it becomes valid. Returns how many pairs were new; those are published with one coalesced regeneration, off the caller's goroutine (see ObserveQUICTwin).

A twin the proxy merely HOLDS (initial_resource_versions without a subscription) admits nothing: it is whatever an older agent generation built. #1032 admitted those too (RestoreQUICTwin), which on the first reference-cluster deploy (rev245) persisted every SAs x destinations twin as a pair.

func (*SnapshotCache) RewriteMeshDNSSnapshot

func (c *SnapshotCache) RewriteMeshDNSSnapshot()

RewriteMeshDNSSnapshot re-persists the last projected record table with a fresh writtenAt stamp and an UNCHANGED generation. It backs the periodic freshness heartbeat (see capture.MeshDNSHeartbeat): the capture reconciler is event-driven with no short resync, so on a quiet cluster the snapshot would otherwise look stale to the resolver daemon and its snapshot-age gauge could not distinguish "nothing changed" from "the agent is wedged".

No-op when mesh DNS is off, and — importantly — before the first projection: writing an empty table would flip the daemon ready and NXDOMAIN the whole mesh.

func (*SnapshotCache) ServiceRangeDelivered

func (c *SnapshotCache) ServiceRangeDelivered() <-chan struct{}

ServiceRangeDelivered returns a channel closed once SetServiceRanges has been called, a nil range included. servicerange.Setup calls it once at start on the override and API-not-served paths; on the ServiceCIDR path the reconciler calls it on its first reconcile.

func (*SnapshotCache) ServiceRanges

func (c *SnapshotCache) ServiceRanges() []netip.Prefix

ServiceRanges returns a copy of the Service range SetServiceRanges last recorded, nil when none is known.

func (*SnapshotCache) SetAuthzSidecar

func (c *SnapshotCache) SetAuthzSidecar(timeout time.Duration, failureModeAllow bool)

SetAuthzSidecar configures the node-local authz sidecar ext_authz entry (proposal 027). Called once at startup, before listener generation.

func (*SnapshotCache) SetCaptureAuthorities

func (c *SnapshotCache) SetCaptureAuthorities(authorities map[string]string)

SetCaptureAuthorities replaces the mesh service -> cluster.local FQDN map (fed by the agent's capture reconciler from the generated mesh Services) and signals a snapshot rebuild on change so the capture route tables re-derive.

func (*SnapshotCache) SetCaptureEnabled

func (c *SnapshotCache) SetCaptureEnabled(v bool)

SetCaptureEnabled turns transparent capture (proposal 018, Phase 3a) on. Call once before the manager starts: it gates per-pod capture listener generation and the cap_http route table.

func (*SnapshotCache) SetCaptureRedirectAll

func (c *SnapshotCache) SetCaptureRedirectAll(v bool)

SetCaptureRedirectAll enables the redirect-all + ORIGINAL_DST passthrough mode (proposal 022, M2a spike). Must be called after SetCaptureEnabled(true): redirect-all only makes sense when the capture listener is being generated. Call once before the manager starts; read without locking.

func (*SnapshotCache) SetCaptureTCPServices

func (c *SnapshotCache) SetCaptureTCPServices(services []capture.CaptureTCPService)

SetCaptureTCPServices implements capture.AuthoritySink: it replaces the list of non-HTTP mesh services that need per-ClusterIP TCP floor chains on the capture listener. A change rebuilds all per-pod capture listeners (they embed the TCP chains) and regenerates the xDS snapshot so Envoy picks up the new filter chains.

func (*SnapshotCache) SetEdgeGateways

func (c *SnapshotCache) SetEdgeGateways(gateways []EdgeGatewayEntry)

SetEdgeGateways replaces the per-Gateway routing set (proposal 021 Phase 2). When non-empty the snapshot generates per-Gateway listeners (bound on InternalPorts) and per-Gateway route tables instead of the shared edge_http/edge_https listeners. When empty, the cache falls back to Phase 1 (shared-listener) behavior. Thread-safe; triggers a dependency rebuild and snapshot push on change.

func (*SnapshotCache) SetEdgeGeoip

func (c *SnapshotCache) SetEdgeGeoip(gc proxy.GeoipConfig, xffTrustedHops uint32)

SetEdgeGeoip configures the edge geo pipeline (proposal 028): the reserved x-geo-* strip always (spoof protection), plus the geoip filter when a database is configured. Boot-time, before listener generation.

func (*SnapshotCache) SetEdgeHTTPRedirect

func (c *SnapshotCache) SetEdgeHTTPRedirect(enabled bool)

SetEdgeHTTPRedirect controls whether the edge's plain-HTTP port listener emits a 301 HTTP→HTTPS redirect (true) or serves routes directly (false, the default). Called by the Gateway API reconciler on every reconcile based on whether any Gateway in the current aether GatewayClass set carries the gateway.aether.io/http-redirect: "true" annotation. Safe for concurrent use.

func (*SnapshotCache) SetEdgeIdentity

func (c *SnapshotCache) SetEdgeIdentity(spiffeID, trustDomain string)

SetEdgeIdentity records the edge proxy's single SVID name and trust domain so the edge service clusters' upstream mTLS presents that identity and validates the trust-domain bundle (served by SPIRE over the spire_agent SDS cluster). The node proxy sets these via the SPIRE bridge instead. It is the pre-start seed; UpdateEdgeIdentity is the after-start form.

func (*SnapshotCache) SetEdgeMode

func (c *SnapshotCache) SetEdgeMode(httpPort uint32)

SetEdgeMode switches the cache to edge (north-south ingress) snapshot composition and binds the edge listener to httpPort. Must be called before the manager starts; the mode is read without locking on every snapshot build.

func (*SnapshotCache) SetEdgeReadinessPort

func (c *SnapshotCache) SetEdgeReadinessPort(port uint32)

SetEdgeReadinessPort sets the port the dedicated always-bound readiness listener binds (the kubelet probe target). Must be called before the manager starts. A zero value leaves the default (proxy.DefaultEdgeReadinessPort) in effect.

func (*SnapshotCache) SetEdgeTCPRoutes

func (c *SnapshotCache) SetEdgeTCPRoutes(routes []proxy.EdgeL4TCPRoute)

SetEdgeTCPRoutes replaces the edge's TCP listener routes (one per Gateway TCP listener port). On change it updates the dependency set and signals a rebuild so the new tcp_proxy listeners appear in the snapshot.

func (*SnapshotCache) SetEdgeTLSMode

func (c *SnapshotCache) SetEdgeTLSMode(httpsPort uint32)

SetEdgeTLSMode enables downstream TLS termination: the edge serves a TLS listener on httpsPort (certs per VirtualHost via SDS). Must be called before the manager starts. The HTTP→HTTPS redirect is separately controlled per-Gateway via SetEdgeHTTPRedirect (driven by the gateway.aether.io/http-redirect annotation).

func (*SnapshotCache) SetEdgeTLSRoutes

func (c *SnapshotCache) SetEdgeTLSRoutes(routes []proxy.EdgeL4TLSRoute)

SetEdgeTLSRoutes replaces the edge's TLS passthrough listener routes (one per Gateway TLS listener port). On change it updates the dependency set and signals a rebuild.

func (*SnapshotCache) SetEdgeTLSSecrets

func (c *SnapshotCache) SetEdgeTLSSecrets(ctx context.Context, certs map[string]EdgeTLSCert) error

SetEdgeTLSSecrets replaces the edge's downstream TLS certs (keyed by SDS name) and serves them over the ADS SecretType channel for Envoy to select by SNI.

func (*SnapshotCache) SetEmitStatsPod

func (c *SnapshotCache) SetEmitStatsPod(enabled bool)

SetEmitStatsPod enables per-pod labels on the aether_stats request counter (--stats-emit-pod flag). Must be called before the manager starts; the flag is read without locking on every listener build.

func (*SnapshotCache) SetImportedServiceChainFilters

func (c *SnapshotCache) SetImportedServiceChainFilters(filters map[string]proxy.ExtensionFilter)

SetImportedServiceChainFilters replaces the peer-cluster-imported service chain filters (proposal 026). Local wins on a per-service collision, like routes.

func (*SnapshotCache) SetImportedServiceRoutes

func (c *SnapshotCache) SetImportedServiceRoutes(routes map[string][]proxy.GammaRoute)

SetImportedServiceRoutes replaces the GAMMA rules IMPORTED from peer clusters (proposal 026): config a remote cluster authored for a service, fetched from the registrar (ConfigImporter) and materialized read-only. Merged with local routes at read time — a LOCAL HTTPRoute for the same service wins (a cluster's own config is authoritative for itself). Signals a scoped-snapshot rebuild on change.

func (*SnapshotCache) SetMeshDNSRecords

func (c *SnapshotCache) SetMeshDNSRecords(records map[string]string)

SetMeshDNSRecords persists the mesh service -> IP table (from the mesh-Service reconciler) to the snapshot file the standalone resolver daemon watches. No-op when mesh DNS is off (empty path). A persist error is logged, never fatal.

The write always happens (it re-stamps the envelope's writtenAt, which is the daemon's freshness signal), but the generation only advances when the record CONTENT changed, so a heartbeat rewrite is distinguishable from a real update.

func (*SnapshotCache) SetMeshDNSSnapshotPath

func (c *SnapshotCache) SetMeshDNSSnapshotPath(path string)

SetMeshDNSSnapshotPath sets the host-persistent file the mesh service->IP record table is written to (proposal 018, mesh-global FQDN; issue #578), or empty when mesh DNS is off. The agent no longer serves DNS: the standalone aether-mesh-dns DaemonSet watches this file and serves :18054, and the CNI DNATs each pod's :53 straight to it. The cache only persists records here.

func (*SnapshotCache) SetMeshDomain

func (c *SnapshotCache) SetMeshDomain(domain string)

SetMeshDomain overrides the default mesh domain (--mesh-domain flag). Must be called before the manager starts; the domain is read without locking on every snapshot build.

func (*SnapshotCache) SetNodeIdentity

func (c *SnapshotCache) SetNodeIdentity(ctx context.Context, nodeSpiffeID string) error

SetNodeIdentity records the agent's node SPIFFE ID (served by the SPIRE bridge as the node SVID) and regenerates the snapshot. Outbound clusters reference it as the no-match client-certificate secret for upstream mTLS (used by active health-check probes and other node-originated connections); until it is set, upstream mTLS injection is skipped. Idempotent: a no-op when the value is unchanged.

func (*SnapshotCache) SetNodeLocality

func (c *SnapshotCache) SetNodeLocality(region, zone string)

SetNodeLocality records the node's topology labels once resolved (CNI server PreListen) and signals a dependency change so the scoped snapshot is rebuilt with locality-aware EDS priorities — the initial snapshot may have been generated before the labels were known.

func (*SnapshotCache) SetNodeWriteGate

func (c *SnapshotCache) SetNodeWriteGate(owned <-chan struct{})

SetNodeWriteGate holds every node-local file write of this cache until owned is closed (proposal 041, "Persisted state, two writers"). Call once at boot, before the manager starts; nil (the default) never holds anything.

While a surge-rolled standby agent builds its first snapshot, the agent that still owns the node keeps writing the observed demand set with its QUIC pairs (#701, #1033) and the mesh-DNS record snapshot (#578, #586), and flushes the observed set once more on its way out. A standby that wrote too would race it — and could land a set from before the old agent's last observations over the file it is about to restore from. So the standby keeps those changes in memory (marking them pending), and when owned closes:

  • the observed set is flushed once, whatever is pending, after ReloadNodeState has merged in the old agent's final flush;
  • the mesh-DNS table is re-stamped from the last projection, so the resolver daemon sees a live writer again within milliseconds of the handoff rather than at the next heartbeat.

func (*SnapshotCache) SetQUICIdleTimeout

func (c *SnapshotCache) SetQUICIdleTimeout(d time.Duration)

SetQUICIdleTimeout sets the `quic:` twins' pool idle timeout (--east-west-quic-idle-timeout, aether#1054); d <= 0 means config.DefaultQUICTwinIdleTimeout. Boot-time, before the manager starts. h1/h2 clusters keep config.UpstreamIdleTimeout whatever this is.

func (*SnapshotCache) SetQUICPairFetchWindow

func (c *SnapshotCache) SetQUICPairFetchWindow(d time.Duration)

SetQUICPairFetchWindow sets the unconfirmed-pair prune window (issue #1033). d <= 0 disables the prune. Boot-time, before the manager starts.

func (*SnapshotCache) SetRegistry

func (c *SnapshotCache) SetRegistry(reg registry.Registry)

SetRegistry stores the service registry for use in HasRegistryService. Called once from NewAgentXdsServer before the manager starts; safe for concurrent use after that point (registry is only read, never replaced).

func (*SnapshotCache) SetRouteTargetPorts

func (c *SnapshotCache) SetRouteTargetPorts(ports map[string][]uint32)

SetRouteTargetPorts replaces the per-route-target real Service port map (proposal 023 M2). Keyed by the same "<ns>/<svc>" route-target key as SetServiceRoutes; fed by the gamma reconciler from each route's parentRef port. captureVhosts emits a "<svc>.<ns>.svc.cluster.local:<port>" domain per listed port so a client dialing the route target's REAL port host-matches its vhost. Signals a scoped-snapshot rebuild on change. A separate side-map (not folded into GammaRoute) keeps the rule-equality plumbing untouched and matches the captureAuthorities pattern.

func (*SnapshotCache) SetSecrets

func (c *SnapshotCache) SetSecrets(ctx context.Context, secrets []*tlsv3.Secret) error

SetSecrets replaces all cached secrets and regenerates the snapshot. Secret resources contain TLS certificates (SVIDs) and validation contexts (trust bundles) sourced from SPIRE.

func (*SnapshotCache) SetServiceChainFilters

func (c *SnapshotCache) SetServiceChainFilters(filters map[string]proxy.ExtensionFilter)

SetServiceChainFilters replaces the service-wide ALWAYS-ON extension filters (proposal 025 M4 CHAIN scope), keyed by "<ns>/<svc>". Fed by the gamma reconciler from CHAIN-scope HTTPFilters with a Service targetRef; at most one per service. Enabled at each service's capture vhost (vhost-level typed_per_filter_config).

func (*SnapshotCache) SetServiceInboundFilters

func (c *SnapshotCache) SetServiceInboundFilters(filters map[string]proxy.ExtensionFilter)

SetServiceInboundFilters replaces the destination-side (INBOUND scope, 027 M3) filters, keyed by "<ns>/<svc>". Enabled on the target service's own pods' inbound listeners; requires the authz sidecar (dropped with a warning otherwise).

func (*SnapshotCache) SetServicePortMaps

func (c *SnapshotCache) SetServicePortMaps(portMaps map[string]map[uint32]uint32)

SetServicePortMaps replaces the port maps of the Services that routes name as a parent or as a backend and that the registrar did not generate: Service port -> the pod port its targetPort names, 0 for a named targetPort (proposal 043, "A Service is a port map"). Fed by the GAMMA reconciler. Signals a snapshot rebuild on change.

func (*SnapshotCache) SetServiceRanges

func (c *SnapshotCache) SetServiceRanges(ranges []netip.Prefix)

SetServiceRanges implements servicerange.Sink: it records the cluster's IPv4 Service range (proposal 044), from the ServiceCIDR objects or the --service-cidrs override. The value is canonicalized here too (masked, sorted, deduplicated, IPv4 only), so a re-delivery of the same range in another order is no change. Nil means no range is known.

The capture listener's Service-range branch (proposal 044, Phase 0) is built from it, so a change does what SetCaptureTCPServices does: rebuild every pod's capture listener (rebuildPodListenersLocked, under listenerMu, after captureMu is released) and then signalDependencyChange, so the new branch reaches the proxy. The early return on an equal range is what keeps a ServiceCIDR resync from rewriting every pod listener on the node.

The first call, whatever its range, closes ServiceRangeDelivered: after the rebuild below, so a waiter that goes on to serve the snapshot finds the listeners built with it.

func (*SnapshotCache) SetServiceRoutes

func (c *SnapshotCache) SetServiceRoutes(routes map[string][]proxy.GammaRoute)

SetServiceRoutes replaces the GAMMA east-west L7 rules (HTTPRoute parentRef= Service, proposal 018 Phase 2). A depended-on service's rule backends enter the dependency set (so their EDS clusters generate) and its outbound vhost is enriched. Signals a scoped-snapshot rebuild on change.

func (*SnapshotCache) SetSpireEnabled

func (c *SnapshotCache) SetSpireEnabled(enabled bool)

SetSpireEnabled records whether SPIRE-backed mTLS is on. The agent calls this with cfg.SpireEnabled before the manager starts. When false the per-pod inbound listener is built cleartext (no downstream mTLS transport socket), matching the outbound clusters, which already go cleartext without a node SVID — so the mesh data path is routable with SPIRE off. Read without locking on every listener build.

func (*SnapshotCache) SetStaticDependencies

func (c *SnapshotCache) SetStaticDependencies(services []string)

SetStaticDependencies replaces the fixed (edge) dependency set with the given services and signals a dependency change if it differs, so the scoped registry watch and the cluster snapshot rebuild to exactly the exposed set.

func (*SnapshotCache) SetTCPServiceRoutes

func (c *SnapshotCache) SetTCPServiceRoutes(routes map[string][]proxy.L4ServiceRoute)

SetTCPServiceRoutes replaces the TCPRoute-derived per-service L4 rules (proposal 018, Phase 3b). On change, it regenerates all per-pod capture listeners (which embed per-ClusterIP TCP floor chains) and triggers a full snapshot rebuild.

func (*SnapshotCache) SetTLSServiceRoutes

func (c *SnapshotCache) SetTLSServiceRoutes(routes map[string][]proxy.L4ServiceRoute)

SetTLSServiceRoutes replaces the TLSRoute-derived per-service SNI rules (proposal 018, Phase 3b). On change, regenerates capture listeners and signals a snapshot rebuild.

func (*SnapshotCache) SetTrustDomain

func (c *SnapshotCache) SetTrustDomain(ctx context.Context, trustDomain string) error

SetTrustDomain records the workload trust domain and, when it CHANGES with listeners already published, rebuilds everything derived from it — inbound SDS server certificates, source-identity filter state, upstream SAN matchers and the per-pod inbound-readiness probes — and publishes exactly ONE snapshot carrying the new identity.

Callers: the agent's SPIRE reconciler, which seeds the cache with the mesh domain before any listener exists and folds in SPIRE's real trust domain when the first SVID lands.

func (*SnapshotCache) SetUDPServiceRoutes

func (c *SnapshotCache) SetUDPServiceRoutes(routes map[string][]proxy.L4Backend)

SetUDPServiceRoutes replaces the UDPRoute-derived per-service UDP routes (proposal 018, Phase 3b). On change, regenerates all per-pod UDP capture listeners (each pod gets one UDP listener covering all services' UDP routes) and triggers a full snapshot rebuild so Envoy picks up the new listeners and their backend UDP clusters.

func (*SnapshotCache) SetUDSCSIRoot

func (c *SnapshotCache) SetUDSCSIRoot(root string)

SetUDSCSIRoot sets the csi.aether.io tmpfs root (--uds-csi-root), the host bridge to a workload's Unix socket (proposals 034/039). An empty root is the operator's off switch: pods requesting a socket then get TCP delivery. Must be called before the manager starts; read without locking on every listener build.

func (*SnapshotCache) SetUDSServicePolicies

func (c *SnapshotCache) SetUDSServicePolicies(policies map[string]string)

SetUDSServicePolicies replaces the service-scoped UDS delivery map (proposal 034 Phase 1b), keyed by "<ns>/<svc>". A pod of a listed service is delivered to the declared socket unless it carries its own uds-socket annotation (which wins).

On change the affected pods' delivery clusters are rebuilt and pushed: the policy is authored independently of the workload, so nothing else would.

func (*SnapshotCache) SetVirtualHosts

func (c *SnapshotCache) SetVirtualHosts(vhosts []VirtualHost)

SetVirtualHosts replaces the edge's exposed virtual hosts. It scopes the dependency set to the union of every route's backend service (plus L4 route backends) and rebuilds the snapshot's route table — including when only the hostnames or matches changed (the service set, and therefore the dependency set, didn't).

func (*SnapshotCache) SetWaypointConfig

func (c *SnapshotCache) SetWaypointConfig(enabled bool, tunnelPort uint32)

SetWaypointConfig enables the split-horizon east/west waypoint rewrite (proposal 019) and sets the node tunnel port dialed for cross-cluster endpoints. Off by default; must be called before the manager starts (read without locking on every cluster build).

func (*SnapshotCache) SignalIfRetentionExpired

func (c *SnapshotCache) SignalIfRetentionExpired()

SignalIfRetentionExpired emits a dependency-change signal when any retained (absent) service has outlived the retention grace, so the refresher runs a reload that prunes it. Pruning is otherwise reload-driven — and under demand-scoped watches a node in steady state receives NO events once a service leaves its dependency set, so the retained empty cluster/vhost would shadow the on-demand catch-all forever (fast 503 instead of ODCDS; observed in vivo 2026-06-12: svc-4's pods moved off a node and the stale vhost stuck). The refresher calls this from its periodic prune tick.

func (*SnapshotCache) TrackOnDemandCluster

func (c *SnapshotCache) TrackOnDemandCluster(streamID int64, clusterName, service string)

TrackOnDemandCluster records a live on-demand (ODCDS) cluster subscription from the node's proxy: streamID identifies the delta stream, clusterName the subscribed resource, service the dependency key it resolves to. It is the observed-USE signal behind the idle TTL (issue #682) — see onDemandSubs. Callers record only names that passed the catalog gate, so a ghost service can never pin a dependency.

func (*SnapshotCache) UntrackOnDemandCluster

func (c *SnapshotCache) UntrackOnDemandCluster(streamID int64, clusterName string)

UntrackOnDemandCluster drops one on-demand subscription (the proxy explicitly unsubscribed from the name). The service reverts to plain idle expiry unless another live subscription still names it.

func (*SnapshotCache) UpdateEdgeIdentity

func (c *SnapshotCache) UpdateEdgeIdentity(ctx context.Context, spiffeID, trustDomain string) error

UpdateEdgeIdentity is SetEdgeIdentity for an identity that arrives AFTER the manager has started, which is the normal case once the edge stops blocking startup on SPIRE (issue #740): it records the identity, rebuilds the cached mTLS-injected clusters, and pushes a new snapshot so the edge Envoy picks the change up on the next CDS update instead of on a restart. Unchanged input is a no-op, so it is safe to call on every SVID rotation.

It is the edge's counterpart to SetNodeIdentity, which does the same for the node proxy when the SPIRE bridge delivers the node SVID.

func (*SnapshotCache) VirtualHosts

func (c *SnapshotCache) VirtualHosts() []types.Resource

VirtualHosts returns all cached virtual host resources as a flat slice. Virtual hosts define routing rules for outbound traffic to services. Thread-safe.

type VirtualHost

type VirtualHost struct {
	Hosts  []string
	Routes []Route
	// TLSSecret is the provider-prefixed SDS name of the cert presented for this
	// virtual host's hosts (empty = no cert). Cert bytes are supplied separately
	// via SetEdgeTLSSecrets.
	TLSSecret string
	// Gateways are the "<ns>/<name>" keys of the Gateways this route attaches to
	// (its parentRefs). Under proposal 021 Phase 2 it scopes which per-Gateway route
	// tables get this vhost — assignment is by ATTACHMENT, not by cert. Empty means
	// unscoped (Phase 1 shared listener, or attach-to-all fallback).
	Gateways []string
}

VirtualHost is the cache's projection of a Gateway API HTTPRoute into edge Envoy virtual hosts. (The VirtualHost CRD, proposal 017, was retired and subsumed by HTTPRoute per proposal 018 — this Go type keeps the name but is no longer backed by any CRD.) It is a set of external hosts carrying an ordered list of path-matched routes to backend services, optionally served under a downstream cert. Empty Routes makes it inert. Empty Hosts is NOT inert — per Gateway API a hostname-less route matches every host on its listener, so it is served via the edge's catch-all "*" vhost (see buildEdgeVhostsLocked).

Directories

Path Synopsis
Package cachemetrics holds the agent xDS snapshot-generation instruments.
Package cachemetrics holds the agent xDS snapshot-generation instruments.
Package snapversion generates xDS snapshot version strings for the agent cache.
Package snapversion generates xDS snapshot version strings for the agent cache.

Jump to

Keyboard shortcuts

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