RHDEVDOCS-7886: Making changes in the respectRBAC feature

declarative_clusterconfig/configuring-an-openshift-cluster-by-deploying-an-application-with-cluster-configurations.adoc

@@ -75,6 +75,9 @@ include::modules/gitops-installing-namespace-scoped-operators.adoc[leveloffset=+
 // About the respectRBAC feature
 include::modules/gitops-about-respect-rbac.adoc[leveloffset=+1]
 
+// Minimum permissions for respectRBAC
+include::modules/ref-gitops-respect-rbac-minimum-permissions.adoc[leveloffset=+2]
+
 // Configuring respectRBAC using the CLI
 include::modules/gitops-configuring-respect-rbac-using-cli.adoc[leveloffset=+2]
 

modules/gitops-about-respect-rbac.adoc

@@ -16,3 +16,13 @@ The `respectRBAC` feature supports the following modes:
 `normal`:: Provides a balance between accuracy and speed. Resource listing is a lightweight operation. Use this mode as the default when enabling `respectRBAC`.
 
 `strict`:: Increases the number of API calls to the server and is more accurate compared to `normal`. Argo CD performs additional validations of RBAC resources to determine permissions. Use this mode if Argo CD reports errors indicating that it cannot access resources when you set the value as `normal`.
+
+[NOTE]
+====
+For cluster-scoped Argo CD instances, disable the default cluster roles to retain full control over the Kubernetes permissions granted to the application-controller. You can achieve this by setting the `ArgoCD.Spec.DefaultClusterScopedRoleDisabled` field to `true`.
+====
+
+[NOTE]
+====
+When `respectRBAC` is enabled on a cluster-scoped Argo CD instance, the application-controller service account still requires cluster-wide permissions for the Application, AppProject, and ApplicationSet resources. Additionally, the server service account needs cluster-wide permissions for the Application and ApplicationSet resources. These permissions are required because the controller establishes watches on these resources independently of the watches Argo CD creates for managed cluster resources.
+====

modules/gitops-configuring-respect-rbac-using-cli.adoc

@@ -34,7 +34,7 @@ spec:
 --
 where:
 
-`metadata.name`:: Specifies the specify the name of the Argo CD instance.
+`metadata.name`:: Specifies the name of the Argo CD instance.
 `spec.controller.respectRBAC`:: Defines the value of the `spec.controller.respectRBAC` key in the `ArgoCD` resource as `normal` or `strict`. Consider setting a value as `normal` to balance accuracy and speed as resource listing is a lightweight operation. Set the value as `strict` if Argo CD reports errors indicating that it cannot access resources when you set the value as `normal`. Setting `strict` increases the number of API calls to the server and it is more accurate compared to `normal` as Argo CD performs additional validations of RBAC resources to determine permissions.
 --
 
@@ -64,3 +64,19 @@ Replace `<argocd_instance_name>` with the name of your Argo CD instance for exam
 $ oc get cm argocd-cm -n <argocd_namespace> -o yaml
 ----
 .. Verify that the `argocd-cm` `ConfigMap` contains the `resource.respectRBAC` parameter and ensure its value is set to either `strict` or `normal`.
+
+[NOTE]
+====
+{OCP}'s basic-user role gives the Argo CD controller service account read-only (`get`/`list`) access to storage classes by default, but not `watch`. If your custom ClusterRole does not add `watch` for this resource, you might see errors such as:
+
+`storageclasses.storage.k8s.io is forbidden: ... cannot watch resource "storageclasses"`
+
+To resolve this error, add `watch` to your ClusterRole's permissions for storage classes:
+
+[source,yaml]
+----
+- apiGroups: ["storage.k8s.io"]
+  resources: ["storageclasses"]
+  verbs: ["get", "list", "watch"]
+----
+====

modules/ref-gitops-respect-rbac-minimum-permissions.adoc

@@ -0,0 +1,101 @@
+// Module included in the following assembly:
+//
+// * declarative_clusterconfig/configuring-an-openshift-cluster-by-deploying-an-application-with-cluster-configurations.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="ref-gitops-respect-rbac-minimum-permissions_{context}"]
+= Minimum permissions for respectRBAC
+
+[role="_abstract"]
+When `respectRBAC` is enabled on a cluster-scoped Argo CD instance with custom cluster roles, you must ensure that the application-controller and server service accounts have the minimum required permissions for Argo CD to function correctly.
+
+The following example shows the minimum set of permissions required for Argo CD to function when `respectRBAC` is enabled:
+
+*Example: minimum ClusterRole for application-controller:*
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: argocd-application-controller-custom
+rules:
+- apiGroups: [""]
+  resources: ["pods", "services", "configmaps"]
+  verbs: ["*"]
+- apiGroups: ["apps"]
+  resources: ["deployments", "replicasets"]
+  verbs: ["*"]
+- apiGroups: ["argoproj.io"]
+  resources: ["*"]
+  verbs: ["*"]
+- apiGroups: ["storage.k8s.io"]
+  resources: ["*"]
+  verbs: ["*"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: argocd-application-controller-custom
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: argocd-application-controller-custom
+subjects:
+- kind: ServiceAccount
+  name: openshift-gitops-openshift-gitops-argocd-application-controller
+  namespace: argocd
+----
+
+*Example: Minimum ClusterRole for server:*
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: argocd-server-custom
+rules:
+- apiGroups:
+  - '*'
+  resources:
+  - '*'
+  verbs:
+  - get
+  - delete
+  - patch
+- apiGroups:
+  - argoproj.io
+  resources:
+  - applications
+  - applicationsets
+  verbs:
+  - list
+  - watch
+- apiGroups:
+  - ""
+  resources:
+  - events
+  verbs:
+  - list
+- apiGroups:
+  - batch
+  resources:
+  - jobs
+  - cronjobs
+  - cronjobs/finalizers
+  verbs:
+  - create
+  - update
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: argocd-server-custom
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: argocd-server-custom
+subjects:
+- kind: ServiceAccount
+  name: openshift-gitops-openshift-gitops-argocd-server
+  namespace: argocd
+----