add options for olm deploy and fix developer.md (#383)

* add options for olm deploy

Signed-off-by: gazarenkov <gazarenkov@gmail.com>

* Update docs/developer.md

Co-authored-by: Armel Soro <armel@rm3l.org>

* Update docs/developer.md

Co-authored-by: Armel Soro <armel@rm3l.org>

* Update docs/developer.md

Co-authored-by: Armel Soro <armel@rm3l.org>

* fix deploy-openshift

Signed-off-by: gazarenkov <gazarenkov@gmail.com>

---------

Signed-off-by: gazarenkov <gazarenkov@gmail.com>
Co-authored-by: Armel Soro <armel@rm3l.org>

Makefile

@@ -363,25 +363,53 @@ release-build: bundle image-build bundle-build catalog-build ## Build operator,
 .PHONY:
 release-push: image-push bundle-push catalog-push ## Push operator, bundle + catalog images
 
+# It has to be the same namespace as ./config/default/kustomization.yaml -> namespace
+OPERATOR_NAMESPACE ?= backstage-system
+OLM_NAMESPACE ?= olm
+OPENSHIFT_OLM_NAMESPACE = openshift-marketplace
+
 .PHONY: deploy-olm
 deploy-olm: ## Deploy the operator with OLM
-	kubectl apply -f config/samples/catalog-operator-group.yaml
-	sed "s/{{VERSION}}/$(subst /,\/,$(VERSION))/g" config/samples/catalog-subscription-template.yaml | sed "s/{{DEFAULT_OLM_NAMESPACE}}/$(subst /,\/,$(DEFAULT_OLM_NAMESPACE))/g" | kubectl apply -f -
+	kubectl -n ${OPERATOR_NAMESPACE} apply -f config/samples/catalog-operator-group.yaml
+	sed "s/{{VERSION}}/$(subst /,\/,$(VERSION))/g" config/samples/catalog-subscription-template.yaml | sed "s/{{OLM_NAMESPACE}}/$(subst /,\/,$(OLM_NAMESPACE))/g" | kubectl -n ${OPERATOR_NAMESPACE} apply -f -
+
+.PHONY: deploy-olm-openshift
+deploy-olm-openshift: ## Deploy the operator with OLM
+	kubectl -n ${OPERATOR_NAMESPACE} apply -f config/samples/catalog-operator-group.yaml
+	sed "s/{{VERSION}}/$(subst /,\/,$(VERSION))/g" config/samples/catalog-subscription-template.yaml | sed "s/{{OLM_NAMESPACE}}/$(subst /,\/,$(OPENSHIFT_OLM_NAMESPACE))/g" | kubectl -n ${OPERATOR_NAMESPACE} apply -f -
+
 
 .PHONY: undeploy-olm
 undeploy-olm: ## Un-deploy the operator with OLM
-	-kubectl delete subscriptions.operators.coreos.com backstage-operator
-	-kubectl delete operatorgroup backstage-operator-group
-	-kubectl delete clusterserviceversion backstage-operator.$(VERSION)
+	-kubectl -n ${OPERATOR_NAMESPACE} delete subscriptions.operators.coreos.com backstage-operator
+	-kubectl -n ${OPERATOR_NAMESPACE} delete operatorgroup backstage-operator-group
+	-kubectl -n ${OPERATOR_NAMESPACE} delete clusterserviceversion backstage-operator.v$(VERSION)
 
-DEFAULT_OLM_NAMESPACE ?= openshift-marketplace
 .PHONY: catalog-update
 catalog-update: ## Update catalog source in the default namespace for catalogsource
-	-kubectl delete catalogsource backstage-operator -n $(DEFAULT_OLM_NAMESPACE)
-	sed "s/{{CATALOG_IMG}}/$(subst /,\/,$(CATALOG_IMG))/g" config/samples/catalog-source-template.yaml | kubectl apply -n $(DEFAULT_OLM_NAMESPACE) -f -
+	-kubectl delete catalogsource backstage-operator -n $(OLM_NAMESPACE)
+	sed "s/{{CATALOG_IMG}}/$(subst /,\/,$(CATALOG_IMG))/g" config/samples/catalog-source-template.yaml | kubectl apply -n $(OLM_NAMESPACE) -f -
+
+.PHONY: catalog-update
+catalog-update-openshift: ## Update catalog source in the default namespace for catalogsource
+	-kubectl delete catalogsource backstage-operator -n $(OLM_NAMESPACE)
+	sed "s/{{CATALOG_IMG}}/$(subst /,\/,$(CATALOG_IMG))/g" config/samples/catalog-source-template.yaml | kubectl apply -n $(OPENSHIFT_OLM_NAMESPACE) -f -
 
+
+# Deploy on Openshift cluster using OLM (by default installed on Openshift)
 .PHONY: deploy-openshift
-deploy-openshift: release-build release-push catalog-update ## Deploy the operator on openshift cluster
+deploy-openshift: release-build release-push catalog-update-openshift create-operator-namespace deploy-olm-openshift ## Deploy the operator on openshift cluster
+
+.PHONY: install-olm
+install-olm: operator-sdk
+	$(OPSDK) olm install
+
+.PHONY: create-operator-namespace
+create-operator-namespace:
+	-kubectl create namespace ${OPERATOR_NAMESPACE}
+
+.PHONY: deploy-k8s-olm
+deploy-k8s-olm: release-build release-push catalog-update create-operator-namespace deploy-olm ## Deploy the operator on openshift cluster
 
 # After this time, Ginkgo will emit progress reports, so we can get visibility into long-running tests.
 POLL_PROGRESS_INTERVAL := 120s

config/samples/catalog-subscription-template.yaml

@@ -7,5 +7,5 @@ spec:
   installPlanApproval: Automatic
   name: backstage-operator
   source: backstage-operator
-  sourceNamespace: openshift-marketplace
+  sourceNamespace: {{OLM_NAMESPACE}}
   startingCSV: backstage-operator.v{{VERSION}}

docs/developer.md

@@ -1,115 +1,150 @@
-# DEVELOPER GUIDE --- WIP
+# Developer Guide 
 
 ## Contributing
 // TODO(user): Add detailed information on how you would like others to contribute to this project
 
+
 ### How it works
 This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/).
 
 It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)
 which provides a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster.
 
