### Start Minikube

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/minikube-without-olm.md

Starts the Minikube local Kubernetes cluster. Ensure Minikube is installed and configured.

```sh
minikube start
```

--------------------------------

### ConfigMap with Mount-on-Start Annotation

Source: https://github.com/devfile/devworkspace-operator/blob/main/CHANGELOG.md

This ConfigMap example demonstrates the use of the `controller.devfile.io/mount-on-start: "true"` annotation. Setting this annotation prevents immediate workspace restarts when automounted resources are created or modified, deferring the mount until the next workspace start.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  annotations:
    controller.devfile.io/mount-as: env
    controller.devfile.io/mount-on-start: "true"
  labels:
    controller.devfile.io/mount-to-devworkspace: "true"
    controller.devfile.io/watch-configmap: "true"
  name: my-config
```

--------------------------------

### Start a DevWorkspace

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Use this command to start a DevWorkspace by setting the 'started' spec to true.

```bash
kubectl patch dw <name> --type merge -p '{"spec": {"started": true}}'
```

--------------------------------

### Install Ginkgo for Testing

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Installs the Ginkgo testing framework, which is recommended for running the full test suite of the DevWorkspace Operator.

```bash
go install github.com/onsi/ginkgo/v2/ginkgo@latest
```

--------------------------------

### Install MetalLB

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-macos.md

Apply the MetalLB manifest to install it on your cluster. Ensure MetalLB pods are ready before proceeding.

```sh
kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.14.9/config/manifests/metallb-native.yaml
```

--------------------------------

### Install cert-manager

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-linux.md

Applies the cert-manager manifest to install the certificate management system. Ensure pods become ready.

```sh
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.4/cert-manager.yaml
```

```sh
kubectl wait --namespace cert-manager \
      --timeout 90s \
      --for=condition=ready pod \
      --selector=app.kubernetes.io/instance=cert-manager
```

--------------------------------

### Run DevWorkspace Controller Locally

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Set the NAMESPACE, install the operator, wait for deployments, scale down the on-cluster deployment, and then run the controller locally. This setup avoids conflicts with the cluster-deployed instance.

```bash
export NAMESPACE="devworkspace-controller"
make install
# Wait for webhook server to start
kubectl rollout status deployment devworkspace-controller-manager -n $NAMESPACE --timeout 90s
kubectl rollout status deployment devworkspace-webhook-server -n $NAMESPACE --timeout 90s
# Scale on-cluster deployment to zero to avoid conflict with locally-running instance
oc patch deployment/devworkspace-controller-manager --patch "{\"spec\":{\"replicas\":0}}" -n $NAMESPACE
make run
```

--------------------------------

### Mount Resource on Workspace Start

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Set the `controller.devfile.io/mount-on-start` annotation to `true` to ensure the resource is mounted automatically when a DevWorkspace starts.

```yaml
metadata:
  annotations:
    controller.devfile.io/mount-on-start: "true"
```

--------------------------------

### Install Cert-Manager

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Install cert-manager to the cluster. This step can be skipped if you are deploying on OpenShift.

```bash
make install_cert_manager && \
kubectl wait --for=condition=Available -n cert-manager deployment/cert-manager
```

--------------------------------

### Install NGINX Ingress Controller

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-macos.md

Apply the manifest to install the NGINX ingress controller. This is necessary for external access to services within the cluster.

```sh
kubectl apply -f https://kind.sigs.k8s.io/examples/ingress/deploy-ingress-nginx.yaml
```

--------------------------------

### Install Homebrew Make and Coreutils on macOS

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

On macOS, install newer versions of make and coreutils using Homebrew to resolve potential Makefile issues. Ensure they are added to your PATH.

```bash
brew install coreutils make
```

```bash
export PATH="/opt/homebrew/opt/make/libexec/gnubin:$PATH"
export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"
```

--------------------------------

### Run Webhook Server Locally for Debugging

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Starts the webhook server locally using telepresence for debugging. Telepresence redirects cluster traffic to the local instance.

```bash
make debug-webhook-server
```

--------------------------------

### Install cert-manager

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-macos.md

Apply the cert-manager installation manifest. cert-manager is required for managing TLS certificates within the cluster.

```sh
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.4/cert-manager.yaml
```

--------------------------------

### Install NGINX Ingress Controller

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-linux.md

Applies the NGINX ingress controller manifest. Wait for the controller pods to be ready before proceeding.

```sh
kubectl apply -f https://kind.sigs.k8s.io/examples/ingress/deploy-ingress-nginx.yaml
```

```sh
kubectl wait --namespace ingress-nginx \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/component=controller \
  --timeout=90s
```

--------------------------------

### Get DevWorkspace IDE URL

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Retrieve the IDE URL for a started DevWorkspace by executing the `kubectl get devworkspace` command.

```bash
kubectl get devworkspace -n <namespace>
```

--------------------------------

### Create DevWorkspace Operator Subscription

Source: https://github.com/devfile/devworkspace-operator/blob/main/README.md

Creates an OLM Subscription to install the operator from the previously configured catalog.

```bash
kubectl apply -f - <<EOF
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: devworkspace-operator
  namespace: openshift-operators
