homelab/.kiro/specs/fastpass-dns-loadbalancer-fix/requirements.md

Requirements Document

Introduction

The FastPass Kubernetes cluster deployment currently has critical DNS and load balancing configuration issues that prevent proper high availability setup. While the cluster endpoint fastpass.local.mk-labs.cloud is defined in the group variables, the cluster_vip variable required by the DNS manager role is missing, and the Traefik load balancer configuration is commented out. This means the cluster endpoint cannot resolve properly and there's no load balancing for the control plane API. This feature will fix these configuration gaps to enable true HA functionality.

Requirements

Requirement 1: DNS CNAME Record for Load Balancer

User Story: As a DevOps engineer, I want the DNS manager to create a CNAME record for the cluster endpoint pointing to the load balancer, so that the cluster endpoint resolves through the load balancer rather than directly to node IPs.

Acceptance Criteria

1. WHEN the dns-manager role is called for a load-balanced cluster THEN the system SHALL create a CNAME record instead of an A record
2. WHEN the CNAME record is created THEN the system SHALL point fastpass.local.mk-labs.cloud to the traefik_server (lightning_lane.local.mk-labs.cloud)
3. WHEN the DNS record type is determined THEN the system SHALL use CNAME for load-balanced endpoints and A records for direct node access
4. WHEN DNS propagation occurs THEN the system SHALL verify that the CNAME resolution works correctly

Requirement 2: Complete Traefik Integration

User Story: As a DevOps engineer, I want the Traefik load balancer to be fully integrated with the FastPass deployment, so that the cluster VIP is properly load balanced across all control plane nodes.

Acceptance Criteria

1. WHEN the traefik-manager role is called THEN the system SHALL use the traefik_server variable (lightning_lane) as the target host
2. WHEN Traefik configuration is generated THEN the system SHALL create proper TCP routing for the cluster endpoint to all control plane nodes
3. WHEN the cluster VIP is accessed THEN the system SHALL distribute requests across space-mountain, big-thunder-mountain, and splash-mountain
4. WHEN Traefik configuration is applied THEN the system SHALL reload the Traefik service to activate the new configuration

Requirement 3: High Availability Validation

User Story: As a DevOps engineer, I want to validate that the HA setup is working correctly, so that I can be confident the cluster will survive node failures.

Acceptance Criteria

1. WHEN the deployment completes THEN the system SHALL test connectivity to the cluster endpoint
2. WHEN connectivity tests run THEN the system SHALL verify that the endpoint resolves through the CNAME to the load balancer
3. WHEN load balancer tests run THEN the system SHALL verify that requests are being distributed across control plane nodes
4. WHEN a control plane node is stopped THEN the system SHALL continue to serve API requests through the remaining nodes

Requirement 4: Backward Compatibility

User Story: As a DevOps engineer, I want the DNS fixes to be backward compatible with existing deployments, so that current clusters continue to function during the transition.

Acceptance Criteria

1. WHEN existing clusters are updated THEN the system SHALL not break existing DNS configurations
2. WHEN new variables are introduced THEN the system SHALL provide sensible defaults for existing deployments
3. WHEN the update is applied THEN the system SHALL preserve existing kubeconfig files and cluster access
4. IF migration issues occur THEN the system SHALL provide rollback procedures and documentation