Skip to content

The open alternative to Salesforce, designed for AI.

feat: add serviceAccount support to Helm chart (#26097)

Md. Minhazul Haque33ba245f0861
diff --git a/packages/twenty-docker/helm/twenty/README.md b/packages/twenty-docker/helm/twenty/README.md
index b9e9874631a..440f3875522 100644
--- a/packages/twenty-docker/helm/twenty/README.md
+++ b/packages/twenty-docker/helm/twenty/README.md
@@ -84,3 +84,12 @@ helm install my-twenty ./packages/twenty-docker/helm/twenty -f values-secrets.ya
- **Image versioning:** The chart defaults to `Chart.yaml`'s `appVersion` (currently v1.14.0). Override via `image.tag` in values to pin a different version or use `latest` for rolling updates.
- **Keep secrets secure:** Avoid `--set` for sensitive values; use `-f values-secrets.yaml` or reference existing Kubernetes Secrets via `server.extraEnvFrom`.
- S3 credentials can be referenced via `storage.s3.secretName + accessKeyIdKey/secretAccessKeyKey` to avoid embedding them in pod specs.
+- **Cloud IAM via ServiceAccount:** Server and worker pods run under the namespace's `default` ServiceAccount unless `serviceAccount.create=true`, which creates a dedicated one named after the release (or `serviceAccount.name`, if set). Grant cloud permissions (e.g. S3 access) without static credentials by enabling it and annotating it:
+ ```yaml
+ serviceAccount:
+ create: true
+ annotations:
+ eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/twenty-role # AWS IRSA
+ # iam.gke.io/gcp-service-account: [email protected] # GCP Workload Identity
+ ```
+ Set `serviceAccount.automount=false` to skip mounting the Kubernetes API token; the server and worker never call the API, and IRSA / Workload Identity keep working.
diff --git a/packages/twenty-docker/helm/twenty/templates/_helpers.tpl b/packages/twenty-docker/helm/twenty/templates/_helpers.tpl
index f9640baf2e0..f1009a6b75b 100644
--- a/packages/twenty-docker/helm/twenty/templates/_helpers.tpl
+++ b/packages/twenty-docker/helm/twenty/templates/_helpers.tpl
@@ -15,6 +15,15 @@
{{ .Release.Namespace }}
{{- end -}}
+{{/* ServiceAccount name used by server/worker pods */}}
+{{- define "twenty.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create -}}
+{{- default (include "twenty.fullname" .) .Values.serviceAccount.name -}}
+{{- else -}}
+{{- default "default" .Values.serviceAccount.name -}}
+{{- end -}}
+{{- end -}}
+
{{/* Server image fields merged with globals */}}
{{- define "twenty.server.image" -}}
{{- $repo := default $.Values.image.repository (index $.Values.server.image "repository" | default "") -}}
diff --git a/packages/twenty-docker/helm/twenty/templates/deployment-server.yaml b/packages/twenty-docker/helm/twenty/templates/deployment-server.yaml
index c87f39fff8c..c1ad30512f5 100644
--- a/packages/twenty-docker/helm/twenty/templates/deployment-server.yaml
+++ b/packages/twenty-docker/helm/twenty/templates/deployment-server.yaml
@@ -30,6 +30,7 @@ spec:
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/component: server
spec:
+ serviceAccountName: {{ include "twenty.serviceAccountName" . }}
securityContext:
{{- toYaml .Values.securityContext | nindent 8 }}
{{- with .Values.server.nodeSelector }}
diff --git a/packages/twenty-docker/helm/twenty/templates/deployment-worker.yaml b/packages/twenty-docker/helm/twenty/templates/deployment-worker.yaml
index 287ff085bb2..d708ee8cde4 100644
--- a/packages/twenty-docker/helm/twenty/templates/deployment-worker.yaml
+++ b/packages/twenty-docker/helm/twenty/templates/deployment-worker.yaml
@@ -26,6 +26,7 @@ spec:
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/component: worker
spec:
+ serviceAccountName: {{ include "twenty.serviceAccountName" . }}
securityContext:
{{- toYaml .Values.securityContext | nindent 8 }}
{{- with .Values.worker.nodeSelector }}
diff --git a/packages/twenty-docker/helm/twenty/templates/serviceaccount.yaml b/packages/twenty-docker/helm/twenty/templates/serviceaccount.yaml
new file mode 100644
index 00000000000..efd605e4887
--- /dev/null
+++ b/packages/twenty-docker/helm/twenty/templates/serviceaccount.yaml
@@ -0,0 +1,15 @@
+{{- if .Values.serviceAccount.create }}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+ name: {{ include "twenty.serviceAccountName" . }}
+ namespace: {{ include "twenty.namespace" . }}
+ labels:
+ app.kubernetes.io/name: {{ include "twenty.name" . }}
+ app.kubernetes.io/instance: {{ .Release.Name }}
+ {{- with .Values.serviceAccount.annotations }}
+ annotations:
+ {{- toYaml . | nindent 4 }}
+ {{- end }}
+automountServiceAccountToken: {{ .Values.serviceAccount.automount }}
+{{- end }}
diff --git a/packages/twenty-docker/helm/twenty/tests/service_account_test.yaml b/packages/twenty-docker/helm/twenty/tests/service_account_test.yaml
new file mode 100644
index 00000000000..b05da3908ac
--- /dev/null
+++ b/packages/twenty-docker/helm/twenty/tests/service_account_test.yaml
@@ -0,0 +1,116 @@
+suite: service account
+templates:
+ - templates/serviceaccount.yaml
+ - templates/deployment-server.yaml
+ - templates/deployment-worker.yaml
+release:
+ name: my-twenty
+ namespace: default
+tests:
+ - it: does not render a ServiceAccount by default
+ template: templates/serviceaccount.yaml
+ asserts:
+ - hasDocuments:
+ count: 0
+
+ - it: creates a ServiceAccount named after the release when enabled
+ template: templates/serviceaccount.yaml
+ set:
+ serviceAccount.create: true
+ asserts:
+ - isKind:
+ of: ServiceAccount
+ - equal:
+ path: metadata.name
+ value: my-twenty-twenty
+ - isNull:
+ path: metadata.annotations
+ - equal:
+ path: automountServiceAccountToken
+ value: true
+
+ - it: can disable API token automount
+ template: templates/serviceaccount.yaml
+ set:
+ serviceAccount.create: true
+ serviceAccount.automount: false
+ asserts:
+ - equal:
+ path: automountServiceAccountToken
+ value: false
+
+ - it: supports a custom name
+ template: templates/serviceaccount.yaml
+ set:
+ serviceAccount.create: true
+ serviceAccount.name: my-custom-sa
+ asserts:
+ - equal:
+ path: metadata.name
+ value: my-custom-sa
+
+ - it: supports AWS IRSA role-arn annotation
+ template: templates/serviceaccount.yaml
+ set:
+ serviceAccount.create: true
+ serviceAccount.annotations:
+ eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/twenty-role
+ asserts:
+ - equal:
+ path: metadata.annotations["eks.amazonaws.com/role-arn"]
+ value: arn:aws:iam::123456789012:role/twenty-role
+
+ - it: supports GCP Workload Identity annotation
+ template: templates/serviceaccount.yaml
+ set:
+ serviceAccount.create: true
+ serviceAccount.annotations:
+ iam.gke.io/gcp-service-account: [email protected]
+ asserts:
+ - equal:
+ path: metadata.annotations["iam.gke.io/gcp-service-account"]
+
+ - it: pods use the "default" service account by default
+ template: templates/deployment-server.yaml
+ asserts:
+ - equal:
+ path: spec.template.spec.serviceAccountName
+ value: default
+
+ - it: server pod uses the generated service account name when enabled
+ template: templates/deployment-server.yaml
+ set:
+ serviceAccount.create: true
+ asserts:
+ - equal:
+ path: spec.template.spec.serviceAccountName
+ value: my-twenty-twenty
+
+ - it: worker pod uses the generated service account name when enabled
+ template: templates/deployment-worker.yaml
+ set:
+ serviceAccount.create: true
+ asserts:
+ - equal:
+ path: spec.template.spec.serviceAccountName
+ value: my-twenty-twenty
+
+ - it: server pod uses the custom service account name when create and name are set
+ template: templates/deployment-server.yaml
+ set:
+ serviceAccount.create: true
+ serviceAccount.name: my-custom-sa
+ asserts:
+ - equal:
+ path: spec.template.spec.serviceAccountName
+ value: my-custom-sa
+
+ - it: pods use an existing service account name when create is false
+ template: templates/deployment-server.yaml
+ set:
+ serviceAccount.name: pre-existing-sa
+ asserts:
+ - equal:
+ path: spec.template.spec.serviceAccountName
+ value: pre-existing-sa
diff --git a/packages/twenty-docker/helm/twenty/values.schema.json b/packages/twenty-docker/helm/twenty/values.schema.json
index 88cf0c9799b..657f0662fd4 100644
--- a/packages/twenty-docker/helm/twenty/values.schema.json
+++ b/packages/twenty-docker/helm/twenty/values.schema.json
@@ -64,6 +64,19 @@
"fullnameOverride": { "type": "string" },
"namespaceOverride": { "type": "string" },
+ "serviceAccount": {
+ "type": "object",
+ "properties": {
+ "create": { "type": "boolean" },
+ "name": { "type": "string" },
+ "automount": { "type": "boolean" },
+ "annotations": {
+ "type": "object",
+ "additionalProperties": { "type": "string" }
+ }
+ }
+ },
+
"secrets": {
"type": "object",
"properties": {
diff --git a/packages/twenty-docker/helm/twenty/values.yaml b/packages/twenty-docker/helm/twenty/values.yaml
index 85a479846db..c6bce7b2d20 100644
--- a/packages/twenty-docker/helm/twenty/values.yaml
+++ b/packages/twenty-docker/helm/twenty/values.yaml
@@ -7,6 +7,15 @@ image:
nameOverride: ""
fullnameOverride: ""
+# ServiceAccount used by the server and worker pods
+serviceAccount:
+ create: false # set true to create a dedicated ServiceAccount instead of using the namespace's "default"
+ name: "" # when create is false, this ServiceAccount must already exist in the namespace; defaults to the chart fullname when create is true
+ automount: true # set false to skip mounting the Kubernetes API token (server and worker do not call the API; IRSA/Workload Identity are unaffected)
+ annotations: {}
+ # eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/twenty-role
+ # iam.gke.io/gcp-service-account: [email protected]
+
# Global security context (uid/gid for all pods)
securityContext:
runAsUser: 1000