spec:
  channel: next                            # <--- `next` or `release`
  installPlanApproval: Automatic
  name: devworkspace-operator
  source: devworkspace-operator-catalog    # <--- the catalog created in the previous step
  sourceNamespace: openshift-marketplace
EOF
```

--------------------------------

### Wait for MetalLB Pods

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-macos.md

This command waits for the MetalLB pods to become ready, ensuring the installation is complete. It has a timeout of 90 seconds.

```sh
kubectl wait --namespace metallb-system \
  --for=condition=ready pod \
  --selector=app=metallb \
  --timeout=90s
```

--------------------------------

### Create Kind Cluster with Port Mappings

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-linux.md

Configures a Kind cluster with specific port mappings for HTTP and HTTPS traffic. Ensure Docker is running and kind is installed.

```sh
cat <<EOF | kind create cluster --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
    protocol: TCP
  - containerPort: 443
    hostPort: 443
    protocol: TCP
EOF
```

--------------------------------

### Install DevWorkspace Operator

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-macos.md

Apply the combined deployment manifest to install the DevWorkspace Operator. This command deploys the operator to the 'devworkspace-controller' namespace.

```sh
kubectl apply -f https://github.com/devfile/devworkspace-operator/raw/refs/tags/v0.31.2/deploy/deployment/kubernetes/combined.yaml
```

--------------------------------

### Install DevWorkspace Operator for Debugging

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Install the DevWorkspace Operator, ensuring Delve is installed and its binary path is added to your system's PATH for debugging purposes.

```bash
make install
```

--------------------------------

### Install cert-manager

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/minikube-without-olm.md

Applies the cert-manager manifest to install the cert-manager component, which handles TLS certificate management. Ensure you are using a compatible version.

```sh
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml
```

--------------------------------

### Annotation to Mount Resources on Workspace Start

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Ensures a resource is only mounted when a DevWorkspace starts. Prevents mounting if the resource is created while a workspace is running, requiring a restart for mounting.

```yaml
annotations:
  controller.devfile.io/mount-on-start: "true"
```

--------------------------------

### Install DevWorkspace Operator

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/minikube-without-olm.md

Deploys the DevWorkspace Operator using its combined Kubernetes manifest. This command installs the operator into the 'devworkspace-controller' namespace.

```sh
kubectl apply -f https://github.com/devfile/devworkspace-operator/raw/refs/tags/v0.32.0/deploy/deployment/kubernetes/combined.yaml
```

--------------------------------

### Install DevWorkspace Operator

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-linux.md

Deploys the DevWorkspace Operator using a combined YAML manifest. Verify that the operator pods are ready.

```sh
kubectl apply -f https://github.com/devfile/devworkspace-operator/raw/refs/tags/v0.31.2/deploy/deployment/kubernetes/combined.yaml
```

```sh
kubectl wait --namespace devworkspace-controller \
      --timeout 90s \
      --for=condition=ready pod \
      --selector=app.kubernetes.io/part-of=devworkspace-operator
```

--------------------------------

### Kubernetes Metadata Annotations

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Apply Kubernetes metadata annotations to a DevWorkspace for additional configuration. This example sets a custom annotation.

```yaml
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: my-workspace
  labels:
    my-annotation: my-annotation-value
```

--------------------------------

### Start Prometheus Container Locally

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/grafana/README.md

Runs a Prometheus container locally, mounting the custom configuration file and exposing its web interface. The --network=host option is crucial for accessing localhost correctly from within the container.

```bash
docker run -d --name prometheus \
  --network=host \
  -v $(pwd)/prometheus.yaml:/etc/prometheus/prometheus.yaml:z \
  prom/prometheus \
  --config.file=/etc/prometheus/prometheus.yaml \
  --web.listen-address=:9999 \
  --log.level=debug
```

--------------------------------

### Create Namespace for Operator

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/openshift-without-olm.md

Creates a dedicated namespace for the DevWorkspace Controller. Ensure you have 'oc' installed and cluster access.

```sh
oc create namespace devworkspace-controller
```

--------------------------------

### Create DevWorkspace Operator Subscription

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/openshift-with-olm.md

Subscribes to the operator in the openshift-operators namespace with automatic installation approval.

```sh
oc apply -f - <<EOF
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: devworkspace-operator
  namespace: openshift-operators
spec:
  channel: next
  installPlanApproval: Automatic
  name: devworkspace-operator
  source: devworkspace-operator-catalog
  sourceNamespace: openshift-marketplace
