gitchegumi/homelab
gitchegumi/homelab
Watch
1
0
Fork
You've already forked homelab
 0
Code Issues 1 Pull requests Projects 1 Wiki Activity Actions

Design and establish the bare-metal cluster networking foundation #3

New issue
Closed
opened 2026-08-29 00:22:48 -05:00 by portegumi · 3 comments
portegumi commented 2026-08-29 00:22:48 -05:00
Collaborator
Copy link

Description

Select the cluster's bare-metal LoadBalancer approach and document how service addresses and DNS will integrate with the existing network. These decisions must precede stable application ingress and UDS work.

Scope

  • Evaluate and select a bare-metal LoadBalancer implementation.
  • Define an IP allocation strategy without assuming an unapproved range.
  • Document interaction with DHCP, static reservations, and existing network routing.
  • Plan internal and public DNS integration.
  • Identify the boundary between load balancing, ingress, and external routing without selecting unspecified implementations by assumption.

Acceptance criteria

  • The selected LoadBalancer approach and rationale are documented.
  • An approved service-IP allocation strategy is documented and avoids conflicts with existing infrastructure.
  • Internal and public DNS integration paths are documented.
  • A test LoadBalancer service is reachable from the intended network after implementation.
  • Unresolved ingress or public-routing decisions are explicitly recorded rather than implied.

Dependencies / blockers

Requires a healthy base RKE2 cluster. Exact IP ranges, DNS records, and ingress implementation remain intentionally unresolved until selected during this issue.

## Description Select the cluster's bare-metal `LoadBalancer` approach and document how service addresses and DNS will integrate with the existing network. These decisions must precede stable application ingress and UDS work. ## Scope - Evaluate and select a bare-metal `LoadBalancer` implementation. - Define an IP allocation strategy without assuming an unapproved range. - Document interaction with DHCP, static reservations, and existing network routing. - Plan internal and public DNS integration. - Identify the boundary between load balancing, ingress, and external routing without selecting unspecified implementations by assumption. ## Acceptance criteria - [x] The selected `LoadBalancer` approach and rationale are documented. - [x] An approved service-IP allocation strategy is documented and avoids conflicts with existing infrastructure. - [x] Internal and public DNS integration paths are documented. - [x] A test `LoadBalancer` service is reachable from the intended network after implementation. - [x] Unresolved ingress or public-routing decisions are explicitly recorded rather than implied. ## Dependencies / blockers Requires a healthy base RKE2 cluster. Exact IP ranges, DNS records, and ingress implementation remain intentionally unresolved until selected during this issue.
gitchegumi commented 2026-08-30 10:04:13 -05:00
Owner
Copy link

Decision: Use MetalLB for bare-metal LoadBalancer services

I will deploy MetalLB in Layer 2 mode as the cluster’s initial implementation for Kubernetes services of type LoadBalancer.

MetalLB was selected because the cluster currently has a single RKE2 control-plane node and the immediate requirement is to provide stable LAN addresses for application and ingress services. It offers straightforward address-pool management, works with the existing Layer 2 network without requiring BGP-capable routing, and leaves a clear upgrade path to BGP later if the network supports it.

This decision does not prevent future control-plane high availability. If the cluster is expanded to three RKE2 server nodes, kube-vip can be added specifically for the fixed RKE2 registration and Kubernetes API address while MetalLB continues handling application services. Migrating application services to kube-vip later would also remain possible, provided the controllers use separate address pools or load-balancer classes during the transition.

Next steps:

  • Inventory the DHCP range, static reservations, and existing fixed addresses.
  • Reserve a conflict-free LAN address pool for MetalLB.
  • Install a pinned stable MetalLB release.
  • Configure an IPAddressPool and L2Advertisement.
  • Validate LAN reachability and node failover with a test LoadBalancer service.
  • Document internal DNS integration and any public-routing decisions that remain unresolved.
## Decision: Use MetalLB for bare-metal `LoadBalancer` services I will deploy **MetalLB in Layer 2 mode** as the cluster’s initial implementation for Kubernetes services of type `LoadBalancer`. MetalLB was selected because the cluster currently has a single RKE2 control-plane node and the immediate requirement is to provide stable LAN addresses for application and ingress services. It offers straightforward address-pool management, works with the existing Layer 2 network without requiring BGP-capable routing, and leaves a clear upgrade path to BGP later if the network supports it. This decision does not prevent future control-plane high availability. If the cluster is expanded to three RKE2 server nodes, **kube-vip can be added specifically for the fixed RKE2 registration and Kubernetes API address while MetalLB continues handling application services**. Migrating application services to kube-vip later would also remain possible, provided the controllers use separate address pools or load-balancer classes during the transition. Next steps: - Inventory the DHCP range, static reservations, and existing fixed addresses. - Reserve a conflict-free LAN address pool for MetalLB. - Install a pinned stable MetalLB release. - Configure an `IPAddressPool` and `L2Advertisement`. - Validate LAN reachability and node failover with a test `LoadBalancer` service. - Document internal DNS integration and any public-routing decisions that remain unresolved.
gitchegumi commented 2026-08-30 13:18:15 -05:00
Owner
Copy link

Networking foundation implementation completed

MetalLB is installed as the cluster's bare-metal LoadBalancer implementation in Layer 2 mode using the pinned stable release selected for this deployment.

Address allocation

  • LAN subnet: [LAN_SUBNET]
  • Router-managed DHCP range: [DHCP_START]-[DHCP_END]
  • Reserved MetalLB service range: [METALLB_POOL_START]-[METALLB_POOL_END]
  • Previously conflicting leases/reservations were moved outside the service range.
  • The complete proposed service range was scanned before activation and contained no active hosts.
  • Exact values remain in the private infrastructure configuration rather than this issue.

