[feature]: Add hcloud-ccm installer for Talos × Hetzner LoadBalancer support

[devantler]

Context

Part of LoadBalancer support (#1714).

Implementation

1. Create pkg/svc/installer/loadbalancer/hcloudccm/ package
2. Implement hcloud-cloud-controller-manager installer
3. Configure API token injection (HCLOUD_TOKEN env var)
4. Add unit tests for installation logic
5. Add integration test: Talos × Hetzner + LoadBalancer service
6. Document prerequisites and authentication setup

Acceptance Criteria

• Talos × Hetzner clusters install hcloud-ccm when LoadBalancer=Default/Enabled
• LoadBalancer services receive Hetzner Load Balancer IPs
• HCLOUD_TOKEN authentication working correctly
• Unit tests cover installer logic
• Integration test validates cloud load balancer provisioning
• Documentation includes prerequisites, token setup, 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 is a well-structured feature request for implementing hcloud-cloud-controller-manager support in Talos × Hetzner clusters. The issue is part of the larger LoadBalancer support epic (#1714, now closed) and follows established KSail installer patterns.

📋 Issue Analysis

Type & Scope

• Type: Feature implementation (installer component)
• Parent Epic: [feature]: Add --load-balancer flag to ksail cluster init|create #1714 (LoadBalancer support) - Recently closed
• Distribution: Talos
• Provider: Hetzner
• Component: hcloud-cloud-controller-manager (CCM)
• Estimated Timeline: 2-3 weeks

Technical Context

This issue implements one of the four LoadBalancer installer packages identified in #1714:

1. ✅ pkg/svc/installer/cloud-provider-kind/ - Vanilla × Docker
2. 🔄 pkg/svc/installer/loadbalancer/hcloudccm/ - This issue (Talos × Hetzner)
3. ⏳ pkg/svc/installer/metallb/ - Talos × Docker
4. ⏳ K3s uses built-in ServiceLB (Klipper)

Prerequisites Already in Place

The codebase already has excellent reference implementations:

• ✅ Hetzner CSI installer (pkg/svc/installer/hetzner-csi/) - Shows HCLOUD_TOKEN pattern
• ✅ Cloud Provider KIND installer (pkg/svc/installer/cloudproviderkind/) - Shows LoadBalancer CCM pattern
• ✅ LoadBalancer enum - Already defined in pkg/apis/cluster/v1alpha1/enums.go
• ✅ Installer factory pattern - Established in pkg/cli/setup/components.go
• ✅ Hetzner provider - Supports Talos clusters on Hetzner Cloud

🔍 Implementation Guidance

Directory Structure

pkg/svc/installer/loadbalancer/hcloudccm/
├── doc.go              # Package documentation
├── installer.go        # Main installer implementation
└── installer_test.go   # Unit tests

Key Implementation Patterns

1. Secret Creation (Follow hetzner-csi pattern)

// Reference: pkg/svc/installer/hetzner-csi/installer.go:83-136
const hetznerTokenEnvVar = "HCLOUD_TOKEN"

func (h *HCloudCCMInstaller) createHCloudSecret(ctx context.Context) error {
    token := os.Getenv(hetznerTokenEnvVar)
    if token == "" {
        return ErrHetznerTokenNotSet
    }
    // Create secret in kube-system namespace
    // Secret name: "hcloud" (same as CSI)
    // Key: "token"
}

2. Helm Installation (Follow cloud-provider-kind pattern)

// Reference: pkg/svc/installer/cloudproviderkind/installer.go
const (
    hcloudCCMRepoName  = "hcloud"
    hcloudCCMRepoURL   = "(charts.hetzner.cloud/redacted)"
    hcloudCCMRelease   = "hcloud-cloud-controller-manager"
    hcloudCCMChartName = "hcloud/hcloud-cloud-controller-manager"
    hcloudCCMNamespace = "kube-system"
)

3. Installer Factory Registration

// In pkg/cli/setup/components.go
LoadBalancer: func(clusterCfg *v1alpha1.Cluster) (installer.Installer, error) {
    if clusterCfg.Spec.Cluster.Distribution == v1alpha1.DistributionTalos &&
       clusterCfg.Spec.Cluster.Provider == v1alpha1.ProviderHetzner {
        // Create hcloud-ccm installer
        helmClient, _, err := factories.HelmClientFactory(clusterCfg)
        if err != nil {
            return nil, err
        }
        return hcloudccminstaller.NewHCloudCCMInstaller(
            helmClient,
            clusterCfg.Spec.Cluster.Kubeconfig,
            clusterCfg.Spec.Cluster.Context,
            5*time.Minute,
        ), nil
    }
    return nil, nil // Other combinations handled elsewhere
},

✅ Testing Strategy

Unit Tests

// pkg/svc/installer/loadbalancer/hcloudccm/installer_test.go
func TestHCloudCCMInstaller_Install(t *testing.T)
func TestHCloudCCMInstaller_Install_MissingToken(t *testing.T)
func TestHCloudCCMInstaller_Uninstall(t *testing.T)

Integration Test

# Add to .github/workflows/ci.yaml system test matrix
- distribution: Talos
  provider: Hetzner
  args: "--load-balancer Enabled"
  description: "Test hcloud-ccm installation and LoadBalancer service provisioning"
  requires_secrets: true

Validation Steps:

1. Create Talos × Hetzner cluster with --load-balancer Default
2. Deploy test service with type: LoadBalancer
3. Verify Hetzner Load Balancer provisioned
4. Verify service receives external IP
5. Test connectivity to LoadBalancer IP

📚 Documentation Requirements

Files to Update

1. CLI Flags Documentation

   • Already covered in [feature]: Add --load-balancer flag to ksail cluster init|create #1714 documentation

2. Support Matrix (docs/src/content/docs/support-matrix.mdx)

   • Update LoadBalancer column for Talos × Hetzner

3. Prerequisites Guide (new section)

   • How to obtain HCLOUD_TOKEN
   • Required Hetzner API permissions
   • Cost implications of Hetzner Load Balancers

4. Troubleshooting (docs/src/content/docs/troubleshooting.md)

   • Common HCLOUD_TOKEN errors
   • Load Balancer provisioning delays
   • Hetzner API rate limits

🔗 Related Resources

Official Documentation

• hcloud-cloud-controller-manager GitHub
• [Hetzner Cloud Load Balancers]((docs.hetzner.com/redacted)
• [Kubernetes Cloud Provider Interface]((kubernetes.io/redacted)

Internal References

• Hetzner CSI installer: pkg/svc/installer/hetzner-csi/installer.go (shows HCLOUD_TOKEN pattern)
• Cloud Provider KIND: pkg/svc/installer/cloudproviderkind/installer.go (shows LoadBalancer CCM pattern)
• Installer interface: pkg/svc/installer/installer.go
• Component factory: pkg/cli/setup/components.go
• Post-CNI setup: pkg/cli/setup/post_cni.go (add LoadBalancer installation logic)

Similar Features

• [feature]: Add --load-balancer flag to ksail cluster init|create #1714 - Parent epic (LoadBalancer support)
• Pending: MetalLB installer for Talos × Docker
• Completed: Cloud Provider KIND for Vanilla × Docker

⚠️ Potential Gotchas

1. Secret Sharing with CSI

   • hcloud-ccm and hetzner-csi can share the same hcloud secret
   • Ensure both installers use consistent secret naming

2. Network Mode Compatibility

   • Hetzner Load Balancers work with both public and private networks
   • Talos may require additional network configuration

3. HCLOUD_TOKEN Scope

   • Token needs both read AND write permissions
   • Must have access to Load Balancer resources
   • Test with restricted token scopes

4. Cost Awareness

   • Each LoadBalancer service creates a billable Hetzner Load Balancer
   • Document cleanup recommendations
   • Consider adding cost warnings in documentation

5. CI/CD Secrets

   • Integration tests require HCLOUD_TOKEN GitHub secret
   • Cleanup action must delete orphaned Load Balancers
   • Reference: .github/actions/cleanup-hetzner/action.yaml

🚀 Implementation Checklist

Phase 1: Core Implementation (Week 1)

• Create pkg/svc/installer/loadbalancer/hcloudccm/ package
• Implement HCloudCCMInstaller struct with Install/Uninstall methods
• Add HCLOUD_TOKEN environment variable handling
• Create secret management (reuse CSI secret if exists)
• Implement Helm chart installation logic
• Add error types (ErrHetznerTokenNotSet, etc.)

Phase 2: Integration (Week 2)

• Add installer factory to pkg/cli/setup/components.go
• Wire up in pkg/cli/setup/post_cni.go LoadBalancer installation flow
• Add unit tests with mocked Helm client
• Test HCLOUD_TOKEN validation

Phase 3: Testing & Documentation (Week 3)

• Add integration test to CI matrix (Talos × Hetzner + LoadBalancer)
• Document HCLOUD_TOKEN setup in prerequisites
• Add troubleshooting guide for common errors
• Update support matrix documentation
• Verify LoadBalancer service provisioning end-to-end
• Test cost implications with multiple services

---

Label Recommendations: go (Go code implementation)

Priority Assessment: Medium - Part of completed epic #1714, extends existing Hetzner provider capabilities

AI generated by Agentic Triage