Enhance pool namespace resolution: use flag if set, else NAMESPACE en… (kubernetes-sigs#1578)

* Enhance pool namespace resolution: use flag if set, else NAMESPACE env var, else default; add documentation for behavior

* address comments

* treat empty string as unset, use flag value if non-empty, else env var, else default

* address comments

* update doc

* relocate document

Author: jyizheng

cmd/epp/runner/runner.go

@@ -83,7 +83,7 @@ var (
 	enablePprof    = flag.Bool("enable-pprof", runserver.DefaultEnablePprof, "Enables pprof handlers. Defaults to true. Set to false to disable pprof handlers.")
 	poolName       = flag.String("pool-name", runserver.DefaultPoolName, "Name of the InferencePool this Endpoint Picker is associated with.")
 	poolGroup      = flag.String("pool-group", runserver.DefaultPoolGroup, "group of the InferencePool this Endpoint Picker is associated with.")
-	poolNamespace  = flag.String("pool-namespace", runserver.DefaultPoolNamespace, "Namespace of the InferencePool this Endpoint Picker is associated with.")
+	poolNamespace  = flag.String("pool-namespace", "", "Namespace of the InferencePool this Endpoint Picker is associated with.")
 	logVerbosity   = flag.Int("v", logging.DEFAULT, "number for the log level verbosity")
 	secureServing  = flag.Bool("secure-serving", runserver.DefaultSecureServing, "Enables secure serving. Defaults to true.")
 	healthChecking = flag.Bool("health-checking", runserver.DefaultHealthChecking, "Enables health checking")
@@ -195,9 +195,20 @@ func (r *Runner) Run(ctx context.Context) error {
 		FilterProvider: filters.WithAuthenticationAndAuthorization,
 	}
 
+	// Determine pool namespace: if --pool-namespace is non-empty, use it; else NAMESPACE env var; else default
+	resolvePoolNamespace := func() string {
+		if *poolNamespace != "" {
+			return *poolNamespace
+		}
+		if nsEnv := os.Getenv("NAMESPACE"); nsEnv != "" {
+			return nsEnv
+		}
+		return runserver.DefaultPoolNamespace
+	}
+	resolvedPoolNamespace := resolvePoolNamespace()
 	poolNamespacedName := types.NamespacedName{
 		Name:      *poolName,
-		Namespace: *poolNamespace,
+		Namespace: resolvedPoolNamespace,
 	}
 	poolGroupKind := schema.GroupKind{
 		Group: *poolGroup,

site-src/guides/epp-configuration/flags.md

@@ -0,0 +1,33 @@
+# EPP Configuration Flags
+
+This page documents selected configuration flags for the Endpoint Picker (EPP) binary. Most flags are self-explanatory via their `--help` descriptions; only flags with nuanced or non-obvious behavior are detailed here.
+
+## --pool-namespace
+
+**Description:**
+Specifies the namespace of the InferencePool this Endpoint Picker is associated with.
+
+**Resolution order:**
+1. If `--pool-namespace` is set to a non-empty value, its value is used.
+2. If the flag is not set (i.e., left empty), the `NAMESPACE` environment variable is checked. If set, its value is used.
+3. If neither is set, the namespace defaults to `default`.
+
+This allows the EPP to automatically use the namespace it is running in (when the `NAMESPACE` env var is set via Kubernetes Downward API), without requiring explicit configuration. If you want to force the use of the default namespace, explicitly set `--pool-namespace=default`. If you want to use the environment variable or fallback, leave the flag unset or set it to an empty string.
+
+**Example manifest snippet to set the env var from pod metadata:**
+
+```yaml
+env:
+  - name: NAMESPACE
+    valueFrom:
+      fieldRef:
+        fieldPath: metadata.namespace
+```
+
+---
+
+For a full list of flags, run:
+
+```
+EPP_BINARY --help
+```