Gate the programmed-set debug endpoint to the test environment

The endpoint that reports what the last build intended to change exists only
so a test can confirm the proxy is running exactly that set. Serve it (and do
the per-build recording that backs it) only when the --enable-programmed-set
flag is passed, so production exposes nothing and does no extra work on the
build path.

The flag joins the extension-server flag surface and is wired through the
deployment the same way as the others: an arg that reads an env var
(ENABLE_PROGRAMMED_SET), defaulting off, so an overlay can turn it on with a
strategic-merge patch on env instead of rewriting the args list.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JbCy8vy66RdNYzGSgqH6P6

Author: scotwells

config/extension-server/deployment.yaml

@@ -58,6 +58,7 @@ spec:
             - --tls-key=$(TLS_KEY)
             - --tls-client-ca=$(TLS_CLIENT_CA)
             - --server-config=$(SERVER_CONFIG)
+            - --enable-programmed-set=$(ENABLE_PROGRAMMED_SET)
           env:
             - name: GRPC_ADDR
               value: ":5005"
@@ -73,6 +74,11 @@ spec:
             # mounted path to apply Coraza directives.
             - name: SERVER_CONFIG
               value: ""
+            # Off in production. The test-environment overlay sets this to "true"
+            # to serve the read-only /debug/programmed-set endpoint the parity
+            # test reads.
+            - name: ENABLE_PROGRAMMED_SET
+              value: "false"
           ports:
             - name: grpc
               containerPort: 5005

internal/extensionserver/cmd/run.go

