Fork me on GitHub

Teleport

teleport-kube-agent Chart Reference

Improve

The teleport-kube-agent Helm chart is used to configure a Teleport agent that runs in a remote Kubernetes cluster to provide access to resources in your infrastructure.

You can browse the source on GitHub.

This reference details available values for the teleport-kube-agent chart.

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.

What the chart deploys

Teleport services

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

Legacy releases

Releases of this chart installed before version 11 are considered legacy releases, which launch the Teleport pod as a Deployment if no storage was configured.

In version 11 and above, the chart launches the Teleport pod as a StatefulSet even when the chart is configured not to use external storage, and the Teleport pod reads its state from a Kubernetes Secret.

While the Teleport pod does not require external storage, you can still use the storage.enabled field to configure the way the Teleport pod reads data from a persistent volume.

To learn how upgrading from a legacy release to version 11 will affect resources launched by this chart, see the resource list.

Kubernetes resources

The teleport-kube-agent chart deploys the following Kubernetes resources:

KindDefault NameDescriptionWhen Deployed
StatefulSetThe release nameRunning a user-configured Teleport pod.Always.
SecretsecretName (default: teleport-kube-agent-join-token)Used for managing the state of the Teleport pod.authToken or joinParams.tokenName is provided.
DeploymentThe release nameRuns a user-configured Teleport pod.storage.enabled is false and the chart is being upgraded. Fresh installs will deploy a StatefulSet instead.
RoleThe roleName option, if given, or the release name.Used to manage the state of the Teleport pod via Kubernetes secrets.Always.
ClusterRoleclusterRoleName, if given, or the release name.Allows impersonating users, groups, and service accounts, getting pods, and creating SelfSubjectAccessReviews so the Teleport pod can manage access to resources in its Kubernetes cluster.Always.
ClusterRoleBindingclusterRoleBindingName, if provided, or the release nameEnables the Teleport pod to manage access to resources in the Kubernetes cluster.Always.
RoleBindingroleBindingName, if given, or the release nameEnables the Teleport pod to manage access to resources in the Kubernetes cluster.Always.
ServiceAccountserviceAccount.name, if given, or the release nameEnables the Teleport pod to manage access to resources in the Kubernetes cluster.serviceAccount.create is true
PodDisruptionBudgetThe release nameEnsure high availability for the Teleport pod.highAvailability.podDisruptionBudget.enabled is true.
ServiceAccountThe release name, suffixed by -hookUsed to delete legacy Deployments in order to deploy a StatefulSet instead. Removed once the upgrade is complete.If the teleport-kube-agent release contains a legacy Deployment resource.
RoleThe release name, suffixed by -hookUsed to delete legacy Deployments in order to deploy a StatefulSet instead. Removed once the upgrade is complete.If the teleport-kube-agent release contains a legacy Deployment resource.
RoleBindingThe release name, suffixed by -hookUsed to delete legacy Deployments in order to deploy a StatefulSet instead. Removed once the upgrade is complete.If the teleport-kube-agent release contains a legacy Deployment resource.
JobThe release name, suffixed by -hookUsed to delete legacy Deployments in order to deploy a StatefulSet instead. Removed once the upgrade is complete.If the teleport-kube-agent release contains a legacy Deployment resource.
ConfigMapThe release nameContains the configuration for the Teleport pod.Always.
PodSecurityPolicyThe release nameEnforces security requirements for pods deployed by teleport-kube-agent.podSecurityPolicy.enabled is true and the Kubernetes cluster supports pod security policies.
RoleThe release name, suffixed by -pspEnforces security requirements for pods deployed by teleport-kube-agent.podSecurityPolicy.enabled is true and the Kubernetes cluster supports pod security policies.
RoleBindingThe release name, suffixed by -pspEnforces security requirements for pods deployed by teleport-kube-agent.podSecurityPolicy.enabled is true and the Kubernetes cluster supports pod security policies.

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.

roleBindingName

TypeDefault valueRequired?
string""No

roleBindingName provides a custom name for the RoleBinding resource that the teleport-kube-agent chart creates for the Teleport pod. By default, the RoleBinding has the name of the Helm release.

You should set this value if there is a RoleBinding resource in the namespace of your teleport-kube-agent resources with the same name as your teleport-kube-agent release.

roleBindingName: myrolebinding
--set roleBindingName=myrolebinding

roleName

TypeDefault valueRequired?
string""No

