Agentic Planner - February 4, 2026: Development Roadmap Update

[botantler[bot]]

Executive Summary

KSail continues strong development momentum with 8 open issues (all feature requests), stable infrastructure, and a clean codebase. The project is focused on completing high-value features that enhance user experience and production readiness.

Current State:

• ✅ Repository Health: Excellent (0 NPM vulnerabilities, clean Git history)
• 🚧 Active Development: LoadBalancer support, cluster lifecycle improvements
• ⚠️ Infrastructure: Minor workflow failures (documentation updates)
• 📋 Open Issues: 8 features planned, 0 bugs blocking development

Key Priority: Complete cluster lifecycle features (LoadBalancer, Update command) before expanding to new distributions (vCluster, Omni).

---

Current State Analysis

Recent Progress (Since Feb 1)

• ✅ Registry mirrors default enabled - docker.io and ghcr.io mirrors now on by default (reduces rate limits)
• ✅ Documentation updated - Copilot instructions reflect registry mirror changes (docs: Add registry mirrors default to Recent Changes #2059)
• ✅ Infrastructure stable - No critical CI/CD failures
• ⚠️ Documentation workflow - Minor failure in Update Docs workflow ([agentics] Update Docs failed #2061)

Open Issues Breakdown

Infrastructure/Automation (2 issues):

• [agentic-workflows] Failed runs #2060: Failed runs tracker (parent issue for workflow failures)
• [agentics] Update Docs failed #2061: Update Docs workflow failure (non-blocking)

Feature Development (6 issues):

1. [feature]: Add --load-balancer flag to ksail cluster init|create #1714: LoadBalancer support (--load-balancer flag) 🔴 High Priority
2. [feature]: add ksail cluster update for in-place updating a cluster #1734: Cluster update command (ksail cluster update) 🔴 High Priority
3. [feature]: Cluster backup and restore commands (Velero-inspired) #1836: Cluster backup/restore (Velero-inspired) 🟡 Medium Priority
4. CI Failure DoctorRecurring merge_group concurrency race causing false CI failures #1903: CI matrix aggregation issue (recurring infrastructure bug) 🟡 Medium Priority
5. [feature]: Add Omni provider for Talos #1970: Omni provider for Talos 🟢 Low Priority
6. [feature]: Implement vCluster as a distribution, and use vind for the docker provider #2017: vCluster distribution support 🟢 Low Priority

---

Priority Matrix

🔴 Critical (Complete February)

1. Complete LoadBalancer Implementation (#1714)

Current Status: Design complete, needs implementation
Scope:

• Add LoadBalancer enum (Default/Enabled/Disabled)
• Implement installers:
  • Cloud Provider KIND (Vanilla × Docker)
  • MetalLB (Talos × Docker)
  • hcloud-cloud-controller-manager (Talos × Hetzner)
• CLI integration (--load-balancer flag for init/create)
• Documentation and tests

Why Critical:

• Essential for dev/prod parity
• Enables testing of LoadBalancer services locally
• Competitive differentiator vs Minikube/Kind alone
• Required for production-ready Talos clusters on Hetzner

Timeline: 3-4 weeks
Dependencies: None (ready to start)

2. Implement Cluster Update Command (#1734)

Current Status: Not started
Scope:

• Add ksail cluster update command
• Detect config differences (current vs desired)
• In-place updates when supported by provider/distribution
• Recreate flow with confirmation prompt for unsupported changes
• --force flag to skip confirmation
• Node scaling support

Why Critical:

• Eliminates delete/recreate cycle for config changes
• Preserves cluster state and workloads
• Improves user experience significantly
• Natural next step after cluster creation

Timeline: 2-3 weeks
Dependencies: None

---

🟡 High Priority (Complete Q1 2026)

3. Resolve CI Matrix Aggregation Issue (#1903)

Current Status: Recurring pattern (3+ occurrences)
Root Cause: GitHub Actions concurrency control race condition
Recommended Fix:

• Update concurrency group to be workflow-specific:

  concurrency:
    group: "ci-ksail-${{ github.workflow }}-${{ github.ref }}"
    cancel-in-progress: true

Why Important:

• Prevents false CI failures
• Reduces manual merge queue intervention
• Improves developer velocity

Timeline: 1 week (simple config change + monitoring)
Next Steps:

1. Implement workflow-specific concurrency groups
2. Monitor 5-10 merge queue runs
3. Close issue if pattern stops

4. Cluster Backup/Restore Commands (#1836)

Current Status: Design phase
Scope: Velero-inspired backup/restore for Kubernetes resources and PVs
Complexity: High (resource ordering, volume snapshots, secret handling)

Why Important:

• Disaster recovery capability
• Cluster migration support
• Production readiness signal

Timeline: 6-8 weeks
Dependencies: None (can start after Update command)

---

🟢 Medium Priority (Q2 2026)

5. vCluster Distribution Support (#2017)

Current Status: Research/planning
Scope: Add vCluster as a distribution option using vind for Docker provider
Strategic Value:

• Unique differentiator
• Multi-tenancy support
• Lightweight virtual clusters

Timeline: 4-6 weeks
Dependencies: Complete high-priority cluster lifecycle features first

6. Omni Provider for Talos (#1970)

Current Status: Research phase
Scope: Provision Talos clusters in Sidero Omni using Omni client SDK
Requirements: Omni account, API credentials

Timeline: 6-8 weeks
Dependencies: None (independent feature)

---

ℹ️ Infrastructure Maintenance

7. Update Docs Workflow Failure (#2061)

Status: Minor issue, non-blocking
Impact: Documentation automation temporarily broken
Action: Debug with agentic-workflows agent or manual investigation

8. Failed Runs Tracker (#2060)

Status: Parent issue for tracking all workflow failures
Purpose: Centralized tracking and filtering of agentic workflow issues
Action: Monitor but no immediate action needed

---

Dependencies & Sequencing

graph TD
    A[LoadBalancer #1714] --> B[Cluster Update #1734]
    B --> C[Backup/Restore #1836]
    B --> D[vCluster #2017]
    E[CI Matrix `Fix #1903`] -.->|Improves stability| A
    
    style A fill:#ff6b6b
    style B fill:#ff6b6b
    style C fill:#ffd93d
    style D fill:#6bcf7f
    style E fill:#ffd93d

Loading

Recommended Sequence:

1. Fix CI matrix aggregation (CI Failure DoctorRecurring merge_group concurrency race causing false CI failures #1903) — Improves developer velocity
2. Complete LoadBalancer support ([feature]: Add --load-balancer flag to ksail cluster init|create #1714) — Essential infrastructure
3. Implement Cluster Update ([feature]: add ksail cluster update for in-place updating a cluster #1734) — High-value UX improvement
4. Start Backup/Restore ([feature]: Cluster backup and restore commands (Velero-inspired) #1836) or vCluster ([feature]: Implement vCluster as a distribution, and use vind for the docker provider #2017) in parallel

---

Timeline Recommendation

Week 1-2 (Feb 4-17)

• Implement workflow-specific concurrency fix (CI Failure DoctorRecurring merge_group concurrency race causing false CI failures #1903)
• Start LoadBalancer enum and CLI integration ([feature]: Add --load-balancer flag to ksail cluster init|create #1714)
• Create LoadBalancer installer packages (MetalLB, hcloud-ccm, Cloud Provider KIND)

Week 3-4 (Feb 18 - Mar 3)

• Complete LoadBalancer implementation ([feature]: Add --load-balancer flag to ksail cluster init|create #1714)
• Write LoadBalancer integration tests
• Document LoadBalancer support matrix
• Start Cluster Update command design ([feature]: add ksail cluster update for in-place updating a cluster #1734)

Month 2 (March 2026)

• Complete Cluster Update command ([feature]: add ksail cluster update for in-place updating a cluster #1734)
• Start Backup/Restore design ([feature]: Cluster backup and restore commands (Velero-inspired) #1836)
• Release v5.x.x with LoadBalancer + Update features

Month 3 (April 2026)

• Complete Backup/Restore implementation ([feature]: Cluster backup and restore commands (Velero-inspired) #1836)
• Start vCluster support ([feature]: Implement vCluster as a distribution, and use vind for the docker provider #2017)
• Evaluate Omni provider priority ([feature]: Add Omni provider for Talos #1970)

---

Risk Assessment

Risk	Likelihood	Impact	Mitigation
LoadBalancer scope creep	Medium	Medium	Clear MVP definition, defer cloud provider snapshots to v2
CI matrix issue recurrence	Medium	Low	Implement workflow-specific concurrency groups
Backup/restore data loss	Low	High	Extensive testing, clear documentation of limitations
vCluster integration complexity	High	Medium	Research phase first, POC before full implementation
Documentation workflow failures	Low	Low	Manual docs updates acceptable, fix when convenient

---

Success Metrics

Completion Metrics (February)

• CI concurrency fix deployed (CI Failure DoctorRecurring merge_group concurrency race causing false CI failures #1903)
• LoadBalancer CLI flags integrated ([feature]: Add --load-balancer flag to ksail cluster init|create #1714)
• At least 1 LoadBalancer installer complete (MetalLB or Cloud Provider KIND)

Quality Metrics (Ongoing)

• Test coverage: Maintain >70%
• Build time: Keep <5 minutes
• Documentation: Update for each feature
• CI success rate: Target >95%

Adoption Metrics (Q1 Target)

• GitHub stars: Track growth from current baseline
• VSCode extension downloads: Monitor trends
• Community engagement: Issues, discussions, PRs from external contributors

---

Suggested New Issues

Based on the current roadmap, the following issues would help track implementation:

# LoadBalancer: MetalLB installer
gh issue create \
  --repo devantler-tech/ksail \
  --title "Add MetalLB installer for Talos × Docker LoadBalancer support" \
  --label "enhancement,loadbalancer" \
  --body "## Context
Part of LoadBalancer support (#1714).

## Implementation
1. Create MetalLB installer in \`pkg/svc/installer/loadbalancer/metallb/\`
2. Add LoadBalancer configuration for Talos provisioner
3. Configure L2 mode by default
4. Update LoadBalancer enum to trigger MetalLB installation
5. Add unit tests for MetalLB installer
6. Add integration tests (Talos cluster + LoadBalancer service)
7. Document MetalLB configuration options

## Acceptance Criteria
- [ ] Talos × Docker clusters with LoadBalancer support install MetalLB
- [ ] LoadBalancer services receive external IPs
- [ ] Unit tests cover MetalLB installation logic
- [ ] Integration tests verify end-to-end functionality
- [ ] Documentation updated with Talos × MetalLB support

## Timeline
2-3 weeks (part of #1714)"

# LoadBalancer: hcloud-ccm installer
gh issue create \
  --repo devantler-tech/ksail \
  --title "Add hcloud-ccm installer for Talos × Hetzner LoadBalancer support" \
  --label "enhancement,loadbalancer,hetzner" \
  --body "## Context
Part of LoadBalancer support (#1714).

## Implementation
1. Create hcloud-ccm installer in \`pkg/svc/installer/loadbalancer/hcloudccm/\`
2. Add LoadBalancer configuration for Talos provisioner on Hetzner
3. Configure API token injection from environment (HCLOUD_TOKEN)
4. Update LoadBalancer enum to trigger hcloud-ccm installation
5. Add unit tests for hcloud-ccm installer
6. Add integration tests (Talos × Hetzner cluster + LoadBalancer service)
7. Document hcloud-ccm configuration and prerequisites

## Acceptance Criteria
- [ ] Talos × Hetzner clusters with LoadBalancer support install hcloud-ccm
- [ ] LoadBalancer services receive Hetzner Load Balancer IPs
- [ ] HCLOUD_TOKEN authentication working
- [ ] Unit tests cover hcloud-ccm installation logic
- [ ] Integration tests verify cloud load balancer provisioning
- [ ] Documentation includes prerequisites and setup

## Timeline
2-3 weeks (part of #1714)"

# LoadBalancer: Cloud Provider KIND installer
gh issue create \
  --repo devantler-tech/ksail \
  --title "Add Cloud Provider KIND installer for Vanilla × Docker LoadBalancer support" \
  --label "enhancement,loadbalancer" \
  --body "## Context
Part of LoadBalancer support (#1714).

## Implementation
1. Create Cloud Provider KIND installer in \`pkg/svc/installer/loadbalancer/cloudproviderkind/\`
2. Add LoadBalancer configuration for Kind provisioner
3. Update LoadBalancer enum to trigger Cloud Provider KIND installation
4. Add unit tests for Cloud Provider KIND installer
5. Add integration tests (Vanilla cluster + LoadBalancer service)
6. Document Cloud Provider KIND setup

## Acceptance Criteria
- [ ] Vanilla × Docker clusters with LoadBalancer support install Cloud Provider KIND
- [ ] LoadBalancer services receive external IPs
- [ ] Unit tests cover installation logic
- [ ] Integration tests verify end-to-end functionality
- [ ] Documentation updated

## Timeline
2-3 weeks (part of #1714)"

# Cluster Update: Core implementation
gh issue create \
  --repo devantler-tech/ksail \
  --title "Implement \`ksail cluster update\` core command and config diff detection" \
  --label "enhancement,cluster-lifecycle" \
  --body "## User Story
As a KSail user, I want to update my cluster configuration without destroying it, so I can add/remove components while preserving workloads.

## Current Behavior
Users must \`ksail cluster delete && ksail cluster create\` to change configuration.

## Proposed Behavior
\`ksail cluster update\` detects configuration changes and applies them in-place when supported.

## Implementation Plan
1. Add \`ksail cluster update\` command to CLI
2. Implement config diff detection (compare running cluster vs ksail.yaml)
3. Create component addition/removal orchestration
4. Add \`--dry-run\` flag to preview changes
5. Add confirmation prompt (reuse deletion confirmation pattern)
6. Handle immutable fields with clear error messages
7. Add rollback on failure
8. Unit tests for diff detection and orchestration
9. Integration tests for component updates
10. Documentation with examples

## Acceptance Criteria
- [ ] \`ksail cluster update\` applies configuration changes in-place
- [ ] \`--dry-run\` shows planned changes without applying
- [ ] Confirmation prompt prevents accidental updates
- [ ] Immutable fields (distribution, provider) rejected with clear errors
- [ ] Workloads and data preserved during updates
- [ ] Rollback on partial failure
- [ ] Comprehensive tests and documentation

## Out of Scope (Future)
- Kubernetes version upgrades
- Node OS updates
- Network reconfiguration

## Timeline
2-3 weeks

## Related
#1734 (parent issue)"

# CI Matrix: Workflow-specific concurrency fix
gh issue create \
  --repo devantler-tech/ksail \
  --title "Implement workflow-specific concurrency groups to fix matrix aggregation" \
  --label "infrastructure,ci" \
  --body "## Context
Issue #1903 shows recurring CI matrix aggregation failures caused by concurrency control race conditions.

## Root Cause
Multiple workflows (CI-KSail, CI-Go, etc.) sharing the same concurrency group cancel each other's jobs.

## Solution
Update concurrency group to be workflow-specific:

\`\`\`yaml
concurrency:
  group: \"ci-ksail-\${{ github.workflow }}-\${{ github.ref }}\"
  cancel-in-progress: true
\`\`\`

## Implementation
1. Update \`.github/workflows/ci.yaml\` concurrency config
2. Update all other workflows with similar pattern
3. Monitor next 5-10 merge queue runs
4. Document pattern in workflow best practices

## Acceptance Criteria
- [ ] Concurrency groups include workflow name
- [ ] No cross-workflow cancellations
- [ ] Matrix aggregation false failures eliminated
- [ ] Pattern documented for future workflows

## Timeline
1 week (simple config change + monitoring)

## Related
#1903 (parent issue with investigation)"

# Documentation: LoadBalancer support matrix
gh issue create \
  --repo devantler-tech/ksail \
  --title "Document LoadBalancer support matrix and configuration examples" \
  --label "documentation,loadbalancer" \
  --body "## Context
After LoadBalancer support (#1714) is complete, comprehensive documentation is needed.

## Documentation Needs

### 1. Support Matrix Table
Create table showing LoadBalancer support per distribution × provider

### 2. Configuration Examples
- Default LoadBalancer (per distribution)
- Explicit LoadBalancer selection
- LoadBalancer=Disabled for all distributions
- Service manifests with LoadBalancer type

### 3. Troubleshooting Guide
- LoadBalancer service stuck in Pending
- IP address not assigned
- Cloud provider logs
- Common misconfigurations

### 4. CLI Flags Reference
Auto-generated docs in \`docs/src/content/docs/cli-flags/\`

## Acceptance Criteria
- [ ] Support matrix table in main documentation
- [ ] Configuration examples for each combination
- [ ] Troubleshooting section
- [ ] CLI flags reference updated
- [ ] README.md mentions LoadBalancer support

## Dependencies
Requires #1714 complete

## Timeline
1 week after LoadBalancer feature complete"

---

Alignment with Previous Plan (Feb 1)

This plan builds on Discussion #2039 with these updates:

What Changed:

1. Removed GOPROXY/PR tracking - Those PRs have been merged/closed
2. Removed Homebrew Cask tracking - Not mentioned in current open issues
3. Elevated CI matrix fix - Still open (CI Failure DoctorRecurring merge_group concurrency race causing false CI failures #1903) and needs attention
4. Maintained feature priorities - LoadBalancer and Update command remain top priorities
5. Added infrastructure context - Documentation workflow failures noted

What Stayed the Same:

• LoadBalancer support as critical priority
• Cluster Update command as high priority
• vCluster and Omni as lower priority
• Focus on completion before expansion

---

Notes

Assumptions

• LoadBalancer implementation ([feature]: Add --load-balancer flag to ksail cluster init|create #1714) is ready to start
• Cluster Update ([feature]: add ksail cluster update for in-place updating a cluster #1734) can begin after LoadBalancer or in parallel
• CI matrix issue (CI Failure DoctorRecurring merge_group concurrency race causing false CI failures #1903) will be resolved with workflow-specific concurrency groups
• Documentation workflow failures ([agentics] Update Docs failed #2061) are non-blocking

Next Steps for Maintainers

1. Review LoadBalancer issue ([feature]: Add --load-balancer flag to ksail cluster init|create #1714) and confirm scope
2. Prioritize between LoadBalancer installers (which to implement first)
3. Validate CI concurrency fix approach (CI Failure DoctorRecurring merge_group concurrency race causing false CI failures #1903)
4. Provide feedback on timeline and priorities via comments

---

How to Respond to This Plan

Add comments to this discussion with:

• Priority adjustments
• Timeline concerns
• Resource constraints
• Implementation questions
• Additional context

The next Agentic Planner run will incorporate your feedback.

---

Generated by: Agentic Planner
Date: February 4, 2026
Repository: devantler-tech/ksail
Previous Plan: Discussion #2039 (Feb 1, 2026)

AI generated by Agentic Planner

• expires on Feb 11, 2026, 10:18 AM UTC