RHDEVDOCS-7085: CQA 2.0 fixes for Multitenancy support in GitOps

modules/gitops-argocd-projects.adoc

@@ -7,11 +7,13 @@
 = Argo CD projects
 
 [role="_abstract"]
-Argo CD projects, not to be confused with {OCP} projects, provide a way to group applications together. With Argo CD projects, you can specify restrictions on Applications concerning what resources can be deployed and where they can be deployed. Additionally, you can enable Argo CD role-based access control (RBAC) rules and permissions by defining them more granularly at the project level versus the global level in the Argo CD custom resource (CR).
+Argo CD projects, not to be confused with {OCP} projects, provide a way to group applications together. With Argo CD projects, you can specify restrictions on Applications, such as what resources can be deployed and where they can be deployed.
 
-While you can define tenant RBAC globally in the Operator’s Argo CD CR, you should define tenant RBAC along with restrictions in the `AppProject` CR.
+Additionally, you can define Argo CD role-based access control (RBAC) rules at the project level. This approach allows more granular permissions compared to the global settings in the Argo CD custom resource (CR).
 
-If you have a large number of tenants, attempting to manage all tenants with global RBAC might lead to a lot of repetition. 
+While you can define tenant RBAC globally in the Operator's Argo CD CR, you should define tenant RBAC along with restrictions in the `AppProject` CR.
+
+If you have a large number of tenants, attempting to manage all tenants with global RBAC might lead to much repetition. 
 
 If you have many instances of tenants, some of the project configurations might be common across tenant projects. To reduce duplication and minimize maintenance, use global projects for common configuration and inherit them in tenant projects.
 

modules/gitops-argocd-rbac.adoc

@@ -9,7 +9,7 @@
 [role="_abstract"]
 Access controls in {gitops-title} are managed at two distinct levels as follows:
 
-* At the Kubernetes level, the {gitops-shortname} Argo CD Application Controller interacts with one or more clusters to deploy various resources by using a single Kubernetes service account per cluster. This service account must have sufficient permissions to deploy resources for all tenants and use cases that this instance of Argo CD is managing.
-* At the Argo CD level, the {gitops-shortname} Argo CD Application Controller includes its own RBAC permissions model independent of Kubernetes. To manage the user-level access, you can use this RBAC model independently of the underlying Kubernetes permissions. You can use this capability to provide access to Argo CD applications that a user would not have access to from a purely Kubernetes perspective.
+* At the Kubernetes level, the {gitops-shortname} Argo CD Application Controller interacts with one or more clusters to deploy various resources by using a single Kubernetes service account per cluster. This service account must have enough permissions to deploy resources for all tenants and use cases that this instance of Argo CD is managing.
+* At the Argo CD level, the {gitops-shortname} Argo CD Application Controller includes its own RBAC permissions model independent of Kubernetes. To manage the user-level access, you can use this RBAC model independently of the underlying Kubernetes permissions. You can use this capability to give access to Argo CD applications that a user would not have access to from a purely Kubernetes perspective.
 
-Because these two access controls and the interaction between components are distinct and separate, privilege escalation becomes a concern when designing a multitenant solution with Argo CD. Privilege escalation is when a tenant leverages the increased privileges of the application controller’s service account to perform actions they would not typically be permitted to perform. You can mitigate the privilege escalation in an Argo CD instance by using the Argo CD RBAC or separate instances of Argo CD.
+Because these two access controls and the interaction between components are distinct and separate, privilege escalation becomes a concern when designing a multitenant solution with Argo CD. Privilege escalation is when a tenant leverages the increased privileges of the application controller's service account to perform actions they would not typically be permitted to perform. You can mitigate the privilege escalation in an Argo CD instance by using the Argo CD RBAC or separate instances of Argo CD.

modules/gitops-cluster-scoped-instance.adoc

