Skip to content

Commit

Permalink
Move development section from README to CONTRIBUTING
Browse files Browse the repository at this point in the history 
Signed-off-by: Mario Loriedo <mario.loriedo@gmail.com>
  • Loading branch information
@l0rd @dkwon17
l0rd authored and dkwon17 committed Nov 12, 2024
1 parent 3d606ab commit fc6583d
Show file tree
Hide file tree
Showing 2 changed files with 220 additions and 151 deletions.
195 changes: 188 additions & 7 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -27,10 +21,197 @@ 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.
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](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 <namespace>`
3. As soon as devworkspace is started you're able to get IDE url by executing `kubectl get devworkspace -n <namespace>`
### 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`
Loading

0 comments on commit fc6583d

Please sign in to comment.