182 lines
6.9 KiB
Markdown
182 lines
6.9 KiB
Markdown
# Che/Red Hat OpenShift Dev Spaces Operator
|
|
|
|
[](https://codecov.io/gh/eclipse-che/che-operator)
|
|
|
|
- [Description](#Description)
|
|
- [Development](#Development)
|
|
- [Update golang dependencies](#Update-golang-dependencies)
|
|
- [Run unit tests](#Run-unit-tests)
|
|
- [Format the code and fix imports](#Format-the-code-and-fix-imports)
|
|
- [Update development resources](#Update-development-resources)
|
|
- [Build Che operator image](#Build-Che-operator-image)
|
|
- [Deploy Che operator](#Deploy-Che-operator)
|
|
- [Update Che operator](#Update-Che-operator)
|
|
- [Debug Che operator](#Debug-Che-operator)
|
|
- [Validation licenses for runtime dependencies](#Validation-licenses-for-runtime-dependencies)
|
|
- [Builds](#Builds)
|
|
- [License](#License)
|
|
|
|
|
|
## Description
|
|
|
|
Che/Red Hat OpenShift Dev Spaces operator uses [Operator SDK](https://github.com/operator-framework/operator-sdk) and [Go Kube client](https://github.com/kubernetes/client-go) to deploy, update and manage K8S/OpenShift resources that constitute a multi-user Eclipse Che/Red Hat OpenShift Dev Spaces cluster.
|
|
|
|
The operator watches for a Custom Resource of Kind `CheCluster`, and operator controller executes its business logic when a new Che object is created, namely:
|
|
|
|
* creates k8s/OpenShift objects
|
|
* verifies successful deployment of Postgres, Devfile/Plugin registries, Dashboard and Che server
|
|
* updates CR status (passwords, URLs, provisioning statuses etc.)
|
|
* etc
|
|
|
|
Che operator is implemented using [operator framework](https://github.com/operator-framework) and the Go programming language. Eclipse Che configuration defined using a custom resource definition object and stored in the custom Kubernetes resource named `checluster`(or plural `checlusters`) in the Kubernetes API group `org.eclipse.che`. Che operator extends Kubernetes API to embed Eclipse Che to Kubernetes cluster in a native way.
|
|
|
|
## Development
|
|
|
|
### Update golang dependencies
|
|
|
|
```bash
|
|
make update-go-dependencies
|
|
```
|
|
|
|
New golang dependencies in the vendor folder should be committed and included in the pull request.
|
|
|
|
**Note:** freeze all new transitive dependencies using "replaces" in `go.mod` file section
|
|
to prevent CQ issues.
|
|
|
|
### Run unit tests
|
|
|
|
```bash
|
|
make test
|
|
```
|
|
|
|
### Format the code and fix imports
|
|
|
|
```bash
|
|
make fmt
|
|
```
|
|
|
|
### Update development resources
|
|
|
|
You have to update development resources
|
|
if you updated any files in `config` folder or `api/v2/checluster_types.go` file.
|
|
To generate new resource, run the following command:
|
|
|
|
```bash
|
|
make update-dev-resources
|
|
```
|
|
|
|
### Build Che operator image
|
|
|
|
```bash
|
|
make docker-build docker-push IMG=<YOUR_OPERATOR_IMAGE>
|
|
```
|
|
|
|
### Deploy Che operator
|
|
|
|
For OpenShift cluster:
|
|
|
|
```bash
|
|
build/scripts/olm/test-catalog-from-sources.sh
|
|
```
|
|
|
|
For Kubernetes cluster:
|
|
|
|
```bash
|
|
make gen-chectl-tmpl TEMPLATES=<OPERATOR_RESOURCES_PATH>
|
|
chectl server:deploy -p (k8s|minikube|microk8s|docker-desktop) --che-operator-image=<YOUR_OPERATOR_IMAGE> --templates <OPERATOR_RESOURCES_PATH>
|
|
```
|
|
|
|
### Update Che operator
|
|
|
|
You can modify any Kubernetes object using the UI (for example OpenShift web console)
|
|
or you can also modify Kubernetes objects using the terminal:
|
|
|
|
```bash
|
|
kubectl edit checluster eclipse-che -n <ECLIPSE-CHE-NAMESPACE>
|
|
```
|
|
|
|
or:
|
|
|
|
```bash
|
|
kubectl patch checluster/eclipse-che --type=merge -p '<PATCH_JSON>' -n <ECLIPSE-CHE-NAMESPACE>
|
|
```
|
|
|
|
### Debug Che operator
|
|
|
|
You can run/debug this operator on your local machine (without deploying to a k8s cluster).
|
|
|
|
|
|
```bash
|
|
make debug
|
|
```
|
|
|
|
Then use VSCode debug configuration `Che Operator` to attach to a running process.
|
|
|
|
|
|
### Validation licenses for runtime dependencies
|
|
|
|
Che operator is an Eclipse Foundation project. So we have to use only open source runtime dependencies with Eclipse compatible license https://www.eclipse.org/legal/licenses.php.
|
|
Runtime dependencies license validation process described here: https://www.eclipse.org/projects/handbook/#ip-third-party
|
|
To merge code with third party dependencies you have to follow process: https://www.eclipse.org/projects/handbook/#ip-prereq-diligence
|
|
When you are using new golang dependencies you have to validate the license for transitive dependencies too.
|
|
You can skip license validation for test dependencies.
|
|
All new dependencies you can find using git diff in the go.sum file.
|
|
|
|
Sometimes in the go.sum file you can find few versions for the same dependency:
|
|
|
|
```go.sum
|
|
...
|
|
github.com/go-openapi/analysis v0.18.0/go.mod h1:IowGgpVeD0vNm45So8nr+IcQ3pxVtpRoBWb8PVZO0ik=
|
|
github.com/go-openapi/analysis v0.19.2/go.mod h1:3P1osvZa9jKjb8ed2TPng3f0i/UY9snX6gxi44djMjk=
|
|
...
|
|
```
|
|
|
|
In this case will be used only one version(the highest) in the runtime, so you need to validate license for only one of them(the latest).
|
|
But also you can find module path https://golang.org/ref/mod#module-path with major version suffix in the go.sum file:
|
|
|
|
```go.sum
|
|
...
|
|
github.com/evanphx/json-patch v4.11.0+incompatible/go.mod h1:50XU6AFN0ol/bzJsmQLiYLvXMP4fmwYFNcr97nuDLSk=
|
|
github.com/evanphx/json-patch/v5 v5.1.0/go.mod h1:G79N1coSVB93tBe7j6PhzjmR3/2VvlbKOFpnXhI9Bw4=
|
|
...
|
|
```
|
|
|
|
In this case we have the same dependency, but with different major versions suffix.
|
|
Main project module uses both these versions in runtime. So both of them should be validated.
|
|
|
|
Also there is some useful golang commands to take a look full list dependencies:
|
|
|
|
```bash
|
|
$ go list -mod=mod -m all
|
|
```
|
|
|
|
This command returns all test and runtime dependencies. Like mentioned above, you can skip test dependencies.
|
|
|
|
If you want to know dependencies relation you can build dependencies graph:
|
|
|
|
```bash
|
|
$ go mod graph
|
|
```
|
|
|
|
> IMPORTANT: Dependencies validation information should be stored in the `DEPENDENCIES.md` file.
|
|
|
|
## Builds
|
|
|
|
This repo contains several [actions](https://github.com/eclipse-che/che-operator/actions), including:
|
|
* [](https://github.com/eclipse-che/che-operator/actions/workflows/release.yml)
|
|
* [](https://github.com/eclipse-che/che-operator/actions/workflows/build-next-images.yaml)
|
|
* [](https://github.com/eclipse-che/che-operator/actions/workflows/pr-check.yml)
|
|
|
|
Downstream builds can be found at the link below, which is _internal to Red Hat_. Stable builds can be found by replacing the 3.x with a specific version like 3.2.
|
|
|
|
* [operator_3.x](https://main-jenkins-csb-crwqe.apps.ocp-c1.prod.psi.redhat.com/job/DS_CI/job/operator_3.x/)
|
|
* [operator-bundle_3.x](https://main-jenkins-csb-crwqe.apps.ocp-c1.prod.psi.redhat.com/job/DS_CI/job/operator-bundle_3.x/)
|
|
|
|
See also:
|
|
* [dsc_3.x](https://main-jenkins-csb-crwqe.apps.ocp-c1.prod.psi.redhat.com/job/DS_CI/job/dsc_3.x) (downstream equivalent of [chectl](https://github.com/redhat-developer/devspaces-chectl/))
|
|
|
|
|
|
## License
|
|
|
|
Che is open sourced under the Eclipse Public License 2.0.
|