gravitational · hugoShaka · Dec 4, 2025 · Dec 2, 2025
diff --git a/docs/cspell.json b/docs/cspell.json
@@ -92,6 +92,7 @@
     "GOAWAY",
     "GODEBUG",
     "GOMAXPROCS",
+    "GOMEMLIMIT",
     "GSLB",
     "Gbps",
     "Ghostunnel",

diff --git a/docs/pages/includes/helm-reference/zz_generated.teleport-kube-agent.mdx b/docs/pages/includes/helm-reference/zz_generated.teleport-kube-agent.mdx
@@ -1820,6 +1820,23 @@ initContainers:
 See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/)
 for more details.
 
+## `goMemLimitRatio`
+
+| Type | Default |
+|------|---------|
+| `float` | `0.9` |
+
+`goMemLimitRatio` configures the GOMEMLIMIT env var set by the chart.
+GOMEMLIMIT instructs the go garbage collector to try to keep allocated memory
+below a given threshold. This is a best-effort attempt, but this helps
+to prevent OOMs in case of bursts.
+
+When the memory limits are set and goMemLimitRatio is non-zero,
+the chart sets the GOMEMLIMIT to `resources.memory.limits * goMemLimitRatio`.
+The value must be between 0 and 1.
+Set to 0 to unset GOMEMLIMIT.
+This has no effect if GOMEMLIMIT is already set through `extraEnv`.
+
 ## `initSecurityContext`
 
 | Type | Default |

diff --git a/docs/pages/includes/helm-reference/zz_generated.teleport-relay.mdx b/docs/pages/includes/helm-reference/zz_generated.teleport-relay.mdx
@@ -321,6 +321,23 @@ the chart. See [the Kubernetes
 documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/)
 for more details.
 
+## `goMemLimitRatio`
+
+| Type | Default |
+|------|---------|
+| `float` | `0.9` |
+
+`goMemLimitRatio` configures the GOMEMLIMIT env var set by the chart.
+GOMEMLIMIT instructs the go garbage collector to try to keep allocated memory
+below a given threshold. This is a best-effort attempt, but this helps
+to prevent OOMs in case of bursts.
+
+When the memory limits are set and goMemLimitRatio is non-zero,
+the chart sets the GOMEMLIMIT to `resources.memory.limits * goMemLimitRatio`.
+The value must be between 0 and 1.
+Set to 0 to unset GOMEMLIMIT.
+This has no effect if GOMEMLIMIT is already set through `extraEnv`.
+
 ## `service`
 
 `service` options for the Service that points to the Teleport Relay