EOF
```

--------------------------------

### E2E Test Cleanup with AfterAll

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Example of using `AfterAll` for cleanup in an ordered test suite. This pattern is crucial for ensuring that shared resources like PVCs are deleted after all tests in the suite have run, preventing conflicts in subsequent runs, especially in CI.

```go
var _ = ginkgo.Describe("[Test Suite Name]", ginkgo.Ordered, func() {
  defer ginkgo.GinkgoRecover()

  const workspaceName = "test-workspace"

  ginkgo.AfterAll(func() {
    // Cleanup workspace and wait for PVC to be fully deleted
    // This prevents PVC conflicts in subsequent tests, especially in CI environments
    _ = config.DevK8sClient.DeleteDevWorkspaceAndWait(workspaceName, config.DevWorkspaceNamespace)
  })

  ginkgo.It("Test case", func() {
    // Test implementation
  })
})
```

--------------------------------

### Configure Timeout for PostStart Events

Source: https://github.com/devfile/devworkspace-operator/blob/main/CHANGELOG.md

Set the postStartTimeout in the DevWorkspaceOperatorConfig to prevent workspace pods from getting stuck in a terminating state. By default, this timeout is disabled.

```yaml
apiVersion: controller.devfile.io/v1alpha1
kind: DevWorkspaceOperatorConfig
metadata:
  name: devworkspace-operator-config
config:
  workspace:
    postStartTimeout: '30s'
```

--------------------------------

### Kubernetes Metadata Labels

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Apply Kubernetes metadata labels to a DevWorkspace for additional configuration. This example sets a custom label.

```yaml
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: my-workspace
  labels:
    my-label: my-label-value
```

--------------------------------

### Start Grafana Container Locally

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/grafana/README.md

Runs a Grafana container locally, exposing its default web interface on port 3000. This allows access to Grafana for configuring datasources and importing dashboards.

```bash
docker run -d --name grafana -p 3000:3000 grafana/grafana
```

--------------------------------

### Apply IPAddressPool for MetalLB

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-macos.md

Define and apply an IPAddressPool resource for MetalLB using a range within your Docker network's subnet. Replace the example range with your actual subnet.

```sh
kubectl apply -f - <<EOF
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: ip-pool
  namespace: metallb-system
spec:
  addresses:
  - 192.168.97.100-192.168.97.110
EOF
```

--------------------------------

### PVC with SubPath for Mounted Directories

Source: https://github.com/devfile/devworkspace-operator/blob/main/CHANGELOG.md

This PersistentVolumeClaim example shows how to use the `controller.devfile.io/mount-path` annotation with a JSON array to mount specific subdirectories from a PVC into a workspace. Each object in the array defines a mount point (`path`) and the corresponding subdirectory within the PVC (`subPath`).

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  annotations:
    controller.devfile.io/mount-path: '[{"path":"/var/logs","subPath":"data/logs"},{"path":"/etc/config","subPath":"data/config"}]'
  labels:
    controller.devfile.io/mount-to-devworkspace: "true"
  name: my-pvc
```

--------------------------------

### Configuring Sparse Checkout for Projects

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Enable sparse checkout for a specific project within a DevWorkspace by setting the 'sparseCheckout' attribute. This example clones only the 'docs' directory from the devworkspace-operator repository.

```yaml
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: my-workspace
spec:
  template:
    projects:
      - name: devworkspace-operator
        attributes:
          sparseCheckout: "docs"
        git:
          remotes:
            origin: "https://github.com/devfile/devworkspace-operator.git"
```

--------------------------------

### Install DevWorkspace Operator

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/openshift-without-olm.md

Deploys the DevWorkspace Operator using the OpenShift-specific bundle. This command applies the operator's deployment configuration.

```sh
oc apply -f https://raw.githubusercontent.com/devfile/devworkspace-operator/refs/heads/main/deploy/deployment/openshift/combined.yaml
```

--------------------------------

### E2E Test Cleanup with AfterEach

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Example of using `AfterEach` for cleanup in test contexts that run multiple times. This ensures that resources are cleaned up after each individual test case, maintaining a clean state for subsequent tests.

```go
ginkgo.Context("Test context", func() {
  const workspaceName = "test-workspace"

  ginkgo.BeforeEach(func() {
    // Setup
  })

  ginkgo.It("Test case", func() {
    // Test implementation
  })

  ginkgo.AfterEach(func() {
    // Cleanup workspace and wait for PVC to be fully deleted
    // This prevents PVC conflicts in subsequent tests, especially in CI environments
    _ = config.DevK8sClient.DeleteDevWorkspaceAndWait(workspaceName, config.DevWorkspaceNamespace)
  })
})
```

--------------------------------

### Devfile Attributes Configuration

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Configure DevWorkspace functionality using top-level Devfile attributes. This example shows setting a custom attribute.

```yaml
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: my-workspace
spec:
  template:
    attributes:
      my-attribute: my-attribute-value
```

--------------------------------

### Configure Docker DNS for Internet Access

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

If the operator requires internet access from containers and `crc setup` does not provision it, configure DNS for Docker by editing `/etc/docker/daemon.json`.

```text
# /etc/docker/daemon.json
{
  "dns": ["192.168.0.1"]
}
```

--------------------------------

### Mutating Webhook for DevWorkspace Creation

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Implement a mutating webhook to modify DevWorkspace objects before they are persisted. This example shows how to add a creator label based on user information and perform permission validation.

