Improve ServiceAccount impersonation docs

Signed-off-by: Matheus Pimenta <[email protected]>

Author: matheuscscp

docs/spec/v1/kustomizations.md

@@ -867,15 +867,52 @@ 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 Kustomization. For example, if the Kustomization 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
-Kustomization must exist both in the cluster where Flux is running
-and in the target remote cluster where Flux will apply resources.
+the controller will impersonate the ServiceAccount username on the target
+cluster, i.e. the username `system:serviceaccount:<namespace>:<name>`, where
+`<namespace>` is the namespace of the Kustomization and `<name>` is the value
+of `.spec.serviceAccountName`. This means that Kubernetes RBAC RoleBindings
+and ClusterRoleBindings must exist on the target cluster granting the required
+permissions to the username `system:serviceaccount:<namespace>:<name>`, or
+directly to the ServiceAccount kind.
+
+Example of RoleBinding on the target cluster granting permissions to the
+ServiceAccount username (through the User kind):
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: apps-sa-binding
+  namespace: apps # This namespace DOES NOT have to match the Kustomization namespace.
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: apps-role
+subjects:
+- apiGroup: rbac.authorization.k8s.io
+  kind: User
+  name: system:serviceaccount:apps:apps-sa # The namespace here HAS to match the Kustomization namespace.
+```
+
+Example of RoleBinding on the target cluster granting permissions through
+the ServiceAccount kind:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: apps-sa-binding
+  namespace: apps # This namespace DOES NOT have to match the Kustomization namespace.
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: apps-role
+subjects:
+- apiGroup: rbac.authorization.k8s.io
+  kind: ServiceAccount
+  name: apps-sa
+  namespace: apps # This namespace HAS to match the Kustomization namespace.
+```
 
 #### Secret-based authentication