Skip to content

feat: add host-network mode for Redis templates#259

Merged
joshrotenberg merged 1 commit into
mainfrom
feat/issue-247-host-network
Jun 11, 2026
Merged

feat: add host-network mode for Redis templates#259
joshrotenberg merged 1 commit into
mainfrom
feat/issue-247-host-network

Conversation

@joshrotenberg

Copy link
Copy Markdown
Owner

What

Adds host networking mode to the Redis templates, exposing network_mode(mode) and host_network() builder methods on both RedisTemplate and RedisClusterTemplate.

Why

RunCommand already supports network, but templates did not expose host mode. RedisClusterTemplate always created its own bridge network and therefore needed the --cluster-announce-ip ceremony for host-side clients. On Linux, --network host eliminates that ceremony entirely because container ports are real host ports.

How

RedisTemplate (single container):

  • host_network() / network_mode("host") set --network host.
  • In host mode, published port mappings are skipped (Docker ignores -p when sharing the host namespace); the Redis port is reachable directly on the host (6379 by default).

RedisClusterTemplate (multi-node):

  • host_network() / network_mode("host") enable host mode (network_mode only special-cases "host"; any other value keeps the default managed bridge).
  • In host mode the template:
    • skips creating and removing the private bridge network,
    • runs every node with --network host and no -p mappings,
    • gives each node a distinct listening port (port_base + index) so nodes do not collide in the shared host namespace,
    • skips the --cluster-announce-ip ceremony, and
    • wires redis-cli --cluster create, node readiness polling, node_role, and cluster_info to reach nodes on 127.0.0.1 at their distinct ports.
  • RedisClusterConnection::from_template and node(i).host_port already report port_base + index, which equals the real host port in host mode, so external clients connect to localhost:<port_base+index> with no changes.

Failure behavior on non-Linux

Host networking is a Linux-only Docker feature. On Docker Desktop for macOS/Windows the daemon runs in a Linux VM, so --network host binds inside that VM and is effectively a no-op. The methods do not return an error on non-Linux (the Docker CLI accepts the flag regardless of backend); this is documented loudly in the rustdoc, and the choice (no hard error, document the no-op) is stated explicitly.

Evidence / test plan

  • Unit tests (run everywhere, no Docker): basic-template --network host wiring + no --publish; cluster uses_host_network, node_internal_port, node_cluster_address, and build_ping_args for both bridge and host modes, including with a password.
  • Integration test test_redis_cluster_host_network_wiring_api asserts host-mode wiring through the public API (distinct host ports, host_port accessor, network_mode("host") == host_network()); runs without Docker.
  • Integration test test_redis_cluster_host_network_smoke_test is #[ignore] and gated to Linux via a runtime skip; the CI Docker Integration job (Ubuntu) exercises the Linux host path. It starts a real host-mode cluster, asserts it converges with no bridge network and no announce-ip, and cleans up.

Validation gate run locally (macOS):

  • cargo fmt --all
  • cargo clippy --all-targets --all-features -- -D warnings
  • cargo clippy --all-targets --no-default-features -- -D warnings
  • cargo test --lib --all-features (819 passed)
  • cargo doc --no-deps --all-features
  • cargo test --doc --all-features (416 passed)

Closes #247.

Add network_mode(mode) and host_network() builder methods to RedisTemplate
and RedisClusterTemplate so containers can run with --network host.

On the basic template, host mode skips published port mappings (Docker
ignores -p when sharing the host namespace) and the Redis port is reachable
directly on the host.

On the cluster template, host mode:
- skips creating and removing the private bridge network,
- runs every node with --network host and no -p mappings,
- gives each node a distinct listening port (port_base + index) so they do
  not collide in the shared host namespace,
- skips the --cluster-announce-ip ceremony entirely (host ports are real
  ports), and
- wires cluster create, readiness polling, role queries, and cluster info to
  reach nodes on 127.0.0.1 at their distinct ports.

Host networking is a Linux-only Docker feature; on Docker Desktop for
macOS/Windows it is a no-op. This is documented loudly in the rustdoc, and the
methods do not error on non-Linux (the CLI accepts the flag regardless of
backend). The Docker integration smoke test is gated to Linux via a runtime
skip and the CI Docker Integration job (Ubuntu) exercises the host path.

Closes #247
@joshrotenberg joshrotenberg merged commit 8d1b802 into main Jun 11, 2026
11 checks passed
@joshrotenberg joshrotenberg deleted the feat/issue-247-host-network branch June 11, 2026 20:34
@github-actions github-actions Bot mentioned this pull request Jun 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: host-network mode for templates

1 participant