-
 ## Local development
 
 ### Prerequisites
 
 * **kubectl**. See [Instaling kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl).
-* **minikube**. See [Instaling minkube](https://kubernetes.io/docs/tasks/tools/#minikube).
+* Available local or remote Kubernetes cluster with cluster admin privileges. For instance **minikube**. See [Instaling minkube](https://kubernetes.io/docs/tasks/tools/#minikube).
 * A copy of the Backstage Operator sources:
 ```sh
 git clone https://github.com/janus-idp/operator
 ```
 
 ### Local Tests
 
-To run both unit tests (since 0.0.2) and Kubernetes integration tests ([envtest](https://book.kubebuilder.io/reference/envtest.html)):
+To run:
+* all the unit tests 
+* part of [Integration Tests](../integration_tests/README.md) which does not require a real cluster.
 
 ```sh
 make test
 ```
 
-### Test on the local cluster
+It only takes a few seconds to run, but covers quite a lot of functionality. For early regression detection, it is recommended to run it as often as possible during development.
 
-You’ll need a Kubernetes cluster to run against.
-You can use [minikube](https://kubernetes.io/docs/tasks/tools/#minikube) or [kind](https://kubernetes.io/docs/tasks/tools/#kind) to get a local cluster for testing, or run against a remote cluster.
+### Test on the cluster
 
-**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
+For testing, you will need a Kubernetes cluster, either remote (with sufficient admin rights) or local, such as [minikube](https://kubernetes.io/docs/tasks/tools/#minikube) or [kind](https://kubernetes.io/docs/tasks/tools/#kind)
 
 - Build and push your image to the location specified by `IMG`:
 ```sh
 make image-build image-push IMG=<your-registry>/backstage-operator:tag
 ```
 
-- Install the CRDs into the local cluster (minikube is installed and running):
+- Install the Custom Resource Definitions into the local cluster (minikube is installed and running):
 ```sh
 make install
 ```
+**IMPORTANT:** If you are editing the CRDs, make sure you reinstall it before deploying.
 
--  You can run your controller standalone (this will run in the foreground, so switch to a new terminal if you want to leave it running)
-This way you can see controllers log just in your terminal window which is quite convenient for debugging:
+- To delete the CRDs from the cluster:
 ```sh
-make run
+make uninstall
 ```
 
-- Or deploy the controller to the cluster with the image specified by `IMG`:
+### Run the controller standalone
+
+You can run your controller standalone (this will run in the foreground, so switch to a new terminal if you want to leave it running)
+This way you can see controllers log just in your terminal window which is quite convenient for debugging.
 ```sh
-make deploy [IMG=<your-registry>/backstage-operator:tag]
+make [install] run
 ```
 
-- To generate deployment manifest, use:
+You can use it for manual and automated ([such as](../integration_tests/README.md) `USE_EXISTING_CLUSTER=true make integration-test`) tests efficiently, but, note, RBAC is not working with this kind of deployment.
+
+### Deploy operator to the real cluster
+
+For development, most probably, you will need to specify the image you build and push:
 ```sh
-make deployment-manifest [IMG=<your-registry>/backstage-operator:tag]
+make deploy [IMG=<your-registry>/backstage-operator[:tag]]
 ```
-it will create the file rhdh-operator-${VERSION}.yaml on the project root and you will be able to share it to make it possible to deploy operator with:
+
+To undeploy the controller from the cluster:
 ```sh
-kubectl apply -f <path-or-url-to-deployment-script>
+make undeploy
 ```
 
-### Uninstall CRDs
-To delete the CRDs from the cluster:
+- To generate deployment manifest, use:
 ```sh
-make uninstall
+make deployment-manifest [IMG=<your-registry>/backstage-operator:tag]
 ```
-### Undeploy controller
-UnDeploy the controller from the cluster:
+it will create the file rhdh-operator-${VERSION}.yaml on the project root and you will be able to share it to make it possible to deploy operator with:
 ```sh
-make undeploy
+kubectl apply -f <path-or-url-to-deployment-script>
 ```
-### Build and Deploy with OLM:
-1. To build operator, bundle and catalog images:
+
+### Deploy with Operator Lifecycle Manager (valid for v0.3.0+):
+
+#### OLM
+
+Make sure your cluster supports **OLM**. For instance [Openshift](https://www.redhat.com/en/technologies/cloud-computing/openshift) supports it out of the box.
+If needed install it using: 
+
 ```sh
-make release-build
+make install-olm
 ```
-2. To push operator, bundle and catalog images to the registry:
+
+#### Build and push images
+
+There are a bunch of commands to build and push to the registry necessary images.
+For development purpose, most probably, you will need to specify the image you build and push with IMAGE_TAG_BASE env variable: 
+
+* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make image-build` builds operator manager image (**backstage-operator**)
+* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make image-push` pushes operator manager image to **your-registry**
+* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make bundle-build` builds operator manager image (**backstage-operator-bundle**)
+* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make bundle-push` pushes bundle image to **your-registry**
+* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make catalog-build` builds catalog image (**backstage-operator-catalog**)
+* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make catalog-push` pushes catalog image to **your-registry**
+
+You can do it all together using:
 ```sh
-make release-push
+[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make release-build release-push
 ```
-3. To deploy or update catalog source:
+
+#### Deploy or update the Catalog Source
+
 ```sh
-make catalog-update
+[OLM_NAMESPACE=<olm-namespace>] [IMAGE_TAG_BASE=<your-registry>/backstage-operator] make catalog-update
 ```
-4. To deloy the operator with OLM
+You can point the namespace where OLM installed. By default, in a vanilla Kubernetes, OLM os deployed on 'olm' namespace. In Openshift you have to explicitly point it to **openshift-marketplace** namespace.
+
+#### Deploy the Operator with OLM 
+Default namespace to deploy the Operator is called **backstage-system** , this name fits one defined in [kustomization.yaml](../config/default/kustomization.yaml). So, if you consider changing it you have to change it in this file and define **OPERATOR_NAMESPACE** environment variable.
+Following command creates OperatorGroup and Subscription on Operator namespace
 ```sh
-make deploy-olm
+[OPERATOR_NAMESPACE=<operator-namespace>] make deploy-olm
 ```
-5. To undeploy the operator with OLM
+To undeploy the Operator
 ```sh
 make undeploy-olm
 ```
 
-6. To deploy the operator to Openshift with OLM
+#### Convenient commands to build and deploy operator with OLM 
+
+**NOTE:** OLM has to be installed as a prerequisite
+
+* To build and deploy the operator to vanilla Kubernetes with OLM
 ```sh
-make deploy-openshift [IMAGE_TAG_BASE=<your-registry>/backstage-operator]
+[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make deploy-k8s-olm
 ```
 
-### Modifying the API definitions
-If you are editing the API definitions, make sure you:
-- run `make install` before deploying the operator with `make deploy`
-- regenerate the manifests and bundle if you plan to deploy the operator with OLM using:
+* To build and deploy the operator to Openshift with OLM
 ```sh
-make manifests bundle
+[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make deploy-openshift 
 ```
+
+
 **NOTE:** Run `make help` for more information on all potential `make` targets
 
 More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)

integration_tests/README.md

@@ -1,5 +1,5 @@
 
-How to run Integration Tests
+**How to run Integration Tests**
 
 - For development (controller will reconsile internally)
   - As a part of the whole testing suite just:
@@ -27,7 +27,7 @@ For example to run specific test(s) you can use something like:
 
 `make integration-test ARGS='--focus "my favorite test"'`
 
-NOTE:
+**NOTE:**
 
 Some tests are Openshift specific only and skipped in a local envtest and bare k8s cluster.