feat(runtime): add kubectl provider

[CalvinAllen]

Add kubectl runtime provider to dtvem for managing Kubernetes CLI versions.

Overview

Implement a kubectl provider that allows users to install, manage, and switch between kubectl versions using dtvem. DevOps teams managing multiple Kubernetes clusters need to match kubectl client versions to server versions.

Why kubectl Needs Version Management

• Version Skew Policy: kubectl must be within ±1 minor version of Kubernetes server
  • Cluster on 1.27 → kubectl can be 1.26, 1.27, or 1.28
  • Using wrong version causes compatibility issues
• Multiple Clusters: DevOps teams manage dev (1.26), staging (1.27), prod (1.28)
• CI/CD Pipelines: Must pin kubectl version for reproducibility
• Client Features: New kubectl features only work with matching server versions
• Breaking Changes: API changes between Kubernetes versions affect kubectl

Implementation Checklist

• Create src/runtimes/kubectl/provider.go
• Implement all 19 Provider interface methods
• Add init() function for auto-registration: runtime.Register(NewProvider())
• Import in src/main.go: _ "github.com/CodingWithCalvin/dtvem/src/runtimes/kubectl"
• Update schemas/runtimes.schema.json to add "kubectl" to runtime enum
• Implement Shims() method to return: ["kubectl"]
• Implement ShouldReshimAfter() (returns false - no plugin install system that needs reshim)
• Add detection logic for existing kubectl installations (system, Docker Desktop, cloud CLIs)
• Implement download/installation logic from official sources
• Ensure cross-platform support (Windows, macOS, Linux)
• Add tests using provider contract harness (internal/runtime/provider_test_harness.go)
• Update documentation with kubectl examples

Version Sources

• Official Releases: https://dl.k8s.io/release/
• Stable Version: https://dl.k8s.io/release/stable.txt
• Version List: https://dl.k8s.io/release/stable-1.{minor}.txt for each minor version
• GitHub Releases: https://github.com/kubernetes/kubernetes/releases

Download Sources by Platform

• All Platforms: Kubernetes provides prebuilt binaries
  • Format: https://dl.k8s.io/release/v{version}/bin/{os}/{arch}/kubectl
  • Examples:
    • https://dl.k8s.io/release/v1.28.4/bin/windows/amd64/kubectl.exe
    • https://dl.k8s.io/release/v1.28.4/bin/darwin/arm64/kubectl
    • https://dl.k8s.io/release/v1.28.4/bin/linux/amd64/kubectl
• Checksums: SHA256 checksums available at same URL with .sha256 suffix

Migration Sources

Detect and migrate from:

• System installations:
  • Windows: C:\Program Files\kubectl\, Docker Desktop kubectl
  • macOS: /usr/local/bin/kubectl, Docker Desktop kubectl, Homebrew
  • Linux: /usr/bin/kubectl, /usr/local/bin/kubectl, snap installations
• Cloud Provider CLIs:
  • AWS CLI bundles kubectl
  • Google Cloud SDK bundles kubectl
  • Azure CLI bundles kubectl
• Docker Desktop: Includes kubectl (but tied to Docker Desktop version)

Shims to Create

• kubectl - Main Kubernetes CLI (single executable)

kubectl Plugins

kubectl has a plugin system (kubectl-<plugin> executables), but:

• Plugins are separate binaries, not managed by kubectl itself
• Users typically install via krew (kubectl plugin manager)
• Plugins go in ~/.krew/bin/ or similar
• Decision: Don't try to manage plugins, just the core kubectl binary

Automatic Reshim Detection

Implement ShouldReshimAfter():

• Returns false - kubectl doesn't install global packages that would need new shims
• Plugin system is separate (krew manages plugins)

Cross-Platform Considerations

• Single Binary: kubectl is a single standalone binary
• Windows: kubectl.exe
• macOS/Linux: kubectl binary with execute permissions
• No Dependencies: Completely standalone
• Architecture Support: amd64, arm64 (Apple Silicon)

Version Format

• Kubernetes uses semantic versioning: 1.28.4, 1.27.8
• Format: v{major}.{minor}.{patch}
• Pre-1.0 versions don't exist (Kubernetes started at 1.0)
• Latest stable: Check https://dl.k8s.io/release/stable.txt

Version Skew Policy

From Kubernetes documentation:

• kubectl can be ±1 minor version from kube-apiserver
• Example: kube-apiserver at 1.28
  • kubectl can be 1.27, 1.28, or 1.29
  • kubectl 1.26 or 1.30 would be unsupported

Testing Requirements

• Use provider contract harness in runtimes/kubectl/provider_test.go
• Test all 19 interface methods
• Test version detection from system installations
• Test installation on all platforms
• Test shim creation and execution
• Test binary download and checksum verification

Special Considerations

• Simplest Provider: Single binary, no dependencies, no extensions
• Cloud Provider Conflict: Users may have kubectl from AWS/GCP/Azure CLIs
  • Ensure dtvem shims take precedence in PATH
• Docker Desktop: May conflict with Docker Desktop's kubectl
• Version Checking: Users can check server version with kubectl version
• kubeconfig: kubectl uses ~/.kube/config (not version-specific)

Integration with Kubernetes Workflows

• Multiple Clusters: .dtvem/runtimes.json per project for cluster-specific versions
• CI/CD: Pin kubectl version in pipeline config
• Team Consistency: Ensure team uses compatible kubectl versions

kubeconfig Context Switching

Note: This is separate from version management

• kubectl config use-context switches between clusters
• dtvem manages kubectl versions, not kubeconfig contexts
• Users still use kubectx or similar tools for context switching

References

• Provider interface: src/internal/runtime/provider.go
• Example implementations: src/runtimes/node/, src/runtimes/python/
• Adding providers guide: .claude/CLAUDE.md
• kubectl releases: https://kubernetes.io/releases/
• Version skew policy: https://kubernetes.io/releases/version-skew-policy/