265 lines
12 KiB
Markdown
265 lines
12 KiB
Markdown
# Wild CLI - Go Architecture Design
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
wild-cli/
|
|
├── cmd/
|
|
│ └── wild/
|
|
│ ├── main.go # Main entry point
|
|
│ ├── root.go # Root command and global flags
|
|
│ ├── setup/ # Setup commands
|
|
│ │ ├── setup.go # Setup root command
|
|
│ │ ├── scaffold.go # wild setup scaffold
|
|
│ │ ├── cluster.go # wild setup cluster
|
|
│ │ └── services.go # wild setup services
|
|
│ ├── app/ # App management commands
|
|
│ │ ├── app.go # App root command
|
|
│ │ ├── list.go # wild app list
|
|
│ │ ├── fetch.go # wild app fetch
|
|
│ │ ├── add.go # wild app add
|
|
│ │ ├── deploy.go # wild app deploy
|
|
│ │ ├── delete.go # wild app delete
|
|
│ │ ├── backup.go # wild app backup
|
|
│ │ ├── restore.go # wild app restore
|
|
│ │ └── doctor.go # wild app doctor
|
|
│ ├── cluster/ # Cluster management commands
|
|
│ │ ├── cluster.go # Cluster root command
|
|
│ │ ├── config.go # wild cluster config
|
|
│ │ ├── nodes.go # wild cluster nodes
|
|
│ │ └── services.go # wild cluster services
|
|
│ ├── config/ # Configuration commands
|
|
│ │ ├── config.go # Config root command
|
|
│ │ ├── get.go # wild config get
|
|
│ │ └── set.go # wild config set
|
|
│ ├── secret/ # Secret management commands
|
|
│ │ ├── secret.go # Secret root command
|
|
│ │ ├── get.go # wild secret get
|
|
│ │ └── set.go # wild secret set
|
|
│ └── util/ # Utility commands
|
|
│ ├── backup.go # wild backup
|
|
│ ├── dashboard.go # wild dashboard
|
|
│ ├── template.go # wild template
|
|
│ ├── status.go # wild status
|
|
│ └── version.go # wild version
|
|
├── internal/ # Internal packages
|
|
│ ├── config/ # Configuration management
|
|
│ │ ├── manager.go # Config/secrets YAML handling
|
|
│ │ ├── template.go # Template processing (gomplate)
|
|
│ │ ├── validation.go # Schema validation
|
|
│ │ └── types.go # Configuration structs
|
|
│ ├── kubernetes/ # Kubernetes operations
|
|
│ │ ├── client.go # K8s client management
|
|
│ │ ├── apply.go # kubectl apply operations
|
|
│ │ ├── namespace.go # Namespace management
|
|
│ │ └── resources.go # Resource utilities
|
|
│ ├── talos/ # Talos Linux operations
|
|
│ │ ├── config.go # Talos config generation
|
|
│ │ ├── node.go # Node operations
|
|
│ │ └── client.go # Talos client wrapper
|
|
│ ├── backup/ # Backup/restore functionality
|
|
│ │ ├── restic.go # Restic backup wrapper
|
|
│ │ ├── postgres.go # PostgreSQL backup
|
|
│ │ ├── pvc.go # PVC backup
|
|
│ │ └── manager.go # Backup orchestration
|
|
│ ├── apps/ # App management
|
|
│ │ ├── catalog.go # App catalog management
|
|
│ │ ├── fetch.go # App fetching logic
|
|
│ │ ├── deploy.go # Deployment logic
|
|
│ │ └── health.go # Health checking
|
|
│ ├── environment/ # Environment detection
|
|
│ │ ├── paths.go # WC_ROOT, WC_HOME detection
|
|
│ │ ├── nodes.go # Node detection
|
|
│ │ └── validation.go # Environment validation
|
|
│ ├── external/ # External tool management
|
|
│ │ ├── kubectl.go # kubectl wrapper
|
|
│ │ ├── talosctl.go # talosctl wrapper
|
|
│ │ ├── yq.go # yq wrapper
|
|
│ │ ├── gomplate.go # gomplate wrapper
|
|
│ │ ├── kustomize.go # kustomize wrapper
|
|
│ │ └── restic.go # restic wrapper
|
|
│ ├── output/ # Output formatting
|
|
│ │ ├── formatter.go # Output formatting
|
|
│ │ ├── progress.go # Progress indicators
|
|
│ │ └── logger.go # Structured logging
|
|
│ └── common/ # Shared utilities
|
|
│ ├── errors.go # Error handling
|
|
│ ├── validation.go # Input validation
|
|
│ ├── files.go # File operations
|
|
│ └── network.go # Network utilities
|
|
├── pkg/ # Public packages
|
|
│ └── wildcloud/ # Public API (if needed)
|
|
│ └── client.go # SDK for other tools
|
|
├── test/ # Test files
|
|
│ ├── integration/ # Integration tests
|
|
│ ├── fixtures/ # Test fixtures
|
|
│ └── mocks/ # Mock implementations
|
|
├── scripts/ # Build and development scripts
|
|
│ ├── build.sh # Build script
|
|
│ ├── test.sh # Test runner
|
|
│ └── install.sh # Installation script
|
|
├── docs/ # Documentation
|
|
│ ├── commands/ # Command documentation
|
|
│ └── development.md # Development guide
|
|
├── go.mod # Go module definition
|
|
├── go.sum # Go module checksums
|
|
├── Makefile # Build automation
|
|
├── README.md # Project README
|
|
└── LICENSE # License file
|
|
```
|
|
|
|
## Core Architecture Principles
|
|
|
|
### 1. Cobra CLI Framework
|
|
- **Root command** with global flags (--config-dir, --verbose, --dry-run)
|
|
- **Nested command structure** mirroring the logical organization
|
|
- **Consistent flag patterns** across similar commands
|
|
- **Auto-generated help** and completion
|
|
|
|
### 2. Dependency Injection
|
|
- **Interface-based design** for external tools and K8s client
|
|
- **Testable components** through dependency injection
|
|
- **Mock implementations** for testing
|
|
- **Configuration-driven** tool selection
|
|
|
|
### 3. Error Handling Strategy
|
|
```go
|
|
// Wrapped errors with context
|
|
func (m *Manager) ApplyApp(ctx context.Context, name string) error {
|
|
if err := m.validateApp(name); err != nil {
|
|
return fmt.Errorf("validating app %s: %w", name, err)
|
|
}
|
|
|
|
if err := m.kubernetes.Apply(ctx, appPath); err != nil {
|
|
return fmt.Errorf("applying app %s to cluster: %w", name, err)
|
|
}
|
|
|
|
return nil
|
|
}
|
|
```
|
|
|
|
### 4. Configuration Management
|
|
```go
|
|
type ConfigManager struct {
|
|
configPath string
|
|
secretsPath string
|
|
template *template.Engine
|
|
}
|
|
|
|
type Config struct {
|
|
Cluster struct {
|
|
Name string `yaml:"name"`
|
|
Domain string `yaml:"domain"`
|
|
VIP string `yaml:"vip"`
|
|
Nodes []Node `yaml:"nodes"`
|
|
} `yaml:"cluster"`
|
|
|
|
Apps map[string]AppConfig `yaml:"apps"`
|
|
}
|
|
```
|
|
|
|
### 5. External Tool Management
|
|
```go
|
|
type ExternalTool interface {
|
|
IsInstalled() bool
|
|
Version() (string, error)
|
|
Execute(ctx context.Context, args ...string) ([]byte, error)
|
|
}
|
|
|
|
type KubectlClient struct {
|
|
binary string
|
|
config string
|
|
}
|
|
|
|
func (k *KubectlClient) Apply(ctx context.Context, file string) error {
|
|
args := []string{"apply", "-f", file}
|
|
if k.config != "" {
|
|
args = append([]string{"--kubeconfig", k.config}, args...)
|
|
}
|
|
|
|
_, err := k.Execute(ctx, args...)
|
|
return err
|
|
}
|
|
```
|
|
|
|
## Key Features & Improvements
|
|
|
|
### 1. **Enhanced User Experience**
|
|
- **Progress indicators** for long-running operations
|
|
- **Interactive prompts** for setup and configuration
|
|
- **Colored output** for better readability
|
|
- **Shell completion** for commands and flags
|
|
|
|
### 2. **Better Error Handling**
|
|
- **Contextualized errors** with suggestion for fixes
|
|
- **Validation before execution** to catch issues early
|
|
- **Rollback capabilities** for failed operations
|
|
- **Detailed error reporting** with troubleshooting tips
|
|
|
|
### 3. **Parallel Operations**
|
|
- **Concurrent node operations** during cluster setup
|
|
- **Parallel app deployments** where safe
|
|
- **Background status monitoring** during operations
|
|
|
|
### 4. **Cross-Platform Support**
|
|
- **Abstracted file paths** using filepath package
|
|
- **Platform-specific executables** (kubectl.exe on Windows)
|
|
- **Docker fallback** for missing tools
|
|
|
|
### 5. **Testing Infrastructure**
|
|
- **Unit tests** for all business logic
|
|
- **Integration tests** with real Kubernetes clusters
|
|
- **Mock implementations** for external dependencies
|
|
- **Benchmark tests** for performance-critical operations
|
|
|
|
## Implementation Strategy
|
|
|
|
### Phase 1: Foundation (Week 1-2)
|
|
1. **Project structure** - Set up Go module and directory structure
|
|
2. **Core interfaces** - Define interfaces for external tools and K8s
|
|
3. **Configuration management** - Implement config/secrets handling
|
|
4. **Basic commands** - Implement `wild config` and `wild secret` commands
|
|
|
|
### Phase 2: App Management (Week 3-4)
|
|
1. **App catalog** - Implement app listing and fetching
|
|
2. **App deployment** - Core deployment logic with Kustomize
|
|
3. **App lifecycle** - Add, deploy, delete commands
|
|
4. **Health checking** - Basic app health validation
|
|
|
|
### Phase 3: Cluster Operations (Week 5-6)
|
|
1. **Setup commands** - Scaffold, cluster, services setup
|
|
2. **Node management** - Node detection and configuration
|
|
3. **Service deployment** - Infrastructure services deployment
|
|
|
|
### Phase 4: Advanced Features (Week 7-8)
|
|
1. **Backup/restore** - Implement restic-based backup system
|
|
2. **Progress tracking** - Add progress indicators and status reporting
|
|
3. **Error recovery** - Implement rollback and retry mechanisms
|
|
4. **Documentation** - Generate command documentation
|
|
|
|
## Technical Considerations
|
|
|
|
### Dependencies
|
|
```go
|
|
// Core dependencies
|
|
github.com/spf13/cobra // CLI framework
|
|
github.com/spf13/viper // Configuration management
|
|
k8s.io/client-go // Kubernetes client
|
|
k8s.io/apimachinery // Kubernetes types
|
|
sigs.k8s.io/yaml // YAML processing
|
|
|
|
// Utility dependencies
|
|
github.com/fatih/color // Colored output
|
|
github.com/schollz/progressbar/v3 // Progress bars
|
|
github.com/manifoldco/promptui // Interactive prompts
|
|
go.uber.org/zap // Structured logging
|
|
```
|
|
|
|
### Build & Release
|
|
- **Multi-platform builds** using GitHub Actions
|
|
- **Automated testing** on Linux, macOS, Windows
|
|
- **Release binaries** for major platforms
|
|
- **Installation script** for easy setup
|
|
- **Homebrew formula** for macOS users
|
|
|
|
This architecture provides a solid foundation for migrating Wild Cloud's functionality to Go while adding modern CLI features and maintaining the existing workflow. |