dwo-configuration.md

DevWorkspace Operator Configuration

The DevWorkspace Operator installs the DevWorkspaceOperatorConfig Custom Resource Definition (short name: dwoc).

Controller configuration

A DevWorkspaceOperatorConfig Custom Resource defines the behavior of the DevWorkspace Operator Controller.

To see documentation on configuration settings, including default values, use kubectl explain or oc explain -- e.g. kubectl explain dwoc.config.routing.clusterHostSuffix.

The only required configuration setting is .routing.clusterHostSuffix, which is required when running on Kubernetes.

Configuration settings in the DevWorkspaceOperatorConfig override default values found in pkg/config.

Global configuration for the DevWorkspace Operator

To configure global behavior of the DevWorkspace Operator, create a DevWorkspaceOperatorConfig named devworkspace-operator-config in the same namespace where the operator is deployed:

apiVersion: controller.devfile.io/v1alpha1
kind: DevWorkspaceOperatorConfig
metadata:
  name: devworkspace-operator-config
  namespace: $OPERATOR_INSTALL_NAMESPACE
config:
  # Configuration fields

DevWorkspace specific configuration

To apply a configuration to a specific DevWorkspace instead of globally, an existing DevWorkspaceOperatorConfig can be referenced in a DevWorkspace's attributes:

apiVersion: workspace.devfile.io/v1alpha2
kind: DevWorkspace
metadata:
  name: my-devworkspace
spec:
  template:
    attributes:
      controller.devfile.io/devworkspace-config:
        name: <name of DevWorkspaceOperatorConfig CR>
        namespace: <namespace of DevWorkspaceOperatorConfig CR>

Configuration specified as above will be merged into the default global configuration, overriding any values present.

Configuring the Webhook deployment

The devworkspace-webhook-server deployment can be configured in the global DevWorkspaceOperatorConfig. The configuration options include: replicas, pod tolerations and nodeSelector.

These configuration options exist in the global DWOC's config.webhook field:

apiVersion: controller.devfile.io/v1alpha1
kind: DevWorkspaceOperatorConfig
metadata:
  name: devworkspace-operator-config
  namespace: $OPERATOR_INSTALL_NAMESPACE
config:
  webhook:
    nodeSelector:  <string, string>
    tolerations: <[]tolerations>
    replicas: <int32>

Note: In order for the devworkspace-webhook-server configuration options to take effect:

• You must place them in the Global configuration for the DevWorkspace Operator, which has the name devworkspace-operator-config and exists in the namespace where the DevWorkspaceOperator is installed. If it does not already exist on the cluster, you must create it.
• You'll need to terminate the devworkspace-controller-manager pod so that the replicaset can recreate it. The new pod will update the devworkspace-webhook-server deployment.

Configuring Cleanup CronJob

The DevWorkspace cleanup job helps manage resources by removing DevWorkspaces that have not been started for a configurable period of time.

Note: By default, the DevWorkspace cleanup job is disabled.

You can control the behaviour of the DevWorkspace cleanup job through the config.workspace.cleanupCronJob section of the global DWOC::

apiVersion: controller.devfile.io/v1alpha1
kind: DevWorkspaceOperatorConfig
metadata:
  name: devworkspace-operator-config
  namespace: $OPERATOR_INSTALL_NAMESPACE
config:
  workspace:
    cleanupCronJob:
      enabled: true
      dryRun: false
      retainTime: 2592000
      schedule: "0 0 1 * *"

Cleanup CronJob configuration fields:

• enable: Set to true to enable the cleanup job, false to disable it. Default: false.
• schedule: A Cron expression defining how often the cleanup job runs. Default: "0 0 1 * *" (first day of the month at midnight).
• retainTime: The duration time in seconds since a DevWorkspace was last started before it is considered stale and eligible for cleanup. Default: 2592000 seconds (30 days).
• dryRun: Set to true to run the cleanup job in dry-run mode. In this mode, the job logs which DevWorkspaces would be removed but does not actually delete them. Set to false to perform the actual deletion. Default: false.

Configuring Backup CronJob

The DevWorkspace backup job allows for periodic backups of DevWorkspace data to a specified backup location. Once enabled and configured, the backup job will run at defined intervals to create backups of DevWorkspace data. The backup controller depends on an OCI-compatible registry e.g., quay.io used as an image artifact storage for backup archives.

