From 7ac161e22d7a03aa6ff7ae17b726fe8feaed578a Mon Sep 17 00:00:00 2001
From: Mallory Hill <mahill@redhat.com>
Date: Mon, 11 May 2026 17:31:37 -0400
Subject: [PATCH] HYPERFLEET-839 - fix: update additional docs/scripts to
 explicitly set NAMESPACE

---
 deploy-scripts/lib/gcp.sh | 17 ++++++++++++-----
 docs/runbook.md           | 22 +++++++++++++++-------
 2 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/deploy-scripts/lib/gcp.sh b/deploy-scripts/lib/gcp.sh
index 7f4da83..41b2be9 100644
--- a/deploy-scripts/lib/gcp.sh
+++ b/deploy-scripts/lib/gcp.sh
@@ -3,7 +3,12 @@
 # gcp.sh - Google Cloud Platform resource management functions
 #
 # This module handles discovery and cleanup of GCP resources (Pub/Sub topics and subscriptions)
-# created during deployment
+# created during deployment.
+#
+# NAMESPACE requirements
+# - Must be unique to prevent Pub/Sub topic/subscription collisions across deployments
+# - Must be DNS-1123 compliant (lowercase alphanumeric, hyphens, start/end with alphanumeric)
+# - Default: hyperfleet-e2e-$USER (when using .env configuration)
 
 # ============================================================================
 # Constants
@@ -48,10 +53,11 @@ discover_pubsub_topics() {
     fi
 
     # List topics that match the namespace pattern
+    # NAMESPACE must be unique and DNS-1123 compliant (default: hyperfleet-e2e-$USER when using .env)
     # Topics are named:
-    #   - ${NAMESPACE}-${resource_type}  (e.g., hyperfleet-e2e-clusters, hyperfleet-e2e-nodepools)
-    #   - ${NAMESPACE}-${resource_type}-dlq  (e.g., hyperfleet-e2e-clusters-dlq)
-    #   - ${NAMESPACE}-${resource_type}-${adapter_name}-dlq  (e.g., testb-clusters-cl-namespace-dlq) - ACTUAL (Temporary))
+    #   - ${NAMESPACE}-${resource_type}  (e.g., hyperfleet-e2e-jdoe-clusters, hyperfleet-e2e-jdoe-nodepools)
+    #   - ${NAMESPACE}-${resource_type}-dlq  (e.g., hyperfleet-e2e-jdoe-clusters-dlq)
+    #   - ${NAMESPACE}-${resource_type}-${adapter_name}-dlq  (e.g., hyperfleet-e2e-jdoe-clusters-adapter1-dlq)
     local topics=()
     local all_topics
 
@@ -114,8 +120,9 @@ discover_pubsub_subscriptions() {
     fi
 
     # List subscriptions that match the namespace pattern
+    # NAMESPACE must be unique and DNS-1123 compliant (default: hyperfleet-e2e-$USER when using .env)
     # Subscriptions are named: ${NAMESPACE}-${resource_type}-${adapter_name}
-    # Example: hyperfleet-e2e-clusters-example1-namespace, hyperfleet-e2e-nodepools-validation
+    # Example: hyperfleet-e2e-jdoe-clusters-adapter1, <unique-namespace>-clusters-adapter1
     local subscriptions=()
     local all_subscriptions
 
diff --git a/docs/runbook.md b/docs/runbook.md
index c3e376a..28f7e03 100644
--- a/docs/runbook.md
+++ b/docs/runbook.md
@@ -153,6 +153,14 @@ export NODEPOOL_TIER0_ADAPTERS_DEPLOYMENT="${NODEPOOL_TIER0_ADAPTERS_DEPLOYMENT:
 # Adapters for API cluster/nodepool configuration
 export API_ADAPTERS_CLUSTER="${API_ADAPTERS_CLUSTER:-cl-namespace,cl-job,cl-deployment,cl-maestro}"
 export API_ADAPTERS_NODEPOOL="${API_ADAPTERS_NODEPOOL:-np-configmap}"
+
+
+# NAMESPACE must be unique to prevent GCP Pub/Sub topic/subscription collisions.
+# Set in the .env.example file as:
+export NAMESPACE="${NAMESPACE:-hyperfleet-e2e-$(echo ${USER:-default} | tr '[:upper:]' '[:lower:]')}"
+# Or can manually set it with as the namespace is DNS-1123 compliant
+export NAMESPACE=<unique_namespace>
+
 ```
 
 #### Verify Deployment
@@ -261,8 +269,8 @@ The following tools are available to help debug and interact with HyperFleet com
 **Important:** Set the `NAMESPACE` environment variable to match the namespace used during deployment. Some test cases deploy adapters dynamically and need to target the same namespace where your HyperFleet components are running.
 
 ```bash
-# Set NAMESPACE if you deployed to a custom namespace
-export NAMESPACE=my-custom-namespace
+# Set NAMESPACE if you deployed to a unique namespace
+export NAMESPACE=<unique_namespace>
 ./bin/hyperfleet-e2e test --label-filter=tier0
 ```
 
@@ -281,7 +289,7 @@ Unexpected error:
 
 1. **Check if all pods are running:**
    ```bash
-   kubectl get pods -n hyperfleet-e2e
+   kubectl get pods -n ${NAMESPACE}
    ```
 
    Expected output - all pods should show `Running` with `READY 1/1`:
@@ -296,13 +304,13 @@ Unexpected error:
 2. **Check pod logs for errors:**
    ```bash
    # Check API logs
-   kubectl logs -n hyperfleet-e2e deployment/hyperfleet-api --tail=50
+   kubectl logs -n ${NAMESPACE} deployment/hyperfleet-api --tail=50
 
    # Check Sentinel logs
-   kubectl logs -n hyperfleet-e2e deployment/hyperfleet-sentinel --tail=50
+   kubectl logs -n ${NAMESPACE} deployment/hyperfleet-sentinel --tail=50
 
    # Check adapter logs
-   kubectl logs -n hyperfleet-e2e deployment/cl-namespace-adapter --tail=50
+   kubectl logs -n ${NAMESPACE} deployment/cl-namespace-adapter --tail=50
    ```
 
 3. **Verify API connectivity:**
@@ -314,7 +322,7 @@ Unexpected error:
 4. **Check service endpoints:**
    ```bash
    # Verify LoadBalancer has external IP
-   kubectl get svc -n hyperfleet-e2e hyperfleet-api
+   kubectl get svc -n ${NAMESPACE} hyperfleet-api
    ```