[feature]: Add MetalLB installer for Talos × Docker LoadBalancer support

[devantler]

Context

Part of LoadBalancer support (#1714).

Implementation

1. Create pkg/svc/installer/loadbalancer/metallb/ package
2. Implement MetalLB installer following existing installer patterns
3. Configure L2 mode by default for Talos × Docker
4. Add unit tests for installation logic
5. Add integration test: Talos cluster + LoadBalancer service
6. Document MetalLB configuration options

Acceptance Criteria

• Talos × Docker clusters install MetalLB when LoadBalancer=Enabled
• LoadBalancer services receive external IPs
• Unit tests cover installer logic
• Integration test validates end-to-end functionality
• Documentation includes MetalLB setup guide

Timeline

2-3 weeks (part of #1714)

[github-actions]

🎉 Yo ho ho! Agentic Triage found the treasure and completed successfully! ⚓💰

[botantler]

🎯 Agentic Issue Triage

This is a well-defined feature request for implementing MetalLB LoadBalancer support for Talos clusters running on Docker. Part of the broader LoadBalancer infrastructure (#1714, now closed), this issue represents one of three LoadBalancer installer implementations.

📋 Summary

Type: Feature Request
Component: LoadBalancer Installer (MetalLB)
Distribution: Talos
Provider: Docker
Parent: #1714 (LoadBalancer flag feature - completed)
Siblings: #2071 (Cloud Provider KIND), #2070 (hcloud-ccm)

🏗️ Implementation Guidance

Package Structure

Create pkg/svc/installer/loadbalancer/metallb/ following the existing installer pattern:

pkg/svc/installer/loadbalancer/metallb/
├── installer.go          # Main installer implementation
├── installer_test.go     # Unit tests
├── config.go            # MetalLB configuration generation
└── manifests/           # Embedded YAML manifests (if needed)

Reference Implementations

Study these existing installers for patterns:

1. pkg/svc/installer/metrics-server/ - Simple installer pattern
2. pkg/svc/installer/cert-manager/ - Complex installer with CRDs
3. pkg/svc/installer/cloudproviderkind/ - Sibling LoadBalancer installer

Key Implementation Steps

1. Installer Interface (pkg/svc/installer/installer.go):

   • Implement Install(ctx context.Context) error
   • Implement Uninstall(ctx context.Context) error (if needed)
   • Follow the helpers.go patterns for manifest application

2. MetalLB Configuration:

   • Install MetalLB operator/controller via Helm or manifests
   • Configure L2Advertisement mode by default
   • Set up IPAddressPool with Docker bridge network range
   • Example IP range: 172.18.255.200-172.18.255.250 (adjust based on Kind/Docker network)

3. Wire into Factory (pkg/cli/setup/components.go):

   • Add to DefaultInstallerFactories() map
   • Key should match distribution × provider combination check

4. Integration Point (pkg/cli/setup/post_cni.go):

   • Called via InstallLoadBalancerSilent() when LoadBalancer=Enabled for Talos × Docker
   • Runs after CNI installation (MetalLB needs working network)

🔍 MetalLB Technical Details

Why MetalLB for Talos × Docker?

• L2 Mode: Works in local Docker environments without BGP
• Industry Standard: Most common LoadBalancer for non-cloud Kubernetes
• Talos Compatible: Minimal host dependencies, works with immutable OS

Configuration Example

apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: docker-pool
  namespace: metallb-system
spec:
  addresses:
  - 172.18.255.200-172.18.255.250  # Adjust based on Docker network
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: docker-l2
  namespace: metallb-system
spec:
  ipAddressPools:
  - docker-pool

Installation Options

Option A: Helm Chart (Recommended)

// Use embedded Helm client
helm.Install("metallb", "metallb", &helm.InstallOptions{
    Namespace: "metallb-system",
    Chart: "(metallb.github.io/redacted),
    Values: map[string]interface{}{...},
})

Option B: Manifests

• Embed YAML manifests in manifests/ directory
• Use helpers.ApplyManifests() pattern

✅ Testing Strategy

Unit Tests (installer_test.go)

• Mock Kubernetes client interactions
• Test configuration generation with different IP ranges
• Test error handling (namespace creation failures, manifest apply errors)
• Follow patterns from pkg/svc/installer/metrics-server/installer_test.go

Integration Test

Create system test scenario:

# Test: Talos × Docker + LoadBalancer service
ksail cluster init --distribution Talos --provider Docker --load-balancer Enabled
ksail cluster create

# Deploy test service
kubectl apply -f - <(EOF
apiVersion: v1
kind: Service
metadata:
  name: test-lb
spec:
  type: LoadBalancer
  selector:
    app: test
  ports:
  - port: 80
EOF

# Verify external IP assigned
kubectl get svc test-lb -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
# Should return IP from MetalLB pool (e.g., 172.18.255.200)

CI Integration

• Add to system test matrix in .github/workflows/ (if not already present)
• Test variation: System Test (Talos, Docker, LoadBalancer=Enabled)

</details)

📚 Documentation Requirements

Files to Update

1. CLI Flags Reference (docs/src/content/docs/cli-flags/cluster/)

   • Auto-generated from code
   • Ensure --load-balancer flag documented

2. LoadBalancer Configuration Guide (new)

   • Create docs/src/content/docs/guides/loadbalancer.mdx
   • Include MetalLB setup, IP range configuration, troubleshooting

3. Distribution × Provider Matrix

   • Update support matrix table (likely in main README or docs)
   • Confirm Talos × Docker shows "MetalLB (L2)" when enabled

Troubleshooting Guide

Common issues to document:

• IP pool exhaustion: How to expand IP range
• ARP conflicts: L2 mode limitations in certain Docker network modes
• No external IP assigned: Check MetalLB logs, verify IPAddressPool config
• Talos firewall: Ensure L2 traffic permitted (usually OK by default)

🎯 Acceptance Checklist Breakdown

Phase 1: Core Implementation (Week 1)

• Create package structure pkg/svc/installer/loadbalancer/metallb/
• Implement Install() method with MetalLB deployment
• Implement L2 IPAddressPool configuration
• Wire into installer factory (pkg/cli/setup/components.go)
• Wire into post-CNI setup (pkg/cli/setup/post_cni.go)

Phase 2: Testing (Week 2)

• Write unit tests for installer logic
• Create integration test scenario (Talos + LoadBalancer service)
• Test IP assignment end-to-end
• Verify behavior with LoadBalancer=Disabled (no MetalLB installed)

Phase 3: Documentation (Week 3)

• Document MetalLB configuration options
• Add troubleshooting guide
• Update distribution × provider matrix
• Create usage examples in guides

🔗 Related Resources

External Documentation

• [MetalLB Official Docs]((metallb.universe.tf/redacted)
• [MetalLB L2 Mode Tutorial]((metallb.universe.tf/redacted)
• [MetalLB Installation Guide]((metallb.universe.tf/redacted)
• [Talos + MetalLB Integration]((www.talos.dev/redacted)

KSail Codebase References

• Existing Installers: pkg/svc/installer/metrics-server/, pkg/svc/installer/cert-manager/
• Installer Interface: pkg/svc/installer/installer.go
• Installer Helpers: pkg/svc/installer/helpers.go
• Parent Issue: [feature]: Add --load-balancer flag to ksail cluster init|create #1714 (LoadBalancer flag implementation - reference for context)
• Sibling Issues: [feature]: Add Cloud Provider KIND installer for Vanilla × Docker LoadBalancer support #2071 (Cloud Provider KIND), [feature]: Add hcloud-ccm installer for Talos × Hetzner LoadBalancer support #2070 (hcloud-ccm)

Similar Implementations in Wild

• kind-metallb - Example for Docker-based clusters
• Talos MetalLB Example

💡 Tips & Gotchas

Docker Network IP Range Discovery

MetalLB needs IP addresses outside the cluster but within Docker bridge network:

// Pseudo-code: Discover Docker bridge network CIDR
docker network inspect kind | grep Subnet
// Example: 172.18.0.0/16
// Allocate pool: 172.18.255.200-172.18.255.250

Consider making IP range configurable via ksail.yaml in future iterations.

Installation Order

Critical ordering:

1. CNI must be ready before MetalLB (pods need networking)
2. MetalLB controller before IPAddressPool CRDs
3. IPAddressPool before L2Advertisement

Use helpers.WaitForReadiness() pattern between stages.

Talos Specifics

• Talos is immutable, so MetalLB runs entirely in-cluster (no host dependencies)
• Ensure MetalLB speaker DaemonSet tolerates control-plane taints if running single-node
• Verify Talos default CNI (usually Flannel) compatible with L2 mode

🚀 Suggested Next Steps

1. Start with Exploration:

   • Run a manual MetalLB installation on a Talos × Docker cluster
   • Document the exact steps and configurations that work
   • Test LoadBalancer service assignment manually

2. Study Sibling Implementations:

   • Review [feature]: Add Cloud Provider KIND installer for Vanilla × Docker LoadBalancer support #2071 (Cloud Provider KIND) implementation when available
   • Ensure consistent patterns across all three LoadBalancer installers

3. Begin Coding:

   • Create package skeleton
   • Implement basic installation (Helm or manifests)
   • Add unit tests incrementally
   • Wire into factory/setup only when core works

4. Integration Testing:

   • Create test cluster with ksail cluster init --distribution Talos --load-balancer Enabled
   • Deploy test LoadBalancer service
   • Verify IP assignment
   • Document any issues encountered

5. Documentation:

   • Write docs alongside code (easier to remember details)
   • Include real-world examples from integration testing
   • Add troubleshooting for any issues you encountered

---

Labels Applied: go, next
Estimated Effort: 2-3 weeks (as stated in issue)
Priority: Medium (part of completed parent #1714, but enables critical Talos × Docker LoadBalancer functionality)

AI generated by Agentic Triage