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:

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

// 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

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

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

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.