```go
func (h *WebhookHandler) MutateWorkspaceV1alpha2OnCreate(
  ctx context.Context, req admission.Request,
) admission.Response {
  wksp := &dwv2.DevWorkspace{}
  if err := h.Decoder.Decode(req, wksp); err != nil {
    return admission.Errored(http.StatusBadRequest, err)
  }

  // Modify object
  wksp.Labels[constants.DevWorkspaceCreatorLabel] = req.UserInfo.UID

  // Validate permissions
  if err := h.validateUserPermissions(ctx, req, wksp, nil); err != nil {
    return admission.Denied(err.Error())
  }

  return h.returnPatched(req, wksp)
}
```

--------------------------------

### Applying Pod Overrides with Labels and Security Context

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Use `pod-overrides` to add labels and configure the security context for a workspace pod. This example demonstrates overriding metadata labels and the pod's security context.

```yaml
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: example-devworkspace
spec:
  started: true
  template:
    attributes:
      pod-overrides:
        metadata:
          labels:
            my-label: my value
        spec:
          securityContext:
            runAsUser: 1234
```

--------------------------------

### Standard Multi-Architecture Build Workflow

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Build and push both amd64 and arm64 images along with their manifest list using make targets.

```bash
make docker-build
make docker-push
```

--------------------------------

### Enable Debugging for Failing Workspaces

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Apply this annotation to a DevWorkspace to keep resources on the cluster when it fails to start. This allows for easier debugging by inspecting logs and filesystem.

```yaml
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: my-workspace
spec:
  template:
    attributes:
      controller.devfile.io/debug-start: "true"
```

--------------------------------

### Validating Pod Override Formats

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Demonstrates that both YAML and JSON formats are acceptable for specifying `pod-overrides`. The first example uses YAML for labels, and the second uses a JSON string for the same purpose.

```yaml
pod-overrides:
  metadata:
    labels:
      my-label: my value
```

```yaml
pod-overrides: {"metadata": {"labels": {"my-label": "my value"}}}
```

--------------------------------

### Create a Sample DevWorkspace

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-linux.md

Use this command to create a sample DevWorkspace with a specified template, including projects, commands, and contributions. Ensure the DevWorkspace API version and metadata are correctly set.

```bash
kubectl apply -f - <<EOF
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: git-clone-sample-devworkspace
spec:
  started: true
  template:
    projects:
      - name: web-nodejs-sample
        git:
          remotes:
            origin: "https://github.com/che-samples/web-nodejs-sample.git"
      - name: devworkspace-operator
        git:
          checkoutFrom:
            remote: origin
            revision: 0.21.x
          remotes:
            origin: "https://github.com/devfile/devworkspace-operator.git"
            amisevsk: "https://github.com/amisevsk/devworkspace-operator.git"
    commands:
      - id: say-hello
        exec:
          component: che-code-runtime-description
          commandLine: echo "Hello from $(pwd)"
          workingDir: ${PROJECT_SOURCE}/app
  contributions:
    - name: che-code
      uri: https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/che-incubator/che-code/latest/devfile.yaml
      components:
        - name: che-code-runtime-description
          container:
            env:
              - name: CODE_HOST
                value: 0.0.0.0
EOF
```

--------------------------------

### Apply Sample DevWorkspace Configuration

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Apply a sample DevWorkspace configuration to your cluster. Replace `<namespace>` with the target namespace.

```bash
kubectl apply -f ./samples/code-latest.yaml -n <namespace>
```

--------------------------------

### Single-Architecture Build Workflow

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Build and push images for a specific architecture (amd64 or arm64) for faster development cycles.

```bash
make docker-build-amd64
make docker-push-amd64
```

```bash
make docker-build-arm64
make docker-push-arm64
```

--------------------------------

### Run All Tests

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Executes all unit and controller tests using Ginkgo if available, otherwise falls back to 'go test'. Ensure Ginkgo is in your PATH.

```bash
make test
```

--------------------------------

### Build and deploy custom images for prerelease testing

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/release/README.md

Use these commands to manually build and push container images for testing release branches before the official release job is triggered.

```bash
export DWO_IMG=quay.io/yourrepo/devworkspace-controller:prerelease
export PROJECT_CLONE_IMG=quay.io/yourrepo/project-clone:prerelease
export PROJECT_BACKUP_IMG=quay.io/yourrepo/project-backup:prerelease
# build and push project clone image
podman build -t "$PROJECT_CLONE_IMG" -f ./project-clone/Dockerfile .
podman push "$PROJECT_CLONE_IMG"
# build and push project backup image
podman build -t "$PROJECT_BACKUP_IMG" -f ./project-backup/Containerfile ./project-backup/
podman push "$PROJECT_BACKUP_IMG"
# build and push DevWorkspace Operator image
export DOCKER=podman # optional
make docker
# deploy DevWorkspace Operator using these images
make install
```

--------------------------------

### Build Custom OLM Bundle

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Builds a custom Operator Lifecycle Manager (OLM) bundle and index image, then registers the catalogsource to the cluster. Requires setting specific environment variables.