@@ -68,13 +68,15 @@ func envBool(key string, def bool) bool {
 //	--tls-key=/tls/tls.key
 //	--tls-client-ca=/tls/ca.crt
 //	--server-config=/config/config.yaml  (optional; provides Coraza WAF config)
+//	--enable-programmed-set=false         (default off; test environments set true)
 type options struct {
-	grpcAddr      string
-	healthAddr    string
-	tlsCert       string
-	tlsKey        string
-	tlsClientCA   string
-	serverCfgFile string
+	grpcAddr            string
+	healthAddr          string
+	tlsCert             string
+	tlsKey              string
+	tlsClientCA         string
+	serverCfgFile       string
+	enableProgrammedSet bool
 }
 
 // NewCommand returns the "extension-server" subcommand.
@@ -99,6 +101,8 @@ func NewCommand() *cobra.Command {
 	fs.StringVar(&o.tlsKey, "tls-key", "", "Path to server TLS key (PEM)")
 	fs.StringVar(&o.tlsClientCA, "tls-client-ca", "", "Path to client CA certificate (PEM) for mTLS")
 	fs.StringVar(&o.serverCfgFile, "server-config", "", "Path to operator config file (optional; provides Coraza WAF settings)")
+	fs.BoolVar(&o.enableProgrammedSet, "enable-programmed-set", false,
+		"Serve the read-only /debug/programmed-set endpoint used by the parity test (test environments only)")
 
 	cmd := &cobra.Command{
 		Use:   "envoy-gateway-extension-server",
@@ -258,6 +262,9 @@ func run(o options) {
 		ConnectorInternalListener: serverConfig.Gateway.ConnectorTunnelListenerName(),
 		CorazaRouteBaseDirectives: coraza.RouteBaseDirectives,
 		LocalReply:                buildLocalReplyConfig(serverConfig.Gateway.ErrorPage, log),
+		// The programmed-set debug endpoint is for the test environment only; it
+		// stays off in production unless --enable-programmed-set is passed.
+		EnableProgrammedSet: o.enableProgrammedSet,
 	}
 
 	// --- gRPC panic recovery interceptor ---
@@ -450,9 +457,12 @@ func run(o options) {
 		}
 	})
 	mux.Handle("/metrics", promhttp.Handler())
-	// Debug endpoint that reports what the last build changed, so a test can
-	// confirm the proxy is running exactly that. Read-only; keeps only the last build.
-	mux.HandleFunc(extserver.ProgrammedSetEndpointPath, extSrv.ProgrammedSetHandler())
+	// Read-only debug endpoint that reports what the last build changed, so a test
+	// can confirm the proxy is running exactly that. Test environment only; it is
+	// not served in production. Keeps only the last build.
+	if srvCfg.EnableProgrammedSet {
+		mux.HandleFunc(extserver.ProgrammedSetEndpointPath, extSrv.ProgrammedSetHandler())
+	}
 	healthServer := &http.Server{
 		Addr:    healthAddr,
 		Handler: mux,

internal/extensionserver/server/programmedset_test.go

@@ -306,7 +306,10 @@ func TestPostTranslateModify_RecordsProgrammedSet(t *testing.T) {
 	cl := fake.NewClientBuilder().WithScheme(scheme).
 		WithObjects(ns, tpp, proxy).
 		WithStatusSubresource(connector).WithObjects(connector).Build()
-	srv := New(cl, testServerConfig(), discardLogger())
+	// Recording only happens when the test-environment endpoint is enabled.
+	cfg := testServerConfig()
+	cfg.EnableProgrammedSet = true
+	srv := New(cl, cfg, discardLogger())
 
 	req := &pb.PostTranslateModifyRequest{
 		Clusters: []*clusterv3.Cluster{{Name: connCluster}, {Name: "infra-cluster"}},
@@ -342,3 +345,19 @@ func TestPostTranslateModify_RecordsProgrammedSet(t *testing.T) {
 	require.Len(t, ps.Keys[FamilyWAFRoute], 1)
 	assert.Contains(t, ps.Keys[FamilyWAFRoute][0], "test-project/test-tpp/Observe")
 }
+
+// TestPostTranslateModify_NoRecordingWhenDisabled proves the production default:
+// with the test-only endpoint off, a build records nothing, so the snapshot
+// stays empty and no per-build work is done.
+func TestPostTranslateModify_NoRecordingWhenDisabled(t *testing.T) {
+	cl := fake.NewClientBuilder().WithScheme(testServerScheme(t)).Build()
+	// testServerConfig() leaves EnableProgrammedSet at its false default.
+	srv := New(cl, testServerConfig(), discardLogger())
+
+	_, err := srv.PostTranslateModify(context.Background(), &pb.PostTranslateModifyRequest{})
+	require.NoError(t, err)
+
+	ps := srv.programmed.snapshot()
+	assert.Equal(t, uint64(0), ps.BuildID, "no build was recorded")
+	assert.Empty(t, ps.Keys, "nothing recorded while the endpoint is disabled")
+}

internal/extensionserver/server/server.go

@@ -37,6 +37,12 @@ type ServerConfig struct {
 	// empty, local-reply injection is a no-op. Sourced from
 	// GatewayConfig.ErrorPage + the embedded/override HTML body.
 	LocalReply mutate.LocalReplyConfig
+	// EnableProgrammedSet turns on the read-only /debug/programmed-set endpoint
+	// and the per-build recording that backs it. It exists only to let a test
+	// confirm the proxy is running exactly the set the build intended, so it is
+	// off in production and enabled only in the test environment. When off, the
+	// build does no extra work and the endpoint is not served.
+	EnableProgrammedSet bool
 }
 
 // Server implements pb.EnvoyGatewayExtensionServer for the NSO production
@@ -332,13 +338,15 @@ func (s *Server) PostTranslateModify(
 	extmetrics.ConnectorRoutesTotal.Add(float64(vhCount))
 	extmetrics.ConnectorOfflineRoutesTotal.Add(float64(offlineRtCount))
 
-	// Record what this build changed so a test can later confirm the proxy is
-	// running exactly that. This only reads the configuration just produced; it
-	// changes nothing.
-	s.programmed.record(
-		listeners, routes, clusters, s.cfg.Coraza.FilterName,
-		prunedChains, prunedSecrets, listenersLeftIntact,
-	)
+	// In the test environment, record what this build changed so a test can later
+	// confirm the proxy is running exactly that. This only reads the configuration
+	// just produced; it changes nothing. Off in production, where it does no work.
+	if s.cfg.EnableProgrammedSet {
+		s.programmed.record(
+			listeners, routes, clusters, s.cfg.Coraza.FilterName,
+			prunedChains, prunedSecrets, listenersLeftIntact,
+		)
+	}
 
 	s.log.Info("PostTranslateModify",
 		"clusters", len(clusters),