Fork me on GitHub
Teleport

Helm chart reference

Improve

The Teleport Helm repository hosts two Helm charts:

Warning

Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.

teleport-cluster

The teleport-cluster Helm chart is used to configure a Teleport cluster. It runs two Teleport services:

Teleport servicePurposeDocumentation
auth_serviceAuthenticates users and hosts, and issues certificatesAuth documentation
proxy_serviceRuns the externally-facing parts of a Teleport cluster, such as the web UI, SSH proxy and reverse tunnel serviceProxy documentation

The teleport-cluster chart can be deployed in four different modes. Get started with a guide for each mode:

chartModeGuide
standaloneGetting started with Kubernetes Access
awsRunning an HA Teleport cluster using an AWS EKS Cluster
gcpRunning an HA Teleport cluster using a Google Cloud GKE cluster
customRunning a Teleport cluster with a custom config

This reference details available values for the teleport-cluster chart.

clusterName

TypeDefault valueRequired?teleport.yaml equivalentCan be used in custom mode?
stringnilWhen chartMode is aws, gcp or standaloneauth_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.

Note

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.

Whether an IP or hostname is provided as an external address for the load balancer varies according to the provider.

EKS uses a hostname:

$ kubectl --namespace teleport-cluster get service/teleport -o jsonpath='{.status.loadBalancer.ingress[*].hostname}'
# a5f22a02798f541e58c6641c1b158ea3-1989279894.us-east-1.elb.amazonaws.com

GKE uses an IP address:

$ kubectl --namespace teleport-cluster get service/teleport -o jsonpath='{.status.loadBalancer.ingress[*].ip}'
# 35.203.56.38

You will need to manually add DNS records pointing teleport.example.com and *.teleport.example.com to either the IP or hostname of the Kubernetes load balancer.

If you are not using ACME certificates, you may also need to accept insecure warnings in your browser to view the page successfully.

kubeClusterName

TypeDefault valueRequired?teleport.yaml equivalentCan be used in custom mode?
stringclusterName valuenokubernetes_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

TypeDefault valueRequired?teleport.yaml equivalentCan be used in custom mode?
stringlocalYesauth_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.

proxyListenerMode

TypeDefault valueRequired?teleport.yaml equivalentCan be used in custom mode?
stringnilnoauth_service.proxy_listener_mode

proxyListenerMode controls proxy TLS routing used by Teleport. Possible values are multiplex.

enterprise

TypeDefault valueCan be used in custom mode?
boolfalse

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:

kubectl --namespace teleport create secret generic license --from-file=/path/to/downloaded/license.pem
Tip

If you installed the Teleport chart into a specific namespace, the license secret you create must also be added to the same namespace.

Note

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:

kubectl --namespace teleport create secret generic license --from-file=license.pem=/path/to/downloaded/this-is-my-teleport-license.pem
enterprise: true
--set enterprise=true

teleportVersionOverride

TypeDefault valueCan be used in custom mode?
stringnil

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:

teleportVersionOverride: "7"
--set teleportVersionOverride="7"

acme

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
boolfalseproxy_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.

Note

ACME can only be used for single-pod clusters. It is not suitable for use in HA configurations.

Warning

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.

acmeEmail

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
stringnilproxy_service.acme.email

