Doc RBAC

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

@@ -11,6 +11,38 @@ You can create a Helm operator from scratch, or create one based on an existing
 !!! info
     Note that it is important to properly define the name of the root folder, since the name of this value will be used by the scaffolding code generator.
 
+## Set up RBAC for the operator
+
+The operator will need to be granted explicit permissions to manage the resources created by the Helm chart.
+It's critical to update `config/rbac/role.yaml` with the necessary permissions!
+
+For an OKD app, it will typically be necessary to add these RBAC rules to manage ingress with routes. Notice we need
+`routes/custom-host` to set the route hostname explicitly!
+
+```yaml
+rules:
+- apiGroups:
+  - route.openshift.io
+  resources:
+  - routes
+  - routes/custom-host
+  verbs:
+  - create
+  - delete
+  - get
+  - list
+  - patch
+  - update
+  - watch
+```
+
+The default set of rules may not be sufficient. An easy method to determine the resources your operator needs
+permissions to manage is to `helm template` your Helm chart and grep the output for all generated types of resources.
+
+```bash
+helm template helm-charts/nexus-cern | egrep -e '^apiVersion' -e '^kind:'
+```
+
 ## Set up CI
 
 Use the following `.gitlab-ci.yml`, updating `IMAGE_TAG_BASE`.

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

@@ -13,6 +13,9 @@ oc new-project test-nexus --description "test nexus cern chart" --as=alossent --
 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
 ```
 
+NB: when adding a new resource kind to the Helm chart, don't forget to give the operator controller-manager permissions
+to manage the new resource kind! (in `config/rbac/role.yaml`)
+
 ## Working on the operator itself
 
 Once we have a working Helm chart, we can now deploy an instance of the application using the operator.
@@ -29,7 +32,10 @@ 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!
+NB1: the operator runs under your admin account, so it has all permissions! But when deployed with OLM it will only
+have the permissions granted by `config/rbac/role.yaml`.
+
+NB2: 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:
@@ -42,6 +48,7 @@ oc new-project test-nexus2 --description "test nexus cern operator" --as=alossen
 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:
@@ -199,7 +206,8 @@ 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
+* Run `make bundle` to initialize the clusterserviceversion file, the first time it will ask to provide name,
+  description etc. for the CSV. To be consistent with other operators, check their own CSV.
 
 * Ensure removing the annotation `olm.skipRange` value under `config\manifests\bases\<operator-name>.clusterserviceversion.yaml`.
 
@@ -223,7 +231,7 @@ When committing the first version of the operator, there is no existing catalog
     ...
   ```
 
-* Ensure the `CATALOG_BASE_IMG` variable is not commented out under the `.gitlab-ci.yml` file.
+* Ensure the `CATALOG_BASE_IMG` variable is set under the `.gitlab-ci.yml` file.
 
   ```yaml
     ---
@@ -234,9 +242,13 @@ When committing the first version of the operator, there is no existing catalog
       CATALOG_BASE_IMG: ${IMAGE_TAG_BASE}-catalog:latest
   ```
 
-* Set the annotation `olm.skipRange` value under `config\manifests\bases\<operator-name>.clusterserviceversion.yaml`. E.g. if new `VERSION` is `0.0.3`, annotation `olm.skipRange` MUST be `<0.0.3`.
+* Set the annotation `olm.skipRange` value under `config\manifests\bases\<operator-name>.clusterserviceversion.yaml`. E.g. if new `VERSION` is `0.0.2`, annotation `olm.skipRange` MUST be `<0.0.2`.
   Ref: <https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/how-to-update-operators.md#skiprange>
 
+* Run `VERSION=0.0.2 make bundle` to update the clusterserviceversion under version control. While it's not strictly necessary since CI will
+  run it again, this allows having an up-to-date view of the final CSV under version control (this final CSV is in
+  `bundle/manifests`)
+
 Finally, commit the changes and let the CI do the work for us, i.e., to build and push both the bundle and the catalog, this last containing the bundle we have generated to the appropriate production clusters.
 
 Refer to the [4._Deployment/Helm/1-deploy-new-version.md](../4._Deployment/Helm/1-deploy-new-version.md) document to deploy changes into the corresponding staging/production clusters.