capture

Documentation

Overview

Package capture contains the node agent's transparent-capture controller: it watches the generated selectorless mesh Services (proposal 018, Phase 3a) and projects their cluster.local authorities into the snapshot cache, which builds the cap_http route table the per-pod capture listeners serve. Endpoints stay in the registry; this only maps a captured authority to its existing service cluster.

Index

• Constants
• type AuthoritySink
• type CaptureTCPService
• type MeshDNSHeartbeat
  • func (h *MeshDNSHeartbeat) NeedLeaderElection() bool
  • func (h *MeshDNSHeartbeat) Start(ctx context.Context) error
• type MeshDNSSnapshotRewriter
• type Reconciler
  • func (r *Reconciler) Reconcile(ctx context.Context, _ reconcile.Request) (reconcile.Result, error)
  • func (r *Reconciler) SetupWithManager(mgr ctrl.Manager) error

Constants

const MeshDNSHeartbeatInterval = 60 * time.Second

MeshDNSHeartbeatInterval is how often the last-known mesh-DNS record table is re-persisted with a fresh writtenAt stamp (issue #586).

The writer is the capture reconciler, which is purely event-driven (the manager has no short SyncPeriod, so the default resync is 10h). A healthy but quiet cluster would therefore leave the snapshot untouched for hours and look indistinguishable — to the resolver daemon's snapshot-age gauge — from an agent that crashed, lost RBAC, or whose reconciler wedged. The heartbeat makes "fresh" mean "the agent is alive and projecting", so the daemon's age gauge is an actual liveness signal for the writer. It must stay well under any alert threshold on that gauge.

Types

type AuthoritySink

type AuthoritySink interface {
	SetCaptureAuthorities(authorities map[string]string)
	SetMeshDNSRecords(records map[string]string)
	SetCaptureTCPServices(services []CaptureTCPService)
}

AuthoritySink receives the projections from the generated mesh Services:

• SetCaptureAuthorities: service -> cluster.local FQDN (cap_http, transparent capture).
• SetMeshDNSRecords: service -> mesh-Service ClusterIP (the per-pod dns_filter's A record for <svc>.<meshDomain>, the mesh-global FQDN).
• SetCaptureTCPServices: the non-HTTP services that need per-ClusterIP TCP floor chains.

All are emitted every reconcile; the cache uses whichever feature is enabled.

type CaptureTCPService

type CaptureTCPService struct {
	// ServiceName is the bare mesh service name (registry key). The cache uses this
	// to derive the TCP cluster name (TCPClusterName) and to look up SAN namespaces.
	ServiceName string
	// ClusterIP is the k8s Service ClusterIP the capture listener's filter chain
	// matches on (original-dst recovered via SO_ORIGINAL_DST). Must be a valid
	// non-None IP address (headless/unallocated Services are skipped).
	ClusterIP string
}

CaptureTCPService describes a non-HTTP mesh Service that needs a per-ClusterIP TCP-proxy floor chain on the capture listener (proposal 018, Phase 3a TCP floor). The ClusterIP drives the filter-chain prefix_ranges match; the cache derives the cluster name from ServiceName and its configured mesh domain.

type MeshDNSHeartbeat

type MeshDNSHeartbeat struct {
	// Rewriter is the snapshot cache to re-stamp. Required.
	Rewriter MeshDNSSnapshotRewriter
	// Interval overrides MeshDNSHeartbeatInterval when positive (tests).
	Interval time.Duration
	// Log is the agent logger; a "mesh-dns-heartbeat" child is derived from it.
	Log *slog.Logger
}

MeshDNSHeartbeat is the controller-runtime Runnable that drives the mesh-DNS snapshot freshness heartbeat. The agent only registers it when --mesh-dns is on, and the rewrite is itself a no-op when the snapshot path is empty, so it is safe either way.

func (*MeshDNSHeartbeat) NeedLeaderElection

func (h *MeshDNSHeartbeat) NeedLeaderElection() bool

NeedLeaderElection reports false: every node agent must re-stamp its OWN node's snapshot, so this runs on all agents, not just a leader.

func (*MeshDNSHeartbeat) Start

func (h *MeshDNSHeartbeat) Start(ctx context.Context) error

Start ticks until the manager's context is cancelled. It never returns an error: a missed heartbeat degrades a freshness signal, it never breaks resolution.

type MeshDNSSnapshotRewriter

type MeshDNSSnapshotRewriter interface {
	// RewriteMeshDNSSnapshot re-stamps the snapshot's freshness without changing its
	// records or generation. It is a no-op before the first projection and when mesh
	// DNS is disabled.
	RewriteMeshDNSSnapshot()
}

MeshDNSSnapshotRewriter re-persists the last projected mesh-DNS record table. It is implemented by the xDS snapshot cache (the capture reconciler's sink).

type Reconciler

type Reconciler struct {
	client.Client

	Sink AuthoritySink
	Log  *slog.Logger
}

Reconciler watches the generated mesh Services (labeled aether.io/mesh-service) and replaces, on any change, the cache's service -> cluster.local authority map. Level-based: each reconcile re-lists, so adds/updates/deletes converge.

func (*Reconciler) Reconcile

func (r *Reconciler) Reconcile(ctx context.Context, _ reconcile.Request) (reconcile.Result, error)

Reconcile re-lists the mesh Services and projects their cluster.local authorities, DNS records, and TCP-floor service set.

func (*Reconciler) SetupWithManager

func (r *Reconciler) SetupWithManager(mgr ctrl.Manager) error

SetupWithManager registers the reconciler to watch mesh Services only.