acmeEmail is the email address to provide during certificate registration (this is a Let's Encrypt requirement).

acmeURI

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
stringLet's Encrypt production serverproxy_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 for testing.

You can also use any other ACME-compatible server.

acme: true
acmeEmail: [email protected]
acmeURI: https://acme-staging-v02.api.letsencrypt.org/directory

``code $ --set acme=true
--set acmeEmail=[email protected]
--set acmeURI=https://acme-staging-v02.api.letsencrypt.org/directory

</TabItem>
</Tabs>

## `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/)

<Tabs>
<TabItem label="values.yaml">
```yaml
podSecurityPolicy:
  enabled: false

``code $ --set podSecurityPolicy.enabled=false

</TabItem>
</Tabs>

## `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.

<Admonition type="note">
These are Teleport-specific RBAC labels, not Kubernetes labels.
</Admonition>

<Tabs>
<TabItem label="values.yaml">
```yaml
labels:
  environment: production
  region: us-east

``code $ --set labels.environment=production
--set labels.region=us-east

</TabItem>
</Tabs>

## `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.

<Tabs>
<TabItem label="values.yaml">
```yaml
standalone:
  existingClaimName: my-existing-pvc-name

``code $ --set standalone.existingClaimName=my-existing-pvc-name

</TabItem>
</Tabs>

### `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.

<Admonition type="note">
`volumeSize` will be ignored if `existingClaimName` is set.
</Admonition>

<Tabs>
<TabItem label="values.yaml">
```yaml
standalone:
  volumeSize: 50Gi

--set standalone.volumeSize=50Gi

aws

Can be used in custom mode?teleport.yaml equivalent
See Using DynamoDB and Using Amazon S3 for details

aws settings are described in the AWS guide: Running an HA Teleport cluster using an AWS EKS Cluster

gcp

Can be used in custom mode?teleport.yaml equivalent
See Using Firestore and Using GCS for details

gcp settings are described in the GCP guide: Running an HA Teleport cluster using a Google Cloud GKE cluster

highAvailability

highAvailability.replicaCount

TypeDefault valueCan be used in custom mode?
int1✅ (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.

Note

Setting highAvailability.replicaCount to a value higher than 1 will disable the use of ACME certs.

Sizing guidelines

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.

Warning

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

Manually configuring NFS-based storage or ReadWriteMany volume claims is NOT supported for an HA deployment and will result in errors.

highAvailability:
  replicaCount: 3

``code $ --set highAvailability.replicaCount=3

</TabItem>
</Tabs>

## `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.

<Admonition type="warning">
This can result in Teleport pods failing to be scheduled in very small clusters or during node downtime, so should be used with caution.
</Admonition>

Setting `highAvailability.requireAntiAffinity` to `false` (the default) uses `preferredDuringSchedulingIgnoredDuringExecution` to make node
anti-affinity a soft requirement.

<Admonition type="note">
This setting only has any effect when `highAvailability.replicaCount` is greater than `1`.
</Admonition>

<Tabs>
<TabItem label="values.yaml">
```yaml
highAvailability:
  requireAntiAffinity: true
--set highAvailability.requireAntiAffinity=true

highAvailability.podDisruptionBudget

highAvailability.podDisruptionBudget.enabled

TypeDefault valueCan be used in custom mode?
boolfalse✅ (when using HA storage)

Kubernetes reference

Enable a Pod Disruption Budget for the Teleport Pod to ensure HA during voluntary disruptions.

highAvailability:
  podDisruptionBudget:
    enabled: true
--set highAvailability.podDisruptionBudget.enabled=true

highAvailability.podDisruptionBudget.minAvailable

TypeDefault valueCan be used in custom mode?
int1✅ (when using HA storage)

Kubernetes reference

Ensures that this number of replicas is available during voluntary disruptions, can be a number of replicas or a percentage.

highAvailability:
  podDisruptionBudget:
    minAvailable: 1
--set highAvailability.podDisruptionBudget.minAvailable=1

highAvailability.certManager

See the cert-manager docs for more information.

highAvailability.certManager.enabled

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
boolfalseproxy_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.

Installing cert-manager

You must install and configure cert-manager in your Kubernetes cluster yourself.

See the cert-manager Helm install instructions and the relevant sections of the AWS and GCP guides for more information.

highAvailability.certManager.issuerName

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
stringnilNone

Sets the name of the cert-manager Issuer or ClusterIssuer to use for issuing certificates.

Configuring an Issuer

You must install configure an appropriate Issuer supporting a DNS01 challenge yourself.

Please see the cert-manager DNS01 docs and the relevant sections of the AWS and GCP guides for more information.

highAvailability:
  certManager:
    enabled: true
    issuerName: letsencrypt-production
--set highAvailability.certManager.enabled=true \--set highAvailability.certManager.issuerName=letsencrypt-production

highAvailability.certManager.issuerKind

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
stringIssuerNone

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.

highAvailability:
  certManager:
    issuerKind: ClusterIssuer

--set highAvailability.certManager.issuerKind=ClusterIssuer

image

TypeDefault valueCan be used in custom mode?
stringquay.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.

image: my.docker.registry/teleport-community-image-name

--set image=my.docker.registry/teleport-community-image-name

enterpriseImage

TypeDefault valueCan be used in custom mode?
stringquay.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.

enterpriseImage: my.docker.registry/teleport-enterprise-image-name

--set enterpriseImage=my.docker.registry/teleport-enterprise-image

log

log.level

Note

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.

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
stringINFOteleport.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.

log:
  level: DEBUG

--set log.level=DEBUG

log.output

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
stringstderrteleport.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.

log:
  output: stderr

--set log.output=stderr

log.format

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
stringtextteleport.log.format.output

log.format sets the output type for the Teleport process.

Possible values are text (default) or json.

log:
  format: json

--set log.format=json

log.extraFields

TypeDefault valueCan 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 for more details on possible values for extra_fields.

log:
  extraFields: ["timestamp", "level"]

--set "log.extraFields[0]=timestamp" \

--set "log.extraFields[1]=level"

affinity

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Kubernetes affinity to set for pod assignments.

Note

You cannot set both affinity and highAvailability.requireAntiAffinity as they conflict with each other. Only set one or the other.

affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: gravitational.io/dedicated
          operator: In
          values:
          - teleport
--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

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
object{}None

Kubernetes reference

Kubernetes annotations which should be applied to the ConfigMap created by the chart.

Note

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.

annotations:
  config:
    kubernetes.io/annotation: value
--set annotations.config."kubernetes\.io\/annotation"=value
Escaping values

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

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Kubernetes annotations which should be applied to the Deployment created by the chart.

annotations:
  deployment:
    kubernetes.io/annotation: value
--set annotations.deployment."kubernetes\.io\/annotation"=value
Escaping values

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

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Kubernetes annotations which should be applied to each Pod created by the chart.

annotations:
  pod:
    kubernetes.io/annotation: value
--set annotations.pod."kubernetes\.io\/annotation"=value
Escaping values

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

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Kubernetes annotations which should be applied to the Service created by the chart.

annotations:
  service:
    kubernetes.io/annotation: value
--set annotations.service."kubernetes\.io\/annotation"=value
Escaping values

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

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Kubernetes annotations which should be applied to the serviceAccount created by the chart.

annotations:
  serviceAccount:
    kubernetes.io/annotation: value
--set annotations.serviceAccount."kubernetes\.io\/annotation"=value
Escaping values

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

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

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+.

annotations:
  certSecret:
    kubernetes.io/annotation: value
--set annotations.certSecret."kubernetes\.io\/annotation"=value
Escaping values

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

TypeDefault valueRequired?Can be used in custom mode?
stringLoadBalancerYes

Kubernetes reference

Allows to specify the service type.

service:
  type: LoadBalancer
--set service.type=LoadBalancer

service.spec.loadBalancerIP

TypeDefault valueRequired?Can be used in custom mode?
stringnilNo

Kubernetes reference

Allows to specify the loadBalancerIP.

service:
  spec:
    loadBalancerIP: 1.2.3.4
--set service.spec.loadBalancerIP=1.2.3.4

extraArgs

TypeDefault valueCan be used in custom mode?
list[]

A list of extra arguments to pass to the teleport start command when running a Teleport Pod.

extraArgs:
- "--bootstrap=/etc/teleport-bootstrap/roles.yaml"
--set "extraArgs={--bootstrap=/etc/teleport-bootstrap/roles.yaml}"

extraEnv

TypeDefault valueCan be used in custom mode?
list[]

Kubernetes reference

A list of extra environment variables to be set on the main Teleport container.

extraEnv:
- name: MY_ENV
  value: my-value
--set "extraEnv[0].name=MY_ENV" \--set "extraEnv[0].value=my-value"

extraVolumes

TypeDefault valueCan be used in custom mode?
list[]

Kubernetes reference

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.

extraVolumes:
- name: myvolume
  secret:
    secretName: mysecret
--set "extraVolumes[0].name=myvolume" \--set "extraVolumes[0].secret.secretName=mysecret"

extraVolumeMounts

TypeDefault valueCan be used in custom mode?
list[]

Kubernetes reference

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.

extraVolumeMounts:
- name: myvolume
  mountPath: /path/to/mount/volume
--set "extraVolumeMounts[0].name=myvolume" \--set "extraVolumeMounts[0].path=/path/to/mount/volume"

imagePullPolicy

TypeDefault valueCan be used in custom mode?
stringIfNotPresent

Kubernetes reference

Allows the imagePullPolicy for any pods created by the chart to be overridden.

imagePullPolicy: Always
--set imagePullPolicy=Always

initContainers

TypeDefault valueCan be used in custom mode?
list[]

Kubernetes reference

A list of initContainers which will be run before the main Teleport container in any pod created by the chart.

initContainers:
- name: teleport-init
  image: alpine
  args: ['echo test']
--set "initContainers[0].name=teleport-init" \--set "initContainers[0].image=alpine" \--set "initContainers[0].args={echo test}"

postStart

Kubernetes reference

A postStart lifecycle handler to be configured on the main Teleport container.

postStart:
  command:
  - echo
  - foo
--set "postStart.command[0]=echo" \
--set "postStart.command[1]=foo"

resources

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Resource requests/limits which should be configured for each container inside the pod. These resource limits will also be applied to initContainers.

resources:
  requests:
    cpu: 1
    memory: 2Gi
--set resources.requests.cpu=1 \--set resources.requests.memory=2Gi

tolerations

TypeDefault valueCan be used in custom mode?
list[]

Kubernetes reference

Kubernetes Tolerations to set for pod assignment.

tolerations:
- key: "dedicated"
  operator: "Equal"
  value: "teleport"
  effect: "NoSchedule"
--set tolerations[0].key=dedicated \--set tolerations[0].operator=Equal \--set tolerations[0].value=teleport \--set tolerations[0].effect=NoSchedule

priorityClassName

TypeDefault valueCan be used in custom mode?
string""

Kubernetes reference

Kubernetes PriorityClass to set for pod.

priorityClassName: "system-cluster-critical"
--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 serviceName for roles and tctl tokens addPurpose
kubernetes_servicekubeUses Teleport to handle authentication with and proxy access to a Kubernetes cluster
application_serviceappUses Teleport to handle authentication with and proxy access to web-based applications
database_servicedbUses 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.

TypeDefault value
stringkube

roles is a comma-separated list of services which should be enabled when running the teleport-kube-agent chart.

ServicesValue for rolesMandatory additional settings for this role
Teleport Kubernetes servicekubekubeClusterName
Teleport Application serviceappapps
Teleport Database servicedbdatabases
roles: kube,app,db
--set roles=kube\,app\,db
Note

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

TypeDefault valueRequired?
stringnilYes

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:

ServicesService Nametctl tokens add exampleteleport.yaml static token example
Kuberneteskubetctl tokens add --type=kube"kube:<replace-with-actual-token>"
Kubernetes, Applicationkube,apptctl tokens add --type=kube,app"kube,app:<replace-with-actual-token>"
Kubernetes, Application, Databasekube,app,dbtctl tokens add --type=kube,app,db"kube,app,db:<replace-with-actual-token>"
Note

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.

authToken: <replace-with-actual-token>
--set authToken=<replace-with-actual-token>

proxyAddr

TypeDefault valueRequired?
stringnilYes

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 methodExample proxy_service.public_addr
On-prem Teleport clusterteleport.example.com:3080
Teleport Cloud clusterexample.teleport.sh:443
teleport-cluster Helm chartteleport.example.com:443

kubeClusterName

TypeDefault valueRequired?
stringnilWhen 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.

kubeClusterName: my-gke-cluster
--set kubeClusterName=my-gke-cluster

apps

TypeDefault valueRequired?
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.

apps:
- name: grafana
  uri: http://localhost:3000
  labels:
    purpose: monitoring
- name: jenkins
  uri: http://jenkins:8080
  labels:
    purpose: ci
YAML formatting

YAML is very sensitive to correct spacing. When specifying lists in a values.yaml file, you might like to use a linter to validate your YAML list and ensure that it is correctly formatted.

--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

Note that when using --set syntax, YAML list elements must be indexed starting at 0.

Supported values

databases

TypeDefault valueRequired?
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.

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 formatting

YAML is very sensitive to correct spacing. When specifying lists in a values.yaml file, you might like to use a linter to validate your YAML list and ensure that it is correctly formatted.

--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

Note that when using --set syntax, YAML list elements must be indexed starting at 0.

Supported values

teleportVersionOverride

TypeDefault value
stringnil

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.

Note

The teleport-kube-agent chart always runs using Teleport Community edition as it does not require any Enterprise features, so it does not require a Teleport license file to be provided.

teleportVersionOverride: "7"
--set teleportVersionOverride="7"

insecureSkipProxyTLSVerify

TypeDefault value
boolfalse

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.

This can be used for joining a Teleport agent to a Teleport cluster which does not have valid TLS certificates for testing.

insecureSkipProxyTLSVerify: false
--set insecureSkipProxyTLSVerify=false
Warning

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 enable cert-manager support.

existingDataVolume

TypeDefault 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.

existingDataVolume: my-volume
--set existingDataVolume=my-volume

podSecurityPolicy

podSecurityPolicy.enabled

TypeDefault value
booltrue

By default, Teleport charts also install a podSecurityPolicy.

To disable this, you can set enabled to false.

Kubernetes reference

podSecurityPolicy:
  enabled: false
--set podSecurityPolicy.enabled=false

labels

TypeDefault 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.

Note

These are Teleport-specific RBAC labels, not Kubernetes labels.

Note

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 section. To set labels for databases, add a static_labels element to the databases section.

For more information on how to set static/dynamic labels for Teleport services, see labelling nodes and applications.

labels:
  environment: production
  region: us-east
--set labels.environment=production \--set labels.region=us-east

storage

storage.enabled

TypeDefault value
boolfalse

Enables the creation of a Kubernetes persistent volume to hold Teleport agent state.

Kubernetes reference

storage:
  enabled: true
--set storage.enabled=true

storage.storageClassName

TypeDefault value
stringnil

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

storage:
  storageClassName: teleport-storage-class
--set storage.storageClassName=teleport-storage-class

storage.requests

TypeDefault value
string128Mi

The size of persistent volume to create.

storage:
  requests: 128Mi
--set storage.requests=128Mi

image

TypeDefault value
stringquay.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.

image: my.docker.registry/teleport-image-name
--set image=my.docker.registry/teleport-image-name

imagePullSecrets

TypeDefault valueCan be used in custom mode?
list[]

Kubernetes reference

A list of secrets containing authorization tokens which can be optionally used to access a private Docker registry.

imagePullSecrets:
- name: my-docker-registry-key
--set "imagePullSecrets[0].name=my-docker-registry-key"

replicaCount

TypeDefault value
int1

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 to provide some redundancy.

Warning

Simply setting replicaCount to a value higher than 1 is not a panacea for getting a highly available Teleport agent deployment.

Teleport does not yet ensure that requests to Teleport agents are guaranteed to always only be routed to active, healthy agents, so you may still find that you get sporadic request errors during pod outages when requests are routed to offline pods.

replicaCount: 3
--set replicaCount=3

clusterRoleName

TypeDefault value
stringnil

clusterRoleName can be optionally used to override the name of the Kubernetes ClusterRole used by the teleport-kube-agent chart's ServiceAccount.

Note

Most users will not need to change this.

clusterRoleName: kubernetes-clusterrole
--set clusterRoleName=kubernetes-clusterrole

clusterRoleBindingName

Note

Most users will not need to change this.

TypeDefault value
stringnil

clusterRoleBindingName can be optionally used to override the name of the Kubernetes ClusterRoleBinding used by the teleport-kube-agent chart's ServiceAccount.

clusterRoleBindingName: kubernetes-clusterrolebinding
--set clusterRoleBindingName=kubernetes-clusterrolebinding

serviceAccountName

Note

Most users will not need to change this.

TypeDefault value
stringnil

serviceAccountName can be optionally used to override the name of the Kubernetes ServiceAccount used by the teleport-kube-agent chart.

serviceAccountName: kubernetes-serviceaccount
--set serviceAccountName=kubernetes-serviceaccount

secretName

TypeDefault value
stringteleport-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:

kubectl --namespace teleport create secret generic teleport-kube-agent-join-token --from-literal=auth-token=<replace-with-actual-token>
Note

The key used for the auth token inside the secret must be auth-token, as in the command above.

serviceAccountName:
--set serviceAccountName=""

log

log.level

Note

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.

TypeDefault value
stringINFO

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.

log:
  level: DEBUG

--set log.level=DEBUG

log.output

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
stringstderrteleport.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.

log:
  output: stderr

--set log.output=stderr

log.format

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
stringtextteleport.log.format.output

log.format sets the output type for the Teleport process.

Possible values are text (default) or json.

log:
  format: json

--set log.format=json

log.extraFields

TypeDefault valueCan 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 for more details on possible values for extra_fields.

log:
  extraFields: ["timestamp", "level"]

--set "log.extraFields[0]=timestamp" \

--set "log.extraFields[1]=level"

affinity

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Kubernetes affinity to set for pod assignments.

Note

You cannot set both affinity and highAvailability.requireAntiAffinity as they conflict with each other.

affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: gravitational.io/dedicated
          operator: In
          values:
          - teleport
--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

TypeDefault 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

nodeSelector:
  role: node
  region: us-east
--set nodeSelector.role=node \
--set nodeSelector.region=us-east

annotations.config

TypeDefault valueCan be used in custom mode?teleport.yaml equivalent
object{}None

Kubernetes reference

Kubernetes annotations which should be applied to the ConfigMap created by the chart.

Note

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.

annotations:
  config:
    kubernetes.io/annotation: value
--set annotations.config."kubernetes\.io\/annotation"=value
Escaping values

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

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Kubernetes annotations which should be applied to the Deployment created by the chart.

annotations:
  deployment:
    kubernetes.io/annotation: value
--set annotations.deployment."kubernetes\.io\/annotation"=value
Escaping values

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

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Kubernetes annotations which should be applied to each Pod created by the chart.

annotations:
  pod:
    kubernetes.io/annotation: value
--set annotations.pod."kubernetes\.io\/annotation"=value
Escaping values

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

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Kubernetes annotations which should be applied to the ServiceAccount created by the chart.

annotations:
  serviceAccount:
    kubernetes.io/annotation: value
--set annotations.serviceAccount."kubernetes\.io\/annotation"=value
Escaping values

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

TypeDefault valueCan be used in custom mode?
list[]

Kubernetes reference

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.

extraVolumes:
- name: myvolume
  secret:
    secretName: mysecret
--set "extraVolumes[0].name=myvolume" \--set "extraVolumes[0].secret.secretName=mysecret"

extraVolumeMounts

TypeDefault valueCan be used in custom mode?
list[]

Kubernetes reference

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.

extraVolumeMounts:
- name: myvolume
  mountPath: /path/to/mount/volume
--set "extraVolumeMounts[0].name=myvolume" \--set "extraVolumeMounts[0].path=/path/to/mount/volume"

imagePullPolicy

TypeDefault valueCan be used in custom mode?
stringIfNotPresent

Kubernetes reference

Allows the imagePullPolicy for any pods created by the chart to be overridden.

imagePullPolicy: Always
--set imagePullPolicy=Always

initContainers

TypeDefault valueCan be used in custom mode?
list[]

Kubernetes reference

A list of initContainers which will be run before the main Teleport container in any pod created by the chart.

initContainers:
- name: teleport-init
  image: alpine
  args: ['echo test']
--set "initContainers[0].name=teleport-init" \--set "initContainers[0].image=alpine" \--set "initContainers[0].args={echo test}"

resources

TypeDefault valueCan be used in custom mode?
object{}

Kubernetes reference

Resource requests/limits which should be configured for each container inside the pod. These resource limits will also be applied to initContainers.

resources:
  requests:
    cpu: 1
    memory: 2Gi
--set resources.requests.cpu=1 \--set resources.requests.memory=2Gi

tolerations

TypeDefault valueCan be used in custom mode?
list[]

Kubernetes reference

Kubernetes Tolerations to set for pod assignment.

tolerations:
- key: "dedicated"
  operator: "Equal"
  value: "teleport"
  effect: "NoSchedule"
--set tolerations[0].key=dedicated \--set tolerations[0].operator=Equal \--set tolerations[0].value=teleport \--set tolerations[0].effect=NoSchedule
Have a suggestion or can’t find something?
IMPROVE THE DOCS