Advertisement design

An IPAddressPool and explicit per-node L2Advertisement resources are configured. Each advertisement pairs [NODE_NAME] with its [WIRED_INTERFACE]. Wireless interfaces may remain enabled for host access but are excluded from MetalLB announcements. All cluster nodes remain eligible for wired Layer 2 failover.

Validation

A temporary nginx service of type LoadBalancer was deployed:

  • MetalLB allocated [TEST_VIP] from the configured pool.
  • The service was reachable from the intended LAN and returned the nginx welcome page.
  • Service events confirmed allocation by the configured pool and Layer 2 announcement by an eligible node.
  • externalTrafficPolicy: Cluster successfully routed traffic to the workload endpoint.
  • The temporary validation namespace was removed afterward.

DNS, ingress, and external-routing boundaries

  • MetalLB: allocates and advertises service VIPs on the LAN. It does not provide HTTP routing, public DNS, TLS termination, or Internet exposure.
  • UDS ingress: the UDS/Istio tenant and admin gateways will provide Kubernetes ingress and application-layer routing. Internal DNS records will point the selected internal hostnames to their assigned MetalLB VIPs.
  • Internal DNS: exact hostname and record values will be created when the UDS gateway VIPs are assigned. The record-management implementation remains a separate deployment concern.
  • Public DNS and routing: no public exposure, DNS, NAT, or firewall changes are approved or implied by this issue. If public access is approved later, authoritative DNS will target the external network endpoint and the edge router/firewall will forward only approved traffic to the UDS tenant gateway. The admin gateway remains internal unless a separate decision explicitly changes that posture.

The deliberately unresolved follow-on decisions are the public-exposure requirement, authoritative DNS/DDNS provider, final public hostnames, edge NAT/firewall policy, and certificate-management details. These are recorded for later work and are outside this networking-foundation issue.

## Networking foundation implementation completed MetalLB is installed as the cluster's bare-metal `LoadBalancer` implementation in Layer 2 mode using the pinned stable release selected for this deployment. ### Address allocation - LAN subnet: `[LAN_SUBNET]` - Router-managed DHCP range: `[DHCP_START]-[DHCP_END]` - Reserved MetalLB service range: `[METALLB_POOL_START]-[METALLB_POOL_END]` - Previously conflicting leases/reservations were moved outside the service range. - The complete proposed service range was scanned before activation and contained no active hosts. - Exact values remain in the private infrastructure configuration rather than this issue. ### Advertisement design An `IPAddressPool` and explicit per-node `L2Advertisement` resources are configured. Each advertisement pairs `[NODE_NAME]` with its `[WIRED_INTERFACE]`. Wireless interfaces may remain enabled for host access but are excluded from MetalLB announcements. All cluster nodes remain eligible for wired Layer 2 failover. ### Validation A temporary nginx service of type `LoadBalancer` was deployed: - MetalLB allocated `[TEST_VIP]` from the configured pool. - The service was reachable from the intended LAN and returned the nginx welcome page. - Service events confirmed allocation by the configured pool and Layer 2 announcement by an eligible node. - `externalTrafficPolicy: Cluster` successfully routed traffic to the workload endpoint. - The temporary validation namespace was removed afterward. ### DNS, ingress, and external-routing boundaries - **MetalLB:** allocates and advertises service VIPs on the LAN. It does not provide HTTP routing, public DNS, TLS termination, or Internet exposure. - **UDS ingress:** the UDS/Istio tenant and admin gateways will provide Kubernetes ingress and application-layer routing. Internal DNS records will point the selected internal hostnames to their assigned MetalLB VIPs. - **Internal DNS:** exact hostname and record values will be created when the UDS gateway VIPs are assigned. The record-management implementation remains a separate deployment concern. - **Public DNS and routing:** no public exposure, DNS, NAT, or firewall changes are approved or implied by this issue. If public access is approved later, authoritative DNS will target the external network endpoint and the edge router/firewall will forward only approved traffic to the UDS tenant gateway. The admin gateway remains internal unless a separate decision explicitly changes that posture. The deliberately unresolved follow-on decisions are the public-exposure requirement, authoritative DNS/DDNS provider, final public hostnames, edge NAT/firewall policy, and certificate-management details. These are recorded for later work and are outside this networking-foundation issue.
gitchegumi commented 2026-08-30 13:19:22 -05:00
Owner
Copy link

Closed as complete

Closed as complete
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
app-migration
Migration of existing applications into Kubernetes

  
ci-cd
Forgejo Actions, runners, GitOps, and delivery automation

  
cluster
RKE2 cluster bootstrap and node lifecycle

  
Discussion
Use this label when the issue is meant to be a discussion. These items will not be actioned on, but may lead to new issues with action items.

  
documentation
Architecture, inventory, conventions, and runbooks

  
gpu
NVIDIA enablement and GPU workload scheduling

  
networking
Cluster networking, load balancing, addressing, and DNS

  
security
Security controls and secret-handling safeguards

  
storage
TrueNAS, CSI, NFS, iSCSI, and local persistent storage

  
uds
Defense Unicorns UDS prerequisites and deployment

No labels
app-migration
ci-cd
cluster
Discussion
documentation
gpu
networking
security
storage
uds
Milestone
Clear milestone
No items
Projects
Clear projects
No items
No project
Homelab k8s Setup
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
gitchegumi/homelab#3
No description provided.