NationTech/harmony
5
0
Fork 2
Code Issues 40 Pull Requests 13 Actions Packages Projects Releases Wiki Activity
Files
chore/leftover-adr
harmony/adr/014-infrastructure-network-ports.md

5.7 KiB
Raw Permalink Blame History

ADR‑014 · Port Allocation Policy

Date: 2025‑11‑03
Status: Proposed
Authors: Infrastructure Team / NationTech Harmony Core

1 · Context

Harmony orchestrates heterogeneous clusters — from developer laptops to multi‑tenant production environments — through a single, typed Rust codebase.
To enable deterministic, automatable service exposure across clusters, we need a stable, conflict‑free range of TCP/UDP ports reserved for Harmony‑managed workloads and host‑network services.

Today, various manual operations (e.g. Ceph RGW on host network) occasionally use ad‑hoc local ports such as 80 or 8080. This leads to unpredictable overlaps with NodePorts, ephemeral ports, or other daemons.

Since Harmony aims to unify manual and automated infrastructure under a single declarative model, we formalize a reserved port block that should be used consistently — even for out‑of‑band operations — so everything remains alignment‑ready for future orchestration.

2 · Problem Statement

We must select a contiguous range of approximately 1000 ports that:

  1. Avoids conflict with:
    • System / well‑known ports (0–1023)
    • Common registered application ports (1024–49151)
    • Kubernetes NodePort default range (30 000–32 767)
    • Ephemeral port ranges (typically 32 768–60 999 on Linux)
  2. Feels deterministic and maintainable for long‑term automation.
  3. Can be mirrored across multiple clusters and bare‑metal hosts.

3 · Decision

We designate:

Harmony Reserved Port Range: 25 000 – 25 999

Rationale

Criterion Reasoning
Safety Lies below the default ephemeral port start (32 768) and above NodePort (30 000–32 767).
Conflicts Very few historical IANA registrations in this span, practically unused in modern systems.
Predictability Easy to recognize and communicate (25k‑block for Harmony).
Ergonomics Mirrors production service conventions (25080 for HTTP‑like, 25443 for HTTPS‑like, etc.).
Cross‑cluster consistency Portable across OKD, K3D, bare‑metal – allows static firewall rules.

This range is registered (per IANA definition 1024–49151) but not occupied. Choosing such a mid‑registered band is intentional: it guarantees good inter‑platform compatibility without interfering with OS‑managed ephemeral allocations.

4 · Integration in Harmony

Harmony’s topology and orchestration layers should expose a built‑in PortAllocator resource:

let orchestrator_ports = harmony::network::PortAllocator::new(25_000, 25_999);
let rados_gateway_port = orchestrator_ports.allocate("ceph-rgw")?;

In TOML configuration:

[harmony.network.defaults]
orchestrator_port_range = "25000-25999"

All Score / Interpret modules that deploy host‑network or externally visible services should use this allocator to pick ports deterministically.

5 · Operational Guidance

  • Manual Operations: Even manually configured host‑network services on clusters we manage (e.g. Ceph RGW, ntfy, reverse proxy tests) should adopt ports within 25 000–25 999.
  • Automation Alignment: Any such ports are considered Harmony‑manageable and may be introspected later by the orchestrator.
  • Firewall Rules: Cluster and site firewalls may pre‑whitelist this block as “Harmony Infra Ports”.

6 · Initial Allocation Table

Service / Component Port Notes
Ceph RADOS Gateway  25080  Replacement for :80; public HTTP front‑end via RGW (host network).
Internal HTTPS Services  25443 Equivalent of :443 for secure endpoints.
Prometheus / Metrics Endpoints  25090–25099 Internal observability.
Harmony Control Plane (gRPC)  25500–25519 Inter‑process messaging, API, TUI backend.
Reserved for Future Scores  25550–25599 Dedicated expansion slots.

These values shall be managed centrally in a harmony.network.ports registry file (YAML / TOML) within the repository.

7 · Consequences

Positive

  • Eliminates accidental collisions with NodePorts and ephemeral connections.
  • Provides a memorable, human‑readable convention suitable for documentation and automation.
  • Enables Harmony to treat host‑network configuration as first‑class code.

Negative / Trade‑offs

  • Occupies part of the IANA “registered” band (must remain consistent across environments).
  • Requires operators to adapt legacy services away from lower ports (80, 443) for compliance with this policy.

8 · Future Work

  • Extend Harmony CLI to display currently allocated ports and detect conflicts.
  • Expose a compile‑time capability check ensuring clusters in a topology do not re‑use the same port twice.
  • Consider parallel UDP range reservation when we start exposing datagram services.

9 · References

Made with 🦀 by the NationTech Harmony team — ensuring your infrastructure behaves like code.