feat: add extraPortMappings support to ClusterSpec

Expose KIND extraPortMappings in the forge config schema via a new
ports field on ClusterSpec. Enables mapping host ports to container
NodePorts for accessing services (Grafana, Prometheus, MLflow) from
the host machine.

Includes config validation, KIND config generation, and an integration
test with a port-mappings fixture.

Host bindings are validated through one environment-wide registry
covering both cluster mappings and service ports. They are published on
the same host by the same container runtime and so compete for one set
of bindings; two registries would let a cluster and a service both claim
8080/tcp, pass validation, and fail later during `forge up` with an
opaque "port is already allocated". A binding is (host port, protocol,
bind address): protocol is compared case-insensitively, TCP and UDP on
one port are distinct bindings that Docker and KIND both accept, and a
wildcard bind overlaps any other binding of that port and protocol while
two specific addresses conflict only when equal. Conflicts name both
claimants.

Signed-off-by: Ladislav Smola <lsmola@redhat.com>

Author: Ladas

src/cluster.rs

@@ -55,7 +55,7 @@ fn handle_create(ctx: &ForgeContext<'_>, name: &str, writer: &mut dyn Write) ->
     }
     let _lock = lock::acquire(&ctx.state_dir)?;
     let mut state = state::load(&ctx.state_dir)?;
-    let created = create_if_missing(ctx, &kind_name, &cluster.nodes, &mut state, name)?;
+    let created = create_if_missing(ctx, &kind_name, cluster, &mut state, name)?;
     state::save(&ctx.state_dir, &state)?;
     if created {
         report_created(writer, name, &kind_name, &ctx.format)
@@ -203,7 +203,7 @@ fn cluster_kind_name(ctx: &ForgeContext<'_>, name: &str) -> String {
 fn create_if_missing(
     ctx: &ForgeContext<'_>,
     kind_name: &str,
-    nodes: &crate::config::NodeConfig,
+    cluster: &crate::config::ClusterSpec,
     st: &mut state::ForgeState,
     name: &str,
 ) -> Result<bool, ForgeError> {
@@ -213,7 +213,13 @@ fn create_if_missing(
     }
     upsert_cluster_state(st, name, kind_name, ClusterPhase::Creating);
     state::save(&ctx.state_dir, st)?;
-    kind_ops::create_cluster(ctx.runner, kind_name, nodes, &ctx.state_dir, None)?;
+    let config = kind_ops::CreateClusterConfig {
+        nodes: &cluster.nodes,
+        ports: &cluster.ports,
+        config_dir: &ctx.state_dir,
+        docker_network: None,
+    };
+    kind_ops::create_cluster(ctx.runner, kind_name, &config)?;
     upsert_cluster_state(st, name, kind_name, ClusterPhase::Running);
     Ok(true)
 }

src/cluster/kind.rs

@@ -8,7 +8,7 @@ use std::collections::BTreeMap;
 
 use crate::{
     command::runner::{CommandOutput, CommandRunner, CommandSpec},
-    config::NodeConfig,
+    config::{NodeConfig, PortMapping},
     error::ForgeError,
 };
 
@@ -40,6 +40,18 @@ pub fn cluster_exists(runner: &dyn CommandRunner, kind_name: &str) -> Result<boo
     Ok(clusters.iter().any(|cl| cl == kind_name))
 }
 
+/// Configuration for creating a KIND cluster.
+pub struct CreateClusterConfig<'cfg> {
+    /// Node layout for the cluster.
+    pub nodes: &'cfg NodeConfig,
+    /// Port mappings to add to the first control-plane node.
+    pub ports: &'cfg [PortMapping],
+    /// Directory where config files are written.
+    pub config_dir: &'cfg std::path::Path,
+    /// Optional Docker network to join via `KIND_EXPERIMENTAL_DOCKER_NETWORK`.
+    pub docker_network: Option<&'cfg str>,
+}
+
 /// Create a KIND cluster with a generated config.
 ///
 /// When `docker_network` is `Some`, the cluster nodes join that
@@ -51,13 +63,11 @@ pub fn cluster_exists(runner: &dyn CommandRunner, kind_name: &str) -> Result<boo
 pub fn create_cluster(
     runner: &dyn CommandRunner,
     kind_name: &str,
-    nodes: &NodeConfig,
-    config_dir: &std::path::Path,
-    docker_network: Option<&str>,
+    config: &CreateClusterConfig<'_>,
 ) -> Result<(), ForgeError> {
-    let config_yaml = generate_kind_config(nodes);
-    let config_path = write_kind_config(config_dir, kind_name, &config_yaml)?;
-    let result = run_create(runner, kind_name, &config_path, docker_network);
+    let config_yaml = generate_kind_config(config.nodes, config.ports);
+    let config_path = write_kind_config(config.config_dir, kind_name, &config_yaml)?;
+    let result = run_create(runner, kind_name, &config_path, config.docker_network);
     cleanup_kind_config(&config_path);
     result
 }
@@ -126,17 +136,42 @@ pub fn run_kubectl(runner: &dyn CommandRunner, kind_name: &str, args: &[String])
 // ---------------------------------------------------------------
 
 /// Generate a KIND cluster config YAML from a [`NodeConfig`].