```bash
make generate_olm_bundle_yaml build_bundle_and_index register_catalogsource
```

--------------------------------

### Initialize Infrastructure Detection

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Always call infrastructure.Initialize() before using infrastructure.IsOpenShift(). This prevents panics and ensures the cluster type is correctly determined.

```go
func init() {
  err := infrastructure.Initialize()
  if err != nil {
    setupLog.Error(err, "could not determine cluster type")
    os.Exit(1)
  }

  if infrastructure.IsOpenShift() {
    // OpenShift-specific initialization
  }
}
```

--------------------------------

### Create Sample DevWorkspace

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/minikube-without-olm.md

Creates a sample DevWorkspace resource named 'git-clone-sample-devworkspace'. This includes defining projects from Git repositories and a command to execute within the workspace. Ensure the `CODE_HOST` environment variable is correctly set if using Che-Code.

```yaml
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: git-clone-sample-devworkspace
spec:
  started: true
  template:
    projects:
      - name: web-nodejs-sample
        git:
          remotes:
            origin: "https://github.com/che-samples/web-nodejs-sample.git"
      - name: devworkspace-operator
        git:
          checkoutFrom:
            remote: origin
            revision: 0.21.x
          remotes:
            origin: "https://github.com/devfile/devworkspace-operator.git"
            amisevsk: "https://github.com/amisevsk/devworkspace-operator.git"
    commands:
      - id: say-hello
        exec:
          component: che-code-runtime-description
          commandLine: echo "Hello from $(pwd)"
          workingDir: ${PROJECT_SOURCE}/app
  contributions:
    - name: che-code
      uri: https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/che-incubator/che-code/latest/devfile.yaml
      components:
        - name: che-code-runtime-description
          container:
            env:
              - name: CODE_HOST
                value: 0.0.0.0
```

--------------------------------

### Detect Infrastructure Environment

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Check for OpenShift or Kubernetes environments, ensuring initialization occurs before usage to avoid panics.

```go
infrastructure.IsOpenShift()
```

```go
infrastructure.Initialize()
```

```go
infrastructure.InitializeForTesting()
```

--------------------------------

### Build and Publish DevWorkspace Controller Image

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Build the controller Go code, then build and publish the container image to your configured container registry.

```bash
make docker
```

--------------------------------

### Select Kubernetes Client

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Choose between the standard cached client and the non-caching client based on data freshness requirements.

```go
NonCachingClient
```

```go
Client
```

--------------------------------

### Add DevWorkspace Operator CatalogSource

Source: https://github.com/devfile/devworkspace-operator/blob/main/README.md

Applies a CatalogSource manifest to the cluster to make the operator available for installation.

```bash
kubectl apply -f - <<EOF
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: devworkspace-operator-catalog
  namespace: openshift-marketplace # Namespace for catalogsource, not operator itself
spec:
  sourceType: grpc
  image: quay.io/devfile/devworkspace-operator-index:next
  publisher: Red Hat
  displayName: DevWorkspace Operator Catalog
  updateStrategy:
    registryPoll:
      interval: 5m
EOF
```

--------------------------------

### Configure Debugging for Failing PostStart Commands

Source: https://github.com/devfile/devworkspace-operator/blob/main/CHANGELOG.md

Set the controller.devfile.io/debug-start annotation to 'true' on a DevWorkspace to enable debugging for failing postStart commands. This prevents immediate termination and allows inspection of logs.

```yaml
apiVersion: controller.devfile.io/v1alpha1
kind: DevWorkspaceOperatorConfig
metadata:
  name: devworkspace-operator-config
config:
  workspace:
    debugStart: true
```

--------------------------------

### Record Workspace Metrics

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Invoke these metric functions to track workspace lifecycle events and provisioning failures.

```go
metrics.WorkspaceStarted()
```

```go
metrics.WorkspaceRunning()
```

```go
metrics.WorkspaceFailed()
```

```go
metrics.DetermineProvisioningFailureReason()
```

```go
metrics.GetFailureReason()
```

--------------------------------

### Get DevWorkspace Status

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/minikube-without-olm.md

Retrieves the status of DevWorkspace resources in the 'default' namespace. This command helps in monitoring the state of your DevWorkspaces.

```sh
kubectl get devworkspace -n default
```

--------------------------------

### Get Load Balancer IP

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-macos.md

Retrieve the external IP address assigned to the ingress-nginx-controller service. This IP will be used in the DevWorkspaceOperatorConfig.

```sh
kubectl get services \
   --namespace ingress-nginx \
   ingress-nginx-controller \
   --output jsonpath='{.status.loadBalancer.ingress[0].ip}'
```

--------------------------------

### Organize Imports by Group

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Imports must be organized into three groups: standard library, third-party/Kubernetes, and project-local, separated by blank lines.