roleName provides a custom name for the Role resource that the teleport-kube-agent chart creates for the Teleport pod. By default, the Role has the name of the Helm release.

You should set this value if there is a Role resource in the namespace of your teleport-kube-agent resources with the same name as your teleport-kube-agent release.

roleName: myrole 
--set roleName=myrole

serviceAccountName

This field is deprecated and will be removed in a future version. Use serviceAccount.name instead.

authToken

TypeDefault valueRequired?
stringnilNo

authToken provides a Teleport join token which will be used to join the Teleport instance to a Teleport cluster.

The value joinParams supports more methods to join the Teleport cluster and takes precedence if both authToken and joinParams are set.

A token must be specified for the agent to join the Teleport cluster, either though authToken, joinParams, or an existing Kubernetes Secret.

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 instance will fail to join the Teleport cluster.

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

joinParams

joinParams controls how the Teleport agent joins the Teleport cluster. These sub-values must be configured for the agent to connect to a cluster.

joinParams.method

TypeDefault valueRequired?
stringtokenYes

joinParams.method defines which join method will be used to join the Teleport cluster. Possible values are token, iam and ec2.

IAM joining requirements

Using the IAM joining method requires either the pods to have access to instance metadata, or IAM roles for service accounts to be set up on the pods's service account. For access to instance metadata (the quickest solution), see AWS's examples on how to restrict instance metadata access to a few pods.

joinParams:
  method: "token"|"ec2"|"iam"
--set joinParams.method="token"|"ec2"|"iam"

joinParams.tokenName

TypeDefault valueRequired?
stringnilYes

When joinParams.method is iam or ec2, joinParams.tokenName contains the name of the token that will be used to join the cluster. In this case, the value is not sensitive as authorization is checked through AWS IAM or EC2.

When joinParams.method is token (by default), joinParams.tokenName contains the join token itself. In this case, the value is sensitive and is automatically stored in a Kubernetes Secret instead of being directly included in the agent's configuration.

If method is token, joinParams.tokenName can be empty if the token is provided through an existing Kubernetes Secret, see secretName for more details and instructions.

joinParams:
  tokenName: "my-token"
--set joinParams.token="my-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 at least one of apps and appResources is required.

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 find it helpful 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

appResources

TypeDefault valueRequired?
list[]When app chart role is used at least one of apps and appResources is required.

appResources is a YAML list object detailing the resource selectors of the applications that should be proxied by Teleport Application Access.

You can specify multiple selectors by including additional list elements.

appResources:
- labels:
    "env": "prod"
- labels:
    "env": "test"
--set "appResources[0].labels.env=prod" \--set "appResources[1].labels.env=test"
Note

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

Example

Once appResources is set, you can dynamically register application with tsh by following this guide.

awsDatabases

AWS database auto-discovery

This section configures AWS database auto-discovery. You can configure databases for other platforms using the azureDatabases or databases sections.

IAM roles

For AWS database auto-discovery to work, your Database Service pods will need to use a role which has appropriate IAM permissions as per the database documentation.

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
TypeDefault valueRequired?
list[]When the db chart role is used at least one of databases, awsDatabases,
azureDatabases, databaseResources is required.

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.
roles: db
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:
      "*": "*"
annotations:
  serviceAccount:
    eks.amazonaws.com/role-arn: arn:aws:iam::1234567890:role/my-rds-autodiscovery-role
YAML formatting

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

azureDatabases

Azure database auto-discovery

This section configures Azure database auto-discovery. You can configure databases for other platforms using the awsDatabases or databases sections.

Azure IAM

For Azure database auto-discovery to work, your Database Service pods will need to have appropriate IAM permissions as per the database documentation.

After configuring a service principal with appropriate IAM permissions, you must pass credentials to the pods. The easiest way is to use an Azure client secret.

First, create in the chart installation namespace a Kubernetes Secret containing the azure client secret:

kubectl create secret generic teleport-azure-client-secret --from-literal=client_secret=<your-azure-client-secret>

secret/teleport-azure-client-secret created

Then, use the extraEnv value to set the pods environment variables:

extraEnv:
- name: AZURE_CLIENT_SECRET
  valueFrom:
    secretKeyRef:
    name: teleport-azure-client-secret
    key: client_secret
    optional: false
- name: AZURE_TENANT_ID
  value: "11111111-2222-3333-4444-555555555555"
- name: AZURE_CLIENT_ID
  value: "11111111-2222-3333-4444-555555555555"
