Adding options on separate vs. single ServiceAccount

resource-definitions/template-driver/serviceaccount/README.md

@@ -6,12 +6,42 @@ The [`workload` Resource Type](https://developer.humanitec.com/platform-orchestr
 
 This `workload` Resource Definition adds the `serviceAccountName` item to the Pod spec and references a [`k8s-service-account` type Resource](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#k8s-service-account), causing it to be provisioned. The `k8s-service-account` Resource Definition generates the Kubernetes manifest for the actual ServiceAccount.
 
-A Resource Graph for a Workload using those Resource Definitions will look like this:
+The examples demonstrates two alternative approaches:
+
+1. Providing a separate Kubernetes ServiceAccount for each Workload
+
+    This approach lets you fine tune the permissions obtained via the ServiceAccount for each Workload, but create more objects in the Resource Graph and on the cluster.
+
+2. Providing a single Kubernetes ServiceAccount for all Workloads in the same Application Environment
+
+    This approach results in unified permissions for each Workload and less objects in the Resource Graph and on the cluster
+
+For option 1, a Resource Graph for Workloads using those Resource Definitions will look like this:
 
 ```mermaid
 flowchart LR
-  workloadVirtual[Workload &quot;my-workload&quot;] --> workload(id: modules.my-workload<br/>type: workload<br/>class: default)
-  workload --> serviceAccount(id: modules.my-workload<br/>type: k8s-service-account<br/>class: default)
+  workloadVirtual1[Workload &quot;my-workload-1&quot;<br/>defined via Score] -.-> workload1(id: modules.my-workload-1<br/>type: workload<br/>class: default)
+  workload1 --> serviceAccount1(id: modules.my-workload-1<br/>type: k8s-service-account<br/>class: default)
+  workloadVirtual2[Workload &quot;my-workload-2&quot;<br/>defined via Score] -.-> workload2(id: modules.my-workload-2<br/>type: workload<br/>class: default)
+  workload2 --> serviceAccount2(id: modules.my-workload-2<br/>type: k8s-service-account<br/>class: default)
+
+  classDef dotted stroke-dasharray: 5 5;
+  class workloadVirtual1,workloadVirtual2 dotted
 ```
 
-Note that the resource `id` is used in the `k8s-service-account` Resource Definition to derive the name of the actual Kubernetes ServiceAccount. Check the code for details.
+For option 2, a Resource Graph for Workloads using those Resource Definitions will look like this:
+
+```mermaid
+flowchart LR
+  workloadVirtual1[Workload &quot;my-workload-1&quot;<br/>defined via Score] -.-> workload1(id: modules.my-workload-1<br/>type: workload<br/>class: default)
+  workload1 --> serviceAccount(id: ksa<br/>type: k8s-service-account<br/>class: default)
+  workloadVirtual2[Workload &quot;my-workload-2&quot;<br/>defined via Score] -.-> workload2(id: modules.my-workload-2<br/>type: workload<br/>class: default)
+  workload2 --> serviceAccount
+
+  classDef dotted stroke-dasharray: 5 5;
+  class workloadVirtual1,workloadVirtual2 dotted
+```
+
+Check the code in the Resource Definitions to activate the option you wish to use.
+
+In both cases, the resource `id` is used in the `k8s-service-account` Resource Definition to derive the name of the Kubernetes ServiceAccount.

resource-definitions/template-driver/serviceaccount/serviceaccount-k8ssa-def.yaml

@@ -12,7 +12,9 @@ entity:
       res_id: ${context.res.id}
       templates:
         init: |
-          name: {{ index ( .driver.values.res_id | splitList "." ) 1 }}
+          res_id: {{ .driver.values.res_id }}
+          {{- $res_name := .driver.values.res_id | splitList "." | last }}
+          name: {{ $res_name | toRawJson }}
         outputs: |
           name: {{ .init.name }}
         manifests: |
@@ -23,3 +25,5 @@ entity:
               kind: ServiceAccount
               metadata:
                 name: {{ .init.name }}
+                annotations:
+                  hum-res: {{ .init.res_id }}

resource-definitions/template-driver/serviceaccount/serviceaccount-workload-def.yaml

@@ -1,4 +1,5 @@
 # This Resource Definition adds a Kubernetes ServiceAccount to a Workload
+# Note the inline comments on adjusting the setup
 apiVersion: entity.humanitec.io/v1b1
 kind: Definition
 metadata:
@@ -14,4 +15,7 @@ entity:
           update: 
           - op: add
             path: /spec/serviceAccountName
+            # Option 1: separate ServiceAccount per workload. Using the current workload's ID by not specifying an ID
             value: ${resources.k8s-service-account.outputs.name}
+            # Option 2: single ServiceAccount for all workloads. Specifying a fixed ID, e.g. "ksa"
+            # value: ${resources.k8s-service-account#ksa.outputs.name}