diff --git a/docs/docs/30-how-to-guides/20-managing-credentials.md b/docs/docs/30-how-to-guides/20-managing-credentials.md index 3cfb33836..65601e9de 100644 --- a/docs/docs/30-how-to-guides/20-managing-credentials.md +++ b/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.`