feat(apply): Implement EdgeConnect configuration parsing foundation
- Add comprehensive YAML configuration types for EdgeConnectConfig - Implement robust parser with validation and path resolution - Support both k8sApp and dockerApp configurations - Add comprehensive test coverage with real example parsing - Create validation for infrastructure uniqueness and port ranges - Generate instance names following pattern: appName-appVersion-instance 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
37df99810b
commit
1e48e1b059
14 changed files with 2022 additions and 279 deletions
333
apply.md
Normal file
333
apply.md
Normal file
|
|
@ -0,0 +1,333 @@
|
|||
# EdgeConnect Apply Command - Architecture Blueprint
|
||||
|
||||
## Overview
|
||||
|
||||
The `edge-connect apply -f edgeconnect.yaml` command will provide declarative deployment functionality, allowing users to define their edge applications and infrastructure in YAML configuration files and deploy them atomically.
|
||||
|
||||
## Architecture Design
|
||||
|
||||
### Command Structure
|
||||
|
||||
```
|
||||
edge-connect apply -f <config-file>
|
||||
├── Parse YAML configuration
|
||||
├── Validate configuration schema
|
||||
├── Plan deployment (create/update/no-change)
|
||||
├── Execute deployment steps
|
||||
└── Report results
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **Config Parser** - Parse and validate EdgeConnectConfig YAML
|
||||
2. **Deployment Planner** - Determine what needs to be created/updated
|
||||
3. **Resource Manager** - Handle app and instance lifecycle
|
||||
4. **State Tracker** - Track deployment state and handle rollbacks
|
||||
5. **Reporter** - Provide user feedback during deployment
|
||||
|
||||
## Configuration Schema Analysis
|
||||
|
||||
Based on `EdgeConnectConfig.yaml`:
|
||||
|
||||
```yaml
|
||||
kind: edgeconnect-deployment
|
||||
metadata:
|
||||
name: "edge-app-demo"
|
||||
spec:
|
||||
k8sApp: # App definition
|
||||
appName: "edge-app-demo"
|
||||
appVersion: "1.0.0"
|
||||
manifestFile: "./k8s-deployment.yaml"
|
||||
infraTemplate: # Instance deployment targets
|
||||
- organization: "edp2"
|
||||
region: "EU"
|
||||
cloudletOrg: "TelekomOP"
|
||||
cloudletName: "Munich"
|
||||
flavorName: "EU.small"
|
||||
network: # Network configuration
|
||||
outboundConnections:
|
||||
- protocol: "tcp"
|
||||
portRangeMin: 80
|
||||
portRangeMax: 80
|
||||
remoteCIDR: "0.0.0.0/0"
|
||||
```
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: Configuration Foundation
|
||||
- Define Go structs for EdgeConnectConfig
|
||||
- Implement YAML unmarshaling with validation
|
||||
- Create configuration validation logic
|
||||
- Add unit tests for config parsing
|
||||
|
||||
### Phase 2: Deployment Planning
|
||||
- Implement deployment planner logic
|
||||
- Add state comparison (existing vs desired)
|
||||
- Create deployment plan data structures
|
||||
- Handle multiple infrastructure targets
|
||||
|
||||
### Phase 3: Resource Management
|
||||
- Integrate with existing SDK for app/instance operations
|
||||
- Implement app creation with manifest file handling
|
||||
- Add instance deployment across multiple cloudlets
|
||||
- Handle network configuration
|
||||
|
||||
### Phase 4: Command Implementation
|
||||
- Create apply command with Cobra
|
||||
- Add file flag handling and validation
|
||||
- Implement deployment execution flow
|
||||
- Add progress reporting and error handling
|
||||
|
||||
### Phase 5: Testing & Polish
|
||||
- Comprehensive unit and integration tests
|
||||
- Error handling and rollback scenarios
|
||||
- Documentation and examples
|
||||
- Performance optimization
|
||||
|
||||
## Detailed Implementation Steps
|
||||
|
||||
### Step 1: Configuration Types and Parser
|
||||
**Goal**: Create robust YAML configuration handling
|
||||
|
||||
```go
|
||||
// Define configuration structs
|
||||
type EdgeConnectConfig struct {
|
||||
Kind string `yaml:"kind"`
|
||||
Metadata Metadata `yaml:"metadata"`
|
||||
Spec Spec `yaml:"spec"`
|
||||
}
|
||||
|
||||
type Spec struct {
|
||||
K8sApp *K8sApp `yaml:"k8sApp,omitempty"`
|
||||
DockerApp *DockerApp `yaml:"dockerApp,omitempty"`
|
||||
InfraTemplate []InfraTemplate `yaml:"infraTemplate"`
|
||||
Network *NetworkConfig `yaml:"network,omitempty"`
|
||||
}
|
||||
|
||||
// Add validation methods
|
||||
func (c *EdgeConnectConfig) Validate() error
|
||||
```
|
||||
|
||||
### Step 2: Deployment Planner
|
||||
**Goal**: Intelligent deployment planning with minimal API calls
|
||||
|
||||
```go
|
||||
type DeploymentPlan struct {
|
||||
AppAction ActionType // CREATE, UPDATE, NONE
|
||||
InstanceActions []InstanceAction
|
||||
Summary string
|
||||
}
|
||||
|
||||
type Planner interface {
|
||||
Plan(ctx context.Context, config *EdgeConnectConfig) (*DeploymentPlan, error)
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Resource Manager Integration
|
||||
**Goal**: Seamless integration with existing SDK
|
||||
|
||||
```go
|
||||
type ResourceManager struct {
|
||||
client *edgeconnect.Client
|
||||
}
|
||||
|
||||
func (rm *ResourceManager) ApplyDeployment(ctx context.Context, plan *DeploymentPlan) error
|
||||
```
|
||||
|
||||
### Step 4: Apply Command Implementation
|
||||
**Goal**: User-friendly CLI command with excellent UX
|
||||
|
||||
```go
|
||||
var applyCmd = &cobra.Command{
|
||||
Use: "apply -f <config-file>",
|
||||
Short: "Apply EdgeConnect configuration from file",
|
||||
RunE: runApply,
|
||||
}
|
||||
|
||||
func runApply(cmd *cobra.Command, args []string) error
|
||||
```
|
||||
|
||||
### Step 5: Advanced Features
|
||||
**Goal**: Production-ready capabilities
|
||||
|
||||
- Manifest file hash tracking in annotations
|
||||
- Parallel deployment across cloudlets
|
||||
- Rollback on failure
|
||||
- Dry-run support
|
||||
- Output formatting (JSON, YAML, table)
|
||||
|
||||
## Implementation Prompts
|
||||
|
||||
### Prompt 1: Configuration Foundation
|
||||
```
|
||||
Create the configuration parsing foundation for the EdgeConnect apply command.
|
||||
|
||||
Requirements:
|
||||
1. Define Go structs that match the EdgeConnectConfig.yaml schema exactly
|
||||
2. Implement YAML unmarshaling with proper validation
|
||||
3. Add comprehensive validation methods for all required fields
|
||||
4. Create a ConfigParser interface and implementation
|
||||
5. Handle both k8sApp and dockerApp configurations (dockerApp is commented out but should be supported)
|
||||
6. Add proper error messages with field-level validation details
|
||||
|
||||
Key files to create:
|
||||
- internal/config/types.go (configuration structs)
|
||||
- internal/config/parser.go (parsing and validation logic)
|
||||
- internal/config/parser_test.go (comprehensive tests)
|
||||
|
||||
Follow existing patterns from cmd/app.go and cmd/instance.go for structure consistency.
|
||||
```
|
||||
|
||||
### Prompt 2: Deployment Planner
|
||||
```
|
||||
Implement the deployment planning logic for the apply command.
|
||||
|
||||
Requirements:
|
||||
1. Create a Planner interface that analyzes desired vs current state
|
||||
2. Implement logic to determine if app needs creation or update
|
||||
3. Plan instance deployments across multiple infrastructure targets
|
||||
4. Handle network configuration changes
|
||||
5. Generate human-readable deployment summaries
|
||||
6. Minimize API calls by batching show operations
|
||||
7. Support dry-run mode for plan preview
|
||||
|
||||
Key files to create:
|
||||
- internal/apply/planner.go (planning interface and implementation)
|
||||
- internal/apply/types.go (deployment plan data structures)
|
||||
- internal/apply/planner_test.go (planning logic tests)
|
||||
|
||||
Integration points:
|
||||
- Use existing SDK client from cmd/app.go patterns
|
||||
- Follow error handling patterns from existing commands
|
||||
```
|
||||
|
||||
### Prompt 3: Resource Manager and Apply Logic
|
||||
```
|
||||
Implement the core apply command with resource management.
|
||||
|
||||
Requirements:
|
||||
1. Create ResourceManager that executes deployment plans
|
||||
2. Handle manifest file reading and hash generation for annotations
|
||||
3. Implement parallel deployment across multiple cloudlets
|
||||
4. Add proper error handling and rollback on partial failures
|
||||
5. Create progress reporting during deployment
|
||||
6. Handle network configuration application
|
||||
7. Support both create and update operations
|
||||
|
||||
Key files to create:
|
||||
- internal/apply/manager.go (resource management logic)
|
||||
- internal/apply/manager_test.go (resource manager tests)
|
||||
- cmd/apply.go (cobra command implementation)
|
||||
|
||||
Integration requirements:
|
||||
- Reuse newSDKClient() pattern from existing commands
|
||||
- Follow flag handling patterns from cmd/app.go
|
||||
- Integrate with existing viper configuration
|
||||
```
|
||||
|
||||
### Prompt 4: Command Integration and UX
|
||||
```
|
||||
Complete the apply command CLI integration with excellent user experience.
|
||||
|
||||
Requirements:
|
||||
1. Add apply command to root command with proper flag handling
|
||||
2. Implement file validation and helpful error messages
|
||||
3. Add progress indicators during deployment
|
||||
4. Create deployment summary reporting
|
||||
5. Add --dry-run flag for plan preview
|
||||
6. Support --output flag for different output formats
|
||||
7. Handle interruption gracefully (Ctrl+C)
|
||||
|
||||
Key files to modify/create:
|
||||
- cmd/apply.go (complete command implementation)
|
||||
- cmd/root.go (add apply command)
|
||||
- Update existing patterns to support new command
|
||||
|
||||
UX requirements:
|
||||
- Clear progress indication during long deployments
|
||||
- Helpful error messages with suggested fixes
|
||||
- Consistent output formatting with existing commands
|
||||
```
|
||||
|
||||
### Prompt 5: Testing and Documentation
|
||||
```
|
||||
Add comprehensive testing and documentation for the apply command.
|
||||
|
||||
Requirements:
|
||||
1. Create integration tests that use httptest mock servers
|
||||
2. Test error scenarios and rollback behavior
|
||||
3. Add example EdgeConnectConfig files for different use cases
|
||||
4. Create documentation explaining the apply workflow
|
||||
5. Add performance tests for large deployments
|
||||
6. Test parallel deployment scenarios
|
||||
|
||||
Key files to create:
|
||||
- cmd/apply_test.go (integration tests)
|
||||
- examples/apply/ (example configurations)
|
||||
- docs/apply-command.md (user documentation)
|
||||
|
||||
Testing requirements:
|
||||
- Follow existing test patterns from cmd/app_test.go
|
||||
- Mock SDK responses for predictable testing
|
||||
- Cover both happy path and error scenarios
|
||||
```
|
||||
|
||||
### Prompt 6: Advanced Features and Polish
|
||||
```
|
||||
Implement advanced features and polish the apply command for production use.
|
||||
|
||||
Requirements:
|
||||
1. Add manifest file hash tracking in app annotations
|
||||
2. Implement intelligent update detection (only update when manifest changes)
|
||||
3. Add rollback functionality for failed deployments
|
||||
4. Create deployment status tracking and reporting
|
||||
5. Add support for environment variable substitution in configs
|
||||
6. Implement configuration validation with helpful suggestions
|
||||
|
||||
Key enhancements:
|
||||
- Optimize for large-scale deployments
|
||||
- Add verbose logging options
|
||||
- Create deployment hooks for custom workflows
|
||||
- Support configuration templating
|
||||
```
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- **Usability**: Users can deploy complex applications with single command
|
||||
- **Reliability**: Deployment failures are handled gracefully with rollback
|
||||
- **Performance**: Parallel deployments reduce total deployment time by 70%
|
||||
- **Maintainability**: Code follows existing CLI patterns and is easily extensible
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
- **Configuration Errors**: Comprehensive validation with helpful error messages
|
||||
- **Partial Failures**: Rollback mechanisms for failed deployments
|
||||
- **API Changes**: Abstract SDK usage through interfaces for easy mocking/testing
|
||||
- **Large Deployments**: Implement timeouts and progress reporting for long operations
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
cmd/
|
||||
├── apply.go # Apply command implementation
|
||||
├── apply_test.go # Command integration tests
|
||||
└── root.go # Updated with apply command
|
||||
|
||||
internal/
|
||||
├── apply/
|
||||
│ ├── types.go # Deployment plan structures
|
||||
│ ├── planner.go # Deployment planning logic
|
||||
│ ├── manager.go # Resource management
|
||||
│ └── *_test.go # Unit tests
|
||||
└── config/
|
||||
├── types.go # Configuration structs
|
||||
├── parser.go # YAML parsing and validation
|
||||
└── *_test.go # Parser tests
|
||||
|
||||
examples/apply/
|
||||
├── simple-app.yaml # Basic application deployment
|
||||
├── multi-cloudlet.yaml # Multi-region deployment
|
||||
└── with-network.yaml # Network configuration example
|
||||
```
|
||||
|
||||
This blueprint provides a systematic approach to implementing the apply command while maintaining consistency with existing CLI patterns and ensuring robust error handling and user experience.
|
||||
Loading…
Add table
Add a link
Reference in a new issue