diff --git a/docs/spec/v2/helmreleases.md b/docs/spec/v2/helmreleases.md index 5cd7ab808..6460286a9 100644 --- a/docs/spec/v2/helmreleases.md +++ b/docs/spec/v2/helmreleases.md @@ -945,18 +945,6 @@ To make a HelmRelease react immediately to changes in the referenced Secret or ConfigMap see [this](#reacting-immediately-to-configuration-dependencies) section. -When both `.spec.kubeConfig` and -[`.spec.serviceAccountName`](#service-account-reference) are specified, -the controller will impersonate the ServiceAccount on the target cluster, -i.e. a ServiceAccount with name `.spec.serviceAccountName` must exist in -the target cluster inside a namespace with the same name as the namespace -of the HelmRelease. For example, if the HelmRelease is in the namespace -`apps` of the cluster where Flux is running, then the ServiceAccount -must be in the `apps` namespace of the target remote cluster, and have the -name `.spec.serviceAccountName`. In other words, the namespace of the -HelmRelease must exist both in the cluster where Flux is running -and in the target remote cluster where Flux will apply resources. - The Helm storage is stored on the remote cluster in a namespace that equals to the namespace of the HelmRelease, or the [configured storage namespace](#storage-namespace). The release itself is made in a namespace that equals to the namespace of the @@ -965,6 +953,41 @@ namespaces are expected to exist, with the exception that the target namespace can be created on demand by Helm when namespace creation is [configured during install](#install-configuration). +When both `.spec.kubeConfig` and +[`.spec.serviceAccountName`](#service-account-reference) are specified, +the controller will impersonate the ServiceAccount on the target cluster. +The ServiceAccount must have the necessary RBAC permissions to perform +the operations associated with the HelmRelease. This includes permissions +on both the storage and target namespaces. + +Example of RoleBinding in the target cluster granting the `admin` ClusterRole +in a *namespaced* fashion (scoped to the `rbac-namespace` namespace): + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: admin + # This namespace SHOULD be the storage/target + # namespace on the TARGET cluster. + namespace: rbac-namespace +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole # Can be either Role or ClusterRole for RoleBinding. + name: admin +subjects: +- apiGroup: rbac.authorization.k8s.io + kind: ServiceAccount + name: apps-sa + # This namespace MUST match the HelmRelease namespace + # on the SOURCE cluster. + namespace: apps +``` + +If the storage and target namespaces are different, the RoleBinding +above must be created in both namespaces. You can also create +ClusterRoleBindings if needed (they can only bind ClusterRoles). + Other references to Kubernetes resources in the HelmRelease, like [values references](#values-references), are expected to exist on the cluster where Flux is running.