feat: configure init containers

Signed-off-by: Oleksii Kurinnyi <[email protected]>

Author: akurinnoy

apis/controller/v1alpha1/devworkspaceoperatorconfig_types.go

@@ -203,6 +203,10 @@ type WorkspaceConfig struct {
 	// If the feature is disabled, setting this field may cause an endless workspace start loop.
 	// +kubebuilder:validation:Optional
 	HostUsers *bool `json:"hostUsers,omitempty"`
+	// InitContainers are injected into all workspace pods as Kubernetes init containers.
+	// Typical uses: injecting organization tools/configs, initializing persistent home, etc.
+	// Note: Only trusted administrators should be allowed to edit the DevWorkspaceOperatorConfig.
+	InitContainers []corev1.Container `json:"initContainers,omitempty"`
 }
 
 type WebhookConfig struct {

controllers/workspace/devworkspace_controller.go

@@ -67,6 +67,107 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/reconcile"
 )
 
+// applyHomeInitDefaults applies default values for image and command fields
+// of the init-persistent-home container.
+func applyHomeInitDefaults(c corev1.Container, workspace *common.DevWorkspaceWithConfig) (corev1.Container, error) {
+	if c.Image == "" {
+		inferred := home.InferWorkspaceImage(&workspace.Spec.Template)
+		if inferred == "" {
+			return c, fmt.Errorf("unable to infer workspace image for init-persistent-home; specify image explicitly")
+		}
+		c.Image = inferred
+	}
+	if len(c.Command) == 0 {
+		c.Command = []string{"/bin/sh", "-c"}
+	}
+	return c, nil
+}
+
+// validateNoAdvancedFields validates that the init-persistent-home container
+// does not use advanced Kubernetes container fields that could make behavior unpredictable.
+func validateNoAdvancedFields(c corev1.Container) error {
+	if len(c.Ports) > 0 {
+		return fmt.Errorf("ports are not allowed for init-persistent-home")
+	}
+
+	if c.LivenessProbe != nil || c.ReadinessProbe != nil || c.StartupProbe != nil {
+		return fmt.Errorf("probes are not allowed for init-persistent-home")
+	}
+
+	if c.Lifecycle != nil {
+		return fmt.Errorf("lifecycle hooks are not allowed for init-persistent-home")
+	}
+
+	if c.Stdin || c.StdinOnce || c.TTY {
+		return fmt.Errorf("stdin/tty fields are not allowed for init-persistent-home")
+	}
+
+	if len(c.VolumeDevices) > 0 || c.WorkingDir != "" {
+		return fmt.Errorf("volumeDevices and workingDir are not allowed for init-persistent-home")
+	}
+
+	if c.TerminationMessagePath != "" || c.TerminationMessagePolicy != "" {
+		return fmt.Errorf("termination message fields are not allowed for init-persistent-home")
+	}
+
+	if c.SecurityContext != nil {
+		return fmt.Errorf("securityContext is not allowed for init-persistent-home")
+	}
+	if c.Resources.Limits != nil || c.Resources.Requests != nil {
+		return fmt.Errorf("resource limits/requests are not allowed for init-persistent-home")
+	}
+
+	return nil
+}
+
+// validateHomeInitContainer validates all aspects of the init-persistent-home container.
+func validateHomeInitContainer(c corev1.Container) error {
+	if strings.ContainsAny(c.Image, "\n\r\t ") {
+		return fmt.Errorf("invalid image reference for init-persistent-home: image reference contains invalid whitespace characters")
+	}
+
+	if len(c.Command) != 2 || c.Command[0] != "/bin/sh" || c.Command[1] != "-c" {
+		return fmt.Errorf("command must be exactly [/bin/sh, -c]")
+	}
+
+	if len(c.Args) != 1 {
+		return fmt.Errorf("args must contain exactly one script string")
+	}
+
+	if len(c.VolumeMounts) > 0 {
+		return fmt.Errorf("volumeMounts are not allowed for init-persistent-home; persistent-home is auto-mounted at /home/user/")
+	}
+
+	if err := validateNoAdvancedFields(c); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// defaultAndValidateHomeInitContainer applies defaults and validation for a custom
+// DWOC-provided init container named init-persistent-home. It ensures a shell execution
+// model, a single script arg, injects the persistent-home mount at /home/user/, and
+// defaults image to the inferred workspace image if not provided.
+func defaultAndValidateHomeInitContainer(c corev1.Container, workspace *common.DevWorkspaceWithConfig) (corev1.Container, error) {
+	var err error
+
+	if c, err = applyHomeInitDefaults(c, workspace); err != nil {
+		return c, err
+	}
+
+	if err = validateHomeInitContainer(c); err != nil {
+		return c, err
+	}
+
+	c.VolumeMounts = []corev1.VolumeMount{{
+		Name:      constants.HomeVolumeName,
+		MountPath: constants.HomeUserDirectory,
+	}}
+
+	return c, nil
+}
+
 const (
 	startingWorkspaceRequeueInterval = 5 * time.Second
 )
@@ -360,6 +461,34 @@ func (r *DevWorkspaceReconciler) Reconcile(ctx context.Context, req ctrl.Request
 		devfilePodAdditions.InitContainers = append([]corev1.Container{*projectClone}, devfilePodAdditions.InitContainers...)
 	}
 
+	// Inject operator-configured init containers
+	if workspace.Config != nil && workspace.Config.Workspace != nil {
+		// Check if init-persistent-home should be disabled
+		disableHomeInit := workspace.Config.Workspace.PersistUserHome.DisableInitContainer != nil &&
+			*workspace.Config.Workspace.PersistUserHome.DisableInitContainer
+
+		for _, c := range workspace.Config.Workspace.InitContainers {
+			// Special handling for init-persistent-home
+			if c.Name == constants.HomeInitComponentName {
+				// Skip if persistent home is disabled
+				if !home.PersistUserHomeEnabled(workspace) {
+					continue
+				}
+				// Skip if init container is explicitly disabled
+				if disableHomeInit {
+					continue
+				}
+				// Apply defaults and validation for init-persistent-home
+				validated, err := defaultAndValidateHomeInitContainer(c, workspace)
+				if err != nil {
+					return r.failWorkspace(workspace, fmt.Sprintf("Invalid init-persistent-home container: %s", err), metrics.ReasonBadRequest, reqLogger, &reconcileStatus), nil
+				}
+				c = validated
+			}
+			devfilePodAdditions.InitContainers = append(devfilePodAdditions.InitContainers, c)
+		}
+	}
+
 	// Add ServiceAccount tokens into devfile containers
 	if err := wsprovision.ProvisionServiceAccountTokensInto(devfilePodAdditions, workspace); err != nil {
 		return r.failWorkspace(workspace, fmt.Sprintf("Failed to mount ServiceAccount tokens to workspace: %s", err), metrics.ReasonBadRequest, reqLogger, &reconcileStatus), nil

docs/dwo-configuration.md

@@ -125,3 +125,83 @@ config:
 ```
 
 The config above will have newly created PVCs to have its access mode set to `ReadWriteMany`.
+
+## Configuring Custom Init Containers
+
+The DevWorkspace Operator allows cluster administrators to inject custom init containers into all workspace pods via the `config.workspace.initContainers` field in the global DWOC. This feature enables use cases such as:
+
+- Injecting organization-specific tools or configurations
+- Customizing the persistent home directory initialization logic
+- Extracting cluster utilities (e.g., `oc` CLI) to ensure version compatibility
+
+**Security Note:** Only trusted administrators should have RBAC permissions to edit the `DevWorkspaceOperatorConfig`, as custom init containers run in every workspace and can execute arbitrary code.
+
+### Basic Example: Injecting Custom Tools
+
+```yaml
+apiVersion: controller.devfile.io/v1alpha1
+kind: DevWorkspaceOperatorConfig
+metadata:
+  name: devworkspace-operator-config
+  namespace: $OPERATOR_INSTALL_NAMESPACE
+config:
+  workspace:
+    initContainers:
+      - name: inject-oc-cli
+        image: registry.redhat.io/openshift4/ose-cli:latest
+        command: ["/bin/sh", "-c"]
+        args:
+          - |
+            cp /usr/bin/oc /home/user/bin/oc
+            cp /usr/bin/kubectl /home/user/bin/kubectl
+        volumeMounts:
+          - name: persistent-home
+            mountPath: /home/user/
+```
+
+### Special Container: `init-persistent-home`
+
+A specially-named init container `init-persistent-home` can be used to override the built-in persistent home directory initialization logic when `config.workspace.persistUserHome.enabled: true`. This is useful for enterprises using customized UDI images that require different home directory setup logic.
+
+**Contract for `init-persistent-home`:**
+
+- **Name:** Must be exactly `init-persistent-home`
+- **Image:** Optional. If omitted, defaults to the first non-imported workspace container's image. If no suitable image can be inferred, the workspace will fail to start with an error.
+- **Command:** Optional. If omitted, defaults to `["/bin/sh", "-c"]`. If provided, must exactly match this value.
+- **Args:** Required. Must contain exactly one string with the initialization script.
+- **VolumeMounts:** Forbidden. The operator automatically mounts the `persistent-home` volume at `/home/user/`.
+- **Env:** Optional. Environment variables are allowed.
+- **Other fields:** Not allowed. Fields such as `ports`, `probes`, `lifecycle`, `securityContext`, `resources`, `volumeDevices`, `stdin`, `tty`, and `workingDir` are rejected to keep behavior predictable.
+
+**Note:** If `persistUserHome.enabled` is `false`, any `init-persistent-home` container is ignored.
+
+### Example: Custom Persistent Home Initialization
+
+```yaml
+apiVersion: controller.devfile.io/v1alpha1
+kind: DevWorkspaceOperatorConfig
+metadata:
+  name: devworkspace-operator-config
+  namespace: $OPERATOR_INSTALL_NAMESPACE
+config:
+  workspace:
+    persistUserHome:
+      enabled: true
+    initContainers:
+      - name: init-persistent-home
+        # image: optional - defaults to workspace image
+        # command: optional - defaults to ["/bin/sh", "-c"]
+        args:
+          - |
+            echo "Enterprise home init"
+            # Custom logic for enterprise UDI
+            rsync -a --ignore-existing /home/tooling/ /home/user/ || true
+            touch /home/user/.home_initialized
+        env:
+          - name: CUSTOM_VAR
+            value: "custom-value"
+```
+
+### Execution Order
+
+Custom init containers are injected after the project-clone init container in the order they are defined in the configuration. The `init-persistent-home` container runs in this sequence along with other custom init containers.

pkg/config/sync.go

@@ -439,6 +439,14 @@ func mergeConfig(from, to *controller.OperatorConfiguration) {
 		if from.Workspace.HostUsers != nil {
 			to.Workspace.HostUsers = from.Workspace.HostUsers
 		}
+
+		if from.Workspace.InitContainers != nil {
+			initContainersCopy := make([]corev1.Container, len(from.Workspace.InitContainers))
+			for i, container := range from.Workspace.InitContainers {
+				initContainersCopy[i] = *container.DeepCopy()
+			}
+			to.Workspace.InitContainers = initContainersCopy
+		}
 	}
 }
 
@@ -687,6 +695,13 @@ func GetCurrentConfigString(currConfig *controller.OperatorConfiguration) string
 		if workspace.HostUsers != nil {
 			config = append(config, fmt.Sprintf("workspace.hostUsers=%t", *workspace.HostUsers))
 		}
+		if len(workspace.InitContainers) > 0 {
+			initContainerNames := make([]string, len(workspace.InitContainers))
+			for i, container := range workspace.InitContainers {
+				initContainerNames[i] = container.Name
+			}
+			config = append(config, fmt.Sprintf("workspace.initContainers=[%s]", strings.Join(initContainerNames, ", ")))
+		}
 	}
 	if currConfig.EnableExperimentalFeatures != nil && *currConfig.EnableExperimentalFeatures {
 		config = append(config, "enableExperimentalFeatures=true")

pkg/library/home/persistentHome.go

@@ -62,7 +62,19 @@ func AddPersistentHomeVolume(workspace *common.DevWorkspaceWithConfig) (*v1alpha
 		Path: constants.HomeUserDirectory,
 	}
 
-	if workspace.Config.Workspace.PersistUserHome.DisableInitContainer == nil || !*workspace.Config.Workspace.PersistUserHome.DisableInitContainer {
+	// Determine if a custom home init container is configured via DWOC
+	hasCustomHomeInit := false
+	if workspace.Config != nil && workspace.Config.Workspace != nil {
+		for _, c := range workspace.Config.Workspace.InitContainers {
+			if c.Name == constants.HomeInitComponentName {
+				hasCustomHomeInit = true
+				break
+			}
+		}
+	}
+
+	// Add default init container only if not disabled and no custom init is configured
+	if (workspace.Config.Workspace.PersistUserHome.DisableInitContainer == nil || !*workspace.Config.Workspace.PersistUserHome.DisableInitContainer) && !hasCustomHomeInit {
 		err := addInitContainer(dwTemplateSpecCopy)
 		if err != nil {
 			return nil, fmt.Errorf("failed to add init container for home persistence setup: %w", err)
@@ -216,22 +228,8 @@ func addInitContainerComponent(dwTemplateSpec *v1alpha2.DevWorkspaceTemplateSpec
 }
 
 func inferInitContainer(dwTemplateSpec *v1alpha2.DevWorkspaceTemplateSpec) *v1alpha2.Container {
-	var nonImportedComponent v1alpha2.Component
-	for _, component := range dwTemplateSpec.Components {
-		if component.Container == nil {
-			continue
-		}
-
-		pluginSource := component.Attributes.GetString(constants.PluginSourceAttribute, nil)
-		if pluginSource == "" || pluginSource == "parent" {
-			// First non-imported container component is selected
-			nonImportedComponent = component
-			break
-		}
-	}
-
-	if nonImportedComponent.Name != "" {
-		image := nonImportedComponent.Container.Image
+	image := InferWorkspaceImage(dwTemplateSpec)
+	if image != "" {
 		return &v1alpha2.Container{
 			Image:   image,
 			Command: []string{"/bin/sh", "-c"},

pkg/library/home/util.go

@@ -0,0 +1,37 @@
+//
+// Copyright (c) 2019-2025 Red Hat, Inc.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package home
+
+import (
+	"github.com/devfile/api/v2/pkg/apis/workspaces/v1alpha2"
+	"github.com/devfile/devworkspace-operator/pkg/constants"
+)
+
+// InferWorkspaceImage finds the first non-imported container component image in the
+// flattened devfile template. This mirrors the selection rule used by the built-in
+// persistent-home initializer to pick a "primary" workspace image.
+func InferWorkspaceImage(dwTemplate *v1alpha2.DevWorkspaceTemplateSpec) string {
+	for _, component := range dwTemplate.Components {
+		if component.Container == nil {
+			continue
+		}
+		pluginSource := component.Attributes.GetString(constants.PluginSourceAttribute, nil)
+		if pluginSource == "" || pluginSource == "parent" {
+			return component.Container.Image
+		}
+	}
+	return ""
+}