TypeDefault valueRequired?
list[]When the db chart role is used at least one of databases, awsDatabases,
azureDatabases, databaseResources is required.

azureDatabases is a YAML list object detailing the filters for the Azure databases that should be discovered and proxied by Teleport Database access.

You can specify multiple database filters by adding additional list elements.

Required fields for each filter:

  • types is a list containing the types of Azure databases that should be discovered.
  • tags can be used to set Azure resource tags that must be matched for databases to be discovered.

Optional fields for each filter:

  • regions is a list of Azure regions which should be scanned for databases.
  • subscriptions can be used to discover databases within matching Azure subscriptions.
  • resource_groups can be used to discover databases within matching Azure resource groups.

The default for each of these optional settings is *, which will auto-discover in all subscriptions, regions, or resource groups accessible by the Teleport service principal in Azure.

roles: db
azureDatabases:
- types: ["mysql", "postgres"]
  tags:
    "*": "*"
- types: ["mysql"]
  tags:
    "env": ["dev", "staging"]
    "origin": "alice"
  regions: ["eastus", "centralus"]
  subscriptions: ["subID1", "subID2"]
  resource_groups: ["group1", "group2"]
extraEnv:
- name: AZURE_CLIENT_SECRET
  valueFrom:
    secretKeyRef:
    name: teleport-azure-client-secret
    key: client_secret
    optional: false
- name: AZURE_TENANT_ID
  value: "11111111-2222-3333-4444-555555555555"
- name: AZURE_CLIENT_ID
  value: "11111111-2222-3333-4444-555555555555"
YAML formatting

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

databases

TypeDefault valueRequired?
list[]When the db chart role is used at least one of databases, awsDatabases,
azureDatabases, databaseResources is required.

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 find it helpful 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
Trusting Database CA

Database CAs can be trusted on a per-database basis. You must create a secret containing the database CA certificate in the same namespace as Teleport using a command like:

kubectl create secret generic my-postgres-ca --from-file=ca.pem=/path/to/database-ca.pem

Then, deploy the Helm chart with the following values:

databases:
- name: my-postgres
  uri: postgres.example.com:5432
  protocol: postgres
  tls:
    ca_cert_file: "/etc/teleport-tls-db/my-postgres/ca.pem"
extraVolumes:
  - name: my-postgres-ca
    secret:
      secretName: my-postgres-ca
extraVolumeMounts:
  - name: my-postgres-ca
    mountPath: /etc/teleport-tls-db/my-postgres
    readOnly: true

databaseResources

TypeDefault valueRequired?
list[]When the db chart role is used at least one of databases, awsDatabases,
azureDatabases, databaseResources is required.

databaseResources is a YAML list object detailing the resource selectors of the databases that should be proxied by Teleport Database Access.

You can specify multiple selectors by adding elements to the list.

databaseResources:
- labels:
    "env": "prod"
    "engine": "postgres"
- labels:
    "env": "test"
    "engine": "mysql"

--set "databaseResources[0].labels.env=prod" \

--set "databaseResources[0].labels.engine=postgres" \

--set "databaseResources[1].labels.env=test" \

--set "databaseResources[0].labels.engine=mysql"

Note

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

Example

Once databaseResources is set, you can dynamically register database with tsh by following this guide.

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"

caPin

TypeDefault value
list[]

When caPin is set, the Teleport pod will use its values to check the Auth Service's identity when first joining a cluster. This enables a more secure way of adding new Teleport instances to a cluster. See "Adding Nodes to the Cluster".

Each list element can be the pin itself (recommended, works out of the box), or a path to a file containing the pin. For the latter it is your responsibility to mount the file using extraVolumes.

caPin: ["sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1"]
--set caPin[0]="sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1"

insecureSkipProxyTLSVerify

TypeDefault value
boolfalse

When insecureSkipProxyTLSVerify is set to true, the Teleport instance will skip the verification of the TLS certificate presented by the Teleport Proxy Service specified using proxyAddr.

This can be used for joining a Teleport instance 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 or enable cert-manager support.

teleportConfig

teleportConfig contains YAML teleport configuration to pass to the Teleport pods. The configuration will be merged with the chart-generated configuration and will take precedence in case of conflict.

See the Teleport Configuration Reference for the list of supported fields.

teleportConfig:
  app_service:
    debug_app: true
  discovery_service:
    enabled: true
    azure:
    - types: ["aks"]
      tags:
        "*":"*"

tls

existingCASecretName

TypeDefault value
string""