@@ -14,20 +14,22 @@ A cluster-scoped instance is intended to deploy and manage resources across a cl
 If you intend to use the _Applications in any namespace_ feature, choose the mode of the Argo CD instance scope as cluster-scoped instance.
 ====
 
-Cluster-scoped instances have access to cluster-level resources and thus are typically, but not always, used for cluster configuration. You can choose to elevate certain namespace-scoped Argo CD instances to become cluster-scoped. To elevate the instances, you must modify the `Subscription` resource of the {gitops-shortname} Operator.
+Cluster-scoped instances have access to cluster-level resources and thus are typically, but not always, used for cluster configuration. You can choose to elevate certain namespace-scoped Argo CD instances to become cluster-scoped. To elevate the instances, you must change the `Subscription` resource of the {gitops-shortname} Operator.
 
 [IMPORTANT]
 ====
 * Ensure you give careful consideration while elevating instances.
 * Do not elevate instances that are self-managed by application delivery teams. Elevating such instances would be a severe security risk to the cluster because this action makes users of self-managed instances cluster administrators, and gives them full control over the permissions. 
 ====
 
-Much care must be taken when setting up multitenancy configuration within Argo CD. For example, in a use case where cluster administrators want to set up an Argo CD instance that is shared among multiple application delivery teams and is managed by the cluster administrators, having a custom cluster-scoped instance might be what you need.
+Much care must be taken when setting up multitenancy in Argo CD. For example, if cluster administrators manage a shared Argo CD instance for many application teams, a custom cluster-scoped instance might be appropriate.
 
 .How does this method work?
 
 To prevent users from deploying Argo CD instances with `cluster-admin` privileges, you must identify the namespaces with cluster privileges by using the `ARGOCD_CLUSTER_CONFIG_NAMESPACES` environment variable in the `Subscription` resource. 
 
 Because non-cluster administrators do not have access to the `Subscription` resource, they cannot elevate the privileges of their instance and bypass cluster security.
 
-When an instance is designated as cluster-scoped, the Operator automatically creates a set of cluster role and cluster role bindings for the Argo CD Application Controller and server service accounts in that namespace. This default role is not intended to be the equivalent of the standard `cluster-admin` role. It is given a much smaller set of permissions. These permissions can be extended by creating additional cluster roles or cluster role bindings as needed.
+When an instance is designated as cluster-scoped, the Operator automatically creates cluster roles and cluster role bindings. These are created for the Argo CD Application Controller and server service accounts in that namespace.
+
+This default role is not intended to be equal to the standard `cluster-admin` role. It gives a much smaller set of permissions. You can extend these permissions by creating additional cluster roles or cluster role bindings as needed.

modules/gitops-configuring-namespace-management-argocd-tenants.adoc

@@ -52,18 +52,18 @@ apiVersion: argoproj.io/v1alpha1
 kind: ArgoCD
 metadata:
   name: example-argocd
-  namespace: <argocd-ns> # <1>
+  namespace: <argocd_ns> # <1>
 spec:
   namespaceManagement:
-    - name: <tenant-ns> # <2>
+    - name: <tenant_ns> # <2>
       allowManagedBy: true
 ----
 +
 --
 where:
 
-`<metadata.namespace>`:: Specifies the `<argocd-ns>` with the Argo CD instance namespace.
-`<spec.namespaceManagement.name>`:: Specifies the `<tenant-ns>` with the namespace that you want Argo CD to manage. You can also use a glob pattern with wildcards such as `/\*` and `?` for pattern matching. For example, specifying `dev-/\*` matches any namespace with the `dev-` prefix.
+`<metadata.namespace>`:: Specifies the `<argocd_ns>` with the Argo CD instance namespace.
+`<spec.namespaceManagement.name>`:: Specifies the `<tenant_ns>` with the namespace that you want Argo CD to manage. You can also use a glob pattern with wildcards such as `/\*` and `?` for pattern matching. For example, specifying `dev-/\*` matches any namespace with the `dev-` prefix.
 --
 
 . Create a `NamespaceManagement` CR.  
