From 867095e0cc19816682dc0c581707d87b8ee5307a Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Tue, 22 Mar 2022 13:47:57 -0400 Subject: [PATCH] Split the Helm chart reference Backports #11292 This will make it easier to navigate to different values settings for each chart, since values can have their own H2 sections that are distinct from chart names. (Previously, both chart names and values settings were organized into H2 section headings.) This will also mean that edition warnings for Cloud users can be more visible, since we can place them at the top of a page for a given chart. See #10636 --- docs/config.json | 12 +- .../getting-started/agent.mdx | 2 +- .../kubernetes-access/helm/guides/aws.mdx | 7 +- .../kubernetes-access/helm/guides/gcp.mdx | 4 +- .../teleport-cluster-cloud-warning.mdx | 2 +- .../kubernetes-access/helm/reference.mdx | 2745 +---------------- .../helm/reference/teleport-cluster.mdx | 1425 +++++++++ .../helm/reference/teleport-kube-agent.mdx | 1334 ++++++++ 8 files changed, 2787 insertions(+), 2744 deletions(-) create mode 100644 docs/pages/kubernetes-access/helm/reference/teleport-cluster.mdx create mode 100644 docs/pages/kubernetes-access/helm/reference/teleport-kube-agent.mdx diff --git a/docs/config.json b/docs/config.json index 8bc8f70e95127..52932f998d8da 100644 --- a/docs/config.json +++ b/docs/config.json @@ -386,7 +386,17 @@ }, { "title": "Helm Chart Reference", - "slug": "/kubernetes-access/helm/reference/" + "slug": "/kubernetes-access/helm/reference/", + "entries": [ + { + "title": "teleport-cluster", + "slug": "/kubernetes-access/helm/reference/teleport-cluster/" + }, + { + "title": "teleport-kube-agent", + "slug": "/kubernetes-access/helm/reference/teleport-kube-agent/" + } + ] }, { "title": "Access Controls", diff --git a/docs/pages/kubernetes-access/getting-started/agent.mdx b/docs/pages/kubernetes-access/getting-started/agent.mdx index 5a4e17c05a5b3..f76f99cc6b20f 100644 --- a/docs/pages/kubernetes-access/getting-started/agent.mdx +++ b/docs/pages/kubernetes-access/getting-started/agent.mdx @@ -162,4 +162,4 @@ $ kubectl get pods ## Next Steps -- Take a look at a [kube-agent helm chart reference](../helm/reference.mdx#teleport-kube-agent) for a full list of parameters. +- Take a look at a [kube-agent helm chart reference](../helm/reference/teleport-kube-agent.mdx) for a full list of parameters. diff --git a/docs/pages/kubernetes-access/helm/guides/aws.mdx b/docs/pages/kubernetes-access/helm/guides/aws.mdx index 515953782e991..9705f44023307 100644 --- a/docs/pages/kubernetes-access/helm/guides/aws.mdx +++ b/docs/pages/kubernetes-access/helm/guides/aws.mdx @@ -525,9 +525,8 @@ $ helm --namespace cert-manager uninstall cert-manager ## Next steps -You can follow our [Getting Started with Teleport guide](../../../setup/guides/docker.mdx#step-34-creating-a-teleport-user) to finish setting up your +- You can follow our [Getting Started with Teleport guide](../../../setup/guides/docker.mdx#step-34-creating-a-teleport-user) to finish setting up your Teleport cluster. +- See the [high availability section of our Helm chart reference](../reference/teleport-cluster.mdx#highavailability) for more details on high availability. +- Read the [`cert-manager` documentation](https://cert-manager.io/docs/). -See the [high availability section of our Helm chart reference](../reference.mdx#highavailability) for more details on high availability. - -Reference: [`cert-manager` docs](https://cert-manager.io/docs/). diff --git a/docs/pages/kubernetes-access/helm/guides/gcp.mdx b/docs/pages/kubernetes-access/helm/guides/gcp.mdx index 7cd82598e7aa8..73554e7f73d92 100644 --- a/docs/pages/kubernetes-access/helm/guides/gcp.mdx +++ b/docs/pages/kubernetes-access/helm/guides/gcp.mdx @@ -409,7 +409,7 @@ To make changes to your Teleport cluster after deployment, you can use `helm upg Helm defaults to using the latest version of the chart available in the repo, which will also correspond to the latest version of Teleport. You can make sure that the repo is up to date by running `helm repo update`. -If you want to use a different version of Teleport, set the [`teleportVersionOverride`](../reference.mdx#teleportversionoverride) value. +If you want to use a different version of Teleport, set the [`teleportVersionOverride`](../reference/teleport-cluster.mdx#teleportversionoverride) value. Here's an example where we set the chart to use 3 replicas: @@ -463,4 +463,4 @@ $ helm --namespace cert-manager uninstall cert-manager You can follow our [Getting Started with Teleport guide](../../../setup/guides/docker.mdx#step-34-creating-a-teleport-user) to finish setting up your Teleport cluster. -See the [high availability section of our Helm chart reference](../reference.mdx#highavailability) for more details on high availability. +See the [high availability section of our Helm chart reference](../reference/teleport-cluster.mdx#highavailability) for more details on high availability. diff --git a/docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx b/docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx index de1279c19c48f..552769882816d 100644 --- a/docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx +++ b/docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx @@ -6,5 +6,5 @@ Since the Auth and Proxy Services are fully managed in Teleport Cloud, you shoul You can use the `teleport-kube-agent` chart to enable the Application Service and Database Service in addition to the Kubernetes Service. -For more information, see our [Helm chart reference](../reference.mdx#teleport-kube-agent). +For more information, see our [Helm chart reference](../reference/teleport-kube-agent.mdx). \ No newline at end of file diff --git a/docs/pages/kubernetes-access/helm/reference.mdx b/docs/pages/kubernetes-access/helm/reference.mdx index 72a34ad1b921f..db2e96e8bb683 100644 --- a/docs/pages/kubernetes-access/helm/reference.mdx +++ b/docs/pages/kubernetes-access/helm/reference.mdx @@ -3,2742 +3,17 @@ title: Helm chart reference description: A list of values that can be set using Teleport Helm charts and their purpose --- -The Teleport Helm repository hosts two Helm charts: + + +![Teleport ](../../../img/k8s/mini-diagrams/teleport-in-k8s-mono.svg) -- [`teleport-cluster`](#teleport-cluster) [(source on Github)](https://github.com/gravitational/teleport/tree/master/examples/chart/teleport-cluster) -- [`teleport-kube-agent`](#teleport-kube-agent) [(source on Github)](https://github.com/gravitational/teleport/tree/master/examples/chart/teleport-kube-agent) +Deploy the Teleport Auth Service and Proxy Service on Kubernetes. -(!docs/pages/includes/backup-warning.mdx!) + + +![Kubernetes agent](../../../img/k8s/mini-diagrams/k8s-to-teleport-mono.svg) -## `teleport-cluster` +Deploy the Teleport Kubernetes Service, Application Service, or Database Service on Kubernetes. -The `teleport-cluster` Helm chart is used to configure a Teleport cluster. It runs two Teleport services: - -| Teleport service | Purpose | Documentation | -| - | - | - | -| `auth_service` | Authenticates users and hosts, and issues certificates | [Auth documentation](../../architecture/authentication.mdx) -| `proxy_service`| Runs the externally-facing parts of a Teleport cluster, such as the web UI, SSH proxy and reverse tunnel service | [Proxy documentation](../../architecture/proxy.mdx) | - -The `teleport-cluster` chart can be deployed in four different modes. Get started with a guide for each mode: - -| `chartMode` | Guide | -| - | - | -| `standalone` | [Getting started with Kubernetes Access](../getting-started.mdx) | -| `aws` | [Running an HA Teleport cluster using an AWS EKS Cluster](./guides/aws.mdx) | -| `gcp` | [Running an HA Teleport cluster using a Google Cloud GKE cluster](./guides/gcp.mdx) | -| `custom` | [Running a Teleport cluster with a custom config](./guides/custom.mdx) | - -This reference details available values for the `teleport-cluster` chart. - -## `clusterName` - -| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | -| - | - | - | - | - | -| `string` | `nil` | When `chartMode` is `aws`, `gcp` or `standalone` | `auth_service.cluster_name`, `proxy_service.public_addr` | ✅ | - -`clusterName` controls the name used to refer to the Teleport cluster, along with the externally-facing public address to use to access it. - - - If using a fully qualified domain name as your `clusterName`, you will also need to configure the DNS provider for this domain to point - to the external load balancer address of your Teleport cluster. - - (!docs/pages/kubernetes-access/helm/includes/kubernetes-externaladdress.mdx!) - - You will need to manually add a DNS A record pointing `teleport.example.com` to either the IP or hostname of the Kubernetes load balancer. - -
-(!docs/pages/includes/dns-app-access.mdx!) -
- - If you are not using ACME certificates, you may also need to accept insecure warnings in your browser to view the page successfully. - - - -## `kubeClusterName` - -| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | -| - | - | - | - | - | -| `string` | `clusterName` value | no | `kubernetes_service.kube_cluster_name` | ✅ | - -`kubeClusterName` sets the name used for the Kubernetes cluster. This name will be shown to Teleport users connecting to the cluster. - -## `authenticationType` - -| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | -| - | - | - | - | - | -| `string` | `local` | Yes | `auth_service.authentication.type` | ❌ | - -`authenticationType` controls the authentication scheme used by Teleport. Possible values are `local` and `github` for OSS, plus `oidc`, `saml`, and `false` for Enterprise. - -## `authenticationSecondFactor` - -### `authenticationSecondFactor.secondFactor` - -| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | -| - | - | - | - | - | -| `string` | `otp` | Yes | `auth_service.authentication.second_factor` | ❌ | - -`authenticationSecondFactor.secondFactor` controls the second factor used for local user authentication. Possible values supported by this chart -are `off` (not recommended), `on`, `otp`, `optional` and `webauthn`. - -When set to `on`, `optional` or `webauthn`, the `authenticationSecondFactor.webauthn` section can also be used. The configured `rp_id` defaults to -the FQDN which is used to access the Teleport cluster. - -### `authenticationSecondFactor.webauthn` - -See [Second Factor - WebAuthn](../../access-controls/guides/webauthn.mdx) for more details. - -#### `authenticationSecondFactor.webauthn.attestationAllowedCas` - -| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | -| - | - | - | - | - | -| `array` | `[]` | No | `auth_service.authentication.webauthn.attestation_allowed_cas` | ❌ | - -`authenticationSecondFactor.webauthn.attestationAllowedCas` is an optional allow list of certificate authorities (as local file paths or in-line PEM certificate string) for -[device verification](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/Attestation.html). -This field allows you to restrict which device models and vendors you trust. -Devices outside of the list will be rejected during registration. -By default all devices are allowed. - -#### `authenticationSecondFactor.webauthn.attestationDeniedCas` - -| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | -| - | - | - | - | - | -| `array` | `[]` | No | `auth_service.authentication.webauthn.attestation_denied_cas` | ❌ | - -`authenticationSecondFactor.webauthn.attestationDeniedCas` is optional deny list of certificate authorities (as local file paths or in-line PEM certificate string) for -[device verification](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/Attestation.html). -This field allows you to forbid specific device models and vendors, while allowing all others (provided they clear attestation_allowed_cas as well). -Devices within this list will be rejected during registration. -By default no devices are forbidden. - -## `proxyListenerMode` - -| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | -| - | - | - | - | - | -| `string` | `nil` | no | `auth_service.proxy_listener_mode` | ❌ | - -`proxyListenerMode` controls proxy TLS routing used by Teleport. Possible values are `multiplex`. - - - - ```yaml - proxyListenerMode: multiplex - ``` - - - ```code - $ --set proxyListenerMode=multiplex - ``` - - - -## `separatePostgresListener` - -| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | -| - | - | - | - | - | -| `bool` | `false` | no | `proxy_service.postgres_listen_addr` | ❌ | - -`separatePostgresListener` controls whether Teleport will multiplex PostgreSQL traffic for Teleport Database Access -over a separate TLS listener to Teleport's web UI. - -When `separatePostgresListener` is `false` (the default), PostgreSQL traffic will be directed to port 443 (the default Teleport web -UI port). This works in situations when Teleport is terminating its own TLS traffic, i.e. when using certificates from LetsEncrypt -or providing a certificate/private key pair via Teleport's `proxy_service.https_keypairs` config. - -When `separatePostgresListener` is `true`, PostgreSQL traffic will be directed to a separate Postgres-only listener on port 5432. -This also adds the port to the `Service` that the chart creates. This is useful when terminating TLS at a load balancer -in front of Teleport, such as when using AWS ACM. - -These settings will not apply if [`proxyListenerMode`](#proxylistenermode) is set to `multiplex`. - - - - ```yaml - separatePostgresListener: true - ``` - - - ```code - $ --set separatePostgresListener=true - ``` - - - -## `separateMongoListener` - -| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | -| - | - | - | - | - | -| `bool` | `false` | no | `proxy_service.mongo_listen_addr` | ❌ | - -`separateMongoListener` controls whether Teleport will multiplex PostgreSQL traffic for Teleport Database Access -over a separate TLS listener to Teleport's web UI. - -When `separateMongoListener` is `false` (the default), MongoDB traffic will be directed to port 443 (the default Teleport web -UI port). This works in situations when Teleport is terminating its own TLS traffic, i.e. when using certificates from LetsEncrypt -or providing a certificate/private key pair via Teleport's `proxy_service.https_keypairs` config. - -When `separateMongoListener` is `true`, MongoDB traffic will be directed to a separate Mongo-only listener on port 27017. -This also adds the port to the `Service` that the chart creates. This is useful when terminating TLS at a load balancer -in front of Teleport, such as when using AWS ACM. - -These settings will not apply if [`proxyListenerMode`](#proxylistenermode) is set to `multiplex`. - - - - ```yaml - separateMongoListener: true - ``` - - - ```code - $ --set separateMongoListener=true - ``` - - - -## `enterprise` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `bool` | `false`| ✅ | - -`enterprise` controls whether to use Teleport Community Edition or Teleport Enterprise. - -Setting `enterprise` to `true` will use the Teleport Enterprise image. - -You will also need to download your Enterprise license from the Teleport dashboard and add it as a Kubernetes secret to use this: - -```code -$ kubectl --namespace teleport create secret generic license --from-file=/path/to/downloaded/license.pem -``` - - - If you installed the Teleport chart into a specific namespace, the `license` secret you create must also be added to the same namespace. - - - - The file added to the secret must be called `license.pem`. If you have renamed it, you can specify the filename to use in the secret creation command: - - ```code - $ kubectl --namespace teleport create secret generic license --from-file=license.pem=/path/to/downloaded/this-is-my-teleport-license.pem - ``` - - - - - ```yaml - enterprise: true - ``` - - - ```code - $ --set enterprise=true - ``` - - - -## `teleportVersionOverride` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `string` | `nil` | ✅ | - -Normally the version of Teleport being used will match the version of the chart being installed. If you install chart version -7.0.0, you'll be using Teleport 7.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 `6.0.2` or `7`. - -See these links for information on Docker image versions: - -- [Community Docker image information](../../setup/guides/docker.mdx#step-14-pick-your-image) -- [Enterprise Docker image information](../../enterprise/getting-started.mdx#run-teleport-enterprise-using-docker) - - - - ```yaml - teleportVersionOverride: "7" - ``` - - - ```code - $ --set teleportVersionOverride="7" - ``` - - - -## `acme` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `bool` | `false` | ❌ | `proxy_service.acme.enabled` | - -ACME is a protocol for getting Web X.509 certificates. - -Setting acme to `true` enables the ACME protocol and will attempt to get a free TLS certificate from Let's Encrypt. -Setting acme to `false` (the default) will cause Teleport to generate and use self-signed certificates for its web UI. - - - ACME can only be used for single-pod clusters. It is not suitable for use in HA configurations. - - - - Using a self-signed TLS certificate and disabling TLS verification is OK for testing, but is not viable when running a production Teleport - cluster as it will drastically reduce security. You must configure valid TLS certificates on your Teleport cluster for production workloads. - - One option might be to use Teleport's built-in ACME support or enable [cert-manager support](#highavailabilitycertmanager). - - -## `acmeEmail` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `string` | `nil` | ❌ | `proxy_service.acme.email` | - -`acmeEmail` is the email address to provide during certificate registration (this is a Let's Encrypt requirement). - -## `acmeURI` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `string` | Let's Encrypt production server | ❌ | `proxy_service.acme.uri` | - -`acmeURI` is the ACME server to use for getting certificates. - -As an example, this can be overridden to use the [Let's Encrypt staging server](https://letsencrypt.org/docs/staging-environment/) for testing. - -You can also use any other ACME-compatible server. - - - - ```yaml - acme: true - acmeEmail: user@email.com - acmeURI: https://acme-staging-v02.api.letsencrypt.org/directory - ``` - - - ```code - $ --set acme=true \ - --set acmeEmail=user@email.com \ - --set acmeURI=https://acme-staging-v02.api.letsencrypt.org/directory - ``` - - - -## `podSecurityPolicy` - -### `podSecurityPolicy.enabled` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `bool` | `true` | ✅ | - -By default, Teleport charts also install a [`podSecurityPolicy`](https://github.com/gravitational/teleport/blob/master/examples/chart/teleport-cluster/templates/psp.yaml). - -To disable this, you can set `enabled` to `false`. - -[Kubernetes reference](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) - - - - ```yaml - podSecurityPolicy: - enabled: false - ``` - - - ```code - $ --set podSecurityPolicy.enabled=false - ``` - - - -## `labels` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `object` | `{}` | ❌ | `kubernetes_service.labels` | - -`labels` can be used to add a map of key-value pairs relating to the Teleport cluster being deployed. These labels can then be used with -Teleport's RBAC policies to define access rules for the cluster. - - - These are Teleport-specific RBAC labels, not Kubernetes labels. - - - - - ```yaml - labels: - environment: production - region: us-east - ``` - - - ```code - $ --set labels.environment=production \ - --set labels.region=us-east - ``` - - - -## `chartMode` - -| Type | Default value | -| - | - | -| `string` | `standalone` | - -`chartMode` is used to configure the chart's operation mode. You can find more information about each mode on its specific guide page: - -| `chartMode` | Guide | -| - | - | -| `standalone` | [Getting started with Kubernetes Access](../getting-started.mdx) | -| `aws` | [Running an HA Teleport cluster using an AWS EKS Cluster](./guides/aws.mdx) | -| `gcp` | [Running an HA Teleport cluster using a Google Cloud GKE cluster](./guides/gcp.mdx) | -| `custom` | [Running a Teleport cluster with a custom config](./guides/custom.mdx) | - -## `standalone` - -### `standalone.existingClaimName` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `string` | `nil` | ✅ | - -`standalone.existingClaimName` can be used to provide the name of a pre-existing `PersistentVolumeClaim` to use if desired. - -The default is left blank, which will automatically create a `PersistentVolumeClaim` to use for Teleport storage in `standalone` mode. - - - - ```yaml - standalone: - existingClaimName: my-existing-pvc-name - ``` - - - ```code - $ --set standalone.existingClaimName=my-existing-pvc-name - ``` - - - -### `standalone.volumeSize` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `string` | `10Gi` | ✅ | - -You can set `volumeSize` to request a different size of persistent volume when installing the Teleport chart in `standalone` mode. - - - `volumeSize` will be ignored if `existingClaimName` is set. - - - - - ```yaml - standalone: - volumeSize: 50Gi - ``` - - - ```code - --set standalone.volumeSize=50Gi - ``` - - - -## `aws` - -| Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | -| ❌ | See [Using DynamoDB](../../setup/reference/backends.mdx#dynamodb) and [Using Amazon S3](../../setup/reference/backends.mdx#s3) for details | - -`aws` settings are described in the AWS guide: [Running an HA Teleport cluster using an AWS EKS Cluster](./guides/aws.mdx) - -## `gcp` - -| Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | -| ❌ | See [Using Firestore](../../setup/reference/backends.mdx#dynamodb) and [Using GCS](../../setup/reference/backends.mdx#gcs) for details | - -`gcp` settings are described in the GCP guide: [Running an HA Teleport cluster using a Google Cloud GKE cluster](./guides/gcp.mdx) - -### `highAvailability` - -## `highAvailability.replicaCount` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `int` | `1` | ✅ (when using HA storage) | - -`highAvailability.replicaCount` can be used to set the number of replicas used in the deployment. - -Set to a number higher than `1` for a high availability mode where multiple Teleport pods will be deployed and connections will be load balanced between them. - - - Setting `highAvailability.replicaCount` to a value higher than `1` will disable the use of ACME certs. - - - - As a rough guide, we recommend configuring one replica per distinct availability zone where your cluster has worker nodes. - - 2 replicas/availability zones will be fine for smaller workloads. 3-5 replicas/availability zones will be more appropriate for bigger - clusters with more traffic. - - - - When using `custom` mode, you **must** use highly-available storage (e.g. etcd, DynamoDB or Firestore) for multiple replicas to be supported. - - [Information on supported Teleport storage backends](../../architecture/authentication.mdx#storage-back-ends) - - Manually configuring NFS-based storage or `ReadWriteMany` volume claims is **NOT** supported for an HA deployment and will result in errors. - - - - - ```yaml - highAvailability: - replicaCount: 3 - ``` - - - ```code - $ --set highAvailability.replicaCount=3 - ``` - - - -## `highAvailability.requireAntiAffinity` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `bool` | `false` | ✅ (when using HA storage) | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity) - -Setting `highAvailability.requireAntiAffinity` to `true` will use `requiredDuringSchedulingIgnoredDuringExecution` to require that multiple -Teleport pods must not be scheduled on the same physical host. - - - This can result in Teleport pods failing to be scheduled in very small clusters or during node downtime, so should be used with caution. - - - Setting `highAvailability.requireAntiAffinity` to `false` (the default) uses `preferredDuringSchedulingIgnoredDuringExecution` to make node - anti-affinity a soft requirement. - - - This setting only has any effect when `highAvailability.replicaCount` is greater than `1`. - - - - - ```yaml - highAvailability: - requireAntiAffinity: true - ``` - - - ```code - $ --set highAvailability.requireAntiAffinity=true - ``` - - - -## `highAvailability.podDisruptionBudget` - -### `highAvailability.podDisruptionBudget.enabled` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `bool` | `false` | ✅ (when using HA storage) | - -[Kubernetes reference](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) - -Enable a Pod Disruption Budget for the Teleport Pod to ensure HA during voluntary disruptions. - - - - ```yaml - highAvailability: - podDisruptionBudget: - enabled: true - ``` - - - ```shell - --set highAvailability.podDisruptionBudget.enabled=true - ``` - - - -### `highAvailability.podDisruptionBudget.minAvailable` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `int` | `1` | ✅ (when using HA storage) | - -[Kubernetes reference](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) - -Ensures that this number of replicas is available during voluntary disruptions, can be a number of replicas or a percentage. - - - - ```yaml - highAvailability: - podDisruptionBudget: - minAvailable: 1 - ``` - - - ```shell - --set highAvailability.podDisruptionBudget.minAvailable=1 - ``` - - - -## `highAvailability.certManager` - -See the [cert-manager](https://cert-manager.io/docs/) docs for more information. - -### `highAvailability.certManager.enabled` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `bool` | `false` | ❌ | `proxy_service.https_keypairs` (to provide your own certificates) | - -Setting `highAvailability.certManager.enabled` to `true` will use `cert-manager` to provision a TLS certificate for a Teleport -cluster deployed in HA mode. - - - You must install and configure `cert-manager` in your Kubernetes cluster yourself. - - See the [cert-manager Helm install instructions](https://cert-manager.io/docs/installation/kubernetes/#option-2-install-crds-as-part-of-the-helm-release) - and the relevant sections of the [AWS](./guides/aws.mdx#step-47-tls-certificates-for-teleport) and [GCP](./guides/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information. - - -### `highAvailability.certManager.addCommonName` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `bool` | `false` | ❌ | `proxy_service.https_keypairs` (to provide your own certificates) | - -Setting `highAvailability.certManager.addCommonName` to `true` will instruct `cert-manager` to set the commonName field in its certificate signing request to the issuing CA. - - - You must install and configure `cert-manager` in your Kubernetes cluster yourself. - - See the [cert-manager Helm install instructions](https://cert-manager.io/docs/installation/kubernetes/#option-2-install-crds-as-part-of-the-helm-release) - and the relevant sections of the [AWS](./guides/aws.mdx#step-47-tls-certificates-for-teleport) and [GCP](./guides/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information. - - - - - ```yaml - highAvailability: - certManager: - enabled: true - addCommonName: true - issuerName: letsencrypt-production - ``` - - - ```code - $ --set highAvailability.certManager.enabled=true \ - --set highAvailability.certManager.addCommonName=true \ - --set highAvailability.certManager.issuerName=letsencrypt-production - ``` - - - -### `highAvailability.certManager.issuerName` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `string` | `nil` | ❌ | None | - -Sets the name of the `cert-manager` `Issuer` or `ClusterIssuer` to use for issuing certificates. - - - You must install configure an appropriate `Issuer` supporting a DNS01 challenge yourself. - - Please see the [cert-manager DNS01 docs](https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers) and the relevant sections - of the [AWS](./guides/aws.mdx#step-47-tls-certificates-for-teleport) and [GCP](./guides/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information. - - - - - ```yaml - highAvailability: - certManager: - enabled: true - issuerName: letsencrypt-production - ``` - - - ```code - $ --set highAvailability.certManager.enabled=true \ - --set highAvailability.certManager.issuerName=letsencrypt-production - ``` - - - -### `highAvailability.certManager.issuerKind` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `string` | `Issuer` | ❌ | None | - -Sets the `Kind` of `Issuer` to be used when issuing certificates with `cert-manager`. Defaults to `Issuer` to keep permissions -scoped to a single namespace. - - - - ```yaml - highAvailability: - certManager: - issuerKind: ClusterIssuer - ``` - - - ```code - --set highAvailability.certManager.issuerKind=ClusterIssuer - ``` - - - -### `highAvailability.certManager.issuerGroup` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `string` | `cert-manager.io` | ❌ | None | - -Sets the `Group` of `Issuer` to be used when issuing certificates with `cert-manager`. Defaults to `cert-manager.io` to use built-in issuers. - - - - ```yaml - highAvailability: - certManager: - issuerGroup: cert-manager.io - ``` - - - ```code - --set highAvailability.certManager.issuerGroup=cert-manager.io - ``` - - - -## `image` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `string` | `quay.io/gravitational/teleport` | ✅ | - -`image` sets the container image used for Teleport Community pods in the cluster. - -You can override this to use your own Teleport Community image rather than a Teleport-published image. - - - - ```yaml - image: my.docker.registry/teleport-community-image-name - ``` - - - ```code - --set image=my.docker.registry/teleport-community-image-name - ``` - - - -## `enterpriseImage` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `string` | `quay.io/gravitational/teleport-ent` | ✅ | - -`enterpriseImage` sets the container image used for Teleport Enterprise pods in the cluster. - -You can override this to use your own Teleport Enterprise image rather than a Teleport-published image. - - - - ```yaml - enterpriseImage: my.docker.registry/teleport-enterprise-image-name - ``` - - - ```code - --set enterpriseImage=my.docker.registry/teleport-enterprise-image - ``` - - - -## `log` - -### `log.level` - - - This field used to be called `logLevel`. For backwards compatibility this name can still be used, but we recommend changing your values file to use `log.level`. - - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `string` | `INFO` | ❌ | `teleport.log.severity` | - -`log.level` sets the log level used for the Teleport process. - -Available log levels (in order of most to least verbose) are: `DEBUG`, `INFO`, `WARNING`, `ERROR`. - -The default is `INFO`, which is recommended in production. - -`DEBUG` is useful during first-time setup or to see more detailed logs for debugging. - - - - ```yaml - log: - level: DEBUG - ``` - - - ```code - --set log.level=DEBUG - ``` - - - -### `log.output` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `string` | `stderr` | ❌ | `teleport.log.output` | - -`log.output` sets the output destination for the Teleport process. - -This can be set to any of the built-in values: `stdout`, `stderr` or `syslog` to use that destination. - -The value can also be set to a file path (such as `/var/log/teleport.log`) to write logs to a file. Bear in mind that a few service startup messages will still go to `stderr` for resilience. - - - - ```yaml - log: - output: stderr - ``` - - - ```code - --set log.output=stderr - ``` - - - -### `log.format` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `string` | `text` | ❌ | `teleport.log.format.output` | - -`log.format` sets the output type for the Teleport process. - -Possible values are `text` (default) or `json`. - - - - ```yaml - log: - format: json - ``` - - - ```code - --set log.format=json - ``` - - - -### `log.extraFields` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `list` | `["timestamp", "level", "component", "caller"]` | ❌ | `teleport.log.format.extra_fields` | - -`log.extraFields` sets the fields used in logging for the Teleport process. - -See the [Teleport config file reference](../../setup/reference/config.mdx) for more details on possible values for `extra_fields`. - - - - ```yaml - log: - extraFields: ["timestamp", "level"] - ``` - - - ```code - --set "log.extraFields[0]=timestamp" \ - --set "log.extraFields[1]=level" - ``` - - - -## `affinity` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) - -Kubernetes affinity to set for pod assignments. - - - You cannot set both `affinity` and `highAvailability.requireAntiAffinity` as they conflict with each other. Only set one or the other. - - - - - ```yaml - affinity: - nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchExpressions: - - key: gravitational.io/dedicated - operator: In - values: - - teleport - ``` - - - ```code - $ --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].key=gravitational.io/dedicated \ - --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].operator=In \ - --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].values[0]=teleport - ``` - - - -## `annotations.config` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `object` | `{}` | ❌ | None | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - -Kubernetes annotations which should be applied to the `ConfigMap` created by the chart. - - - These annotations will not be applied in `custom` mode, as the `ConfigMap` is not managed by the chart. - In this instance, you should apply annotations manually to your created `ConfigMap`. - - - - - ```yaml - annotations: - config: - kubernetes.io/annotation: value - ``` - - - ```code - $ --set annotations.config."kubernetes\.io\/annotation"=value - ``` - - You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend - using a `values.yaml` file instead to avoid confusion and errors. - - - - -## `annotations.deployment` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - -Kubernetes annotations which should be applied to the `Deployment` created by the chart. - - - - ```yaml - annotations: - deployment: - kubernetes.io/annotation: value - ``` - - - ```code - $ --set annotations.deployment."kubernetes\.io\/annotation"=value - ``` - - You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend - using a `values.yaml` file instead to avoid confusion and errors. - - - - -## `annotations.pod` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - -Kubernetes annotations which should be applied to each `Pod` created by the chart. - - - - ```yaml - annotations: - pod: - kubernetes.io/annotation: value - ``` - - - ```code - $ --set annotations.pod."kubernetes\.io\/annotation"=value - ``` - - You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend - using a `values.yaml` file instead to avoid confusion and errors. - - - - -## `annotations.service` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - -Kubernetes annotations which should be applied to the `Service` created by the chart. - - - - ```yaml - annotations: - service: - kubernetes.io/annotation: value - ``` - - - ```code - $ --set annotations.service."kubernetes\.io\/annotation"=value - ``` - - You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend - using a `values.yaml` file instead to avoid confusion and errors. - - - - -## `annotations.serviceAccount` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - -Kubernetes annotations which should be applied to the `serviceAccount` created by the chart. - - - - ```yaml - annotations: - serviceAccount: - kubernetes.io/annotation: value - ``` - - - ```code - $ --set annotations.serviceAccount."kubernetes\.io\/annotation"=value - ``` - - You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend - using a `values.yaml` file instead to avoid confusion and errors. - - - - -## `annotations.certSecret` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - -Kubernetes annotations which should be applied to the `secret` generated by -`cert-manager` from the `certificate` created by the chart. Only valid when -`highAvailability.certManager.enabled` is set to `true` and requires -`cert-manager` v1.5.0+. - - - - ```yaml - annotations: - certSecret: - kubernetes.io/annotation: value - ``` - - - ```code - $ --set annotations.certSecret."kubernetes\.io\/annotation"=value - ``` - - You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend - using a `values.yaml` file instead to avoid confusion and errors. - - - - -## `service.type` - -| Type | Default value | Required? | Can be used in `custom` mode? | -| - | - | - | - | -| `string` | `LoadBalancer` | Yes | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/services-networking/service/) - -Allows to specify the service type. - - - - ```yaml - service: - type: LoadBalancer - ``` - - - ```code - $ --set service.type=LoadBalancer - ``` - - - -## `service.spec.loadBalancerIP` - -| Type | Default value | Required? | Can be used in `custom` mode? | -| - | - | - | - | -| `string` | `nil` | No | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer) - -Allows to specify the `loadBalancerIP`. - - - - ```yaml - service: - spec: - loadBalancerIP: 1.2.3.4 - ``` - - - ```code - $ --set service.spec.loadBalancerIP=1.2.3.4 - ``` - - - -## `extraArgs` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -A list of extra arguments to pass to the `teleport start` command when running a Teleport Pod. - - - - ```yaml - extraArgs: - - "--bootstrap=/etc/teleport-bootstrap/roles.yaml" - ``` - - - ```code - $ --set "extraArgs={--bootstrap=/etc/teleport-bootstrap/roles.yaml}" - ``` - - - -## `extraEnv` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/) - -A list of extra environment variables to be set on the main Teleport container. - - - - ```yaml - extraEnv: - - name: MY_ENV - value: my-value - ``` - - - ```code - $ --set "extraEnv[0].name=MY_ENV" \ - --set "extraEnv[0].value=my-value" - ``` - - - - -## `extraVolumes` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/volumes/) - -A list of extra Kubernetes `Volumes` which should be available to any `Pod` created by the chart. These volumes -will also be available to any `initContainers` configured by the chart. - - - - ```yaml - extraVolumes: - - name: myvolume - secret: - secretName: mysecret - ``` - - - ```code - $ --set "extraVolumes[0].name=myvolume" \ - --set "extraVolumes[0].secret.secretName=mysecret" - ``` - - - -## `extraVolumeMounts` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/volumes/) - -A list of extra Kubernetes volume mounts which should be mounted into any `Pod` created by the chart. These volume -mounts will also be mounted into any `initContainers` configured by the chart. - - - - ```yaml - extraVolumeMounts: - - name: myvolume - mountPath: /path/to/mount/volume - ``` - - - ```code - $ --set "extraVolumeMounts[0].name=myvolume" \ - --set "extraVolumeMounts[0].path=/path/to/mount/volume" - ``` - - - -## `imagePullPolicy` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `string` | `IfNotPresent` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/containers/images/#updating-images) - -Allows the `imagePullPolicy` for any pods created by the chart to be overridden. - - - - ```yaml - imagePullPolicy: Always - ``` - - - ```code - $ --set imagePullPolicy=Always - ``` - - - -## `initContainers` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) - -A list of `initContainers` which will be run before the main Teleport container in any pod created by the chart. - - - - ```yaml - initContainers: - - name: teleport-init - image: alpine - args: ['echo test'] - ``` - - - ```code - $ --set "initContainers[0].name=teleport-init" \ - --set "initContainers[0].image=alpine" \ - --set "initContainers[0].args={echo test}" - ``` - - - -## `postStart` - -[Kubernetes reference](https://kubernetes.io/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/) - -A `postStart` lifecycle handler to be configured on the main Teleport container. - - - - ```yaml - postStart: - command: - - echo - - foo - ``` - - - ```shell - --set "postStart.command[0]=echo" \ - --set "postStart.command[1]=foo" - ``` - - - -## `resources` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) - -Resource requests/limits which should be configured for each container inside the pod. These resource limits -will also be applied to `initContainers`. - - - - ```yaml - resources: - requests: - cpu: 1 - memory: 2Gi - ``` - - - ```code - $ --set resources.requests.cpu=1 \ - --set resources.requests.memory=2Gi - ``` - - - -## `tolerations` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) - -Kubernetes Tolerations to set for pod assignment. - - - - ```yaml - tolerations: - - key: "dedicated" - operator: "Equal" - value: "teleport" - effect: "NoSchedule" - ``` - - - ```code - $ --set tolerations[0].key=dedicated \ - --set tolerations[0].operator=Equal \ - --set tolerations[0].value=teleport \ - --set tolerations[0].effect=NoSchedule - ``` - - - -## `priorityClassName` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `string` | `""` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/) - -Kubernetes PriorityClass to set for pod. - - - - ```yaml - priorityClassName: "system-cluster-critical" - ``` - - - ```code - $ --set priorityClassName=system-cluster-critical - ``` - - - -## --- - -## `teleport-kube-agent` - -The `teleport-kube-agent` Helm chart is used to configure a Teleport agent which runs in a remote Kubernetes cluster and joins back to a -Teleport cluster to provide access to services running there. - -The `teleport-kube-agent` chart can run any or all of three Teleport services: - -| Teleport service | Name for `roles` and `tctl tokens add` | Purpose | -| - | - | - | -| [`kubernetes_service`](../../kubernetes-access/guides.mdx) | `kube` | Uses Teleport to handle authentication with and proxy access to a Kubernetes cluster | -| [`application_service`](../../application-access/guides.mdx) | `app` | Uses Teleport to handle authentication with and proxy access to web-based applications | -| [`database_service`](../../database-access/guides.mdx) | `db` | Uses Teleport to handle authentication with and proxy access to databases | - -This reference details available values for the `teleport-kube-agent` chart. - -## `roles` - -This parameter is not mandatory to preserve backwards compatibility with older chart versions, but we recommend it is set. - -| Type | Default value | -| - | - | -| `string` | `kube` | - -`roles` is a comma-separated list of services which should be enabled when running the `teleport-kube-agent` chart. - -| Services | Value for `roles` | Mandatory additional settings for this role | -| - | - | - | -| Teleport Kubernetes service | `kube` | [`kubeClusterName`](#kubeclustername) | -| Teleport Application service | `app` | [`apps`](#apps) | -| Teleport Database service | `db` | [`databases`](#databases) | - - - - ```yaml - roles: kube,app,db - ``` - - - ```code - $ --set roles=kube\,app\,db - ``` - - - When specifying multiple roles using `--set` syntax, you must escape the commas using a backslash (`\`). - - This is a quirk of Helm's CLI parser. - - - - - -If you specify a role here, you may also need to specify some other settings which are detailed in this reference. - -## `authToken` - -| Type | Default value | Required? | -| - | - | - | -| `string` | `nil` | Yes | - -`authToken` provides a Teleport join token which will be used to join the Teleport agent to a Teleport cluster. - -This value **must** be provided for the chart to work. The token that you use must also be valid for every Teleport service that you -are trying to add with the `teleport-kube-agent` chart. Here are a few examples: - -| Services | Service Name | `tctl tokens add` example | `teleport.yaml` static token example | -| - | - | - | - | -| Kubernetes | `kube` | `tctl tokens add --type=kube` | `"kube:"` | -| Kubernetes, Application | `kube,app` | `tctl tokens add --type=kube,app` | `"kube,app:"` | -| Kubernetes, Application, Database | `kube,app,db` | `tctl tokens add --type=kube,app,db` | `"kube,app,db:"` | - - - When you use a token, all of the services that it provides **must** be used. - - For example, you cannot use a token of type `app,db` to only join a Teleport `app` service by itself. It must join both `app` and `db` services at once. - - Also, each static token you configure must be unique, as the token itself is used to define which services will be supported. - - You cannot reuse the same static token and specify a different set of services. - - -If you do not have the correct services (Teleport refers to these internally as `Roles`) assigned to your join token, the Teleport agent will -fail to join the Teleport cluster. - - - - ```yaml - authToken: - ``` - - - ```code - $ --set authToken= - ``` - - - -## `proxyAddr` - -| Type | Default value | Required? | -| - | - | - | -| `string` | `nil` | Yes | - -`proxyAddr` provides the public-facing Teleport proxy endpoint which should be used to join the cluster. This is the same URL that is used -to access the web UI of your Teleport cluster. It is the same as the value configured for `proxy_service.public_addr` in a traditional -Teleport cluster. The port used is usually either 3080 or 443. - -Here are a few examples: - -| Deployment method | Example `proxy_service.public_addr` | -| - | - | -| On-prem Teleport cluster | `teleport.example.com:3080` | -| Teleport Cloud cluster | `example.teleport.sh:443` | -| `teleport-cluster` Helm chart | `teleport.example.com:443` | - -## `kubeClusterName` - -| Type | Default value | Required? | -| - | - | - | -| `string` | `nil` | When `kube` chart role is used | - -`kubeClusterName` sets the name used for the Kubernetes cluster proxied by the Teleport agent. This name will be shown to Teleport users -connecting to the cluster. - - - - ```yaml - kubeClusterName: my-gke-cluster - ``` - - - ```code - $ --set kubeClusterName=my-gke-cluster - ``` - - - -## `apps` - -| Type | Default value | Required? | -| - | - | - | -| `list` | `[]` | When `app` chart role is used? | - -`apps` is a YAML list object detailing the applications that should be proxied by Teleport Application access. - -You can specify multiple apps by adding additional list elements. - - - - ```yaml - apps: - - name: grafana - uri: http://localhost:3000 - labels: - purpose: monitoring - - name: jenkins - uri: http://jenkins:8080 - labels: - purpose: ci - ``` - - - YAML is very sensitive to correct spacing. When specifying lists in a `values.yaml` file, you might like - to [use a linter](https://codebeautify.org/yaml-validator) to validate your YAML list and ensure that it is correctly formatted. - - - - ```code - $ --set "apps[0].name=grafana" \ - --set "apps[0].uri=http://localhost:3000" \ - --set "apps[0].purpose=monitoring" \ - --set "apps[1].name=grafana" \ - --set "apps[1].uri=http://jenkins:8080" \ - --set "apps[1].purpose=ci" - ``` - - - Note that when using `--set` syntax, YAML list elements must be indexed starting at `0`. - - - - - - - You can see a list of all the supported [values which can be used in a Teleport application access configuration here](../../application-access/reference.mdx#configuration). - - -## `awsDatabases` - - - This section configures database auto-discovery, which is only currently supported on AWS. You can configure databases for other platforms using the [`databases`](#databases) section below this. - - - - For AWS database auto-discovery to work, your agent pods will need to use a role which has appropriate IAM permissions as per the [database documentation](../../database-access/guides/rds.mdx#step-47-create-an-iam-policy-for-teleport). - - After configuring a role, you can use an `eks.amazonaws.com/role-arn` annotation with the `annotations.serviceAccount` value to associate it with the service account and grant permissions: - - ``` - annotations: - serviceAccount: - eks.amazonaws.com/role-arn: arn:aws:iam::1234567890:role/my-rds-autodiscovery-role - ``` - - -| Type | Default value | Required? | -| - | - | - | -| `list` | `[]` | No | - -`awsDatabases` is a YAML list object detailing the filters for the AWS databases that should be discovered and proxied by Teleport Database access. - -You can specify multiple database filters by adding additional list elements. - -- `types` is a list containing the types of AWS databases that should be discovered. -- `regions` is a list of AWS regions which should be scanned for databases. -- `tags` can be used to set AWS tags that must be matched for databases to be discovered. - - - - ```yaml - awsDatabases: - - types: ["rds"] - regions: ["us-east-1", "us-west-2"] - tags: - "environment": "production" - - types: ["rds"] - regions: ["us-east-1"] - tags: - "environment": "dev" - - types: ["rds"] - regions: ["eu-west-1"] - tags: - "*": "*" - ``` - - - YAML is very sensitive to correct spacing. When specifying lists in a `values.yaml` file, you might like - to [use a linter](https://codebeautify.org/yaml-validator) to validate your YAML list and ensure that it is correctly formatted. - - - - ```code - --set "awsDatabases[0].types[0]=rds" \ - --set "awsDatabases[0].regions[0]=us-east-1" \ - --set "awsDatabases[0].regions[1]=us-west-2" \ - --set "awsDatabases[0].tags[0].environment=production" \ - --set "awsDatabases[1].types[0]=rds" \ - --set "awsDatabases[1].regions[0]=us-east-1" \ - --set "awsDatabases[1].tags[0].environment=dev" \ - --set "awsDatabases[2].types[0]=rds" \ - --set "awsDatabases[2].regions[0]=eu-west-1" \ - --set "awsDatabases[2].tags[0].*=*" - ``` - - - Note that when using `--set` syntax, YAML list elements must be indexed starting at `0`. - - - - - -## `databases` - -| Type | Default value | Required? | -| - | - | - | -| `list` | `[]` | When `db` chart role is used | - -`databases` is a YAML list object detailing the databases that should be proxied by Teleport Database access. - -You can specify multiple databases by adding additional list elements. - - - - ```yaml - databases: - - name: aurora-postgres - uri: postgres-aurora-instance-1.xxx.us-east-1.rds.amazonaws.com:5432 - protocol: postgres - aws: - region: us-east-1 - static_labels: - env: staging - - name: mysql - uri: mysql-instance-1.xxx.us-east-1.rds.amazonaws.com:3306 - protocol: mysql - aws: - region: us-east-1 - static_labels: - env: staging - ``` - - - YAML is very sensitive to correct spacing. When specifying lists in a `values.yaml` file, you might like - to [use a linter](https://codebeautify.org/yaml-validator) to validate your YAML list and ensure that it is correctly formatted. - - - - ```code - $ --set "databases[0].name=aurora" \ - --set "databases[0].uri=postgres-aurora-instance-1.xxx.us-east-1.rds.amazonaws.com:5432" \ - --set "databases[0].protocol=postgres" \ - --set "databases[0].aws.region=us-east-1" \ - --set "databases[0].static_labels.env=staging" \ - --set "databases[1].name=mysql" \ - --set "databases[1].uri=mysql-instance-1.xxx.us-east-1.rds.amazonaws.com:3306" \ - --set "databases[1].protocol=mysql" \ - --set "databases[1].aws.region=us-east-1" \ - --set "databases[1].static_labels.env=staging" - ``` - - - Note that when using `--set` syntax, YAML list elements must be indexed starting at `0`. - - - - - - - You can see a list of all the supported [values which can be used in a Teleport database service configuration here](../../database-access/reference/configuration.mdx). - - -## `teleportVersionOverride` - -| Type | Default value | -| - | - | -| `string` | `nil` | - -Normally the version of Teleport being used will match the version of the chart being installed. If you install chart version -7.0.0, you'll be using Teleport 7.0.0. - -You can optionally override this to use a different published Teleport Docker image tag like `6.0.2` or `7`. - -See [this link for information on Community Docker image versions](../../setup/guides/docker.mdx#step-14-pick-your-image). - - - 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. - - - - - ```yaml - teleportVersionOverride: "7" - ``` - - - ```code - $ --set teleportVersionOverride="7" - ``` - - - -## `insecureSkipProxyTLSVerify` - -| Type | Default value | -| - | - | -| `bool` | `false` | - -When `insecureSkipProxyTLSVerify` is set to `true`, the agent will skip the verification of the TLS certificate presented by the Teleport -proxy server specified using [`proxyAddr`](#proxyaddr). - -This can be used for joining a Teleport agent to a Teleport cluster which does not have valid TLS certificates for testing. - - - - ```yaml - insecureSkipProxyTLSVerify: false - ``` - - - ```code - $ --set insecureSkipProxyTLSVerify=false - ``` - - - - - Using a self-signed TLS certificate and disabling TLS verification is OK for testing, but is not viable when running a production Teleport - cluster as it will drastically reduce security. You must configure valid TLS certificates on your Teleport cluster for production workloads. - - One option might be to use Teleport's built-in [ACME support](#acme) enable [cert-manager support](#highavailabilitycertmanager). - - -## `existingDataVolume` - -| Type | Default value | -| - | - | -| `string` | `""` | - -When `existingDataVolume` is set to the name of an existing volume, the `/var/lib/teleport` mount will use this volume instead of creating a new `emptyDir` volume. - - - - ```yaml - existingDataVolume: my-volume - ``` - - - ```bash - --set existingDataVolume=my-volume - ``` - - - -## `podSecurityPolicy` - -### `podSecurityPolicy.enabled` - -| Type | Default value | -| - | - | -| `bool` | `true` | - -By default, Teleport charts also install a [`podSecurityPolicy`](https://github.com/gravitational/teleport/blob/master/examples/chart/teleport-kube-agent/templates/psp.yaml). - -To disable this, you can set `enabled` to `false`. - -[Kubernetes reference](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) - - - - ```yaml - podSecurityPolicy: - enabled: false - ``` - - - ```code - $ --set podSecurityPolicy.enabled=false - ``` - - - -## `labels` - -| Type | Default value | -| - | - | -| `object` | `{}` | - -`labels` can be used to add a map of key-value pairs for the `kubernetes_service` which is deployed using the `teleport-kube-agent` chart. -These labels can then be used with Teleport's RBAC policies to define access rules for the cluster. - - - These are Teleport-specific RBAC labels, not Kubernetes labels. - - - - For historical/backwards compatibility reasons, these labels will only be applied to the Kubernetes cluster being joined via the - Teleport Kubernetes service. - - To set labels for applications, add a `labels` element to the [`apps`](#apps) section. - To set labels for databases, add a `static_labels` element to the [`databases`](#databases) section. - - For more information on how to set static/dynamic labels for Teleport services, see [labelling nodes and applications](../../setup/admin/labels.mdx). - - - - - ```yaml - labels: - environment: production - region: us-east - ``` - - - ```code - $ --set labels.environment=production \ - --set labels.region=us-east - ``` - - - -## `storage` - -### `storage.enabled` - -| Type | Default value | -| - | - | -| `bool` | `false` | - -Enables the creation of a Kubernetes persistent volume to hold Teleport agent state. - -[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) - - - - ```yaml - storage: - enabled: true - ``` - - - ```bash - --set storage.enabled=true - ``` - - - -### `storage.storageClassName` - -| Type | Default value | -| - | - | -| `string` | `nil` | - -The storage class name the persistent volume should use when creating persistent volume claims. The provided storage class -name needs to exist on the Kubernetes cluster for Teleport to use. - -[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/storage-classes/) - - - - ```yaml - storage: - storageClassName: teleport-storage-class - ``` - - - ```bash - --set storage.storageClassName=teleport-storage-class - ``` - - - -### `storage.requests` - -| Type | Default value | -| - | - | -| `string` | `128Mi` | - -The size of persistent volume to create. - - - - ```yaml - storage: - requests: 128Mi - ``` - - - ```bash - --set storage.requests=128Mi - ``` - - - -## `image` - -| Type | Default value | -| - | - | -| `string` | `quay.io/gravitational/teleport` | - -`image` sets the container image used for Teleport pods run by the `teleport-kube-agent` chart. - -You can override this to use your own Teleport image rather than a Teleport-published image. - - - - ```yaml - image: my.docker.registry/teleport-image-name - ``` - - - ```code - $ --set image=my.docker.registry/teleport-image-name - ``` - - - -## `imagePullSecrets` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) - -A list of secrets containing authorization tokens which can be optionally used to access a private Docker registry. - - - - ```yaml - imagePullSecrets: - - name: my-docker-registry-key - ``` - - - ```shell - --set "imagePullSecrets[0].name=my-docker-registry-key" - ``` - - - -### `highAvailability` - -## `highAvailability.replicaCount` - -| Type | Default value | -| - | - | -| `int` | `1` | - -`highAvailability.replicaCount` can be used to set the number of replicas used in the deployment. - -Set to a number higher than `1` for a high availability mode where multiple Teleport agent pods will be deployed. - - - As a rough guide, we recommend configuring one replica per distinct availability zone where your cluster has worker nodes. - - 2 replicas/availability zones will be fine for smaller workloads. 3-5 replicas/availability zones will be more appropriate for bigger - clusters with more traffic. - - - - - ```yaml - highAvailability: - replicaCount: 3 - ``` - - - ```shell - --set highAvailability.replicaCount=3 - ``` - - - -## `highAvailability.requireAntiAffinity` - -| Type | Default value | -| - | - | -| `bool` | `false` | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity) - -Setting `highAvailability.requireAntiAffinity` to `true` will use `requiredDuringSchedulingIgnoredDuringExecution` to require that multiple -Teleport pods must not be scheduled on the same physical host. - - - This can result in Teleport pods failing to be scheduled in very small clusters or during node downtime, so should be used with caution. - - - Setting `highAvailability.requireAntiAffinity` to `false` (the default) uses `preferredDuringSchedulingIgnoredDuringExecution` to make node - anti-affinity a soft requirement. - - - This setting only has any effect when `highAvailability.replicaCount` is greater than `1`. - - - - - ```yaml - highAvailability: - requireAntiAffinity: true - ``` - - - ```shell - --set highAvailability.requireAntiAffinity=true - ``` - - - -## `highAvailability.podDisruptionBudget` - -### `highAvailability.podDisruptionBudget.enabled` - -| Type | Default value | -| - | - | -| `bool` | `false` | - -[Kubernetes reference](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) - -Enable a Pod Disruption Budget for the Teleport Pod to ensure HA during voluntary disruptions. - - - - ```yaml - highAvailability: - podDisruptionBudget: - enabled: true - ``` - - - ```shell - --set highAvailability.podDisruptionBudget.enabled=true - ``` - - - -### `highAvailability.podDisruptionBudget.minAvailable` - -| Type | Default value | -| - | - | -| `int` | `1` | - -[Kubernetes reference](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) - -Ensures that this number of replicas is available during voluntary disruptions, can be a number of replicas or a percentage. - - - - ```yaml - highAvailability: - podDisruptionBudget: - minAvailable: 1 - ``` - - - ```shell - --set highAvailability.podDisruptionBudget.minAvailable=1 - ``` - - - -## `clusterRoleName` - -| Type | Default value | -| - | - | -| `string` | `nil` | - -`clusterRoleName` can be optionally used to override the name of the Kubernetes `ClusterRole` used by the `teleport-kube-agent` chart's `ServiceAccount`. - - - Most users will not need to change this. - - - - - ```yaml - clusterRoleName: kubernetes-clusterrole - ``` - - - ```code - $ --set clusterRoleName=kubernetes-clusterrole - ``` - - - -## `clusterRoleBindingName` - - - Most users will not need to change this. - - -| Type | Default value | -| - | - | -| `string` | `nil` | - - -`clusterRoleBindingName` can be optionally used to override the name of the Kubernetes `ClusterRoleBinding` used by the `teleport-kube-agent` chart's `ServiceAccount`. - - - - ```yaml - clusterRoleBindingName: kubernetes-clusterrolebinding - ``` - - - ```code - $ --set clusterRoleBindingName=kubernetes-clusterrolebinding - ``` - - - -## `serviceAccountName` - - - Most users will not need to change this. - - -| Type | Default value | -| - | - | -| `string` | `nil` | - -`serviceAccountName` can be optionally used to override the name of the Kubernetes `ServiceAccount` used by the `teleport-kube-agent` chart. - - - - ```yaml - serviceAccountName: kubernetes-serviceaccount - ``` - - - ```code - $ --set serviceAccountName=kubernetes-serviceaccount - ``` - - - -## `secretName` - -| Type | Default value | -| - | - | -| `string` | `teleport-kube-agent-join-token` | - -`secretName` is the name of the Kubernetes `Secret` used to store the Teleport join token which is used by the `teleport-kube-agent` chart. - -If you set this to a blank value, the chart will not attempt to create the secret itself and will instead read the value of the -existing `teleport-kube-agent-join-token` secret. This allows you to configure this secret externally and avoid having a plaintext -join token stored in your Teleport chart values. - -To create your own join token secret, you can use a command like this: - -```code -$ kubectl --namespace teleport create secret generic teleport-kube-agent-join-token --from-literal=auth-token= -``` - - - The key used for the auth token inside the secret must be `auth-token`, as in the command above. - - - - - ```yaml - serviceAccountName: - ``` - - - ```code - $ --set serviceAccountName="" - ``` - - - -## `log` - -### `log.level` - - - This field used to be called `logLevel`. For backwards compatibility this name can still be used, but we recommend changing your values file to use `log.level`. - - -| Type | Default value | -| - | - | -| `string` | `INFO` | - -`log.level` sets the log level used for the Teleport process. - -Available log levels (in order of most to least verbose) are: `DEBUG`, `INFO`, `WARNING`, `ERROR`. - -The default is `INFO`, which is recommended in production. - -`DEBUG` is useful during first-time setup or to see more detailed logs for debugging. - - - - ```yaml - log: - level: DEBUG - ``` - - - ```code - --set log.level=DEBUG - ``` - - - -### `log.output` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `string` | `stderr` | ❌ | `teleport.log.output` | - -`log.output` sets the output destination for the Teleport process. - -This can be set to any of the built-in values: `stdout`, `stderr` or `syslog` to use that destination. - -The value can also be set to a file path (such as `/var/log/teleport.log`) to write logs to a file. Bear in mind that a few service startup messages will still go to `stderr` for resilience. - - - - ```yaml - log: - output: stderr - ``` - - - ```code - --set log.output=stderr - ``` - - - -### `log.format` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `string` | `text` | ❌ | `teleport.log.format.output` | - -`log.format` sets the output type for the Teleport process. - -Possible values are `text` (default) or `json`. - - - - ```yaml - log: - format: json - ``` - - - ```code - --set log.format=json - ``` - - - -### `log.extraFields` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `list` | `["timestamp", "level", "component", "caller"]` | ❌ | `teleport.log.format.extra_fields` | - -`log.extraFields` sets the fields used in logging for the Teleport process. - -See the [Teleport config file reference](../../setup/reference/config.mdx) for more details on possible values for `extra_fields`. - - - - ```yaml - log: - extraFields: ["timestamp", "level"] - ``` - - - ```code - --set "log.extraFields[0]=timestamp" \ - --set "log.extraFields[1]=level" - ``` - - - -## `affinity` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) - -Kubernetes affinity to set for pod assignments. - - - You cannot set both `affinity` and `highAvailability.requireAntiAffinity` as they conflict with each other. - - - - - ```yaml - affinity: - nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchExpressions: - - key: gravitational.io/dedicated - operator: In - values: - - teleport - ``` - - - ```code - $ --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].key=gravitational.io/dedicated \ - --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].operator=In \ - --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].values[0]=teleport - ``` - - - -## `nodeSelector` - -| Type | Default value | -| - | - | -| `object` | `{}` | - -`nodeSelector` can be used to add a map of key-value pairs to constrain the nodes the agent pods will run on. - -[Kubernetes reference](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/) - - - - ```yaml - nodeSelector: - role: node - region: us-east - ``` - - - ```bash - --set nodeSelector.role=node \ - --set nodeSelector.region=us-east - ``` - - - -## `annotations.config` - -| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | -| - | - | - | - | -| `object` | `{}` | ❌ | None | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - -Kubernetes annotations which should be applied to the `ConfigMap` created by the chart. - - - These annotations will not be applied in `custom` mode, as the `ConfigMap` is not managed by the chart. - In this instance, you should apply annotations manually to your created `ConfigMap`. - - - - - ```yaml - annotations: - config: - kubernetes.io/annotation: value - ``` - - - ```code - $ --set annotations.config."kubernetes\.io\/annotation"=value - ``` - - You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend - using a `values.yaml` file instead to avoid confusion and errors. - - - - -## `annotations.deployment` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - -Kubernetes annotations which should be applied to the `Deployment` created by the chart. - - - - ```yaml - annotations: - deployment: - kubernetes.io/annotation: value - ``` - - - ```code - $ --set annotations.deployment."kubernetes\.io\/annotation"=value - ``` - - You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend - using a `values.yaml` file instead to avoid confusion and errors. - - - - -## `annotations.pod` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - -Kubernetes annotations which should be applied to each `Pod` created by the chart. - - - - ```yaml - annotations: - pod: - kubernetes.io/annotation: value - ``` - - - ```code - $ --set annotations.pod."kubernetes\.io\/annotation"=value - ``` - - You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend - using a `values.yaml` file instead to avoid confusion and errors. - - - - -## `annotations.serviceAccount` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) - -Kubernetes annotations which should be applied to the `ServiceAccount` created by the chart. - - - - ```yaml - annotations: - serviceAccount: - kubernetes.io/annotation: value - ``` - - - ```code - $ --set annotations.serviceAccount."kubernetes\.io\/annotation"=value - ``` - - You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend - using a `values.yaml` file instead to avoid confusion and errors. - - - - -## `extraVolumes` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/volumes/) - -A list of extra Kubernetes `Volumes` which should be available to any `Pod` created by the chart. These volumes -will also be available to any `initContainers` configured by the chart. - - - - ```yaml - extraVolumes: - - name: myvolume - secret: - secretName: mysecret - ``` - - - ```code - $ --set "extraVolumes[0].name=myvolume" \ - --set "extraVolumes[0].secret.secretName=mysecret" - ``` - - - -## `extraArgs` - -| Type | Default value | -| - | - | -| `list` | `[]` | - -A list of extra arguments to pass to the `teleport start` command when running a Teleport Pod. - - - - ```yaml - extraArgs: - - "--debug" - ``` - - - ```code - $ --set "extraArgs={--debug}" - ``` - - - -## `extraEnv` - -| Type | Default value | -| - | - | -| `list` | `[]` | - -[Kubernetes reference](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/) - -A list of extra environment variables to be set on the main Teleport container. - - - - ```yaml - extraEnv: - - name: HTTPS_PROXY - value: "http://username:password@my.proxy.host:3128" - ``` - - - ```code - $ --set "extraEnv[0].name=HTTPS_PROXY" \ - --set "extraEnv[0].value=\"http://username:password@my.proxy.host:3128\"" - ``` - - - -## `extraVolumeMounts` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/volumes/) - -A list of extra Kubernetes volume mounts which should be mounted into any `Pod` created by the chart. These volume -mounts will also be mounted into any `initContainers` configured by the chart. - - - - ```yaml - extraVolumeMounts: - - name: myvolume - mountPath: /path/to/mount/volume - ``` - - - ```code - $ --set "extraVolumeMounts[0].name=myvolume" \ - --set "extraVolumeMounts[0].path=/path/to/mount/volume" - ``` - - - -## `imagePullPolicy` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `string` | `IfNotPresent` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/containers/images/#updating-images) - -Allows the `imagePullPolicy` for any pods created by the chart to be overridden. - - - - ```yaml - imagePullPolicy: Always - ``` - - - ```code - $ --set imagePullPolicy=Always - ``` - - - -## `initContainers` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) - -A list of `initContainers` which will be run before the main Teleport container in any pod created by the chart. - - - - ```yaml - initContainers: - - name: teleport-init - image: alpine - args: ['echo test'] - ``` - - - ```code - $ --set "initContainers[0].name=teleport-init" \ - --set "initContainers[0].image=alpine" \ - --set "initContainers[0].args={echo test}" - ``` - - - -## `resources` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `object` | `{}` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) - -Resource requests/limits which should be configured for each container inside the pod. These resource limits -will also be applied to `initContainers`. - - - - ```yaml - resources: - requests: - cpu: 1 - memory: 2Gi - ``` - - - ```code - $ --set resources.requests.cpu=1 \ - --set resources.requests.memory=2Gi - ``` - - - -## `tolerations` - -| Type | Default value | Can be used in `custom` mode? | -| - | - | - | -| `list` | `[]` | ✅ | - -[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) - -Kubernetes Tolerations to set for pod assignment. - - - - ```yaml - tolerations: - - key: "dedicated" - operator: "Equal" - value: "teleport" - effect: "NoSchedule" - ``` - - - ```code - $ --set tolerations[0].key=dedicated \ - --set tolerations[0].operator=Equal \ - --set tolerations[0].value=teleport \ - --set tolerations[0].effect=NoSchedule - ``` - - + + diff --git a/docs/pages/kubernetes-access/helm/reference/teleport-cluster.mdx b/docs/pages/kubernetes-access/helm/reference/teleport-cluster.mdx new file mode 100644 index 0000000000000..a41bf4fe7f50c --- /dev/null +++ b/docs/pages/kubernetes-access/helm/reference/teleport-cluster.mdx @@ -0,0 +1,1425 @@ +--- +title: teleport-cluster Chart Reference +description: Values that can be set using the teleport-cluster Helm chart +--- + +The `teleport-cluster` Helm chart is used to deploy the Teleport Auth Service +and Proxy Service, which is ideal for getting started with a self-hosted Teleport +cluster on Kubernetes. + + + +Teleport Cloud manages the Auth Service and Proxy Service for you. Use the +`teleport-cluster` chart if you are interested in hosting Teleport yourself, or +use the [`teleport-kube-agent`](./teleport-kube-agent.mdx) chart to deploy the +Kubernetes Service, Application Service, or Database Service. + + + +You can +[browse the source on GitHub](https://github.com/gravitational/teleport/tree/master/examples/chart/teleport-cluster). + +The `teleport-cluster` chart runs two Teleport services: + +| Teleport service | Purpose | Documentation | +| - | - | - | +| `auth_service` | Authenticates users and hosts, and issues certificates | [Auth documentation](../../../architecture/authentication.mdx) +| `proxy_service`| Runs the externally-facing parts of a Teleport cluster, such as the web UI, SSH proxy and reverse tunnel service | [Proxy documentation](../../../architecture/proxy.mdx) | + +The `teleport-cluster` chart can be deployed in four different modes. Get started with a guide for each mode: + +| `chartMode` | Guide | +| - | - | +| `standalone` | [Getting started with Kubernetes Access](../../../getting-started.mdx) | +| `aws` | [Running an HA Teleport cluster using an AWS EKS Cluster](../guides/aws.mdx) | +| `gcp` | [Running an HA Teleport cluster using a Google Cloud GKE cluster](../guides/gcp.mdx) | +| `custom` | [Running a Teleport cluster with a custom config](../guides/custom.mdx) | + +This reference details available values for the `teleport-cluster` chart. + +(!docs/pages/includes/backup-warning.mdx!) + +## `clusterName` + +| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | +| - | - | - | - | - | +| `string` | `nil` | When `chartMode` is `aws`, `gcp` or `standalone` | `auth_service.cluster_name`, `proxy_service.public_addr` | ✅ | + +`clusterName` controls the name used to refer to the Teleport cluster, along with the externally-facing public address to use to access it. + + + If using a fully qualified domain name as your `clusterName`, you will also need to configure the DNS provider for this domain to point + to the external load balancer address of your Teleport cluster. + + (!docs/pages/kubernetes-access/helm/includes/kubernetes-externaladdress.mdx!) + + You will need to manually add a DNS A record pointing `teleport.example.com` to either the IP or hostname of the Kubernetes load balancer. + +
+(!docs/pages/includes/dns-app-access.mdx!) +
+ + If you are not using ACME certificates, you may also need to accept insecure warnings in your browser to view the page successfully. + + + +## `kubeClusterName` + +| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | +| - | - | - | - | - | +| `string` | `clusterName` value | no | `kubernetes_service.kube_cluster_name` | ✅ | + +`kubeClusterName` sets the name used for the Kubernetes cluster. This name will be shown to Teleport users connecting to the cluster. + +## `authenticationType` + +| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | +| - | - | - | - | - | +| `string` | `local` | Yes | `auth_service.authentication.type` | ❌ | + +`authenticationType` controls the authentication scheme used by Teleport. Possible values are `local` and `github` for OSS, plus `oidc`, `saml`, and `false` for Enterprise. + +## `authenticationSecondFactor` + +### `authenticationSecondFactor.secondFactor` + +| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | +| - | - | - | - | - | +| `string` | `otp` | Yes | `auth_service.authentication.second_factor` | ❌ | + +`authenticationSecondFactor.secondFactor` controls the second factor used for local user authentication. Possible values supported by this chart +are `off` (not recommended), `on`, `otp`, `optional` and `webauthn`. + +When set to `on`, `optional` or `webauthn`, the `authenticationSecondFactor.webauthn` section can also be used. The configured `rp_id` defaults to +the FQDN which is used to access the Teleport cluster. + +### `authenticationSecondFactor.webauthn` + +See [Second Factor - WebAuthn](../../../access-controls/guides/webauthn.mdx) for more details. + +#### `authenticationSecondFactor.webauthn.attestationAllowedCas` + +| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | +| - | - | - | - | - | +| `array` | `[]` | No | `auth_service.authentication.webauthn.attestation_allowed_cas` | ❌ | + +`authenticationSecondFactor.webauthn.attestationAllowedCas` is an optional allow list of certificate authorities (as local file paths or in-line PEM certificate string) for +[device verification](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/Attestation.html). +This field allows you to restrict which device models and vendors you trust. +Devices outside of the list will be rejected during registration. +By default all devices are allowed. + +#### `authenticationSecondFactor.webauthn.attestationDeniedCas` + +| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | +| - | - | - | - | - | +| `array` | `[]` | No | `auth_service.authentication.webauthn.attestation_denied_cas` | ❌ | + +`authenticationSecondFactor.webauthn.attestationDeniedCas` is optional deny list of certificate authorities (as local file paths or in-line PEM certificate string) for +[device verification](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/Attestation.html). +This field allows you to forbid specific device models and vendors, while allowing all others (provided they clear attestation_allowed_cas as well). +Devices within this list will be rejected during registration. +By default no devices are forbidden. + +## `proxyListenerMode` + +| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | +| - | - | - | - | - | +| `string` | `nil` | no | `auth_service.proxy_listener_mode` | ❌ | + +`proxyListenerMode` controls proxy TLS routing used by Teleport. Possible values are `multiplex`. + + + + ```yaml + proxyListenerMode: multiplex + ``` + + + ```code + $ --set proxyListenerMode=multiplex + ``` + + + +## `separatePostgresListener` + +| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | +| - | - | - | - | - | +| `bool` | `false` | no | `proxy_service.postgres_listen_addr` | ❌ | + +`separatePostgresListener` controls whether Teleport will multiplex PostgreSQL traffic for Teleport Database Access +over a separate TLS listener to Teleport's web UI. + +When `separatePostgresListener` is `false` (the default), PostgreSQL traffic will be directed to port 443 (the default Teleport web +UI port). This works in situations when Teleport is terminating its own TLS traffic, i.e. when using certificates from LetsEncrypt +or providing a certificate/private key pair via Teleport's `proxy_service.https_keypairs` config. + +When `separatePostgresListener` is `true`, PostgreSQL traffic will be directed to a separate Postgres-only listener on port 5432. +This also adds the port to the `Service` that the chart creates. This is useful when terminating TLS at a load balancer +in front of Teleport, such as when using AWS ACM. + +These settings will not apply if [`proxyListenerMode`](#proxylistenermode) is set to `multiplex`. + + + + ```yaml + separatePostgresListener: true + ``` + + + ```code + $ --set separatePostgresListener=true + ``` + + + +## `separateMongoListener` + +| Type | Default value | Required? | `teleport.yaml` equivalent | Can be used in `custom` mode? | +| - | - | - | - | - | +| `bool` | `false` | no | `proxy_service.mongo_listen_addr` | ❌ | + +`separateMongoListener` controls whether Teleport will multiplex PostgreSQL traffic for Teleport Database Access +over a separate TLS listener to Teleport's web UI. + +When `separateMongoListener` is `false` (the default), MongoDB traffic will be directed to port 443 (the default Teleport web +UI port). This works in situations when Teleport is terminating its own TLS traffic, i.e. when using certificates from LetsEncrypt +or providing a certificate/private key pair via Teleport's `proxy_service.https_keypairs` config. + +When `separateMongoListener` is `true`, MongoDB traffic will be directed to a separate Mongo-only listener on port 27017. +This also adds the port to the `Service` that the chart creates. This is useful when terminating TLS at a load balancer +in front of Teleport, such as when using AWS ACM. + +These settings will not apply if [`proxyListenerMode`](#proxylistenermode) is set to `multiplex`. + + + + ```yaml + separateMongoListener: true + ``` + + + ```code + $ --set separateMongoListener=true + ``` + + + +## `enterprise` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `bool` | `false`| ✅ | + +`enterprise` controls whether to use Teleport Community Edition or Teleport Enterprise. + +Setting `enterprise` to `true` will use the Teleport Enterprise image. + +You will also need to download your Enterprise license from the Teleport dashboard and add it as a Kubernetes secret to use this: + +```code +$ kubectl --namespace teleport create secret generic license --from-file=/path/to/downloaded/license.pem +``` + + + If you installed the Teleport chart into a specific namespace, the `license` secret you create must also be added to the same namespace. + + + + The file added to the secret must be called `license.pem`. If you have renamed it, you can specify the filename to use in the secret creation command: + + ```code + $ kubectl --namespace teleport create secret generic license --from-file=license.pem=/path/to/downloaded/this-is-my-teleport-license.pem + ``` + + + + + ```yaml + enterprise: true + ``` + + + ```code + $ --set enterprise=true + ``` + + + +## `teleportVersionOverride` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `string` | `nil` | ✅ | + +Normally the version of Teleport being used will match the version of the chart being installed. If you install chart version +7.0.0, you'll be using Teleport 7.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 `6.0.2` or `7`. + +See these links for information on Docker image versions: + +- [Community Docker image information](../../../setup/guides/docker.mdx#step-14-pick-your-image) +- [Enterprise Docker image information](../../../enterprise/getting-started.mdx#run-teleport-enterprise-using-docker) + + + + ```yaml + teleportVersionOverride: "7" + ``` + + + ```code + $ --set teleportVersionOverride="7" + ``` + + + +## `acme` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `bool` | `false` | ❌ | `proxy_service.acme.enabled` | + +ACME is a protocol for getting Web X.509 certificates. + +Setting acme to `true` enables the ACME protocol and will attempt to get a free TLS certificate from Let's Encrypt. +Setting acme to `false` (the default) will cause Teleport to generate and use self-signed certificates for its web UI. + + + ACME can only be used for single-pod clusters. It is not suitable for use in HA configurations. + + + + Using a self-signed TLS certificate and disabling TLS verification is OK for testing, but is not viable when running a production Teleport + cluster as it will drastically reduce security. You must configure valid TLS certificates on your Teleport cluster for production workloads. + + One option might be to use Teleport's built-in ACME support or enable [cert-manager support](#highavailabilitycertmanager). + + +## `acmeEmail` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `string` | `nil` | ❌ | `proxy_service.acme.email` | + +`acmeEmail` is the email address to provide during certificate registration (this is a Let's Encrypt requirement). + +## `acmeURI` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `string` | Let's Encrypt production server | ❌ | `proxy_service.acme.uri` | + +`acmeURI` is the ACME server to use for getting certificates. + +As an example, this can be overridden to use the [Let's Encrypt staging server](https://letsencrypt.org/docs/staging-environment/) for testing. + +You can also use any other ACME-compatible server. + + + + ```yaml + acme: true + acmeEmail: user@email.com + acmeURI: https://acme-staging-v02.api.letsencrypt.org/directory + ``` + + + ```code + $ --set acme=true \ + --set acmeEmail=user@email.com \ + --set acmeURI=https://acme-staging-v02.api.letsencrypt.org/directory + ``` + + + +## `podSecurityPolicy` + +### `podSecurityPolicy.enabled` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `bool` | `true` | ✅ | + +By default, Teleport charts also install a [`podSecurityPolicy`](https://github.com/gravitational/teleport/blob/master/examples/chart/teleport-cluster/templates/psp.yaml). + +To disable this, you can set `enabled` to `false`. + +[Kubernetes reference](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) + + + + ```yaml + podSecurityPolicy: + enabled: false + ``` + + + ```code + $ --set podSecurityPolicy.enabled=false + ``` + + + +## `labels` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `object` | `{}` | ❌ | `kubernetes_service.labels` | + +`labels` can be used to add a map of key-value pairs relating to the Teleport cluster being deployed. These labels can then be used with +Teleport's RBAC policies to define access rules for the cluster. + + + These are Teleport-specific RBAC labels, not Kubernetes labels. + + + + + ```yaml + labels: + environment: production + region: us-east + ``` + + + ```code + $ --set labels.environment=production \ + --set labels.region=us-east + ``` + + + +## `chartMode` + +| Type | Default value | +| - | - | +| `string` | `standalone` | + +`chartMode` is used to configure the chart's operation mode. You can find more information about each mode on its specific guide page: + +| `chartMode` | Guide | +| - | - | +| `standalone` | [Getting started with Kubernetes Access](../../../getting-started.mdx) | +| `aws` | [Running an HA Teleport cluster using an AWS EKS Cluster](../guides/aws.mdx) | +| `gcp` | [Running an HA Teleport cluster using a Google Cloud GKE cluster](../guides/gcp.mdx) | +| `custom` | [Running a Teleport cluster with a custom config](../guides/custom.mdx) | + +## `standalone` + +### `standalone.existingClaimName` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `string` | `nil` | ✅ | + +`standalone.existingClaimName` can be used to provide the name of a pre-existing `PersistentVolumeClaim` to use if desired. + +The default is left blank, which will automatically create a `PersistentVolumeClaim` to use for Teleport storage in `standalone` mode. + + + + ```yaml + standalone: + existingClaimName: my-existing-pvc-name + ``` + + + ```code + $ --set standalone.existingClaimName=my-existing-pvc-name + ``` + + + +### `standalone.volumeSize` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `string` | `10Gi` | ✅ | + +You can set `volumeSize` to request a different size of persistent volume when installing the Teleport chart in `standalone` mode. + + + `volumeSize` will be ignored if `existingClaimName` is set. + + + + + ```yaml + standalone: + volumeSize: 50Gi + ``` + + + ```code + --set standalone.volumeSize=50Gi + ``` + + + +## `aws` + +| Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | +| ❌ | See [Using DynamoDB](../../../setup/reference/backends.mdx#dynamodb) and [Using Amazon S3](../../../setup/reference/backends.mdx#s3) for details | + +`aws` settings are described in the AWS guide: [Running an HA Teleport cluster using an AWS EKS Cluster](../guides/aws.mdx) + +## `gcp` + +| Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | +| ❌ | See [Using Firestore](../../../setup/reference/backends.mdx#dynamodb) and [Using GCS](../../../setup/reference/backends.mdx#gcs) for details | + +`gcp` settings are described in the GCP guide: [Running an HA Teleport cluster using a Google Cloud GKE cluster](../guides/gcp.mdx) + +### `highAvailability` + +## `highAvailability.replicaCount` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `int` | `1` | ✅ (when using HA storage) | + +`highAvailability.replicaCount` can be used to set the number of replicas used in the deployment. + +Set to a number higher than `1` for a high availability mode where multiple Teleport pods will be deployed and connections will be load balanced between them. + + + Setting `highAvailability.replicaCount` to a value higher than `1` will disable the use of ACME certs. + + + + As a rough guide, we recommend configuring one replica per distinct availability zone where your cluster has worker nodes. + + 2 replicas/availability zones will be fine for smaller workloads. 3-5 replicas/availability zones will be more appropriate for bigger + clusters with more traffic. + + + + When using `custom` mode, you **must** use highly-available storage (e.g. etcd, DynamoDB or Firestore) for multiple replicas to be supported. + + [Information on supported Teleport storage backends](../../../architecture/authentication.mdx#storage-back-ends) + + Manually configuring NFS-based storage or `ReadWriteMany` volume claims is **NOT** supported for an HA deployment and will result in errors. + + + + + ```yaml + highAvailability: + replicaCount: 3 + ``` + + + ```code + $ --set highAvailability.replicaCount=3 + ``` + + + +## `highAvailability.requireAntiAffinity` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `bool` | `false` | ✅ (when using HA storage) | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity) + +Setting `highAvailability.requireAntiAffinity` to `true` will use `requiredDuringSchedulingIgnoredDuringExecution` to require that multiple +Teleport pods must not be scheduled on the same physical host. + + + This can result in Teleport pods failing to be scheduled in very small clusters or during node downtime, so should be used with caution. + + + Setting `highAvailability.requireAntiAffinity` to `false` (the default) uses `preferredDuringSchedulingIgnoredDuringExecution` to make node + anti-affinity a soft requirement. + + + This setting only has any effect when `highAvailability.replicaCount` is greater than `1`. + + + + + ```yaml + highAvailability: + requireAntiAffinity: true + ``` + + + ```code + $ --set highAvailability.requireAntiAffinity=true + ``` + + + +## `highAvailability.podDisruptionBudget` + +### `highAvailability.podDisruptionBudget.enabled` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `bool` | `false` | ✅ (when using HA storage) | + +[Kubernetes reference](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) + +Enable a Pod Disruption Budget for the Teleport Pod to ensure HA during voluntary disruptions. + + + + ```yaml + highAvailability: + podDisruptionBudget: + enabled: true + ``` + + + ```shell + --set highAvailability.podDisruptionBudget.enabled=true + ``` + + + +### `highAvailability.podDisruptionBudget.minAvailable` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `int` | `1` | ✅ (when using HA storage) | + +[Kubernetes reference](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) + +Ensures that this number of replicas is available during voluntary disruptions, can be a number of replicas or a percentage. + + + + ```yaml + highAvailability: + podDisruptionBudget: + minAvailable: 1 + ``` + + + ```shell + --set highAvailability.podDisruptionBudget.minAvailable=1 + ``` + + + +## `highAvailability.certManager` + +See the [cert-manager](https://cert-manager.io/docs/) docs for more information. + +### `highAvailability.certManager.enabled` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `bool` | `false` | ❌ | `proxy_service.https_keypairs` (to provide your own certificates) | + +Setting `highAvailability.certManager.enabled` to `true` will use `cert-manager` to provision a TLS certificate for a Teleport +cluster deployed in HA mode. + + + You must install and configure `cert-manager` in your Kubernetes cluster yourself. + + See the [cert-manager Helm install instructions](https://cert-manager.io/docs/installation/kubernetes/#option-2-install-crds-as-part-of-the-helm-release) + and the relevant sections of the [AWS](../guides/aws.mdx#step-4a-install-and-configure-cert-manager-to-handle-tls) and [GCP](../guides/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information. + + +### `highAvailability.certManager.addCommonName` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `bool` | `false` | ❌ | `proxy_service.https_keypairs` (to provide your own certificates) | + +Setting `highAvailability.certManager.addCommonName` to `true` will instruct `cert-manager` to set the commonName field in its certificate signing request to the issuing CA. + + + You must install and configure `cert-manager` in your Kubernetes cluster yourself. + + See the [cert-manager Helm install instructions](https://cert-manager.io/docs/installation/kubernetes/#option-2-install-crds-as-part-of-the-helm-release) + and the relevant sections of the [AWS](../guides/aws.mdx#step-4a-install-and-configure-cert-manager-to-handle-tls) and [GCP](../guides/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information. + + + + + ```yaml + highAvailability: + certManager: + enabled: true + addCommonName: true + issuerName: letsencrypt-production + ``` + + + ```code + $ --set highAvailability.certManager.enabled=true \ + --set highAvailability.certManager.addCommonName=true \ + --set highAvailability.certManager.issuerName=letsencrypt-production + ``` + + + +### `highAvailability.certManager.issuerName` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `string` | `nil` | ❌ | None | + +Sets the name of the `cert-manager` `Issuer` or `ClusterIssuer` to use for issuing certificates. + + + You must install configure an appropriate `Issuer` supporting a DNS01 challenge yourself. + + Please see the [cert-manager DNS01 docs](https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers) and the relevant sections + of the [AWS](../guides/aws.mdx#step-4a-install-and-configure-cert-manager-to-handle-tls) and [GCP](../guides/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information. + + + + + ```yaml + highAvailability: + certManager: + enabled: true + issuerName: letsencrypt-production + ``` + + + ```code + $ --set highAvailability.certManager.enabled=true \ + --set highAvailability.certManager.issuerName=letsencrypt-production + ``` + + + +### `highAvailability.certManager.issuerKind` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `string` | `Issuer` | ❌ | None | + +Sets the `Kind` of `Issuer` to be used when issuing certificates with `cert-manager`. Defaults to `Issuer` to keep permissions +scoped to a single namespace. + + + + ```yaml + highAvailability: + certManager: + issuerKind: ClusterIssuer + ``` + + + ```code + --set highAvailability.certManager.issuerKind=ClusterIssuer + ``` + + + +### `highAvailability.certManager.issuerGroup` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `string` | `cert-manager.io` | ❌ | None | + +Sets the `Group` of `Issuer` to be used when issuing certificates with `cert-manager`. Defaults to `cert-manager.io` to use built-in issuers. + + + + ```yaml + highAvailability: + certManager: + issuerGroup: cert-manager.io + ``` + + + ```code + --set highAvailability.certManager.issuerGroup=cert-manager.io + ``` + + + +## `image` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `string` | `quay.io/gravitational/teleport` | ✅ | + +`image` sets the container image used for Teleport Community pods in the cluster. + +You can override this to use your own Teleport Community image rather than a Teleport-published image. + + + + ```yaml + image: my.docker.registry/teleport-community-image-name + ``` + + + ```code + --set image=my.docker.registry/teleport-community-image-name + ``` + + + +## `enterpriseImage` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `string` | `quay.io/gravitational/teleport-ent` | ✅ | + +`enterpriseImage` sets the container image used for Teleport Enterprise pods in the cluster. + +You can override this to use your own Teleport Enterprise image rather than a Teleport-published image. + + + + ```yaml + enterpriseImage: my.docker.registry/teleport-enterprise-image-name + ``` + + + ```code + --set enterpriseImage=my.docker.registry/teleport-enterprise-image + ``` + + + +## `log` + +### `log.level` + + + This field used to be called `logLevel`. For backwards compatibility this name can still be used, but we recommend changing your values file to use `log.level`. + + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `string` | `INFO` | ❌ | `teleport.log.severity` | + +`log.level` sets the log level used for the Teleport process. + +Available log levels (in order of most to least verbose) are: `DEBUG`, `INFO`, `WARNING`, `ERROR`. + +The default is `INFO`, which is recommended in production. + +`DEBUG` is useful during first-time setup or to see more detailed logs for debugging. + + + + ```yaml + log: + level: DEBUG + ``` + + + ```code + --set log.level=DEBUG + ``` + + + +### `log.output` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `string` | `stderr` | ❌ | `teleport.log.output` | + +`log.output` sets the output destination for the Teleport process. + +This can be set to any of the built-in values: `stdout`, `stderr` or `syslog` to use that destination. + +The value can also be set to a file path (such as `/var/log/teleport.log`) to write logs to a file. Bear in mind that a few service startup messages will still go to `stderr` for resilience. + + + + ```yaml + log: + output: stderr + ``` + + + ```code + --set log.output=stderr + ``` + + + +### `log.format` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `string` | `text` | ❌ | `teleport.log.format.output` | + +`log.format` sets the output type for the Teleport process. + +Possible values are `text` (default) or `json`. + + + + ```yaml + log: + format: json + ``` + + + ```code + --set log.format=json + ``` + + + +### `log.extraFields` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `list` | `["timestamp", "level", "component", "caller"]` | ❌ | `teleport.log.format.extra_fields` | + +`log.extraFields` sets the fields used in logging for the Teleport process. + +See the [Teleport config file reference](../../../setup/reference/config.mdx) for more details on possible values for `extra_fields`. + + + + ```yaml + log: + extraFields: ["timestamp", "level"] + ``` + + + ```code + --set "log.extraFields[0]=timestamp" \ + --set "log.extraFields[1]=level" + ``` + + + +## `affinity` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) + +Kubernetes affinity to set for pod assignments. + + + You cannot set both `affinity` and `highAvailability.requireAntiAffinity` as they conflict with each other. Only set one or the other. + + + + + ```yaml + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: gravitational.io/dedicated + operator: In + values: + - teleport + ``` + + + ```code + $ --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].key=gravitational.io/dedicated \ + --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].operator=In \ + --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].values[0]=teleport + ``` + + + +## `annotations.config` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `object` | `{}` | ❌ | None | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + +Kubernetes annotations which should be applied to the `ConfigMap` created by the chart. + + + These annotations will not be applied in `custom` mode, as the `ConfigMap` is not managed by the chart. + In this instance, you should apply annotations manually to your created `ConfigMap`. + + + + + ```yaml + annotations: + config: + kubernetes.io/annotation: value + ``` + + + ```code + $ --set annotations.config."kubernetes\.io\/annotation"=value + ``` + + You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend + using a `values.yaml` file instead to avoid confusion and errors. + + + + +## `annotations.deployment` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + +Kubernetes annotations which should be applied to the `Deployment` created by the chart. + + + + ```yaml + annotations: + deployment: + kubernetes.io/annotation: value + ``` + + + ```code + $ --set annotations.deployment."kubernetes\.io\/annotation"=value + ``` + + You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend + using a `values.yaml` file instead to avoid confusion and errors. + + + + +## `annotations.pod` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + +Kubernetes annotations which should be applied to each `Pod` created by the chart. + + + + ```yaml + annotations: + pod: + kubernetes.io/annotation: value + ``` + + + ```code + $ --set annotations.pod."kubernetes\.io\/annotation"=value + ``` + + You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend + using a `values.yaml` file instead to avoid confusion and errors. + + + + +## `annotations.service` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + +Kubernetes annotations which should be applied to the `Service` created by the chart. + + + + ```yaml + annotations: + service: + kubernetes.io/annotation: value + ``` + + + ```code + $ --set annotations.service."kubernetes\.io\/annotation"=value + ``` + + You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend + using a `values.yaml` file instead to avoid confusion and errors. + + + + +## `annotations.serviceAccount` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + +Kubernetes annotations which should be applied to the `serviceAccount` created by the chart. + + + + ```yaml + annotations: + serviceAccount: + kubernetes.io/annotation: value + ``` + + + ```code + $ --set annotations.serviceAccount."kubernetes\.io\/annotation"=value + ``` + + You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend + using a `values.yaml` file instead to avoid confusion and errors. + + + + +## `annotations.certSecret` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + +Kubernetes annotations which should be applied to the `secret` generated by +`cert-manager` from the `certificate` created by the chart. Only valid when +`highAvailability.certManager.enabled` is set to `true` and requires +`cert-manager` v1.5.0+. + + + + ```yaml + annotations: + certSecret: + kubernetes.io/annotation: value + ``` + + + ```code + $ --set annotations.certSecret."kubernetes\.io\/annotation"=value + ``` + + You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend + using a `values.yaml` file instead to avoid confusion and errors. + + + + +## `service.type` + +| Type | Default value | Required? | Can be used in `custom` mode? | +| - | - | - | - | +| `string` | `LoadBalancer` | Yes | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/services-networking/service/) + +Allows to specify the service type. + + + + ```yaml + service: + type: LoadBalancer + ``` + + + ```code + $ --set service.type=LoadBalancer + ``` + + + +## `service.spec.loadBalancerIP` + +| Type | Default value | Required? | Can be used in `custom` mode? | +| - | - | - | - | +| `string` | `nil` | No | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer) + +Allows to specify the `loadBalancerIP`. + + + + ```yaml + service: + spec: + loadBalancerIP: 1.2.3.4 + ``` + + + ```code + $ --set service.spec.loadBalancerIP=1.2.3.4 + ``` + + + +## `extraArgs` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +A list of extra arguments to pass to the `teleport start` command when running a Teleport Pod. + + + + ```yaml + extraArgs: + - "--bootstrap=/etc/teleport-bootstrap/roles.yaml" + ``` + + + ```code + $ --set "extraArgs={--bootstrap=/etc/teleport-bootstrap/roles.yaml}" + ``` + + + +## `extraEnv` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/) + +A list of extra environment variables to be set on the main Teleport container. + + + + ```yaml + extraEnv: + - name: MY_ENV + value: my-value + ``` + + + ```code + $ --set "extraEnv[0].name=MY_ENV" \ + --set "extraEnv[0].value=my-value" + ``` + + + + +## `extraVolumes` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/volumes/) + +A list of extra Kubernetes `Volumes` which should be available to any `Pod` created by the chart. These volumes +will also be available to any `initContainers` configured by the chart. + + + + ```yaml + extraVolumes: + - name: myvolume + secret: + secretName: mysecret + ``` + + + ```code + $ --set "extraVolumes[0].name=myvolume" \ + --set "extraVolumes[0].secret.secretName=mysecret" + ``` + + + +## `extraVolumeMounts` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/volumes/) + +A list of extra Kubernetes volume mounts which should be mounted into any `Pod` created by the chart. These volume +mounts will also be mounted into any `initContainers` configured by the chart. + + + + ```yaml + extraVolumeMounts: + - name: myvolume + mountPath: /path/to/mount/volume + ``` + + + ```code + $ --set "extraVolumeMounts[0].name=myvolume" \ + --set "extraVolumeMounts[0].path=/path/to/mount/volume" + ``` + + + +## `imagePullPolicy` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `string` | `IfNotPresent` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/containers/images/#updating-images) + +Allows the `imagePullPolicy` for any pods created by the chart to be overridden. + + + + ```yaml + imagePullPolicy: Always + ``` + + + ```code + $ --set imagePullPolicy=Always + ``` + + + +## `initContainers` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) + +A list of `initContainers` which will be run before the main Teleport container in any pod created by the chart. + + + + ```yaml + initContainers: + - name: teleport-init + image: alpine + args: ['echo test'] + ``` + + + ```code + $ --set "initContainers[0].name=teleport-init" \ + --set "initContainers[0].image=alpine" \ + --set "initContainers[0].args={echo test}" + ``` + + + +## `postStart` + +[Kubernetes reference](https://kubernetes.io/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/) + +A `postStart` lifecycle handler to be configured on the main Teleport container. + + + + ```yaml + postStart: + command: + - echo + - foo + ``` + + + ```shell + --set "postStart.command[0]=echo" \ + --set "postStart.command[1]=foo" + ``` + + + +## `resources` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) + +Resource requests/limits which should be configured for each container inside the pod. These resource limits +will also be applied to `initContainers`. + + + + ```yaml + resources: + requests: + cpu: 1 + memory: 2Gi + ``` + + + ```code + $ --set resources.requests.cpu=1 \ + --set resources.requests.memory=2Gi + ``` + + + +## `tolerations` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) + +Kubernetes Tolerations to set for pod assignment. + + + + ```yaml + tolerations: + - key: "dedicated" + operator: "Equal" + value: "teleport" + effect: "NoSchedule" + ``` + + + ```code + $ --set tolerations[0].key=dedicated \ + --set tolerations[0].operator=Equal \ + --set tolerations[0].value=teleport \ + --set tolerations[0].effect=NoSchedule + ``` + + + +## `priorityClassName` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `string` | `""` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/) + +Kubernetes PriorityClass to set for pod. + + + + ```yaml + priorityClassName: "system-cluster-critical" + ``` + + + ```code + $ --set priorityClassName=system-cluster-critical + ``` + + + diff --git a/docs/pages/kubernetes-access/helm/reference/teleport-kube-agent.mdx b/docs/pages/kubernetes-access/helm/reference/teleport-kube-agent.mdx new file mode 100644 index 0000000000000..ef76f14e59562 --- /dev/null +++ b/docs/pages/kubernetes-access/helm/reference/teleport-kube-agent.mdx @@ -0,0 +1,1334 @@ +--- +title: teleport-kube-agent Chart Reference +description: Values that can be set using the teleport-cluster Helm chart +--- + +The `teleport-kube-agent` Helm chart is used to configure a Teleport agent that +runs in a remote Kubernetes cluster and joins back to a Teleport cluster to +provide access to services running there. + +You can [browse the source on GitHub](https://github.com/gravitational/teleport/tree/master/examples/chart/teleport-kube-agent). + +The `teleport-kube-agent` chart can run any or all of three Teleport services: + +| Teleport service | Name for `roles` and `tctl tokens add` | Purpose | +| - | - | - | +| [`kubernetes_service`](../../../kubernetes-access/guides.mdx) | `kube` | Uses Teleport to handle authentication with and proxy access to a Kubernetes cluster | +| [`application_service`](../../../application-access/guides.mdx) | `app` | Uses Teleport to handle authentication with and proxy access to web-based applications | +| [`database_service`](../../../database-access/guides.mdx) | `db` | Uses Teleport to handle authentication with and proxy access to databases | + +This reference details available values for the `teleport-kube-agent` chart. + +(!docs/pages/includes/backup-warning.mdx!) + +## `roles` + +This parameter is not mandatory to preserve backwards compatibility with older chart versions, but we recommend it is set. + +| Type | Default value | +| - | - | +| `string` | `kube` | + +`roles` is a comma-separated list of services which should be enabled when running the `teleport-kube-agent` chart. + +| Services | Value for `roles` | Mandatory additional settings for this role | +| - | - | - | +| Teleport Kubernetes service | `kube` | [`kubeClusterName`](#kubeclustername) | +| Teleport Application service | `app` | [`apps`](#apps) | +| Teleport Database service | `db` | [`databases`](#databases) | + + + + ```yaml + roles: kube,app,db + ``` + + + ```code + $ --set roles=kube\,app\,db + ``` + + + When specifying multiple roles using `--set` syntax, you must escape the commas using a backslash (`\`). + + This is a quirk of Helm's CLI parser. + + + + + +If you specify a role here, you may also need to specify some other settings which are detailed in this reference. + +## `authToken` + +| Type | Default value | Required? | +| - | - | - | +| `string` | `nil` | Yes | + +`authToken` provides a Teleport join token which will be used to join the Teleport agent to a Teleport cluster. + +This value **must** be provided for the chart to work. The token that you use must also be valid for every Teleport service that you +are trying to add with the `teleport-kube-agent` chart. Here are a few examples: + +| Services | Service Name | `tctl tokens add` example | `teleport.yaml` static token example | +| - | - | - | - | +| Kubernetes | `kube` | `tctl tokens add --type=kube` | `"kube:"` | +| Kubernetes, Application | `kube,app` | `tctl tokens add --type=kube,app` | `"kube,app:"` | +| Kubernetes, Application, Database | `kube,app,db` | `tctl tokens add --type=kube,app,db` | `"kube,app,db:"` | + + + When you use a token, all of the services that it provides **must** be used. + + For example, you cannot use a token of type `app,db` to only join a Teleport `app` service by itself. It must join both `app` and `db` services at once. + + Also, each static token you configure must be unique, as the token itself is used to define which services will be supported. + + You cannot reuse the same static token and specify a different set of services. + + +If you do not have the correct services (Teleport refers to these internally as `Roles`) assigned to your join token, the Teleport agent will +fail to join the Teleport cluster. + + + + ```yaml + authToken: + ``` + + + ```code + $ --set authToken= + ``` + + + +## `proxyAddr` + +| Type | Default value | Required? | +| - | - | - | +| `string` | `nil` | Yes | + +`proxyAddr` provides the public-facing Teleport proxy endpoint which should be used to join the cluster. This is the same URL that is used +to access the web UI of your Teleport cluster. It is the same as the value configured for `proxy_service.public_addr` in a traditional +Teleport cluster. The port used is usually either 3080 or 443. + +Here are a few examples: + +| Deployment method | Example `proxy_service.public_addr` | +| - | - | +| On-prem Teleport cluster | `teleport.example.com:3080` | +| Teleport Cloud cluster | `example.teleport.sh:443` | +| `teleport-cluster` Helm chart | `teleport.example.com:443` | + +## `kubeClusterName` + +| Type | Default value | Required? | +| - | - | - | +| `string` | `nil` | When `kube` chart role is used | + +`kubeClusterName` sets the name used for the Kubernetes cluster proxied by the Teleport agent. This name will be shown to Teleport users +connecting to the cluster. + + + + ```yaml + kubeClusterName: my-gke-cluster + ``` + + + ```code + $ --set kubeClusterName=my-gke-cluster + ``` + + + +## `apps` + +| Type | Default value | Required? | +| - | - | - | +| `list` | `[]` | When `app` chart role is used? | + +`apps` is a YAML list object detailing the applications that should be proxied by Teleport Application access. + +You can specify multiple apps by adding additional list elements. + + + + ```yaml + apps: + - name: grafana + uri: http://localhost:3000 + labels: + purpose: monitoring + - name: jenkins + uri: http://jenkins:8080 + labels: + purpose: ci + ``` + + + YAML is very sensitive to correct spacing. When specifying lists in a `values.yaml` file, you might like + to [use a linter](https://codebeautify.org/yaml-validator) to validate your YAML list and ensure that it is correctly formatted. + + + + ```code + $ --set "apps[0].name=grafana" \ + --set "apps[0].uri=http://localhost:3000" \ + --set "apps[0].purpose=monitoring" \ + --set "apps[1].name=grafana" \ + --set "apps[1].uri=http://jenkins:8080" \ + --set "apps[1].purpose=ci" + ``` + + + Note that when using `--set` syntax, YAML list elements must be indexed starting at `0`. + + + + + + + You can see a list of all the supported [values which can be used in a Teleport application access configuration here](../../../application-access/reference.mdx#configuration). + + +## `awsDatabases` + + + This section configures database auto-discovery, which is only currently supported on AWS. You can configure databases for other platforms using the [`databases`](#databases) section below this. + + + + For AWS database auto-discovery to work, your agent pods will need to use a role which has appropriate IAM permissions as per the [database documentation](../../../database-access/guides/rds.mdx#step-47-create-an-iam-policy-for-teleport). + + After configuring a role, you can use an `eks.amazonaws.com/role-arn` annotation with the `annotations.serviceAccount` value to associate it with the service account and grant permissions: + + ``` + annotations: + serviceAccount: + eks.amazonaws.com/role-arn: arn:aws:iam::1234567890:role/my-rds-autodiscovery-role + ``` + + +| Type | Default value | Required? | +| - | - | - | +| `list` | `[]` | No | + +`awsDatabases` is a YAML list object detailing the filters for the AWS databases that should be discovered and proxied by Teleport Database access. + +You can specify multiple database filters by adding additional list elements. + +- `types` is a list containing the types of AWS databases that should be discovered. +- `regions` is a list of AWS regions which should be scanned for databases. +- `tags` can be used to set AWS tags that must be matched for databases to be discovered. + + + + ```yaml + awsDatabases: + - types: ["rds"] + regions: ["us-east-1", "us-west-2"] + tags: + "environment": "production" + - types: ["rds"] + regions: ["us-east-1"] + tags: + "environment": "dev" + - types: ["rds"] + regions: ["eu-west-1"] + tags: + "*": "*" + ``` + + + YAML is very sensitive to correct spacing. When specifying lists in a `values.yaml` file, you might like + to [use a linter](https://codebeautify.org/yaml-validator) to validate your YAML list and ensure that it is correctly formatted. + + + + ```code + --set "awsDatabases[0].types[0]=rds" \ + --set "awsDatabases[0].regions[0]=us-east-1" \ + --set "awsDatabases[0].regions[1]=us-west-2" \ + --set "awsDatabases[0].tags[0].environment=production" \ + --set "awsDatabases[1].types[0]=rds" \ + --set "awsDatabases[1].regions[0]=us-east-1" \ + --set "awsDatabases[1].tags[0].environment=dev" \ + --set "awsDatabases[2].types[0]=rds" \ + --set "awsDatabases[2].regions[0]=eu-west-1" \ + --set "awsDatabases[2].tags[0].*=*" + ``` + + + Note that when using `--set` syntax, YAML list elements must be indexed starting at `0`. + + + + + +## `databases` + +| Type | Default value | Required? | +| - | - | - | +| `list` | `[]` | When `db` chart role is used | + +`databases` is a YAML list object detailing the databases that should be proxied by Teleport Database access. + +You can specify multiple databases by adding additional list elements. + + + + ```yaml + databases: + - name: aurora-postgres + uri: postgres-aurora-instance-1.xxx.us-east-1.rds.amazonaws.com:5432 + protocol: postgres + aws: + region: us-east-1 + static_labels: + env: staging + - name: mysql + uri: mysql-instance-1.xxx.us-east-1.rds.amazonaws.com:3306 + protocol: mysql + aws: + region: us-east-1 + static_labels: + env: staging + ``` + + + YAML is very sensitive to correct spacing. When specifying lists in a `values.yaml` file, you might like + to [use a linter](https://codebeautify.org/yaml-validator) to validate your YAML list and ensure that it is correctly formatted. + + + + ```code + $ --set "databases[0].name=aurora" \ + --set "databases[0].uri=postgres-aurora-instance-1.xxx.us-east-1.rds.amazonaws.com:5432" \ + --set "databases[0].protocol=postgres" \ + --set "databases[0].aws.region=us-east-1" \ + --set "databases[0].static_labels.env=staging" \ + --set "databases[1].name=mysql" \ + --set "databases[1].uri=mysql-instance-1.xxx.us-east-1.rds.amazonaws.com:3306" \ + --set "databases[1].protocol=mysql" \ + --set "databases[1].aws.region=us-east-1" \ + --set "databases[1].static_labels.env=staging" + ``` + + + Note that when using `--set` syntax, YAML list elements must be indexed starting at `0`. + + + + + + + You can see a list of all the supported [values which can be used in a Teleport database service configuration here](../../../database-access/reference/configuration.mdx). + + +## `teleportVersionOverride` + +| Type | Default value | +| - | - | +| `string` | `nil` | + +Normally the version of Teleport being used will match the version of the chart being installed. If you install chart version +7.0.0, you'll be using Teleport 7.0.0. + +You can optionally override this to use a different published Teleport Docker image tag like `6.0.2` or `7`. + +See [this link for information on Community Docker image versions](../../../setup/guides/docker.mdx#step-14-pick-your-image). + + + 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. + + + + + ```yaml + teleportVersionOverride: "7" + ``` + + + ```code + $ --set teleportVersionOverride="7" + ``` + + + +## `insecureSkipProxyTLSVerify` + +| Type | Default value | +| - | - | +| `bool` | `false` | + +When `insecureSkipProxyTLSVerify` is set to `true`, the agent will skip the verification of the TLS certificate presented by the Teleport +proxy server specified using [`proxyAddr`](#proxyaddr). + +This can be used for joining a Teleport agent to a Teleport cluster which does not have valid TLS certificates for testing. + + + + ```yaml + insecureSkipProxyTLSVerify: false + ``` + + + ```code + $ --set insecureSkipProxyTLSVerify=false + ``` + + + + + Using a self-signed TLS certificate and disabling TLS verification is OK for testing, but is not viable when running a production Teleport + cluster as it will drastically reduce security. You must configure valid TLS certificates on your Teleport cluster for production workloads. + + One option might be to use Teleport's built-in [ACME support](./teleport-cluster.mdx#acme) or enable [cert-manager support](./teleport-cluster.mdx#highavailabilitycertmanager). + + +## `existingDataVolume` + +| Type | Default value | +| - | - | +| `string` | `""` | + +When `existingDataVolume` is set to the name of an existing volume, the `/var/lib/teleport` mount will use this volume instead of creating a new `emptyDir` volume. + + + + ```yaml + existingDataVolume: my-volume + ``` + + + ```bash + --set existingDataVolume=my-volume + ``` + + + +## `podSecurityPolicy` + +### `podSecurityPolicy.enabled` + +| Type | Default value | +| - | - | +| `bool` | `true` | + +By default, Teleport charts also install a [`podSecurityPolicy`](https://github.com/gravitational/teleport/blob/master/examples/chart/teleport-kube-agent/templates/psp.yaml). + +To disable this, you can set `enabled` to `false`. + +[Kubernetes reference](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) + + + + ```yaml + podSecurityPolicy: + enabled: false + ``` + + + ```code + $ --set podSecurityPolicy.enabled=false + ``` + + + +## `labels` + +| Type | Default value | +| - | - | +| `object` | `{}` | + +`labels` can be used to add a map of key-value pairs for the `kubernetes_service` which is deployed using the `teleport-kube-agent` chart. +These labels can then be used with Teleport's RBAC policies to define access rules for the cluster. + + + These are Teleport-specific RBAC labels, not Kubernetes labels. + + + + For historical/backwards compatibility reasons, these labels will only be applied to the Kubernetes cluster being joined via the + Teleport Kubernetes service. + + To set labels for applications, add a `labels` element to the [`apps`](#apps) section. + To set labels for databases, add a `static_labels` element to the [`databases`](#databases) section. + + For more information on how to set static/dynamic labels for Teleport services, see [labelling nodes and applications](../../../setup/admin/labels.mdx). + + + + + ```yaml + labels: + environment: production + region: us-east + ``` + + + ```code + $ --set labels.environment=production \ + --set labels.region=us-east + ``` + + + +## `storage` + +### `storage.enabled` + +| Type | Default value | +| - | - | +| `bool` | `false` | + +Enables the creation of a Kubernetes persistent volume to hold Teleport agent state. + +[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) + + + + ```yaml + storage: + enabled: true + ``` + + + ```bash + --set storage.enabled=true + ``` + + + +### `storage.storageClassName` + +| Type | Default value | +| - | - | +| `string` | `nil` | + +The storage class name the persistent volume should use when creating persistent volume claims. The provided storage class +name needs to exist on the Kubernetes cluster for Teleport to use. + +[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/storage-classes/) + + + + ```yaml + storage: + storageClassName: teleport-storage-class + ``` + + + ```bash + --set storage.storageClassName=teleport-storage-class + ``` + + + +### `storage.requests` + +| Type | Default value | +| - | - | +| `string` | `128Mi` | + +The size of persistent volume to create. + + + + ```yaml + storage: + requests: 128Mi + ``` + + + ```bash + --set storage.requests=128Mi + ``` + + + +## `image` + +| Type | Default value | +| - | - | +| `string` | `quay.io/gravitational/teleport` | + +`image` sets the container image used for Teleport pods run by the `teleport-kube-agent` chart. + +You can override this to use your own Teleport image rather than a Teleport-published image. + + + + ```yaml + image: my.docker.registry/teleport-image-name + ``` + + + ```code + $ --set image=my.docker.registry/teleport-image-name + ``` + + + +## `imagePullSecrets` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) + +A list of secrets containing authorization tokens which can be optionally used to access a private Docker registry. + + + + ```yaml + imagePullSecrets: + - name: my-docker-registry-key + ``` + + + ```shell + --set "imagePullSecrets[0].name=my-docker-registry-key" + ``` + + + +### `highAvailability` + +## `highAvailability.replicaCount` + +| Type | Default value | +| - | - | +| `int` | `1` | + +`highAvailability.replicaCount` can be used to set the number of replicas used in the deployment. + +Set to a number higher than `1` for a high availability mode where multiple Teleport agent pods will be deployed. + + + As a rough guide, we recommend configuring one replica per distinct availability zone where your cluster has worker nodes. + + 2 replicas/availability zones will be fine for smaller workloads. 3-5 replicas/availability zones will be more appropriate for bigger + clusters with more traffic. + + + + + ```yaml + highAvailability: + replicaCount: 3 + ``` + + + ```shell + --set highAvailability.replicaCount=3 + ``` + + + +## `highAvailability.requireAntiAffinity` + +| Type | Default value | +| - | - | +| `bool` | `false` | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity) + +Setting `highAvailability.requireAntiAffinity` to `true` will use `requiredDuringSchedulingIgnoredDuringExecution` to require that multiple +Teleport pods must not be scheduled on the same physical host. + + + This can result in Teleport pods failing to be scheduled in very small clusters or during node downtime, so should be used with caution. + + + Setting `highAvailability.requireAntiAffinity` to `false` (the default) uses `preferredDuringSchedulingIgnoredDuringExecution` to make node + anti-affinity a soft requirement. + + + This setting only has any effect when `highAvailability.replicaCount` is greater than `1`. + + + + + ```yaml + highAvailability: + requireAntiAffinity: true + ``` + + + ```shell + --set highAvailability.requireAntiAffinity=true + ``` + + + +## `highAvailability.podDisruptionBudget` + +### `highAvailability.podDisruptionBudget.enabled` + +| Type | Default value | +| - | - | +| `bool` | `false` | + +[Kubernetes reference](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) + +Enable a Pod Disruption Budget for the Teleport Pod to ensure HA during voluntary disruptions. + + + + ```yaml + highAvailability: + podDisruptionBudget: + enabled: true + ``` + + + ```shell + --set highAvailability.podDisruptionBudget.enabled=true + ``` + + + +### `highAvailability.podDisruptionBudget.minAvailable` + +| Type | Default value | +| - | - | +| `int` | `1` | + +[Kubernetes reference](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) + +Ensures that this number of replicas is available during voluntary disruptions, can be a number of replicas or a percentage. + + + + ```yaml + highAvailability: + podDisruptionBudget: + minAvailable: 1 + ``` + + + ```shell + --set highAvailability.podDisruptionBudget.minAvailable=1 + ``` + + + +## `clusterRoleName` + +| Type | Default value | +| - | - | +| `string` | `nil` | + +`clusterRoleName` can be optionally used to override the name of the Kubernetes `ClusterRole` used by the `teleport-kube-agent` chart's `ServiceAccount`. + + + Most users will not need to change this. + + + + + ```yaml + clusterRoleName: kubernetes-clusterrole + ``` + + + ```code + $ --set clusterRoleName=kubernetes-clusterrole + ``` + + + +## `clusterRoleBindingName` + + + Most users will not need to change this. + + +| Type | Default value | +| - | - | +| `string` | `nil` | + + +`clusterRoleBindingName` can be optionally used to override the name of the Kubernetes `ClusterRoleBinding` used by the `teleport-kube-agent` chart's `ServiceAccount`. + + + + ```yaml + clusterRoleBindingName: kubernetes-clusterrolebinding + ``` + + + ```code + $ --set clusterRoleBindingName=kubernetes-clusterrolebinding + ``` + + + +## `serviceAccountName` + + + Most users will not need to change this. + + +| Type | Default value | +| - | - | +| `string` | `nil` | + +`serviceAccountName` can be optionally used to override the name of the Kubernetes `ServiceAccount` used by the `teleport-kube-agent` chart. + + + + ```yaml + serviceAccountName: kubernetes-serviceaccount + ``` + + + ```code + $ --set serviceAccountName=kubernetes-serviceaccount + ``` + + + +## `secretName` + +| Type | Default value | +| - | - | +| `string` | `teleport-kube-agent-join-token` | + +`secretName` is the name of the Kubernetes `Secret` used to store the Teleport join token which is used by the `teleport-kube-agent` chart. + +If you set this to a blank value, the chart will not attempt to create the secret itself and will instead read the value of the +existing `teleport-kube-agent-join-token` secret. This allows you to configure this secret externally and avoid having a plaintext +join token stored in your Teleport chart values. + +To create your own join token secret, you can use a command like this: + +```code +$ kubectl --namespace teleport create secret generic teleport-kube-agent-join-token --from-literal=auth-token= +``` + + + The key used for the auth token inside the secret must be `auth-token`, as in the command above. + + + + + ```yaml + serviceAccountName: + ``` + + + ```code + $ --set serviceAccountName="" + ``` + + + +## `log` + +### `log.level` + + + This field used to be called `logLevel`. For backwards compatibility this name can still be used, but we recommend changing your values file to use `log.level`. + + +| Type | Default value | +| - | - | +| `string` | `INFO` | + +`log.level` sets the log level used for the Teleport process. + +Available log levels (in order of most to least verbose) are: `DEBUG`, `INFO`, `WARNING`, `ERROR`. + +The default is `INFO`, which is recommended in production. + +`DEBUG` is useful during first-time setup or to see more detailed logs for debugging. + + + + ```yaml + log: + level: DEBUG + ``` + + + ```code + --set log.level=DEBUG + ``` + + + +### `log.output` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `string` | `stderr` | ❌ | `teleport.log.output` | + +`log.output` sets the output destination for the Teleport process. + +This can be set to any of the built-in values: `stdout`, `stderr` or `syslog` to use that destination. + +The value can also be set to a file path (such as `/var/log/teleport.log`) to write logs to a file. Bear in mind that a few service startup messages will still go to `stderr` for resilience. + + + + ```yaml + log: + output: stderr + ``` + + + ```code + --set log.output=stderr + ``` + + + +### `log.format` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `string` | `text` | ❌ | `teleport.log.format.output` | + +`log.format` sets the output type for the Teleport process. + +Possible values are `text` (default) or `json`. + + + + ```yaml + log: + format: json + ``` + + + ```code + --set log.format=json + ``` + + + +### `log.extraFields` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `list` | `["timestamp", "level", "component", "caller"]` | ❌ | `teleport.log.format.extra_fields` | + +`log.extraFields` sets the fields used in logging for the Teleport process. + +See the [Teleport config file reference](../../../setup/reference/config.mdx) for more details on possible values for `extra_fields`. + + + + ```yaml + log: + extraFields: ["timestamp", "level"] + ``` + + + ```code + --set "log.extraFields[0]=timestamp" \ + --set "log.extraFields[1]=level" + ``` + + + +## `affinity` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) + +Kubernetes affinity to set for pod assignments. + + + You cannot set both `affinity` and `highAvailability.requireAntiAffinity` as they conflict with each other. + + + + + ```yaml + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: gravitational.io/dedicated + operator: In + values: + - teleport + ``` + + + ```code + $ --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].key=gravitational.io/dedicated \ + --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].operator=In \ + --set affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[0].matchExpressions[0].values[0]=teleport + ``` + + + +## `nodeSelector` + +| Type | Default value | +| - | - | +| `object` | `{}` | + +`nodeSelector` can be used to add a map of key-value pairs to constrain the nodes the agent pods will run on. + +[Kubernetes reference](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/) + + + + ```yaml + nodeSelector: + role: node + region: us-east + ``` + + + ```bash + --set nodeSelector.role=node \ + --set nodeSelector.region=us-east + ``` + + + +## `annotations.config` + +| Type | Default value | Can be used in `custom` mode? | `teleport.yaml` equivalent | +| - | - | - | - | +| `object` | `{}` | ❌ | None | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + +Kubernetes annotations which should be applied to the `ConfigMap` created by the chart. + + + These annotations will not be applied in `custom` mode, as the `ConfigMap` is not managed by the chart. + In this instance, you should apply annotations manually to your created `ConfigMap`. + + + + + ```yaml + annotations: + config: + kubernetes.io/annotation: value + ``` + + + ```code + $ --set annotations.config."kubernetes\.io\/annotation"=value + ``` + + You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend + using a `values.yaml` file instead to avoid confusion and errors. + + + + +## `annotations.deployment` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + +Kubernetes annotations which should be applied to the `Deployment` created by the chart. + + + + ```yaml + annotations: + deployment: + kubernetes.io/annotation: value + ``` + + + ```code + $ --set annotations.deployment."kubernetes\.io\/annotation"=value + ``` + + You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend + using a `values.yaml` file instead to avoid confusion and errors. + + + + +## `annotations.pod` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + +Kubernetes annotations which should be applied to each `Pod` created by the chart. + + + + ```yaml + annotations: + pod: + kubernetes.io/annotation: value + ``` + + + ```code + $ --set annotations.pod."kubernetes\.io\/annotation"=value + ``` + + You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend + using a `values.yaml` file instead to avoid confusion and errors. + + + + +## `annotations.serviceAccount` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + +Kubernetes annotations which should be applied to the `ServiceAccount` created by the chart. + + + + ```yaml + annotations: + serviceAccount: + kubernetes.io/annotation: value + ``` + + + ```code + $ --set annotations.serviceAccount."kubernetes\.io\/annotation"=value + ``` + + You must escape values entered on the command line correctly for Helm's CLI to understand them. We recommend + using a `values.yaml` file instead to avoid confusion and errors. + + + + +## `extraVolumes` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/volumes/) + +A list of extra Kubernetes `Volumes` which should be available to any `Pod` created by the chart. These volumes +will also be available to any `initContainers` configured by the chart. + + + + ```yaml + extraVolumes: + - name: myvolume + secret: + secretName: mysecret + ``` + + + ```code + $ --set "extraVolumes[0].name=myvolume" \ + --set "extraVolumes[0].secret.secretName=mysecret" + ``` + + + +## `extraArgs` + +| Type | Default value | +| - | - | +| `list` | `[]` | + +A list of extra arguments to pass to the `teleport start` command when running a Teleport Pod. + + + + ```yaml + extraArgs: + - "--debug" + ``` + + + ```code + $ --set "extraArgs={--debug}" + ``` + + + +## `extraEnv` + +| Type | Default value | +| - | - | +| `list` | `[]` | + +[Kubernetes reference](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/) + +A list of extra environment variables to be set on the main Teleport container. + + + + ```yaml + extraEnv: + - name: HTTPS_PROXY + value: "http://username:password@my.proxy.host:3128" + ``` + + + ```code + $ --set "extraEnv[0].name=HTTPS_PROXY" \ + --set "extraEnv[0].value=\"http://username:password@my.proxy.host:3128\"" + ``` + + + +## `extraVolumeMounts` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/storage/volumes/) + +A list of extra Kubernetes volume mounts which should be mounted into any `Pod` created by the chart. These volume +mounts will also be mounted into any `initContainers` configured by the chart. + + + + ```yaml + extraVolumeMounts: + - name: myvolume + mountPath: /path/to/mount/volume + ``` + + + ```code + $ --set "extraVolumeMounts[0].name=myvolume" \ + --set "extraVolumeMounts[0].path=/path/to/mount/volume" + ``` + + + +## `imagePullPolicy` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `string` | `IfNotPresent` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/containers/images/#updating-images) + +Allows the `imagePullPolicy` for any pods created by the chart to be overridden. + + + + ```yaml + imagePullPolicy: Always + ``` + + + ```code + $ --set imagePullPolicy=Always + ``` + + + +## `initContainers` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) + +A list of `initContainers` which will be run before the main Teleport container in any pod created by the chart. + + + + ```yaml + initContainers: + - name: teleport-init + image: alpine + args: ['echo test'] + ``` + + + ```code + $ --set "initContainers[0].name=teleport-init" \ + --set "initContainers[0].image=alpine" \ + --set "initContainers[0].args={echo test}" + ``` + + + +## `resources` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `object` | `{}` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) + +Resource requests/limits which should be configured for each container inside the pod. These resource limits +will also be applied to `initContainers`. + + + + ```yaml + resources: + requests: + cpu: 1 + memory: 2Gi + ``` + + + ```code + $ --set resources.requests.cpu=1 \ + --set resources.requests.memory=2Gi + ``` + + + +## `tolerations` + +| Type | Default value | Can be used in `custom` mode? | +| - | - | - | +| `list` | `[]` | ✅ | + +[Kubernetes reference](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) + +Kubernetes Tolerations to set for pod assignment. + + + + ```yaml + tolerations: + - key: "dedicated" + operator: "Equal" + value: "teleport" + effect: "NoSchedule" + ``` + + + ```code + $ --set tolerations[0].key=dedicated \ + --set tolerations[0].operator=Equal \ + --set tolerations[0].value=teleport \ + --set tolerations[0].effect=NoSchedule + ``` + +