From 9993c65854a5dda2ea4b11d0c4fb2a42fcf00177 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 28 May 2026 04:11:53 +0000 Subject: [PATCH 1/6] docs: Initialize documentation pipeline [skip ci] --- .doc-pipeline-status.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .doc-pipeline-status.md diff --git a/.doc-pipeline-status.md b/.doc-pipeline-status.md new file mode 100644 index 00000000..11512c98 --- /dev/null +++ b/.doc-pipeline-status.md @@ -0,0 +1,5 @@ +# Documentation Pipeline Started + +Run ID: doc-orchestrator-1779941493376 +Status: In Progress +Started: 2026-05-28 04:11:53 UTC From e298cb49d64618c57d145da60996a8cf2fcfd3c4 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 28 May 2026 04:13:19 +0000 Subject: [PATCH 2/6] docs: Stage 1 - Inline documentation (10 files) [skip ci] --- cmd/bootstrap/.bootstrap.md | 31 +++++++++++++++++---------- cmd/chart/.chart.md | 29 ++++++++++++------------- cmd/chart/.install.md | 42 +++++++++++++------------------------ cmd/cluster/.cleanup.md | 15 +++++++------ cmd/cluster/.cluster.md | 39 ++++++++++++++++++---------------- cmd/cluster/.create.md | 35 +++++++++++++------------------ cmd/cluster/.delete.md | 36 +++++++++++-------------------- cmd/cluster/.list.md | 31 ++++++++++++++++----------- cmd/cluster/.status.md | 28 ++++++++++++------------- cmd/dev/.dev.md | 27 +++++++++++++----------- 10 files changed, 152 insertions(+), 161 deletions(-) diff --git a/cmd/bootstrap/.bootstrap.md b/cmd/bootstrap/.bootstrap.md index dfa02783..5bb46876 100644 --- a/cmd/bootstrap/.bootstrap.md +++ b/cmd/bootstrap/.bootstrap.md @@ -1,12 +1,11 @@ -This file defines the CLI command for bootstrapping a complete OpenFrame environment, providing a streamlined setup experience. +This file defines the CLI command interface for bootstrapping a complete OpenFrame environment, providing a streamlined setup experience that combines cluster creation and chart installation. ## Key Components -- **`GetBootstrapCmd()`** - Returns a configured Cobra command for the bootstrap operation -- **Command Configuration** - Sets up usage patterns, help text, and argument validation -- **Flag Definitions** - Configures deployment mode, interactive options, and verbosity settings -- **Execution Handler** - Delegates actual bootstrap logic to the internal bootstrap service +- **GetBootstrapCmd()**: Returns a configured Cobra command that orchestrates the complete OpenFrame bootstrap process +- **Command Configuration**: Defines usage patterns, help text, and command-line flags for the bootstrap operation +- **Service Delegation**: Delegates the actual bootstrap logic to `bootstrap.NewService().Execute()` ## Usage Example @@ -19,16 +18,26 @@ import ( ) func main() { - rootCmd := &cobra.Command{ - Use: "openframe", - } + rootCmd := &cobra.Command{Use: "openframe"} - // Add the bootstrap command to the root command + // Add the bootstrap command to the CLI rootCmd.AddCommand(bootstrap.GetBootstrapCmd()) - // Execute the CLI rootCmd.Execute() } ``` -The bootstrap command performs a complete OpenFrame setup by sequentially executing cluster creation and chart installation. It supports various deployment modes (oss-tenant, saas-tenant, saas-shared) and can run in both interactive and non-interactive modes. The verbose flag enables detailed logging including ArgoCD synchronization progress, making it suitable for both development and CI/CD environments. \ No newline at end of file +The bootstrap command supports multiple execution modes: + +```bash +# Interactive mode with prompts +openframe bootstrap my-cluster + +# Non-interactive CI/CD mode +openframe bootstrap --deployment-mode=oss-tenant --non-interactive + +# Verbose mode with detailed logging +openframe bootstrap -v --deployment-mode=saas-shared +``` + +This command combines `openframe cluster create` and `openframe chart install` into a single operation, making it easier for users to get started with OpenFrame by automating the complete environment setup process. \ No newline at end of file diff --git a/cmd/chart/.chart.md b/cmd/chart/.chart.md index a05d083c..2eaeb9f2 100644 --- a/cmd/chart/.chart.md +++ b/cmd/chart/.chart.md @@ -1,27 +1,28 @@ -This file defines the root `chart` command for the OpenFrame CLI, providing Helm chart management functionality with a focus on ArgoCD installation and management. +This file defines the main chart command for the OpenFrame CLI, providing Helm chart management functionality with a focus on ArgoCD deployment. ## Key Components -- **GetChartCmd()** - Returns the main chart command with subcommands -- **Prerequisites Integration** - Automatically checks and installs required dependencies -- **UI Integration** - Shows the OpenFrame logo for better user experience -- **Command Structure** - Supports aliases (`c`) and includes help text with examples +- **GetChartCmd()**: Returns the root `chart` command with alias `c` for managing Helm charts +- **PersistentPreRunE**: Runs prerequisite checks and installations for all chart subcommands +- **RunE**: Shows the OpenFrame logo and help when no subcommand is specified +- **Subcommand Integration**: Adds the install command via `getInstallCmd()` + +The command includes comprehensive help text explaining ArgoCD chart lifecycle management and usage examples. It ensures prerequisites are met before executing chart operations and provides a clean user interface with the Flamingo logo display. ## Usage Example ```go -// Create the chart command with subcommands +// Get the chart command with all subcommands chartCmd := GetChartCmd() -// The command supports both full and alias usage: -// openframe chart install -// openframe c install - -// When run without subcommands, shows help: -// openframe chart +// The command supports these usage patterns: +// openframe chart install - Install ArgoCD on default cluster +// openframe chart install my-cluster - Install on specific cluster +// openframe c install - Using alias 'c' -// Prerequisites are automatically checked before subcommand execution +// Add to root command +rootCmd.AddCommand(chartCmd) ``` -The command implements a `PersistentPreRunE` hook that validates prerequisites for all subcommands and displays the UI logo. When invoked without subcommands, it shows the help text. The command structure suggests it's part of a larger CLI tool for managing Kubernetes clusters and ArgoCD deployments. \ No newline at end of file +The chart command serves as the parent for chart-related operations, with prerequisite validation ensuring all dependencies are available before chart deployment operations begin. \ No newline at end of file diff --git a/cmd/chart/.install.md b/cmd/chart/.install.md index 1a4e395e..bb0da063 100644 --- a/cmd/chart/.install.md +++ b/cmd/chart/.install.md @@ -1,13 +1,13 @@ -Command line interface module for installing ArgoCD and app-of-apps on Kubernetes clusters with support for interactive and CI/CD modes. +This file implements the `install` subcommand for the OpenFrame CLI chart management system, providing automated installation of ArgoCD and app-of-apps configurations on Kubernetes clusters. ## Key Components -- **getInstallCmd()** - Creates the install subcommand with comprehensive help text and examples -- **runInstallCommand()** - Handles command execution by extracting flags and delegating to services -- **InstallFlags** - Struct containing all installation configuration options -- **extractInstallFlags()** - Validates and extracts command flags with deployment mode validation -- **addInstallFlags()** - Defines all available command-line flags +- **`getInstallCmd()`** - Returns the configured cobra.Command for the install subcommand with usage examples and flag definitions +- **`runInstallCommand()`** - Main execution handler that processes flags and delegates to the installation service +- **`InstallFlags`** - Struct containing all installation configuration options including deployment modes and GitHub settings +- **`extractInstallFlags()`** - Extracts and validates command-line flags with built-in validation for deployment modes +- **`addInstallFlags()`** - Defines all available flags for the install command ## Usage Example @@ -15,34 +15,22 @@ Command line interface module for installing ArgoCD and app-of-apps on Kubernete // Create the install command installCmd := getInstallCmd() -// The command supports multiple usage patterns: -// Interactive mode -cmd.Execute([]string{"install"}) - -// Specific cluster -cmd.Execute([]string{"install", "my-cluster"}) - -// CI/CD mode with all options -cmd.Execute([]string{ - "install", - "--deployment-mode=oss-tenant", - "--non-interactive", - "--github-branch=develop", - "--force" -}) - -// Extract flags programmatically +// Example flag extraction flags, err := extractInstallFlags(cmd) if err != nil { return err } -// Use extracted flags for installation request +// Create installation request req := types.InstallationRequest{ - DeploymentMode: flags.DeploymentMode, - NonInteractive: flags.NonInteractive, + Args: []string{"my-cluster"}, Force: flags.Force, + DeploymentMode: "oss-tenant", + NonInteractive: true, } + +// Execute installation +err = services.InstallChartsWithConfig(req) ``` -The module validates deployment modes (oss-tenant, saas-tenant, saas-shared) and enforces that non-interactive mode requires a deployment mode to be specified. \ No newline at end of file +The command supports three deployment modes (`oss-tenant`, `saas-tenant`, `saas-shared`) and includes comprehensive validation ensuring non-interactive mode requires a deployment mode specification. It integrates with the shared error handling system for consistent CLI experience. \ No newline at end of file diff --git a/cmd/cluster/.cleanup.md b/cmd/cluster/.cleanup.md index 558db5e0..70f25b04 100644 --- a/cmd/cluster/.cleanup.md +++ b/cmd/cluster/.cleanup.md @@ -1,23 +1,22 @@ -Implements the `cleanup` command for removing unused cluster resources and Docker images from development clusters to free disk space. +This file implements the cluster cleanup command functionality for the OpenFrame CLI, providing Docker image and resource cleanup for development clusters. ## Key Components -- **`getCleanupCmd()`** - Creates and configures the cobra command with flags, aliases, and validation +- **`getCleanupCmd()`** - Creates and configures the cleanup cobra command with flags, aliases, and validation - **`runCleanupCluster()`** - Main execution logic that handles cluster selection, type detection, and cleanup operations -- **`GetCleanupCmdForTesting()`** - Test-friendly export of the cleanup command +- **`GetCleanupCmdForTesting()`** - Public function that exposes the cleanup command for testing purposes ## Usage Example ```go -// Get the cleanup command and add to parent +// Create and execute the cleanup command cleanupCmd := getCleanupCmd() -clusterCmd.AddCommand(cleanupCmd) -// Command supports multiple usage patterns: +// Command supports various usage patterns: // openframe cluster cleanup # Interactive cluster selection -// openframe cluster cleanup my-cluster # Target specific cluster +// openframe cluster cleanup my-cluster # Clean specific cluster // openframe cluster cleanup my-cluster --force # Skip confirmation prompts ``` -The command integrates with the cluster service layer to detect cluster types (Docker, Kubernetes, etc.) and execute appropriate cleanup procedures. It provides a user-friendly interface with operation status messages and confirmation prompts for safe resource removal during development workflows. \ No newline at end of file +The cleanup command follows a standard pattern: validates flags and global configuration, presents a user-friendly cluster selection interface, detects the cluster type automatically, and executes the cleanup operation through the service layer while providing progress feedback through the operations UI. \ No newline at end of file diff --git a/cmd/cluster/.cluster.md b/cmd/cluster/.cluster.md index b6017036..f26de9ef 100644 --- a/cmd/cluster/.cluster.md +++ b/cmd/cluster/.cluster.md @@ -1,28 +1,31 @@ -This file defines the main cluster command for the OpenFrame CLI, providing Kubernetes cluster lifecycle management functionality through Cobra CLI framework. +The main entry point for the cluster command group that manages Kubernetes clusters in the OpenFrame CLI. ## Key Components -- **GetClusterCmd()**: Main function that creates and configures the cluster command with subcommands -- **Persistent Pre-run Hook**: Validates prerequisites and shows UI logo for subcommands -- **Subcommands**: Integrates create, delete, list, status, and cleanup cluster operations -- **Global Flags**: Initializes and applies global configuration flags across all subcommands +- **GetClusterCmd()** - Returns the root cluster command with all subcommands and configuration +- **Global Flags Integration** - Initializes and adds global flags using the utils and models packages +- **Prerequisites Check** - Validates system requirements before executing subcommands +- **UI Integration** - Shows the OpenFrame logo and provides consistent user experience + +## Command Structure + +The cluster command provides these subcommands: +- `create` - Interactive cluster creation +- `delete` - Cluster removal and cleanup +- `list` - Display managed clusters +- `status` - Show cluster details +- `cleanup` - Remove unused resources ## Usage Example ```go -// Get the complete cluster command with all subcommands -clusterCmd := GetClusterCmd() - -// Add to root command -rootCmd.AddCommand(clusterCmd) - -// The command provides these operations: -// openframe cluster create - Create new K3d cluster -// openframe cluster delete - Remove existing cluster -// openframe cluster list - Show all managed clusters -// openframe cluster status - Display cluster details -// openframe cluster cleanup - Clean unused resources +// Get the cluster command for CLI registration +clusterCmd := cluster.GetClusterCmd() + +// The command supports aliases and provides help +// Users can run: openframe cluster create +// Or shorthand: openframe k create ``` -The command supports both the full `cluster` name and short alias `k` for convenience. Each subcommand includes prerequisite validation and consistent UI presentation through the logo display system. All operations are designed for K3d clusters optimized for local development environments. \ No newline at end of file +The command includes automatic prerequisite checking and logo display for a polished user experience. It uses K3d for local Kubernetes development clusters and integrates with the shared UI system for consistent branding across the OpenFrame CLI. \ No newline at end of file diff --git a/cmd/cluster/.create.md b/cmd/cluster/.create.md index b247c475..ca908275 100644 --- a/cmd/cluster/.create.md +++ b/cmd/cluster/.create.md @@ -1,31 +1,26 @@ -This file implements the `create` command for the OpenFrame CLI cluster management functionality, providing both interactive and non-interactive cluster creation workflows. +A Cobra command implementation for creating Kubernetes clusters in the OpenFrame CLI tool, supporting both interactive wizard and non-interactive modes with comprehensive flag validation. ## Key Components -- **`getCreateCmd()`** - Builds the cobra command with flags, validation, and usage documentation -- **`runCreateCluster()`** - Main execution logic handling interactive UI flow or direct creation from flags -- **Configuration Flow** - Supports wizard mode via UI layer or direct flag-based configuration -- **Validation Pipeline** - Pre-run validation for cluster names, node counts, and global flags +- **`getCreateCmd()`** - Returns a configured Cobra command with cluster creation flags and validation +- **`runCreateCluster()`** - Main execution function that handles both interactive and non-interactive cluster creation flows +- **Interactive Mode** - Uses UI configuration handler to guide users through cluster setup +- **Non-Interactive Mode** - Creates clusters directly from command-line flags with sensible defaults +- **Flag Validation** - Comprehensive validation of cluster names, node counts, and configuration parameters ## Usage Example ```go -// Interactive cluster creation with wizard -cmd := getCreateCmd() -cmd.Execute() // Shows selection menu for quick start or custom config +// Get the create command and add it to parent command +createCmd := getCreateCmd() +clusterCmd.AddCommand(createCmd) -// Direct creation with flags (non-interactive) -args := []string{"my-cluster"} -cmd.SetArgs(args) -cmd.Flags().Set("skip-wizard", "true") -cmd.Flags().Set("nodes", "3") -cmd.Flags().Set("type", "k3d") -cmd.Execute() // Creates cluster directly with specified config - -// Dry-run mode to preview configuration -cmd.Flags().Set("dry-run", "true") -cmd.Execute() // Shows config summary without creating cluster +// Example command flows: +// Interactive: openframe cluster create +// With name: openframe cluster create my-cluster +// Non-interactive: openframe cluster create --skip-wizard --nodes 3 --type k3d +// Dry run: openframe cluster create --dry-run ``` -The command integrates with the UI layer for interactive configuration and the service layer for actual cluster operations, supporting both wizard-guided setup and automation-friendly flag-based creation. \ No newline at end of file +The command integrates with the broader cluster management system, using service layers for actual cluster creation and UI components for user interaction. It supports various cluster types (K3d, etc.) and provides detailed configuration summaries before execution. \ No newline at end of file diff --git a/cmd/cluster/.delete.md b/cmd/cluster/.delete.md index cdd71c1f..eaae630f 100644 --- a/cmd/cluster/.delete.md +++ b/cmd/cluster/.delete.md @@ -1,35 +1,23 @@ -Provides the cluster delete command implementation for the OpenFrame CLI, handling interactive cluster selection and cleanup of all associated resources. +Implements the `delete` command for removing Kubernetes clusters in the OpenFrame CLI, providing an interactive cluster deletion workflow with confirmation prompts and comprehensive cleanup. ## Key Components -- **`getDeleteCmd()`** - Creates and configures the cobra command for cluster deletion with flags and validation -- **`runDeleteCluster()`** - Main execution function that handles cluster selection, type detection, and deletion workflow -- **Interactive UI** - Uses `OperationsUI` for user-friendly cluster selection and operation feedback -- **Service Integration** - Leverages cluster service for listing, type detection, and deletion operations -- **Error Handling** - Comprehensive error handling with verbose output support and graceful cancellation +- **`getDeleteCmd()`** - Creates and configures the `delete` subcommand with flags, validation, and help text +- **`runDeleteCluster()`** - Executes the cluster deletion process including selection, confirmation, and cleanup operations +- **Interactive Selection** - Uses UI components to provide user-friendly cluster selection and confirmation prompts +- **Comprehensive Cleanup** - Stops intercepts, deletes cluster resources, and cleans up Docker containers/networks ## Usage Example ```go -// Create the delete command -deleteCmd := getDeleteCmd() +// Register the delete command with the cluster parent command +clusterCmd.AddCommand(getDeleteCmd()) -// The command supports multiple usage patterns: -// 1. Direct cluster name specification -// openframe cluster delete my-cluster - -// 2. Interactive selection from available clusters -// openframe cluster delete - -// 3. Force deletion without confirmation -// openframe cluster delete my-cluster --force - -// Execute with args simulation -err := deleteCmd.RunE(deleteCmd, []string{"my-cluster"}) -if err != nil { - log.Fatal(err) -} +// Example CLI usage: +// openframe cluster delete my-cluster # Delete specific cluster +// openframe cluster delete my-cluster --force # Skip confirmation +// openframe cluster delete # Interactive selection ``` -The delete command provides a complete cluster cleanup workflow including stopping intercepts, removing Docker resources, and cleaning up configuration files. It supports both direct cluster specification and interactive selection with confirmation prompts for safe operation. \ No newline at end of file +The command supports both direct cluster specification via arguments and interactive selection from available clusters. It includes pre-run validation, force deletion options, and proper error handling with verbose output support. The deletion process automatically detects cluster type and performs appropriate cleanup operations. \ No newline at end of file diff --git a/cmd/cluster/.list.md b/cmd/cluster/.list.md index 020f2055..fba4ac88 100644 --- a/cmd/cluster/.list.md +++ b/cmd/cluster/.list.md @@ -1,23 +1,30 @@ -Defines the `list` subcommand for the OpenFrame cluster CLI, providing functionality to display all managed Kubernetes clusters in a formatted table. +This file implements the "list" command functionality for OpenFrame CLI's cluster management, allowing users to view all Kubernetes clusters managed by the platform. ## Key Components -- **`getListCmd()`** - Creates and configures the cobra command for listing clusters with validation and flag setup -- **`runListClusters()`** - Executes the cluster listing logic, retrieves cluster data and displays results -- **Command Configuration** - Sets up usage examples, help text, and integrates with global flag system -- **Validation Pipeline** - Implements pre-run validation for global and list-specific flags +- **`getListCmd()`** - Creates and configures the Cobra command for listing clusters with validation and flag setup +- **`runListClusters()`** - Executes the cluster listing operation, retrieving and displaying cluster information ## Usage Example ```go -// Command registration (typically in parent cluster command) -rootCmd.AddCommand(getListCmd()) +// Command structure usage within OpenFrame CLI +func addClusterCommands(rootCmd *cobra.Command) { + clusterCmd := &cobra.Command{ + Use: "cluster", + Short: "Manage Kubernetes clusters", + } + + // Add the list subcommand + clusterCmd.AddCommand(getListCmd()) + rootCmd.AddCommand(clusterCmd) +} -// Command line usage examples: -// openframe cluster list -// openframe cluster list --verbose -// openframe cluster list --quiet +// The command supports various output formats +// openframe cluster list // Standard table output +// openframe cluster list --verbose // Detailed cluster information +// openframe cluster list --quiet // Minimal output format ``` -The command integrates with the OpenFrame CLI's global flag system and service layer to retrieve cluster information from all registered providers. It supports verbose output for detailed information and quiet mode for minimal output, displaying results in a user-friendly table format showing cluster name, type, status, and node count. \ No newline at end of file +The command integrates with OpenFrame's global flag system for consistent behavior across all cluster operations. It performs validation before execution and uses a service layer to abstract the actual cluster discovery and display logic, supporting multiple Kubernetes providers and output formats for different use cases. \ No newline at end of file diff --git a/cmd/cluster/.status.md b/cmd/cluster/.status.md index 001b4df9..6a62b3d9 100644 --- a/cmd/cluster/.status.md +++ b/cmd/cluster/.status.md @@ -1,27 +1,25 @@ -Implements cluster status checking functionality for the OpenFrame CLI tool. Provides detailed information about Kubernetes cluster health, nodes, applications, and resource usage with interactive cluster selection. +This file implements the `status` command for the OpenFrame CLI's cluster management functionality, allowing users to view detailed information about Kubernetes cluster health, nodes, applications, and resource usage. ## Key Components -- **`getStatusCmd()`** - Creates and configures the cobra command for cluster status operations -- **`runClusterStatus()`** - Executes the status check operation with cluster selection and service layer integration +- **`getStatusCmd()`** - Creates and configures the Cobra command for cluster status operations with flags and validation +- **`runClusterStatus()`** - Executes the status command logic, handling cluster selection and displaying status information +- **Interactive cluster selection** - Uses the operations UI for user-friendly cluster selection when no cluster name is provided +- **Flag validation** - Validates status-specific flags before command execution +- **Service layer integration** - Delegates actual status retrieval to the cluster service ## Usage Example ```go -// Create status command +// Create the status command statusCmd := getStatusCmd() -// The command supports various usage patterns: -// openframe cluster status my-cluster -// openframe cluster status --detailed -// openframe cluster status # interactive selection - -// Command execution flow -err := runClusterStatus(cmd, []string{"my-cluster"}) -if err != nil { - log.Fatal(err) -} +// The command supports multiple usage patterns: +// openframe cluster status my-cluster # Show status for specific cluster +// openframe cluster status # Interactive cluster selection +// openframe cluster status my-cluster --detailed # Detailed status view +// openframe cluster status my-cluster --no-apps # Skip application status ``` -The command integrates with the global flag system for configuration management and uses an interactive UI for cluster selection when no specific cluster is provided. Status information includes cluster health, node status, installed applications, and resource usage details with optional verbose output control. \ No newline at end of file +The command integrates with the broader OpenFrame CLI architecture, using the common command setup wrapper for consistent error handling and the operations UI for interactive cluster selection. It supports optional detailed output and can exclude application status information based on user preferences. \ No newline at end of file diff --git a/cmd/dev/.dev.md b/cmd/dev/.dev.md index 5b7de9b8..95bfa477 100644 --- a/cmd/dev/.dev.md +++ b/cmd/dev/.dev.md @@ -1,25 +1,28 @@ -Development command orchestrator for local Kubernetes workflows, providing traffic interception and live reloading capabilities through Telepresence and Skaffold integration. +Provides development workflow commands for local Kubernetes development with traffic interception and live reloading capabilities. ## Key Components -- **GetDevCmd()** - Main command factory that creates the `dev` command with subcommands for local development workflows -- **PersistentPreRunE** - Prerequisite validation logic that checks requirements for intercept and skaffold operations -- **Subcommands** - Integrates `getInterceptCmd()` and `getScaffoldCmd()` for traffic routing and deployment workflows +- **`GetDevCmd()`** - Main function that creates and configures the `dev` command with its subcommands +- **Command Aliases** - Supports `d` as a shorthand alias for the dev command +- **Subcommands** - Integrates `intercept` and `skaffold` subcommands for development workflows +- **Prerequisites Check** - Validates required tools (Telepresence, Skaffold) before command execution +- **Global Flags** - Adds consistent global flags across all dev subcommands ## Usage Example ```go -// Get the complete dev command with all subcommands +// Get the dev command with all subcommands devCmd := GetDevCmd() -// The command supports these workflows: -// openframe dev intercept my-service // Route cluster traffic to local dev -// openframe dev skaffold my-service // Deploy with live reloading -// openframe dev // Show help and available options +// The command supports multiple workflows: +// openframe dev intercept my-service - Intercept cluster traffic locally +// openframe dev skaffold my-service - Deploy with live reloading +// openframe dev - Show help with available options -// Add to root command -rootCmd.AddCommand(devCmd) +// Prerequisites are automatically checked: +// - Telepresence installation for intercept command +// - Skaffold installation for skaffold command ``` -The command automatically validates prerequisites like Telepresence installation for intercept operations and Skaffold availability for deployment workflows. It includes global flags through the models package and provides contextual help with logo display. The command follows the CLI pattern of showing help when no subcommand is specified, making it discoverable for developers setting up local Kubernetes development environments. \ No newline at end of file +The command provides a unified entry point for local development workflows, automatically checking prerequisites and displaying the OpenFrame logo for better user experience. It integrates with Telepresence for traffic interception and Skaffold for continuous development deployments. \ No newline at end of file From 632ef04c319276bf1613eb56e85e657e32563122 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 28 May 2026 04:13:21 +0000 Subject: [PATCH 3/6] chore(docs): Remove 1 orphaned inline files [skip ci] --- .doc-pipeline-status.md | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 .doc-pipeline-status.md diff --git a/.doc-pipeline-status.md b/.doc-pipeline-status.md deleted file mode 100644 index 11512c98..00000000 --- a/.doc-pipeline-status.md +++ /dev/null @@ -1,5 +0,0 @@ -# Documentation Pipeline Started - -Run ID: doc-orchestrator-1779941493376 -Status: In Progress -Started: 2026-05-28 04:11:53 UTC From eddb2f9f290e424bc181926f6ad5c991f6662679 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 28 May 2026 04:13:54 +0000 Subject: [PATCH 4/6] docs: Stage 2 - Architecture analysis (5 files) [skip ci] --- docs/architecture/overview.md | 394 +++++++----------- docs/diagrams/architecture/README.md | 8 +- .../architecture/bootstrap-workflow.mmd | 21 + .../cluster-management-workflow.mmd | 18 + .../architecture/component-relationships.mmd | 41 ++ .../architecture/high-level-architecture.mmd | 30 ++ 6 files changed, 260 insertions(+), 252 deletions(-) create mode 100644 docs/diagrams/architecture/bootstrap-workflow.mmd create mode 100644 docs/diagrams/architecture/cluster-management-workflow.mmd create mode 100644 docs/diagrams/architecture/component-relationships.mmd create mode 100644 docs/diagrams/architecture/high-level-architecture.mmd diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 87ceae9f..5a7f54e1 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -2,320 +2,218 @@ # OpenFrame CLI Architecture Documentation -OpenFrame CLI is a modern, interactive command-line tool for managing OpenFrame Kubernetes clusters and development workflows, providing seamless cluster lifecycle management, chart installation with ArgoCD, and developer-friendly tools for service intercepts and scaffolding. +OpenFrame CLI is a comprehensive command-line interface for bootstrapping and managing Kubernetes clusters with ArgoCD for MSP (Managed Service Provider) environments. It provides streamlined workflows for creating development clusters, installing GitOps components, and managing development tools. ## Architecture -### High-Level System Design +The CLI follows a modular architecture with command-specific packages handling different aspects of cluster lifecycle management and development workflows. + +### High-Level Architecture ```mermaid graph TB - subgraph "CLI Layer" - Root[Root Command] - Bootstrap[Bootstrap Command] - Cluster[Cluster Commands] - Chart[Chart Commands] - Dev[Dev Commands] - end - - subgraph "Service Layer" - ClusterSvc[Cluster Service] - ChartSvc[Chart Service] - InterceptSvc[Intercept Service] - ScaffoldSvc[Scaffold Service] - end - - subgraph "Provider Layer" - K3D[K3D Provider] - Helm[Helm Provider] - ArgoCD[ArgoCD Provider] - Telepresence[Telepresence Provider] - Kubectl[Kubectl Provider] - end - - subgraph "External Systems" - Docker[Docker] - K8s[Kubernetes] - Git[Git Repositories] - Registry[Container Registry] + CLI[OpenFrame CLI] --> Bootstrap[Bootstrap Command] + CLI --> Cluster[Cluster Management] + CLI --> Chart[Chart Management] + CLI --> Dev[Development Tools] + + Bootstrap --> ClusterCreate[Cluster Creation] + Bootstrap --> ChartInstall[Chart Installation] + + Cluster --> Create[Create Clusters] + Cluster --> Delete[Delete Clusters] + Cluster --> List[List Clusters] + Cluster --> Status[Status Check] + Cluster --> Cleanup[Resource Cleanup] + + Chart --> ArgoCD[ArgoCD Installation] + Chart --> AppOfApps[App-of-Apps Setup] + + Dev --> Intercept[Traffic Interception] + Dev --> Skaffold[Live Development] + + subgraph Infrastructure[Infrastructure Layer] + K3d[K3d Clusters] + Kubernetes[Kubernetes API] + ArgoCD[ArgoCD GitOps] end - Root --> Bootstrap - Root --> Cluster - Root --> Chart - Root --> Dev - - Bootstrap --> ClusterSvc - Bootstrap --> ChartSvc - Cluster --> ClusterSvc - Chart --> ChartSvc - Dev --> InterceptSvc - Dev --> ScaffoldSvc - - ClusterSvc --> K3D - ChartSvc --> Helm - ChartSvc --> ArgoCD - InterceptSvc --> Telepresence - InterceptSvc --> Kubectl - ScaffoldSvc --> Kubectl - - K3D --> Docker - Helm --> K8s - ArgoCD --> K8s - ArgoCD --> Git - Telepresence --> K8s - Kubectl --> K8s + Create --> K3d + ArgoCD --> Kubernetes + Intercept --> Kubernetes ``` ## Core Components | Component | Package | Responsibility | -|-----------|---------|---------------| -| **CLI Commands** | `cmd/` | Command definitions and argument parsing using Cobra | -| **Cluster Service** | `internal/cluster/` | Kubernetes cluster lifecycle management (K3D) | -| **Chart Service** | `internal/chart/` | Helm chart and ArgoCD application management | -| **Dev Tools** | `internal/dev/` | Development workflows (Telepresence, Skaffold) | -| **Bootstrap Service** | `internal/bootstrap/` | Complete environment setup orchestration | -| **K3D Provider** | `internal/cluster/providers/k3d/` | K3D cluster operations and configuration | -| **Helm Provider** | `internal/chart/providers/helm/` | Helm chart installation and management | -| **ArgoCD Provider** | `internal/chart/providers/argocd/` | ArgoCD application lifecycle and monitoring | -| **Telepresence Provider** | `internal/dev/providers/telepresence/` | Traffic interception for local development | -| **Shared Utilities** | `internal/shared/` | Common functionality (UI, config, errors, execution) | -| **Prerequisites** | `internal/*/prerequisites/` | Tool installation and validation | +|-----------|---------|----------------| +| **Bootstrap** | `cmd/bootstrap` | Orchestrates complete OpenFrame environment setup | +| **Cluster Management** | `cmd/cluster` | Kubernetes cluster lifecycle operations | +| **Chart Management** | `cmd/chart` | Helm chart and ArgoCD installation | +| **Development Tools** | `cmd/dev` | Local development workflow tools | +| **Create Command** | `cmd/cluster/create.go` | Interactive cluster creation with configuration wizard | +| **Install Command** | `cmd/chart/install.go` | ArgoCD and app-of-apps installation | +| **Delete Command** | `cmd/cluster/delete.go` | Safe cluster deletion with resource cleanup | +| **Status Command** | `cmd/cluster/status.go` | Detailed cluster health and information display | ## Component Relationships -### Dependency Flow Between Modules - ```mermaid -graph TD - subgraph "Command Layer" - RootCmd[Root Command] - BootstrapCmd[Bootstrap Command] +graph LR + subgraph Commands[CLI Commands] + Bootstrap[Bootstrap] ClusterCmd[Cluster Commands] ChartCmd[Chart Commands] DevCmd[Dev Commands] end - subgraph "Service Orchestration" - BootstrapSvc[Bootstrap Service] - end - - subgraph "Domain Services" + subgraph Internal[Internal Services] ClusterSvc[Cluster Service] - ChartSvc[Chart Service] - InterceptSvc[Intercept Service] - ScaffoldSvc[Scaffold Service] - end - - subgraph "Provider Implementations" - K3DMgr[K3D Manager] - HelmMgr[Helm Manager] - ArgoCDMgr[ArgoCD Manager] - TelepresenceProv[Telepresence Provider] - KubectlProv[Kubectl Provider] - GitRepo[Git Repository] - end - - subgraph "Shared Infrastructure" - Executor[Command Executor] + ChartSvc[Chart Service] + DevSvc[Dev Service] UI[UI Components] - Config[Configuration] Prerequisites[Prerequisites] end - RootCmd --> BootstrapCmd - RootCmd --> ClusterCmd - RootCmd --> ChartCmd - RootCmd --> DevCmd + subgraph External[External Dependencies] + K3d[K3d CLI] + Helm[Helm CLI] + kubectl[kubectl] + ArgoCD[ArgoCD] + end + + Bootstrap --> ClusterSvc + Bootstrap --> ChartSvc - BootstrapCmd --> BootstrapSvc ClusterCmd --> ClusterSvc ChartCmd --> ChartSvc - DevCmd --> InterceptSvc - DevCmd --> ScaffoldSvc - - BootstrapSvc --> ClusterSvc - BootstrapSvc --> ChartSvc - - ClusterSvc --> K3DMgr - ChartSvc --> HelmMgr - ChartSvc --> ArgoCDMgr - ChartSvc --> GitRepo - InterceptSvc --> TelepresenceProv - InterceptSvc --> KubectlProv - ScaffoldSvc --> KubectlProv + DevCmd --> DevSvc - K3DMgr --> Executor - HelmMgr --> Executor - ArgoCDMgr --> Executor - TelepresenceProv --> Executor - KubectlProv --> Executor - GitRepo --> Executor + ClusterSvc --> K3d + ChartSvc --> Helm + ChartSvc --> kubectl ClusterSvc --> UI ChartSvc --> UI - InterceptSvc --> UI - ScaffoldSvc --> UI - - ClusterSvc --> Config - ChartSvc --> Config + DevSvc --> UI - ClusterSvc --> Prerequisites - ChartSvc --> Prerequisites + ClusterCmd --> Prerequisites + ChartCmd --> Prerequisites DevCmd --> Prerequisites ``` ## Data Flow -### Complete Bootstrap Workflow +### Bootstrap Workflow ```mermaid sequenceDiagram participant User - participant Bootstrap as Bootstrap Service - participant Cluster as Cluster Service - participant K3D as K3D Provider - participant Chart as Chart Service - participant Helm as Helm Provider - participant ArgoCD as ArgoCD Provider - participant K8s as Kubernetes API + participant Bootstrap + participant ClusterService + participant ChartService + participant K3d + participant ArgoCD User->>Bootstrap: openframe bootstrap - Bootstrap->>Bootstrap: Check prerequisites - Bootstrap->>Cluster: Create cluster - Cluster->>K3D: Create K3D cluster - K3D->>K8s: Initialize cluster - K8s-->>K3D: Cluster ready - K3D-->>Cluster: Cluster config - Cluster-->>Bootstrap: rest.Config - - Bootstrap->>Chart: Install charts - Chart->>Helm: Install ArgoCD - Helm->>K8s: Deploy ArgoCD - K8s-->>Helm: ArgoCD running - Helm-->>Chart: Installation complete - - Chart->>ArgoCD: Install app-of-apps - ArgoCD->>K8s: Create Application CRDs - K8s-->>ArgoCD: Applications created - ArgoCD->>ArgoCD: Sync applications - ArgoCD-->>Chart: Applications synced - Chart-->>Bootstrap: Charts installed - Bootstrap-->>User: Environment ready + Bootstrap->>Bootstrap: Show Logo + Bootstrap->>ClusterService: Create Cluster + ClusterService->>K3d: k3d cluster create + K3d-->>ClusterService: Cluster Ready + ClusterService-->>Bootstrap: Cluster Created + + Bootstrap->>ChartService: Install Charts + ChartService->>ChartService: Install ArgoCD + ChartService->>ArgoCD: Deploy App-of-Apps + ArgoCD-->>ChartService: Applications Synced + ChartService-->>Bootstrap: Installation Complete + Bootstrap-->>User: Environment Ready ``` -### Development Intercept Workflow +### Cluster Management Workflow ```mermaid sequenceDiagram - participant Dev as Developer - participant Intercept as Intercept Service - participant Kubectl as Kubectl Provider - participant Telepresence as Telepresence Provider - participant K8s as Kubernetes - participant Local as Local Development - - Dev->>Intercept: openframe dev intercept - Intercept->>Kubectl: Get services - Kubectl->>K8s: List services - K8s-->>Kubectl: Service list - Kubectl-->>Intercept: Available services - Intercept->>Dev: Select service/port - Dev->>Intercept: Service selection - - Intercept->>Telepresence: Setup intercept - Telepresence->>K8s: Create intercept - K8s->>Telepresence: Traffic routing active - Telepresence->>Local: Forward traffic - Local->>Dev: Local debugging - - Note over Dev,Local: Development session active - - Dev->>Intercept: Stop intercept (Ctrl+C) - Intercept->>Telepresence: Cleanup intercept - Telepresence->>K8s: Remove routing - K8s-->>Telepresence: Cleanup complete - Telepresence-->>Intercept: Disconnected - Intercept-->>Dev: Session ended + participant User + participant ClusterCmd + participant UI + participant Service + participant K3d + + User->>ClusterCmd: openframe cluster create + ClusterCmd->>UI: Show Logo + ClusterCmd->>UI: Get Configuration + UI->>User: Interactive Wizard + User-->>UI: Cluster Config + UI-->>ClusterCmd: Configuration + ClusterCmd->>Service: Create Cluster + Service->>K3d: Create with Config + K3d-->>Service: Cluster Ready + Service-->>ClusterCmd: Success + ClusterCmd-->>User: Cluster Created ``` ## Key Files | File | Purpose | |------|---------| -| `main.go` | Application entry point and version configuration | -| `cmd/root.go` | Root command definition and global flag management | -| `cmd/bootstrap/bootstrap.go` | Complete environment bootstrap command | -| `internal/cluster/service.go` | Core cluster management business logic | -| `internal/cluster/providers/k3d/manager.go` | K3D cluster provider implementation | -| `internal/chart/services/chart_service.go` | Chart installation orchestration | -| `internal/chart/providers/helm/manager.go` | Helm chart deployment logic | -| `internal/chart/providers/argocd/applications.go` | ArgoCD application management | -| `internal/dev/services/intercept/service.go` | Telepresence intercept workflow | -| `internal/shared/executor/executor.go` | Command execution abstraction with WSL support | -| `internal/shared/ui/logo.go` | Terminal UI and branding components | +| `cmd/bootstrap/bootstrap.go` | Main bootstrap command orchestrating complete setup | +| `cmd/cluster/create.go` | Interactive cluster creation with configuration wizard | +| `cmd/cluster/delete.go` | Safe cluster deletion with confirmation prompts | +| `cmd/chart/install.go` | ArgoCD and GitOps application installation | +| `cmd/cluster/list.go` | Display all managed clusters in formatted table | +| `cmd/cluster/status.go` | Detailed cluster health and resource information | +| `cmd/cluster/cleanup.go` | Remove unused Docker images and cluster resources | +| `cmd/dev/dev.go` | Development tools parent command with Telepresence integration | ## Dependencies -The project integrates with several external tools and libraries: +The CLI integrates with several external tools and internal packages: -### Core Kubernetes Libraries -- **client-go**: Native Kubernetes API access for cluster operations -- **apiextensions**: CRD management for ArgoCD applications -- **kubectl**: Command-line cluster interaction fallback +### External Tool Dependencies +- **K3d**: Lightweight Kubernetes clusters using Docker containers +- **Helm**: Package manager for Kubernetes applications +- **kubectl**: Kubernetes command-line tool for cluster interaction +- **ArgoCD**: GitOps continuous delivery tool for Kubernetes -### CLI Framework -- **cobra**: Command structure, argument parsing, and help generation -- **pterm**: Rich terminal UI components, spinners, and progress bars -- **promptui**: Interactive prompts and user input validation - -### External Tool Integration -- **K3D**: Lightweight Kubernetes cluster management -- **Helm**: Chart packaging and deployment via command execution -- **ArgoCD**: GitOps application lifecycle through API and CLI -- **Telepresence**: Service mesh traffic interception -- **Docker**: Container runtime for K3D clusters - -### Configuration and State -- **YAML**: Configuration file parsing for Helm values and cluster specs -- **JSON**: Structured data exchange with Kubernetes APIs -- **Home directory**: User configuration and certificate storage +### Internal Package Structure +- **Models**: Define configuration structures and validation rules +- **Services**: Business logic for cluster and chart operations +- **UI Components**: Interactive prompts and formatted output display +- **Prerequisites**: Tool availability and version checking +- **Utils**: Common utilities and command wrapping functions ## CLI Commands -### Core Commands - -| Command | Description | Example | -|---------|-------------|---------| -| `openframe bootstrap` | Complete environment setup (cluster + charts) | `openframe bootstrap my-cluster` | -| `openframe cluster create` | Create new Kubernetes cluster | `openframe cluster create --nodes 3` | -| `openframe cluster delete` | Remove existing cluster | `openframe cluster delete my-cluster` | -| `openframe cluster list` | Show all available clusters | `openframe cluster list` | -| `openframe cluster status` | Detailed cluster information | `openframe cluster status my-cluster` | -| `openframe chart install` | Install ArgoCD and applications | `openframe chart install` | -| `openframe dev intercept` | Start Telepresence traffic intercept | `openframe dev intercept my-service --port 8080` | -| `openframe dev skaffold` | Development workflow with hot reload | `openframe dev skaffold my-cluster` | - -### Command Options +### Bootstrap Commands +```bash +openframe bootstrap # Interactive mode +openframe bootstrap my-cluster # Custom cluster name +openframe bootstrap --deployment-mode=oss-tenant # Skip deployment selection +openframe bootstrap --verbose # Detailed logging +``` -**Global Flags:** -- `--verbose, -v`: Enable detailed logging and progress information -- `--dry-run`: Show planned operations without execution -- `--force, -f`: Skip confirmation prompts for automation +### Cluster Management Commands +```bash +openframe cluster create # Interactive cluster creation +openframe cluster delete my-cluster # Delete specific cluster +openframe cluster list # Show all clusters +openframe cluster status my-cluster # Detailed cluster status +openframe cluster cleanup my-cluster # Clean unused resources +``` -**Bootstrap Flags:** -- `--deployment-mode`: Pre-select deployment type (oss-tenant, saas-tenant, saas-shared) -- `--non-interactive`: Use existing configuration without prompts +### Chart Management Commands +```bash +openframe chart install # Interactive installation +openframe chart install my-cluster # Install on specific cluster +openframe chart install --deployment-mode=saas-shared # Skip deployment selection +openframe chart install --github-branch develop # Use develop branch +``` -**Cluster Creation Flags:** -- `--nodes, -n`: Number of worker nodes (default: 3) -- `--type, -t`: Cluster type (k3d, gke) -- `--version`: Kubernetes version -- `--skip-wizard`: Use defaults without interactive configuration +### Development Commands +```bash +openframe dev intercept my-service # Traffic interception +openframe dev skaffold my-service # Live development workflow +``` -**Development Flags:** -- `--port`: Local port for traffic forwarding -- `--namespace`: Kubernetes namespace for operations -- `--mount`: Mount remote volumes locally -- `--env-file`: Load environment variables from file +The CLI provides a unified interface for managing the complete OpenFrame development lifecycle, from initial cluster creation through application deployment and development workflows. diff --git a/docs/diagrams/architecture/README.md b/docs/diagrams/architecture/README.md index 7b3e892e..72aa808c 100644 --- a/docs/diagrams/architecture/README.md +++ b/docs/diagrams/architecture/README.md @@ -4,10 +4,10 @@ This directory contains Mermaid diagrams generated from architecture analysis. ## Diagrams -- **[High-Level System Design](./high-level-system-design.mmd)** - `.mmd` file -- **[Dependency Flow Between Modules](./dependency-flow-between-modules.mmd)** - `.mmd` file -- **[Complete Bootstrap Workflow](./complete-bootstrap-workflow.mmd)** - `.mmd` file -- **[Development Intercept Workflow](./development-intercept-workflow.mmd)** - `.mmd` file +- **[High-Level Architecture](./high-level-architecture.mmd)** - `.mmd` file +- **[Component Relationships](./component-relationships.mmd)** - `.mmd` file +- **[Bootstrap Workflow](./bootstrap-workflow.mmd)** - `.mmd` file +- **[Cluster Management Workflow](./cluster-management-workflow.mmd)** - `.mmd` file ## Viewing Diagrams diff --git a/docs/diagrams/architecture/bootstrap-workflow.mmd b/docs/diagrams/architecture/bootstrap-workflow.mmd new file mode 100644 index 00000000..dab764b2 --- /dev/null +++ b/docs/diagrams/architecture/bootstrap-workflow.mmd @@ -0,0 +1,21 @@ +sequenceDiagram + participant User + participant Bootstrap + participant ClusterService + participant ChartService + participant K3d + participant ArgoCD + + User->>Bootstrap: openframe bootstrap + Bootstrap->>Bootstrap: Show Logo + Bootstrap->>ClusterService: Create Cluster + ClusterService->>K3d: k3d cluster create + K3d-->>ClusterService: Cluster Ready + ClusterService-->>Bootstrap: Cluster Created + + Bootstrap->>ChartService: Install Charts + ChartService->>ChartService: Install ArgoCD + ChartService->>ArgoCD: Deploy App-of-Apps + ArgoCD-->>ChartService: Applications Synced + ChartService-->>Bootstrap: Installation Complete + Bootstrap-->>User: Environment Ready diff --git a/docs/diagrams/architecture/cluster-management-workflow.mmd b/docs/diagrams/architecture/cluster-management-workflow.mmd new file mode 100644 index 00000000..c71dd721 --- /dev/null +++ b/docs/diagrams/architecture/cluster-management-workflow.mmd @@ -0,0 +1,18 @@ +sequenceDiagram + participant User + participant ClusterCmd + participant UI + participant Service + participant K3d + + User->>ClusterCmd: openframe cluster create + ClusterCmd->>UI: Show Logo + ClusterCmd->>UI: Get Configuration + UI->>User: Interactive Wizard + User-->>UI: Cluster Config + UI-->>ClusterCmd: Configuration + ClusterCmd->>Service: Create Cluster + Service->>K3d: Create with Config + K3d-->>Service: Cluster Ready + Service-->>ClusterCmd: Success + ClusterCmd-->>User: Cluster Created diff --git a/docs/diagrams/architecture/component-relationships.mmd b/docs/diagrams/architecture/component-relationships.mmd new file mode 100644 index 00000000..6ff1ffba --- /dev/null +++ b/docs/diagrams/architecture/component-relationships.mmd @@ -0,0 +1,41 @@ +graph LR + subgraph Commands[CLI Commands] + Bootstrap[Bootstrap] + ClusterCmd[Cluster Commands] + ChartCmd[Chart Commands] + DevCmd[Dev Commands] + end + + subgraph Internal[Internal Services] + ClusterSvc[Cluster Service] + ChartSvc[Chart Service] + DevSvc[Dev Service] + UI[UI Components] + Prerequisites[Prerequisites] + end + + subgraph External[External Dependencies] + K3d[K3d CLI] + Helm[Helm CLI] + kubectl[kubectl] + ArgoCD[ArgoCD] + end + + Bootstrap --> ClusterSvc + Bootstrap --> ChartSvc + + ClusterCmd --> ClusterSvc + ChartCmd --> ChartSvc + DevCmd --> DevSvc + + ClusterSvc --> K3d + ChartSvc --> Helm + ChartSvc --> kubectl + + ClusterSvc --> UI + ChartSvc --> UI + DevSvc --> UI + + ClusterCmd --> Prerequisites + ChartCmd --> Prerequisites + DevCmd --> Prerequisites diff --git a/docs/diagrams/architecture/high-level-architecture.mmd b/docs/diagrams/architecture/high-level-architecture.mmd new file mode 100644 index 00000000..3cb0e294 --- /dev/null +++ b/docs/diagrams/architecture/high-level-architecture.mmd @@ -0,0 +1,30 @@ +graph TB + CLI[OpenFrame CLI] --> Bootstrap[Bootstrap Command] + CLI --> Cluster[Cluster Management] + CLI --> Chart[Chart Management] + CLI --> Dev[Development Tools] + + Bootstrap --> ClusterCreate[Cluster Creation] + Bootstrap --> ChartInstall[Chart Installation] + + Cluster --> Create[Create Clusters] + Cluster --> Delete[Delete Clusters] + Cluster --> List[List Clusters] + Cluster --> Status[Status Check] + Cluster --> Cleanup[Resource Cleanup] + + Chart --> ArgoCD[ArgoCD Installation] + Chart --> AppOfApps[App-of-Apps Setup] + + Dev --> Intercept[Traffic Interception] + Dev --> Skaffold[Live Development] + + subgraph Infrastructure[Infrastructure Layer] + K3d[K3d Clusters] + Kubernetes[Kubernetes API] + ArgoCD[ArgoCD GitOps] + end + + Create --> K3d + ArgoCD --> Kubernetes + Intercept --> Kubernetes From 63b918445cd789bb445562b24355beb0760299ee Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 28 May 2026 04:20:34 +0000 Subject: [PATCH 5/6] docs: Stage 3 - Tutorial generation (9 files) [skip ci] --- docs/development/README.md | 286 +++---- docs/development/architecture/README.md | 798 ++++++++------------ docs/development/security/README.md | 678 +++++++++++++++++ docs/development/setup/environment.md | 747 +++++++----------- docs/development/setup/local-development.md | 718 ++++++++---------- docs/getting-started/first-steps.md | 549 +++++--------- docs/getting-started/introduction.md | 183 ++--- docs/getting-started/prerequisites.md | 339 +++------ docs/getting-started/quick-start.md | 398 ++++------ 9 files changed, 2242 insertions(+), 2454 deletions(-) create mode 100644 docs/development/security/README.md diff --git a/docs/development/README.md b/docs/development/README.md index 8ef86fdf..062ff4d0 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -1,180 +1,180 @@ # Development Documentation -This section contains comprehensive guides for developing with and contributing to OpenFrame CLI. Whether you're setting up a development environment, understanding the architecture, or contributing code, these guides will help you get started. +Welcome to the OpenFrame CLI development documentation. This section provides comprehensive guides for developers working with, contributing to, or extending OpenFrame CLI. -## ๐Ÿ—๏ธ Architecture & Design +## Overview -Understanding how OpenFrame CLI is structured and how its components interact: +OpenFrame CLI is a Go-based command-line tool that orchestrates Kubernetes cluster management with GitOps automation. The development documentation covers everything from setting up your development environment to understanding the architecture and contributing guidelines. -- **[Architecture Overview](architecture/README.md)** - High-level system design, component relationships, and data flows +## Quick Navigation -## ๐Ÿ› ๏ธ Development Setup +### Setup and Environment +- **[Environment Setup](setup/environment.md)** - IDE, tools, and development environment configuration +- **[Local Development](setup/local-development.md)** - Clone, build, run, and debug locally -Get your development environment ready: +### Architecture and Design +- **[Architecture Overview](architecture/README.md)** - High-level system architecture and component relationships -- **[Environment Setup](setup/environment.md)** - IDE configuration, tools, and development dependencies -- **[Local Development](setup/local-development.md)** - Clone, build, run, and debug OpenFrame CLI locally +### Security +- **[Security Guidelines](security/README.md)** - Security best practices, authentication patterns, and vulnerability management -## ๐Ÿ”’ Security +### Testing +- **[Testing Overview](testing/README.md)** - Test structure, running tests, and writing new tests -Security best practices and guidelines: +### Contributing +- **[Contributing Guidelines](contributing/guidelines.md)** - Code style, PR process, and review checklist -- **[Security Guidelines](security/README.md)** - Authentication patterns, data protection, and vulnerability prevention +## Development Workflow -## ๐Ÿงช Testing +### Typical Development Process -Comprehensive testing approaches: +1. **Setup**: Configure your development environment +2. **Build**: Compile and test the CLI locally +3. **Develop**: Make changes following architecture patterns +4. **Test**: Run comprehensive tests before committing +5. **Security**: Follow security best practices +6. **Contribute**: Submit PRs following contribution guidelines -- **[Testing Guide](testing/README.md)** - Test structure, running tests, writing new tests, and coverage requirements +### Development Commands -## ๐Ÿค Contributing +```bash +# Build the CLI +go build -o openframe ./main.go -Guidelines for contributing to the project: +# Run tests +go test ./... -- **[Contributing Guidelines](contributing/guidelines.md)** - Code standards, review process, and submission guidelines +# Run with race detection +go test -race ./... -## Quick Navigation +# Build for multiple platforms +make build-all -### New Contributors -If you're new to OpenFrame CLI development, start here: -1. [Architecture Overview](architecture/README.md) - Understand the system -2. [Environment Setup](setup/environment.md) - Configure your tools -3. [Local Development](setup/local-development.md) - Get the code running -4. [Contributing Guidelines](contributing/guidelines.md) - Learn the process - -### Experienced Developers -Jump to specific areas: -- **Architecture**: Deep dive into design patterns and component interactions -- **Security**: Review security models and best practices -- **Testing**: Understand test patterns and coverage expectations - -### Operations & DevOps -Focus on deployment and operational aspects: -- **Architecture**: Service dependencies and operational considerations -- **Security**: Production security requirements and configurations -- **Testing**: Integration and end-to-end testing strategies - -## Development Workflow Overview - -```mermaid -flowchart TD - A[Fork Repository] --> B[Setup Dev Environment] - B --> C[Create Feature Branch] - C --> D[Write Code & Tests] - D --> E[Run Local Tests] - E --> F{Tests Pass?} - F -->|No| D - F -->|Yes| G[Commit Changes] - G --> H[Push to Fork] - H --> I[Create Pull Request] - I --> J[Code Review] - J --> K{Review Approved?} - K -->|No| D - K -->|Yes| L[Merge to Main] - L --> M[CI/CD Pipeline] - M --> N[Deploy & Test] +# Run linting +golangci-lint run ``` -## Key Technologies +## Technology Stack -OpenFrame CLI is built with: +OpenFrame CLI is built using: -| Technology | Purpose | Version | -|------------|---------|---------| -| **Go** | Primary language | 1.24.6+ | -| **Cobra** | CLI framework | v1.8.1+ | -| **Kubernetes** | Container orchestration | v1.31.2+ | -| **K3D** | Local Kubernetes clusters | v5.0+ | -| **Helm** | Package management | v3.10+ | -| **ArgoCD** | GitOps deployments | v2.14+ | -| **Telepresence** | Service intercepts | v2.10+ | +| Component | Technology | Purpose | +|-----------|------------|---------| +| **Core Language** | Go 1.21+ | CLI implementation and business logic | +| **CLI Framework** | Cobra | Command structure and argument parsing | +| **Container Runtime** | Docker | K3d cluster management | +| **Kubernetes** | K3d, kubectl | Local cluster creation and management | +| **GitOps** | ArgoCD, Helm | Application deployment and management | +| **Development Tools** | Telepresence, Skaffold | Traffic interception and live development | -## Project Structure +## Architecture Highlights +### Command Structure ```text -openframe-cli/ -โ”œโ”€โ”€ cmd/ # CLI command definitions -โ”‚ โ”œโ”€โ”€ bootstrap/ # Bootstrap command -โ”‚ โ”œโ”€โ”€ cluster/ # Cluster management commands -โ”‚ โ”œโ”€โ”€ chart/ # Chart installation commands -โ”‚ โ”œโ”€โ”€ dev/ # Development workflow commands -โ”‚ โ””โ”€โ”€ root.go # Root command setup -โ”œโ”€โ”€ internal/ # Internal packages -โ”‚ โ”œโ”€โ”€ bootstrap/ # Bootstrap orchestration -โ”‚ โ”œโ”€โ”€ cluster/ # Cluster lifecycle management -โ”‚ โ”œโ”€โ”€ chart/ # Chart and ArgoCD integration -โ”‚ โ”œโ”€โ”€ dev/ # Development tools -โ”‚ โ””โ”€โ”€ shared/ # Common utilities -โ”œโ”€โ”€ tests/ # Test suites -โ”‚ โ”œโ”€โ”€ integration/ # Integration tests -โ”‚ โ”œโ”€โ”€ mocks/ # Test mocks -โ”‚ โ””โ”€โ”€ testutil/ # Test utilities -โ”œโ”€โ”€ docs/ # Documentation -โ”œโ”€โ”€ examples/ # Usage examples -โ”œโ”€โ”€ scripts/ # Build and utility scripts -โ”œโ”€โ”€ go.mod # Go module definition -โ”œโ”€โ”€ go.sum # Go dependency checksums -โ””โ”€โ”€ main.go # Application entry point +openframe +โ”œโ”€โ”€ bootstrap/ # Complete environment setup +โ”œโ”€โ”€ cluster/ # Cluster lifecycle management +โ”‚ โ”œโ”€โ”€ create # Interactive cluster creation +โ”‚ โ”œโ”€โ”€ delete # Safe cluster removal +โ”‚ โ”œโ”€โ”€ list # Display managed clusters +โ”‚ โ”œโ”€โ”€ status # Cluster health monitoring +โ”‚ โ””โ”€โ”€ cleanup # Resource cleanup +โ”œโ”€โ”€ chart/ # Helm chart and ArgoCD management +โ”‚ โ””โ”€โ”€ install # ArgoCD installation +โ””โ”€โ”€ dev/ # Development workflow tools + โ”œโ”€โ”€ intercept # Traffic interception + โ””โ”€โ”€ skaffold # Live development ``` -## Development Principles +### Key Design Principles -### Code Quality -- **Clean Architecture**: Clear separation of concerns with layered design -- **Testability**: All components designed for easy testing and mocking -- **Error Handling**: Comprehensive error handling with user-friendly messages -- **Documentation**: Code is self-documenting with clear comments +- **Modularity**: Each command is self-contained with clear responsibilities +- **User Experience**: Interactive wizards and helpful error messages +- **Safety**: Confirmation prompts and safe defaults +- **Extensibility**: Plugin-friendly architecture for custom workflows +- **GitOps Native**: Built-in ArgoCD integration and app-of-apps pattern -### User Experience -- **Interactive Design**: Wizard-style interfaces for complex operations -- **Clear Feedback**: Progress indicators and status messages -- **Error Recovery**: Helpful error messages with suggested solutions -- **Consistency**: Uniform command patterns and flag usage +## Development Environment -### Operational Excellence -- **Observability**: Comprehensive logging and monitoring capabilities -- **Reliability**: Robust error handling and recovery mechanisms -- **Performance**: Efficient resource usage and fast execution -- **Security**: Secure defaults and best practices +### Recommended Tools -## Getting Started +- **IDE**: VS Code with Go extension, GoLand +- **Go Version**: 1.21 or later +- **Docker**: Latest stable version +- **Git**: Latest version with SSH key setup +- **Make**: For build automation -### Prerequisites -Before diving into development, ensure you have: -- Go 1.24.6 or later installed -- Docker and Kubernetes tools (kubectl, helm, k3d) -- Git and a code editor/IDE -- Basic familiarity with Kubernetes concepts +### Environment Variables -### Quick Start -1. **Read the [Architecture Overview](architecture/README.md)** to understand the system -2. **Follow the [Environment Setup](setup/environment.md)** guide -3. **Complete the [Local Development](setup/local-development.md)** setup -4. **Review [Contributing Guidelines](contributing/guidelines.md)** before making changes +```bash +# Go development +export GOPATH=$HOME/go +export PATH=$GOPATH/bin:$PATH -## Community & Support +# OpenFrame development +export OPENFRAME_DEV_MODE=true +export OPENFRAME_LOG_LEVEL=debug -### Getting Help -- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) for development questions -- **Documentation**: Browse these guides for detailed information -- **Code Reviews**: Learn from existing pull requests and code reviews +# Kubernetes development +export KUBECONFIG=$HOME/.kube/config +``` -### Contributing -We welcome contributions! Here's how to get involved: -1. **Start Small**: Begin with bug fixes or documentation improvements -2. **Discuss Large Changes**: Use Slack to discuss major features or architectural changes -3. **Follow Guidelines**: Adhere to coding standards and review processes -4. **Be Patient**: Maintain a collaborative and respectful approach - -### Code of Conduct -- Be respectful and inclusive in all interactions -- Focus on constructive feedback and learning -- Help others learn and grow in the community -- Follow the project's established patterns and conventions - ---- - -Ready to start developing? Choose your path: -- **New to the project**: Start with [Architecture Overview](architecture/README.md) -- **Ready to code**: Jump to [Local Development](setup/local-development.md) -- **Want to contribute**: Review [Contributing Guidelines](contributing/guidelines.md) \ No newline at end of file +## Contributing Areas + +We welcome contributions in these areas: + +### Core Features +- New command implementations +- Enhanced interactive wizards +- Improved error handling and messaging +- Performance optimizations + +### Platform Support +- Additional deployment modes +- Cloud provider integrations +- Windows compatibility improvements +- macOS Apple Silicon optimizations + +### Development Experience +- Enhanced debugging capabilities +- Better logging and observability +- Developer productivity tools +- Documentation improvements + +### Testing and Quality +- Unit test coverage improvements +- Integration test scenarios +- Performance benchmarks +- Security testing automation + +## Getting Started with Development + +1. **Read the setup guides** to configure your environment +2. **Explore the architecture** to understand the system design +3. **Review security guidelines** before making changes +4. **Check the testing approach** for quality standards +5. **Follow contributing guidelines** for smooth collaboration + +## Code Quality Standards + +- **Test Coverage**: Minimum 80% for new code +- **Linting**: All code must pass `golangci-lint` +- **Documentation**: Public APIs must have Go doc comments +- **Security**: Follow OWASP guidelines and security best practices +- **Performance**: Benchmark critical paths and avoid regressions + +## Resources + +### External Documentation +- [Go Documentation](https://golang.org/doc/) +- [Cobra CLI Framework](https://cobra.dev/) +- [K3d Documentation](https://k3d.io/) +- [ArgoCD Documentation](https://argo-cd.readthedocs.io/) +- [Kubernetes Documentation](https://kubernetes.io/docs/) + +### Community +- **OpenMSP Slack**: [Join here](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) +- **GitHub Discussions**: Use for feature requests and architectural discussions +- **GitHub Issues**: For bug reports and specific improvements + +> ๐Ÿ’ก **New to the codebase?** Start with the [Environment Setup](setup/environment.md) guide, then explore the [Architecture Overview](architecture/README.md) to understand how everything fits together. \ No newline at end of file diff --git a/docs/development/architecture/README.md b/docs/development/architecture/README.md index c42f299d..62a3e4e9 100644 --- a/docs/development/architecture/README.md +++ b/docs/development/architecture/README.md @@ -1,574 +1,432 @@ # Architecture Overview -OpenFrame CLI is built with a clean, layered architecture that separates concerns and provides extensibility. This guide provides a comprehensive overview of the system design, component relationships, and key architectural decisions. +This document provides a comprehensive overview of OpenFrame CLI's architecture, design patterns, and component relationships. ## High-Level Architecture -OpenFrame CLI follows a layered architecture pattern with clear separation between the CLI interface, business logic, and external integrations: +OpenFrame CLI follows a modular, command-driven architecture that orchestrates Kubernetes cluster lifecycle management with integrated GitOps workflows. ```mermaid graph TB - subgraph "User Interface Layer" - CLI[CLI Commands] - UI[Interactive UI] - Wizard[Setup Wizards] + subgraph User Interface + CLI[OpenFrame CLI] + Wizard[Interactive Wizards] + UI[UI Components] end - subgraph "Application Layer" - Bootstrap[Bootstrap Orchestrator] - ClusterMgr[Cluster Manager] - ChartMgr[Chart Manager] - DevTools[Development Tools] + subgraph Command Layer + Bootstrap[Bootstrap Command] + Cluster[Cluster Commands] + Chart[Chart Commands] + Dev[Dev Commands] end - subgraph "Provider Layer" - K3DProvider[K3D Provider] - HelmProvider[Helm Provider] - ArgoCDProvider[ArgoCD Provider] - TelepresenceProvider[Telepresence Provider] - KubectlProvider[kubectl Provider] - GitProvider[Git Provider] + subgraph Service Layer + BootstrapSvc[Bootstrap Service] + ClusterSvc[Cluster Service] + ChartSvc[Chart Service] + DevSvc[Dev Service] end - subgraph "Infrastructure Layer" - Executor[Command Executor] - Config[Configuration] - Logger[Logging] - ErrorHandler[Error Handling] - FileSystem[File Operations] - end - - subgraph "External Systems" - Docker[Docker Engine] - K8s[Kubernetes API] - Git[Git Repositories] - Registry[Container Registry] - ArgoCD[ArgoCD Server] + subgraph External Integrations + K3d[K3d Clusters] + ArgoCD[ArgoCD GitOps] + Helm[Helm Charts] + Docker[Docker Runtime] + Telepresence[Telepresence] + Skaffold[Skaffold] end + CLI --> Wizard CLI --> Bootstrap - CLI --> ClusterMgr - CLI --> ChartMgr - CLI --> DevTools + CLI --> Cluster + CLI --> Chart + CLI --> Dev + + Bootstrap --> BootstrapSvc + Cluster --> ClusterSvc + Chart --> ChartSvc + Dev --> DevSvc - Bootstrap --> ClusterMgr - Bootstrap --> ChartMgr - ClusterMgr --> K3DProvider - ChartMgr --> HelmProvider - ChartMgr --> ArgoCDProvider - DevTools --> TelepresenceProvider - DevTools --> KubectlProvider + BootstrapSvc --> ClusterSvc + BootstrapSvc --> ChartSvc - K3DProvider --> Executor - HelmProvider --> Executor - ArgoCDProvider --> Executor - TelepresenceProvider --> Executor - KubectlProvider --> Executor - GitProvider --> Executor + ClusterSvc --> K3d + ClusterSvc --> Docker + ChartSvc --> Helm + ChartSvc --> ArgoCD + DevSvc --> Telepresence + DevSvc --> Skaffold - K3DProvider --> Docker - HelmProvider --> K8s - ArgoCDProvider --> ArgoCD - TelepresenceProvider --> K8s - KubectlProvider --> K8s - GitProvider --> Git + UI --> Wizard ``` ## Core Components -### Command Layer (`cmd/`) - -The command layer implements the CLI interface using the Cobra framework: +| Component | Package | Responsibility | Dependencies | +|-----------|---------|----------------|--------------| +| **Bootstrap Service** | `internal/bootstrap` | Orchestrates complete environment setup | Cluster Service, Chart Service | +| **Cluster Service** | `internal/cluster` | Kubernetes cluster lifecycle management | K3d, Docker, kubectl | +| **Chart Service** | `internal/chart` | Helm chart and ArgoCD installation | Helm, ArgoCD, kubectl | +| **Development Service** | `internal/dev` | Local development workflow tools | Telepresence, Skaffold | +| **UI Components** | `internal/ui` | Interactive prompts and formatted output | Cobra, Survey | +| **Prerequisites** | `internal/prerequisites` | Tool availability and version checking | External tool binaries | -| Component | Purpose | Key Features | -|-----------|---------|--------------| -| **Root Command** | Entry point and version management | Interactive help, global flags, subcommand routing | -| **Bootstrap Command** | Complete environment setup | Orchestrates cluster + chart installation | -| **Cluster Commands** | Kubernetes cluster lifecycle | Create, delete, list, status operations | -| **Chart Commands** | Application deployment | Helm charts, ArgoCD applications | -| **Dev Commands** | Development workflows | Service intercepts, scaffolding | +## Command Structure and Flow -### Service Layer (`internal/`) - -The service layer contains the core business logic: - -#### Bootstrap Service (`internal/bootstrap/`) -- **Purpose**: Orchestrates complete environment setup -- **Key Functions**: - - Validates prerequisites - - Creates Kubernetes clusters - - Installs core charts (ArgoCD, Traefik) - - Configures GitOps workflows +### Bootstrap Workflow ```mermaid sequenceDiagram participant User participant Bootstrap - participant Cluster - participant Chart + participant ClusterService + participant ChartService + participant K3d participant ArgoCD User->>Bootstrap: openframe bootstrap - Bootstrap->>Bootstrap: Check prerequisites - Bootstrap->>Cluster: Create K3D cluster - Cluster-->>Bootstrap: Cluster ready - Bootstrap->>Chart: Install ArgoCD - Chart-->>Bootstrap: ArgoCD installed - Bootstrap->>ArgoCD: Deploy app-of-apps - ArgoCD-->>Bootstrap: Applications synced - Bootstrap-->>User: Environment ready + Bootstrap->>Bootstrap: Show Logo & Prerequisites + Bootstrap->>ClusterService: Create Cluster + + ClusterService->>K3d: k3d cluster create + K3d-->>ClusterService: Cluster Ready + ClusterService-->>Bootstrap: Cluster Created + + Bootstrap->>ChartService: Install Charts + ChartService->>ChartService: Install ArgoCD + ChartService->>ArgoCD: Deploy App-of-Apps + ArgoCD-->>ChartService: Applications Synced + ChartService-->>Bootstrap: Installation Complete + + Bootstrap-->>User: Environment Ready ``` -#### Cluster Service (`internal/cluster/`) -- **Purpose**: Manages Kubernetes cluster lifecycle -- **Key Functions**: - - K3D cluster creation and deletion - - Cluster status monitoring - - Node management and scaling - - Configuration and context management - -#### Chart Service (`internal/chart/`) -- **Purpose**: Manages application deployments -- **Key Functions**: - - Helm chart installation - - ArgoCD application management - - GitOps workflow configuration - - Application synchronization monitoring - -#### Development Services (`internal/dev/`) -- **Purpose**: Provides development workflow tools -- **Key Functions**: - - Service intercepts with Telepresence - - Code scaffolding and templates - - Local development environment setup - - Debug and testing utilities - -### Provider Layer - -The provider layer abstracts external tool integrations: - -#### K3D Provider (`internal/cluster/providers/k3d/`) -```go -type Manager interface { - CreateCluster(config ClusterConfig) (*rest.Config, error) - DeleteCluster(name string) error - ListClusters() ([]ClusterInfo, error) - GetClusterStatus(name string) (*ClusterStatus, error) -} +### Cluster Management Workflow + +```mermaid +sequenceDiagram + participant User + participant ClusterCmd + participant UI + participant ClusterService + participant K3d + + User->>ClusterCmd: openframe cluster create + ClusterCmd->>UI: Show Logo + ClusterCmd->>UI: Get Configuration + UI->>User: Interactive Wizard + User-->>UI: Cluster Config + UI-->>ClusterCmd: Configuration + ClusterCmd->>ClusterService: Create Cluster + ClusterService->>K3d: Create with Config + K3d-->>ClusterService: Cluster Ready + ClusterService-->>ClusterCmd: Success + ClusterCmd-->>User: Cluster Created ``` -Key responsibilities: -- Docker container management for K3D nodes -- Kubernetes API server configuration -- Network and port forwarding setup -- Cluster lifecycle management +## Data Flow and Dependencies -#### Helm Provider (`internal/chart/providers/helm/`) -```go -type Manager interface { - InstallChart(release string, chart string, values map[string]interface{}) error - UpgradeChart(release string, chart string, values map[string]interface{}) error - UninstallChart(release string) error - ListReleases() ([]Release, error) -} +### Component Relationships + +```mermaid +graph LR + subgraph Commands[CLI Commands] + BootstrapCmd[Bootstrap] + ClusterCmd[Cluster Commands] + ChartCmd[Chart Commands] + DevCmd[Dev Commands] + end + + subgraph Services[Internal Services] + BootstrapSvc[Bootstrap Service] + ClusterSvc[Cluster Service] + ChartSvc[Chart Service] + DevSvc[Dev Service] + UI[UI Components] + Prerequisites[Prerequisites] + end + + subgraph External[External Dependencies] + K3d[K3d CLI] + Helm[Helm CLI] + kubectl[kubectl] + ArgoCD[ArgoCD] + Docker[Docker Engine] + Telepresence[Telepresence] + Skaffold[Skaffold] + end + + BootstrapCmd --> BootstrapSvc + ClusterCmd --> ClusterSvc + ChartCmd --> ChartSvc + DevCmd --> DevSvc + + BootstrapSvc --> ClusterSvc + BootstrapSvc --> ChartSvc + + ClusterSvc --> K3d + ClusterSvc --> Docker + ChartSvc --> Helm + ChartSvc --> kubectl + ChartSvc --> ArgoCD + DevSvc --> Telepresence + DevSvc --> Skaffold + + ClusterSvc --> UI + ChartSvc --> UI + DevSvc --> UI + + ClusterCmd --> Prerequisites + ChartCmd --> Prerequisites + DevCmd --> Prerequisites ``` -Key responsibilities: -- Helm repository management -- Chart installation and upgrades -- Release lifecycle management -- Value overrides and templating +## Key Design Patterns + +### 1. Command Pattern + +Each CLI command is implemented as a separate package with a consistent interface: -#### ArgoCD Provider (`internal/chart/providers/argocd/`) ```go -type Manager interface { - CreateApplication(app ApplicationSpec) error - SyncApplication(name string) error - DeleteApplication(name string) error - WaitForSync(name string, timeout time.Duration) error +// Command interface pattern +type Command interface { + Execute(cmd *cobra.Command, args []string) error +} + +// Service interface pattern +type Service interface { + Execute(cmd *cobra.Command, args []string) error + Validate() error + Prerequisites() error } ``` -Key responsibilities: -- ArgoCD application CRD management -- Git repository synchronization -- Application health monitoring -- Sync policy configuration - -### Shared Infrastructure (`internal/shared/`) - -Common utilities and cross-cutting concerns: - -#### Command Executor (`internal/shared/executor/`) -- **Purpose**: Standardized external command execution -- **Features**: - - Command building and execution - - Output capture and streaming - - Error handling and retry logic - - Timeout management - - Mock support for testing - -#### Configuration Management (`internal/shared/config/`) -- **Purpose**: Application configuration and settings -- **Features**: - - YAML/JSON configuration files - - Environment variable overrides - - Default value management - - Validation and type safety - -#### User Interface (`internal/shared/ui/`) -- **Purpose**: Consistent user interaction patterns -- **Features**: - - Interactive prompts and wizards - - Progress indicators and spinners - - Colored output and formatting - - Table rendering and alignment - - Error message presentation - -## Data Flow Architecture +### 2. Service Layer Pattern -### Bootstrap Workflow +Business logic is separated from command handling: -The bootstrap process follows a carefully orchestrated sequence: +- **Commands** (`cmd/`) handle CLI parsing and user interaction +- **Services** (`internal/`) contain business logic and orchestration +- **External integrations** are abstracted through service interfaces -```mermaid -flowchart TD - A[Start Bootstrap] --> B[Check Prerequisites] - B --> C{Prerequisites OK?} - C -->|No| D[Install Missing Tools] - C -->|Yes| E[Validate Configuration] - D --> E - E --> F[Create K3D Cluster] - F --> G[Wait for Cluster Ready] - G --> H[Install ArgoCD] - H --> I[Configure Git Repositories] - I --> J[Deploy App-of-Apps] - J --> K[Wait for Application Sync] - K --> L{All Apps Healthy?} - L -->|No| M[Troubleshoot & Retry] - L -->|Yes| N[Bootstrap Complete] - M --> K -``` +### 3. Dependency Injection -### Service Interaction Patterns +Services receive their dependencies through constructors: -Services interact through well-defined interfaces: +```go +type BootstrapService struct { + clusterService ClusterService + chartService ChartService + ui UIComponents +} -```mermaid -classDiagram - class BootstrapService { - +Execute(config BootstrapConfig) error - -validatePrerequisites() error - -createCluster() error - -installCharts() error +func NewBootstrapService(cluster ClusterService, chart ChartService, ui UIComponents) *BootstrapService { + return &BootstrapService{ + clusterService: cluster, + chartService: chart, + ui: ui, } - - class ClusterService { - +Create(name string) error - +Delete(name string) error - +Status(name string) ClusterStatus - +List() []ClusterInfo - } - - class ChartService { - +Install(chart ChartSpec) error - +List() []ChartInfo - +Sync(name string) error - +WaitForReady(name string) error - } - - BootstrapService --> ClusterService - BootstrapService --> ChartService - ChartService --> ArgocdProvider - ClusterService --> K3dProvider +} ``` -## Key Design Decisions +### 4. Configuration Management -### 1. Layered Architecture +Configuration is managed through structured types with validation: -**Decision**: Implement strict layering with dependency injection -**Rationale**: -- Clear separation of concerns -- Easier testing through interface mocking -- Flexibility to swap implementations -- Maintainable and extensible codebase - -### 2. Provider Pattern +```go +type ClusterConfig struct { + Name string `yaml:"name" validate:"required"` + NodeCount int `yaml:"nodeCount" validate:"min=1,max=10"` + Resources ResourceLimits `yaml:"resources"` + Network NetworkConfig `yaml:"network"` + AddOns []string `yaml:"addOns"` +} +``` -**Decision**: Abstract external tools behind provider interfaces -**Rationale**: -- Support multiple Kubernetes distributions (K3D, Kind, etc.) -- Enable testing without external dependencies -- Simplify adding new tool integrations -- Consistent error handling and logging +## Directory Structure and Responsibilities -### 3. Command Executor Abstraction +### Command Layer (`cmd/`) -**Decision**: Centralize external command execution -**Rationale**: -- Consistent error handling across all external calls -- Unified logging and debugging capabilities -- Simplified testing with command mocking -- Retry logic and timeout management +```text +cmd/ +โ”œโ”€โ”€ bootstrap/ # Complete environment setup +โ”‚ โ””โ”€โ”€ bootstrap.go # Cobra command definition +โ”œโ”€โ”€ cluster/ # Cluster lifecycle management +โ”‚ โ”œโ”€โ”€ cluster.go # Root cluster command +โ”‚ โ”œโ”€โ”€ create.go # Interactive cluster creation +โ”‚ โ”œโ”€โ”€ delete.go # Safe cluster deletion +โ”‚ โ”œโ”€โ”€ list.go # Display managed clusters +โ”‚ โ”œโ”€โ”€ status.go # Cluster health monitoring +โ”‚ โ””โ”€โ”€ cleanup.go # Resource cleanup +โ”œโ”€โ”€ chart/ # Helm chart and ArgoCD management +โ”‚ โ”œโ”€โ”€ chart.go # Root chart command +โ”‚ โ””โ”€โ”€ install.go # ArgoCD installation +โ””โ”€โ”€ dev/ # Development workflow tools + โ””โ”€โ”€ dev.go # Development tools parent command +``` -### 4. Interactive CLI Design +### Service Layer (`internal/`) -**Decision**: Provide both interactive and non-interactive modes -**Rationale**: -- User-friendly for manual operations -- Scriptable for automation and CI/CD -- Progressive disclosure of complexity -- Clear error messages and guidance +```text +internal/ +โ”œโ”€โ”€ bootstrap/ # Bootstrap orchestration logic +โ”œโ”€โ”€ cluster/ # Cluster management services +โ”œโ”€โ”€ chart/ # Chart installation services +โ”œโ”€โ”€ dev/ # Development workflow services +โ”œโ”€โ”€ ui/ # User interface components +โ”œโ”€โ”€ utils/ # Shared utilities +โ””โ”€โ”€ models/ # Data structures and validation +``` -### 5. GitOps-First Approach +### Public Packages (`pkg/`) -**Decision**: Default to GitOps workflows with ArgoCD -**Rationale**: -- Industry best practices for Kubernetes deployments -- Declarative infrastructure management -- Audit trails and rollback capabilities -- Team collaboration through Git workflows +```text +pkg/ +โ”œโ”€โ”€ config/ # Configuration management +โ”œโ”€โ”€ k3d/ # K3d integration +โ”œโ”€โ”€ helm/ # Helm integration +โ””โ”€โ”€ argocd/ # ArgoCD integration +``` ## Error Handling Strategy -### Error Types and Handling +### Layered Error Handling -```mermaid -graph TD - A[Error Occurs] --> B{Error Type?} - B -->|Validation Error| C[Show Usage Help] - B -->|External Tool Error| D[Parse Tool Output] - B -->|Network Error| E[Suggest Connectivity Check] - B -->|Resource Error| F[Check Resource Availability] - - C --> G[Exit with Code 1] - D --> H{Recoverable?} - E --> H - F --> H - - H -->|Yes| I[Retry with Backoff] - H -->|No| J[Show Error + Solutions] +```go +// Domain errors +type ClusterError struct { + Operation string + Cluster string + Cause error +} + +// Service errors wrap domain errors +func (s *ClusterService) CreateCluster(config ClusterConfig) error { + if err := s.validateConfig(config); err != nil { + return fmt.Errorf("cluster configuration invalid: %w", err) + } - I --> K{Max Retries?} - K -->|No| A - K -->|Yes| J + if err := s.k3d.CreateCluster(config); err != nil { + return &ClusterError{ + Operation: "create", + Cluster: config.Name, + Cause: err, + } + } - J --> G -``` + return nil +} -### Error Categories - -| Category | Examples | Handling Strategy | -|----------|----------|------------------| -| **User Input** | Invalid flags, missing config | Show usage help, suggest corrections | -| **Prerequisites** | Missing tools, permissions | Guide installation, check prerequisites | -| **Network** | Connection timeouts, DNS issues | Retry with backoff, check connectivity | -| **Resource** | Insufficient memory, disk space | Check resources, suggest alternatives | -| **External Tools** | kubectl errors, helm failures | Parse tool output, provide context | - -## Configuration Architecture - -### Configuration Sources (Priority Order) - -1. **Command-line flags** - Highest priority -2. **Environment variables** - Override config files -3. **Configuration files** - User and system configs -4. **Default values** - Built-in sensible defaults - -### Configuration Structure - -```yaml -# ~/.openframe/config.yaml -openframe: - log_level: "info" - config_dir: "~/.openframe" - -cluster: - provider: "k3d" - default_name: "openframe-local" - nodes: 1 - -bootstrap: - mode: "oss-tenant" - timeout: "15m" - interactive: true - -chart: - timeout: "10m" - wait_for_ready: true - -dev: - intercept_timeout: "5m" - scaffold_template_dir: "~/.openframe/templates" +// Commands handle service errors +func (cmd *CreateCommand) Execute(args []string) error { + if err := cmd.service.CreateCluster(config); err != nil { + var clusterErr *ClusterError + if errors.As(err, &clusterErr) { + return fmt.Errorf("failed to %s cluster %s: %w", + clusterErr.Operation, clusterErr.Cluster, clusterErr.Cause) + } + return err + } + return nil +} ``` -## Testing Architecture +## Concurrency and Performance -### Test Strategy +### Concurrent Operations -```mermaid -graph TB - subgraph "Unit Tests" - A[Service Logic Tests] - B[Provider Tests with Mocks] - C[Utility Function Tests] - end - - subgraph "Integration Tests" - D[End-to-End Command Tests] - E[Provider Integration Tests] - F[External Tool Integration] - end - - subgraph "Acceptance Tests" - G[Complete Bootstrap Workflow] - H[Multi-Cluster Scenarios] - I[Development Workflow Tests] - end - - A --> D - B --> E - C --> F - D --> G - E --> H - F --> I -``` - -### Mock Strategy - -- **External Commands**: Mock command executor for tool interactions -- **Kubernetes API**: Use fake clientsets for API testing -- **File System**: Mock file operations for config testing -- **Network**: Mock HTTP clients for external service calls +- **Parallel Installation**: ArgoCD and applications install concurrently +- **Resource Monitoring**: Background monitoring of cluster health +- **Cleanup Operations**: Concurrent cleanup of multiple resources -## Security Architecture +### Performance Optimizations -### Security Principles +- **Lazy Loading**: External tool validation only when needed +- **Caching**: Configuration and status caching for repeated operations +- **Streaming**: Real-time log streaming for long operations +- **Connection Pooling**: Reuse of kubectl and Docker connections -1. **Least Privilege**: Request minimal permissions necessary -2. **Secure Defaults**: Safe configurations out of the box -3. **Input Validation**: Sanitize all user inputs -4. **Secret Management**: Secure handling of credentials and keys -5. **Audit Logging**: Track security-relevant operations +## Testing Architecture -### Trust Boundaries +### Test Structure -```mermaid -graph LR - subgraph "Trusted Zone" - A[OpenFrame CLI] - B[Local Kubernetes] - C[Local Docker] - end - - subgraph "Semi-Trusted Zone" - D[Container Images] - E[Helm Charts] - F[Git Repositories] - end - - subgraph "Untrusted Zone" - G[Public Internet] - H[External APIs] - I[User Input] - end - - A --> B - A --> C - B --> D - A --> E - A --> F - - E --> G - F --> G - A --> H - I --> A +```text +testing/ +โ”œโ”€โ”€ unit/ # Unit tests for individual components +โ”œโ”€โ”€ integration/ # Integration tests with external tools +โ”œโ”€โ”€ e2e/ # End-to-end workflow tests +โ”œโ”€โ”€ fixtures/ # Test data and configurations +โ””โ”€โ”€ mocks/ # Mock implementations for external dependencies ``` -## Performance Considerations +### Testing Patterns -### Optimization Strategies +- **Unit Tests**: Test individual functions and methods in isolation +- **Integration Tests**: Test integration with external tools (Docker, K3d) +- **End-to-End Tests**: Test complete workflows from CLI to cluster +- **Mock Objects**: Mock external dependencies for reliable testing -1. **Lazy Loading**: Load providers and tools only when needed -2. **Concurrent Operations**: Parallel execution where safe -3. **Caching**: Cache expensive operations (cluster status, etc.) -4. **Resource Monitoring**: Track memory and CPU usage -5. **Efficient Data Structures**: Use appropriate data types +## Configuration and Extensibility -### Resource Management +### Plugin Architecture -- **Memory**: Stream large outputs, avoid loading everything in memory -- **CPU**: Use worker pools for concurrent operations -- **Disk**: Clean up temporary files, use appropriate buffer sizes -- **Network**: Connection pooling, request batching where possible +OpenFrame CLI is designed for extensibility: -## Extensibility Points +- **Command Plugins**: New commands can be added through the plugin interface +- **Service Extensions**: New services can be registered and discovered +- **External Tool Integration**: New tools can be integrated through standardized interfaces -### Adding New Commands +### Configuration Hierarchy -1. **Create command file** in appropriate `cmd/` subdirectory -2. **Implement service logic** in `internal/` package -3. **Add provider interface** if external tool needed -4. **Write comprehensive tests** for all components -5. **Update documentation** and help text +1. **Command Line Flags**: Highest priority, override everything +2. **Environment Variables**: Override configuration files +3. **Configuration Files**: User and system-level configuration +4. **Default Values**: Built-in sensible defaults -### Adding New Providers +## Security Considerations -1. **Define provider interface** in appropriate service package -2. **Implement provider** in `internal/*/providers/` directory -3. **Add configuration support** for provider-specific settings -4. **Implement comprehensive testing** including mocks -5. **Update factory functions** to instantiate new provider +### Principle of Least Privilege -### Plugin Architecture (Future) +- Commands run with minimal required permissions +- External tool execution is sandboxed where possible +- Configuration validation prevents malicious inputs -Future extensibility through plugins: +### Credential Management -```mermaid -graph TB - A[OpenFrame Core] --> B[Plugin Manager] - B --> C[Command Plugins] - B --> D[Provider Plugins] - B --> E[UI Plugins] - - C --> F[Custom Commands] - D --> G[New Tool Integrations] - E --> H[Custom Interfaces] -``` +- No credentials stored in configuration files +- Integration with system credential stores +- Secure handling of Kubernetes contexts and Docker credentials -## Migration and Upgrade Strategy +## Performance Characteristics -### Backward Compatibility +### Resource Usage -- **Configuration**: Support old config format with migration -- **Commands**: Maintain command compatibility across versions -- **Data**: Migrate user data automatically when needed -- **Dependencies**: Graceful handling of version mismatches +- **Memory**: Minimal memory footprint, streaming for large operations +- **CPU**: Efficient concurrent operations, minimal CPU overhead +- **Disk**: Temporary files cleaned automatically +- **Network**: Efficient use of connections, connection pooling -### Version Management +### Scalability -```go -type VersionInfo struct { - Version string // Semantic version - Commit string // Git commit hash - Date string // Build timestamp - Go string // Go version used -} -``` +- **Multi-Cluster**: Support for managing multiple clusters concurrently +- **Large Deployments**: Efficient handling of large ArgoCD deployments +- **Resource Cleanup**: Automatic cleanup prevents resource accumulation + +## Future Architecture Considerations -## Next Steps +### Planned Enhancements -To deepen your understanding of OpenFrame CLI architecture: +- **Remote Cluster Support**: Extend beyond local K3d clusters +- **Plugin Ecosystem**: Standardized plugin architecture +- **Web Interface**: Optional web UI for cluster management +- **Metrics and Observability**: Built-in monitoring and metrics collection -1. **[Security Guidelines](../security/README.md)** - Learn about security implementations -2. **[Testing Guide](../testing/README.md)** - Understand testing strategies -3. **[Contributing Guidelines](../contributing/guidelines.md)** - Learn development processes +### Extensibility Points -## Additional Resources +- **Custom Deployment Modes**: Support for organization-specific modes +- **External Tool Integration**: Framework for integrating new tools +- **Configuration Providers**: Support for external configuration sources +- **Event System**: Plugin system based on events and hooks -- **[Architecture Documentation](./architecture/overview.md)** - Generated architecture docs from code -- **Go Design Patterns**: https://golang.org/doc/effective_go -- **Kubernetes Client Libraries**: https://kubernetes.io/docs/reference/using-api/client-libraries/ -- **Cobra CLI Framework**: https://cobra.dev/ -- **OpenMSP Community**: [Join Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) \ No newline at end of file +> ๐Ÿ“ **Architecture Philosophy**: OpenFrame CLI prioritizes simplicity, reliability, and extensibility. The modular design ensures that each component can be understood, tested, and modified independently while maintaining clear interfaces and responsibilities. \ No newline at end of file diff --git a/docs/development/security/README.md b/docs/development/security/README.md new file mode 100644 index 00000000..b35cd04b --- /dev/null +++ b/docs/development/security/README.md @@ -0,0 +1,678 @@ +# Security Best Practices + +This document outlines security best practices, authentication patterns, and vulnerability management for OpenFrame CLI development. + +## Security Overview + +OpenFrame CLI operates in a privileged environment, managing Docker containers, Kubernetes clusters, and external tool integrations. Security is paramount to prevent privilege escalation, data exposure, and malicious code execution. + +## Authentication and Authorization Patterns + +### Kubernetes Authentication + +OpenFrame CLI relies on existing Kubernetes authentication mechanisms: + +```go +// Secure kubeconfig handling +type KubeConfigManager struct { + configPath string + context string +} + +func (k *KubeConfigManager) GetSecureConfig() (*rest.Config, error) { + // Validate kubeconfig path + if !isSecurePath(k.configPath) { + return nil, fmt.Errorf("insecure kubeconfig path: %s", k.configPath) + } + + // Load with restricted permissions + config, err := clientcmd.BuildConfigFromFlags("", k.configPath) + if err != nil { + return nil, fmt.Errorf("failed to load kubeconfig: %w", err) + } + + // Apply security constraints + config.Timeout = 30 * time.Second + config.QPS = 10 + config.Burst = 15 + + return config, nil +} +``` + +### Docker Authentication + +Secure Docker daemon communication: + +```go +// Secure Docker client configuration +func NewSecureDockerClient() (*client.Client, error) { + // Use system Docker socket with validation + host := os.Getenv("DOCKER_HOST") + if host == "" { + host = "unix:///var/run/docker.sock" + } + + // Validate Docker socket permissions + if err := validateDockerSocket(host); err != nil { + return nil, fmt.Errorf("docker socket validation failed: %w", err) + } + + // Create client with security options + opts := []client.Opt{ + client.WithAPIVersionNegotiation(), + client.WithTimeout(30 * time.Second), + } + + return client.NewClientWithOpts(opts...) +} + +func validateDockerSocket(host string) error { + if strings.HasPrefix(host, "unix://") { + socketPath := strings.TrimPrefix(host, "unix://") + info, err := os.Stat(socketPath) + if err != nil { + return err + } + + // Check socket permissions (should be writable by docker group) + if info.Mode()&0o066 != 0 { + return fmt.Errorf("docker socket has overly permissive permissions: %v", info.Mode()) + } + } + return nil +} +``` + +### ArgoCD Integration Security + +```go +// Secure ArgoCD client configuration +type ArgoCDClient struct { + serverAddr string + token string + insecure bool +} + +func (a *ArgoCDClient) NewSecureConnection() (*grpc.ClientConn, error) { + var opts []grpc.DialOption + + if a.insecure { + // Only allow insecure connections for localhost development + if !isLocalhost(a.serverAddr) { + return nil, fmt.Errorf("insecure connections only allowed for localhost") + } + opts = append(opts, grpc.WithInsecure()) + } else { + // Use TLS with certificate verification + config := &tls.Config{ + ServerName: extractHostname(a.serverAddr), + MinVersion: tls.VersionTLS12, + } + opts = append(opts, grpc.WithTransportCredentials(credentials.NewTLS(config))) + } + + return grpc.Dial(a.serverAddr, opts...) +} +``` + +## Data Encryption and Secure Storage + +### Configuration Data + +```go +// Secure configuration handling +type SecureConfig struct { + data map[string]interface{} + encrypted bool +} + +func (c *SecureConfig) SetSecretValue(key, value string) error { + // Encrypt sensitive values before storage + encrypted, err := encrypt(value, getConfigEncryptionKey()) + if err != nil { + return fmt.Errorf("failed to encrypt value: %w", err) + } + + c.data[key] = encrypted + c.encrypted = true + return nil +} + +func (c *SecureConfig) GetSecretValue(key string) (string, error) { + value, exists := c.data[key] + if !exists { + return "", fmt.Errorf("key not found: %s", key) + } + + if !c.encrypted { + return value.(string), nil + } + + decrypted, err := decrypt(value.(string), getConfigEncryptionKey()) + if err != nil { + return "", fmt.Errorf("failed to decrypt value: %w", err) + } + + return decrypted, nil +} + +func getConfigEncryptionKey() []byte { + // Use system keyring or environment-based key derivation + key := os.Getenv("OPENFRAME_CONFIG_KEY") + if key == "" { + // Derive key from system information (non-portable but secure) + return deriveSystemKey() + } + return []byte(key) +} +``` + +### Temporary Files + +```go +// Secure temporary file handling +func CreateSecureTempFile(prefix string) (*os.File, error) { + // Create temporary file with restricted permissions + tmpDir := os.TempDir() + + // Ensure temp directory has proper permissions + if err := os.Chmod(tmpDir, 0o700); err != nil { + return nil, fmt.Errorf("failed to secure temp directory: %w", err) + } + + // Create file with owner-only permissions + file, err := os.CreateTemp(tmpDir, prefix) + if err != nil { + return nil, fmt.Errorf("failed to create temp file: %w", err) + } + + // Set restrictive permissions + if err := file.Chmod(0o600); err != nil { + file.Close() + os.Remove(file.Name()) + return nil, fmt.Errorf("failed to set file permissions: %w", err) + } + + return file, nil +} + +// Automatic cleanup with secure deletion +func SecureCleanup(filepath string) error { + // Overwrite file contents before deletion + file, err := os.OpenFile(filepath, os.O_WRONLY, 0) + if err != nil { + return err + } + defer file.Close() + + // Get file size + info, err := file.Stat() + if err != nil { + return err + } + + // Overwrite with random data + randomData := make([]byte, info.Size()) + rand.Read(randomData) + + if _, err := file.WriteAt(randomData, 0); err != nil { + return err + } + + if err := file.Sync(); err != nil { + return err + } + + // Remove file + return os.Remove(filepath) +} +``` + +## Input Validation and Sanitization + +### Command Input Validation + +```go +// Secure command input validation +type InputValidator struct { + allowedChars *regexp.Regexp + maxLength int +} + +func NewInputValidator() *InputValidator { + return &InputValidator{ + // Allow alphanumeric, hyphens, and underscores only + allowedChars: regexp.MustCompile(`^[a-zA-Z0-9_-]+$`), + maxLength: 63, // Kubernetes name length limit + } +} + +func (v *InputValidator) ValidateClusterName(name string) error { + if len(name) == 0 { + return fmt.Errorf("cluster name cannot be empty") + } + + if len(name) > v.maxLength { + return fmt.Errorf("cluster name too long: %d > %d", len(name), v.maxLength) + } + + if !v.allowedChars.MatchString(name) { + return fmt.Errorf("cluster name contains invalid characters: %s", name) + } + + // Prevent reserved names + reserved := []string{"kubernetes", "default", "kube-system", "kube-public", "kube-node-lease"} + for _, r := range reserved { + if strings.EqualFold(name, r) { + return fmt.Errorf("cluster name conflicts with reserved name: %s", r) + } + } + + return nil +} + +func (v *InputValidator) ValidatePath(path string) error { + // Prevent path traversal attacks + cleanPath := filepath.Clean(path) + if strings.Contains(cleanPath, "..") { + return fmt.Errorf("path contains directory traversal: %s", path) + } + + // Ensure path is within allowed directories + allowedPrefixes := []string{ + os.TempDir(), + os.Getenv("HOME"), + "/opt/openframe", + } + + isAllowed := false + for _, prefix := range allowedPrefixes { + if strings.HasPrefix(cleanPath, prefix) { + isAllowed = true + break + } + } + + if !isAllowed { + return fmt.Errorf("path not in allowed directories: %s", path) + } + + return nil +} +``` + +### YAML/JSON Configuration Validation + +```go +// Secure configuration parsing +func ParseSecureConfig(data []byte) (*Config, error) { + // Limit parsing size to prevent DoS + if len(data) > 10*1024*1024 { // 10MB limit + return nil, fmt.Errorf("configuration file too large: %d bytes", len(data)) + } + + // Use secure YAML parser with restrictions + decoder := yaml.NewDecoder(bytes.NewReader(data)) + decoder.KnownFields(true) // Reject unknown fields + + var config Config + if err := decoder.Decode(&config); err != nil { + return nil, fmt.Errorf("failed to parse configuration: %w", err) + } + + // Validate configuration structure + if err := validateConfig(&config); err != nil { + return nil, fmt.Errorf("configuration validation failed: %w", err) + } + + return &config, nil +} + +func validateConfig(config *Config) error { + // Validate all string fields + validator := NewInputValidator() + + if err := validator.ValidateClusterName(config.ClusterName); err != nil { + return fmt.Errorf("invalid cluster name: %w", err) + } + + // Validate resource limits + if config.Resources.Memory < 0 || config.Resources.Memory > 64*1024*1024*1024 { // 64GB max + return fmt.Errorf("invalid memory limit: %d", config.Resources.Memory) + } + + if config.Resources.CPU < 0 || config.Resources.CPU > 32 { // 32 CPU max + return fmt.Errorf("invalid CPU limit: %f", config.Resources.CPU) + } + + return nil +} +``` + +## Common Security Vulnerabilities and Mitigations + +### 1. Command Injection + +```go +// Secure command execution +func ExecuteSecureCommand(command string, args ...string) error { + // Whitelist allowed commands + allowedCommands := map[string]bool{ + "k3d": true, + "kubectl": true, + "helm": true, + "docker": true, + } + + if !allowedCommands[command] { + return fmt.Errorf("command not allowed: %s", command) + } + + // Validate all arguments + for _, arg := range args { + if err := validateCommandArgument(arg); err != nil { + return fmt.Errorf("invalid argument '%s': %w", arg, err) + } + } + + // Use exec.Command instead of shell execution + cmd := exec.Command(command, args...) + + // Set secure environment + cmd.Env = getSecureEnvironment() + + // Set working directory to safe location + cmd.Dir = "/tmp" + + return cmd.Run() +} + +func validateCommandArgument(arg string) error { + // Prevent shell metacharacters + dangerous := []string{";", "&", "|", "$", "`", "$(", "${", ">", "<", "&&", "||"} + for _, d := range dangerous { + if strings.Contains(arg, d) { + return fmt.Errorf("argument contains dangerous characters: %s", d) + } + } + return nil +} +``` + +### 2. Path Traversal + +```go +// Secure file operations +func SecureFileRead(basePath, userPath string) ([]byte, error) { + // Clean and validate the path + cleanBase := filepath.Clean(basePath) + cleanUser := filepath.Clean(userPath) + fullPath := filepath.Join(cleanBase, cleanUser) + + // Ensure the resulting path is within the base directory + if !strings.HasPrefix(fullPath, cleanBase) { + return nil, fmt.Errorf("path traversal detected: %s", userPath) + } + + // Check if file exists and is readable + info, err := os.Stat(fullPath) + if err != nil { + return nil, fmt.Errorf("file access error: %w", err) + } + + // Prevent reading of special files + if !info.Mode().IsRegular() { + return nil, fmt.Errorf("not a regular file: %s", fullPath) + } + + // Limit file size + if info.Size() > 10*1024*1024 { // 10MB limit + return nil, fmt.Errorf("file too large: %d bytes", info.Size()) + } + + return os.ReadFile(fullPath) +} +``` + +### 3. Privilege Escalation + +```go +// Run commands with minimal privileges +func ExecuteWithMinimalPrivileges(command string, args []string) error { + cmd := exec.Command(command, args...) + + // Drop privileges if running as root + if os.Getuid() == 0 { + // Find the nobody user + nobody, err := user.Lookup("nobody") + if err != nil { + return fmt.Errorf("failed to lookup nobody user: %w", err) + } + + uid, _ := strconv.Atoi(nobody.Uid) + gid, _ := strconv.Atoi(nobody.Gid) + + cmd.SysProcAttr = &syscall.SysProcAttr{ + Credential: &syscall.Credential{ + Uid: uint32(uid), + Gid: uint32(gid), + }, + } + } + + return cmd.Run() +} +``` + +## Security Testing and Code Review Guidelines + +### Security Testing Checklist + +- [ ] **Input Validation**: All user inputs are validated and sanitized +- [ ] **Command Injection**: No user input is directly passed to shell commands +- [ ] **Path Traversal**: File paths are validated and contained within safe directories +- [ ] **Privilege Escalation**: Commands run with minimal required privileges +- [ ] **Secrets Management**: No secrets are logged or stored in plain text +- [ ] **Network Security**: All network connections use appropriate encryption +- [ ] **Error Handling**: Error messages don't leak sensitive information + +### Code Review Security Focus + +```go +// Example of security-focused code review +func ReviewSecurityChecklist(code string) []string { + issues := []string{} + + // Check for common security anti-patterns + if strings.Contains(code, "exec.Command(") { + issues = append(issues, "Review exec.Command usage for command injection") + } + + if strings.Contains(code, "os.Open(") { + issues = append(issues, "Review file operations for path traversal") + } + + if strings.Contains(code, "http.Get(") { + issues = append(issues, "Review HTTP requests for proper TLS configuration") + } + + if strings.Contains(code, "fmt.Printf") && strings.Contains(code, "password") { + issues = append(issues, "Potential secret logging detected") + } + + return issues +} +``` + +## Environment Variables and Secrets Management + +### Secure Environment Variable Handling + +```go +// Secure environment variable management +type SecureEnv struct { + sensitiveKeys map[string]bool +} + +func NewSecureEnv() *SecureEnv { + return &SecureEnv{ + sensitiveKeys: map[string]bool{ + "OPENFRAME_CONFIG_KEY": true, + "DOCKER_PASSWORD": true, + "KUBECONFIG": true, + "ARGOCD_AUTH_TOKEN": true, + }, + } +} + +func (s *SecureEnv) Get(key string) (string, error) { + value := os.Getenv(key) + if value == "" { + return "", fmt.Errorf("environment variable not set: %s", key) + } + + // Log access to sensitive variables + if s.sensitiveKeys[key] { + log.Info("accessing sensitive environment variable", "key", key) + } + + return value, nil +} + +func (s *SecureEnv) Set(key, value string) error { + if s.sensitiveKeys[key] { + // Validate sensitive values + if len(value) < 8 { + return fmt.Errorf("sensitive value too short for %s", key) + } + } + + return os.Setenv(key, value) +} + +// Sanitize environment for subprocesses +func GetSecureEnvironment() []string { + allowedVars := []string{ + "PATH", "HOME", "USER", "TMPDIR", + "DOCKER_HOST", "KUBECONFIG", + "OPENFRAME_CONFIG_DIR", + } + + var secureEnv []string + for _, key := range allowedVars { + if value := os.Getenv(key); value != "" { + secureEnv = append(secureEnv, key+"="+value) + } + } + + return secureEnv +} +``` + +### Kubernetes Secrets Integration + +```go +// Secure secrets management with Kubernetes +func StoreSecretInCluster(name, namespace string, data map[string][]byte) error { + config, err := rest.InClusterConfig() + if err != nil { + return fmt.Errorf("failed to get cluster config: %w", err) + } + + client, err := kubernetes.NewForConfig(config) + if err != nil { + return fmt.Errorf("failed to create client: %w", err) + } + + secret := &corev1.Secret{ + ObjectMeta: metav1.ObjectMeta{ + Name: name, + Namespace: namespace, + Annotations: map[string]string{ + "openframe.io/managed": "true", + "openframe.io/created": time.Now().Format(time.RFC3339), + }, + }, + Type: corev1.SecretTypeOpaque, + Data: data, + } + + _, err = client.CoreV1().Secrets(namespace).Create(context.TODO(), secret, metav1.CreateOptions{}) + if err != nil { + return fmt.Errorf("failed to create secret: %w", err) + } + + return nil +} +``` + +## Compliance and Audit + +### Audit Logging + +```go +// Security audit logging +type SecurityAuditor struct { + logger *log.Logger +} + +func (a *SecurityAuditor) LogSecurityEvent(event SecurityEvent) { + a.logger.Info("security event", + "type", event.Type, + "user", event.User, + "action", event.Action, + "resource", event.Resource, + "timestamp", event.Timestamp, + "success", event.Success, + ) +} + +type SecurityEvent struct { + Type string // e.g., "authentication", "authorization", "data_access" + User string // username or system account + Action string // specific action performed + Resource string // resource accessed + Timestamp time.Time + Success bool + Details map[string]interface{} +} +``` + +### Compliance Checks + +```go +// Automated compliance checking +func RunComplianceCheck() error { + checks := []ComplianceCheck{ + CheckFilePermissions, + CheckEnvironmentSecurity, + CheckNetworkSecurity, + CheckSecretHandling, + } + + for _, check := range checks { + if err := check(); err != nil { + return fmt.Errorf("compliance check failed: %w", err) + } + } + + return nil +} + +func CheckFilePermissions() error { + configDir := os.Getenv("OPENFRAME_CONFIG_DIR") + info, err := os.Stat(configDir) + if err != nil { + return err + } + + if info.Mode()&0o077 != 0 { + return fmt.Errorf("config directory has overly permissive permissions: %v", info.Mode()) + } + + return nil +} +``` + +> ๐Ÿ”’ **Security First**: Security is not an afterthought in OpenFrame CLI. Every feature must be designed with security in mind, following the principle of least privilege and defense in depth. When in doubt, choose the more secure option. \ No newline at end of file diff --git a/docs/development/setup/environment.md b/docs/development/setup/environment.md index 9f95aa1e..cffdeaa2 100644 --- a/docs/development/setup/environment.md +++ b/docs/development/setup/environment.md @@ -1,621 +1,440 @@ # Development Environment Setup -This guide walks you through setting up a complete development environment for OpenFrame CLI, including IDEs, tools, extensions, and configuration for maximum productivity. +This guide walks you through setting up an optimal development environment for contributing to OpenFrame CLI. -## IDE and Editor Setup - -### Visual Studio Code (Recommended) +## Prerequisites -VS Code provides excellent Go support and Kubernetes tooling: +Ensure you've completed the [Prerequisites guide](../../getting-started/prerequisites.md) before proceeding with development setup. -#### Installation -```bash -# macOS -brew install --cask visual-studio-code - -# Ubuntu/Debian -wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg -sudo install -o root -g root -m 644 packages.microsoft.gpg /etc/apt/trusted.gpg.d/ -sudo sh -c 'echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/trusted.gpg.d/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list' -sudo apt update -sudo apt install code -``` +## IDE and Editor Setup -#### Essential Extensions +### VS Code (Recommended) -Install these extensions for Go and Kubernetes development: +VS Code provides excellent Go support with these essential extensions: +#### Required Extensions ```bash -# Core Go development -code --install-extension golang.Go -code --install-extension golang.Go-nightly - -# Kubernetes and YAML -code --install-extension ms-kubernetes-tools.vscode-kubernetes-tools -code --install-extension redhat.vscode-yaml - -# Git and GitHub integration -code --install-extension GitHub.vscode-pull-request-github -code --install-extension eamodio.gitlens - -# Code quality and testing -code --install-extension ms-vscode.test-adapter-converter -code --install-extension hbenl.vscode-test-explorer -code --install-extension SonarSource.sonarlint-vscode - -# Docker and containers -code --install-extension ms-azuretools.vscode-docker - -# Markdown and documentation -code --install-extension yzhang.markdown-all-in-one -code --install-extension bierner.markdown-mermaid - -# Productivity -code --install-extension vscodevim.vim # Optional: Vim keybindings +# Install via VS Code Extensions marketplace or CLI +code --install-extension golang.go code --install-extension ms-vscode.vscode-json +code --install-extension redhat.vscode-yaml +code --install-extension ms-kubernetes-tools.vscode-kubernetes-tools ``` -#### VS Code Configuration - -Create `.vscode/settings.json` in your workspace: +#### VS Code Settings +Create `.vscode/settings.json` in your project: ```json { - "go.toolsManagement.autoUpdate": true, - "go.useLanguageServer": true, - "go.gopath": "", - "go.goroot": "", "go.lintTool": "golangci-lint", - "go.lintFlags": [ - "--fast" - ], - "go.vetOnSave": "package", + "go.lintOnSave": "package", "go.formatTool": "goimports", - "go.buildOnSave": "package", - "go.testFlags": ["-v"], - "go.testTimeout": "30s", - "go.coverOnSave": false, - "go.coverOnSingleTest": true, - "go.coverOnSingleTestFile": true, - "go.coverOnTestPackage": true, + "go.useLanguageServer": true, + "go.testFlags": ["-v", "-race"], + "go.buildTags": "integration", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.organizeImports": true - }, - "files.eol": "\n", - "yaml.schemas": { - "https://json.schemastore.org/kustomization": [ - "kustomization.yaml", - "kustomization.yml" - ], - "https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/crds/application-crd.yaml": [ - "**/argocd-apps/*.yaml", - "**/argocd-apps/*.yml" - ] - }, - "kubernetes.namespace": "default", - "kubernetes.defaultLogLevel": "info" + } } ``` -Create `.vscode/launch.json` for debugging: +#### VS Code Tasks +Create `.vscode/tasks.json` for common development tasks: ```json { - "version": "0.2.0", - "configurations": [ + "version": "2.0.0", + "tasks": [ { - "name": "Launch OpenFrame CLI", - "type": "go", - "request": "launch", - "mode": "auto", - "program": "${workspaceFolder}/main.go", - "args": ["--help"], - "env": { - "GO_ENV": "development" + "label": "Build OpenFrame", + "type": "shell", + "command": "go", + "args": ["build", "-o", "openframe", "./main.go"], + "group": "build", + "presentation": { + "reveal": "always", + "panel": "new" } }, { - "name": "Debug Bootstrap Command", - "type": "go", - "request": "launch", - "mode": "auto", - "program": "${workspaceFolder}/main.go", - "args": ["bootstrap", "--verbose", "--non-interactive"], - "env": { - "GO_ENV": "development" + "label": "Run Tests", + "type": "shell", + "command": "go", + "args": ["test", "./..."], + "group": "test", + "presentation": { + "reveal": "always", + "panel": "new" } }, { - "name": "Debug Cluster Status", - "type": "go", - "request": "launch", - "mode": "auto", - "program": "${workspaceFolder}/main.go", - "args": ["cluster", "status"], - "env": { - "GO_ENV": "development" + "label": "Lint Code", + "type": "shell", + "command": "golangci-lint", + "args": ["run"], + "group": "build", + "presentation": { + "reveal": "always", + "panel": "new" } } ] } ``` -### GoLand/IntelliJ IDEA +### GoLand (Alternative) -For JetBrains IDEs: +GoLand provides built-in Go support. Configure these settings: -#### Installation -```bash -# macOS -brew install --cask goland - -# Or download from https://www.jetbrains.com/go/ -``` +1. **Go Modules**: Enable `Go โ†’ Go Modules โ†’ Enable Go modules integration` +2. **Code Style**: Set to `gofmt` formatting +3. **Inspections**: Enable all Go-related inspections +4. **Run Configurations**: Set up configurations for tests and builds -#### Configuration -1. **Go Settings**: File โ†’ Settings โ†’ Go โ†’ GOROOT and GOPATH -2. **Code Style**: File โ†’ Settings โ†’ Editor โ†’ Code Style โ†’ Go -3. **Live Templates**: File โ†’ Settings โ†’ Editor โ†’ Live Templates -4. **Kubernetes Plugin**: File โ†’ Settings โ†’ Plugins โ†’ Install "Kubernetes" +## Required Development Tools -### Vim/Neovim +### Go Environment -For terminal-based editing: - -#### Installation ```bash -# Install vim-go plugin manager -curl -fLo ~/.vim/autoload/plug.vim --create-dirs \ - https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim -``` - -Add to `~/.vimrc`: -```vim -call plug#begin('~/.vim/plugged') -Plug 'fatih/vim-go', { 'do': ':GoUpdateBinaries' } -Plug 'neoclide/coc.nvim', {'branch': 'release'} -Plug 'preservim/nerdtree' -Plug 'airblade/vim-gitgutter' -call plug#end() - -" Go-specific settings -let g:go_fmt_command = "goimports" -let g:go_auto_type_info = 1 -let g:go_highlight_types = 1 -let g:go_highlight_fields = 1 -let g:go_highlight_functions = 1 -let g:go_highlight_function_calls = 1 -``` +# Verify Go version (1.21+ required) +go version -## Development Tools +# Configure Go environment +export GOPATH=$HOME/go +export PATH=$GOPATH/bin:$PATH +export GO111MODULE=on -### Go Tools Installation - -Install essential Go development tools: - -```bash -# Core Go tools +# Install development tools go install golang.org/x/tools/cmd/goimports@latest -go install golang.org/x/tools/cmd/godoc@latest -go install golang.org/x/tools/cmd/gofmt@latest - -# Linting and code quality go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest -go install honnef.co/go/tools/cmd/staticcheck@latest -go install github.com/kisielk/errcheck@latest - -# Testing tools -go install github.com/rakyll/gotest@latest -go install github.com/axw/gocov/gocov@latest -go install github.com/AlekSi/gocov-xml@latest - -# Documentation tools +go install github.com/cosmtrek/air@latest go install golang.org/x/tools/cmd/godoc@latest - -# Binary management -go install github.com/cosmtrek/air@latest # Hot reload -go install github.com/goreleaser/goreleaser@latest # Release management ``` -### Configure golangci-lint +### Linting and Code Quality -Create `.golangci.yml` in the project root: +#### golangci-lint Configuration + +Create `.golangci.yml` in project root: ```yaml run: timeout: 5m - issues-exit-code: 1 tests: true -linters-settings: - golint: - min-confidence: 0 - gocyclo: - min-complexity: 15 - goimports: - local-prefixes: github.com/flamingo-stack/openframe-cli - govet: - check-shadowing: true - errcheck: - check-type-assertions: true - check-blank: true - unused: - check-exported: false - linters: enable: - - bodyclose - - deadcode - - depguard - - dogsled - - dupl - errcheck - - exportloopref - - exhaustive - - goconst - - gocritic - gofmt - goimports - golint - - goprintffuncname - gosec - gosimple - govet - ineffassign - - misspell - - nakedret - - noctx - - nolintlint - - rowserrcheck - staticcheck - - structcheck - - stylecheck - typecheck - unconvert - - unparam - unused - varcheck - - whitespace + - deadcode + +linters-settings: + golint: + min-confidence: 0.8 + gosec: + excludes: + - G104 # Audit errors not checked + - G204 # Subprocess launched with variable + errcheck: + check-type-assertions: true + check-blank: true issues: exclude-rules: - path: _test\.go linters: - gosec - - dupl - exclude-use-default: false - exclude: - - "Error return value of .((os\.)?std(out|err)\..*|.*Close|.*Flush|os\.Remove(All)?|.*print.*|os\.(Un)?Setenv). is not checked" + - errcheck ``` -### Shell Configuration - -Add helpful aliases and functions to your shell profile: +### Git Configuration ```bash -# Add to ~/.bashrc, ~/.zshrc, or ~/.fish -# OpenFrame development aliases -alias of="go run main.go" -alias oft="go test ./..." -alias ofb="go build -o openframe main.go" -alias ofl="golangci-lint run" - -# Go development aliases -alias gob="go build" -alias got="go test" -alias gor="go run" -alias gof="go fmt ./..." -alias goi="goimports -w ." -alias gol="golangci-lint run" - -# Kubernetes aliases for development -alias k="kubectl" -alias kgp="kubectl get pods" -alias kgs="kubectl get svc" -alias kgd="kubectl get deployment" -alias kdp="kubectl describe pod" -alias kl="kubectl logs" -alias kex="kubectl exec -it" - -# OpenFrame specific kubectl contexts -alias kof="kubectl config use-context k3d-openframe-local" -alias kctx="kubectl config current-context" -alias kns="kubectl config set-context --current --namespace" - -# Docker aliases -alias d="docker" -alias dc="docker compose" -alias dps="docker ps" -alias di="docker images" -alias dl="docker logs" - -# Git aliases for development workflow -alias gs="git status" -alias ga="git add" -alias gc="git commit" -alias gp="git push" -alias gl="git pull" -alias gb="git branch" -alias gco="git checkout" -alias gd="git diff" -``` - -## Environment Variables - -Set up development environment variables: - -```bash -# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.) - -# Go development -export GOPATH="$HOME/go" -export GOROOT="$(go env GOROOT)" -export PATH="$GOPATH/bin:$GOROOT/bin:$PATH" - -# OpenFrame CLI development -export OPENFRAME_LOG_LEVEL="debug" -export OPENFRAME_CONFIG_DIR="$HOME/.openframe-dev" -export OPENFRAME_DEV_MODE="true" +# Configure Git for development +git config --global user.name "Your Name" +git config --global user.email "your.email@example.com" -# Kubernetes development -export KUBECONFIG="$HOME/.kube/config" -export KUBECTL_EXTERNAL_DIFF="diff -u" +# Set up Git hooks (optional) +git config core.hooksPath .githooks -# Docker development -export DOCKER_BUILDKIT=1 -export COMPOSE_DOCKER_CLI_BUILD=1 - -# Development tools -export EDITOR="code" # or vim, nano, etc. -export BROWSER="chrome" # or firefox, safari, etc. - -# Testing -export GO_TEST_TIMEOUT="30s" -export COVERAGE_OUTPUT="coverage.out" +# Configure Git to handle Go modules +git config --global url."git@github.com:".insteadOf "https://github.com/" ``` -## Kubernetes Development Setup +### Make and Build Tools -### Configure kubectl contexts +Install build automation tools: ```bash -# Create separate contexts for development -kubectl config set-context openframe-dev \ - --cluster=k3d-openframe-local \ - --user=admin@k3d-openframe-local +# Install Make (if not already installed) +# Linux +sudo apt-get install make -kubectl config set-context openframe-test \ - --cluster=k3d-openframe-test \ - --user=admin@k3d-openframe-test +# macOS +brew install make -# Use development context by default -kubectl config use-context openframe-dev +# Verify installation +make --version ``` -### Install Kubernetes development tools - -```bash -# Helm -curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash +## Environment Variables -# K3D -curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash +### Development Environment Variables -# Stern for log streaming -brew install stern # macOS -# or download from https://github.com/stern/stern/releases +Create a `.env` file or add to your shell profile: -# kubectx and kubens for context switching -brew install kubectx # macOS -# or download from https://github.com/ahmetb/kubectx/releases +```bash +# OpenFrame Development +export OPENFRAME_DEV_MODE=true +export OPENFRAME_LOG_LEVEL=debug +export OPENFRAME_CONFIG_DIR=$HOME/.openframe + +# Go Development +export GOPATH=$HOME/go +export GO111MODULE=on +export GOPROXY=https://proxy.golang.org +export GOSUMDB=sum.golang.org + +# Kubernetes Development +export KUBECONFIG=$HOME/.kube/config +export KUBECTL_EXTERNAL_DIFF="code --diff --wait" + +# Docker Development +export DOCKER_BUILDKIT=1 +export COMPOSE_DOCKER_CLI_BUILD=1 -# K9s for cluster management -brew install k9s # macOS -# or download from https://github.com/derailed/k9s/releases +# Testing +export OPENFRAME_TEST_TIMEOUT=30m +export OPENFRAME_INTEGRATION_TESTS=true ``` -## Testing Environment Setup +### Shell Profile Configuration -### Configure test databases and services +Add to your `~/.bashrc`, `~/.zshrc`, or equivalent: ```bash -# Create test namespace -kubectl create namespace openframe-test - -# Install test dependencies -helm repo add bitnami https://charts.bitnami.com/bitnami -helm install test-redis bitnami/redis \ - --namespace openframe-test \ - --set auth.enabled=false - -# Install test monitoring -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/kind/deploy.yaml -``` - -### Test configuration +# OpenFrame CLI development function +openframe-dev() { + cd $GOPATH/src/github.com/flamingo-stack/openframe-cli + export OPENFRAME_DEV_MODE=true + export OPENFRAME_LOG_LEVEL=debug + echo "OpenFrame development environment activated" +} -Create `test.env` for test environment variables: +# Quick build and test +openframe-test() { + go build -o openframe ./main.go && ./openframe "$@" +} -```bash -# Test environment configuration -export OPENFRAME_TEST_MODE=true -export OPENFRAME_TEST_CLUSTER="k3d-openframe-test" -export OPENFRAME_TEST_NAMESPACE="openframe-test" -export OPENFRAME_TEST_TIMEOUT="60s" - -# Test database connections -export TEST_REDIS_URL="redis://localhost:6379" -export TEST_DATABASE_URL="postgres://localhost:5432/openframe_test" - -# Integration test settings -export INTEGRATION_TEST_ENABLED=true -export E2E_TEST_ENABLED=false # Disable by default +# Lint and format code +openframe-lint() { + goimports -w . + golangci-lint run +} ``` -## Performance and Debugging Tools - -### Install profiling tools +## Editor Extensions and Plugins -```bash -# Go profiling tools -go install github.com/google/pprof@latest -go install github.com/uber/go-torch@latest +### Essential Extensions -# Memory and performance analysis -go install github.com/pkg/profile@latest -``` +| Editor | Extension | Purpose | +|--------|-----------|---------| +| **VS Code** | Go (by Google) | Go language support | +| **VS Code** | Kubernetes | Kubernetes YAML support | +| **VS Code** | YAML | YAML language support | +| **VS Code** | GitLens | Enhanced Git integration | +| **GoLand** | Kubernetes | Kubernetes integration | +| **Vim/Neovim** | vim-go | Go development support | -### Configure debugging +### Optional but Helpful -Add debug configuration to your project: +- **Thunder Client** (VS Code): API testing +- **Docker** (VS Code): Container management +- **Remote - Containers** (VS Code): Development in containers +- **Live Share** (VS Code): Collaborative development -```go -// debug/profile.go -// +build debug +## Debugging Configuration -package debug +### VS Code Debug Configuration -import ( - "github.com/pkg/profile" - "os" -) +Create `.vscode/launch.json`: -func init() { - if os.Getenv("CPUPROFILE") != "" { - defer profile.Start().Stop() - } - if os.Getenv("MEMPROFILE") != "" { - defer profile.Start(profile.MemProfile).Stop() +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug OpenFrame CLI", + "type": "go", + "request": "launch", + "mode": "debug", + "program": "${workspaceFolder}/main.go", + "args": ["bootstrap", "--verbose"], + "env": { + "OPENFRAME_DEV_MODE": "true", + "OPENFRAME_LOG_LEVEL": "debug" + }, + "showLog": true + }, + { + "name": "Debug Tests", + "type": "go", + "request": "launch", + "mode": "test", + "program": "${workspaceFolder}", + "env": { + "OPENFRAME_TEST_MODE": "true" + }, + "args": [ + "-test.v", + "-test.run", + "TestBootstrap" + ] } + ] } ``` -## Pre-commit Hooks - -Set up git hooks for code quality: +### Command Line Debugging ```bash -# Install pre-commit (optional but recommended) -pip install pre-commit - -# Create .pre-commit-config.yaml -cat > .pre-commit-config.yaml << 'EOF' -repos: - - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.4.0 - hooks: - - id: trailing-whitespace - - id: end-of-file-fixer - - id: check-yaml - - id: check-added-large-files - - - repo: https://github.com/dnephin/pre-commit-golang - rev: v0.5.1 - hooks: - - id: go-fmt - - id: go-imports - - id: go-vet-mod - - id: go-unit-tests-mod - - id: golangci-lint-mod -EOF - -# Install the hooks -pre-commit install -``` +# Debug with delve +go install github.com/go-delve/delve/cmd/dlv@latest -Or create a simple git hook manually: +# Debug the CLI +dlv debug ./main.go -- bootstrap --verbose -```bash -# Create .git/hooks/pre-commit -cat > .git/hooks/pre-commit << 'EOF' -#!/bin/bash -# Pre-commit hook for OpenFrame CLI +# Debug tests +dlv test ./internal/bootstrap +``` + +## Performance and Monitoring -set -e +### Profiling Tools -echo "Running pre-commit checks..." +```bash +# Install pprof +go install github.com/google/pprof@latest -# Format code -echo "Running gofmt..." -gofmt -l -w . +# Profile CPU usage +go test -cpuprofile=cpu.prof -bench=. -# Organize imports -echo "Running goimports..." -goimports -l -w . +# Profile memory usage +go test -memprofile=mem.prof -bench=. -# Run linter -echo "Running golangci-lint..." -golangci-lint run +# Analyze profiles +pprof cpu.prof +pprof mem.prof +``` -# Run tests -echo "Running tests..." -go test -short ./... +### Benchmarking -echo "Pre-commit checks passed!" -EOF +```bash +# Run benchmarks +go test -bench=. -benchmem ./... -chmod +x .git/hooks/pre-commit +# Compare benchmarks +go install golang.org/x/perf/cmd/benchcmp@latest +benchcmp old.txt new.txt ``` -## Troubleshooting - -### Common Go Issues +## Development Workflow Automation + +### Air for Live Reloading + +Create `.air.toml` for live reloading: + +```toml +root = "." +testdata_dir = "testdata" +tmp_dir = "tmp" + +[build] + args_bin = ["bootstrap", "--verbose"] + bin = "./tmp/openframe" + cmd = "go build -o ./tmp/openframe ./main.go" + delay = 1000 + exclude_dir = ["assets", "tmp", "vendor", "testdata"] + exclude_file = [] + exclude_regex = ["_test.go"] + exclude_unchanged = false + follow_symlink = false + full_bin = "" + include_dir = [] + include_ext = ["go", "tpl", "tmpl", "html"] + include_file = [] + kill_delay = "0s" + log = "build-errors.log" + send_interrupt = false + stop_on_root = false + +[color] + app = "" + build = "yellow" + main = "magenta" + runner = "green" + watcher = "cyan" + +[log] + time = false + +[misc] + clean_on_exit = false +``` -#### GOPATH/GOROOT Problems +Start live reloading: ```bash -# Check Go environment -go env - -# Reset Go environment -go env -w GOPATH="" -go env -w GOROOT="" +air ``` -#### Module Issues +## Troubleshooting Common Issues + +### Go Module Issues ```bash -# Clean module cache +# Clear module cache go clean -modcache -# Reinstall dependencies +# Reinitialize modules go mod tidy -go mod download +go mod vendor ``` -### Kubernetes Issues - -#### Context Not Found +### VS Code Go Extension Issues ```bash -# List available contexts -kubectl config get-contexts +# Restart Go language server +Ctrl+Shift+P โ†’ "Go: Restart Language Server" -# Create new context -kubectl config set-context openframe-dev \ - --cluster=k3d-openframe-local \ - --user=admin@k3d-openframe-local +# Update Go tools +Ctrl+Shift+P โ†’ "Go: Install/Update Tools" ``` -#### Tools Not Found +### Build Issues ```bash -# Verify PATH includes Go bin directory -echo $PATH | grep go +# Clean build cache +go clean -cache -# Add Go bin to PATH -export PATH="$GOPATH/bin:$PATH" +# Rebuild everything +go build -a ./... ``` ## Next Steps -Your development environment is now ready! Continue with: +With your development environment configured: -1. **[Local Development Guide](local-development.md)** - Clone and run OpenFrame CLI locally +1. **[Local Development Guide](local-development.md)** - Clone and run the project locally 2. **[Architecture Overview](../architecture/README.md)** - Understand the system design -3. **[Contributing Guidelines](../contributing/guidelines.md)** - Learn the development workflow - -## Additional Resources +3. **[Contributing Guidelines](../contributing/guidelines.md)** - Learn the contribution process -- **Go Documentation**: https://golang.org/doc/ -- **Kubernetes Documentation**: https://kubernetes.io/docs/ -- **Cobra CLI Documentation**: https://cobra.dev/ -- **VS Code Go Extension**: https://marketplace.visualstudio.com/items?itemName=golang.Go -- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) \ No newline at end of file +> ๐Ÿ’ก **Pro Tip**: Set up your development environment incrementally. Start with basic Go support, then add linting, debugging, and automation tools as you become more comfortable with the codebase. \ No newline at end of file diff --git a/docs/development/setup/local-development.md b/docs/development/setup/local-development.md index 66002a68..abc02afc 100644 --- a/docs/development/setup/local-development.md +++ b/docs/development/setup/local-development.md @@ -1,590 +1,468 @@ # Local Development Guide -This guide covers cloning, building, running, and debugging OpenFrame CLI in your local development environment. Follow these steps to get the code running and start contributing. +This guide covers cloning, building, running, and debugging OpenFrame CLI locally for development purposes. -## Prerequisites +[![OpenFrame v0.3.7 - Enhanced Developer Experience](https://img.youtube.com/vi/O8hbBO5Mym8/maxresdefault.jpg)](https://www.youtube.com/watch?v=O8hbBO5Mym8) -Before starting local development, ensure you have completed: -- **[Prerequisites](../../getting-started/prerequisites.md)** - System requirements and dependencies -- **[Environment Setup](environment.md)** - IDE, tools, and development configuration +## Quick Start for Developers -## Clone the Repository +```bash +# 1. Clone the repository +git clone https://github.com/flamingo-stack/openframe-cli.git +cd openframe-cli -### Fork and Clone (Recommended for Contributors) +# 2. Install dependencies +go mod tidy -1. **Fork the repository** on GitHub: - - Go to https://github.com/flamingo-stack/openframe-cli - - Click "Fork" in the top-right corner - - Choose your GitHub account +# 3. Build the CLI +go build -o openframe ./main.go -2. **Clone your fork**: - ```bash - # Clone your fork - git clone https://github.com/YOUR-USERNAME/openframe-cli.git - cd openframe-cli - - # Add upstream remote for syncing - git remote add upstream https://github.com/flamingo-stack/openframe-cli.git - - # Verify remotes - git remote -v - ``` +# 4. Run locally +./openframe --help +``` -### Direct Clone (Read-only) +## Repository Setup -For read-only access or testing: +### Clone and Initialize ```bash +# Clone the repository git clone https://github.com/flamingo-stack/openframe-cli.git cd openframe-cli -``` -## Project Structure Overview +# Set up Git remotes (if forking) +git remote add upstream https://github.com/flamingo-stack/openframe-cli.git +git remote -v + +# Install dependencies +go mod download +go mod tidy +``` -Familiarize yourself with the codebase structure: +### Project Structure ```text openframe-cli/ -โ”œโ”€โ”€ main.go # Application entry point -โ”œโ”€โ”€ go.mod # Go module definition -โ”œโ”€โ”€ go.sum # Go dependency checksums -โ”œโ”€โ”€ cmd/ # CLI command definitions -โ”‚ โ”œโ”€โ”€ root.go # Root command and version info -โ”‚ โ”œโ”€โ”€ bootstrap/ # Complete environment bootstrap -โ”‚ โ”œโ”€โ”€ cluster/ # Kubernetes cluster management -โ”‚ โ”œโ”€โ”€ chart/ # Helm chart and ArgoCD operations +โ”œโ”€โ”€ cmd/ # CLI command implementations +โ”‚ โ”œโ”€โ”€ bootstrap/ # Complete environment setup +โ”‚ โ”œโ”€โ”€ cluster/ # Cluster management commands +โ”‚ โ”œโ”€โ”€ chart/ # Helm chart management โ”‚ โ””โ”€โ”€ dev/ # Development workflow tools -โ”œโ”€โ”€ internal/ # Private application code -โ”‚ โ”œโ”€โ”€ bootstrap/ # Bootstrap orchestration service -โ”‚ โ”œโ”€โ”€ cluster/ # Cluster lifecycle management -โ”‚ โ”œโ”€โ”€ chart/ # Chart installation and ArgoCD integration -โ”‚ โ”œโ”€โ”€ dev/ # Development tools (intercept, scaffold) -โ”‚ โ””โ”€โ”€ shared/ # Common utilities and adapters -โ”œโ”€โ”€ tests/ # Test suites and utilities -โ”‚ โ”œโ”€โ”€ integration/ # Integration tests -โ”‚ โ”œโ”€โ”€ mocks/ # Test mocks and fixtures -โ”‚ โ””โ”€โ”€ testutil/ # Test helper functions +โ”œโ”€โ”€ internal/ # Internal packages +โ”‚ โ”œโ”€โ”€ bootstrap/ # Bootstrap service implementation +โ”‚ โ”œโ”€โ”€ cluster/ # Cluster service implementation +โ”‚ โ”œโ”€โ”€ chart/ # Chart service implementation +โ”‚ โ””โ”€โ”€ utils/ # Utility functions +โ”œโ”€โ”€ pkg/ # Public packages โ”œโ”€โ”€ docs/ # Documentation -โ”œโ”€โ”€ examples/ # Usage examples and samples -โ””โ”€โ”€ scripts/ # Build and utility scripts +โ”œโ”€โ”€ scripts/ # Build and deployment scripts +โ”œโ”€โ”€ .github/ # GitHub workflows and templates +โ”œโ”€โ”€ main.go # CLI entry point +โ”œโ”€โ”€ go.mod # Go module definition +โ”œโ”€โ”€ go.sum # Go module checksums +โ”œโ”€โ”€ Makefile # Build automation +โ””โ”€โ”€ README.md # Project overview ``` -## Build and Run +## Building the Project -### Build the Binary +### Standard Build ```bash -# Build for your current platform -go build -o openframe main.go - -# Build with version information -VERSION=$(git describe --tags --always --dirty) -COMMIT=$(git rev-parse --short HEAD) -DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") +# Build for current platform +go build -o openframe ./main.go -go build -ldflags "-X main.version=$VERSION -X main.commit=$COMMIT -X main.date=$DATE" -o openframe main.go +# Build with version info +go build -ldflags "-X main.version=$(git describe --tags --always)" -o openframe ./main.go -# Test the build -./openframe --version +# Build for production (optimized) +CGO_ENABLED=0 go build -ldflags "-s -w" -o openframe ./main.go ``` -### Run During Development - -For rapid development cycles, run directly with Go: +### Cross-Platform Builds ```bash -# Run with go run (rebuilds automatically) -go run main.go --help - -# Run specific commands -go run main.go bootstrap --help -go run main.go cluster status -go run main.go chart list -``` - -### Hot Reload with Air - -Install and use Air for automatic rebuilds: +# Build for Linux +GOOS=linux GOARCH=amd64 go build -o openframe-linux-amd64 ./main.go -```bash -# Install Air -go install github.com/cosmtrek/air@latest +# Build for macOS +GOOS=darwin GOARCH=amd64 go build -o openframe-darwin-amd64 ./main.go +GOOS=darwin GOARCH=arm64 go build -o openframe-darwin-arm64 ./main.go -# Create .air.toml configuration -cat > .air.toml << 'EOF' -root = "." -testdata_dir = "testdata" -tmp_dir = "tmp" - -[build] -args_bin = [] -bin = "./tmp/main" -cmd = "go build -o ./tmp/main main.go" -delay = 1000 -exclude_dir = ["assets", "tmp", "vendor", "testdata", "docs"] -exclude_file = [] -exclude_regex = ["_test.go"] -exclude_unchanged = false -follow_symlink = false -full_bin = "" -include_dir = [] -include_ext = ["go", "tpl", "tmpl", "html"] -kill_delay = "0s" -log = "build-errors.log" -send_interrupt = false -stop_on_root = false - -[color] -app = "" -build = "yellow" -main = "magenta" -runner = "green" -watcher = "cyan" - -[log] -time = false - -[misc] -clean_on_exit = false -EOF - -# Run with hot reload -air +# Build for Windows +GOOS=windows GOARCH=amd64 go build -o openframe-windows-amd64.exe ./main.go ``` -Now changes to Go files will automatically trigger rebuilds. - -## Running Tests - -### Unit Tests +### Using Make ```bash -# Run all tests -go test ./... +# Build for current platform +make build -# Run tests with verbose output -go test -v ./... +# Build for all platforms +make build-all -# Run tests with coverage -go test -cover ./... +# Clean build artifacts +make clean -# Generate detailed coverage report -go test -coverprofile=coverage.out ./... -go tool cover -html=coverage.out -o coverage.html -open coverage.html # macOS -# or xdg-open coverage.html # Linux +# Run tests +make test + +# Run linting +make lint ``` -### Integration Tests +## Running Locally -Integration tests require a running Kubernetes cluster: +### Basic Execution ```bash -# Start a test cluster -k3d cluster create openframe-test +# Run the built binary +./openframe --help +./openframe --version -# Run integration tests -go test -tags=integration ./tests/integration/... +# Test bootstrap command (dry-run) +./openframe bootstrap --help -# Clean up -k3d cluster delete openframe-test +# Test cluster commands +./openframe cluster --help ``` -### Test Specific Packages +### Development Mode -```bash -# Test specific packages -go test ./internal/cluster/... -go test ./internal/chart/... -go test ./cmd/bootstrap/... +Set development environment variables: -# Test with timeout -go test -timeout=30s ./internal/bootstrap/... +```bash +# Enable development mode +export OPENFRAME_DEV_MODE=true +export OPENFRAME_LOG_LEVEL=debug -# Run specific tests -go test -run TestClusterCreate ./internal/cluster/... -go test -run TestBootstrapService ./internal/bootstrap/... +# Run with development settings +./openframe bootstrap --verbose ``` -## Development Workflow - -### Create a Feature Branch +### Running Without Building ```bash -# Sync with upstream (if using fork) -git fetch upstream -git checkout main -git merge upstream/main +# Run directly with go run +go run ./main.go --help +go run ./main.go bootstrap --verbose -# Create feature branch -git checkout -b feature/your-feature-name - -# Or for bug fixes -git checkout -b fix/issue-description +# Run with development flags +OPENFRAME_DEV_MODE=true go run ./main.go cluster status ``` -### Make Changes +## Hot Reload Development + +### Using Air -1. **Write Code**: Implement your feature or fix -2. **Write Tests**: Add or update tests for your changes -3. **Run Tests**: Ensure all tests pass -4. **Format Code**: Use `gofmt` and `goimports` -5. **Lint Code**: Run `golangci-lint` +Install and configure Air for live reloading: ```bash -# Format and organize imports -gofmt -w . -goimports -w . +# Install Air +go install github.com/cosmtrek/air@latest -# Run linter -golangci-lint run +# Create .air.toml (see environment setup guide) -# Run all tests -go test ./... +# Start live reloading +air + +# Air will automatically rebuild and restart when files change ``` -### Commit Changes +### Manual Hot Reload -Follow conventional commit format: +Create a simple script for quick iteration: ```bash -# Stage changes -git add . - -# Commit with descriptive message -git commit -m "feat(cluster): add support for custom node labels" -git commit -m "fix(bootstrap): handle timeout errors gracefully" -git commit -m "docs(readme): update installation instructions" - -# Push to your fork -git push origin feature/your-feature-name +#!/bin/bash +# Save as scripts/dev-watch.sh +while inotifywait -e modify -r ./cmd ./internal ./pkg; do + clear + echo "Rebuilding..." + go build -o openframe ./main.go + echo "Ready for testing!" +done ``` -## Debugging - -### VS Code Debugging +## Testing During Development -Use the launch configurations from [Environment Setup](environment.md): - -1. **Set breakpoints** in your code -2. **Press F5** or go to Run โ†’ Start Debugging -3. **Choose configuration**: - - "Launch OpenFrame CLI" - Debug with `--help` - - "Debug Bootstrap Command" - Debug bootstrap process - - "Debug Cluster Status" - Debug cluster operations - -### Command-line Debugging with Delve +### Unit Tests ```bash -# Install Delve -go install github.com/go-delve/delve/cmd/dlv@latest +# Run all tests +go test ./... -# Debug the application -dlv debug main.go -- bootstrap --verbose +# Run tests with verbose output +go test -v ./... -# Debug tests -dlv test ./internal/bootstrap/ +# Run tests with race detection +go test -race ./... -# Debug with arguments -dlv debug main.go -- cluster create --name=test-cluster +# Run tests with coverage +go test -cover ./... +go test -coverprofile=coverage.out ./... +go tool cover -html=coverage.out ``` -### Debug Commands in Delve +### Integration Tests -```text -(dlv) break main.main # Set breakpoint at main function -(dlv) break bootstrap.go:45 # Set breakpoint at line 45 in bootstrap.go -(dlv) continue # Continue execution -(dlv) next # Execute next line -(dlv) step # Step into function calls -(dlv) print variable_name # Print variable value -(dlv) goroutines # List all goroutines -(dlv) exit # Exit debugger -``` +```bash +# Run integration tests (requires Docker) +go test -tags=integration ./... -### Debugging with Print Statements - -For quick debugging, add log statements: - -```go -package main - -import ( - "log" - "os" -) - -func debugFunction() { - log.Printf("DEBUG: variable value: %+v", variable) - - // Pretty print structs - log.Printf("DEBUG: struct: %#v", structVariable) - - // Print with file and line info - log.Printf("DEBUG [%s:%d]: message", "filename.go", 123) -} - -func init() { - // Enable debug logging during development - if os.Getenv("DEBUG") == "true" { - log.SetFlags(log.LstdFlags | log.Lshortfile) - } -} -``` +# Run specific test packages +go test ./internal/bootstrap/... +go test ./internal/cluster/... -Run with debug logging: -```bash -DEBUG=true go run main.go bootstrap +# Run specific tests +go test -run TestBootstrapCommand ./cmd/bootstrap/ ``` -## Testing Your Changes - ### Manual Testing -Create test scenarios to verify your changes: +Create test scripts for common scenarios: ```bash -# Test bootstrap functionality -go run main.go bootstrap --mode=oss-tenant --non-interactive +#!/bin/bash +# scripts/test-bootstrap.sh +set -e -# Test cluster operations -go run main.go cluster create test-cluster -go run main.go cluster status test-cluster -go run main.go cluster delete test-cluster +echo "Testing bootstrap command..." +./openframe bootstrap test-cluster --deployment-mode=oss-tenant --non-interactive -# Test chart operations -go run main.go chart install test-app --repo=https://charts.example.com -go run main.go chart list +echo "Testing cluster status..." +./openframe cluster status -# Test development tools -go run main.go dev scaffold my-service --template=microservice -go run main.go dev intercept my-service --port=3000:8080 +echo "Cleaning up..." +./openframe cluster delete test-cluster ``` -### Integration Testing +## Debug Configuration -Test with real Kubernetes clusters: +### Command Line Debugging ```bash -# Create test cluster -k3d cluster create openframe-test --agents 2 +# Debug with delve +dlv debug ./main.go -- bootstrap --verbose + +# Debug with specific breakpoints +dlv debug ./main.go +(dlv) break main.main +(dlv) break cmd/bootstrap.(*Service).Execute +(dlv) continue +``` -# Run your changes against the cluster -KUBECONFIG=$(k3d kubeconfig write openframe-test) go run main.go bootstrap +### Logging and Observability -# Verify results -kubectl get pods --all-namespaces -kubectl get applications -n argocd +```bash +# Enable debug logging +export OPENFRAME_LOG_LEVEL=debug +./openframe bootstrap --verbose -# Clean up -k3d cluster delete openframe-test +# Custom logging configuration +export OPENFRAME_LOG_FORMAT=json +export OPENFRAME_LOG_OUTPUT=/tmp/openframe.log ``` -### Performance Testing - -Monitor resource usage and performance: +### Profiling During Development ```bash -# Build optimized binary -go build -ldflags="-s -w" -o openframe main.go - -# Monitor memory usage -/usr/bin/time -v ./openframe bootstrap - -# Profile CPU usage -CPUPROFILE=cpu.prof go run main.go bootstrap +# CPU profiling +go build -o openframe ./main.go +./openframe bootstrap --cpuprofile=cpu.prof go tool pprof cpu.prof -# Profile memory usage -MEMPROFILE=mem.prof go run main.go bootstrap +# Memory profiling +go build -gcflags="-m" -o openframe ./main.go +./openframe bootstrap --memprofile=mem.prof go tool pprof mem.prof ``` -## Code Quality +## Local Development Workflows -### Automated Checks - -Run all quality checks before committing: +### Feature Development ```bash -#!/bin/bash -# quality-check.sh +# 1. Create feature branch +git checkout -b feature/new-deployment-mode -echo "Running code quality checks..." +# 2. Make changes and test locally +go run ./main.go bootstrap --deployment-mode=new-mode -# Format code -echo "Formatting code..." -gofmt -l -w . -goimports -l -w . - -# Vet code -echo "Vetting code..." -go vet ./... +# 3. Run tests +go test ./... -# Run linter -echo "Running linter..." +# 4. Lint code golangci-lint run -# Run tests -echo "Running tests..." -go test -race -cover ./... - -# Check for security issues -echo "Checking security..." -gosec ./... - -# Check dependencies -echo "Checking dependencies..." -go mod tidy -go mod verify - -echo "All checks passed!" +# 5. Commit and push +git add . +git commit -m "Add new deployment mode" +git push origin feature/new-deployment-mode ``` -Make it executable and run: +### Bug Fixing + ```bash -chmod +x quality-check.sh -./quality-check.sh -``` +# 1. Reproduce the bug locally +./openframe bootstrap --verbose 2>&1 | tee debug.log -### Manual Code Review +# 2. Add debug logging +export OPENFRAME_LOG_LEVEL=debug -Before submitting changes, review: +# 3. Use debugger to investigate +dlv debug ./main.go -- bootstrap -1. **Code Structure**: Is the code well-organized and follows Go conventions? -2. **Error Handling**: Are errors properly handled and user-friendly? -3. **Documentation**: Are public functions and packages documented? -4. **Tests**: Are there adequate unit and integration tests? -5. **Performance**: Are there any obvious performance issues? +# 4. Write failing test +go test -run TestBugRepro ./internal/bootstrap/ -## Advanced Development +# 5. Fix and verify +go test ./internal/bootstrap/ +``` -### Working with Dependencies +### Performance Investigation ```bash -# Add a new dependency -go get github.com/new/dependency@latest +# 1. Benchmark current performance +go test -bench=. -benchmem ./... -# Update dependencies -go get -u ./... +# 2. Profile specific operations +go test -cpuprofile=cpu.prof -bench=BenchmarkBootstrap ./internal/bootstrap/ -# Vendor dependencies (if needed) -go mod vendor - -# Remove unused dependencies -go mod tidy +# 3. Analyze results +go tool pprof cpu.prof ``` -### Working with Build Tags +## Local Environment Configuration -Use build tags for conditional compilation: +### Configuration Files -```go -// +build debug +Create local configuration for development: -package debug +```yaml +# ~/.openframe/config.yaml +development: + log_level: debug + cluster_prefix: dev- + auto_cleanup: true + timeout: 30m -func init() { - // Debug-only initialization -} +clusters: + default_mode: oss-tenant + auto_install_charts: true + +charts: + argocd_version: "5.46.7" + timeout: "10m" ``` -```bash -# Build with debug tag -go build -tags debug -o openframe-debug main.go +### Environment Variables -# Run tests with integration tag -go test -tags integration ./... +```bash +# Development environment setup +export OPENFRAME_CONFIG_FILE=$HOME/.openframe/config.yaml +export OPENFRAME_DEV_MODE=true +export OPENFRAME_CLUSTER_PREFIX=dev-$(whoami)- +export OPENFRAME_AUTO_CLEANUP=true + +# Kubernetes development +export KUBECONFIG=$HOME/.kube/config +export K3D_FIX_DNS=1 + +# Docker development +export DOCKER_BUILDKIT=1 +export DOCKER_CLI_EXPERIMENTAL=enabled ``` -### Cross-platform Development +## Troubleshooting Local Development -Build for multiple platforms: +### Common Build Issues ```bash -# Build for Linux -GOOS=linux GOARCH=amd64 go build -o openframe-linux main.go - -# Build for Windows -GOOS=windows GOARCH=amd64 go build -o openframe.exe main.go +# Go module issues +go clean -modcache +go mod download +go mod tidy -# Build for macOS (Intel) -GOOS=darwin GOARCH=amd64 go build -o openframe-darwin-amd64 main.go +# Build cache issues +go clean -cache +go build -a ./... -# Build for macOS (Apple Silicon) -GOOS=darwin GOARCH=arm64 go build -o openframe-darwin-arm64 main.go +# Dependency conflicts +go mod graph | grep conflicting-package +go mod why problematic-dependency ``` -## Troubleshooting - -### Common Development Issues +### Runtime Issues -#### Module Problems ```bash -# Clear module cache -go clean -modcache - -# Reinitialize modules -rm go.sum -go mod tidy -``` +# Docker daemon not running +sudo systemctl start docker -#### Build Errors -```bash -# Clean build cache -go clean -cache +# K3d clusters conflicting +k3d cluster list +k3d cluster delete --all -# Rebuild everything -go build -a main.go +# Port conflicts +sudo netstat -tulpn | grep :8080 +sudo lsof -i :8080 ``` -#### Test Failures +### Performance Issues + ```bash -# Run tests with verbose output -go test -v -race ./... +# Memory usage monitoring +go build -race -o openframe ./main.go +./openframe bootstrap --memprofile=mem.prof -# Run specific failing test -go test -v -run TestSpecificFunction ./path/to/package +# CPU usage monitoring +go build -o openframe ./main.go +./openframe bootstrap --cpuprofile=cpu.prof ``` -#### Kubernetes Context Issues -```bash -# Check current context -kubectl config current-context +## Development Best Practices -# Switch to correct context -kubectl config use-context k3d-openframe-local +### Code Organization -# Verify cluster connectivity -kubectl cluster-info -``` +- Keep command implementations in `cmd/` directories simple +- Put business logic in `internal/` packages +- Use `pkg/` for reusable public packages +- Write testable code with dependency injection + +### Testing Strategy -### Debug Environment Variables +- Write unit tests for all business logic +- Use integration tests for end-to-end workflows +- Mock external dependencies (Docker, K3d, kubectl) +- Test error conditions and edge cases -Set these for debugging: +### Version Control ```bash -export GODEBUG="gctrace=1" # GC tracing -export GOTRACEBACK="all" # Full stack traces -export OPENFRAME_LOG_LEVEL="debug" # Detailed logging -export KUBECONFIG="$HOME/.kube/config" -``` +# Commit message format +git commit -m "feat(cluster): add multi-node support -## Next Steps +- Add node count configuration to cluster creation +- Update cluster status to show all nodes +- Add validation for node resource requirements -Now that you have a working development environment: +Closes #123" -1. **[Architecture Overview](../architecture/README.md)** - Understand the system design -2. **[Contributing Guidelines](../contributing/guidelines.md)** - Learn the contribution process -3. **[Testing Guide](../testing/README.md)** - Deep dive into testing strategies +# Keep commits atomic +git add cmd/cluster/create.go +git commit -m "feat(cluster): add node count parameter" -## Getting Help +git add internal/cluster/service.go +git commit -m "feat(cluster): implement multi-node creation" +``` -If you encounter issues: +## Next Steps + +With local development set up: -- **Check existing issues**: Search GitHub issues for similar problems -- **Ask in Slack**: Join the [OpenMSP community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) -- **Review documentation**: Check other guides in this repository -- **Debug systematically**: Use logging and debugging tools to isolate issues +1. **[Architecture Overview](../architecture/README.md)** - Understand the system design +2. **[Testing Guide](../testing/README.md)** - Learn the testing approach +3. **[Contributing Guidelines](../contributing/guidelines.md)** - Follow contribution standards -Happy coding! ๐Ÿš€ \ No newline at end of file +> ๐Ÿš€ **Pro Tip**: Start by exploring existing commands to understand the patterns, then try modifying a simple command before building new features from scratch. \ No newline at end of file diff --git a/docs/getting-started/first-steps.md b/docs/getting-started/first-steps.md index 24c144d6..dda21a6b 100644 --- a/docs/getting-started/first-steps.md +++ b/docs/getting-started/first-steps.md @@ -1,467 +1,296 @@ # First Steps with OpenFrame CLI -Now that you have OpenFrame CLI installed and your first environment bootstrapped, let's explore the key features and workflows. This guide covers the essential first steps to get you productive with OpenFrame. +Now that you have OpenFrame CLI running, let's explore the key features and workflows that will make you productive immediately. ## Your First 5 Actions -### 1. Explore the CLI Structure +### 1. Explore Your Cluster -Get familiar with the command hierarchy: +Start by understanding what you've created: ```bash -# See all available commands -openframe --help - -# Explore each command group -openframe cluster --help -openframe chart --help -openframe dev --help -openframe bootstrap --help -``` - -The CLI is organized into logical groups: -- **bootstrap**: One-time environment setup -- **cluster**: Kubernetes cluster lifecycle -- **chart**: Application and service deployment -- **dev**: Development and debugging tools - -### 2. Check Your Environment Status - -Verify everything is running correctly: - -```bash -# Overall cluster health +# Get detailed cluster information openframe cluster status -# List all running clusters +# List all available clusters openframe cluster list -# Check installed charts and applications -openframe chart list +# Check cluster nodes and resources +kubectl get nodes -o wide +kubectl get namespaces ``` -Expected healthy output: -```text -๐Ÿ“Š Cluster Status: openframe-local -โœ… Cluster is running -โœ… ArgoCD is healthy -โœ… All core services operational -``` +**What you'll see:** +- Cluster health status and resource usage +- Available namespaces including `argocd` +- Node information and networking details -### 3. Access the ArgoCD Dashboard +### 2. Navigate the ArgoCD Interface -ArgoCD provides a web interface for GitOps deployments: +Access your GitOps dashboard: ```bash -# Get admin password -kubectl -n argocd get secret argocd-initial-admin-secret \ - -o jsonpath="{.data.password}" | base64 -d; echo +# Get ArgoCD admin password +kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d -# Port forward to access UI +# Access ArgoCD UI kubectl port-forward svc/argocd-server -n argocd 8080:443 - -# Open in browser: https://localhost:8080 -# Username: admin -# Password: (from command above) ``` -In the ArgoCD UI, you'll see: -- **Applications**: Deployed services and components -- **Repositories**: Connected Git repositories -- **Settings**: Configuration and policies -- **User Info**: Access controls and authentication +Open `https://localhost:8080` and explore: +- **Applications**: View deployed applications and their sync status +- **Repositories**: See connected Git repositories +- **Clusters**: Manage target deployment clusters +- **Settings**: Configure projects, repositories, and RBAC -### 4. Deploy Your First Application +### 3. Deploy Your First Application via GitOps -Let's deploy a simple application to test the workflow: +Create a simple application using ArgoCD: ```bash -# Create a test namespace -kubectl create namespace hello-world - -# Deploy a sample application -kubectl apply -f - < my-first-app.yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application metadata: - name: hello-world - namespace: hello-world + name: guestbook + namespace: argocd spec: - selector: - app: hello-world - ports: - - protocol: TCP - port: 80 - targetPort: 80 + project: default + source: + repoURL: https://github.com/argoproj/argocd-example-apps.git + targetRevision: HEAD + path: guestbook + destination: + server: https://kubernetes.default.svc + namespace: default + syncPolicy: + automated: + prune: true + selfHeal: true EOF + +# Apply the application +kubectl apply -f my-first-app.yaml + +# Watch the deployment +kubectl get pods -w ``` -Verify the deployment: -```bash -# Check pods -kubectl get pods -n hello-world +### 4. Try Development Workflows -# Check service -kubectl get svc -n hello-world +Explore the development commands: -# Test connectivity -kubectl port-forward svc/hello-world -n hello-world 8081:80 & -curl http://localhost:8081 -kill %1 # Stop port forward +```bash +# View available development tools +openframe dev --help + +# List available development commands +openframe dev ``` -### 5. Set Up Your Development Environment +**Available workflows:** +- **Traffic Interception**: Route cluster traffic to local development +- **Live Reloading**: Deploy with automatic updates on code changes + +### 5. Practice Resource Management -Configure kubectl context and helpful aliases: +Learn essential management commands: ```bash -# Set default context -kubectl config use-context k3d-openframe-local - -# Add helpful aliases to your shell profile -cat >> ~/.bashrc << 'EOF' -# OpenFrame aliases -alias of="openframe" -alias ofcs="openframe cluster status" -alias ofcl="openframe cluster list" -alias k="kubectl" -alias kgp="kubectl get pods" -alias kgs="kubectl get svc" -alias kgn="kubectl get nodes" -EOF +# Monitor cluster health +openframe cluster status -# Reload shell configuration -source ~/.bashrc -``` +# Clean up unused resources +openframe cluster cleanup -## Key Workflows to Learn - -### Cluster Management Workflow - -```mermaid -flowchart TD - A[Create Cluster] --> B[Check Status] - B --> C[Deploy Applications] - C --> D[Monitor Health] - D --> E{Issues?} - E -->|Yes| F[Debug & Fix] - E -->|No| G[Continue Development] - F --> D - G --> H[Scale or Update] - H --> D +# View cluster resource usage +kubectl top nodes +kubectl top pods --all-namespaces ``` -#### Common Cluster Commands -```bash -# Create a new cluster -openframe cluster create my-new-cluster +## Essential Configuration -# List all clusters -openframe cluster list +### Set Up Your Development Environment -# Get detailed status -openframe cluster status my-cluster +Create a development workspace: -# Delete a cluster -openframe cluster delete my-cluster +```bash +# Create development namespace +kubectl create namespace dev -# Clean up resources -openframe cluster cleanup +# Set as default namespace +kubectl config set-context --current --namespace=dev ``` -### Application Deployment Workflow - -```mermaid -sequenceDiagram - participant Dev as Developer - participant CLI as OpenFrame CLI - participant ArgoCD as ArgoCD - participant K8s as Kubernetes - - Dev->>CLI: openframe chart install - CLI->>ArgoCD: Create Application - ArgoCD->>K8s: Deploy Resources - K8s-->>ArgoCD: Resource Status - ArgoCD-->>CLI: Sync Status - CLI-->>Dev: Deployment Complete -``` +### Configure Git Integration + +For GitOps workflows, ensure Git is configured: -#### Common Chart Commands ```bash -# Install a chart from repository -openframe chart install my-app \ - --repo=https://github.com/my-org/my-app \ - --path=charts/my-app +# Configure Git (if not already done) +git config --global user.name "Your Name" +git config --global user.email "your.email@example.com" -# List installed applications -openframe chart list +# Generate SSH key for Git repositories (if needed) +ssh-keygen -t ed25519 -C "your.email@example.com" +``` -# Check application sync status -kubectl get applications -n argocd +## Exploring Key Features -# Manually sync an application -kubectl patch application my-app -n argocd \ - --type=json \ - -p='[{"op": "replace", "path": "/spec/syncPolicy", "value": {"automated": {"selfHeal": true}}}]' -``` +### Cluster Management Features -### Development Workflow +| Feature | Command | Purpose | +|---------|---------|---------| +| **Status Monitoring** | `openframe cluster status` | Check cluster health and resources | +| **Multi-Cluster** | `openframe cluster list` | Manage multiple development clusters | +| **Resource Cleanup** | `openframe cluster cleanup` | Remove unused Docker images and resources | +| **Safe Deletion** | `openframe cluster delete ` | Remove clusters with confirmation | -For local development with live Kubernetes integration: +### GitOps Capabilities + +- **Automated Deployment**: Applications sync automatically from Git +- **Self-Healing**: ArgoCD corrects configuration drift +- **Rollback Support**: Easy rollback to previous versions +- **Multi-Environment**: Manage dev, staging, and production environments + +### Development Workflows ```bash -# Start a development intercept -openframe dev intercept my-service \ - --namespace=default \ - --port=3000:8080 - -# Generate scaffold for new service -openframe dev scaffold my-new-service \ - --template=microservice \ - --language=go +# Example: Set up traffic interception (requires Telepresence) +openframe dev intercept my-service --port 8080 + +# Example: Use live development (requires Skaffold) +openframe dev skaffold my-app ``` -## Essential Configuration +## Common Initial Configuration -### Customize OpenFrame Settings +### 1. Customize Cluster Settings -Create a configuration file for personalized settings: +Create a cluster with custom configuration: ```bash -mkdir -p ~/.openframe -cat > ~/.openframe/config.yaml << 'EOF' -# OpenFrame CLI Configuration -default: - cluster_name: "openframe-local" - namespace: "default" - log_level: "info" - -bootstrap: - mode: "oss-tenant" - interactive: true - timeout: "15m" - -cluster: - provider: "k3d" - nodes: 1 - -chart: - timeout: "10m" - wait: true - -dev: - intercept_timeout: "5m" - scaffold_templates_dir: "~/.openframe/templates" -EOF +# Interactive cluster creation with custom settings +openframe cluster create my-custom-cluster ``` -### Configure Git Integration +You'll be prompted for: +- Node configuration +- Network settings +- Resource limits +- Add-on installations + +### 2. Set Up Persistent Storage -For ArgoCD to access your repositories: +Configure persistent volumes for stateful applications: ```bash -# Add a Git repository to ArgoCD -kubectl apply -f - < - username: + name: local-storage +provisioner: kubernetes.io/no-provisioner +volumeBindingMode: WaitForFirstConsumer EOF ``` -### Set Up Ingress (Optional) +### 3. Configure Network Policies -Configure Traefik ingress for external access: +Set up basic security with network policies: ```bash -# Create an ingress for your application -kubectl apply -f - < -n +# View cluster events +kubectl get events --sort-by='.lastTimestamp' -# Check logs -kubectl logs -n +# Check pod logs +kubectl logs -f -# Check resource constraints -kubectl get resourcequota -n +# Describe problematic resources +kubectl describe pod +kubectl describe node ``` -#### Service Not Accessible +### Cleanup Commands ```bash -# Check service endpoints -kubectl get endpoints -n +# Remove failed pods +kubectl delete pods --field-selector=status.phase=Failed --all-namespaces -# Test internal connectivity -kubectl run test-pod --image=busybox -it --rm -- sh -# Inside pod: -wget -q -O- http://..svc.cluster.local -``` +# Clean up completed jobs +kubectl delete jobs --field-selector=status.successful=1 --all-namespaces -#### ArgoCD Application Not Syncing -```bash -# Check application status -kubectl get application -n argocd -o yaml - -# Force refresh -kubectl patch application -n argocd \ - --type=json \ - -p='[{"op": "replace", "path": "/spec/source/targetRevision", "value": "HEAD"}]' - -# Manual sync -kubectl patch application -n argocd \ - --type=json \ - -p='[{"op": "add", "path": "/metadata/annotations/argocd.argoproj.io~1sync", "value": ""}]' +# Full cluster cleanup +openframe cluster cleanup ``` -## Best Practices - -### Development Environment -1. **Use namespaces**: Organize applications by environment or team -2. **Resource limits**: Set appropriate CPU/memory limits -3. **Health checks**: Implement liveness and readiness probes -4. **Secrets management**: Use Kubernetes secrets, not hardcoded values - -### GitOps Workflow -1. **Infrastructure as Code**: Store all configurations in Git -2. **Automated sync**: Enable ArgoCD auto-sync for non-production -3. **Manual approval**: Require manual sync for production deployments -4. **Rollback strategy**: Use Git reverts for quick rollbacks - -### Cluster Management -1. **Regular backups**: Backup cluster state and data -2. **Monitor resources**: Set up alerts for resource usage -3. **Update strategy**: Plan regular updates for cluster components -4. **Security scanning**: Regularly scan images and configurations - -## Next Steps - -Now that you're familiar with OpenFrame basics, explore advanced topics: - -### Development Workflows -Learn how to set up a complete development environment: -- Configure your IDE and editor -- Set up local development workflows -- Use service intercepts for debugging - -### Architecture Understanding -Dive deeper into how OpenFrame components work: -- Study the service architecture -- Understand data flows and dependencies -- Learn about security models and best practices - -### Advanced Deployment Patterns -Master sophisticated deployment strategies: -- Blue/green deployments -- Canary releases -- Multi-environment promotion pipelines - -## Getting Help +## Where to Get Help ### Community Resources -- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) for questions and support -- **Documentation**: Explore other guides in this repository -- **Examples**: Check the examples directory for sample configurations +- **OpenMSP Slack**: [Join here](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) +- **OpenFrame Website**: [openframe.ai](https://openframe.ai) +- **Flamingo Stack**: [flamingo.run](https://flamingo.run) -### Useful Commands Reference -```bash -# Quick status check -openframe cluster status +### Documentation +- **ArgoCD Documentation**: [argoproj.github.io/argo-cd](https://argo-cd.readthedocs.io/) +- **K3d Documentation**: [k3d.io](https://k3d.io/) +- **Kubernetes Documentation**: [kubernetes.io/docs](https://kubernetes.io/docs/) -# View all resources -kubectl get all --all-namespaces +### Command Help +```bash +# Get help for any command +openframe --help +openframe bootstrap --help +openframe cluster --help +openframe dev --help -# Emergency cluster reset -openframe cluster delete -openframe bootstrap +# Get command usage examples +openframe bootstrap --help | grep -A 10 "Examples:" +``` -# Export current configuration -kubectl get all -o yaml > backup.yaml +## Next Steps in Your Journey -# View OpenFrame CLI logs -openframe --verbose -``` +Now that you're familiar with the basics: -### Debugging Resources -- ArgoCD UI: https://localhost:8080 (after port forward) -- Traefik Dashboard: https://localhost:9000 (after port forward) -- Kubernetes Dashboard: Install with `kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml` +1. **Set up a real application** using GitOps workflows +2. **Explore advanced features** like traffic interception and live development +3. **Configure CI/CD pipelines** that deploy to your cluster +4. **Join the community** to share experiences and get help +5. **Contribute back** by reporting issues or suggesting improvements -You're now ready to be productive with OpenFrame CLI! Explore the features, experiment with deployments, and join the community for support and sharing experiences. \ No newline at end of file +> ๐Ÿš€ **Pro Tip**: Start small with simple applications and gradually add complexity as you become more comfortable with the GitOps workflow and Kubernetes patterns. \ No newline at end of file diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index 2c2771af..b59605dd 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -1,142 +1,113 @@ # Introduction to OpenFrame CLI -OpenFrame CLI is a modern, interactive command-line tool for managing OpenFrame Kubernetes clusters and development workflows. It provides seamless cluster lifecycle management, chart installation with ArgoCD, and developer-friendly tools for service intercepts and scaffolding. +Welcome to OpenFrame CLI - a comprehensive command-line interface for bootstrapping and managing Kubernetes clusters with GitOps automation for MSP (Managed Service Provider) environments. -[![OpenFrame Product Walkthrough (Beta Access)](https://img.youtube.com/vi/awc-yAnkhIo/maxresdefault.jpg)](https://www.youtube.com/watch?v=awc-yAnkhIo) +[![Getting Started with OpenFrame - Organization Setup Basics](https://img.youtube.com/vi/-_56_qYvMWk/maxresdefault.jpg)](https://www.youtube.com/watch?v=-_56_qYvMWk) ## What is OpenFrame CLI? -OpenFrame CLI is part of the broader OpenFrame ecosystem - an AI-powered MSP platform that replaces expensive proprietary software with open-source alternatives enhanced by intelligent automation. The CLI serves as the entry point for developers and operators to bootstrap, manage, and develop on OpenFrame environments. +OpenFrame CLI is a streamlined tool that automates the complete setup and management of Kubernetes development environments. It combines cluster creation, ArgoCD installation, and development workflow tools into a single, unified interface. -## Key Features - -### ๐Ÿš€ Complete Environment Bootstrapping -- **One-command setup**: Bootstrap entire OpenFrame environments with `openframe bootstrap` -- **Multi-mode deployment**: Support for OSS tenant, SaaS tenant, and SaaS shared modes -- **Automated cluster creation**: Creates K3D clusters with all necessary components -- **ArgoCD integration**: Automatic chart installation and application management - -### ๐Ÿ”ง Cluster Management -- **Lifecycle operations**: Create, delete, list, and monitor Kubernetes clusters -- **K3D integration**: Lightweight Kubernetes for development and testing -- **Status monitoring**: Real-time cluster health and resource monitoring -- **Easy cleanup**: Remove clusters and associated resources with simple commands - -### ๐Ÿ“ฆ Chart & Application Management -- **Helm chart installation**: Streamlined chart deployment with dependency management -- **ArgoCD applications**: GitOps-based application lifecycle management -- **App-of-apps pattern**: Hierarchical application management for complex deployments -- **Synchronization monitoring**: Track deployment progress with detailed logging - -### ๐Ÿ›  Development Tools -- **Service intercepts**: Local development with Telepresence integration -- **Scaffolding**: Generate boilerplate code and configurations -- **Live debugging**: Debug services running in Kubernetes from your local environment -- **Hot reload**: Rapid development cycles with instant feedback - -## Target Audience - -### DevOps Engineers -- Simplify Kubernetes cluster management -- Automate deployment pipelines with GitOps -- Monitor and maintain OpenFrame environments +### Elevator Pitch -### Software Developers -- Develop and test microservices locally -- Debug applications running in Kubernetes -- Scaffold new services and components quickly +**"From zero to GitOps-enabled Kubernetes cluster in minutes"** - OpenFrame CLI eliminates the complexity of setting up local development environments by automating cluster creation with K3d, installing ArgoCD for GitOps workflows, and providing integrated development tools. -### System Administrators -- Bootstrap complete OpenFrame environments -- Manage multiple clusters and deployments -- Monitor system health and performance +## Key Features -### MSP Teams -- Deploy OpenFrame for multiple tenants -- Manage client environments efficiently -- Reduce vendor costs with open-source alternatives +- **๐Ÿš€ One-Command Bootstrap**: Complete environment setup with `openframe bootstrap` +- **๐ŸŽฏ Interactive Wizards**: Guided cluster creation and configuration +- **๐Ÿ“ฆ GitOps Integration**: Automatic ArgoCD installation and app-of-apps pattern +- **๐Ÿ”ง Development Tools**: Traffic interception and live reloading capabilities +- **๐Ÿงน Resource Management**: Cleanup and status monitoring commands +- **๐ŸŒ Multi-Platform**: Support for multiple deployment modes (OSS tenant, SaaS shared, SaaS tenant) ## Architecture Overview ```mermaid graph TB - subgraph "CLI Commands" - Bootstrap[openframe bootstrap] - Cluster[openframe cluster] - Chart[openframe chart] - Dev[openframe dev] - end + CLI[OpenFrame CLI] --> Bootstrap[Bootstrap Command] + CLI --> Cluster[Cluster Management] + CLI --> Chart[Chart Management] + CLI --> Dev[Development Tools] - subgraph "Core Services" - ClusterSvc[Cluster Management] - ChartSvc[Chart Installation] - DevSvc[Development Tools] - end + Bootstrap --> ClusterCreate[Cluster Creation] + Bootstrap --> ChartInstall[Chart Installation] - subgraph "External Tools" - K3D[K3D Clusters] - Helm[Helm Charts] - ArgoCD[ArgoCD Apps] - Telepresence[Service Intercepts] - end + Cluster --> Create[Create Clusters] + Cluster --> Delete[Delete Clusters] + Cluster --> List[List Clusters] + Cluster --> Status[Status Check] + Cluster --> Cleanup[Resource Cleanup] - subgraph "Target Environment" - K8s[Kubernetes] - Apps[Applications] - Services[Microservices] - end + Chart --> ArgoCD[ArgoCD Installation] + Chart --> AppOfApps[App-of-Apps Setup] - Bootstrap --> ClusterSvc - Bootstrap --> ChartSvc - Cluster --> ClusterSvc - Chart --> ChartSvc - Dev --> DevSvc + Dev --> Intercept[Traffic Interception] + Dev --> Skaffold[Live Development] - ClusterSvc --> K3D - ChartSvc --> Helm - ChartSvc --> ArgoCD - DevSvc --> Telepresence + subgraph Infrastructure[Infrastructure Layer] + K3d[K3d Clusters] + Kubernetes[Kubernetes API] + ArgoCDSvc[ArgoCD GitOps] + end - K3D --> K8s - Helm --> Apps - ArgoCD --> Apps - Telepresence --> Services + Create --> K3d + ArgoCD --> Kubernetes + Intercept --> Kubernetes ``` -## Key Benefits +## Target Audience + +OpenFrame CLI is designed for: + +- **DevOps Engineers** setting up local Kubernetes environments +- **Platform Engineers** standardizing development workflows +- **MSP Providers** deploying standardized environments for clients +- **Developers** needing local Kubernetes clusters with GitOps capabilities +- **Teams** adopting GitOps practices and ArgoCD workflows + +## Core Benefits | Benefit | Description | |---------|-------------| -| **Rapid Setup** | Go from zero to running OpenFrame environment in minutes | -| **Developer Friendly** | Interactive prompts, helpful error messages, and clear documentation | -| **Production Ready** | Battle-tested components with enterprise-grade reliability | -| **Open Source** | Complete transparency, community-driven development | -| **Cost Effective** | Replace expensive proprietary tools with open-source alternatives | -| **GitOps Native** | Built-in ArgoCD integration for modern deployment practices | +| **Speed** | Complete cluster setup in under 5 minutes | +| **Consistency** | Standardized environments across teams | +| **GitOps Ready** | ArgoCD pre-configured with app-of-apps pattern | +| **Developer Friendly** | Traffic interception and live reload capabilities | +| **Resource Efficient** | K3d-based lightweight clusters | +| **Easy Cleanup** | One-command resource cleanup and management | -## How It Works +## Getting Started Journey -1. **Bootstrap**: Run `openframe bootstrap` to create a complete environment -2. **Develop**: Use `openframe dev` commands for local development workflows -3. **Deploy**: Manage applications with `openframe chart` commands -4. **Monitor**: Check cluster status with `openframe cluster` commands +Your journey with OpenFrame CLI follows this path: -The CLI handles all the complexity of Kubernetes cluster management, chart installations, and development tool configuration, allowing you to focus on building and deploying applications. +1. **[Prerequisites](prerequisites.md)** - Install required tools and check system requirements +2. **[Quick Start](quick-start.md)** - Get your first cluster running in 5 minutes +3. **[First Steps](first-steps.md)** - Explore key features and workflows -## Next Steps +## Command Categories -Ready to get started? Continue with these guides: +| Category | Commands | Purpose | +|----------|----------|---------| +| **Bootstrap** | `bootstrap` | Complete environment setup | +| **Cluster** | `create`, `delete`, `list`, `status`, `cleanup` | Cluster lifecycle management | +| **Chart** | `install` | ArgoCD and Helm chart management | +| **Development** | `intercept`, `skaffold` | Development workflow tools | -- **[Prerequisites](prerequisites.md)** - Check system requirements and install dependencies -- **[Quick Start](quick-start.md)** - Get OpenFrame running in 5 minutes -- **[First Steps](first-steps.md)** - Explore key features and workflows +## What Makes OpenFrame CLI Different? -## Community and Support +Unlike traditional Kubernetes setup tools, OpenFrame CLI: -OpenFrame is built by the community for the community. Get help and connect with other users: +- **Combines multiple tools** into a single workflow (K3d + ArgoCD + development tools) +- **Provides interactive wizards** instead of requiring complex configuration files +- **Includes cleanup and management** commands for ongoing operations +- **Integrates development workflows** with traffic interception and live reloading +- **Supports multiple deployment modes** for different MSP scenarios + +## Community and Support -- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) -- **Website**: [https://flamingo.run](https://flamingo.run) -- **OpenFrame Platform**: [https://openframe.ai](https://openframe.ai) +- **OpenMSP Slack Community**: [Join our Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) +- **Website**: [flamingo.run](https://flamingo.run) +- **OpenFrame Platform**: [openframe.ai](https://openframe.ai) -> **Note**: We don't use GitHub Issues or Discussions - all support and community interaction happens in the OpenMSP Slack community. \ No newline at end of file +> ๐Ÿ’ก **Note**: OpenFrame CLI is part of the larger OpenFrame ecosystem that integrates multiple MSP tools into a unified AI-driven platform for automating IT support operations. \ No newline at end of file diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md index 314e0978..26fc9a5d 100644 --- a/docs/getting-started/prerequisites.md +++ b/docs/getting-started/prerequisites.md @@ -1,315 +1,194 @@ # Prerequisites -Before installing and using OpenFrame CLI, ensure your system meets the following requirements and has the necessary dependencies installed. +Before using OpenFrame CLI, ensure your system meets the requirements and has the necessary tools installed. ## System Requirements -### Hardware Requirements +| Requirement | Minimum | Recommended | Notes | +|-------------|---------|-------------|-------| +| **Memory** | 24GB RAM | 32GB RAM | Kubernetes clusters require significant memory | +| **CPU** | 6 cores | 12 cores | Multi-core beneficial for parallel operations | +| **Disk Space** | 50GB free | 100GB free | Docker images and cluster data | +| **Operating System** | Linux, macOS, Windows | Linux/macOS | Windows requires WSL2 | -| Resource | Minimum | Recommended | -|----------|---------|-------------| -| **RAM** | 24GB | 32GB | -| **CPU Cores** | 6 cores | 12 cores | -| **Disk Space** | 50GB free | 100GB free | -| **Architecture** | x86_64, ARM64 | x86_64, ARM64 | +## Required Software -### Operating System Support - -| OS | Version | Status | -|---|---------|--------| -| **Linux** | Ubuntu 20.04+, CentOS 8+, RHEL 8+ | โœ… Fully Supported | -| **macOS** | 11+ (Big Sur and later) | โœ… Fully Supported | -| **Windows** | Windows 10/11 with WSL2 | โš ๏ธ Supported via WSL2 | +### Core Dependencies -> **Windows Users**: OpenFrame CLI requires WSL2 for proper Kubernetes integration. Native Windows support is not currently available. +| Tool | Minimum Version | Installation | Purpose | +|------|----------------|--------------|---------| +| **Docker** | 20.10+ | [Get Docker](https://docs.docker.com/get-docker/) | Container runtime for K3d clusters | +| **K3d** | 5.0+ | [Install K3d](https://k3d.io/v5.6.0/#installation) | Lightweight Kubernetes clusters | +| **kubectl** | 1.24+ | [Install kubectl](https://kubernetes.io/docs/tasks/tools/) | Kubernetes command-line interface | +| **Helm** | 3.8+ | [Install Helm](https://helm.sh/docs/intro/install/) | Kubernetes package manager | -## Required Dependencies +### OpenFrame CLI -### Core Dependencies +Download the latest OpenFrame CLI for your platform: -These tools must be installed before using OpenFrame CLI: +| Platform | Download Link | +|----------|---------------| +| **Windows (AMD64)** | [openframe-cli_windows_amd64.zip](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip) | +| **Linux (AMD64)** | [openframe-cli_linux_amd64.tar.gz](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz) | +| **macOS (Intel)** | [openframe-cli_darwin_amd64.tar.gz](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_amd64.tar.gz) | +| **macOS (Apple Silicon)** | [openframe-cli_darwin_arm64.tar.gz](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz) | -| Tool | Version | Purpose | Installation | -|------|---------|---------|--------------| -| **Docker** | 20.10+ | Container runtime for K3D clusters | [Docker Install Guide](https://docs.docker.com/get-docker/) | -| **kubectl** | 1.25+ | Kubernetes command-line tool | [kubectl Install Guide](https://kubernetes.io/docs/tasks/tools/) | -| **Helm** | 3.10+ | Kubernetes package manager | [Helm Install Guide](https://helm.sh/docs/intro/install/) | -| **K3D** | 5.0+ | Lightweight Kubernetes clusters | [K3D Install Guide](https://k3d.io/v5.4.6/#installation) | +### Development Tools (Optional) -### Development Dependencies (Optional) +For development workflows, install these additional tools: -Required only if using development features (`openframe dev` commands): +| Tool | Purpose | Installation | +|------|---------|--------------| +| **Telepresence** | Traffic interception | [Install Telepresence](https://www.telepresence.io/docs/latest/install/) | +| **Skaffold** | Live development | [Install Skaffold](https://skaffold.dev/docs/install/) | -| Tool | Version | Purpose | Installation | -|------|---------|---------|--------------| -| **Telepresence** | 2.10+ | Service intercepts for local development | [Telepresence Install](https://www.telepresence.io/docs/latest/install/) | -| **jq** | 1.6+ | JSON processing for dev scripts | [jq Install Guide](https://jqlang.github.io/jq/download/) | +## Installation Steps -## Installation Verification +### 1. Install Core Dependencies -### Check Docker +**Docker** ```bash +# Verify Docker installation docker --version docker ps ``` -Expected output: -```text -Docker version 20.10.0 or higher -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -``` - -### Check kubectl +**K3d** ```bash -kubectl version --client -``` +# Install K3d (Linux/macOS) +curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash -Expected output: -```text -Client Version: version.Info{Major:"1", Minor:"25"+...} +# Verify K3d +k3d version ``` -### Check Helm +**kubectl** ```bash -helm version -``` +# Install kubectl (Linux) +curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" +chmod +x kubectl +sudo mv kubectl /usr/local/bin/ -Expected output: -```text -version.BuildInfo{Version:"v3.10.0"+...} +# Verify kubectl +kubectl version --client ``` -### Check K3D +**Helm** ```bash -k3d version -``` +# Install Helm (Linux/macOS) +curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash -Expected output: -```text -k3d version v5.0.0+ +# Verify Helm +helm version ``` -### Check Telepresence (Optional) +### 2. Install OpenFrame CLI + +**Linux/macOS** ```bash -telepresence version -``` +# Download and extract +curl -L "https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz" | tar xz -Expected output: -```text -Client: v2.10.0+ -``` +# Make executable and move to PATH +chmod +x openframe +sudo mv openframe /usr/local/bin/openframe -### Check jq (Optional) -```bash -jq --version +# Verify installation +openframe --version ``` -Expected output: -```text -jq-1.6+ -``` +**Windows (PowerShell)** +```bash +# Download the zip file +Invoke-WebRequest -Uri "https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip" -OutFile "openframe-cli.zip" -## Network Requirements +# Extract and run +Expand-Archive -Path "openframe-cli.zip" -DestinationPath "." -### Outbound Connectivity -OpenFrame CLI requires internet access for: -- Pulling Docker images -- Downloading Helm charts -- Accessing Git repositories -- Installing prerequisites - -### Port Requirements -| Port Range | Protocol | Purpose | -|------------|----------|---------| -| 80, 443 | TCP | HTTPS/HTTP for downloads | -| 6443 | TCP | Kubernetes API server | -| 30000-32767 | TCP | Kubernetes NodePort range | -| 2376, 2377 | TCP | Docker daemon (if remote) | - -### Firewall Considerations -Ensure your firewall allows: -- Docker daemon communication -- Kubernetes cluster communication -- Outbound HTTPS connections +# Add to PATH or run directly +./openframe.exe --version +``` ## Environment Variables Set these environment variables for optimal experience: -### Required ```bash -# Docker daemon configuration -export DOCKER_HOST="unix:///var/run/docker.sock" +# Docker configuration +export DOCKER_HOST=unix:///var/run/docker.sock # Kubernetes configuration -export KUBECONFIG="$HOME/.kube/config" -``` +export KUBECONFIG=$HOME/.kube/config -### Optional -```bash -# OpenFrame CLI configuration -export OPENFRAME_LOG_LEVEL="info" -export OPENFRAME_CONFIG_DIR="$HOME/.openframe" - -# Development tools -export TELEPRESENCE_LOGIN_DOMAIN="auth.datawire.io" +# Optional: Set default cluster name +export OPENFRAME_CLUSTER_NAME=openframe-dev ``` -## Account Requirements +## Network Requirements -### Container Registry Access -- **Public registries**: Docker Hub, GHCR.io (no authentication required) -- **Private registries**: Configure Docker credentials if using private images +Ensure these network configurations: -### Git Repository Access -- **Public repositories**: No authentication required -- **Private repositories**: Configure SSH keys or personal access tokens +- **Docker daemon** running and accessible +- **Port availability**: 80, 443, 6443, 8080-8090 (for cluster services) +- **Internet access** for downloading images and charts +- **DNS resolution** working correctly -## Quick Setup Script +## Verification Commands -For convenience, here's a script to verify all prerequisites: +Run these commands to verify your setup: ```bash -#!/bin/bash -# prerequisites-check.sh - -echo "๐Ÿ” Checking OpenFrame CLI prerequisites..." - -# Function to check if command exists -command_exists() { - command -v "$1" >/dev/null 2>&1 -} - -# Function to check version -check_version() { - local tool="$1" - local min_version="$2" - local current_version="$3" - - echo " $tool: $current_version (required: $min_version+)" -} - -errors=0 - # Check Docker -if command_exists docker; then - docker_version=$(docker --version | cut -d' ' -f3 | cut -d',' -f1) - check_version "Docker" "20.10.0" "$docker_version" - if ! docker ps >/dev/null 2>&1; then - echo " โŒ Docker daemon is not running or accessible" - ((errors++)) - fi -else - echo " โŒ Docker not found" - ((errors++)) -fi +docker run hello-world + +# Check K3d +k3d cluster list # Check kubectl -if command_exists kubectl; then - kubectl_version=$(kubectl version --client -o json 2>/dev/null | jq -r '.clientVersion.gitVersion' 2>/dev/null || echo "unknown") - check_version "kubectl" "1.25.0" "$kubectl_version" -else - echo " โŒ kubectl not found" - ((errors++)) -fi +kubectl cluster-info # Check Helm -if command_exists helm; then - helm_version=$(helm version --short | cut -d'+' -f1) - check_version "Helm" "3.10.0" "$helm_version" -else - echo " โŒ Helm not found" - ((errors++)) -fi - -# Check K3D -if command_exists k3d; then - k3d_version=$(k3d version | grep k3d | cut -d' ' -f2) - check_version "K3D" "5.0.0" "$k3d_version" -else - echo " โŒ K3D not found" - ((errors++)) -fi - -# Check optional tools -echo "" -echo "๐Ÿ“‹ Optional development tools:" - -if command_exists telepresence; then - telepresence_version=$(telepresence version --output=json 2>/dev/null | jq -r '.client.version' 2>/dev/null || "unknown") - check_version "Telepresence" "2.10.0" "$telepresence_version" -else - echo " โš ๏ธ Telepresence not found (optional for dev workflows)" -fi - -if command_exists jq; then - jq_version=$(jq --version | cut -d'-' -f2) - check_version "jq" "1.6" "$jq_version" -else - echo " โš ๏ธ jq not found (optional for dev scripts)" -fi - -echo "" -if [ $errors -eq 0 ]; then - echo "โœ… All required prerequisites are installed!" - echo "๐Ÿš€ You're ready to install OpenFrame CLI" -else - echo "โŒ $errors required dependencies are missing" - echo "๐Ÿ“– Please install missing dependencies before proceeding" - exit 1 -fi -``` - -Save this as `prerequisites-check.sh`, make it executable, and run: +helm repo list -```bash -chmod +x prerequisites-check.sh -./prerequisites-check.sh +# Check OpenFrame CLI +openframe --help ``` ## Troubleshooting Common Issues -### Docker Permission Issues -If you get permission denied errors: - +### Docker Issues ```bash -# Add your user to the docker group -sudo usermod -aG docker $USER +# Start Docker daemon (Linux) +sudo systemctl start docker -# Log out and back in, or run: +# Add user to docker group (Linux) +sudo usermod -aG docker $USER newgrp docker ``` -### kubectl Not Finding Config +### K3d Issues ```bash -# Create kubeconfig directory -mkdir -p ~/.kube +# Check Docker is running +docker ps -# Verify KUBECONFIG environment variable -echo `$KUBECONFIG` +# Reset K3d if needed +k3d cluster delete --all ``` -### K3D Installation Issues on macOS +### Kubectl Issues ```bash -# If using Homebrew -brew install k3d +# Check kubeconfig +kubectl config get-contexts -# If using curl -curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash +# Reset kubeconfig if needed +kubectl config unset current-context ``` -### WSL2 Setup on Windows -1. Enable WSL2: `wsl --install` -2. Install Ubuntu from Microsoft Store -3. Install Docker Desktop with WSL2 backend -4. Install all prerequisites inside WSL2 environment - ## Next Steps -Once all prerequisites are installed and verified: +Once prerequisites are installed: -1. **[Quick Start Guide](quick-start.md)** - Install OpenFrame CLI and bootstrap your first environment -2. **[First Steps Guide](first-steps.md)** - Explore key features and workflows +1. **[Quick Start Guide](quick-start.md)** - Create your first cluster in 5 minutes +2. **[First Steps Guide](first-steps.md)** - Explore key features after setup -Need help? Join our community: -- **OpenMSP Slack**: [Join here](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) \ No newline at end of file +> ๐Ÿ”ง **Having issues?** Join our [OpenMSP Slack community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) for help and support. \ No newline at end of file diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index 72253b3f..83150f84 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -1,290 +1,215 @@ # Quick Start Guide -Get OpenFrame CLI up and running in 5 minutes! This guide will walk you through installing OpenFrame CLI and bootstrapping your first environment. +Get your first OpenFrame environment running in under 5 minutes with this streamlined guide. -[![OpenFrame: 5-Minute MSP Platform Walkthrough - Cut Vendor Costs & Automate Ops](https://img.youtube.com/vi/er-z6IUnAps/maxresdefault.jpg)](https://www.youtube.com/watch?v=er-z6IUnAps) +[![OpenFrame Product Walkthrough (Beta Access)](https://img.youtube.com/vi/awc-yAnkhIo/maxresdefault.jpg)](https://www.youtube.com/watch?v=awc-yAnkhIo) ## TL;DR - 5-Minute Setup -If you have all prerequisites installed, here's the fastest path: - ```bash -# 1. Download and install OpenFrame CLI (choose your platform) -# Linux/macOS -curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar -xz -sudo mv openframe /usr/local/bin/ - -# Windows (download manually) -# Download: https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip - -# 2. Verify installation -openframe --version +# 1. Bootstrap complete environment +openframe bootstrap my-first-cluster -# 3. Bootstrap complete environment -openframe bootstrap - -# 4. Check cluster status +# 2. Verify cluster is running openframe cluster status + +# 3. Check ArgoCD installation +kubectl get pods -n argocd ``` -That's it! Continue reading for detailed steps and explanations. +That's it! You now have a fully functional Kubernetes cluster with ArgoCD GitOps capabilities. -## Step 1: Install OpenFrame CLI +## Step-by-Step Walkthrough -### Option A: Download Pre-built Binary (Recommended) +### Step 1: Bootstrap Your Environment -Choose your platform and download the latest release: +The `bootstrap` command combines cluster creation and chart installation into one seamless operation: -#### Linux (AMD64) ```bash -curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar -xz -sudo mv openframe /usr/local/bin/ -chmod +x /usr/local/bin/openframe +openframe bootstrap ``` -#### Linux (ARM64) -```bash -curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_arm64.tar.gz | tar -xz -sudo mv openframe /usr/local/bin/ -chmod +x /usr/local/bin/openframe -``` +This command will: +1. Show the OpenFrame logo and welcome message +2. Prompt you for cluster configuration +3. Create a K3d cluster with your settings +4. Install ArgoCD with GitOps configuration +5. Set up the app-of-apps pattern -#### macOS (AMD64) -```bash -curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_amd64.tar.gz | tar -xz -sudo mv openframe /usr/local/bin/ -chmod +x /usr/local/bin/openframe -``` +**Expected output:** +```text +๐Ÿš€ OpenFrame CLI - MSP Kubernetes Environment Manager -#### macOS (Apple Silicon) -```bash -curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz | tar -xz -sudo mv openframe /usr/local/bin/ -chmod +x /usr/local/bin/openframe -``` +โœ“ Creating cluster: openframe-dev +โœ“ Installing ArgoCD charts +โœ“ Configuring app-of-apps pattern +โœ“ Environment ready! -#### Windows (AMD64) -1. Download: https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip -2. Extract the ZIP file -3. Move `openframe.exe` to a directory in your `PATH` -4. Open WSL2 terminal and verify access +Cluster: openframe-dev +ArgoCD URL: https://localhost:8080 +``` -### Option B: Build from Source +### Step 2: Verify Your Installation -If you have Go 1.24.6+ installed: +Check that your cluster is running correctly: ```bash -# Clone the repository -git clone https://github.com/flamingo-stack/openframe-cli.git -cd openframe-cli - -# Build the binary -go build -o openframe main.go - -# Move to PATH -sudo mv openframe /usr/local/bin/ -``` - -## Step 2: Verify Installation +# View cluster status +openframe cluster status -Confirm OpenFrame CLI is installed correctly: +# List all clusters +openframe cluster list -```bash -openframe --version +# Check Kubernetes nodes +kubectl get nodes ``` -Expected output: +**Expected output:** ```text -openframe version v1.x.x (commit: abc123, built: 2024-01-01) -``` - -Check available commands: -```bash -openframe --help +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Cluster Name โ”‚ Status โ”‚ Nodes โ”‚ Version โ”‚ Age โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ openframe-dev โ”‚ Ready โ”‚ 1/1 โ”‚ v1.27.4 โ”‚ 2m โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` -You should see the main command groups: -- `bootstrap` - Complete environment setup -- `cluster` - Kubernetes cluster management -- `chart` - Helm chart and ArgoCD management -- `dev` - Development tools and workflows +### Step 3: Explore ArgoCD -## Step 3: Bootstrap Your First Environment - -The bootstrap command creates a complete OpenFrame environment with a single command: +Verify ArgoCD is installed and running: ```bash -openframe bootstrap -``` +# Check ArgoCD pods +kubectl get pods -n argocd -### Interactive Bootstrap +# Get ArgoCD admin password +kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d -The command will guide you through setup with prompts: +# Port forward to access ArgoCD UI (optional) +kubectl port-forward svc/argocd-server -n argocd 8080:443 +``` -```text -๐Ÿš€ OpenFrame Bootstrap Wizard +Access ArgoCD at `https://localhost:8080` with: +- Username: `admin` +- Password: (from the command above) -? Select deployment mode: - > oss-tenant (Single tenant, open source) - saas-tenant (Multi-tenant SaaS mode) - saas-shared (Shared SaaS infrastructure) +## Basic "Hello World" Example -? Enable verbose logging? (y/N): y +Let's deploy a simple application to verify everything works: -๐Ÿ” Checking prerequisites... -โœ… Docker is running -โœ… kubectl is available -โœ… Helm is available -โœ… K3D is available +```bash +# Create a simple deployment +kubectl create deployment hello-openframe --image=nginx -๐ŸŽฏ Creating K3D cluster... -โœ… Cluster 'openframe-local' created +# Expose the deployment +kubectl expose deployment hello-openframe --port=80 --target-port=80 -๐ŸŽญ Installing ArgoCD... -โœ… ArgoCD installed and ready +# Check the deployment +kubectl get deployments +kubectl get services +``` -๐Ÿ“ฆ Installing application charts... -โœ… App-of-apps synchronized -โœ… All applications healthy +**Expected output:** +```text +NAME READY UP-TO-DATE AVAILABLE AGE +hello-openframe 1/1 1 1 30s -๐ŸŽ‰ OpenFrame environment is ready! +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +hello-openframe ClusterIP 10.43.123.456 80/TCP 20s ``` -### Non-Interactive Bootstrap - -For scripts and CI/CD, use flags to skip prompts: +## Configuration Options -```bash -openframe bootstrap \ - --mode=oss-tenant \ - --non-interactive \ - --verbose -``` +### Non-Interactive Mode -## Step 4: Verify Your Environment +For CI/CD or automated deployments: -### Check Cluster Status ```bash -openframe cluster status +# Skip all prompts with predefined deployment mode +openframe bootstrap --deployment-mode=oss-tenant --non-interactive ``` -Expected output: -```text -๐Ÿ“Š Cluster Status: openframe-local - -Cluster Info: - Name: openframe-local - Status: Running โœ… - Nodes: 1 (1 ready) - Kubernetes Version: v1.28.6+k3s1 - -Resource Usage: - CPU: 2 cores (25% used) - Memory: 8Gi (45% used) - Storage: 50Gi (12% used) - -Key Services: - ArgoCD: Healthy โœ… - Traefik: Healthy โœ… - CoreDNS: Healthy โœ… -``` +### Verbose Mode -### Access ArgoCD UI -The bootstrap process installs ArgoCD. Access the web interface: +For detailed logging and troubleshooting: ```bash -# Get ArgoCD URL and credentials -kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo -kubectl port-forward svc/argocd-server -n argocd 8080:443 +# Show detailed progress including ArgoCD sync +openframe bootstrap --verbose ``` -Then open: http://localhost:8080 -- Username: `admin` -- Password: (from the command above) +### Custom Cluster Name -### View Running Applications ```bash -# List all pods across namespaces -kubectl get pods --all-namespaces - -# Check ArgoCD applications -kubectl get applications -n argocd +# Specify custom cluster name +openframe bootstrap my-custom-cluster ``` -## Step 5: Test Basic Functionality +## Deployment Modes -### Create a Test Namespace -```bash -kubectl create namespace test-app -kubectl get namespaces -``` +| Mode | Description | Use Case | +|------|-------------|----------| +| `oss-tenant` | Open-source tenant configuration | Development and testing | +| `saas-tenant` | SaaS tenant setup | Multi-tenant environments | +| `saas-shared` | SaaS shared configuration | Shared service platforms | -### Deploy a Simple Application -```bash -# Create a test deployment -kubectl create deployment nginx --image=nginx:latest -n test-app -kubectl expose deployment nginx --port=80 --target-port=80 -n test-app +## What You Just Created -# Check deployment -kubectl get pods -n test-app -kubectl get svc -n test-app -``` +Your OpenFrame environment includes: -### Test Service Access -```bash -# Port forward to test connectivity -kubectl port-forward svc/nginx -n test-app 8081:80 & +### Infrastructure Components +- **K3d Cluster**: Lightweight Kubernetes cluster running in Docker +- **ArgoCD**: GitOps continuous delivery platform +- **Helm Charts**: Pre-configured application templates -# Test the service -curl http://localhost:8081 +### Network Configuration +- **Cluster Network**: Internal pod-to-pod communication +- **Service Discovery**: DNS-based service resolution +- **Load Balancing**: K3d load balancer for external access -# Clean up -kill %1 # Stop port-forward -kubectl delete namespace test-app -``` +### GitOps Setup +- **App-of-Apps Pattern**: ArgoCD managing multiple applications +- **Automated Sync**: Continuous deployment from Git repositories +- **Declarative Configuration**: Infrastructure as code approach -## What Just Happened? +## Quick Verification Checklist -The bootstrap process created: +Ensure everything is working: -1. **K3D Cluster**: A lightweight Kubernetes cluster running in Docker -2. **ArgoCD**: GitOps deployment tool for application management -3. **Traefik**: Ingress controller for routing traffic -4. **Core Services**: DNS, metrics, and monitoring components -5. **Application Templates**: Ready-to-use deployment patterns +- [ ] `openframe cluster status` shows "Ready" +- [ ] `kubectl get nodes` shows cluster nodes +- [ ] `kubectl get pods -n argocd` shows ArgoCD pods running +- [ ] ArgoCD UI accessible at `https://localhost:8080` +- [ ] Sample deployment successful -## Expected Results +## What's Next? -After successful bootstrap: +Now that your environment is running: -| Component | Status | Access Method | -|-----------|--------|---------------| -| **Kubernetes API** | โœ… Running | `kubectl` commands | -| **ArgoCD UI** | โœ… Running | Port forward to 8080 | -| **Traefik Dashboard** | โœ… Running | Port forward to 9000 | -| **Container Registry** | โœ… Running | Docker daemon | +1. **[First Steps Guide](first-steps.md)** - Explore key features and capabilities +2. **Development Setup** - Configure your development workflow +3. **Application Deployment** - Deploy your first real application via GitOps -## Troubleshooting +## Cleaning Up + +When you're done experimenting: -### Bootstrap Fails with Docker Error ```bash -# Check Docker status -docker ps -docker info +# Delete the cluster +openframe cluster delete openframe-dev -# Restart Docker if needed -sudo systemctl restart docker # Linux -# or restart Docker Desktop on macOS/Windows +# Clean up Docker resources +openframe cluster cleanup ``` -### Kubectl Cannot Connect +## Troubleshooting + +### Cluster Creation Failed ```bash -# Check kubeconfig -kubectl config current-context -kubectl config get-contexts +# Check Docker is running +docker ps -# Switch to openframe context if needed -kubectl config use-context k3d-openframe-local +# Try with verbose logging +openframe bootstrap --verbose ``` ### ArgoCD Not Accessible @@ -292,64 +217,15 @@ kubectl config use-context k3d-openframe-local # Check ArgoCD pods kubectl get pods -n argocd -# Restart ArgoCD if needed -kubectl rollout restart deployment argocd-server -n argocd -``` - -### Port Already in Use -```bash -# Find and kill processes using required ports -lsof -ti:6443,8080,9000 | xargs kill -9 - -# Or use different ports -kubectl port-forward svc/argocd-server -n argocd 8081:443 -``` - -## Next Steps - -๐ŸŽ‰ **Congratulations!** You now have a running OpenFrame environment. Here's what to explore next: - -- **[First Steps Guide](first-steps.md)** - Learn key workflows and features -- **[Architecture Overview](../development/architecture/README.md)** - Understand how components work together -- **[Development Setup](../development/setup/local-development.md)** - Configure your development environment - -## Common Next Actions - -### Deploy Your First Application -```bash -# Use ArgoCD to deploy from Git -openframe chart install my-app \ - --repo=https://github.com/your-org/your-app \ - --path=helm-chart -``` - -### Start Local Development -```bash -# Intercept a service for local development -openframe dev intercept my-service \ - --namespace=default \ - --port=8080:3000 +# Restart port-forward +kubectl port-forward svc/argocd-server -n argocd 8080:443 ``` -### Explore the Environment +### Network Issues ```bash -# List available commands -openframe --help - -# Get cluster information -openframe cluster list -openframe cluster status - -# Check chart installations -openframe chart list +# Reset cluster networking +openframe cluster delete openframe-dev +openframe bootstrap --verbose ``` -## Getting Help - -Need assistance? The OpenFrame community is here to help: - -- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) -- **Documentation**: Browse other guides in this repository -- **GitHub Issues**: Report bugs or request features (but use Slack for general support) - -> **Note**: All community support happens in Slack - we don't monitor GitHub Issues for support requests. \ No newline at end of file +> ๐ŸŽ‰ **Congratulations!** You've successfully set up your first OpenFrame environment. Head to the [First Steps Guide](first-steps.md) to explore what you can do next. \ No newline at end of file From 3610fcc1518c151aa1cccf08afc1dcb7239ef669 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 28 May 2026 04:23:11 +0000 Subject: [PATCH 6/6] docs: Stage 4 - Repository documentation (4 files) [skip ci] --- CONTRIBUTING.md | 510 +++++++++++++++++++++++++----------------------- README.md | 269 ++++++++++++------------- SECURITY.md | 8 +- docs/README.md | 190 +++++++++--------- 4 files changed, 506 insertions(+), 471 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5be2c28..64f80d29 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,323 +1,353 @@ # Contributing to OpenFrame CLI -We're excited that you're interested in contributing to OpenFrame CLI! This guide will help you get started with contributing to the project. +Welcome to the OpenFrame CLI community! We're excited to have you contribute to our mission of simplifying Kubernetes cluster management and GitOps workflows for MSP environments. -## Getting Started +## ๐Ÿš€ Quick Start for Contributors -### Prerequisites +### Prerequisites for Development -Before you begin, ensure you have: +- **Go 1.21+** - [Install Go](https://golang.org/doc/install) +- **Docker 20.10+** - [Get Docker](https://docs.docker.com/get-docker/) +- **Git** - [Install Git](https://git-scm.com/downloads) +- **Make** - For build automation -- Go 1.24.6 or higher -- Docker 20.10+ (with daemon running) -- kubectl 1.25+ -- Helm 3.10+ -- K3D 5.0+ -- Git +**Hardware Requirements:** +- Minimum: 24GB RAM, 6 CPU cores, 50GB disk +- Recommended: 32GB RAM, 12 CPU cores, 100GB disk -### Development Environment Setup +### Development Setup -1. **Fork and Clone the Repository** ```bash -# Fork the repo on GitHub, then clone your fork -git clone https://github.com/YOUR_USERNAME/openframe-cli.git +# 1. Clone the repository +git clone https://github.com/flamingo-stack/openframe-cli.git cd openframe-cli -# Add upstream remote -git remote add upstream https://github.com/flamingo-stack/openframe-cli.git +# 2. Install dependencies +go mod download +go mod tidy + +# 3. Build the CLI +go build -o openframe ./main.go + +# 4. Run tests +go test ./... + +# 5. Verify your setup +./openframe --help ``` -2. **Set Up Your Development Environment** +## ๐Ÿ—๏ธ Development Workflow -Follow the [Development Environment Setup](./docs/development/setup/environment.md) guide for detailed IDE configuration, tools, and environment variables. +### Setting Up Your Development Environment -3. **Install Go Tools** ```bash -# Install essential Go development tools -go install golang.org/x/tools/cmd/goimports@latest -go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest -go install github.com/rakyll/gotest@latest +# Set up development environment variables +export OPENFRAME_DEV_MODE=true +export OPENFRAME_LOG_LEVEL=debug + +# Configure Git (if not already done) +git config --global user.name "Your Name" +git config --global user.email "your.email@example.com" ``` -4. **Build and Test** -```bash -# Build the project -go build -o openframe main.go +### Making Changes -# Run tests -go test ./... +1. **Create a feature branch**: + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Make your changes** following our coding standards + +3. **Test locally**: + ```bash + # Run unit tests + go test ./... + + # Run with race detection + go test -race ./... + + # Test the CLI functionality + ./openframe bootstrap test-cluster --verbose + ``` + +4. **Lint your code**: + ```bash + golangci-lint run + ``` + +5. **Commit and push**: + ```bash + git add . + git commit -m "feat(component): add new feature + + - Detailed description of the change + - Why this change is needed + - Any breaking changes + + Closes #123" + git push origin feature/your-feature-name + ``` + +## ๐Ÿ“ Contribution Guidelines + +### Code Standards + +- **Test Coverage**: Minimum 80% for new code +- **Linting**: All code must pass `golangci-lint` +- **Documentation**: Public APIs must have Go doc comments +- **Error Handling**: All errors must be properly handled and meaningful +- **Logging**: Use structured logging with appropriate levels + +### Commit Message Format + +Follow the conventional commit format: -# Run linter -golangci-lint run ``` +(): -## Development Workflow + -### Branch Management +