```go
import (
  "context"
  "fmt"

  dw "github.com/devfile/api/v2/pkg/apis/workspaces/v1alpha2"
  corev1 "k8s.io/api/core/v1"
  k8sErrors "k8s.io/apimachinery/pkg/api/errors"
  ctrl "sigs.k8s.io/controller-runtime"

  controllerv1alpha1 "github.com/devfile/devworkspace-operator/apis/controller/v1alpha1"
  "github.com/devfile/devworkspace-operator/pkg/common"
  "github.com/devfile/devworkspace-operator/pkg/dwerrors"
)
```

--------------------------------

### Get DevWorkspace Status

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/openshift-without-olm.md

Retrieves the status of DevWorkspaces in the specified namespace. This command helps in checking if the DevWorkspace is in the 'Running' phase.

```sh
oc get devworkspace -n devworkspace-samples
```

--------------------------------

### Apply Mandatory Copyright Header

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

All Go source files must include this specific Apache 2.0 license header, replacing {CURRENT_YEAR} with the current year.

```go
// Copyright (c) 2019-{CURRENT_YEAR} 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.
```

--------------------------------

### Get Minikube IP Address

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/minikube-without-olm.md

Retrieves the IP address of the Minikube cluster. This IP is used to configure the routing suffix for DevWorkspace.

```sh
minikube ip
```

--------------------------------

### Get Kind Node Internal IP

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-linux.md

Retrieves the internal IP address of the Kind control-plane node, which is required for configuring the DevWorkspaceOperatorConfig.

```sh
kubectl get node -o wide
```

--------------------------------

### Create Sample DevWorkspace

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/openshift-without-olm.md

Applies a sample DevWorkspace definition to the 'devworkspace-samples' namespace. This includes project definitions, commands, and contributions like 'che-code'.

```sh
oc apply -f - <<EOF
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: git-clone-sample-devworkspace
  namespace: devworkspace-samples
spec:
  started: true
  template:
    projects:
      - name: web-nodejs-sample
        git:
          remotes:
            origin: "https://github.com/che-samples/web-nodejs-sample.git"
      - name: devworkspace-operator
        git:
          checkoutFrom:
            remote: origin
            revision: 0.21.x
          remotes:
            origin: "https://github.com/devfile/devworkspace-operator.git"
            amisevsk: "https://github.com/amisevsk/devworkspace-operator.git"
    commands:
      - id: say-hello
        exec:
          component: che-code-runtime-description
          commandLine: echo "Hello from $(pwd)"
          workingDir: ${PROJECT_SOURCE}/app
  contributions:
    - name: che-code
      uri: https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/che-incubator/che-code/latest/devfile.yaml
      components:
        - name: che-code-runtime-description
          container:
            env:
              - name: CODE_HOST
                value: 0.0.0.0
EOF
```

--------------------------------

### Create Kind Cluster

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-macos.md

Use this command to create a local Kubernetes cluster with Kind.

```sh
kind create cluster
```

--------------------------------

### Configure PVC Storage Access Mode

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/dwo-configuration.md

Set the access mode for PVCs managed by the DevWorkspace Operator. This example configures it to ReadWriteMany.

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

--------------------------------

### Filter JSON Logs by Workspace Name

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Use this command to filter controller logs for a specific DevWorkspace by its name. Ensure `jq` is installed.

```bash
kubectl logs -l app.kubernetes.io/name=devworkspace-controller -n devworkspace-controller | \
  jq 'select(.workspace.name == "my-workspace")'
```

--------------------------------

### Check Infrastructure Type for Platform-Specific Code

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Use infrastructure.IsOpenShift() to conditionally execute platform-specific code. This allows for different handling of resources like Routes or Ingress based on the cluster environment.

```go
if infrastructure.IsOpenShift() {
  // Use Routes, OpenShift SCC, etc.
} else {
  // Use Ingress, standard Kubernetes
}
```

--------------------------------

### Filter JSON Logs by Workspace ID

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Use this command to filter controller logs for a specific DevWorkspace by its unique ID. Ensure `jq` is installed.

```bash
kubectl logs -l app.kubernetes.io/name=devworkspace-controller -n devworkspace-controller | \
  jq 'select(.workspace.id == "workspace-id-12345")'
```

--------------------------------

### Remove DevWorkspace CRDs

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/uninstall.md

Delete the Custom Resource Definitions (CRDs) installed by the DevWorkspace Operator. This ensures that the schema for DevWorkspace resources is removed from the cluster.

```bash
kubectl delete customresourcedefinitions.apiextensions.k8s.io devworkspaceroutings.controller.devfile.io
kubectl delete customresourcedefinitions.apiextensions.k8s.io devworkspaces.workspace.devfile.io
kubectl delete customresourcedefinitions.apiextensions.k8s.io devworkspacetemplates.workspace.devfile.io
```

--------------------------------

### Use Non-Caching Client for Immediate Reads

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Employ the NonCachingClient when reading a resource immediately after its creation or update. This is necessary because the cache might not yet reflect the latest changes.

