From eeca47f604a85609eaaa332ed9321140eae36b6b Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Fri, 15 Nov 2024 23:18:03 +0530 Subject: [PATCH 1/6] docs: manual rolebindings for global namespaces Signed-off-by: Faeka Ansari --- .../20-managing-credentials.md | 31 ++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) 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 a3da210ce..734a9f90e 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,35 @@ 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-binding + namespace: kargo +subjects: +- kind: ServiceAccount + name: kargo-controller + namespace: kargo +roleRef: + kind: Role + name: kargo-controller-read-secrets + apiGroup: rbac.authorization.k8s.io +``` + +OR + +(Not recommended) Set `controller.serviceAccount.clusterWideSecretReadingEnabled` +setting to `true` in Kargo's Helm chart. + :::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 From 105977b72aa81780b6b323a32d47d30734b560cb Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Sat, 16 Nov 2024 00:08:11 +0530 Subject: [PATCH 2/6] address reviews by @krancour Signed-off-by: Faeka Ansari --- .../30-how-to-guides/20-managing-credentials.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) 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 734a9f90e..8521bd005 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. @@ -118,7 +118,7 @@ You can do so by creating your own `RoleBinding`s to permit the Kargo apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: - name: kargo-controller-read-secrets-binding + name: kargo-controller-read-secrets namespace: kargo subjects: - kind: ServiceAccount @@ -135,6 +135,12 @@ OR (Not recommended) Set `controller.serviceAccount.clusterWideSecretReadingEnabled` setting to `true` in Kargo's Helm chart. +:::warning +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. +::: + :::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 @@ -154,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.` From 1d0df32dda8aabef4280ab8b9b0926b1464f4f46 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Sat, 16 Nov 2024 00:43:00 +0530 Subject: [PATCH 3/6] update warning and ns-name for rb Signed-off-by: Faeka Ansari --- .../30-how-to-guides/20-managing-credentials.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) 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 8521bd005..2ba75cc1c 100644 --- a/docs/docs/30-how-to-guides/20-managing-credentials.md +++ b/docs/docs/30-how-to-guides/20-managing-credentials.md @@ -119,7 +119,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: kargo-controller-read-secrets - namespace: kargo + namespace: kargo-global-creds subjects: - kind: ServiceAccount name: kargo-controller @@ -132,13 +132,18 @@ roleRef: OR -(Not recommended) Set `controller.serviceAccount.clusterWideSecretReadingEnabled` +Set `controller.serviceAccount.clusterWideSecretReadingEnabled` setting to `true` in Kargo's Helm chart. :::warning -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. +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 `Secrets` throughout the Kargo control +plane's cluster -- including `Secrets` having nothing to do with Kargo. ::: :::note From e2a377e29fdbc6a90ce1954f5e6d87c83e4bc1cb Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Sat, 16 Nov 2024 00:47:42 +0530 Subject: [PATCH 4/6] nit Signed-off-by: Faeka Ansari --- docs/docs/30-how-to-guides/20-managing-credentials.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) 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 2ba75cc1c..1748b9ff5 100644 --- a/docs/docs/30-how-to-guides/20-managing-credentials.md +++ b/docs/docs/30-how-to-guides/20-managing-credentials.md @@ -130,20 +130,15 @@ roleRef: apiGroup: rbac.authorization.k8s.io ``` -OR - -Set `controller.serviceAccount.clusterWideSecretReadingEnabled` -setting to `true` in Kargo's Helm chart. - :::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 +__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 `Secrets` throughout the Kargo control -plane's cluster -- including `Secrets` having nothing to do with 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 From f100b88ae85e32f6c460fd7140b5c3d574de0b0a Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Thu, 21 Nov 2024 05:09:13 +0530 Subject: [PATCH 5/6] divide section into notes, info and warnings Signed-off-by: Faeka Ansari --- .../20-managing-credentials.md | 39 ++++++++++++------- 1 file changed, 24 insertions(+), 15 deletions(-) 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 1748b9ff5..6bfd34e2a 100644 --- a/docs/docs/30-how-to-guides/20-managing-credentials.md +++ b/docs/docs/30-how-to-guides/20-managing-credentials.md @@ -106,29 +106,38 @@ 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: +:::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 + name: kargo-controller-read-secrets + namespace: kargo-global-creds subjects: -- kind: ServiceAccount - name: kargo-controller - namespace: kargo + - kind: ServiceAccount + name: kargo-controller + namespace: kargo roleRef: - kind: Role - name: kargo-controller-read-secrets - apiGroup: rbac.authorization.k8s.io + kind: Role + 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 From 1048484d3cb017ab66a9ddee579a728a8c6c5548 Mon Sep 17 00:00:00 2001 From: Faeka Ansari Date: Wed, 4 Dec 2024 20:13:09 +0530 Subject: [PATCH 6/6] nit: role -> clusterrole Signed-off-by: Faeka Ansari --- docs/docs/30-how-to-guides/20-managing-credentials.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 6bfd34e2a..ebd4b5e1f 100644 --- a/docs/docs/30-how-to-guides/20-managing-credentials.md +++ b/docs/docs/30-how-to-guides/20-managing-credentials.md @@ -123,7 +123,7 @@ subjects: name: kargo-controller namespace: kargo roleRef: - kind: Role + kind: ClusterRole name: kargo-controller-read-secrets apiGroup: rbac.authorization.k8s.io ```