docs: Improve RBAC documentation (#15430)

* Improve staging-db project name

This change renames the project to distinguish it from the role.

Signed-off-by: Andreas Lindhé <[email protected]>

* Rename db-staging role to singular form

Role names should be singular ("User x has the role admin" as opposed to
"User x has the role admins").

Signed-off-by: Andreas Lindhé <[email protected]>

* Remove trailing newlines

Signed-off-by: Andreas Lindhé <[email protected]>

* Consistently mark `AppProject` as code

Signed-off-by: Andreas Lindhé <[email protected]>

* Replace ```shell with ```console in suitable places

Signed-off-by: Andreas Lindhé <[email protected]>

* Use consistent style for unordered list

https://github.com/DavidAnson/markdownlint/blob/main/doc/md004.md

Signed-off-by: Andreas Lindhé <[email protected]>

* Use consistent emphasis style

https://github.com/DavidAnson/markdownlint/blob/main/doc/md049.md

Signed-off-by: Andreas Lindhé <[email protected]>

* Fix incorrect description of the staging-db example

Signed-off-by: Andreas Lindhé <[email protected]>

---------

Signed-off-by: Andreas Lindhé <[email protected]>

docs/operator-manual/rbac.md

@@ -2,7 +2,7 @@
 
 The RBAC feature enables restriction of access to Argo CD resources. Argo CD does not have its own
 user management system and has only one built-in user `admin`. The `admin` user is a superuser and
-it has unrestricted access to the system. RBAC requires [SSO configuration](user-management/index.md) or [one or more local users setup](user-management/index.md). 
+it has unrestricted access to the system. RBAC requires [SSO configuration](user-management/index.md) or [one or more local users setup](user-management/index.md).
 Once SSO or local users are configured, additional RBAC roles can be defined, and SSO groups or local users can then be mapped to roles.
 
 ## Basic Built-in Roles
@@ -22,7 +22,7 @@ Breaking down the permissions definition differs slightly between applications a
 
     `p, <role/user/group>, <resource>, <action>, <object>`
 
-* Applications, applicationsets, logs, and exec (which belong to an AppProject):
+* Applications, applicationsets, logs, and exec (which belong to an `AppProject`):
 
     `p, <role/user/group>, <resource>, <action>, <appproject>/<object>`
 
@@ -59,7 +59,7 @@ also use glob patterns in the action path: `action/*` (or regex patterns if you
 
 #### The `exec` resource
 
-`exec` is a special resource. When enabled with the `create` action, this privilege allows a user to `exec` into Pods via 
+`exec` is a special resource. When enabled with the `create` action, this privilege allows a user to `exec` into Pods via
 the Argo CD UI. The functionality is similar to `kubectl exec`.
 
 See [Web-based Terminal](web_based_terminal.md) for more info.
@@ -68,7 +68,7 @@ See [Web-based Terminal](web_based_terminal.md) for more info.
 
 [ApplicationSets](applicationset/index.md) provide a declarative way to automatically create/update/delete Applications.
 
-Granting `applicationsets, create` effectively grants the ability to create Applications. While it doesn't allow the 
+Granting `applicationsets, create` effectively grants the ability to create Applications. While it doesn't allow the
 user to create Applications directly, they can create Applications via an ApplicationSet.
 
 In v2.5, it is not possible to create an ApplicationSet with a templated Project field (e.g. `project: {{path.basename}}`)
@@ -101,19 +101,19 @@ p, role:extension, extensions, invoke, httpbin, allow
 
 Explanation:
 
-- *line1*: defines the group `role:extension` associated with the
+* *line1*: defines the group `role:extension` associated with the
   subject `ext`.
-- *line2*: defines a policy allowing this role to read (`get`) the
+* *line2*: defines a policy allowing this role to read (`get`) the
   `httpbin-app` application in the `default` project.
-- *line3*: defines another policy allowing this role to `invoke` the
+* *line3*: defines another policy allowing this role to `invoke` the
   `httpbin` extension.
 
 **Note 1**: that for extensions requests to be allowed, the policy defined
-in the *line2* is also required. 
+in the *line2* is also required.
 
 **Note 2**: `invoke` is a new action introduced specifically to be used
 with the `extensions` resource. The current actions for `extensions`
-are `*` or `invoke`. 
+are `*` or `invoke`.
 
 ## Tying It All Together
 
@@ -123,7 +123,7 @@ configures a custom role, named `org-admin`. The role is assigned to any user wh
 which cannot modify Argo CD settings.
 
 !!! warning
-    All authenticated users get _at least_ the permissions granted by the default policy. This access cannot be blocked 
+    All authenticated users get *at least* the permissions granted by the default policy. This access cannot be blocked
     by a `deny` rule. Instead, restrict the default policy and then grant permissions to individual roles as needed.
 
 *ArgoCD ConfigMap `argocd-rbac-cm` Example:*
@@ -157,19 +157,24 @@ data:
 Another `policy.csv` example might look as follows:
 
 ```csv
-p, role:staging-db-admins, applications, create, staging-db-admins/*, allow
-p, role:staging-db-admins, applications, delete, staging-db-admins/*, allow
-p, role:staging-db-admins, applications, get, staging-db-admins/*, allow
-p, role:staging-db-admins, applications, override, staging-db-admins/*, allow
-p, role:staging-db-admins, applications, sync, staging-db-admins/*, allow
-p, role:staging-db-admins, applications, update, staging-db-admins/*, allow
-p, role:staging-db-admins, logs, get, staging-db-admins/*, allow
-p, role:staging-db-admins, exec, create, staging-db-admins/*, allow
-p, role:staging-db-admins, projects, get, staging-db-admins, allow
-g, db-admins, role:staging-db-admins
+p, role:staging-db-admin, applications, create, staging-db-project/*, allow
+p, role:staging-db-admin, applications, delete, staging-db-project/*, allow
+p, role:staging-db-admin, applications, get, staging-db-project/*, allow
+p, role:staging-db-admin, applications, override, staging-db-project/*, allow
+p, role:staging-db-admin, applications, sync, staging-db-project/*, allow
+p, role:staging-db-admin, applications, update, staging-db-project/*, allow
+p, role:staging-db-admin, logs, get, staging-db-project/*, allow
+p, role:staging-db-admin, exec, create, staging-db-project/*, allow
+p, role:staging-db-admin, projects, get, staging-db-project, allow
+g, db-admins, role:staging-db-admin
 ```
 
-This example defines a *role* called `staging-db-admins` with *nine permissions* that allow that role to perform the *actions* (`create`/`delete`/`get`/`override`/`sync`/`update` applications, `get` logs, `create` exec and `get` appprojects) against `*` (all) objects in the `staging-db-admins` Argo CD AppProject.
+This example defines a *role* called `staging-db-admin` with nine *permissions* that allow users with that role to perform the following *actions*:
+
+* `create`, `delete`, `get`, `override`, `sync` and `update` for applications in the `staging-db-project` project,
+* `get` logs for objects in the `staging-db-project` project,
+* `create` exec for objects in the `staging-db-project` project, and
+* `get` for the project named `staging-db-project`.
 
 !!! note
     The `scopes` field controls which OIDC scopes to examine during rbac
@@ -281,38 +286,43 @@ Given the example from the above ConfigMap, which defines the role
 `role:org-admin`, and is stored on your local system as `argocd-rbac-cm-yaml`,
 you can test whether that role can do something like follows:
 
-```shell
+```console
 $ argocd admin settings rbac can role:org-admin get applications --policy-file argocd-rbac-cm.yaml
 Yes
+
 $ argocd admin settings rbac can role:org-admin get clusters --policy-file argocd-rbac-cm.yaml
 Yes
+
 $ argocd admin settings rbac can role:org-admin create clusters 'somecluster' --policy-file argocd-rbac-cm.yaml
 No
+
 $ argocd admin settings rbac can role:org-admin create applications 'someproj/someapp' --policy-file argocd-rbac-cm.yaml
 Yes
 ```
 
 Another example,  given the policy above from `policy.csv`, which defines the
-role `role:staging-db-admins` and associates the group `db-admins` with it.
+role `role:staging-db-admin` and associates the group `db-admins` with it.
 Policy is stored locally as `policy.csv`:
 
 You can test against the role:
 
-```shell
-# Plain policy, without a default role defined
-$ argocd admin settings rbac can role:staging-db-admins get applications --policy-file policy.csv
+```console
+$ # Plain policy, without a default role defined
+$ argocd admin settings rbac can role:staging-db-admin get applications --policy-file policy.csv
 No
-$ argocd admin settings rbac can role:staging-db-admins get applications 'staging-db-admins/*' --policy-file policy.csv
+
+$ argocd admin settings rbac can role:staging-db-admin get applications 'staging-db-project/*' --policy-file policy.csv
 Yes
-# Argo CD augments a builtin policy with two roles defined, the default role
-# being 'role:readonly' - You can include a named default role to use:
-$ argocd admin settings rbac can role:staging-db-admins get applications --policy-file policy.csv --default-role role:readonly
+
+$ # Argo CD augments a builtin policy with two roles defined, the default role
+$ # being 'role:readonly' - You can include a named default role to use:
+$ argocd admin settings rbac can role:staging-db-admin get applications --policy-file policy.csv --default-role role:readonly
 Yes
 ```
 
 Or against the group defined:
 
-```shell
-$ argocd admin settings rbac can db-admins get applications 'staging-db-admins/*' --policy-file policy.csv
+```console
+$ argocd admin settings rbac can db-admins get applications 'staging-db-project/*' --policy-file policy.csv
 Yes
 ```