Contributing

Contributions are welcome!

Code of Conduct

Before contributing to this repository for the first time, please review our project's Code of Conduct.

Getting Started

Issues

Open or search for issues.
If a related issue doesn't exist, you can open a new issue using a relevant issue form.

Pull Requests

All commits must be signed off with the footer:

Signed-off-by: Firstname Lastname <email@email.com>

Once you set your user.name and user.email in your git config, you can sign your commit automatically with git commit -s. When you think the code is ready for review, create a pull request and link the issue associated with it.

Owners of the repository will watch out for and review new PRs.

If comments have been given in a review, they have to be addressed before merging.

After addressing review comments, don't forget to add a comment in the PR afterward, so everyone gets notified by Github and knows to re-review.

CI

GitHub actions

Next Dockerimage action builds main branch and pushes it to quay.io/devfile/devworkspace-controller:next
Code Coverage Report action creates a code coverage report using codecov.io.

Development

Detailed instructions regarding the DevWorkspace Operator development are provided in this section.

Prerequisites

To build, test and debug the DevWorkspace Operator the following development tools are required:

go 1.16 or later
git
sed
jq
yq (python-yq from https://github.com/kislyuk/yq#installation, other distributions may not work)
skopeo (if building the OLM catalogsource)
podman or docker

Note: kustomize v4.0.5 is required for most tasks. It is downloaded automatically to the .kustomize folder in this repo when required. This downloaded version is used regardless of whether or not kustomize is already installed on the system.

macOS Specific Issues

On macOS, the default make utility might be outdated, leading to issues with some Makefile targets. To resolve this, it's recommended to install a newer version of make using Homebrew and ensure it's prioritized in your system's $PATH. Some scripts also require GNU coreutils.

Note: make version 4.4.1 has been tested and confirmed to resolve these issues.

Install Homebrew make and coreutils:
```
brew install coreutils make
```
Add the Homebrew make and coreutils executables to your $PATH. Open a new terminal session and check if they are in your path:
```
which make split
```
If the output shows paths inside /opt/homebrew/, you are all set. Otherwise, add the following lines to your shell configuration file (e.g., ~/.zshrc, ~/.bash_profile):
```
export PATH="/opt/homebrew/opt/make/libexec/gnubin:$PATH"
export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"
```
After adding, reload your shell configuration (e.g., source ~/.zshrc or source ~/.bash_profile) or open a new terminal session.

Multi-Architecture Builds

The DevWorkspace Operator supports building images for both amd64 and arm64 architectures. The build system automatically creates multi-architecture manifest lists that work on both platform types.

Standard multi-arch workflow:

make docker-build  # Builds both amd64 and arm64 images and creates a manifest list
make docker-push   # Pushes both images and the manifest list to the registry

Single-architecture builds (for faster development):

make docker-build-amd64  # Build only amd64
make docker-push-amd64   # Push only amd64

make docker-build-arm64  # Build only arm64
make docker-push-arm64   # Push only arm64

Container Tool Selection

The build system automatically detects and uses either Docker or Podman, whichever is available. You can also explicitly choose the container tool:

Using Docker:

export DOCKER=docker
make docker-build

Using Podman:

export DOCKER=podman
make docker-build

Note: Docker with buildx extension provides the fastest multi-arch builds, while Podman builds architectures sequentially and combines them into manifest lists.

Makefile

The repository contains a Makefile; building and deploying can be configured via the environment variables:

variable	purpose	default value
`DWO_IMG`	Image used for controller	`quay.io/devfile/devworkspace-controller:next`
`DEFAULT_DWO_IMG`	Image used for controller when generating default deployment templates. Can be used to override the controller image in the OLM bundle	`quay.io/devfile/devworkspace-controller:next`
`NAMESPACE`	Namespace to use for deploying controller	`devworkspace-controller`
`ROUTING_SUFFIX`	Cluster routing suffix (e.g. `$(minikube ip).nip.io`, `apps-crc.testing`). Required for Kubernetes	`192.168.99.100.nip.io`
`PULL_POLICY`	Image pull policy for controller	`Always`
`DEVWORKSPACE_API_VERSION`	Branch or tag of the github.com/devfile/api to depend on	`v1alpha1`

Some of the rules supported by the Makefile:

rule	purpose
docker	build and push docker image
install	install controller to cluster
restart	restart cluster controller deployment
install_cert_manager	installs the cert-manager to the cluster (only required for Kubernetes)
uninstall	delete controller namespace `devworkspace-controller` and remove CRDs from cluster
help	print all rules and variables

To see all rules supported by the makefile, run make help

DevWorkspace Operator first time development setup

Fork devfile/devworkspce-operator and clone your fork locally
Export the DWO_IMG environment variable. For example:
```
export DWO_IMG=quay.io/mloriedo/devworkspace-controller:dev
```
⚠️ You need write privileges on this container registry repository. The DevWorkspace controller image will be pushed there during build.

If your changes include some update to the Devfile or DevWorkspace schema set some environment variables and run go mod to point to your fork instead of devfile/api:

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

Build the controller go code, build the container image and publish it to the container registry:
```
make docker
```

Install cert-manager (can be skipped on OpenShift):

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

Finally deploys the CRDs and the controller to the current cluster:

make install  # <== this command copies the CRDs definition
              #     creates the namespace for the controller in the cluster
              #     downloads and runs kustomize to build the manifests
              #     deploys all the manifests (CRDs and controller)

Test run controller

Take a look samples devworkspace configuration in ./samples folder.
Apply any of them by executing kubectl apply -f ./samples/code-latest.yaml -n <namespace>
As soon as devworkspace is started you're able to get IDE url by executing kubectl get devworkspace -n <namespace>

Run controller locally

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

Note: The operator requires internet access from containers to work. By default, crc setup may not provision this, so it's necessary to configure DNS for Docker:
# /etc/docker/daemon.json
{
  "dns": ["192.168.0.1"]
}

By default, the controller will expose workspace servers without any authentication; this is not advisable for public clusters, as any user could access the created workspace via URL.

Run controller locally and debug

Debugging the controller depends on delve being installed (go install github.com/go-delve/delve/cmd/dlv@latest). Note that $GOPATH/bin or $GOBIN must be added to $PATH in order for make debug to run correctly.

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
oc patch deployment/devworkspace-controller-manager --patch "{\"spec\":{\"replicas\":0}}"
# Scale on-cluster deployment to zero to avoid conflict with locally-running instance
make debug

Run webhook server locally and debug

Debugging the webhook server depends on telepresence being installed (https://www.telepresence.io/docs/latest/install/). Teleprescence works by redirecting traffic going from the webhook-server in the cluster to the local webhook-server you will be running on your computer.

make debug-webhook-server

when you are done debugging you have to manually uninstall the telepresence agent

make disconnect-debug-webhook-server

Updating devfile API

devfile API is the Kube-native API for cloud development workspaces specification and the core dependency of the devworkspace-operator that should be regularly updated to the latest version. In order to do the update:

update DEVWORKSPACE_API_VERSION variable in the Makefile and build/scripts/generate_deployment.sh. The variable should correspond to the commit SHA from the devfile API repository
run the following scripts and the open pull request

make update_devworkspace_api update_devworkspace_crds # first commit
make generate_all # second commit

Example of the devfile API update PR

Remove controller from your K8s/OS Cluster

To uninstall the controller and associated CRDs, use the Makefile uninstall rule:

make uninstall

This will delete all custom resource definitions created for the controller, as well as the devworkspace-controller namespace.

Build a custom OLM bundle

In order to build a custom bundle, the following environment variables should be set:

variable	purpose	default value
`DWO_BUNDLE_IMG`	Image used for Operator bundle image	`quay.io/devfile/devworkspace-operator-bundle:next`
`DWO_INDEX_IMG`	Image used for Operator index image	`quay.io/devfile/devworkspace-operator-index:next`
`DEFAULT_DWO_IMG`	Image used for controller when generating defaults	`quay.io/devfile/devworkspace-controller:next`

To build the index image and register its catalogsource to the cluster, run

make generate_olm_bundle_yaml build_bundle_and_index register_catalogsource

Note that setting DEFAULT_DWO_IMG while generating sources will result in local changes to the repo which should be git restored before committing. This can also be done by unsetting the DEFAULT_DWO_IMG env var and re-running make generate_olm_bundle_yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing

Code of Conduct

Getting Started

Issues

Pull Requests

CI

GitHub actions

Development

Prerequisites

macOS Specific Issues

Multi-Architecture Builds

Container Tool Selection

Makefile

DevWorkspace Operator first time development setup

Test run controller

Run controller locally

Run controller locally and debug

Run webhook server locally and debug

Updating devfile API

Remove controller from your K8s/OS Cluster

Build a custom OLM bundle

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing

Code of Conduct

Getting Started

Issues

Pull Requests

CI

GitHub actions

Development

Prerequisites

macOS Specific Issues

Multi-Architecture Builds

Container Tool Selection

Makefile

DevWorkspace Operator first time development setup

Test run controller

Run controller locally

Run controller locally and debug

Run webhook server locally and debug

Updating devfile API

Remove controller from your K8s/OS Cluster

Build a custom OLM bundle