fix(cli): pass cluster name to ssh-proxy child process for correct TLS path resolution (#52)

Author: drew

.env.example

@@ -1,10 +1,8 @@
 # Navigator local development environment
 # Copy to .env and customise. Mise loads .env automatically.
 #
-# Local clusters bind Kubernetes API port 6443 on the host, so only one local
-# Navigator cluster can run at a time on a given Docker host.
-# Use unique CLUSTER_NAME/GATEWAY_PORT values per worktree to make switching
-# predictable; `mise run cluster` will recreate as needed.
+# Use unique CLUSTER_NAME/GATEWAY_PORT values per worktree to run
+# multiple clusters simultaneously; `mise run cluster` will recreate as needed.
 
 # ---------- Cluster identity ----------
 
@@ -22,3 +20,9 @@
 # Host port mapped to the k3s NodePort (30051) where the Navigator gateway
 # listens.  The CLI connects here.  Must be unique per cluster.
 #GATEWAY_PORT=8080
+
+# Expose the Kubernetes control plane on this host port (maps to 6443
+# inside the container).  Leave unset to skip the binding — this is the
+# default and allows multiple clusters to coexist without port conflicts.
+# Set this only when you need direct kubectl access to the cluster.
+#KUBE_PORT=6443

build/scripts/cluster-bootstrap.sh

@@ -85,13 +85,6 @@ pick_random_port() {
   return 1
 }
 
-list_6443_conflicts() {
-  docker ps --format '{{.Names}} {{.Ports}}' | awk '
-    $0 ~ /0\.0\.0\.0:6443->6443\/tcp/ || $0 ~ /:::6443->6443\/tcp/ {
-      print $1
-    }'
-}
-
 CLUSTER_NAME=${CLUSTER_NAME:-$(basename "$PWD")}
 
 if [ -n "${GATEWAY_PORT:-}" ]; then
@@ -210,25 +203,6 @@ CONTAINER_NAME="navigator-cluster-${CLUSTER_NAME}"
 VOLUME_NAME="navigator-cluster-${CLUSTER_NAME}"
 
 if [ "${MODE}" = "fast" ]; then
-  mapfile -t port_conflicts < <(list_6443_conflicts || true)
-  for cname in "${port_conflicts[@]:-}"; do
-    [ -n "${cname}" ] || continue
-    if [ "${cname}" = "${CONTAINER_NAME}" ]; then
-      continue
-    fi
-
-    if [[ "${cname}" == navigator-cluster-* ]]; then
-      other_cluster=${cname#navigator-cluster-}
-      echo "Removing conflicting local cluster '${other_cluster}' (holds host port 6443)..."
-      nav cluster admin destroy --name "${other_cluster}"
-      continue
-    fi
-
-    echo "Error: container '${cname}' is using host port 6443, which Navigator clusters require." >&2
-    echo "Stop/remove that container, then retry 'mise run cluster'." >&2
-    exit 1
-  done
-
   if docker inspect "${CONTAINER_NAME}" >/dev/null 2>&1 || docker volume inspect "${VOLUME_NAME}" >/dev/null 2>&1; then
     echo "Recreating cluster '${CLUSTER_NAME}' from scratch..."
     nav cluster admin destroy --name "${CLUSTER_NAME}"
@@ -243,9 +217,10 @@ elif [ "${MODE}" = "build" ] || [ "${MODE}" = "fast" ]; then
   done
 fi
 
-GATEWAY_HOST_ARGS=()
+DEPLOY_CMD=(nav cluster admin deploy --name "${CLUSTER_NAME}" --port "${GATEWAY_PORT}" --update-kube-config)
+
 if [ -n "${GATEWAY_HOST:-}" ]; then
-  GATEWAY_HOST_ARGS+=(--gateway-host "${GATEWAY_HOST}")
+  DEPLOY_CMD+=(--gateway-host "${GATEWAY_HOST}")
 
   # Ensure the gateway host resolves from the current environment.
   # On Linux CI runners host.docker.internal is not set automatically
@@ -260,7 +235,15 @@ if [ -n "${GATEWAY_HOST:-}" ]; then
   fi
 fi
 
-nav cluster admin deploy --name "${CLUSTER_NAME}" --port "${GATEWAY_PORT}" "${GATEWAY_HOST_ARGS[@]}" --update-kube-config
+if [ -n "${KUBE_PORT:-}" ]; then
+  # Explicit port requested — pass it through.
+  DEPLOY_CMD+=(--kube-port "${KUBE_PORT}")
+else
+  # Auto-select a free port so kubectl works during local development.
+  DEPLOY_CMD+=(--kube-port)
+fi
+
+"${DEPLOY_CMD[@]}"
 
 echo ""
 echo "Cluster '${CLUSTER_NAME}' is ready."

crates/navigator-bootstrap/src/docker.rs

@@ -198,6 +198,7 @@ pub async fn ensure_container(
     extra_sans: &[String],
     ssh_gateway_host: Option<&str>,
     gateway_port: u16,
+    kube_port: Option<u16>,
 ) -> Result<()> {
     let container_name = container_name(name);
 
@@ -256,21 +257,26 @@ pub async fn ensure_container(
     }
 
     let mut port_bindings = HashMap::new();
-    port_bindings.insert(
-        "6443/tcp".to_string(),
-        Some(vec![PortBinding {
-            host_ip: Some("0.0.0.0".to_string()),
-            host_port: Some("6443".to_string()),
-        }]),
-    );
+    if let Some(kp) = kube_port {
+        port_bindings.insert(
+            "6443/tcp".to_string(),
+            Some(vec![PortBinding {
+                host_ip: Some("0.0.0.0".to_string()),
+                host_port: Some(kp.to_string()),
+            }]),
+        );
+    }
     port_bindings.insert(
         "30051/tcp".to_string(),
         Some(vec![PortBinding {
             host_ip: Some("0.0.0.0".to_string()),
             host_port: Some(gateway_port.to_string()),
         }]),
     );
-    let exposed_ports = vec!["6443/tcp".to_string(), "30051/tcp".to_string()];
+    let mut exposed_ports = vec!["30051/tcp".to_string()];
+    if kube_port.is_some() {
+        exposed_ports.push("6443/tcp".to_string());
+    }
 
     let host_config = HostConfig {
         privileged: Some(true),

crates/navigator-bootstrap/src/kubeconfig.rs

@@ -94,26 +94,36 @@ pub fn store_kubeconfig(path: &Path, contents: &str) -> Result<()> {
 
 /// Rewrite kubeconfig for remote deployment.
 ///
-/// The kubeconfig points to 127.0.0.1:6443, which works with an SSH tunnel:
-/// `ssh -L 6443:127.0.0.1:6443 user@host`
+/// The kubeconfig points to `127.0.0.1:<kube_port>`, which works with an SSH tunnel:
+/// `ssh -L <kube_port>:127.0.0.1:6443 user@host`
 ///
 /// The cluster name includes "-remote" suffix to distinguish from local clusters.
-pub fn rewrite_kubeconfig_remote(contents: &str, cluster_name: &str, _destination: &str) -> String {
-    // Use the same rewrite logic but with a remote-specific cluster name
-    // The server address stays as 127.0.0.1:6443 because users will use SSH tunneling
+pub fn rewrite_kubeconfig_remote(
+    contents: &str,
+    cluster_name: &str,
+    _destination: &str,
+    kube_port: Option<u16>,
+) -> String {
     let remote_name = format!("{cluster_name}-remote");
-    rewrite_kubeconfig(contents, &remote_name)
+    rewrite_kubeconfig(contents, &remote_name, kube_port)
 }
 
-pub fn rewrite_kubeconfig(contents: &str, cluster_name: &str) -> String {
+/// Rewrite the raw k3s kubeconfig for use on the host.
+///
+/// When `kube_port` is `Some`, the server URL is rewritten to
+/// `https://127.0.0.1:<kube_port>`. When `None`, the original server URL
+/// is left intact (the control plane is not exposed on the host).
+pub fn rewrite_kubeconfig(contents: &str, cluster_name: &str, kube_port: Option<u16>) -> String {
     let mut replaced = Vec::new();
     for line in contents.lines() {
         let trimmed = line.trim_start();
-        if trimmed.starts_with("server:") {
-            let indent_len = line.len() - trimmed.len();
-            let indent = &line[..indent_len];
-            replaced.push(format!("{indent}server: https://127.0.0.1:6443"));
-            continue;
+        if let Some(kp) = kube_port {
+            if trimmed.starts_with("server:") {
+                let indent_len = line.len() - trimmed.len();
+                let indent = &line[..indent_len];
+                replaced.push(format!("{indent}server: https://127.0.0.1:{kp}"));
+                continue;
+            }
         }
         // Rename default cluster/context/user to the cluster name
         // Handle both "name: default" and "- name: default" (YAML list item)
@@ -237,16 +247,34 @@ mod tests {
     use super::rewrite_kubeconfig;
 
     #[test]
-    fn rewrite_updates_server_address() {
+    fn rewrite_updates_server_address_with_kube_port() {
         let input = "apiVersion: v1\nclusters:\n- cluster:\n    server: https://10.0.0.1:6443\n";
-        let output = rewrite_kubeconfig(input, "test-cluster");
+        let output = rewrite_kubeconfig(input, "test-cluster", Some(6443));
         assert!(output.contains("server: https://127.0.0.1:6443"));
     }
 
+    #[test]
+    fn rewrite_updates_server_address_custom_port() {
+        let input = "apiVersion: v1\nclusters:\n- cluster:\n    server: https://10.0.0.1:6443\n";
+        let output = rewrite_kubeconfig(input, "test-cluster", Some(7443));
+        assert!(output.contains("server: https://127.0.0.1:7443"));
+        assert!(!output.contains("server: https://127.0.0.1:6443"));
+    }
+
+    #[test]
+    fn rewrite_preserves_server_when_no_kube_port() {
+        let input = "apiVersion: v1\nclusters:\n- cluster:\n    server: https://10.0.0.1:6443\n";
+        let output = rewrite_kubeconfig(input, "test-cluster", None);
+        assert!(
+            output.contains("server: https://10.0.0.1:6443"),
+            "server address should be preserved when kube_port is None"
+        );
+    }
+
     #[test]
     fn rewrite_preserves_trailing_newline() {
         let input = "apiVersion: v1\nserver: https://10.0.0.1\n";
-        let output = rewrite_kubeconfig(input, "test-cluster");
+        let output = rewrite_kubeconfig(input, "test-cluster", Some(6443));
         assert!(output.ends_with('\n'));
     }
 
@@ -266,7 +294,7 @@ mod tests {
  - name: default
  current-context: default
  ";
-        let output = rewrite_kubeconfig(input, "my-cluster");
+        let output = rewrite_kubeconfig(input, "my-cluster", Some(6443));
         assert!(
             output.contains("name: my-cluster"),
             "should contain 'name: my-cluster'"

crates/navigator-bootstrap/src/lib.rs

@@ -76,6 +76,15 @@ impl RemoteOptions {
 /// Default host port that maps to the k3s `NodePort` (30051) for the gateway.
 pub const DEFAULT_GATEWAY_PORT: u16 = 8080;
 
+/// Find a random available TCP port by binding to port 0.
+///
+/// Binds to `127.0.0.1:0` and returns the OS-assigned port.
+pub fn pick_available_port() -> Result<u16> {
+    let listener = std::net::TcpListener::bind("127.0.0.1:0").into_diagnostic()?;
+    let port = listener.local_addr().into_diagnostic()?.port();
+    Ok(port)
+}
+
 #[derive(Debug, Clone)]
 pub struct DeployOptions {
     pub name: String,
@@ -90,6 +99,10 @@ pub struct DeployOptions {
     /// Useful in CI where `127.0.0.1` is not reachable from the test runner
     /// (e.g., `host.docker.internal`).
     pub gateway_host: Option<String>,
+    /// Host port to expose the k3s Kubernetes control plane on.
+    /// When `None`, the control plane port (6443) is not exposed on the host,
+    /// allowing multiple clusters to run simultaneously without port conflicts.
+    pub kube_port: Option<u16>,
 }
 
 impl DeployOptions {
@@ -100,6 +113,7 @@ impl DeployOptions {
             remote: None,
             port: DEFAULT_GATEWAY_PORT,
             gateway_host: None,
+            kube_port: None,
         }
     }
 
@@ -123,6 +137,14 @@ impl DeployOptions {
         self.gateway_host = Some(host.into());
         self
     }
+
+    /// Set the host port for the k3s Kubernetes control plane.
+    /// When set, the control plane is accessible via `kubectl` at this port.
+    #[must_use]
+    pub fn with_kube_port(mut self, kube_port: u16) -> Self {
+        self.kube_port = Some(kube_port);
+        self
+    }
 }
 
 #[derive(Debug, Clone)]
@@ -184,6 +206,7 @@ where
     let image_ref = options.image_ref.unwrap_or_else(default_cluster_image_ref);
     let port = options.port;
     let gateway_host = options.gateway_host;
+    let kube_port = options.kube_port;
     let kubeconfig_path = stored_kubeconfig_path(&name)?;
 
     // Wrap on_log in Arc<Mutex<>> so we can share it with pull_remote_image
@@ -273,6 +296,7 @@ where
         &extra_sans,
         ssh_gateway_host.as_deref(),
         port,
+        kube_port,
     )
     .await?;
     log("[status] Starting cluster container".to_string());
@@ -283,8 +307,8 @@ where
 
     // Rewrite kubeconfig based on deployment mode
     let rewritten = remote_opts.as_ref().map_or_else(
-        || rewrite_kubeconfig(&raw_kubeconfig, &name),
-        |opts| rewrite_kubeconfig_remote(&raw_kubeconfig, &name, &opts.destination),
+        || rewrite_kubeconfig(&raw_kubeconfig, &name, kube_port),
+        |opts| rewrite_kubeconfig_remote(&raw_kubeconfig, &name, &opts.destination, kube_port),
     );
     log("[status] Writing kubeconfig".to_string());
     store_kubeconfig(&kubeconfig_path, &rewritten)?;
@@ -384,6 +408,7 @@ where
         &name,
         remote_opts.as_ref(),
         port,
+        kube_port,
         ssh_gateway_host.as_deref(),
     );
     store_cluster_metadata(&name, &metadata)?;
@@ -407,9 +432,9 @@ pub fn cluster_handle(name: &str, remote: Option<&RemoteOptions>) -> Result<Clus
     };
     let kubeconfig_path = stored_kubeconfig_path(name)?;
     // Try to load existing metadata, fall back to creating new metadata
-    // with the default port (the actual port is only known at deploy time).
+    // with the default ports (the actual ports are only known at deploy time).
     let metadata = load_cluster_metadata(name)
-        .unwrap_or_else(|_| create_cluster_metadata(name, remote, DEFAULT_GATEWAY_PORT));
+        .unwrap_or_else(|_| create_cluster_metadata(name, remote, DEFAULT_GATEWAY_PORT, None));
     Ok(ClusterHandle {
         name: name.to_string(),
         kubeconfig_path,