refactor: unify local image handling and fix operator tag usage

Consolidates duplicate code and improves type safety in local image detection and CSV patching:

- Extract shared image list logic into getExpectedImages() helper to eliminate duplication between detection and loading
- Fix bug where stackrox-operator incorrectly used mainTag instead of operatorTag
- Replace generic map navigation in CSV patching with type-safe clusterServiceVersion struct
- Unify shouldSkipCredentialVerification() and shouldSkipImagePullSecrets() into hasAllImagesLocally()
- Change CheckLocalImage to idiomatic (value, bool, error) return pattern
- Make ExtractKindClusterName and helper functions private
- Remove unused test cases and helper functions

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: GrimmiMeloni

README.md

@@ -106,16 +106,13 @@ When deploying to a kind cluster, roxie:
 
 - kind cluster (context name must start with "kind")
 - podman with images built locally
-- Images tagged with either:
-  - `localhost/stackrox/<image>:<tag>`
-  - `quay.io/<branding-org>/<image>:<tag>`
+- Images tagged with `quay.io/<branding-org>/<image>:<tag>`
 
 ### Supported Images
 
-- main
+- main, central-db
 - scanner, scanner-db
 - scanner-v4-db, scanner-v4-indexer, scanner-v4-matcher
-- central-db
 - stackrox-operator-bundle
 - stackrox-operator-index
 
@@ -136,7 +133,7 @@ make image
 
 # Deploy to kind - roxie automatically uses local images
 cd /path/to/roxie
