[network-check] Implement "local" mode

Tool: gitpod/catfood.gitpod.cloud

Author: geropl

gitpod-network-check/cmd/checks.go

@@ -12,28 +12,6 @@ import (
 	testrunner "github.com/gitpod-io/enterprise-deployment-toolkit/gitpod-network-check/pkg/runner"
 )
 
-type Mode string
-
-const (
-	ModeEC2    Mode = "ec2"
-	ModeLambda Mode = "lambda"
-)
-
-var validModes = map[string]bool{
-	string(ModeLambda): true,
-	string(ModeEC2):    true,
-}
-
-var flags = struct {
-	// Variable to store the testsets flag value
-	SelectedTestsets []string
-
-	// Variable to store the mode flag value
-	ModeVar string
-
-	Mode Mode
-}{}
-
 var checkCommand = &cobra.Command{ // nolint:gochecknoglobals
 	PersistentPreRunE: validateArguments,
 	Use:               "diagnose",
@@ -42,15 +20,17 @@ var checkCommand = &cobra.Command{ // nolint:gochecknoglobals
 	RunE: func(cmd *cobra.Command, args []string) error {
 		ctx := cmd.Context()
 
-		var runner testrunner.TestRunner
-		if flags.Mode == ModeEC2 {
-			ec2Runner, err := testrunner.NewEC2TestRunner(ctx, &networkConfig)
-			if err != nil {
-				return fmt.Errorf("❌  failed to create EC2 test runner: %v", err)
-			}
-			runner = ec2Runner
+		runner, err := testrunner.NewRunner(ctx, flags.Mode, &networkConfig)
+		if err != nil {
+			return fmt.Errorf("❌  failed to create test runner: %v", err)
 		}
+
 		defer (func() {
+			// Ensure runner was actually assigned before trying to clean up
+			if runner == nil {
+				log.Info("ℹ️  No runner initialized, skipping cleanup.")
+				return
+			}
 			log.Infof("ℹ️  Running cleanup")
 			terr := runner.Cleanup(ctx)
 			if terr != nil {
@@ -60,7 +40,7 @@ var checkCommand = &cobra.Command{ // nolint:gochecknoglobals
 		})()
 
 		// Prepare
-		err := runner.Prepare(ctx)
+		err = runner.Prepare(ctx)
 		if err != nil {
 			return fmt.Errorf("❌  failed to prepare: %v", err)
 		}
@@ -92,12 +72,6 @@ var checkCommand = &cobra.Command{ // nolint:gochecknoglobals
 }
 
 func validateArguments(cmd *cobra.Command, args []string) error {
-	// Validate mode
-	if !validModes[flags.ModeVar] {
-		return fmt.Errorf("invalid mode: %s, must be one of: %v", flags.ModeVar, maps.Keys(validModes))
-	}
-	flags.Mode = Mode(flags.ModeVar)
-
 	// Validate testsets if specified
 	if len(flags.SelectedTestsets) > 0 {
 		for _, testset := range flags.SelectedTestsets {

gitpod-network-check/cmd/cleanup.go

@@ -10,17 +10,16 @@ import (
 )
 
 var cleanCommand = &cobra.Command{ // nolint:gochecknoglobals
-	PersistentPreRunE: validateSubnets,
 	Use:               "clean",
 	Short:             "Explicitly cleans up after the network check diagnosis",
 	SilenceUsage:      false,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		ctx := cmd.Context()
 
 		log.Infof("ℹ️ Running cleanup")
-		runner, err := runner.LoadEC2RunnerFromTags(ctx, &networkConfig)
+		runner, err := runner.NewRunner(ctx, flags.Mode, &networkConfig)
 		if err != nil {
-			log.WithError(err).Fatal("Failed to load EC2 runner")
+			return fmt.Errorf("❌  failed to create test runner: %v", err)
 		}
 
 		err = runner.Cleanup(ctx)

gitpod-network-check/cmd/root.go

@@ -13,10 +13,21 @@ import (
 	"github.com/spf13/viper"
 
 	"github.com/gitpod-io/enterprise-deployment-toolkit/gitpod-network-check/pkg/checks"
+	"github.com/gitpod-io/enterprise-deployment-toolkit/gitpod-network-check/pkg/runner"
 )
 
 var networkConfig = checks.NetworkConfig{LogLevel: "INFO"}
 
+var flags = struct {
+	// Variable to store the testsets flag value
+	SelectedTestsets []string
+
+	// Variable to store the mode flag value
+	ModeVar string
+
+	Mode runner.Mode
+}{}
+
 var networkCheckCmd = &cobra.Command{ // nolint:gochecknoglobals
 	PersistentPreRunE: preRunE,
 	Use:               "gitpod-network-check",
@@ -28,16 +39,24 @@ func preRunE(cmd *cobra.Command, args []string) error {
 	// setup logger
 	lvl, err := log.ParseLevel(networkConfig.LogLevel)
 	if err != nil {
-		log.WithField("log-level", networkConfig.CfgFile).Fatal("incorrect log level")
-
-		return fmt.Errorf("incorrect log level")
+		return fmt.Errorf("❌  incorrect log level: %v", err)
 	}
 
 	log.SetLevel(lvl)
 	log.WithField("log-level", networkConfig.CfgFile).Debug("log level configured")
 
 	// validate the config
-	return validateSubnets(cmd, args)
+	err = validateSubnets(cmd, args)
+	if err != nil {
+		return fmt.Errorf("❌  incorrect subnets: %v", err)
+	}
+
+	err = validateMode(cmd, args)
+	if err != nil {
+		return fmt.Errorf("❌  incorrect mode: %v", err)
+	}
+
+	return nil
 }
 
 func validateSubnets(cmd *cobra.Command, args []string) error {
@@ -53,6 +72,17 @@ func validateSubnets(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+func validateMode(cmd *cobra.Command, args []string) error {
+	// Validate mode
+	mode, err := runner.VaildateMode(flags.ModeVar)
+	if err != nil {
+		return err
+	}
+	flags.Mode = mode
+
+	return nil
+}
+
 func bindFlags(cmd *cobra.Command, v *viper.Viper) {
 	cmd.PersistentFlags().VisitAll(func(f *pflag.Flag) {
 		// Environment variables can't have dashes in them, so bind them to their equivalent
@@ -95,8 +125,8 @@ func init() {
 	networkCheckCmd.PersistentFlags().StringSliceVar(&networkConfig.HttpsHosts, "https-hosts", []string{}, "Hosts to test for outbound HTTPS connectivity")
 	networkCheckCmd.PersistentFlags().StringVar(&networkConfig.InstanceAMI, "instance-ami", "", "Custom ec2 instance AMI id, if not set will use latest ubuntu")
 	networkCheckCmd.PersistentFlags().StringVar(&networkConfig.ApiEndpoint, "api-endpoint", "", "The Gitpod Enterprise control plane's regional API endpoint subdomain")
-	networkCheckCmd.Flags().StringSliceVar(&flags.SelectedTestsets, "testsets", []string{"aws-services-pod-subnet", "aws-services-main-subnet", "https-hosts-main-subnet"}, "List of testsets to run (options: aws-services-pod-subnet, aws-services-main-subnet, https-hosts-main-subnet)")
-	networkCheckCmd.Flags().StringVar(&flags.ModeVar, "mode", string(ModeEC2), "How to run the tests (default: ec2, options: ec2, lamda)")
+	networkCheckCmd.PersistentFlags().StringSliceVar(&flags.SelectedTestsets, "testsets", []string{"aws-services-pod-subnet", "aws-services-main-subnet", "https-hosts-main-subnet"}, "List of testsets to run (options: aws-services-pod-subnet, aws-services-main-subnet, https-hosts-main-subnet)")
+	networkCheckCmd.PersistentFlags().StringVar(&flags.ModeVar, "mode", string(runner.ModeEC2), "How to run the tests (default: ec2, options: ec2, lambda, local)")
 	bindFlags(networkCheckCmd, v)
 	log.Infof("ℹ️  Running with region `%s`, main subnet `%v`, pod subnet `%v`, hosts `%v`, ami `%v`, and API endpoint `%v`", networkConfig.AwsRegion, networkConfig.MainSubnets, networkConfig.PodSubnets, networkConfig.HttpsHosts, networkConfig.InstanceAMI, networkConfig.ApiEndpoint)
 }

gitpod-network-check/pkg/runner/common.go

@@ -2,19 +2,55 @@ package runner
 
 import (
 	"context"
+	"fmt"
+	"maps"
+	"slices"
 
 	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go-v2/config"
 
 	"github.com/gitpod-io/enterprise-deployment-toolkit/gitpod-network-check/pkg/checks"
 )
 
+type Mode string
+
+const (
+	ModeEC2    Mode = "ec2"
+	ModeLambda Mode = "lambda"
+	ModeLocal  Mode = "local"
+)
+
+var validModes = map[string]bool{
+	string(ModeLambda): true,
+	string(ModeEC2):    true,
+	string(ModeLocal):  true,
+}
+
+func VaildateMode(modeStr string) (Mode, error) {
+	if _, ok := validModes[modeStr]; ok {
+		return Mode(modeStr), nil
+	}
+	return "", fmt.Errorf("invalid mode: %s, must be one of: %v", modeStr, slices.Collect(maps.Keys(validModes)))
+}
+
 type TestRunner interface {
 	Prepare(ctx context.Context) error
 	TestService(ctx context.Context, subnets []checks.Subnet, serviceEndpoints map[string]string) (bool, error)
 	Cleanup(ctx context.Context) error
 }
 
+func NewRunner(ctx context.Context, mode Mode, config *checks.NetworkConfig) (TestRunner, error) {
+	switch mode {
+	case ModeEC2:
+		return NewEC2TestRunner(context.Background(), config)
+	case ModeLocal:
+		return NewLocalTestRunner(), nil
+	default:
+		return nil, fmt.Errorf("invalid mode: %s, must be one of: %v", mode, slices.Collect(maps.Keys(validModes)))
+	}
+	// TODO: Add logic for ModeLambda if/when implemented
+}
+
 func initAwsConfig(ctx context.Context, region string) (aws.Config, error) {
 	return config.LoadDefaultConfig(ctx, config.WithRegion(region))
 }

gitpod-network-check/pkg/runner/local-runner.go

@@ -0,0 +1,105 @@
+package runner
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/url"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+
+	"github.com/gitpod-io/enterprise-deployment-toolkit/gitpod-network-check/pkg/checks"
+)
+
+// LocalTestRunner executes network checks directly from the local machine.
+type LocalTestRunner struct {
+	// No fields needed for local runner currently
+}
+
+// NewLocalTestRunner creates a new instance of LocalTestRunner.
+func NewLocalTestRunner() *LocalTestRunner {
+	log.Info("ℹ️  Using local test runner")
+	return &LocalTestRunner{}
+}
+
+// Prepare performs any setup required for the local runner. Currently a no-op.
+func (r *LocalTestRunner) Prepare(ctx context.Context) error {
+	log.Debug("Local runner Prepare: No preparation needed.")
+	return nil // No setup needed for local execution
+}
+
+// TestService runs connectivity tests to the specified service endpoints from the local machine.
+// The subnets parameter is ignored in local mode.
+func (r *LocalTestRunner) TestService(ctx context.Context, subnets []checks.Subnet, serviceEndpoints map[string]string) (bool, error) {
+	log.Debugf("Local runner TestService: Ignoring subnets (%d provided)", len(subnets))
+	overallSuccess := true
+
+	httpClient := &http.Client{
+		Timeout: 15 * time.Second, // Sensible default timeout
+		Transport: &http.Transport{
+			// Consider adding proxy support if needed later
+			// Proxy: http.ProxyFromEnvironment,
+			DisableKeepAlives: true, // Avoid reusing connections for distinct tests
+		},
+	}
+
+	for name, endpointURL := range serviceEndpoints {
+		log.Infof("ℹ️  Testing connectivity to %s (%s) locally...", name, endpointURL)
+
+		// Ensure URL includes scheme
+		parsedURL, err := url.Parse(endpointURL)
+		if err != nil {
+			log.Errorf("❌ Failed to parse URL for %s (%s): %v", name, endpointURL, err)
+			overallSuccess = false
+			continue
+		}
+		if parsedURL.Scheme == "" {
+			// Default to HTTPS if no scheme is provided
+			parsedURL.Scheme = "https"
+			endpointURL = parsedURL.String()
+			log.Debugf("Assuming HTTPS for %s: %s", name, endpointURL)
+		}
+
+		req, err := http.NewRequestWithContext(ctx, http.MethodHead, endpointURL, nil)
+		if err != nil {
+			log.Errorf("❌ Failed to create request for %s (%s): %v", name, endpointURL, err)
+			overallSuccess = false
+			continue
+		}
+
+		// Add a user-agent?
+		// req.Header.Set("User-Agent", "gitpod-network-check/local")
+
+		resp, err := httpClient.Do(req)
+		if err != nil {
+			log.Errorf("❌ Failed to connect to %s (%s): %v", name, endpointURL, err)
+			overallSuccess = false
+			continue
+		}
+		resp.Body.Close() // Ensure body is closed even if not read
+
+		// Consider any 2xx or 3xx status code as success for a HEAD request.
+		// Some services might return 403 Forbidden for HEAD but are still reachable.
+		// Let's be lenient for now and accept anything < 500.
+		if resp.StatusCode >= 500 {
+			log.Errorf("❌ Connection test failed for %s (%s): Received status code %d", name, endpointURL, resp.StatusCode)
+			overallSuccess = false
+		} else {
+			log.Infof("✅ Successfully connected to %s (%s) - Status: %d", name, endpointURL, resp.StatusCode)
+		}
+	}
+
+	if !overallSuccess {
+		return false, fmt.Errorf("one or more local connectivity tests failed")
+	}
+
+	log.Info("✅ All local connectivity tests passed.")
+	return true, nil
+}
+
+// Cleanup performs any teardown required for the local runner. Currently a no-op.
+func (r *LocalTestRunner) Cleanup(ctx context.Context) error {
+	log.Debug("Local runner Cleanup: No cleanup needed.")
+	return nil // No cleanup needed for local execution
+}

memory-bank/activeContext.md

@@ -0,0 +1,19 @@
+# Active Context: gitpod-network-check (2025-04-03)
+
+**Current Focus:**
+
+Implement a new "local" execution mode for the `gitpod-network-check diagnose` command.
+
+**Recent Changes:**
+
+*   Memory Bank initialized (`projectbrief.md`, `productContext.md` created).
+*   Analysis of existing code (`cmd/checks.go`, `pkg/runner/common.go`, `pkg/runner/ec2-runner.go`, `cmd/root.go`) completed in PLAN MODE.
+*   Plan developed and approved for adding the `local` mode.
+
+**Next Steps:**
+
+1.  Create remaining core Memory Bank files (`systemPatterns.md`, `techContext.md`, `progress.md`).
+2.  Create `gitpod-network-check/pkg/runner/local-runner.go`.
+3.  Implement the `TestRunner` interface within `local-runner.go` using `net/http` for checks.
+4.  Update `gitpod-network-check/cmd/checks.go` to add the `local` mode constant, update `validModes`, and add instantiation logic for `LocalTestRunner`.
+5.  Update `gitpod-network-check/cmd/root.go` to modify the help text for the `--mode` flag.

memory-bank/productContext.md

@@ -0,0 +1,25 @@
+# Product Context: gitpod-network-check
+
+**Problem Solved:**
+
+Deploying Gitpod requires specific network configurations to allow communication between its components and various external services (AWS APIs, container registries, identity providers, etc.). Misconfigurations are common and can be difficult to diagnose, leading to deployment failures or runtime issues. This tool aims to proactively identify these network connectivity problems before or during Gitpod installation/updates.
+
+**How it Should Work:**
+
+The tool executes predefined sets of network connectivity tests (`TestSets`) targeting specific endpoints required by Gitpod. These tests are run from environments that simulate where Gitpod components would run (e.g., within specific AWS subnets).
+
+*   **Modes:** The tool supports different execution modes:
+    *   `ec2`: (Existing) Launches temporary EC2 instances in specified subnets to run tests. Requires AWS credentials and permissions.
+    *   `lambda`: (Planned/Partially Implemented?) Uses AWS Lambda functions for testing.
+    *   `local`: (Current Task) Runs tests directly from the machine executing the CLI using standard Go libraries. Useful for basic outbound checks or when AWS resources aren't desired/available.
+*   **Test Sets:** Groups of related checks (e.g., connectivity to core AWS services from pod subnets).
+*   **Configuration:** Network details (subnets, region) and test parameters (hosts) are provided via CLI flags or a configuration file.
+*   **Output:** Logs detailed information about each check, clearly indicating success or failure.
+*   **Cleanup:** Automatically removes any temporary resources created during the `ec2` mode run.
+
+**User Experience Goals:**
+
+*   **Simplicity:** Easy to run with sensible defaults.
+*   **Clarity:** Provide clear pass/fail results and informative error messages.
+*   **Flexibility:** Allow users to select specific test sets and execution modes.
+*   **Reliability:** Accurately reflect the network connectivity status relevant to Gitpod.