edge-connect-client/apply.md

# 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.