@@ -76,9 +76,9 @@ apiVersion: argoproj.io/v1beta1
 kind: NamespaceManagement
 metadata:
   name: ui-team-namespace
-  namespace: <tenant-ns> # <1>
+  namespace: <tenant_ns> # <1>
 spec:
-  managedBy: <argocd-ns> # <2>
+  managedBy: <argocd_ns> # <2>
 ----
 +
 --
@@ -97,8 +97,8 @@ After you create the `NamespaceManagement` CR, the {gitops-title} Operator autom
 
 You can verify the following resources in the tenant namespace:
 
-* *Roles*: `<argocd-instance-name>-argocd-server`, `<argocd-instance-name>-argocd-application-controller`
-* *RoleBindings*: `<argocd-instance-name>-argocd-server`, `<argocd-instance-name>-argocd-application-controller`
-* *Cluster secret*: `<argocd-instance-name>-cluster`
+* *Roles*: `<argocd_instance_name>-argocd-server`, `<argocd_instance_name>-argocd-application-controller`
+* *RoleBindings*: `<argocd_instance_name>-argocd-server`, `<argocd_instance_name>-argocd-application-controller`
+* *Cluster secret*: `<argocd_instance_name>-cluster`
 
-where, <argocd-instance-name> is the name of your Argo CD instance.
+where, <argocd_instance_name> is the name of your Argo CD instance.

modules/gitops-enable-tenant-namespace-management-with-namespacemanagement.adoc

@@ -13,7 +13,7 @@ _NamespaceManagement CR Overview_
 
 The namespace management feature in {gitops-shortname} introduces a new `NamespaceManagement` custom resource (CR) that allows tenants to delegate control of their own namespaces to Argo CD instances without requiring direct cluster administrator action. For security reasons, this feature is disabled by default and must be explicitly enabled by a cluster administrator.
 
-When enabled, Argo CD administrators can configure namespace management using glob patterns to match one or more namespaces, such as `/\*` or `tenant-/\*`. Tenants then create a `NamespaceManagement` custom resource (CR) in their target namespace. The {gitops-title} Operator automatically provisions the required role-based access control (RBAC) resources and updates the Argo CD cluster secret, ensuring that the namespace is managed correctly.
+When enabled, Argo CD administrators can configure namespace management by using glob patterns to match one or more namespaces, such as `/\*` or `tenant-/\*`. Tenants then create a `NamespaceManagement` custom resource (CR) in their target namespace. The {gitops-title} Operator automatically provisions the required role-based access control (RBAC) resources and updates the Argo CD cluster secret, ensuring that the namespace is managed correctly.
 
 _Effects of `NamespaceManagement` CR_
 

modules/gitops-namespace-scoped-instance.adoc

@@ -7,7 +7,7 @@
 = Namespace-scoped instance (Application delivery instance)
 
 [role="_abstract"]
-After you create an Argo CD custom resource (CR) in one of your namespaces, the {gitops-shortname} Operator starts an Argo CD in this namespace, which you can use for application delivery. In its initial state, this instance has permission to deploy resources only in the same namespace in which it is installed. However, you may need to configure the instance to meet your specific requirements.
+After you create an Argo CD custom resource (CR) in one of your namespaces, the {gitops-shortname} Operator starts an Argo CD in this namespace, which you can use for application delivery. In its initial state, this instance has permission to deploy resources only in the same namespace in which it is installed. However, you might need to configure the instance to meet your specific requirements.
 
 With the {gitops-shortname} Operator, you can extend the permissions of the Argo CD instance to enable the Argo CD Application Controller to deploy resources into other namespaces apart from where it is installed. 
 
@@ -18,19 +18,19 @@ The roles that the {gitops-shortname} Operator in the namespace creates are name
 
 .How does this method work?
 