tls.existingCASecretName sets the SSL_CERT_FILE environment variable to load a trusted CA or bundle in PEM format into Teleport pods. This can be set to inject a root and/or intermediate CA so that Teleport can build a full trust chain on startup. The injected CA will be used to validate TLS communications, with the Proxy Service, with upstream applications or databases.

Note

The recommended way to trust a database CA is to do it per-database instead of adding the CA to the global Teleport trust store. It allows to trust multiple CAs while limiting the trust scope to their specific databases. See the databases section.

You must create a secret containing the CA certs in the same namespace as Teleport using a command like:

kubectl create secret generic my-root-ca --from-file=ca.pem=/path/to/root-ca.pem

The key containing the root CA in the secret must be ca.pem.

tls:
  existingCASecretName: my-root-ca
--set tls.existingSecretName=my-root-ca

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 instance state.

Kubernetes reference

Chart upgrades for legacy releases

If you are upgrading a legacy teleport-kube-agent release (pre-v11), the way the teleport-kube-agent chart handles upgrades differs depending on the value of storage.enabled. Prior to v11, the chart ran the Teleport pod as a Deployment if storage.enabled was false and a StatefulSet if it was true. In v11 and after, the chart always runs the Teleport pod as a StatefulSet.

During an upgrade, if storage.enabled is false, the chart installs a StatefulSet resource to run the Teleport pod alongside the existing Deployment. Once the StatefulSet joins the cluster and becomes healthy, the chart deletes the Deployment using a Helm hook, and the upgrade finishes.

If storage.enabled is true, then during the upgrade, the teleport-kube-agent chart will use the existing StatefulSet resource to run the Teleport pod. The chart will import the pod's identify from the previously configured external storage into a Kubernetes Secret.

New chart installations

New installations of teleport-kube-agent always launch the Teleport pod as a StatefulSet, and the pod reads its state from a Kubernetes Secret. Setting storage.enabled to true is not required for the Teleport pod to maintain its state.

If storage.enabled is true, the chart creates a volume mount for the Teleport pod that persists across the lifetimes of all Teleport pods deployed on a particular node. The Teleport pod uses this volume mount to manage its data, which is useful for storing session recordings locally.

You can configure this persistent storage using storage.storageClassName and storage.requests.

If storage.enabled is false, the chart configures the Teleport pod to manage its data with a temporary directory that exists until the Teleport pod stops running.

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
stringpublic.ecr.aws/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"

highAvailability

highAvailability.replicaCount

TypeDefault value
int1

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.

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.

highAvailability:
  replicaCount: 3
--set highAvailability.replicaCount=3

highAvailability.requireAntiAffinity

TypeDefault value
boolfalse

Kubernetes reference

Setting highAvailability.requireAntiAffinity to true will use requiredDuringSchedulingIgnoredDuringExecution to require that multiple Teleport pods must not be scheduled on the same physical host.

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.

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

Note

This setting only has any effect when highAvailability.replicaCount is greater than 1.

highAvailability:
  requireAntiAffinity: true
--set highAvailability.requireAntiAffinity=true

highAvailability.podDisruptionBudget

highAvailability.podDisruptionBudget.enabled

TypeDefault value
boolfalse

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

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

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

priorityClassName

TypeDefault value
stringnil

priorityClassName allows to specify a priority class for the teleport-kube-agent deployment/statefulset.

priorityClassName: "teleport-kube-agent"
--set priorityClassName=teleport-kube-agent

serviceAccount.create

TypeDefault valueRequired?Can be used in custom mode?
booleantrueNo

Kubernetes reference

Boolean value to control whether Helm Chart should create the ServiceAccount. When off, the serviceAccount.name parameter should be set to the existing ServiceAccount name.

serviceAccount:
  create: false
  name: kubernetes-serviceaccount
--set serviceAccount.create=false
--set serviceAccount.name=kubernetes-serviceaccount

serviceAccount.name

TypeDefault valueRequired?Can be used in custom mode?
string""No

serviceAccount.name provides a custom name for the ServiceAccount resource that the teleport-kube-agent chart creates for the Teleport pod. By default, the ServiceAccount has the name of the Helm release.

You should set this value if there is a ServiceAccount resource in the namespace of your teleport-kube-agent resources with the same name as your teleport-kube-agent release.

serviceAccount:
  name: kubernetes-serviceaccount
--set serviceAccount.name=kubernetes-serviceaccount

secretName

TypeDefault value
stringteleport-kube-agent-join-token