```go
// Reading immediately after create
if err := r.Create(ctx, configMap); err != nil {
  return ctrl.Result{}, err
}
// Cache might not have it yet - use NonCachingClient
if err := r.NonCachingClient.Get(ctx, key, &createdConfigMap); err != nil {
  return ctrl.Result{}, err
}
```

--------------------------------

### Custom Persistent Home Initialization

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/dwo-configuration.md

Override the default persistent home directory initialization logic using a specially named init container. This is useful for custom UDI images.

```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"
```

--------------------------------

### Set RuntimeClass for Workspace Pods

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Use this attribute to specify a RuntimeClass for your DevWorkspace pods. The specified RuntimeClass must exist in the cluster for the workspace to start successfully.

```yaml
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: my-workspace
spec:
  template:
    attributes:
      controller.devfile.io/runtime-class: kata
```

--------------------------------

### Inject Custom Init Container for Tools

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/dwo-configuration.md

Inject custom init containers into workspace pods to add tools like the 'oc' CLI. Ensure RBAC permissions are restricted for security.

```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/
```

--------------------------------

### Wait for Controller and Webhook Server

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Checks the rollout status of the controller manager and webhook server deployments. Ensures deployments are ready before proceeding.

```bash
kubectl rollout status deployment devworkspace-controller-manager -n $NAMESPACE --timeout 90s
kubectl rollout status deployment devworkspace-webhook-server -n $NAMESPACE --timeout 90s
```

--------------------------------

### Get DevWorkspace Controller Logs

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Retrieve logs from the DevWorkspace controller manager pod. Uses the `NAMESPACE` environment variable if set, otherwise defaults to `devworkspace-controller`.

```bash
kubectl logs -n ${NAMESPACE:-devworkspace-controller} deploy/devworkspace-controller-manager -c devworkspace-controller
```

--------------------------------

### Create SSH Configuration File

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Generates a basic SSH configuration file to be mounted into DevWorkspaces. This configures SSH to use specific identity files and disables strict host key checking.

```bash
cat <<EOF > /tmp/ssh_config
host *
  IdentityFile /etc/ssh/dwo_ssh_key
  StrictHostKeyChecking = no
EOF
```

--------------------------------

### Configure Workspace Storage Access Mode

Source: https://github.com/devfile/devworkspace-operator/blob/main/CHANGELOG.md

Example of DevWorkspaceOperatorConfig to set the storage access mode for per-user and per-workspace PVCs. Use 'ReadWriteMany' for shared access.

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

--------------------------------

### Get Service Account Token for Local Metrics Access

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/grafana/README.md

Generates a 1-hour valid token for the devworkspace-controller-serviceaccount. This token is used for authenticating local access to the metrics endpoint.

```bash
TOKEN=$(kubectl create token devworkspace-controller-serviceaccount -n ${NAMESPACE} --duration=1h)
```

--------------------------------

### Applying Container Overrides for Resource Limits

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Use `container-overrides` on a container component to set resource limits, such as GPU allocation. This example configures the `nvidia.com/gpu` limit for the `web-terminal` component.

```yaml
kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: example-devworkspace
spec:
  started: true
  template:
    components:
      - name: web-terminal
        attributes:
          container-overrides: {"resources":{"limits":{"nvidia.com/gpu":"1"}}}
```

--------------------------------

### Create DevWorkspaceOperatorConfig

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/kind-without-olm-macos.md

Create the DevWorkspaceOperatorConfig resource, specifying the clusterHostSuffix using the obtained Load Balancer IP. Replace '<HOST_IP>' with the actual IP address.

```sh
kubectl apply -f - <<EOF
apiVersion: controller.devfile.io/v1alpha1
kind: DevWorkspaceOperatorConfig
metadata:
  name: devworkspace-operator-config
  namespace: devworkspace-controller
config:
  routing:
    clusterHostSuffix: "<HOST_IP>.nip.io"
EOF
```

--------------------------------

### Enable Minikube Ingress Addon

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/minikube-without-olm.md

Enables the Ingress addon for Minikube, which is required for external access to services.

```sh
minikube addons enable ingress
```

--------------------------------

### Enable Backup CronJob with Regular OCI Registry

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/dwo-configuration.md

Configure the DevWorkspaceOperatorConfig to enable the backup job, specify a regular OCI-compatible registry path, and provide an authentication secret. The schedule is set to run every 4 hours.

```yaml
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
```

--------------------------------

### Include Workspaces for Mounting

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Use the `controller.devfile.io/mount-to-devworkspace-include` annotation to specify which workspaces a resource should be mounted to. Supports comma-separated values and wildcard patterns.

```yaml
metadata:
  annotations:
    controller.devfile.io/mount-to-devworkspace-include: "my-workspace, staging-*"
```

--------------------------------

### Get DevWorkspace ID using kubectl and jq

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/workspace-capabilities.md

This bash command retrieves the DevWorkspace ID from a Kubernetes DevWorkspace object using `kubectl` and `jq`. The ID is used to construct the service account name for the workspace.

```bash
DEVWORKSPACE_ID=$(kubectl get devworkspaces <workspace-name> -o json | jq -r '.status.devworkspaceId')

```

