chore(backport release-1.1): docs: manual rolebindings for global nam…

…espaces (#3127)

Co-authored-by: Faeka Ansari <[email protected]>

docs/docs/30-how-to-guides/20-managing-credentials.md

@@ -5,7 +5,7 @@ sidebar_label: Managing Credentials
 
 # Managing Credentials
 
-To manage the progression of freight from stage to stage, Kargo will often
+To manage the progression of Freight from Stage to Stage, Kargo will often
 require read/write permissions on private GitOps repositories and read-only
 permissions on private container image and/or Helm chart repositories.
 
@@ -106,6 +106,50 @@ Refer to
 [the advanced section of the installation guide](./10-installing-kargo.md#advanced-installation)
 for more details.
 
+:::note
+Operators must manually ensure Kargo controllers receive read-only access
+to `Secret`s in the designated namespaces. For example, if `kargo-global-creds`
+is designated as a global credentials namespace, the following `RoleBinding`
+should be created within that `Namespace`:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+    name: kargo-controller-read-secrets
+    namespace: kargo-global-creds
+subjects:
+    - kind: ServiceAccount
+      name: kargo-controller
+      namespace: kargo
+roleRef:
+    kind: ClusterRole
+    name: kargo-controller-read-secrets
+    apiGroup: rbac.authorization.k8s.io
+```
+:::
+
+:::info
+By default, Kargo controllers lack cluster-wide permissions on `Secret`
+resources. Instead, the Kargo _management controller_ dynamically expands
+controller access to `Secret`s on a namespace-by-namespace basis as new
+`Project`s are created.
+
+_It is because this process does not account for "global" credential namespaces
+that these bindings must be created manually by an operator._
+:::
+
+:::warning
+Setting `controller.serviceAccount.clusterWideSecretReadingEnabled` setting to
+`true` during Kargo installation will grant Kargo controllers cluster-wide read
+permission on `Secret` resources.
+
+__This is highly discouraged, especially in sharded environments where this
+permission would have the undesirable effect of granting remote Kargo
+controllers read permissions on all `Secret`s throughout the Kargo control
+plane's cluster -- including `Secret`s having nothing to do with Kargo.__
+:::
+
 :::note
 Any matching credentials (exact match _or_ pattern match) found in a project's
 own `Namespace` take precedence over those found in any global credentials
@@ -125,12 +169,6 @@ searched in lexical order by name. Only after no exact match _and_ no pattern
 match is found in one global credentials `Namespace` does Kargo search the next.
 :::
 
-:::caution
-It is important to understand the security implications of this feature. Any
-credentials stored in a global credentials `Namespace` will be available to
-_all_ Kargo projects.
-:::
-
 ## Managing Credentials with the CLI
 
 The Kargo CLI can be used to manage credentials in a project's `Namespace.`