The backup makes a snapshot of Workspace PVCs and stores them as tar.gz archives in the specified OCI registry. Note: By default, the DevWorkspace backup job is disabled.

Backup CronJob configuration fields:

• enable: Set to true to enable the backup job, false to disable it. Default: false.

• schedule: A Cron expression defining how often the backup job runs. Default: "0 1 * * *".

• registry.path: A base registry location where the backup archives will be pushed. The value provided for registry.path is only the first segment of the final location. The full registry path is assembled dynamically, incorporating the name of the workspace and the :latest tag, following this pattern: <registry.path>/<devworkspace-name>:latest

• registry.authSecret: (Optional) The name of the Kubernetes Secret containing credentials to access the OCI registry. If not provided, it is assumed that the registry is public or uses integrated OpenShift registry.

• oras.extraArgs: (Optional) Additional arguments to pass to the oras CLI tool during push and pull operations.

There are several configuration options to customize the logic:

Integrated OpenShift container registry

This option is available only on OpenShift clusters with integrated container registry enabled and requires no additional configuration.

To enable the backup use following configuration in the global DWOC:

apiVersion: controller.devfile.io/v1alpha1
kind: DevWorkspaceOperatorConfig
metadata:
  name: devworkspace-operator-config
  namespace: $OPERATOR_INSTALL_NAMESPACE
config:
  routing:
    defaultRoutingClass: basic
  workspace:
    backupCronJob:
      enable: true
      registry:
        path: default-route-openshift-image-registry.apps.{cluster ID}.openshiftapps.com
      schedule: '0 */4 * * *' # cron expression with backup frequency
    imagePullPolicy: Always

Note: The path field must contain the URL to your OpenShift integrated registry given by the cluster.

Once the backup job is finished, the backup archives will be available in the DevWorkspace namespace under a repository with a matching Devworkspace name.

Regular OCI-compatible registry

To use a regular OCI-compatible registry for backups, you need to provide registry credentials. Depending on your RBAC policy, the token can be provided via a secret in the operator namespace or in each DevWorkspace namespace. Having the secret in the DevWorkspace namespace allows for using different registry accounts per namespace with more granular access control.

kind: DevWorkspaceOperatorConfig
apiVersion: controller.devfile.io/v1alpha1
metadata:
  name: devworkspace-operator-config
  namespace: $OPERATOR_INSTALL_NAMESPACE
config:
  routing:
    defaultRoutingClass: basic
  workspace:
    backupCronJob:
      enable: true
      registry:
        authSecret: my-secret
        path: quay.io/my-company-org
      schedule: '0 */4 * * *'
    imagePullPolicy: Always

The authSecret must point to a real Kubernetes Secret of type kubernetes.io/dockerconfigjson containing credentials to access the registry.

To create one you can use following command:

kubectl create secret docker-registry my-secret --from-file=config.json -n devworkspace-controller

The secret must contain a label controller.devfile.io/watch-secret=true to be recognized by the DevWorkspace Operator.

kubectl label secret my-secret controller.devfile.io/watch-secret=true -n devworkspace-controller

Restore workspace from backup

DevWorkspaces can be restored from a backup by setting the controller.devfile.io/restore-workspace: 'true' attribute. When this attribute is set, the workspace deployment includes a restore init container that pulls the backed-up /projects content from an OCI registry instead of cloning from Git.

By default, the restore source is derived from the admin-configured registry at <registry>/<namespace>/<workspace>:latest. Users can optionally specify a custom source image using the controller.devfile.io/restore-source-image attribute.

kind: DevWorkspace
spec:
  template:
    attributes:
      controller.devfile.io/restore-workspace: 'true'
      # Optional: restore from a specific image instead of the default backup registry
      controller.devfile.io/restore-source-image: 'registry.example.com/my-backup:latest'

Configuring PVC storage access mode

By default, PVCs managed by the DevWorkspace Operator are created with the ReadWriteOnce access mode. The access mode can be configured with the config.workspace.storageAccessMode section of the global DWOC:

apiVersion: controller.devfile.io/v1alpha1
kind: DevWorkspaceOperatorConfig
metadata:
  name: devworkspace-operator-config
  namespace: $OPERATOR_INSTALL_NAMESPACE
config:
  workspace:
    storageAccessMode:
    - ReadWriteMany

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

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.

Prerequisites 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, can be any valid command array.
• Args: Optional. If omitted and command is also omitted, defaults to a single script string. If provided, can be any valid args array.
• 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

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.