-The {gitops-shortname} Operator allows OpenShift users to instantiate Argo CD instances in their namespaces, as long as they have permission to create Argo CD resources in the `argoproj.io/v1alpha1` or `argoproj.io/v1beta1` API in their namespace. Currently, a namespace-scoped instance has full administrative permissions for one or many namespaces it manages, similar to allowing all verbs for all resources within that namespace.
+The {gitops-shortname} Operator allows OpenShift users to instantiate Argo CD instances in their namespaces, provided that they have permission to create Argo CD resources in the `argoproj.io/v1alpha1` or `argoproj.io/v1beta1` API in their namespace. Currently, a namespace-scoped instance has full administrative permissions for one or many namespaces it manages, similar to allowing all verbs for all resources within that namespace.
 
-For the Argo CD Application Controller to deploy resources into any other namespace, you need Kubernetes roles and role bindings to label and indicate these namespaces that you want a namespace-scoped instance to manage. The {gitops-shortname} Operator supports the use of the `argocd.argoproj.io/managed-by` label to automatically create these roles and role bindings. Use this label and set the value to indicate the managed namespaces. Then, with the `argocd.argoproj.io/managed-by` label, when you deploy the {gitops-shortname} Operator in the namespace-scoped instance mode, it creates a set of roles and role bindings in every namespace that the instance manages. 
+For the Argo CD Application Controller to deploy resources in other namespaces, you must configure Kubernetes roles and role bindings. These roles and bindings identify the namespaces that a namespace-scoped instance can manage. The {gitops-shortname} Operator supports the argocd.argoproj.io/managed-by label to simplify this setup. Use this label to indicate the namespaces managed by the instance. When you deploy the {gitops-shortname} Operator in namespace-scoped mode, it automatically creates the required roles and role bindings in each labeled namespace.
 
 [IMPORTANT]
 ====
 The `argocd.argoproj.io/managed-by` label only works for namespaces in the same cluster as the {gitops-shortname} Operator. For remote clusters, you must define the permissions manually.
 ====
 
-By default, when labeling the namespace using the `managed-by` label, the {gitops-shortname} Operator gives the Argo CD Application Controller permissions equivalent to the Kubernetes default `admin` cluster role for the labeled namespace. However, you can opt to define an alternate cluster role that is used for the controller and server components by using the `CONTROLLER_CLUSTER_ROLE` and `CONTROLLER_SERVER_ROLE` environment variables respectively in the Operator's `Subscription` resource.  When you provide these variables, the Operator will not create a default role in the namespace but rather only create a role binding in the namespace of the corresponding cluster role. It is up to the administrator to create the cluster role, having full control over the permissions.
+By default, when labeling the namespace by using the `managed-by` label, the {gitops-shortname} Operator gives the Argo CD Application Controller permissions equal to the Kubernetes default `admin` cluster role for the labeled namespace. However, you can opt to define an alternate cluster role that is used for the controller and server components by using the `CONTROLLER_CLUSTER_ROLE` and `CONTROLLER_SERVER_ROLE` environment variables in the Operator's `Subscription` resource. When you give these variables, the Operator will not create a default role in the namespace but rather only create a role binding in the namespace of the corresponding cluster role. It is up to the administrator to create the cluster role, having full control over the permissions.
 
 [NOTE]
 ====
-* When defining your role, Argo CD will attempt to interact with all resources. Therefore, you must either provide permission to `view`, `get`, and `watch` all resources in your custom cluster role, or configure the Argo CD CR to include or exclude specific resources through the `resourceInclusions` or `resourceExclusions` fields defined in the role.
+* When defining your role, Argo CD will attempt to interact with all resources. Therefore, you must either give permission to `view`, `get`, and `watch` all resources in your custom cluster role, or configure the Argo CD CR to include or exclude specific resources through the `resourceInclusions` or `resourceExclusions` fields defined in the role.
 * It is not possible to manage cluster-scoped resources, such as namespaces, custom resource definitions (CRDs), or cluster roles with a namespace-scoped instance.
 ====