gravitational · hugoShaka · May 9, 2023 · May 5, 2023
diff --git a/docs/cspell.json b/docs/cspell.json
@@ -23,6 +23,7 @@
     "Aqxs",
     "Archlinux",
     "Authy",
+    "authteleportconfig",
     "BDRVJUSUZ",
     "BSFD",
     "BUCKETNAME",
@@ -31,6 +32,7 @@
     "CCDC",
     "CHANGEID",
     "CHANGEME",
+    "chartmode",
     "clientcmd",
     "CLOUDSDK",
     "clusterrolebindings",
@@ -145,6 +147,7 @@
     "Pbbd",
     "Pluggable",
     "Println",
+    "proxyteleportconfig",
     "Quickstart",
     "Quicktime's",
     "rabbitmq",

diff --git a/docs/pages/reference/helm-reference/teleport-cluster.mdx b/docs/pages/reference/helm-reference/teleport-cluster.mdx
@@ -38,7 +38,7 @@ Get started with a guide for each mode:
 | `standalone` | Runs by relying only on Kubernetes resources. | [Getting Started - Kubernetes with SSO](../../deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx) |
 | `aws` | Leverages AWS managed services to store data. | [Running an HA Teleport cluster using an AWS EKS Cluster](../../deploy-a-cluster/helm-deployments/aws.mdx) |
 | `gcp` | Leverages GCP managed services to store data. | [Running an HA Teleport cluster using a Google Cloud GKE cluster](../../deploy-a-cluster/helm-deployments/gcp.mdx) |