diff --git a/docs/pages/reference/helm-reference/teleport-cluster.mdx b/docs/pages/reference/helm-reference/teleport-cluster.mdx
@@ -2311,6 +2311,22 @@ See [the GitHub PR](https://github.com/gravitational/teleport/pull/36251) for te
       cpu: 1
       memory: 2Gi
   ```
+## `goMemLimitRatio`
+
+| Type    | Default |
+|---------|---------|
+| `float` | `0.9`   |
+
+`goMemLimitRatio` configures the GOMEMLIMIT env var set by the chart.
+GOMEMLIMIT instructs the go garbage collector to try to keep allocated memory
+below a given threshold. This is a best-effort attempt, but this helps
+to prevent OOMs in case of bursts.
+
+When the memory limits are set and goMemLimitRatio is non-zero,
+the chart sets the GOMEMLIMIT to `resources.memory.limits * goMemLimitRatio`.
+The value must be between 0 and 1.
+Set to 0 to unset GOMEMLIMIT.
+This has no effect if GOMEMLIMIT is already set through `extraEnv`.
 
 ## `podSecurityContext`
 

diff --git a/examples/chart/teleport-cluster/templates/_quantity.tpl b/examples/chart/teleport-cluster/templates/_quantity.tpl
@@ -0,0 +1,39 @@
+{{/* This template tries to parse a resource quantity like Kubernetes does.
+Helm sadly doesn't offer this critical primitive: https://github.com/helm/helm/issues/11376
+The quantity serialization format is described here: https://github.com/kubernetes/apimachinery/blob/master/pkg/api/resource/quantity.go#L33
+
+This template support IEC, SI and decimal notation syntaxes, but has poor error handling.*/}}
+{{- define "teleport-cluster.resource-quantity" -}}
+    {{- $value := . -}}
+    {{- $unit := 1.0 -}}
+    {{- if typeIs "string" . -}}
+        {{- $base2 := dict "Ki" 0x1p10 "Mi" 0x1p20 "Gi" 0x1p30 "Ti" 0x1p40 "Pi" 0x1p50 "Ei" 0x1p60 -}}
+        {{- $base10 := dict "m" 1e-3 "k" 1e3 "M" 1e6 "G" 1e9 "T" 1e12 "P" 1e15 "E" 1e18 -}}
+        {{- range $k, $v := merge $base2 $base10 -}}
+            {{- if hasSuffix $k $ -}}
+                {{- $value = trimSuffix $k $ -}}
+                {{- $unit = $v -}}
+            {{- end -}}
+        {{- end -}}
+    {{- end -}}
+    {{- mulf (float64 $value) $unit -}}
+{{- end -}}
+
+{{/* This renders the GOMEMLIMIT env var unless the user already specified it
+in extraEnv, goMemLimitRatio is set to 0, or requests.memory.limit is unset.
+
+Important: unlike other templates, this should be called on $proxy or $auth instead of .*/}}
+{{- define "teleport-cluster.gomemlimit" -}}
+    {{- $alreadySet := false -}}
+    {{- range $_, $var := .extraEnv -}}
+        {{- if eq $var.name "GOMEMLIMIT" -}}
+            {{- $alreadySet = true -}}
+        {{- end -}}
+    {{- end -}}
+    {{- if and (not $alreadySet) .goMemLimitRatio -}}
+        {{- $ratio := .goMemLimitRatio -}}
+        {{- with .resources }}{{ with .limits }}{{ with .memory -}}
+            {{- include "teleport-cluster.resource-quantity" . | float64 | mulf $ratio | ceil | int -}}
+        {{- end }}{{ end }}{{ end -}}
+    {{- end -}}
+{{- end -}}
diff --git a/examples/chart/teleport-cluster/templates/auth/deployment.yaml b/examples/chart/teleport-cluster/templates/auth/deployment.yaml
@@ -157,8 +157,13 @@ spec:
       - name: "teleport"
         image: '{{ if $auth.enterprise }}{{ $auth.enterpriseImage }}{{ else }}{{ $auth.image }}{{ end }}:{{ include "teleport-cluster.version" . }}'
         imagePullPolicy: {{ $auth.imagePullPolicy }}
-        {{- if or $auth.extraEnv $auth.tls.existingCASecretName }}
+        {{- $gomemlimit := include "teleport-cluster.gomemlimit" $auth }}
+        {{- if or $auth.extraEnv $auth.tls.existingCASecretName $gomemlimit }}
         env:
+        {{- if $gomemlimit }}
+        - name: GOMEMLIMIT
+          value: {{ $gomemlimit | quote }}
+        {{- end }}
         {{- if (gt (len $auth.extraEnv) 0) }}
           {{- toYaml $auth.extraEnv | nindent 8 }}
         {{- end }}

diff --git a/examples/chart/teleport-cluster/templates/proxy/deployment.yaml b/examples/chart/teleport-cluster/templates/proxy/deployment.yaml
@@ -176,8 +176,13 @@ spec:
       - name: "teleport"
         image: '{{ if $proxy.enterprise }}{{ $proxy.enterpriseImage }}{{ else }}{{ $proxy.image }}{{ end }}:{{ include "teleport-cluster.version" . }}'
         imagePullPolicy: {{ $proxy.imagePullPolicy }}
-        {{- if or $proxy.extraEnv $proxy.tls.existingCASecretName }}
+        {{- $gomemlimit := include "teleport-cluster.gomemlimit" $proxy }}
+        {{- if or $proxy.extraEnv $proxy.tls.existingCASecretName $gomemlimit }}
         env:
+        {{- if $gomemlimit }}
+        - name: GOMEMLIMIT
+          value: {{ $gomemlimit | quote }}
+        {{- end }}
         {{- if (gt (len $proxy.extraEnv) 0) }}
           {{- toYaml $proxy.extraEnv | nindent 8 }}
         {{- end }}

diff --git a/examples/chart/teleport-cluster/tests/__snapshot__/auth_deployment_test.yaml.snap b/examples/chart/teleport-cluster/tests/__snapshot__/auth_deployment_test.yaml.snap
@@ -274,6 +274,9 @@ should set resources when set in values:
     - args:
       - --diag-addr=0.0.0.0:3000
       - --apply-on-startup=/etc/teleport/apply-on-startup.yaml
+      env:
+      - name: GOMEMLIMIT
+        value: "3865470567"
       image: public.ecr.aws/gravitational/teleport-distroless:18.4.2
       imagePullPolicy: IfNotPresent
       lifecycle:

diff --git a/examples/chart/teleport-cluster/tests/__snapshot__/proxy_deployment_test.yaml.snap b/examples/chart/teleport-cluster/tests/__snapshot__/proxy_deployment_test.yaml.snap
@@ -349,6 +349,9 @@ should set resources for wait-auth-update initContainer when set in values:
     containers:
     - args:
       - --diag-addr=0.0.0.0:3000
+      env:
+      - name: GOMEMLIMIT
+        value: "3865470567"
       image: public.ecr.aws/gravitational/teleport-distroless:18.4.2
       imagePullPolicy: IfNotPresent
       lifecycle:
@@ -475,6 +478,9 @@ should set resources when set in values:
     containers:
     - args:
       - --diag-addr=0.0.0.0:3000
+      env:
+      - name: GOMEMLIMIT
+        value: "3865470567"
       image: public.ecr.aws/gravitational/teleport-distroless:18.4.2
       imagePullPolicy: IfNotPresent
       lifecycle:

diff --git a/examples/chart/teleport-cluster/tests/auth_deployment_test.yaml b/examples/chart/teleport-cluster/tests/auth_deployment_test.yaml
@@ -1021,3 +1021,102 @@ tests:
               labelSelector:
                 matchLabels:
                   app: baz
+
+  - it: sets GOMEMLIMIT by default (SI unit)
+    template: auth/deployment.yaml
+    set:
+      clusterName: helm-lint
+      resources:
+        limits:
+          memory: "10.5G"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+            value: "9450000000"
+
+  - it: sets GOMEMLIMIT by default (IEC unit)
+    template: auth/deployment.yaml
+    set:
+      clusterName: helm-lint
+      resources:
+        limits:
+          memory: "10.5Gi"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+            value: "10146860237"
+
+  - it: sets GOMEMLIMIT by default (scientific notation)
+    template: auth/deployment.yaml
+    set:
+      clusterName: helm-lint
+      resources:
+        limits:
+          memory: "10.5e9"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+            value: "9450000000"
+
+  - it: honours existing GOMEMLIMIT
+    template: auth/deployment.yaml
+    set:
+      clusterName: helm-lint
+      resources:
+        limits:
+          memory: "10.5G"
+      extraEnv:
+        - name: FOO
+          value: bar
+        - name: GOMEMLIMIT
+          value: "5GB"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+            value: "5GB"
+
+  - it: does not set GOMEMLIMIT if ratio is 0
+    template: auth/deployment.yaml
+    set:
+      clusterName: helm-lint
+      # we set an extra env so contrainers[0].env always exists
+      # this makes testing easier
+      extraEnv:
+        - name: FOO
+          value: bar
+      resources:
+        limits:
+          memory: "10.5G"
+      # we nest under auth to check if merge works properly
+      auth:
+        goMemLimitRatio: 0
+    asserts:
+      - notContains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+            value: "9450000000"
+
+  - it: does not set GOMEMLIMIT if resources are not set
+    template: auth/deployment.yaml
+    set:
+      clusterName: helm-lint
+      # we set an extra env so contrainers[0].env always exists
+      # this makes testing easier
+      extraEnv:
+        - name: FOO
+          value: bar
+    asserts:
+      - notContains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+          any: true
diff --git a/examples/chart/teleport-cluster/tests/proxy_deployment_test.yaml b/examples/chart/teleport-cluster/tests/proxy_deployment_test.yaml
@@ -1140,3 +1140,102 @@ tests:
               labelSelector:
                 matchLabels:
                   app: baz
+
+  - it: sets GOMEMLIMIT by default (SI unit)
+    template: proxy/deployment.yaml
+    set:
+      clusterName: helm-lint
+      resources:
+        limits:
+          memory: "10.5G"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+            value: "9450000000"
+
+  - it: sets GOMEMLIMIT by default (IEC unit)
+    template: proxy/deployment.yaml
+    set:
+      clusterName: helm-lint
+      resources:
+        limits:
+          memory: "10.5Gi"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+            value: "10146860237"
+
+  - it: sets GOMEMLIMIT by default (scientific notation)
+    template: proxy/deployment.yaml
+    set:
+      clusterName: helm-lint
+      resources:
+        limits:
+          memory: "10.5e9"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+            value: "9450000000"
+
+  - it: honours existing GOMEMLIMIT
+    template: proxy/deployment.yaml
+    set:
+      clusterName: helm-lint
+      resources:
+        limits:
+          memory: "10.5G"
+      extraEnv:
+        - name: FOO
+          value: bar
+        - name: GOMEMLIMIT
+          value: "5GB"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+            value: "5GB"
+
+  - it: does not set GOMEMLIMIT if ratio is 0
+    template: proxy/deployment.yaml
+    set:
+      clusterName: helm-lint
+      # we set an extra env so contrainers[0].env always exists
+      # this makes testing easier
+      extraEnv:
+        - name: FOO
+          value: bar
+      resources:
+        limits:
+          memory: "10.5G"
+      # we nest under proxy to check if merge works properly
+      proxy:
+        goMemLimitRatio: 0
+    asserts:
+      - notContains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+            value: "9450000000"
+
+  - it: does not set GOMEMLIMIT if resources are not set
+    template: proxy/deployment.yaml
+    set:
+      clusterName: helm-lint
+      # we set an extra env so contrainers[0].env always exists
+      # this makes testing easier
+      extraEnv:
+        - name: FOO
+          value: bar
+    asserts:
+      - notContains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: "GOMEMLIMIT"
+          any: true