125 lines
5.7 KiB
Markdown
125 lines
5.7 KiB
Markdown
# 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:
|
||
|
||
```rust
|
||
let orchestrator_ports = harmony::network::PortAllocator::new(25_000, 25_999);
|
||
let rados_gateway_port = orchestrator_ports.allocate("ceph-rgw")?;
|
||
```
|
||
|
||
In TOML configuration:
|
||
|
||
```toml
|
||
[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
|
||
- [IANA Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml)
|
||
- [Kubernetes NodePort default range documentation](https://kubernetes.io/docs/concepts/services-networking/service/)
|
||
- Harmony ADR‑001 · Why Rust
|
||
- Harmony ADR‑003 · Infrastructure Abstractions
|
||
|
||
---
|
||
|
||
*Made with 🦀 by the NationTech Harmony team — ensuring your infrastructure behaves like code.*
|