-pub fn generate_kind_config(nodes: &NodeConfig) -> String {
+///
+/// When `ports` is non-empty, `extraPortMappings` entries are added
+/// to the first control-plane node (KIND only supports port mappings
+/// on control-plane nodes).
+pub fn generate_kind_config(nodes: &NodeConfig, ports: &[PortMapping]) -> String {
     let mut yaml = String::from("kind: Cluster\napiVersion: kind.x-k8s.io/v1alpha4\nnodes:\n");
-    for _ in 0..nodes.control_planes {
+    for idx in 0..nodes.control_planes {
         yaml.push_str("  - role: control-plane\n");
+        if idx == 0 && !ports.is_empty() {
+            write_port_mappings(&mut yaml, ports);
+        }
     }
     for _ in 0..nodes.workers {
         yaml.push_str("  - role: worker\n");
     }
     yaml
 }
 
+/// Append `extraPortMappings` entries for a control-plane node.
+fn write_port_mappings(yaml: &mut String, ports: &[PortMapping]) {
+    use std::fmt::Write as _;
+    yaml.push_str("    extraPortMappings:\n");
+    for port in ports {
+        let _written = write!(
+            yaml,
+            "      - hostPort: {}\n        containerPort: {}\n        protocol: {}\n",
+            port.host,
+            port.container,
+            port.protocol.to_uppercase(),
+        );
+        if let Some(addr) = &port.bind_address {
+            let _addr_written = writeln!(yaml, "        listenAddress: \"{addr}\"");
+        }
+    }
+}
+
 // ---------------------------------------------------------------
 // Private helpers
 // ---------------------------------------------------------------
@@ -292,7 +327,7 @@ mod tests {
     #[test]
     fn generate_kind_config_default_nodes() {
         let nodes = NodeConfig::default();
-        let yaml = generate_kind_config(&nodes);
+        let yaml = generate_kind_config(&nodes, &[]);
         assert!(yaml.contains("control-plane"), "should have control-plane");
         let cp_count = yaml.matches("control-plane").count();
         assert_eq!(cp_count, 1, "default should have 1 control-plane, got {cp_count}");
@@ -305,13 +340,62 @@ mod tests {
             control_planes: 3,
             workers: 2,
         };
-        let yaml = generate_kind_config(&nodes);
+        let yaml = generate_kind_config(&nodes, &[]);
         let cp_count = yaml.matches("control-plane").count();
         let w_count = yaml.matches("worker").count();
         assert_eq!(cp_count, 3, "should have 3 control-planes, got {cp_count}");
         assert_eq!(w_count, 2, "should have 2 workers, got {w_count}");
     }
 
+    #[test]
+    fn generate_kind_config_with_port_mappings() {
+        let nodes = NodeConfig::default();
+        let ports = vec![
+            PortMapping {
+                bind_address: None,
+                host: 13000,
+                container: 30300,
+                protocol: "tcp".to_owned(),
+            },
+            PortMapping {
+                bind_address: Some("127.0.0.1".to_owned()),
+                host: 19090,
+                container: 30909,
+                protocol: "udp".to_owned(),
+            },
+        ];
+        let yaml = generate_kind_config(&nodes, &ports);
+        assert!(yaml.contains("extraPortMappings:"), "should have extraPortMappings");
+        assert!(yaml.contains("hostPort: 13000"), "should map first host port");
+        assert!(yaml.contains("containerPort: 30300"), "should map first container port");
+        assert!(yaml.contains("hostPort: 19090"), "should map second host port");
+        assert!(yaml.contains("protocol: UDP"), "should uppercase protocol");
+        assert!(
+            yaml.contains("listenAddress: \"127.0.0.1\""),
+            "should include listen address"
+        );
+    }
+
+    #[test]
+    fn generate_kind_config_port_mappings_only_on_first_control_plane() {
+        let nodes = NodeConfig {
+            control_planes: 2,
+            workers: 0,
+        };
+        let ports = vec![PortMapping {
+            bind_address: None,
+            host: 8080,
+            container: 30080,
+            protocol: "tcp".to_owned(),
+        }];
+        let yaml = generate_kind_config(&nodes, &ports);
+        assert_eq!(
+            yaml.matches("extraPortMappings:").count(),
+            1,
+            "port mappings should only appear on the first control-plane node"
+        );
+    }
+
     #[test]
     fn parse_cluster_list_handles_empty() {
         let output = CommandOutput {

src/command/up.rs

@@ -217,7 +217,13 @@ fn create_if_missing(
     }
     ensure_state_entry(state, &cluster.name, kind_name, ClusterPhase::Creating);
     checkpoint(ctx, state)?;
-    kind_ops::create_cluster(ctx.runner, kind_name, &cluster.nodes, &ctx.state_dir, docker_network)?;
+    let cluster_config = kind_ops::CreateClusterConfig {
+        nodes: &cluster.nodes,
+        ports: &cluster.ports,
+        config_dir: &ctx.state_dir,
+        docker_network,
+    };
+    kind_ops::create_cluster(ctx.runner, kind_name, &cluster_config)?;
     ensure_state_entry(state, &cluster.name, kind_name, ClusterPhase::Running);
     Ok(true)
 }

src/config.rs

@@ -163,6 +163,13 @@ pub struct ClusterSpec {
     /// Node layout for this Kind cluster.
     #[serde(default)]
     pub nodes: NodeConfig,
+    /// Host-to-node port mappings (Kind `extraPortMappings`).
+    ///
+    /// Maps host ports to Kind node ports via `extraPortMappings` in the
+    /// Kind cluster config. Required on macOS where `MetalLB` `LoadBalancer`
+    /// IPs are unreachable from the host.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub ports: Vec<PortMapping>,
     /// Stacks to apply to this cluster (must exist in `spec.stacks`).
     #[serde(default)]
     pub stacks: Vec<String>,