-./roxie deploy both
+./roxie deploy
 ```
 
 ### Behavior

internal/cluster/kind.go

@@ -21,10 +21,10 @@ func isKindContext(contextName string) bool {
 	return strings.HasPrefix(strings.ToLower(contextName), "kind")
 }
 
-// ExtractKindClusterName extracts the cluster name from a kind context.
+// extractKindClusterName extracts the cluster name from a kind context.
 // For context "kind-acs", returns "acs".
 // For context "kind", returns "kind".
-func ExtractKindClusterName(contextName string) string {
+func extractKindClusterName(contextName string) string {
 	// Remove "kind-" prefix if present
 	if strings.HasPrefix(strings.ToLower(contextName), "kind-") {
 		return contextName[len("kind-"):]
@@ -39,5 +39,5 @@ func GetKindClusterName() string {
 	if !IsKindCluster() {
 		return ""
 	}
-	return ExtractKindClusterName(env.GetCurrentContext())
+	return extractKindClusterName(env.GetCurrentContext())
 }

internal/cluster/kind_test.go

@@ -82,9 +82,9 @@ func TestExtractKindClusterName(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			result := ExtractKindClusterName(tt.contextName)
+			result := extractKindClusterName(tt.contextName)
 			if result != tt.expected {
-				t.Errorf("ExtractKindClusterName(%q) = %v, want %v", tt.contextName, result, tt.expected)
+				t.Errorf("extractKindClusterName(%q) = %v, want %v", tt.contextName, result, tt.expected)
 			}
 		})
 	}

internal/deployer/deploy_via_operator.go

@@ -180,7 +180,7 @@ func (d *Deployer) prepareNamespace(ctx context.Context, namespace string) error
 	}
 
 	if env.GetCurrentClusterType() != env.InfraOpenShift4 {
-		if !d.shouldSkipImagePullSecrets() {
+		if !d.hasAllImagesLocally() {
 			if err := d.ensurePullSecretExists(ctx, namespace); err != nil {
 				return fmt.Errorf("ensuring image pull secret exists: %w", err)
 			}

internal/deployer/deployer.go

@@ -27,9 +27,6 @@ const (
 	// totalRequiredImages is the number of images needed for a complete deployment
 	// (7 main images + 2 operator images: stackrox-operator + stackrox-operator-bundle).
 	// Main images: main, scanner, scanner-db, scanner-v4, scanner-v4-db, central-db, collector
-	// Note: scanner-v4 is a single image that runs in different modes (indexer/matcher)
-	//       based on runtime configuration.
-	// Note: operator-index is not included as roxie doesn't use it in default (non-OLM) mode.
 	totalRequiredImages = 9
 
 	// skipLocalImagesEnvVar is the environment variable name to disable local image detection.
@@ -134,9 +131,8 @@ type Deployer struct {
 	earlyReadiness         bool
 	dockerCreds            *dockerauth.Credentials
 	clusterResourceKinds   map[string]struct{}
-	// New fields for local image support
-	localImages      map[string]string // map of image names to local references
-	usingLocalImages bool              // true if any local images were found and loaded
+	localImages            map[string]string // map of image names to local references
+	usingLocalImages       bool
 }
 
 type ResourceKindWithName struct {
@@ -445,7 +441,7 @@ func (d *Deployer) Deploy(ctx context.Context, component, resources, exposure st
 
 	// Prepare and verify credentials early to fail fast
 	// Skip if all images are local
-	if !d.shouldSkipCredentialVerification() {
+	if !d.hasAllImagesLocally() {
 		if err := d.prepareCredentials(); err != nil {
 			return fmt.Errorf("failed to prepare credentials: %w", err)
 		}
@@ -491,19 +487,14 @@ func (d *Deployer) prepareCredentials() error {
 }
 
 // detectAndLoadLocalImages attempts to detect and load locally-available container
-// images into the kind cluster. It performs the following steps:
-//  1. Checks if ROXIE_SKIP_LOCAL_IMAGES environment variable is set
-//  2. Verifies the target cluster is a kind cluster
-//  3. Queries podman for locally available images
-//  4. Loads discovered images into the kind cluster
+// images into the kind cluster.
 //
 // This method gracefully degrades - if podman is unavailable or no images are found,
 // it returns nil and allows deployment to proceed with remote image pulls.
 // Returns an error only if image loading into kind fails after images are detected.
 func (d *Deployer) detectAndLoadLocalImages(ctx context.Context) error {
-	// Check if ROXIE_SKIP_LOCAL_IMAGES is set
 	if os.Getenv(skipLocalImagesEnvVar) == "true" {
-		d.logger.Dim("ROXIE_SKIP_LOCAL_IMAGES is set, skipping local image detection")
+		d.logger.Dim(skipLocalImagesEnvVar + " is set, skipping local image detection")
 		return nil
 	}
 
@@ -520,7 +511,6 @@ func (d *Deployer) detectAndLoadLocalImages(ctx context.Context) error {
 	d.logger.Dim("Checking for local images in podman...")
 	localImages, err := localimages.CheckImages(d.mainImageTag, d.operatorTag)
 	if err != nil {
-		// If podman is not available, gracefully fall back
 		d.logger.Dimf("Could not check for local images: %v", err)
 		d.logger.Dim("Falling back to quay.io")
 		return nil
@@ -531,13 +521,11 @@ func (d *Deployer) detectAndLoadLocalImages(ctx context.Context) error {
 		return nil
 	}
 
-	// Calculate total images needed (7 main + 2 operator = 9)
-	totalExpected := totalRequiredImages
-	d.logger.Infof("Found %d/%d images locally in podman", len(localImages), totalExpected)
+	d.logger.Infof("Found %d/%d images locally in podman", len(localImages), totalRequiredImages)
 
 	// Load images into kind using quay.io paths
 	if err := localimages.LoadImagesToKind(ctx, localImages, d.mainImageTag, d.operatorTag, kindClusterName, d.logger); err != nil {
-		return fmt.Errorf("failed to load %d images into kind cluster %s: %w", len(localImages), kindClusterName, err)
+		return fmt.Errorf("failed to load images into kind cluster %s: %w", kindClusterName, err)
 	}
 
 	// Store the local images for later use
@@ -547,34 +535,26 @@ func (d *Deployer) detectAndLoadLocalImages(ctx context.Context) error {
 	return nil
 }
 
-// shouldSkipCredentialVerification returns true if credential verification should be skipped.
-// Verification is skipped only when all required images (9 total) are available locally.
-// For partial local image scenarios, verification is still required for remote pulls.
-func (d *Deployer) shouldSkipCredentialVerification() bool {
-	// If not using any local images, don't skip
+// hasAllImagesLocally returns true if all required images are available locally.
+// When all images are local, credential verification and image pull secrets can be skipped.
+// For partial local image scenarios, credentials are still required for remote pulls.
+func (d *Deployer) hasAllImagesLocally() bool {
+	// If not using any local images, return false
 	if !d.usingLocalImages {
 		return false
 	}
 
-	// If using some local images but not all, don't skip (need creds for remote pulls)
-	// Total expected: 7 main + 2 operator = 9
-	totalExpected := totalRequiredImages
-	if len(d.localImages) < totalExpected {
+	// If using some local images but not all, return false (need creds for remote pulls)
+	if len(d.localImages) < totalRequiredImages {
 		d.logger.Dimf("Using %d/%d local images, remaining images will be pulled from quay.io",
-			len(d.localImages), totalExpected)
+			len(d.localImages), totalRequiredImages)
 		return false
 	}
 
 	// All images are local
 	return true
 }
 
-// shouldSkipImagePullSecrets returns true if image pull secrets should be skipped.
-// Same logic as credential verification - skip only if all images are local.
-func (d *Deployer) shouldSkipImagePullSecrets() bool {
-	return d.shouldSkipCredentialVerification()
-}
-
 func (d *Deployer) deployCentral(ctx context.Context, resources, exposure string) error {
 	d.logger.Infof("Deploying Central to namespace %s", d.centralNamespace)
 	if d.namespaceExists(d.centralNamespace) {

internal/deployer/operator.go

@@ -25,6 +25,43 @@ const (
 	operatorDeploymentName  = "rhacs-operator-controller-manager"
 )
 
+// clusterServiceVersion represents the relevant structure of a ClusterServiceVersion YAML
+// that we need to patch for local image references. Uses inline maps to preserve
+// all fields not explicitly defined.
+type clusterServiceVersion struct {
+	Spec struct {
+		Install struct {
+			Spec struct {
+				Deployments []struct {
+					Spec struct {
+						Template struct {
+							Spec struct {
+								Containers []struct {
+									Image string `yaml:"image"`
+									Env   []struct {
+										Name        string                 `yaml:"name"`
+										Value       string                 `yaml:"value"`
+										ExtraFields map[string]interface{} `yaml:",inline"`
+									} `yaml:"env"`
+									ExtraFields map[string]interface{} `yaml:",inline"`
+								} `yaml:"containers"`
+								ExtraFields map[string]interface{} `yaml:",inline"`
+							} `yaml:"spec"`
+							ExtraFields map[string]interface{} `yaml:",inline"`
+						} `yaml:"template"`
+						ExtraFields map[string]interface{} `yaml:",inline"`
+					} `yaml:"spec"`
+					ExtraFields map[string]interface{} `yaml:",inline"`
+				} `yaml:"deployments"`
+				ExtraFields map[string]interface{} `yaml:",inline"`
+			} `yaml:"spec"`
+			ExtraFields map[string]interface{} `yaml:",inline"`
+		} `yaml:"install"`
+		ExtraFields map[string]interface{} `yaml:",inline"`
+	} `yaml:"spec"`
+	ExtraFields map[string]interface{} `yaml:",inline"`
+}
+
 // deployOperator deploys the RHACS operator
 func (d *Deployer) deployOperator(ctx context.Context) error {
 	d.logger.Infof("Operator tag: %s", d.operatorTag)
@@ -331,7 +368,7 @@ func (d *Deployer) deployOperatorFromCSV(ctx context.Context, bundleDir string)
 	// Patch CSV with local image references if using local images
 	if d.usingLocalImages {
 		d.logger.Info("Patching CSV with local image references")
-		if err := patchCSVWithLocalImages(csvFile, d.mainImageTag, d.localImages); err != nil {
+		if err := patchCSVWithLocalImages(csvFile, d.mainImageTag, d.operatorTag, d.localImages); err != nil {
 			return fmt.Errorf("failed to patch CSV with local images: %w", err)
 		}
 	}
@@ -383,9 +420,7 @@ func (d *Deployer) deployOperatorFromCSV(ctx context.Context, bundleDir string)
 // envVarToImageName converts a RELATED_IMAGE_* environment variable name to an image name.
 // e.g., RELATED_IMAGE_SCANNER_V4_DB → scanner-v4-db
 func envVarToImageName(envVar string) string {
-	// Remove RELATED_IMAGE_ prefix
 	name := strings.TrimPrefix(envVar, "RELATED_IMAGE_")
-	// Convert to lowercase and replace underscores with hyphens
 	name = strings.ToLower(name)
 	name = strings.ReplaceAll(name, "_", "-")
 	return name
@@ -398,86 +433,34 @@ func envVarToImageName(envVar string) string {
 //
 // The function only patches images that exist in the localImages map, leaving
 // other image references unchanged.
-func patchCSVWithLocalImages(csvFile, mainImageTag string, localImages map[string]string) error {
-	// Return early if no local images to patch
-	if len(localImages) == 0 {
-		return nil
-	}
-
+func patchCSVWithLocalImages(csvFile, mainImageTag, operatorTag string, localImages map[string]string) error {
 	// Read the CSV file
 	content, err := os.ReadFile(csvFile)
 	if err != nil {
 		return fmt.Errorf("failed to read CSV file: %w", err)
 	}
 
-	// Unmarshal to map[string]interface{}
-	var csvData map[string]interface{}
+	var csvData clusterServiceVersion
 	if err := yaml.Unmarshal(content, &csvData); err != nil {
 		return fmt.Errorf("failed to parse CSV YAML: %w", err)
 	}
 
-	// Navigate to the container spec
-	spec, ok := csvData["spec"].(map[string]interface{})
-	if !ok {
-		return errors.New("CSV missing 'spec' field")
-	}
-
-	install, ok := spec["install"].(map[string]interface{})
-	if !ok {
-		return errors.New("CSV missing 'spec.install' field")
-	}
-
-	installSpec, ok := install["spec"].(map[string]interface{})
-	if !ok {
-		return errors.New("CSV missing 'spec.install.spec' field")
-	}
-
-	deployments, ok := installSpec["deployments"].([]interface{})
-	if !ok || len(deployments) == 0 {
-		return errors.New("CSV missing 'spec.install.spec.deployments' field or deployments array is empty")
-	}
-
-	deployment, ok := deployments[0].(map[string]interface{})
-	if !ok {
-		return errors.New("invalid deployment structure in CSV")
-	}
-
-	deploymentSpec, ok := deployment["spec"].(map[string]interface{})
-	if !ok {
-		return errors.New("CSV missing deployment spec")
+	// Validate structure
+	if len(csvData.Spec.Install.Spec.Deployments) == 0 {
+		return errors.New("CSV missing deployments")
 	}
-
-	template, ok := deploymentSpec["template"].(map[string]interface{})
-	if !ok {
-		return errors.New("CSV missing deployment template")
-	}
-
-	podSpec, ok := template["spec"].(map[string]interface{})
-	if !ok {
-		return errors.New("CSV missing pod spec")
-	}
-
-	containers, ok := podSpec["containers"].([]interface{})
-	if !ok || len(containers) == 0 {
-		return errors.New("CSV missing containers or containers array is empty")
+	if len(csvData.Spec.Install.Spec.Deployments[0].Spec.Template.Spec.Containers) == 0 {
+		return errors.New("CSV missing containers")
 	}
 
-	container, ok := containers[0].(map[string]interface{})
-	if !ok {
-		return errors.New("invalid container structure in CSV")
-	}
+	// Get reference to the first container
+	container := &csvData.Spec.Install.Spec.Deployments[0].Spec.Template.Spec.Containers[0]
 
 	// Patch operator image if it exists in localImages
 	// Use the actual detected image reference to handle fallback branding cases
-	operatorImageKey := "stackrox-operator:" + mainImageTag
+	operatorImageKey := "stackrox-operator:" + operatorTag
 	if imageRef, ok := localImages[operatorImageKey]; ok {
-		container["image"] = imageRef
-	}
-
-	// Patch RELATED_IMAGE_* environment variables
-	envVars, ok := container["env"].([]interface{})
-	if !ok {
-		return errors.New("CSV missing container env variables")
+		container.Image = imageRef
 	}
 
 	// Build a reverse map from image name to full image reference for quick lookup
@@ -491,25 +474,18 @@ func patchCSVWithLocalImages(csvFile, mainImageTag string, localImages map[strin
 		}
 	}
 
-	for _, envVar := range envVars {
-		envMap, ok := envVar.(map[string]interface{})
-		if !ok {
-			continue
-		}
-
-		envName, ok := envMap["name"].(string)
-		if !ok {
-			continue
-		}
+	// Patch RELATED_IMAGE_* environment variables
+	for i := range container.Env {
+		envVar := &container.Env[i]
 
 		// Check if this is a RELATED_IMAGE_* env var
-		if !strings.HasPrefix(envName, "RELATED_IMAGE_") {
+		if !strings.HasPrefix(envVar.Name, "RELATED_IMAGE_") {
 			continue
 		}
 
 		// Convert RELATED_IMAGE_FOO_BAR to foo-bar
 		// e.g., RELATED_IMAGE_SCANNER_V4_DB → scanner-v4-db
-		imageName := envVarToImageName(envName)
+		imageName := envVarToImageName(envVar.Name)
 
 		// Special case: scanner-v4-indexer and scanner-v4-matcher both use the scanner-v4 image
 		// The same image runs in different modes based on runtime configuration
@@ -520,7 +496,7 @@ func patchCSVWithLocalImages(csvFile, mainImageTag string, localImages map[strin
 		// Check if we have this image locally and use the actual detected reference
 		// This handles cases where an image was found at a fallback branding org
 		if imageRef, found := imageNameToRef[imageName]; found {
-			envMap["value"] = imageRef
+			envVar.Value = imageRef
 		}
 	}