-| `scratch` (v12 and above) | Generates empty Teleport configuration. User must pass their own config. | [Running a Teleport cluster with a custom config](../../deploy-a-cluster/helm-deployments/custom.mdx) |
+| `scratch` (v12 and above) | Generates empty Teleport configuration. User must pass their own config. This is discouraged, use `standalone` mode with [`auth.teleportConfig`](#authteleportconfig) and [`proxy.teleportConfig`](#proxyteleportconfig) instead. | [Running a Teleport cluster with a custom config](../../deploy-a-cluster/helm-deployments/custom.mdx) |
 
 <Admonition type="note" title="Custom mode removal">
 `custom` mode has been removed in Teleport version 12. See the [version 12
@@ -124,7 +124,9 @@ auth:
 
 `auth.teleportConfig` contains YAML teleport configuration for auth pods.
 The configuration will be merged with the chart-generated configuration
-and will take precedence in case of conflict.
+and will take precedence in case of conflict. This field allows customization of/overrides to
+any bit of configuration in `teleport.yaml` without having to use
+[the `scratch` chart mode](#chartmode).
 
 The merge logic is as follows:
 - object fields are merged recursively
@@ -175,7 +177,9 @@ proxy:
 
 `proxy.teleportConfig` contains YAML teleport configuration for proxy pods
 The configuration will be merged with the chart-generated configuration
-and will take precedence in case of conflict.
+and will take precedence in case of conflict. This field allows customization of/overrides to
+any bit of configuration in `teleport.yaml` without having to use
+[the `scratch` chart mode](#chartmode).
 
 The merge logic is as follows:
 - object fields are merged recursively
@@ -765,10 +769,21 @@ It is recommended to set resource requests/limits for each container based on th
 |----------|---------------|
 | `string` | `nil`         |
 
-Normally the version of Teleport being used will match the version of the chart being installed. If you install chart version
-10.0.0, you'll be using Teleport 10.0.0. Upgrading the Helm chart will use the latest version from the repo.
+Normally the version of Teleport being used will match the version of the chart
+being installed. If you install chart version 10.0.0, you'll be using Teleport
+10.0.0. Upgrading the Helm chart will use the latest version from the repo.
 
-You can optionally override this to use a different published Teleport Docker image tag like `10.1.2` or `11`.
+You can optionally override this to use a different published Teleport Docker
+image tag like `10.1.2` or `11`.
+
+<Admonition type="danger">
+`teleportVersionOverride` MUST NOT be used to control the Teleport version.
+This chart is designed to run a specific Teleport version. You will face
+compatibility issues trying to run a different Teleport version with it.
+
+If you want to run Teleport version `X.Y.Z`, you should use
+`helm --version X.Y.Z` instead.
+</Admonition>
 
 See our [installation guide](../../installation.mdx#docker) for information on
 Docker image versions.
@@ -923,6 +938,16 @@ Teleport's RBAC policies to define access rules for the cluster.
 | `gcp`        | [Running an HA Teleport cluster using a Google Cloud GKE cluster](../../deploy-a-cluster/helm-deployments/gcp.mdx) |
 | `scratch`    | [Running a Teleport cluster with a custom config](../../deploy-a-cluster/helm-deployments/custom.mdx)              |
 
+<Admonition type="warning">
+Using the `scratch` chart mode is discouraged. Precise chart and Teleport
+knowledge is required to write a fully working cluster configuration.
+
+If you want a working cluster with blocks of custom configuration, it is
+recommended to use one of the other modes and rely on
+[`auth.teleportConfig`](#authteleportconfig) and [`proxy.teleportConfig`](#proxyteleportconfig)
+to inject your custom configuration.
+</Admonition>
+
 ## `persistence`
 
 <Details title="Read this if using Kubernetes 1.23+ on EKS" opened={false}>

diff --git a/docs/pages/reference/helm-reference/teleport-kube-agent.mdx b/docs/pages/reference/helm-reference/teleport-kube-agent.mdx
@@ -784,16 +784,20 @@ You can specify multiple selectors by adding elements to the list.
 |----------|---------------|
 | `string` | `nil`         |
 
-Normally the version of Teleport being used will match the version of the chart being installed. If you install chart version
-10.0.0, you'll be using Teleport 10.0.0.
+Normally the version of Teleport being used will match the version of the chart
+being installed. If you install chart version 10.0.0, you'll be using Teleport
+10.0.0. Upgrading the Helm chart will use the latest version from the repo.
 
-You can optionally override this to use a different published Teleport Docker image tag like `10.2.2` or `11`.
+You can optionally override this to use a different published Teleport Docker
+image tag like `10.1.2` or `11`.
 
-See [this link for information on Community Docker image versions](../../installation.mdx#docker).
+<Admonition type="danger">
+`teleportVersionOverride` is intended for development and MUST NOT be used to control the Teleport version in a typical deployment.
+This chart is designed to run a specific Teleport version. You will face
+compatibility issues trying to run a different Teleport version with it.
 
-<Admonition type="note">
-  The `teleport-kube-agent` chart always runs using Teleport Community edition as it does not require any Enterprise features, so it does
-  not require a Teleport license file to be provided.
+If you want to run Teleport version `X.Y.Z`, you should use
+`helm --version X.Y.Z` instead.
 </Admonition>
 
 <Tabs>

diff --git a/examples/chart/teleport-cluster/templates/NOTES.txt b/examples/chart/teleport-cluster/templates/NOTES.txt
@@ -7,16 +7,8 @@ You can check the status of the certificate with `kubectl -n {{ .Release.Namespa
 NOTE: For certificates to be provisioned, you must also install cert-manager (https://cert-manager.io/docs/) and configure an appropriate
       Issuer with access to your DNS provider to handle DNS01 challenges (https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers)
 
-For more information, please see the Helm guides in the Teleport docs (https://goteleport.com/docs/kubernetes-access/helm/guides/)
-{{- else if (gt (int .Values.highAvailability.replicaCount) 1) }}
-{{- if not (hasKey .Values.annotations.service "service.beta.kubernetes.io/aws-load-balancer-ssl-cert") }}
-You have requested more than 1 replica but have not enabled cert-manager support (highAvailability.certManager.enabled=true) to get ACME certificates, or enabled AWS ACM
-for TLS termination using the service.beta.kubernetes.io/aws-load-balancer-ssl-cert service annotation.
-Your Teleport cluster will not be properly accessible by remote nodes until TLS certificates with the correct clusterName ({{ .Values.clusterName }}) are configured.
-
 For more information, please see the Helm guides in the Teleport docs (https://goteleport.com/docs/kubernetes-access/helm/guides/)
 {{- end }}
-{{- end }}
 
 {{- if and .Values.podSecurityPolicy.enabled (semverCompare "<1.23.0-0" .Capabilities.KubeVersion.Version) }}
 
@@ -31,3 +23,13 @@ See https://goteleport.com/docs/deploy-a-cluster/helm-deployments/migration-kube
 
 To remove this warning, explicitly set "podSecurityPolicy.enabled=false".
 {{- end }}
+
+{{- if .Values.teleportVersionOverride }}
+
+DANGER: `teleportVersionOverride` MUST NOT be used to control the Teleport version.
+This chart is designed to run Teleport version {{ .Chart.AppVersion }}.
+You will face compatibility issues trying to run a different Teleport version with it.
+
+If you want to run Teleport version {{.Values.teleportVersionOverride}},
+you should use `helm --version {{.Values.teleportVersionOverride}}` instead.
+{{- end }}
diff --git a/examples/chart/teleport-cluster/values.yaml b/examples/chart/teleport-cluster/values.yaml
@@ -23,6 +23,11 @@ kubeClusterName: ""
 ##################################################
 
 # Version of teleport image, if different from chart version in Chart.yaml.
+# DANGER: `teleportVersionOverride` MUST NOT be used to control the Teleport version.
+# This chart is designed to run a specific teleport version (see Chart.yaml).
+# You will face compatibility issues trying to run a different Teleport version with it.
+#
+# If you want to run Teleport version X, you should use `helm --version X` instead.
 teleportVersionOverride: ""
 
 # The `teleport-cluster` charts deploys two sets of pods: auth and proxy.
@@ -250,6 +255,9 @@ labels: {}
 # (1) To use "aws" mode, you must also configure the "aws" section below.
 # (2) To use "gcp" mode, you must also configure the "gcp" section below.
 # (3) When set to "scratch", you must write the teleport configuration in auth.teleportConfig and proxy.teleportConfig.
+# `scratch` usage is strongly discouraged, this is a last resort option and
+# everything should be doable with `standalone` mode + overrides through
+# `auth.teleportConfig` and `proxy.teleportConfig`.
 chartMode: standalone
 
 # validateConfigOnDeploy enables a Kubernetes job before install and upgrade that will verify

diff --git a/examples/chart/teleport-kube-agent/templates/NOTES.txt b/examples/chart/teleport-kube-agent/templates/NOTES.txt
@@ -10,3 +10,13 @@ See https://goteleport.com/docs/deploy-a-cluster/helm-deployments/migration-kube
 
 To remove this warning, explicitly set "podSecurityPolicy.enabled=false".
 {{- end }}
+
+{{- if .Values.teleportVersionOverride }}
+
+DANGER: `teleportVersionOverride` MUST NOT be used to control the Teleport version.
+This chart is designed to run Teleport version {{ .Chart.AppVersion }}.
+You will face compatibility issues trying to run a different Teleport version with it.
+
+If you want to run Teleport version {{.Values.teleportVersionOverride}},
+you should use `helm --version {{.Values.teleportVersionOverride}}` instead.
+{{- end }}
diff --git a/examples/chart/teleport-kube-agent/values.yaml b/examples/chart/teleport-kube-agent/values.yaml
@@ -103,7 +103,12 @@ databaseResources: []
 # Values that you may need to change.
 ################################################################
 
-# Version of teleport image, if different from appVersion in Chart.yaml.
+# Version of teleport image, if different from chart version in Chart.yaml.
+# DANGER: `teleportVersionOverride` MUST NOT be used to control the Teleport version.
+# This chart is designed to run a specific teleport version (see Chart.yaml).
+# You will face compatibility issues trying to run a different Teleport version with it.
+#
+# If you want to run Teleport version X, you should use `helm --version X` instead.
 teleportVersionOverride: ""
 
 # Optional CA pins of the auth server. This enables a more secure way of