Skip to content

Commit fc6583d

Browse files
l0rddkwon17
l0rd
authored and
dkwon17
committed
Move development section from README to CONTRIBUTING
Signed-off-by: Mario Loriedo <[email protected]>
1 parent 3d606ab commit fc6583d

File tree

2 files changed

+220
-151
lines changed

2 files changed

+220
-151
lines changed

‎CONTRIBUTING.md‎

Lines changed: 188 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,8 @@ Before contributing to this repository for the first time, please review our pro
1111
### Issues
1212

1313
- Open or search for [issues](https://github.com/devfile/devworkspace-operator/issues).
14-
1514
- 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).
1615

17-
### Development
18-
19-
Detailed instructions regarding project development are found [here](README.md#development).
20-
21-
2216
### Pull Requests
2317

2418
All commits must be signed off with the footer:
@@ -27,10 +21,197 @@ All commits must be signed off with the footer:
2721
Signed-off-by: Firstname Lastname <[email protected]>
2822
```
2923

30-
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.
24+
Once you set your `user.name` and `user.email` in your git config, you can sign your commit automatically with
25+
`git commit -s`. When you think the code is ready for review, create a pull request and link the issue associated with
26+
it.
3127

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

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

3632
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.
33+
34+
## CI
35+
36+
#### GitHub actions
37+
38+
- [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)
39+
- [Code Coverage Report](./.github/workflows/code-coverage.yml) action creates a code coverage report using [codecov.io](https://about.codecov.io/).
40+
41+
## Development
42+
43+
Detailed instructions regarding the DevWorkspace Operator development are provided in this section.
44+
45+
### Prerequisites
46+
47+
To build, test and debug the DevWorkspace Operator the following development tools are required:
48+
49+
- go 1.16 or later
50+
- git
51+
- sed
52+
- jq
53+
- yq (python-yq from https://github.com/kislyuk/yq#installation, other distributions may not work)
54+
- skopeo (if building the OLM catalogsource)
55+
- podman or docker
56+
57+
Note: kustomize `v4.0.5` is required for most tasks. It is downloaded automatically to the `.kustomize` folder in this
58+
repo when required. This downloaded version is used regardless of whether or not kustomize is already installed on the
59+
system.
60+
61+
### Makefile
62+
63+
The repository contains a `Makefile`; building and deploying can be configured via the environment variables:
64+
65+
|variable|purpose|default value|
66+
|---|---|---|
67+
| `DWO_IMG` | Image used for controller | `quay.io/devfile/devworkspace-controller:next` |
68+
| `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` |
69+
| `NAMESPACE` | Namespace to use for deploying controller | `devworkspace-controller` |
70+
| `ROUTING_SUFFIX` | Cluster routing suffix (e.g. `$(minikube ip).nip.io`, `apps-crc.testing`). Required for Kubernetes | `192.168.99.100.nip.io` |
71+
| `PULL_POLICY` | Image pull policy for controller | `Always` |
72+
| `DEVWORKSPACE_API_VERSION` | Branch or tag of the github.com/devfile/api to depend on | `v1alpha1` |
73+
74+
Some of the rules supported by the `Makefile`:
75+
76+
|rule|purpose|
77+
|---|---|
78+
| docker | build and push docker image |
79+
| install | install controller to cluster |
80+
| restart | restart cluster controller deployment |
81+
| install_cert_manager | installs the cert-manager to the cluster (only required for Kubernetes) |
82+
| uninstall | delete controller namespace `devworkspace-controller` and remove CRDs from cluster |
83+
| help | print all rules and variables |
84+
85+
To see all rules supported by the makefile, run `make help`
86+
87+
### DevWorkspace Operator first time development setup
88+
89+
1. Fork [devfile/devworkspce-operator](https://github.com/devfile/devworkspace-operator) and clone your fork locally
90+
2. Export the `DWO_IMG` environment variable. For example:
91+
```bash
92+
export DWO_IMG=quay.io/mloriedo/devworkspace-controller:dev
93+
```
94+
:warning: _You need write privileges on this container registry repository. The DevWorkspace controller image will be
95+
pushed there during build._
96+
3. If your changes include some update to the Devfile or DevWorkspace schema set some environment variables and run
97+
`go mod` to point to your fork instead of devfile/api:
98+
```bash
99+
export DEVFILE_API_REPO=github.com/l0rd/api # <== your devfile/api fork
100+
export DEVFILE_API_BRANCH=my-branch-name # <== the branch of your fork
101+
export DEVWORKSPACE_API_VERSION=$(git ls-remote https://${DEVFILE_API_REPO} | grep refs/heads/${DEVFILE_API_BRANCH} | cut -f 1)
102+
go mod edit -replace github.com/devfile/api/v2=${DEVFILE_API_REPO}/v2@${DEVWORKSPACE_API_VERSION} && \
103+
go mod download && \
104+
go mod tidy
105+
```
106+
4. Build the controller go code, build the container image and publish it to the container registry:
107+
```bash
108+
make docker
109+
```
110+
5. Install cert-manager (can be skipped on OpenShift):
111+
```bash
112+
make install_cert_manager && \
113+
kubectl wait --for=condition=Available -n cert-manager deployment/cert-manager
114+
```
115+
6. Finally deploys the CRDs and the controller to the current cluster:
116+
```
117+
make install # <== this command copies the CRDs definition
118+
# creates the namespace for the controller in the cluster
119+
# downloads and runs kustomize to build the manifests
120+
# deploys all the manifests (CRDs and controller)
121+
```
122+
123+
### Test run controller
124+
125+
1. Take a look samples devworkspace configuration in `./samples` folder.
126+
2. Apply any of them by executing `kubectl apply -f ./samples/code-latest.yaml -n <namespace>`
127+
3. As soon as devworkspace is started you're able to get IDE url by executing `kubectl get devworkspace -n <namespace>`
128+
129+
### Run controller locally
130+
131+
```bash
132+
export NAMESPACE="devworkspace-controller"
133+
make install
134+
# Wait for webhook server to start
135+
kubectl rollout status deployment devworkspace-controller-manager -n $NAMESPACE --timeout 90s
136+
kubectl rollout status deployment devworkspace-webhook-server -n $NAMESPACE --timeout 90s
137+
# Scale on-cluster deployment to zero to avoid conflict with locally-running instance
138+
oc patch deployment/devworkspace-controller-manager --patch "{\"spec\":{\"replicas\":0}}" -n $NAMESPACE
139+
make run
140+
```
141+
142+
> 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:
143+
> ```
144+
> # /etc/docker/daemon.json
145+
> {
146+
> "dns": ["192.168.0.1"]
147+
> }
148+
> ```
149+
150+
By default, the controller will expose workspace servers without any authentication; this is not advisable for public
151+
clusters, as any user could access the created workspace via URL.
152+
153+
### Run controller locally and debug
154+
155+
Debugging the controller depends on [delve](https://github.com/go-delve/delve) being installed
156+
(`go install github.com/go-delve/delve/cmd/dlv@latest`). Note that `$GOPATH/bin` or `$GOBIN` must be added to `$PATH` in
157+
order for `make debug` to run correctly.
158+
159+
```bash
160+
make install
161+
# Wait for webhook server to start
162+
kubectl rollout status deployment devworkspace-controller-manager -n $NAMESPACE --timeout 90s
163+
kubectl rollout status deployment devworkspace-webhook-server -n $NAMESPACE --timeout 90s
164+
oc patch deployment/devworkspace-controller-manager --patch "{\"spec\":{\"replicas\":0}}"
165+
# Scale on-cluster deployment to zero to avoid conflict with locally-running instance
166+
make debug
167+
```
168+
169+
### Run webhook server locally and debug
170+
171+
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.
172+
173+
```bash
174+
make debug-webhook-server
175+
```
176+
177+
when you are done debugging you have to manually uninstall the telepresence agent
178+
179+
```bash
180+
make disconnect-debug-webhook-server
181+
```
182+
183+
### Updating devfile API
184+
185+
[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:
186+
187+
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
188+
2. run the following scripts and the open pull request
189+
190+
```bash
191+
make update_devworkspace_api update_devworkspace_crds # first commit
192+
make generate_all # second commit
193+
```
194+
Example of the devfile API update [PR](https://github.com/devfile/devworkspace-operator/pull/797)
195+
196+
### Remove controller from your K8s/OS Cluster
197+
To uninstall the controller and associated CRDs, use the Makefile uninstall rule:
198+
```bash
199+
make uninstall
200+
```
201+
This will delete all custom resource definitions created for the controller, as well as the `devworkspace-controller` namespace.
202+
203+
### Build a custom OLM bundle
204+
205+
In order to build a custom bundle, the following environment variables should be set:
206+
| variable | purpose | default value |
207+
|---|---|---|
208+
| `DWO_BUNDLE_IMG` | Image used for Operator bundle image | `quay.io/devfile/devworkspace-operator-bundle:next` |
209+
| `DWO_INDEX_IMG` | Image used for Operator index image | `quay.io/devfile/devworkspace-operator-index:next` |
210+
| `DEFAULT_DWO_IMG` | Image used for controller when generating defaults | `quay.io/devfile/devworkspace-controller:next` |
211+
212+
To build the index image and register its catalogsource to the cluster, run
213+
```
214+
make generate_olm_bundle_yaml build_bundle_and_index register_catalogsource
215+
```
216+
217+
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`

0 commit comments

Comments
 (0)