--------------------------------

### Wait for cert-manager Pods

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/minikube-without-olm.md

Waits for cert-manager pods in the 'cert-manager' namespace to become ready. This ensures cert-manager is fully operational before proceeding.

```sh
kubectl wait --namespace cert-manager \
      --timeout 90s \
      --for=condition=ready pod \
      --selector=app.kubernetes.io/instance=cert-manager
```

--------------------------------

### Create DevWorkspaceOperatorConfig

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/minikube-without-olm.md

Applies a DevWorkspaceOperatorConfig resource to configure the operator's routing. Replace <HOST_IP> with the actual Minikube IP obtained previously. The `clusterHostSuffix` is set to `<HOST_IP>.nip.io`.

```yaml
apiVersion: controller.devfile.io/v1alpha1
kind: DevWorkspaceOperatorConfig
metadata:
  name: devworkspace-operator-config
  namespace: devworkspace-controller
config:
  routing:
    clusterHostSuffix: "<HOST_IP>.nip.io"
```

--------------------------------

### Fail Workspace with FailureReason

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Call failWorkspace with an appropriate FailureReason when a workspace encounters a failure. This marks the workspace as failed and provides a reason for the failure.

```go
return r.failWorkspace(
  workspace,
  "Error message",
  metrics.ReasonInfrastructureFailure, // or ReasonBadRequest, ReasonWorkspaceEngineFailure
  log,
  status,
)
```

--------------------------------

### External Controller Test Pattern

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Standard pattern for writing controller tests using an external test package. It utilizes Ginkgo and Gomega for defining test suites and assertions, including setting up resources and verifying their state over time.

```go
package controllers_test

import (
  . "github.com/onsi/ginkgo/v2"
  . "github.com/onsi/gomega"
)

var _ = Describe("DevWorkspace Controller", func() {
  It("Sets DevWorkspace ID and Starting status", func() {
    By("Creating a new DevWorkspace")
    // Create resource

    By("Checking DevWorkspace ID has been set")
    Eventually(func() (string, error) {
      // Get and return value
    }, timeout, interval).Should(Equal(expectedValue))
  })
})
```

--------------------------------

### Combined Include and Exclude for Mounting

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc

Combine `include` and `exclude` annotations to precisely control resource mounting. Resources are mounted only if they match the include pattern and do not match the exclude pattern.

```yaml
metadata:
  annotations:
    controller.devfile.io/mount-to-devworkspace-include: "staging-*"
    controller.devfile.io/mount-to-devworkspace-exclude: "staging-legacy"
```

--------------------------------

### Scale Controller to Zero

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

Scales the on-cluster controller deployment to zero replicas. This is done to avoid conflicts when running a local instance for debugging.

```bash
oc patch deployment/devworkspace-controller-manager --patch "{"spec":{"replicas":0}}"
```

--------------------------------

### Restore DevWorkspace from Backup

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/dwo-configuration.md

Configure a DevWorkspace to restore its project content from a backup in an OCI registry. This is achieved by setting the `controller.devfile.io/restore-workspace` attribute to 'true'. Optionally, a custom restore source image can be specified using `controller.devfile.io/restore-source-image`.

```yaml
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'
```

--------------------------------

### Configure Devfile API Fork for Local Development

Source: https://github.com/devfile/devworkspace-operator/blob/main/CONTRIBUTING.md

When modifying Devfile or DevWorkspace schemas, configure environment variables to point to your fork of the devfile/api repository. This ensures `go mod` uses your local fork for development.

```bash
export DEVFILE_API_REPO=github.com/l0rd/api   # <== your devfile/api fork
export DEVFILE_API_BRANCH=my-branch-name      # <== the branch of your fork
export DEVWORKSPACE_API_VERSION=$(git ls-remote https://${DEVFILE_API_REPO} | grep refs/heads/${DEVFILE_API_BRANCH} | cut -f 1)
go mod edit -replace github.com/devfile/api/v2=${DEVFILE_API_REPO}/v2@${DEVWORKSPACE_API_VERSION} && \
go mod download && \
go mod tidy
```

--------------------------------

### Scale Down Controller Deployment for Local Debugging

Source: https://github.com/devfile/devworkspace-operator/blob/main/AGENTS.md

Before running the controller locally, scale down the cluster deployment to avoid conflicts. This command targets the `devworkspace-controller-manager` deployment.

```bash
kubectl scale deploy devworkspace-controller-manager -n devworkspace-controller --replicas=0
```

--------------------------------

### Create DevWorkspaces Namespace

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/installation/openshift-without-olm.md

Creates a namespace specifically for DevWorkspace samples. This isolates sample DevWorkspaces from the operator's namespace.

```sh
oc create namespace devworkspace-samples
```

--------------------------------

### Webhook Deployment Configuration

Source: https://github.com/devfile/devworkspace-operator/blob/main/docs/dwo-configuration.md

Configure webhook server deployment options like replicas, tolerations, and nodeSelector within the global DWOC's config.webhook field.

```yaml
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>
```