Skip to content

Agent Mesh

sam-one: grouped tunables for the embedded control plane and router

Antonio Ojea985025687d8b
diff --git a/cmd/sam-one/main.go b/cmd/sam-one/main.go
index 62cc0ea0..2eb1964e 100644
--- a/cmd/sam-one/main.go
+++ b/cmd/sam-one/main.go
@@ -47,8 +47,12 @@ func main() {
adminToken string
policyFile string
oidcIssuer string
+ oidcClientID string
allowedAudiencesFlag string
logLevel string
+ cpTunables standalone.ControlPlaneTunables
+ routerTunables standalone.RouterTunables
+ routerAllowLoopback bool
)
rootCmd := &cobra.Command{
@@ -84,6 +88,7 @@ func main() {
}
}
+ routerTunables.DisallowLoopback = !routerAllowLoopback
srv, err := standalone.New(standalone.Options{
BindAddress: net.JoinHostPort(bindAddress, strconv.Itoa(port)),
ExternalURL: externalURL,
@@ -95,7 +100,10 @@ func main() {
AdminToken: adminToken,
PolicyFile: policyFile,
OIDCIssuer: oidcIssuer,
+ OIDCClientID: oidcClientID,
AllowedAudiences: auds,
+ ControlPlane: cpTunables,
+ Router: routerTunables,
})
if err != nil {
logger.Fatalf("Invalid configuration: %v", err)
@@ -125,9 +133,27 @@ func main() {
rootCmd.Flags().StringVar(&adminToken, "admin-token", "", "Admin API bearer token (or env SAM_ADMIN_TOKEN; auto-generated if empty)")
rootCmd.Flags().StringVar(&policyFile, "policy-file", "", "Path to a protojson PolicyConfigUpdateRequest seeding the mesh policy on first boot only")
rootCmd.Flags().StringVar(&oidcIssuer, "issuer", "", "Optional external OIDC issuer URL (comma-separated)")
+ rootCmd.Flags().StringVar(&oidcClientID, "oidc-client-id", "", "OAuth client id advertised via /info (defaults to the first allowed audience)")
rootCmd.Flags().StringVar(&allowedAudiencesFlag, "allowed-audiences", api.DefaultAudience, "Comma-separated list of allowed OIDC audiences")
rootCmd.Flags().StringVar(&logLevel, "log-level", "", "Log level: debug, info, warn, error")
+ // Embedded control plane tunables.
+ rootCmd.Flags().DurationVar(&cpTunables.LeaseDuration, "control-plane-lease-duration", 0, "Router lease validity (0 keeps the component default)")
+ rootCmd.Flags().DurationVar(&cpTunables.KeyRotationInterval, "control-plane-key-rotation-interval", 0, "Biscuit signing key rotation interval (0 keeps the component default)")
+ rootCmd.Flags().DurationVar(&cpTunables.KeyGracePeriod, "control-plane-key-grace-period", 0, "How long rotated-out keys stay valid for verification (0 keeps the component default)")
+ rootCmd.Flags().DurationVar(&cpTunables.BiscuitTTL, "control-plane-biscuit-ttl", 0, "Lifespan minted into issued biscuits (0 keeps the component default)")
+ rootCmd.Flags().BoolVar(&cpTunables.ManualEnrollment, "control-plane-manual-enrollment", false, "Queue bootstrap enrollments for admin approval instead of auto-approving")
+
+ // Embedded router tunables.
+ rootCmd.Flags().DurationVar(&routerTunables.KeysSyncInterval, "router-keys-sync-interval", 0, "Biscuit public key refresh interval (0 keeps the component default)")
+ rootCmd.Flags().DurationVar(&routerTunables.LeaseRenewInterval, "router-lease-renew-interval", 0, "Lease renewal interval (0 keeps the component default)")
+ rootCmd.Flags().IntVar(&routerTunables.LowWaterMark, "router-low-watermark", 0, "Connection manager low watermark (0 keeps the component default)")
+ rootCmd.Flags().IntVar(&routerTunables.HighWaterMark, "router-high-watermark", 0, "Connection manager high watermark (0 keeps the component default)")
+ rootCmd.Flags().IntVar(&routerTunables.ConnsPerSourceIP, "router-conns-per-source-ip", 0, "Per-source-IP connection budget (0 follows the high watermark; proxied peers share source IPs)")
+ rootCmd.Flags().DurationVar(&routerTunables.DHTProviderAddrTTL, "router-dht-provider-addr-ttl", 0, "DHT provider address TTL (0 keeps the library default)")
+ rootCmd.Flags().DurationVar(&routerTunables.DHTMaxRecordAge, "router-dht-max-record-age", 0, "DHT record max age (0 keeps the library default)")
+ rootCmd.Flags().BoolVar(&routerAllowLoopback, "router-allow-loopback", true, "Advertise loopback addresses (disable on public deployments)")
+
rootCmd.AddCommand(newAdminSubcommands()...)
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
diff --git a/internal/standalone/standalone.go b/internal/standalone/standalone.go
index df9aba75..ddd13a4e 100644
--- a/internal/standalone/standalone.go
+++ b/internal/standalone/standalone.go
@@ -96,6 +96,49 @@ type Options struct {
// OIDCIssuer optionally enables full OIDC enrollment.
OIDCIssuer string
AllowedAudiences []string
+ // OIDCClientID is the OAuth client id advertised via /info.
+ OIDCClientID string
+
+ // ControlPlane and Router forward operator tunables to the embedded
+ // components; zero values keep each component's defaults.
+ ControlPlane ControlPlaneTunables
+ Router RouterTunables
+}
+
+// ControlPlaneTunables are the embedded control plane's operator knobs.
+type ControlPlaneTunables struct {
+ // LeaseDuration bounds how long a router lease stays valid.
+ LeaseDuration time.Duration
+ // KeyRotationInterval is how often the biscuit signing key rotates.
+ KeyRotationInterval time.Duration
+ // KeyGracePeriod keeps rotated-out keys valid for verification.
+ KeyGracePeriod time.Duration
+ // BiscuitTTL is the lifespan minted into issued biscuits.
+ BiscuitTTL time.Duration
+ // ManualEnrollment queues bootstrap enrollments for admin approval
+ // instead of auto-approving them.
+ ManualEnrollment bool
+}
+
+// RouterTunables are the embedded router's operator knobs.
+type RouterTunables struct {
+ // KeysSyncInterval is how often biscuit public keys are refreshed.
+ KeysSyncInterval time.Duration
+ // LeaseRenewInterval is how often the router renews its lease.
+ LeaseRenewInterval time.Duration
+ // LowWaterMark / HighWaterMark bound the connection manager.
+ LowWaterMark int
+ HighWaterMark int
+ // ConnsPerSourceIP scales libp2p's per-source-IP budgets; defaults to
+ // the connection manager high watermark (proxied deployments share
+ // source IPs, so the global cap should be what binds).
+ ConnsPerSourceIP int
+ // DHTProviderAddrTTL / DHTMaxRecordAge tune DHT record lifetimes.
+ DHTProviderAddrTTL time.Duration
+ DHTMaxRecordAge time.Duration
+ // DisallowLoopback stops advertising loopback addresses (useful on
+ // public deployments; the default keeps local development working).
+ DisallowLoopback bool
}
// Default fills unset options with development-friendly values.
@@ -117,6 +160,12 @@ func (o *Options) Default() {
if len(o.AllowedAudiences) == 0 {
o.AllowedAudiences = []string{api.DefaultAudience}
}
+ if o.Router.HighWaterMark == 0 {
+ o.Router.HighWaterMark = router.DefaultHighWaterMark
+ }
+ if o.Router.ConnsPerSourceIP == 0 {
+ o.Router.ConnsPerSourceIP = o.Router.HighWaterMark
+ }
}
// Validate rejects option combinations Start could not honor.
@@ -191,10 +240,15 @@ func (s *Server) Start(ctx context.Context) error {
DriverName: s.opts.DBDriver,
DataSourceName: s.opts.DBDSN,
OIDCIssuer: s.opts.OIDCIssuer,
+ OIDCClientID: s.opts.OIDCClientID,
AllowedAudiences: s.opts.AllowedAudiences,
+ LeaseDuration: s.opts.ControlPlane.LeaseDuration,
+ KeyRotationInterval: s.opts.ControlPlane.KeyRotationInterval,
+ KeyGracePeriod: s.opts.ControlPlane.KeyGracePeriod,
+ BiscuitTTL: s.opts.ControlPlane.BiscuitTTL,
BiscuitTimeout: 10 * time.Second,
AdminToken: s.adminToken,
- AutoApproveEnrollment: true,
+ AutoApproveEnrollment: !s.opts.ControlPlane.ManualEnrollment,
}, store)
if err != nil {
return fmt.Errorf("failed to create control plane: %w", err)
@@ -260,18 +314,23 @@ func (s *Server) Start(ctx context.Context) error {
}
rtr, err := router.NewRouter(ctx, router.Options{
- ControlPlaneURL: "http://" + cp.Addr(),
- ListenAddrs: append([]string{wsAddr}, s.opts.P2PListen...),
- ExternalAddrs: externalAddrs,
- AllowLoopback: true,
- KeysDBPath: filepath.Join(s.opts.DataDir, routerKeyFile),
- BootstrapToken: routerToken,
+ ControlPlaneURL: "http://" + cp.Addr(),
+ ListenAddrs: append([]string{wsAddr}, s.opts.P2PListen...),
+ ExternalAddrs: externalAddrs,
+ AllowLoopback: !s.opts.Router.DisallowLoopback,
+ KeysDBPath: filepath.Join(s.opts.DataDir, routerKeyFile),
+ BootstrapToken: routerToken,
+ KeysSyncInterval: s.opts.Router.KeysSyncInterval,
+ LeaseRenewInterval: s.opts.Router.LeaseRenewInterval,
+ LowWaterMark: s.opts.Router.LowWaterMark,
+ HighWaterMark: s.opts.Router.HighWaterMark,
+ DHTProviderAddrTTL: s.opts.Router.DHTProviderAddrTTL,
+ DHTMaxRecordAge: s.opts.Router.DHTMaxRecordAge,
// Single-port deployments typically sit behind a TLS-terminating
// proxy (Cloud Run, L7 LBs) or NAT where every peer shares a few
// source IPs; libp2p's default 8-conns-per-IP cap would throttle
- // the whole listener. Matches the conn manager's high watermark so
- // the global cap, not the per-IP one, is what binds.
- ConnsPerSourceIP: router.DefaultHighWaterMark,
+ // the whole listener.
+ ConnsPerSourceIP: s.opts.Router.ConnsPerSourceIP,
HTTPFallbackHandler: mux,
})
if err != nil {