More doc improvements

docs/2._Development/Helm/1-create-helm-operator.md

@@ -13,12 +13,90 @@ You can create a Helm operator from scratch, or create one based on an existing
 
 ## Set up CI
 
-Use the following `.gitlab-ci.yml`:
+Use the following `.gitlab-ci.yml`, updating `IMAGE_TAG_BASE`.
+
+- For deployment with OLM on app-catalogue, several images are built from the `IMAGE_TAG_BASE` prefix:
+  - the controller itself 
+  - a bundle image with the metadata about the current version (CSV etc.)
+  - the catalog image (for deployment to staging and prod clusters) where each bundle is appended
+- [set up a project](https://gitlab.cern.ch/vcs/harbor-integration-docs/-/blob/master/docs/1._Getting_Started/1-setup-harbor-project.md)
+  on `registry.cern.ch`
+  and [set CI/CD var `DOCKER_AUTH_CONFIG`](https://gitlab.cern.ch/vcs/harbor-integration-docs/-/blob/master/docs/2._Build_Push_And_Run_Image/2-using-gitlab-ci-cd.md)
+  (CI templates for Helm operators do not expect gitlab-registry).
+
 
 ```yaml
+variables:
+  VERSION: 0.0.1
+  # IMAGE_TAG_BASE defines the docker.io namespace and part of the image name for remote images.
+  # This variable is used to construct full image tags for bundle and catalog images.
+  IMAGE_TAG_BASE: "registry.cern.ch/vcs/nexus-cern-operator/nexus-cern-operator"
+  # Image URL to use all building/pushing image targets
+  IMG: "${IMAGE_TAG_BASE}-controller:${VERSION}"
+  BUNDLE_IMG: ${IMAGE_TAG_BASE}-bundle:v${VERSION}
+  # Channel naming
+  # c.f. https://olm.operatorframework.io/docs/best-practices/channel-naming/#recommended-channel-naming
+  # Bundle channels are configured per enviroment
+  BUNDLE_CHANNELS: "--channels='stable'"
+  BUNDLE_DEFAULT_CHANNEL: "--default-channel='stable'"
+  BUNDLE_METADATA_OPTS: "${BUNDLE_CHANNELS} ${BUNDLE_DEFAULT_CHANNEL}"
+  # A comma-separated list of bundle images (e.g. make catalog-build BUNDLE_IMGS=example.com/operator-bundle:v0.1.0,example.com/operator-bundle:v0.2.0).
+  # These images MUST exist in a registry and be pull-able.
+  BUNDLE_IMGS: ${BUNDLE_IMG}
+  # Operator SDK version required.
+  OPERATOR_SDK_VERSION: 1.19.0
+
+include:
+  - project: 'paas-tools/infrastructure-ci'
+    file: 'operator-ci-templates/DockerImages.gitlab-ci.yml'
+
+# DEVELOPMENT PURPOSES #
+#
+# Just use it for development purposes.
+Build and Push Bundle (for development purposes):
+  stage: build-bundle
+  environment: dev
+  except:
+    - tags
+  when: manual
+  needs: []
+
+# STAGING #
+#
+# When pushing to any branch, this will trigger a deployment under the `stable` channel.
+# and to the `catalog:staging` tag (staging clusters)
+# i.e., changes are automatically deployed to https://app-stg-cat.cern.ch
+# This process must be triggered manually and it will build/push the controller, the bundle and the catalog.
+OLM Deployment (staging):
+  stage: deploy-bundle-staging
+  environment: staging
+  except:
+    - tags
+  when: manual
+  needs: []
+  variables:
+    # Set CATALOG_BASE_IMG to an existing catalog image tag to add $BUNDLE_IMGS to that image.
+    # Use staging tag for staging clusters
+    CATALOG_IMG: ${IMAGE_TAG_BASE}-catalog:staging
+#    CATALOG_BASE_IMG: ${IMAGE_TAG_BASE}-catalog:staging
 
+# PRODUCTION #
+#
+# When generating a tag (e.g., 0.0.3), this will trigger a deployment under the `stable` channel.
+# and to the `catalog:latest` tag (production clusters)
+# i.e., changes are automatically deployed to https://app-catalogue.cern.ch
+# This process must be triggered manually and it will build/push the controller, the bundle and the catalog.
+OLM Deployment (production):
+  stage: deploy-bundle-production
+  environment: production
+  when: manual
+  needs: []
+  only:
+    - tags
+  variables:
+    # Set CATALOG_BASE_IMG to an existing catalog image tag to add $BUNDLE_IMGS to that image.
+    # Use latest tag for production clusters
+    CATALOG_IMG: ${IMAGE_TAG_BASE}-catalog:latest
+#    CATALOG_BASE_IMG: ${IMAGE_TAG_BASE}-catalog:latest
 ```
 
-TODO:
-- need workspace on `registry.cern.ch`
-- set CI/CD var `DOCKER_AUTH_CONFIG`

docs/2._Development/Helm/3-develop-new-version.md

 # Develop a new version of the Helm operator
 
-In order to iteratively develop the operator, we must take into account the following concepts:
+## Working on the Helm chart
+
+First step is to develop and test the Helm chart without deploying it via the operator. E.g. on an OKD4 dev cluster
+configured with flavor `paas` or `app-catalogue`:
+
+```bash
+export KUBECONFIG=/my/dev/cluster/admin/kubeconfig
+# create project on behalf of CERN user to have SSO integration working
+oc new-project test-nexus --description "test nexus cern chart" --as=alossent --as-group system:authenticated:oauth --as-group system:authenticated
+# deploy/upgrade our Helm chart, setting some Helm values
+helm upgrade --namespace test-nexus --install nexus1 helm-charts/nexus-cern --set cern-auth-proxy.route.hostname=nexus1.apptest.cern.ch --set init-nexus-config.initialAdminEgroup=it-service-vcs --set nexus-repository-manager.nexus.securityContext=null --reset-values
+```
+
+## Working on the operator itself
+
+Once we have a working Helm chart, we can now deploy an instance of the application using the operator.
+
+Still on an OKD4 dev cluster configured with flavor `paas` or `app-catalogue`:
+
+```bash
+export KUBECONFIG=/my/dev/cluster/admin/kubeconfig
+# deploy CRD to dev cluster
+make install
+# run the operator locally
+make run
+```
+
+Now the operator is running (on our local machine, not on the cluster) and watches for custom resources.
+
+NB: if another version of the operator is installed in the cluster, stop it before running the operator locally!
+Otherwise they will compete with one another.
+
+Create an application instance via the operator:
+
+```bash
+# create another project for an instance provisioned from operator
+oc new-project test-nexus2 --description "test nexus cern operator" --as=alossent --as-group system:authenticated:oauth --as-group system:authenticated
+# create app instance by instantiating a custom resource
+# (assuming we've properly updated the sample when creating our CRD)
+oc create -f config/samples/nexus_v1alpha1_nexus.yaml
+```
+
+## Packaging the operator with OLM
+
+In order to iteratively develop the OLM packaging of the operator, we must take into account the following concepts:
 
 * The `controller manager`.
 * The `bundle`: a representation of the operator in the form of manifests. It will be composed of several resources, like the `CustomResourceDefinition` (CRD), the `ClusterServiceVersion` (CSV), and the necessary service account and RBAC for the controller manager to run.
@@ -9,8 +53,6 @@ In order to iteratively develop the operator, we must take into account the foll
 
 Check <https://docs.okd.io/latest/operators/admin/olm-managing-custom-catalogs.html> for a more detailed description.
 
-## How to develop a new version
-
 To develop a new version of the Helm operator, we will lean in the use of the GitLab CI jobs prepared for the Helm operators purpose (see <https://gitlab.cern.ch/paas-tools/infrastructure-ci/-/blob/master/operator-ci-templates/DockerImages.gitlab-ci.yml>). We will basically simulate how the GitLab CI does but in our local development machine.
 
 These commands are based on the `Makefile` provided by default by the helm operator generated project.
@@ -21,6 +63,13 @@ These commands are based on the `Makefile` provided by default by the helm opera
 
 First version of the operator (`0.0.1`) is a special case for the OKD4 infrastructure, given [how the catalog sources are deployed](https://gitlab.cern.ch/paas-tools/okd4-install/-/tree/master/docs/components/operators-catalogue), so we will deal with it separately.
 
+### Testing the OLM deployment on a dev cluster (optional)
+
+This step can be used to debug the OLM packaging process.
+In general it's optional since once we are happy with our operator using the previous steps,
+we can just commit the changes and let GitLab CI build the OLM catalog (see "committing changes" sections below)
+and then [deploy it on app-catalogue staging or prod instances](../4._Deployment/Helm/1-deploy-new-version.md).
+
 Let's assume we have already deployed the version `0.0.1`, and we want to deploy the version `0.0.2`.
 
 !!! info
@@ -126,7 +175,7 @@ Once we are satifisfied with the result, it is time to commit changes.
 
 Depending on the version we want to deploy, different procedure applies. See below.
 
-## Committing changes for the first version of the operator
+### Committing changes for the first version of the operator
 
 When committing the first version of the operator, there is no existing catalog at that moment, hence we cannot _append_ the new bundle but _add_ it to the catalog.
 
@@ -149,9 +198,11 @@ When committing the first version of the operator, there is no existing catalog
       # CATALOG_BASE_IMG: ${IMAGE_TAG_BASE}-catalog:latest
   ```
 
+* Run `make bundle` once to initialize the clusterserviceversion file
+
 * Ensure removing the `metadata.annotations.olm.skipRange` value under `config\manifests\bases\<operator-name>.clusterserviceversion.yaml`.
 
-## Committing changes for sucessive versions of the operator
+### Committing changes for sucessive versions of the operator
 
 * Update the `VERSION` value under the `.gitlab-ci.yml` file.
 

docs/4._Deployment/Helm/1-deploy-new-version.md

@@ -9,7 +9,7 @@ According to <https://gitlab.cern.ch/paas-tools/infrastructure-ci/-/blob/master/
 In short:
 
 * **Staging cluster**: any branch (including `master`).
-* **Production cluster**: create a new tag.
+* **Production cluster**: create a new tag using the version number (`VERSION` in `.gitlab-ci.yml`), e.g. `0.0.1`
 
 For both cases, go to your GitLab repository, mouse over `CI/CD` > Pipelines > point the appropriate job and execute the `OLM Deployment (staging)` or `OLM Deployment (production)` jobs accordingly.