diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f00bacfed..097ae7286 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,14 +11,8 @@ Before contributing to this repository for the first time, please review our pro ### Issues - Open or search for [issues](https://github.com/devfile/devworkspace-operator/issues). - - If a related issue doesn't exist, you can open a new issue using a relevant [issue form](https://github.com/devfile/devworkspace-operator/issues/new/choose). -### Development - -Detailed instructions regarding project development are found [here](README.md#development). - - ### Pull Requests All commits must be signed off with the footer: @@ -27,10 +21,197 @@ All commits must be signed off with the footer: Signed-off-by: Firstname Lastname ``` -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. +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. \ No newline at end of file +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](https://github.com/devfile/devworkspace-operator/blob/main/.github/workflows/dockerimage-next.yml) action builds main branch and pushes it to [quay.io/devfile/devworkspace-controller:next](https://quay.io/repository/devfile/devworkspace-controller?tag=latest&tab=tags) +- [Code Coverage Report](./.github/workflows/code-coverage.yml) action creates a code coverage report using [codecov.io](https://about.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. + +### 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 + +1. Fork [devfile/devworkspce-operator](https://github.com/devfile/devworkspace-operator) and clone your fork locally +2. Export the `DWO_IMG` environment variable. For example: + ```bash + export DWO_IMG=quay.io/mloriedo/devworkspace-controller:dev + ``` + :warning: _You need write privileges on this container registry repository. The DevWorkspace controller image will be +pushed there during build._ +3. 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: + ```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 + ``` +4. Build the controller go code, build the container image and publish it to the container registry: + ```bash + make docker + ``` +5. Install cert-manager (can be skipped on OpenShift): + ```bash + make install_cert_manager && \ + kubectl wait --for=condition=Available -n cert-manager deployment/cert-manager + ``` +6. 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 + +1. Take a look samples devworkspace configuration in `./samples` folder. +2. Apply any of them by executing `kubectl apply -f ./samples/code-latest.yaml -n ` +3. As soon as devworkspace is started you're able to get IDE url by executing `kubectl get devworkspace -n ` + +### Run controller locally + +```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 +``` + +> 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](https://github.com/go-delve/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. + +```bash +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. + +```bash +make debug-webhook-server +``` + +when you are done debugging you have to manually uninstall the telepresence agent + +```bash +make disconnect-debug-webhook-server +``` + +### Updating devfile API + +[devfile API](https://github.com/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: + +1. 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](https://github.com/devfile/api) repository +2. run the following scripts and the open pull request + +```bash +make update_devworkspace_api update_devworkspace_crds # first commit +make generate_all # second commit +``` +Example of the devfile API update [PR](https://github.com/devfile/devworkspace-operator/pull/797) + +### Remove controller from your K8s/OS Cluster +To uninstall the controller and associated CRDs, use the Makefile uninstall rule: +```bash +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` diff --git a/README.md b/README.md index 2adabbb41..bdd19ae9e 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ DevWorkspace operator repository that contains the controller for the DevWorkspa A [Kubernetes Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) to run **fast**, **repeatable** and **scalable** Cloud Development Environments. -[Install it](#deploying-devworkspace-operator) and apply a DevWorkspace to create a Cloud Development Environment:
+[Install it](#devworkspace-operator-installation) and apply a DevWorkspace to create a Cloud Development Environment:
![dw apply demo](img/apply-demo.gif) Get the Cloud Developent Environment URI:
@@ -53,48 +53,28 @@ and the DevWorkspaces can be further configured through DevWorkspace `attributes`, `labels` and `annotations`. For a list of all options available, see [additional documentation](docs/additional-configuration.adoc). -## Deploying DevWorkspace Operator +## DevWorkspace Operator Installation -### Prerequisites -- 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 +This section describes how to install the Operator on a cluster using the +[Operator Lifecycle Manager (OLM)](https://olm.operatorframework.io). The file [CONTRIBUTING.md](CONTRIBUTING.md) has +instructions to install the Operator, using the `Makefile`, without requiring OLM. -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. +#### Installing the Operator Lifecycle Manager -### Running the controller in a cluster +The Operator Framework website has +[general instructions to install OLM in your cluster](https://olm.operatorframework.io/docs/getting-started/#installing-olm-in-your-cluster). +On [Minikube](https://minikube.sigs.k8s.io/), OLM is available as +[an addon](https://minikube.sigs.k8s.io/docs/commands/addons/). +OLM is pre-installed on OpenShift. -#### With yaml resources +#### Adding the DevWorkspace Operator catalog source -When installing on Kubernetes clusters, the DevWorkspace Operator requires the [cert-manager](https://cert-manager.io) operator in order to properly serve webhooks. To install the latest version of cert-manager in a cluster, the Makefile rule `install_cert_manager` can be used. The minimum version of cert-manager is `v1.0.4`. - -The controller can be deployed to a cluster provided you are logged in with cluster-admin credentials: +If the DevWorkspace Operator is not already available amongst the `PackageManifests` (use command +`kubectl get packagemanifest -n olm | grep devworkspace` to check it) you add should add a `CatalogSource` in the +cluster: ```bash -export DWO_IMG=quay.io/devfile/devworkspace-controller:next -make install -``` - -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. - -See below for all environment variables used in the makefile. - -> 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"] -> } -> ``` - -#### With Operator Lifecycle Manager (OLM) - -DevWorkspace Operator has bundle and index images which enable installation via OLM. To enable installing the DevWorkspace Operator through OLM, it may be necessary to create a CatalogSource in the cluster for this index: -```yaml +kubectl apply -f - <` -3. As soon as devworkspace is started you're able to get IDE url by executing `kubectl get devworkspace -n ` - -### Run controller locally -```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 -``` - -### Run controller locally and debug -Debugging the controller depends on [delve](https://github.com/go-delve/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. +#### Create the DevWorkspace Operator Subscription -```bash -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. - -```bash -make debug-webhook-server -``` - -when you are done debugging you have to manually uninstall the telepresence agent +To install the DevWorkspace Operator, create a OLM Subscription with the following command: ```bash -make disconnect-debug-webhook-server -``` - -### Updating devfile API - -[devfile API](https://github.com/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: - -1. 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](https://github.com/devfile/api) repository -2. run the following scripts and the open pull request - -```bash -make update_devworkspace_api update_devworkspace_crds # first commit -make generate_all # second commit -``` -Example of the devfile API update [PR](https://github.com/devfile/devworkspace-operator/pull/797) - -### Remove controller from your K8s/OS Cluster -To uninstall the controller and associated CRDs, use the Makefile uninstall rule: -```bash -make uninstall +kubectl apply -f - <