diff --git a/docs/cspell.json b/docs/cspell.json index 703859e7d0c04..3b878051fe8d5 100644 --- 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 index d2debdea2c7fe..6466ed86d3be3 100644 --- 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) | `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`. + + +`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. + 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) | + +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. + + ## `persistence`
diff --git a/docs/pages/reference/helm-reference/teleport-kube-agent.mdx b/docs/pages/reference/helm-reference/teleport-kube-agent.mdx index 085328eabc7b4..76ce971338d73 100644 --- 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). + +`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. - - 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. diff --git a/examples/chart/teleport-cluster/templates/NOTES.txt b/examples/chart/teleport-cluster/templates/NOTES.txt index 13de3195049e5..f85e1fa879e28 100644 --- 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 index a1ffd2029ccdb..2efdb2447f0ef 100644 --- 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 index 94ab279dcaf63..79fa48ecc0b08 100644 --- 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 index 4fde7262328a8..3f5efa7d68bb1 100644 --- 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