First commit of golang CLI.
This commit is contained in:
265
CLI_ARCHITECTURE.md
Normal file
265
CLI_ARCHITECTURE.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user