[feature]: Add Cloud Provider KIND installer for Vanilla × Docker LoadBalancer support

[devantler]

Context

Part of LoadBalancer support (#1714).

Implementation

1. Create pkg/svc/installer/loadbalancer/cloudproviderkind/ package
2. Implement Cloud Provider KIND installer
3. Add unit tests for installation logic
4. Add integration test: Vanilla cluster + LoadBalancer service
5. Document Cloud Provider KIND setup

Acceptance Criteria

• Vanilla × Docker clusters install Cloud Provider KIND when LoadBalancer=Enabled
• LoadBalancer services receive external IPs
• Unit tests cover installer logic
• Integration test validates end-to-end functionality
• Documentation includes setup and troubleshooting

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 issue implements Cloud Provider KIND installer as part of the broader LoadBalancer support initiative (#1714). It's a well-defined feature request for enabling LoadBalancer services on Vanilla × Docker clusters.

📋 Issue Summary

Type: Feature Implementation
Area: Cluster Provisioning / Component Installation
Distribution: Vanilla (Kind)
Provider: Docker
Component: Cloud Provider KIND
Parent Issue: #1714 (LoadBalancer support - now closed)
Related Issues: #2069 (MetalLB for Talos × Docker), #2070 (hcloud-ccm for Talos × Hetzner), #2074 (Documentation)

🎯 Implementation Breakdown

Required Changes

1. Create Installer Package (pkg/svc/installer/loadbalancer/cloudproviderkind/)

   • Follow existing installer patterns (reference: pkg/svc/installer/metricsserver/, pkg/svc/installer/cni/)
   • Implement installer interface
   • Handle Cloud Provider KIND deployment manifests

2. Integration Points

   • Wire into pkg/cli/setup/components.go installer factory
   • Add to ComponentRequirements in pkg/cli/setup/post_cni.go
   • Connect to LoadBalancer enum logic (already implemented in [feature]: Add --load-balancer flag to ksail cluster init|create #1714)

3. Testing Requirements

   • Unit tests for installer logic
   • Integration test: Create Vanilla cluster with LoadBalancer=Enabled
   • Deploy test service with type: LoadBalancer
   • Verify external IP assignment

4. Documentation

   • Setup guide in docs/
   • Troubleshooting section
   • CLI flag reference (auto-generated)

🔍 Key Technical Considerations

Cloud Provider KIND Architecture

• Purpose: Provides LoadBalancer support for Kind clusters via Docker port mapping
• Repository: https://github.com/kubernetes-sigs/cloud-provider-kind
• Installation Method: Apply Kubernetes manifests (likely via kubectl apply)
• Configuration: Minimal - typically works out-of-the-box with Kind

Integration Pattern

Look at existing installers for reference:

# Study these patterns
pkg/svc/installer/metricsserver/  # Similar post-CNI component
pkg/svc/installer/cni/             # Installation patterns
pkg/cli/setup/components.go        # Factory wiring

Timing Considerations

• Install After: CNI must be ready
• Install Before: Application workloads
• Dependency Check: Ensure cluster is Vanilla × Docker before installing

🧪 Testing Strategy

Unit Tests

// pkg/svc/installer/loadbalancer/cloudproviderkind/installer_test.go
func TestInstaller_Install(t *testing.T) {
    // Test successful installation
    // Test error handling
    // Test idempotency
}

Integration Test (add to CI)

# Should create a system test job in .github/workflows/ci.yaml
Distribution: Vanilla
Provider: Docker
Flags: --load-balancer Enabled
Test: Deploy service with type LoadBalancer, verify external IP

Manual Validation

# Create cluster with LoadBalancer support
ksail cluster init --distribution Vanilla --provider Docker --load-balancer Enabled
ksail cluster create

# Deploy test service
kubectl create deployment nginx --image=nginx
kubectl expose deployment nginx --type=LoadBalancer --port=80

# Verify external IP assigned
kubectl get svc nginx
# Should show EXTERNAL-IP with Docker host IP

📚 Resources & References

Upstream Documentation

• Cloud Provider KIND
• [Kind LoadBalancer Guide]((kind.sigs.k8s.../redacted)

Related KSail Code

• pkg/svc/installer/ - Installer interface and patterns
• pkg/apis/cluster/v1alpha1/enums.go - LoadBalancer enum (already exists)
• pkg/cli/setup/post_cni.go - Component installation orchestration

Similar Implementations in KSail

• Issue [feature]: Add MetalLB installer for Talos × Docker LoadBalancer support #2069: MetalLB installer (similar scope, different tech)
• Issue [feature]: Add hcloud-ccm installer for Talos × Hetzner LoadBalancer support #2070: hcloud-ccm installer (similar scope, cloud provider)

Learning Resources

• [Kubernetes LoadBalancer Service Type]((kubernetes.io/redacted)
• [Kind Architecture]((kind.sigs.k8s.../redacted)

✅ Definition of Done Checklist

Implementation:

• pkg/svc/installer/loadbalancer/cloudproviderkind/ package created
• Installer implements required interface
• Wired into component factory
• Wired into post-CNI setup flow

Testing:

• Unit tests for installer logic
• Unit tests achieve >80% coverage
• Integration test in CI (Vanilla + Docker + LoadBalancer)
• Manual validation completed

Documentation:

• Cloud Provider KIND setup guide written
• Troubleshooting section added
• CLI flags documentation generated
• Code comments explain non-obvious logic

Quality Gates:

• go build succeeds
• go test ./... passes
• Linters pass (golangci-lint)
• Integration test passes in CI
• No regressions in existing tests

🚀 Suggested Implementation Order

1. Research Phase (1-2 days)

   • Study Cloud Provider KIND manifests and configuration
   • Review existing KSail installer implementations
   • Identify installation requirements and dependencies

2. Core Implementation (3-5 days)

   • Create installer package structure
   • Implement Install() method
   • Wire into component factory
   • Wire into post-CNI setup

3. Testing (2-3 days)

   • Write unit tests
   • Add integration test to CI matrix
   • Manual end-to-end testing

4. Documentation (1-2 days)

   • Write setup guide
   • Add troubleshooting tips
   • Generate CLI flag docs

5. Review & Polish (1-2 days)

   • Code review feedback
   • Fix any issues
   • Final validation

⚠️ Potential Gotchas

1. Docker Network Considerations

   • Cloud Provider KIND relies on Docker's port mapping
   • May need special handling for rootless Docker setups
   • Test with different Docker configurations

2. Race Conditions

   • Must wait for CNI to be ready before installing
   • May need retry logic for manifest application
   • Handle cluster-not-ready scenarios gracefully

3. Version Compatibility

   • Ensure Cloud Provider KIND version matches Kind version
   • May need to pin specific versions
   • Document version compatibility matrix

4. Cleanup on Failure

   • Ensure partial installations are cleaned up
   • Don't leave cluster in inconsistent state
   • Provide clear error messages

5. Existing LoadBalancer Controllers

   • Detect if another LoadBalancer controller already exists
   • Prevent conflicts with user-installed controllers
   • Document limitations/caveats

---

Labels Applied: go (primary language), next (queued for implementation)

Priority Assessment: Medium - Part of LoadBalancer feature set; not blocking other work but valuable for Vanilla × Docker users

Estimated Effort: 2-3 weeks (as stated in issue timeline)

AI generated by Agentic Triage