secretName is the name of the Kubernetes Secret containing the Teleport join token used by the chart.

If joinParams.method is token and you set both authToken and joinParams.tokenName to a blank value, the chart will not attempt to create the secret itself. Instead, it will read the value from an existing secret. secretName configures the name of this 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.

secretName: "secret-i-created-before"
joinParams:
  method: "token"
  tokenName: ""
--set secretName="secret-i-created-before" \ --set joinParams.method="token" \ --set joinParams.tokenName=""

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

dnsConfig

TypeDefault value
object{}

Kubernetes reference

Kubernetes pod DNS configuration. This value can reduce the DNS load by setting ndots to 0.

dnsConfig:
  nameservers:
    - 1.2.3.4
  searches:
    - ns1.svc.cluster-domain.example
    - my.dns.search.suffix
  options:
    - name: ndots
      value: "2"

dnsPolicy

TypeDefault value
string""

Kubernetes reference

Kubernetes pod DNS policy.

dnsPolicy: "Default"

nodeSelector

TypeDefault value
object{}

nodeSelector can be used to add a map of key-value pairs to constrain the nodes that Teleport pods will run on.

Kubernetes reference

nodeSelector:
  role: node
  region: us-east

--set nodeSelector.role=node \

--set nodeSelector.region=us-east

extraLabels.clusterRole

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to the ClusterRole created by the chart.

extraLabels:
  clusterRole:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.clusterRole."app\.kubernetes\.io\/name"=teleport-kube-agent
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.

extraLabels.clusterRoleBinding

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to the ClusterRoleBinding created by the chart.

extraLabels:
  clusterRoleBinding:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.clusterRoleBinding."app\.kubernetes\.io\/name"=teleport-kube-agent
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.

extraLabels.role

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to the Role created by the chart for the Teleport pod.

extraLabels:
  role:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.role."app\.kubernetes\.io\/name"=teleport-kube-agent
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.

extraLabels.roleBinding

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to the RoleBinding created by the chart for the Teleport pod.

extraLabels:
  roleBinding:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.roleBinding."app\.kubernetes\.io\/name"=teleport-kube-agent
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.

extraLabels.config

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to the ConfigMap created by the chart.

extraLabels:
  config:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.config."app\.kubernetes\.io\/name"=teleport-kube-agent
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.

extraLabels.deployment

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to the Deployment or StatefulSet created by the chart.

extraLabels:
  deployment:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.deployment."app\.kubernetes\.io\/name"=teleport-kube-agent
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.

extraLabels.pod

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to every Pod in the Deployment or StatefulSet created by the chart.

extraLabels:
  pod:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.pod."app\.kubernetes\.io\/name"=teleport-kube-agent
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.

extraLabels.podDisruptionBudget

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to the PodDisruptionBudget created by the chart (if enabled).

extraLabels:
  podDisruptionBudget:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.podDisruptionBudget."app\.kubernetes\.io\/name"=teleport-kube-agent
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.

extraLabels.podSecurityPolicy

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to the PodSecurityPolicy created by the chart (if enabled).

extraLabels:
  podSecurityPolicy:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.podSecurityPolicy."app\.kubernetes\.io\/name"=teleport-kube-agent
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.

extraLabels.secret

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to the Secret created by the chart (if enabled).

extraLabels:
  secret:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.secret."app\.kubernetes\.io\/name"=teleport-kube-agent
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.

extraLabels.serviceAccount

TypeDefault value
object{}

Kubernetes reference

Kubernetes labels that should be applied to the ServiceAccount created by the chart for the Teleport pod.

extraLabels:
  serviceAccount:
    app.kubernetes.io/name: teleport-kube-agent
--set extraLabels.serviceAccount."app\.kubernetes\.io\/name"=teleport-kube-agent
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.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"

extraArgs

TypeDefault value
list[]

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

extraArgs:
- "--debug"
--set "extraArgs={--debug}"

extraEnv

TypeDefault value
list[]

Kubernetes reference

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

extraEnv:
- name: HTTPS_PROXY
  value: "http://username:[email protected]:3128"
--set "extraEnv[0].name=HTTPS_PROXY" \--set "extraEnv[0].value=\"http://username:[email protected]:3128\""

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

probeTimeoutSeconds

TypeDefault value
integer1

Kubernetes reference

Kubernetes timeouts for the liveness and readiness probes.

probeTimeoutSeconds: 5
--set probeTimeoutSeconds=5