docs: manual rolebindings for global namespaces

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,41 @@ Refer to
 [the advanced section of the installation guide](./10-installing-kargo.md#advanced-installation)
 for more details.
 
+While doing this you must ensure that the Kargo controller has the appropriate
+permissions to read `Secret` resources in these namespaces. This is necessary because,
+as of Kargo v1.0.0, the controller does not have cluster-wide access to `Secret`s. Permissions
+are granted dynamically on a per-Project basis as `Projects` are created.
+
+You can do so by creating your own `RoleBinding`s to permit the Kargo
+ controller(s) to read Secret(s) from each of those namespaces:
+
+```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: Role
+  name: kargo-controller-read-secrets
+  apiGroup: rbac.authorization.k8s.io
+```
+
+:::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 +160,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.`