diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 325641f46..2ff5ad4bf 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -41,8 +41,7 @@ chectl server:deploy \ - [ ] [Code produced is complete](https://github.com/eclipse/che/blob/master/CONTRIBUTING.md#code-produced-is-complete) - [ ] [Code builds without errors](https://github.com/eclipse/che/blob/master/CONTRIBUTING.md#code-builds-without-errors) - [ ] [Tests are covering the bugfix](https://github.com/eclipse/che/blob/master/CONTRIBUTING.md#tests-are-covering-the-bugfix) -- [ ] [Custom resource definition file is up to date](https://github.com/eclipse-che/che-operator/blob/main/README.md#updating-custom-resource-definition-file) -- [ ] [OLM bundles are up to date](https://github.com/eclipse-che/che-operator/blob/main/README.md#update-olm-bundle) +- [ ] [Development resource are up to date](https://github.com/eclipse-che/che-operator/blob/main/README.md#update-development-resources) - [ ] [The repository devfile is up to date and works](https://github.com/eclipse/che/blob/master/CONTRIBUTING.md#the-repository-devfile-is-up-to-date-and-works) - [ ] [Sections `What issues does this PR fix or reference` and `How to test this PR` completed](https://github.com/eclipse/che/blob/master/CONTRIBUTING.md#sections-what-issues-does-this-pr-fix-or-reference-and-how-to-test-this-pr-completed) - [ ] [Relevant user documentation updated](https://github.com/eclipse/che/blob/master/CONTRIBUTING.md#relevant-contributing-documentation-updated) diff --git a/.vscode/launch.json b/.vscode/launch.json index f5b79874f..2ffd04a6d 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -34,7 +34,7 @@ "name": "Launch Main *.go File", "type": "go", "request": "launch", - "program": "${file}", + "program": "${file}" } ] } diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 4ae404033..311b41970 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -2,7 +2,7 @@ "version": "2.0.0", "tasks": [ { - "label": "Compile che-operator code", + "label": "Compile Che operator code", "command": "make compile", "options": { "env": { @@ -20,21 +20,8 @@ "group": "build" }, { - "label": "Format che-operator code", - "command": "go fmt ./...", - "type": "shell", - "args": [], - "problemMatcher": [ - "$go" - ], - "presentation": { - "reveal": "always" - }, - "group": "build" - }, - { - "label": "Fix che-operator imports", - "command": "find . -not -path \"./vendor/*\" -name '*.go' -exec goimports -l -w {} \\;", + "label": "Format Che operator code", + "command": "make fmt", "type": "shell", "args": [], "problemMatcher": [ @@ -47,7 +34,7 @@ }, { "label": "Update golang dependencies", - "command": "go mod tidy; go mod vendor", + "command": "make update-go-dependencies", "type": "shell", "args": [], "problemMatcher": [ @@ -59,8 +46,8 @@ "group": "build" }, { - "label": "Run che-operator tests", - "command": "go test -mod=vendor -v ./...", + "label": "Run unit tests", + "command": "make test", "type": "shell", "args": [], "problemMatcher": [ @@ -77,7 +64,7 @@ "group": "build" }, { - "label": "Update all", + "label": "Update development resources", "command": "make update-dev-resources", "type": "shell", "args": [], @@ -90,8 +77,8 @@ "group": "build" }, { - "label": "Update CR/CRDs", - "command": "make generate manifests -s", + "label": "Debug Che operator", + "command": "make debug", "type": "shell", "args": [], "problemMatcher": [ @@ -101,19 +88,6 @@ "reveal": "always" }, "group": "build" - }, - { - "label": "Await debugger attach for che-operator", - "command": "make debug -s", - "type": "shell", - "args": [], - "problemMatcher": [ - "$go" - ], - "presentation": { - "reveal": "always" - }, - "group": "build" - }, + } ] } diff --git a/Makefile b/Makefile index 3b00f962f..4240900bd 100644 --- a/Makefile +++ b/Makefile @@ -75,7 +75,18 @@ VSCODE_ENV_FILE=$(INTERNAL_TMP_DIR)/vscode.env DEPLOYMENT_DIR=$(PROJECT_DIR)/deploy/deployment -ECLIPSE_CHE_NAMESPACE="eclipse-che" +ifneq (,$(shell $(K8S_CLI) get checluster -A 2>/dev/null)) + ECLIPSE_CHE_NAMESPACE := $(shell $(K8S_CLI) get checluster -A -o "jsonpath={.items[0].metadata.namespace}") +else + ECLIPSE_CHE_NAMESPACE ?= "eclipse-che" +endif + +ifneq (,$(shell $(K8S_CLI) get deployment -l app.kubernetes.io/component=che-operator -A 2>/dev/null)) + OPERATOR_NAMESPACE := $(shell $(K8S_CLI) get deployment -l app.kubernetes.io/component=che-operator -A -o "jsonpath={.items[0].metadata.namespace}") +else + OPERATOR_NAMESPACE ?= "eclipse-che" +endif + ECLIPSE_CHE_PACKAGE_NAME="eclipse-che-preview-openshift" CHECLUSTER_CR_PATH="$(PROJECT_DIR)/config/samples/org_v2_checluster.yaml" @@ -311,6 +322,10 @@ ENVTEST_ASSETS_DIR=$(shell pwd)/testbin test: download-gateway-resources ## Run tests. export MOCK_API=true; go test -mod=vendor ./... -coverprofile cover.out +update-go-dependencies: update-go-dependencies ## Update golang dependencies + go mod tidy + go mod vendor + license: ## Add license to the files FILES=$$(echo $(filter-out $@,$(MAKECMDGOALS))) $(ADD_LICENSE) -f hack/license-header.txt $${FILES} @@ -345,14 +360,14 @@ genenerate-env: install-che-operands: SHELL := /bin/bash install-che-operands: generate manifests download-kustomize download-gateway-resources echo "[INFO] Running on $(PLATFORM)" - if [[ ! "$(SKIP_CHE_OPERANDS_INSTALLATION)" == "true" ]]; then + if [[ ! "$$($(K8S_CLI) get checluster eclipse-che -n $(ECLIPSE_CHE_NAMESPACE) || false )" ]]; then [[ $(PLATFORM) == "kubernetes" ]] && $(MAKE) install-certmgr $(MAKE) install-devworkspace CHANNEL="next" $(KUSTOMIZE) build config/$(PLATFORM) | $(K8S_CLI) apply -f - $(MAKE) wait-pod-running SELECTOR="app.kubernetes.io/component=che-operator" NAMESPACE=$(ECLIPSE_CHE_NAMESPACE) fi - $(K8S_CLI) scale deploy che-operator -n $(ECLIPSE_CHE_NAMESPACE) --replicas=0 + $(K8S_CLI) scale deploy che-operator -n $(OPERATOR_NAMESPACE) --replicas=0 # Disable Webhooks since che operator pod is scaled down $(K8S_CLI) delete validatingwebhookconfiguration org.eclipse.che diff --git a/README.md b/README.md index cc57332d8..96e9057b2 100644 --- a/README.md +++ b/README.md @@ -2,294 +2,120 @@ [![codecov](https://codecov.io/gh/eclipse-che/che-operator/branch/main/graph/badge.svg?token=IlYvrVU5nB)](https://codecov.io/gh/eclipse-che/che-operator) -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 single or multi-user Eclipse Che/Red Hat OpenShift Dev Spaces cluster. +- [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 and Che server -* updates CR spec and status (passwords, URLs, provisioning statuses etc.) -* continuously watches CR, update Che ConfigMap accordingly and schedule a new Che deployment -* changes state of certain objects depending on CR fields: - * turn on/off TLS mode (reconfigure routes, update ConfigMap) - * turn on/off OpenShift oAuth (login with OpenShift in Che) (create identity provider, oAuth client, update Che ConfigMap) +* 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. -## CheCluster custom resource +## Development -Che operator deploys Eclipse Che using configuration stored in the Kubernetes custom resource(CR). CR object structure defined in the code using `api/v2/checluster_types.go` file. Field name defined using the serialization tag `json`. Che operator default CR sample is stored in the `config/samples/org_v2_checluster.yaml`. These files should be directly modified if you want to apply new fields with default values, or in case of changing default values for existing fields. Also, you can apply in the field comments Openshift UI annotations: to display some interactive information about these fields on the Openshift UI. -For example: - -```go - // +operator-sdk:csv:customresourcedefinitions:type=status - // +operator-sdk:csv:customresourcedefinitions:type=status,displayName="Eclipse Che URL" - // +operator-sdk:csv:customresourcedefinitions:type=status,xDescriptors="urn:alm:descriptor:org.w3:link" -``` - -This comment-annotations displays clickable link on the Openshift ui with a text "Eclipse Che URL" - -It is mandatory to update the OLM bundle after modification of the CR sample to deploy Eclipse Che using OLM. - -## Build and push custom Che operator image - -1. Export globally environment variables: +### Update golang dependencies ```bash -$ export IMAGE_REGISTRY_USER_NAME= && \ - export IMAGE_REGISTRY_HOST= +make update-go-dependencies ``` -Where: -- `IMAGE_REGISTRY_USER_NAME` - docker image registry account name. -- `IMAGE_REGISTRY_HOST` - docker image registry hostname, for example: "docker.io", "quay.io". Host could be with a non default port: localhost:5000, 127.0.0.1:3000 and etc. +New golang dependencies in the vendor folder should be committed and included in the pull request. -2. Run VSCode task `Build and push custom che-operator image` or use the terminal: +**Note:** freeze all new transitive dependencies using "replaces" in `go.mod` file section +to prevent CQ issues. + +### Run unit tests ```bash -$ make docker-build docker-push IMG="${IMAGE_REGISTRY_HOST}/${IMAGE_REGISTRY_USER_NAME}/che-operator:next" +make test ``` -## Deploy Che operator using make - -che-operator MAKE file provides ability to install che-operator(VSCode task `Deploy che-operator`): +### Format the code and fix imports ```bash -$ make deploy IMG=\"${IMAGE_REGISTRY_HOST}/${IMAGE_REGISTRY_USER_NAME}/che-operator:next\" - -$ kubectl apply -f config/samples/org_v2_checluster.yaml -n +make fmt ``` -Undeploy che-operator(VSCode task `UnDeploy che-operator`): +### 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 undeploy +make update-dev-resources ``` -### Deploy Che operator with chectl - -To deploy Che operator you can use [chectl](https://github.com/che-incubator/chectl). It has got two installer types corresponding to Che operator: `operator` and `olm`. With the `--installer operator` chectl reuses copies of Che operator deployment and roles (cluster roles) YAMLs, CR, CRD from the `deploy` directory of the project. With `--installer olm` chectl uses catalog source index image with olm bundles from the `bundle` directory. - -#### Deploy Che operator with chectl using `--installer operator` flag - -1. Build your custom operator image, see [How to Build che-operator Image](#build-and-push-custom-che-operator-image). - -2. Deploy Eclipse Che on a running k8s cluster: +### Build Che operator image ```bash -$ chectl server:deploy --installer operator -p --che-operator-image=${IMAGE_REGISTRY_HOST}/${IMAGE_REGISTRY_USER_NAME}/che-operator:next +make docker-build docker-push IMG= ``` -Where: -- `PLATFORM` - k8s platform supported by chectl. +### Deploy Che operator -If you have changed Che operator deployment, roles, cluster roles, CRD or CR then you must use `--templates` flag to point chectl to modified Che operator templates. Use make command to prepare chectl templates folder: +For OpenShift cluster: ```bash -$ make gen-chectl-tmpl TEMPLATES= +build/scripts/olm/testCatalogFromSources.sh -o ``` -Execute chectl: +For Kubernetes cluster: ```bash -$ chectl server:deploy --installer operator -p --che-operator-image=${IMAGE_REGISTRY_HOST}/${IMAGE_REGISTRY_USER_NAME}/che-operator:next --templates /templates +make gen-chectl-tmpl TEMPLATES= +chectl server:deploy -p (k8s|minikube|microk8s|docker-desktop) --che-operator-image= --templates ``` -#### Deploy Che operator with chectl using `--installer olm` flag +### Update Che operator -1. Build your custom operator image, see [How to Build Che operator Image](#build-and-push-custom-che-operator-image). - -2. Update OLM files: +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 -$ make update-dev-resources -``` - -3. Build catalog source and bundle images: - -```bash -$ olm/buildCatalog.sh -c -i -``` - -4. Create a custom catalog source yaml (update strategy is workaround for https://github.com/operator-framework/operator-lifecycle-manager/issues/903): - -```yaml -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: - name: eclipse-che-custom-catalog - namespace: eclipse-che -spec: - image: - sourceType: grpc - updateStrategy: - registryPoll: - interval: 5m -``` - -5. Deploy Che operator: - - -```bash -$ chectl server:deploy --installer=olm --platform= --catalog-source-yaml --olm-channel=next --package-manifest-name=eclipse-che-preview- -``` - -## Update Che operator deployment - -### Edit checluster custom resource using a command-line interface (terminal) - -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 +kubectl edit checluster eclipse-che -n ``` or: ```bash -$ kubectl patch checluster/eclipse-che --type=merge -p '' -n +kubectl patch checluster/eclipse-che --type=merge -p '' -n ``` -### Update checluster using chectl - -You can update Che configuration using the `chectl server:update` command providing `--cr-patch` flag. See [chectl](https://github.com/che-incubator/chectl) for more details. - -## Development - ### Debug Che operator You can run/debug this operator on your local machine (without deploying to a k8s cluster). -Go client grabs kubeconfig either from InClusterConfig or `~/.kube` locally. Make sure your current kubectl context points to a target cluster and namespace and a current user can create objects in a target namespace. ```bash -`make debug ECLIPSE_CHE_NAMESPACE= ECLIPSE_CHE_CR= +make debug ``` -Where: -* `ECLIPSE-CHE-NAMESPACE` - namespace name to deploy Che operator into, default is `che` -* `CUSTOM_RESOURCE` - path to custom resource yaml, default is `./config/samples/org_v2_checluster.yaml` +Then use VSCode debug configuration `Che Operator` to attach to a running process. -Use VSCode debug configuration `Che Operator` to attach to the running process. - -To uninstall che-operator use: - -```bash -$ make uninstall -``` - -And then interrupt debug process by `CTRL+C`. - -### Run unit tests - -Che operator covered with unit tests. Some of them uses mocks. To run tests use VSCode task `Run che-operator tests` or run in the terminal in the root of the project: - -```bash -$ go test -mod=vendor -v ./... -``` - -### Compile Che operator code - -The operator will be compiled to the binary `/tmp/che-operator/che-operator`. -This command is useful to make sure that che-operator is still compiling after your changes. Run VSCode task: `Compile che-operator code` or use the terminal: - -```bash -$ GOOS=linux GOARCH=${ARCH} CGO_ENABLED=0 GO111MODULE=on go build -mod=vendor -a -o /tmp/che-operator/che-operator main.go -``` - -### Format code - -Run the VSCode task: `Format che-operator code` or use the terminal: - -```bash -$ go fmt ./... -``` - -### Fix imports - -Run the VSCode task: `Fix che-operator imports` or use the terminal: - -```bash -$ find . -not -path \"./vendor/*\" -name '*.go' -exec goimports -l -w {} \\; -``` - -### Update golang dependencies - -Che operator uses Go modules and a vendor folder. Run the VSCode task: `Update che-operator dependencies` or use the terminal: - -```bash -$ go mod tidy -$ go mod vendor -``` - -New golang dependencies in the vendor folder should be committed and included in the pull request. - -Notice: freeze all new transitive dependencies using "replaces" go.mod file section to prevent CQ issues. - -### Updating Custom Resource Definition file - -Che cluster custom resource definition (CRD) defines Eclipse CheCluster custom resource object. It contains information about object structure, field types, field descriptions. CRD file is a YAML definition located in the folder `config/crd/bases`. These files are auto-generated, so do not edit it directly to update them. If you want to add new fields or fix descriptions in the CRDs, make your changes in the file `api/v1/checluster_types.go` and run VSCode task `Update CR/CRDs` or use the terminal: - -``` -$ make generate; make manifests -``` - -This command will update CRD files: - - `config/crd/bases/org.eclipse.che_checlusters.yaml` - -CRD beta yamls should be used for back compatibility with Openshift 3. - -### Update OLM bundle - -Sometimes, during development, you need to modify some YAML definitions in the `config` folder or Che cluster custom resource. There are most frequently changes which should be included to the new OLM bundle: - - operator deployment `config/manager/manager.yaml` - - operator roles/cluster roles permissions. They are defined like role/rolebinding or cluster role/rolebinding yamls in the `config` folder. - - operator custom resource CR `config/crd/bases/org_v1_che_cr.yaml`. This file contains the default CheCluster sample. Also this file is the default OLM CheCluster sample. - - Che cluster custom resource definition `api/v1/checluster_types.go`. For example you want to fix some properties description or apply new Che type properties with default values. These changes affect CRD `config/crd/bases/org.eclipse.che_checlusters.yaml`. - - add Openshift ui annotations for Che types properties (`api/v1/checluster_types.go`) to display information or interactive elements on the Openshift user interface. - -For all these cases it's a necessary to generate a new OLM bundle to make these changes working with OLM. Run the VSCode tasks `Update resources` or use the terminal: - -```bash -$ make update-dev-resources -``` - -Every changes will be included to the `bundle` folder and will override all previous changes. OLM bundle changes should be committed to the pull request. - -To update a bundle without version incrementation and time update: - -```bash -$ make update-dev-resources INCREMENT_BUNDLE_VERSION=false -``` - -### Che operator PR checks - -Documentation about all Che operator test cases can be found [here](https://github.com/eclipse-che/che-operator/tree/main/.ci/README.md) - -### Generate go mocks. - -Install mockgen tool: - -```bash -$ GO111MODULE=on go get github.com/golang/mock/mockgen@v1.4.4 -``` - -Generate new mock for go interface. Example: - -```bash -$ mockgen -source=pkg/util/process.go -destination=mocks/pkg/util/process_mock.go -package mock_util - -$ mockgen -source=pkg/controller/che/oauth_initial_htpasswd_provider.go \ - -destination=mocks/pkg/controller/che/oauth_initial_htpasswd_provider_mock.go \ - -package mock_che -``` - -See more: https://github.com/golang/mock/blob/master/README.md ### 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. +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. @@ -334,7 +160,7 @@ $ go mod graph > IMPORTANT: Dependencies validation information should be stored in the `DEPENDENCIES.md` file. -# Builds +## Builds This repo contains several [actions](https://github.com/eclipse-che/che-operator/actions), including: * ![release latest stable](https://github.com/eclipse-che/che-operator/actions/workflows/release.yml/badge.svg) @@ -348,6 +174,6 @@ Downstream builds can be found at the link below, which is _internal to Red Hat_ * [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 +## License Che is open sourced under the Eclipse Public License 2.0.