Merge pull request #983 from wallrj/olm-configuration

Document how to configure cert-manager via OLM

.spelling

@@ -69,6 +69,7 @@ ClusterIssuer
 ClusterIssuers
 ClusterRole
 ClusterRoles
+ClusterServiceVersion
 ConfigMap
 CoreDNS
 CronJob
@@ -419,6 +420,7 @@ zsh
 PodSecurityPolicy
 ClusterIP
 NodePort
+NodeSelector
 pprof
 GSoD
 GSoC

content/docs/installation/operator-lifecycle-manager.md

@@ -91,9 +91,146 @@ in accordance with [OLM's Recommended Channel Naming][].
 If you have any issues with your installation, please refer to the
 [FAQ](../faq/README.md).
 
+## Configuration
+
+The configuration options are quite limited when you install cert-manager using OLM.
+There are a few Deployment settings which can be overridden permanently in the Subscription
+and most other elements of the cert-manager manifests can be changed by editing the ClusterServiceVersion,
+but changes to the ClusterServiceVersion are temporary and will be lost if OLM upgrades cert-manager,
+because an upgrade results in a new ClusterServiceVersion resource.
+
+### Configuration Via Subscription
+
+When you create an OLM Subscription you can override **some** of the cert-manager Deployment settings,
+but the options are quite limited.
+The configuration which you add to the Subscription will be applied immediately to the current cert-manager Deployments.
+It will also be re-applied if OLM upgrades cert-manager.
+
+> 🔰 Read the [Configuring Operators deployed by OLM](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/subscription-config.md#configuring-operators-deployed-by-olm) design doc in the OLM repository.
+>
+> 🔰 Refer to the [Subscription API documentation](https://pkg.go.dev/github.com/operator-framework/[email protected]/pkg/operators/v1alpha1#Subscription).
+
+Here are some examples of configuration that can be achieved by modifying the Subscription resource.
+In each case we assume that you are starting with the following [default Subscription from OperatorHub.io]((https://operatorhub.io/install/cert-manager.yaml)):
+
+```yaml
+# cert-manager.yaml
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  name: my-cert-manager
+  namespace: operators
+spec:
+  channel: stable
+  name: cert-manager
+  source: operatorhubio-catalog
+  sourceNamespace: olm
+```
+
+```bash
+kubectl create -f https://operatorhub.io/install/cert-manager.yaml
+```
+
+#### Change the Resource Requests and Limits
+
+It is possible to change the resource requests and limits by adding a `config` stanza to the Subscription:
+
+```yaml
+# resources-patch.yaml
+spec:
+  config:
+    resources:
+      requests:
+        memory: "64Mi"
+        cpu: "250m"
+      limits:
+        memory: "128Mi"
+        cpu: "500m"
+```
+
+
+```bash
+kubectl -n operators patch subscription my-cert-manager --type merge --patch-file resources-patch.yaml
+```
+
+You will see **all** the cert-manager Pods are restarted with the new resources:
+
+```console
+$ kubectl -n operators get pods -o "custom-columns=name:.metadata.name,mem:.spec.containers[*].resources"
+name                                       mem
+cert-manager-669867589c-n8dcn              map[limits:map[cpu:500m memory:128Mi] requests:map[cpu:250m memory:100Mi]]
+cert-manager-cainjector-7b7fff8b9c-dxw6b   map[limits:map[cpu:500m memory:128Mi] requests:map[cpu:250m memory:100Mi]]
+cert-manager-webhook-975bc87b5-tqdj4       map[limits:map[cpu:500m memory:128Mi] requests:map[cpu:250m memory:100Mi]]
+```
+
+> ⚠️ This configuration will apply to **all** the cert-manager Deployments.
+> This is a known limitation of OLM which [does not support configuration of individual Deployments](https://github.com/operator-framework/operator-lifecycle-manager/issues/1794).
+
+#### Change the NodeSelector
+
+It is possible to change the `nodeSelector` for cert-manager Pods by adding the following stanza to the Subscription:
+
+```yaml
+# nodeselector-patch.yaml
+spec:
+  config:
+    nodeSelector:
+      kubernetes.io/arch: amd64
+```
+
+```bash
+kubectl -n operators patch subscription my-cert-manager --type merge --patch-file nodeselector-patch.yaml
+```
+
+You will see **all** the cert-manager Pods are restarted with the new `nodeSelector`:
+
+```console
+$ kubectl -n operators get pods -o "custom-columns=name:.metadata.name,nodeselector:.spec.nodeSelector"
+name                                      nodeselector
+cert-manager-5b6b8f7d74-k7l94             map[kubernetes.io/arch:amd64 kubernetes.io/os:linux]
+cert-manager-cainjector-b89cd6f46-kdkk2   map[kubernetes.io/arch:amd64 kubernetes.io/os:linux]
+cert-manager-webhook-8464bc7cc8-64b4w     map[kubernetes.io/arch:amd64 kubernetes.io/os:linux]
+```
+
+> ⚠️ This configuration will apply to **all** the cert-manager Deployments.
+> This is a known limitation of OLM which [does not support configuration of individual Deployments](https://github.com/operator-framework/operator-lifecycle-manager/issues/1794).
+
+### Configuration Via ClusterServiceVersion (CSV)
+
+The ClusterServiceVersion (CSV) resource contains the templates for all the cert-manager Deployments.
+If you patch these templates, OLM will immediately roll out the changes to the Deployments.
+
+> ⚠️ If OLM upgrades cert-manager your changes will be lost because it will create a new CSV with default Deployment templates.
+
+Nevertheless, editing (patching) the CSV can be a useful way to override certain cert-manager settings. An example:
+
+#### Change the log level of cert-manager components
+
+The following JSON patch will append `-v=6` to command line arguments of the cert-manager controller-manager
+(the first container of the first Deployment).
+
+```bash
+kubectl patch csv cert-manager.v1.8.0 \
+  --type json \
+  -p '[{"op": "add", "path": "/spec/install/spec/deployments/0/spec/template/spec/containers/0/args/-", "value": "-v=6" }]'
+```
+
+You will see the controller-manager Pod is restarted with the new arguments.
+
+```console
+$ kubectl  -n operators get pods -o "custom-columns=name:.metadata.name,args:.spec.containers[0].args"
+name                                      args
+cert-manager-797979cbdb-g444r             [-v=2 --cluster-resource-namespace=$(POD_NAMESPACE) --leader-election-namespace=kube-system -v=6]
+...
+```
+
+> 🔰 Refer to the [ClusterServiceVersion API documentation](https://pkg.go.dev/github.com/operator-framework/[email protected]/pkg/operators/v1alpha1#ClusterServiceVersion).
+
+## Uninstall
+
 Below is the processes for uninstalling cert-manager on OpenShift.
 
-> **Warning**: To uninstall cert-manger you should always use the same process for
+> ⚠️ To uninstall cert-manger you should always use the same process for
 > installing but in reverse. Deviating from the following process can cause
 > issues and potentially broken states. Please ensure you follow the below steps
 > when uninstalling to prevent this happening.