Skip to content

Latest commit

 

History

History
1844 lines (1307 loc) · 68 KB

teleport-kube-agent.mdx

File metadata and controls

1844 lines (1307 loc) · 68 KB
title description
teleport-kube-agent Chart Reference
Values that can be set using the teleport-kube-agent Helm chart

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.

(!docs/pages/includes/backup-warning.mdx!)

What the chart deploys

Teleport services

The teleport-kube-agent chart can run any or all of three Teleport services:

Teleport service Name for roles and tctl tokens add Purpose
kubernetes_service kube Uses Teleport to handle authentication
with and proxy access to a Kubernetes cluster
application_service app Uses Teleport to handle authentication
with and proxy access to web-based applications
database_service db Uses 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:

Kind Default Name Description When Deployed
StatefulSet The release name Running a user-configured Teleport pod. Always.
Secret joinTokenSecret.name (default: teleport-kube-agent-join-token) Used for managing the state of the Teleport pod. joinTokenSecret.secret is true.
Deployment The release name Runs a user-configured Teleport pod. storage.enabled is false and the chart is being upgraded. Fresh installs will deploy a StatefulSet instead.
Role The roleName option, if given, or the release name. Used to manage the state of the Teleport pod via Kubernetes secrets. Always.
ClusterRole clusterRoleName, 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.
ClusterRoleBinding clusterRoleBindingName, if provided, or the release name Enables the Teleport pod to manage access to resources in the Kubernetes cluster. Always.
RoleBinding roleBindingName, if given, or the release name Enables the Teleport pod to manage access to resources in the Kubernetes cluster. Always.
ServiceAccount serviceAccount.name, if given, or the release name Enables the Teleport pod to manage access to resources in the Kubernetes cluster. serviceAccount.create is true
PodDisruptionBudget The release name Ensure high availability for the Teleport pod. highAvailability.podDisruptionBudget.enabled is true.
ServiceAccount The release name, suffixed by -hook Used 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.
Role The release name, suffixed by -hook Used 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.
RoleBinding The release name, suffixed by -hook Used 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.
Job The release name, suffixed by -hook Used 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.
ConfigMap The release name Contains the configuration for the Teleport pod. Always.
PodSecurityPolicy The release name Enforces security requirements for pods deployed by teleport-kube-agent. podSecurityPolicy.enabled is true and the Kubernetes cluster version is < 1.23.
Role The release name, suffixed by -psp Enforces security requirements for pods deployed by teleport-kube-agent. podSecurityPolicy.enabled is true and the Kubernetes cluster version is < 1.23.
RoleBinding The release name, suffixed by -psp Enforces security requirements for pods deployed by teleport-kube-agent. podSecurityPolicy.enabled is true and the Kubernetes cluster version is < 1.23.

roles

This parameter is not mandatory to preserve backwards compatibility with older chart versions, but we recommend it is set.

Type Default value
string kube

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

Services Value for roles Mandatory additional settings for this role
Teleport Kubernetes service kube kubeClusterName
Teleport Application service app apps
Teleport Database service db databases

values.yaml example:

roles: kube,app,db

If you specify a role here, you may also need to specify some other settings which are detailed in this reference.

updater

updater controls whether the Kube Agent Updater should be deployed alongside the teleport-kube-agent. The updater fetches the target version, validates the image signature, and updates the teleport deployment.

All kubernetes-specific fields such as tolerations, affinity, nodeSelector, ... default to the agent values. However, they can be overridden from the updater object. For example:

# the agent pod requests 1cpu and 2 GiB of memory. It also has a memory limit.
resources:
  requests:
    cpu: "1"
    memory: "2Gi"
  limits:
    memory: "2Gi"

# the updater pod requests 0.5 cpu and 512MiB of memory. The memory limit has also been unset.
updater:
  resources:
    requests:
      cpu: "0.5"
      memory: "512Mi"
    limits: ~

Other updater-specific values that can be defined in updater are described below:

updater.enabled

Type Default value Required?
bool false No

Enables the Kube Agent Updater and deploys it alongside the Teleport Agent. You can enable this when:

  • using Teleport Cloud and your tenant is enrolled into automatic updates. (You can check this through the web UI, choose Add Kubernetes and Enroll New Resource of type Kubernetes, and check if the value is turned on.)
  • using self-hosted Teleport and you maintain your own version server.

You must not enable this if:

  • you are a Teleport Cloud customer not enrolled in automatic updates.
  • you are a self-hosted Teleport user and have not set up your Teleport cluster to support automatic updates.

updater.versionServer

Type Default value Required?
string "https://update.gravitational.io/v1/" Yes if not using Teleport Cloud

updater.versionServer is the URL of the version server the agent fetches the target version from. The complete version endpoint is built by concatenating versionServer and releaseChannel.

You must set this if the updater is enabled, and you are not a Teleport Cloud user.

You must not change the default values if you are a Teleport Cloud user.

updater.releaseChannel

Type Default value Required?
string "stable/cloud" No

updater.releaseChannel is the release channel the updater subscribes to. The complete version endpoint is built by concatenating versionServer and releaseChannel. You must not change the default value if you are a Teleport Cloud user unless instructed by Teleport support.

You can change this value if the updater is enabled, you are not a Teleport Cloud user, and manage your own version server.

updater.image

Type Default value Required?
string "public.ecr.aws/gravitational/teleport-kube-agent-updater" No

image sets the container image used for Teleport updater pods run when updater.enabled is true.

You can override this to use your own Teleport Kube Agent Updater image rather than a Teleport-published image.

roleBindingName

Type Default value Required?
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.

values.yaml example:

roleBindingName: myrolebinding

roleName

Type Default value Required?
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.

values.yaml example:

roleName: myrole

serviceAccountName

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

authToken

Type Default value Required?
string nil No

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.

Services Service Name tctl tokens add example teleport.yaml static token example
Kubernetes kube tctl tokens add --type=kube "kube:<replace-with-actual-token>"
Kubernetes, Application kube,app tctl tokens add --type=kube,app "kube,app:<replace-with-actual-token>"
Kubernetes, Application, Database kube,app,db tctl tokens add --type=kube,app,db "kube,app,db:<replace-with-actual-token>"
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.

values.yaml example:

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

Type Default value Required?
string token Yes

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

Using the IAM joining method requires either the pods to have access to [instance metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html), or [IAM roles for service accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) 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](https://aws.github.io/aws-eks-best-practices/security/docs/iam/#restrict-access-to-the-instance-profile-assigned-to-the-worker-node).

values.yaml example:

joinParams:
  method: "token"|"ec2"|"iam"

joinParams.tokenName

Type Default value Required?
string nil Yes

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 joinTokenSecret for more details and instructions.

values.yaml example:

joinParams:
  tokenName: "my-token"

proxyAddr

Type Default value Required?
string nil Yes

proxyAddr provides the public-facing Teleport proxy endpoint which should be used to join the cluster. This is the same URL that is used to access the web UI of your Teleport cluster. It is the same as the value configured for proxy_service.public_addr in a traditional Teleport cluster. The port used is usually either 3080 or 443.

Here are a few examples:

Deployment method Example proxy_service.public_addr
On-prem Teleport cluster teleport.example.com:3080
Teleport Cloud cluster example.teleport.sh:443
teleport-cluster Helm chart teleport.example.com:443

kubeClusterName

Type Default value Required?
string nil When kube chart role is used

kubeClusterName sets the name used for the Kubernetes cluster proxied by the Teleport agent. This name will be shown to Teleport users connecting to the cluster.

values.yaml example:

kubeClusterName: my-gke-cluster

apps

Type Default value Required?
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.

values.yaml example:

apps:
- name: grafana
  uri: http://localhost:3000
  labels:
    purpose: monitoring
- name: jenkins
  uri: http://jenkins:8080
  labels:
    purpose: ci
You can see a list of all the supported [values which can be used in a Teleport application access configuration here](../../application-access/reference.mdx#configuration).

appResources

Type Default value Required?
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 the Teleport Application Service.

You can specify multiple selectors by including additional list elements.

values.yaml example:

appResources:
- labels:
    "env": "prod"
- labels:
    "env": "test"
Once `appResources` is set, you can dynamically register application with `tsh` by following [this guide](../../application-access/guides/dynamic-registration.mdx).

awsDatabases

This section configures AWS database auto-discovery. You can configure databases for other platforms using the [`azureDatabases`](#azuredatabases) or [`databases`](#databases) sections. 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](../../database-access/guides/rds.mdx#step-36-create-an-iam-policy-for-teleport).

After configuring a role, you can use an eks.amazonaws.com/role-arn annotation with the annotations.serviceAccount value to associate it with the service account and grant permissions:

annotations:
  serviceAccount:
    eks.amazonaws.com/role-arn: arn:aws:iam::1234567890:role/my-rds-autodiscovery-role
Type Default value Required?
list [] 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.

values.yaml example:

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

azureDatabases

This section configures Azure database auto-discovery. You can configure databases for other platforms using the [`awsDatabases`](#awsdatabases) or [`databases`](#databases) sections. For Azure database auto-discovery to work, your Database Service pods will need to have appropriate IAM permissions as per the [database documentation](../../database-access/guides/azure-postgres-mysql.mdx#step-46-configure-iam-permissions-for-teleport).

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"
Type Default value Required?
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.

values.yaml example:

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"

databases

Type Default value Required?
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.

values.yaml example:

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
You can see a list of all the supported [values which can be used in a Teleport database service configuration here](../../database-access/reference/configuration.mdx). 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

Type Default value Required?
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 the Teleport Database Service.

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

values.yaml example:

databaseResources:
- labels:
    "env": "prod"
    "engine": "postgres"
- labels:
    "env": "test"
    "engine": "mysql"
Once `databaseResources` is set, you can dynamically register database with `tsh` by following [this guide](../../database-access/guides/dynamic-registration.mdx).

teleportVersionOverride

Type Default value
string nil

Normally the version of Teleport being used will match the version of the chart being installed. If you install chart version 10.0.0, you'll be using Teleport 10.0.0. Upgrading the Helm chart will use the latest version from the repo.

You can optionally override this to use a different published Teleport Docker image tag like 10.1.2 or 11.

`teleportVersionOverride` is intended for development and MUST NOT be used to control the Teleport version in a typical deployment. This chart is designed to run a specific Teleport version. You will face compatibility issues trying to run a different Teleport version with it.

If you want to run Teleport version X.Y.Z, you should use helm --version X.Y.Z instead.

values.yaml example:

teleportVersionOverride: "11"

caPin

Type Default 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.

values.yaml example:

caPin: ["sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1"]

insecureSkipProxyTLSVerify

Type Default value
bool false

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.

values.yaml example:

insecureSkipProxyTLSVerify: false
Using a self-signed TLS certificate and disabling TLS verification is OK for testing, but is not viable when running a production Teleport cluster as it will drastically reduce security. You must configure valid TLS certificates on your Teleport cluster for production workloads.

One option might be to use Teleport's built-in ACME support 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

Type Default 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.

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](#databases).

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

values.yaml example:

tls:
  existingCASecretName: my-root-ca

existingDataVolume

Type Default value
string ""

When existingDataVolume is set to the name of an existing volume, the /var/lib/teleport mount will use this volume instead of creating a new emptyDir volume.

values.yaml example:

existingDataVolume: my-volume

podSecurityPolicy

podSecurityPolicy.enabled

Type Default value
bool true for < 1.23 false for >= 1.23

By default, Teleport charts used to install a podSecurityPolicy.

PodSecurityPolicy resources (PSP) have been removed in Kubernetes 1.25 and replaced since 1.23 by PodSecurityAdmission (PSA). If you are running on Kubernetes 1.23 or later, it is recommended to disable PSPs and use PSAs. The steps are documented in the PSP removal guide.

To disable PSP creation, you can set enabled to false.

Kubernetes reference

values.yaml example:

podSecurityPolicy:
  enabled: false

labels

Type Default value
object {}

labels can be used to add a map of key-value pairs for the kubernetes_service which is deployed using the teleport-kube-agent chart. These labels can then be used with Teleport's RBAC policies to define access rules for the cluster.

These are Teleport-specific RBAC labels, not Kubernetes labels. For historical/backwards compatibility reasons, these labels will only be applied to the Kubernetes cluster being joined via the Teleport Kubernetes service.

To set labels for applications, add a labels element to the apps 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.

values.yaml example:

labels:
  environment: production
  region: us-east

storage

storage.enabled

Type Default value
bool false

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.

values.yaml example:

storage:
  enabled: true

storage.storageClassName

Type Default value
string nil

The storage class name the persistent volume should use when creating persistent volume claims. The provided storage class name needs to exist on the Kubernetes cluster for Teleport to use.

Kubernetes reference

values.yaml example:

storage:
  storageClassName: teleport-storage-class

storage.requests

Type Default value
string 128Mi

The size of persistent volume to create.

values.yaml example:

storage:
  requests: 128Mi

image

Type Default value
string public.ecr.aws/gravitational/teleport

image sets the container image used for Teleport agent pods run by the teleport-kube-agent chart.

You can override this to use your own Teleport image rather than a Teleport-published image.

When using the Teleport Kube Agent Updater you must ensure the image is available before the updater version target gets updated and Kubernetes tries to pull the image.

For this reason, it is strongly discouraged to set a custom image when connecting to a Teleport Cloud instance enrolled in automatic updates.

values.yaml example:

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

imagePullSecrets

Type Default value Can 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.

values.yaml example:

imagePullSecrets:
- name: my-docker-registry-key

highAvailability

highAvailability.replicaCount

Type Default value
int 1

highAvailability.replicaCount can be used to set the number of replicas used in the deployment.

Set to a number higher than 1 for a high availability mode where multiple Teleport pods will be deployed.

As a rough guide, we recommend configuring one replica per distinct availability zone where your cluster has worker nodes.

2 replicas/availability zones will be fine for smaller workloads. 3-5 replicas/availability zones will be more appropriate for bigger clusters with more traffic.

values.yaml example:

highAvailability:
  replicaCount: 3

highAvailability.requireAntiAffinity

Type Default value
bool false

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.

This can result in Teleport pods failing to be scheduled in very small clusters or during node downtime, so should be used with caution.

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

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

values.yaml example:

highAvailability:
  requireAntiAffinity: true

highAvailability.podDisruptionBudget

highAvailability.podDisruptionBudget.enabled

Type Default value
bool false

Kubernetes reference

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

values.yaml example:

highAvailability:
  podDisruptionBudget:
    enabled: true

highAvailability.podDisruptionBudget.minAvailable

Type Default value
int 1

Kubernetes reference

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

values.yaml example:

highAvailability:
  podDisruptionBudget:
    minAvailable: 1

clusterRoleName

Type Default value
string nil

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

Most users will not need to change this.

values.yaml example:

clusterRoleName: kubernetes-clusterrole

clusterRoleBindingName

Most users will not need to change this.
Type Default value
string nil

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

values.yaml example:

clusterRoleBindingName: kubernetes-clusterrolebinding

priorityClassName

Type Default value
string nil

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

values.yaml example:

priorityClassName: "teleport-kube-agent"

serviceAccount.create

Type Default value Required? Can be used in custom mode?
boolean true No

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.

values.yaml example:

serviceAccount:
  create: false
  name: kubernetes-serviceaccount

serviceAccount.name

Type Default value Required? 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.

values.yaml example:

serviceAccount:
  name: kubernetes-serviceaccount

joinTokenSecret

joinTokenSecret.create

Type Default value
bool true

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

joinTokenSecret.name

Type Default value
string teleport-kube-agent-join-token

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

If joinTokenSecret.create is false, the chart will not attempt to create the secret itself. Instead, it will read the value from an existing secret. joinTokenSecret.name 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>
The key used for the auth token inside the secret must be `auth-token`, as in the command above.

values.yaml example:

joinTokenSecret:
  create: false
  name: "secret-i-created-before"

joinParams:
  method: "token"
  tokenName: ""

log

log.level

This field used to be called `logLevel`. For backwards compatibility this name can still be used, but we recommend changing your values file to use `log.level`.
Type Default value
string INFO

log.level sets the log level used for the Teleport process.

Available log levels (in order of most to least verbose) are: DEBUG, INFO, WARNING, ERROR.

The default is INFO, which is recommended in production.

DEBUG is useful during first-time setup or to see more detailed logs for debugging.

values.yaml example:

log:
  level: DEBUG

log.output

Type Default value Can be used in custom mode? teleport.yaml equivalent
string stderr teleport.log.output

log.output sets the output destination for the Teleport process.

This can be set to any of the built-in values: stdout, stderr or syslog to use that destination.

The value can also be set to a file path (such as /var/log/teleport.log) to write logs to a file. Bear in mind that a few service startup messages will still go to stderr for resilience.

values.yaml example:

log:
  output: stderr

log.format

Type Default value Can be used in custom mode? teleport.yaml equivalent
string text teleport.log.format.output

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

Possible values are text (default) or json.

values.yaml example:

log:
  format: json

log.extraFields

Type Default value Can be used in custom mode? teleport.yaml equivalent
list ["timestamp", "level", "component", "caller"] teleport.log.format.extra_fields

log.extraFields sets the fields used in logging for the Teleport process.

See the Teleport config file reference for more details on possible values for extra_fields.

values.yaml example:

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

affinity

Type Default value
object {}

Kubernetes reference

Kubernetes affinity to set for pod assignments.

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

values.yaml example:

affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: gravitational.io/dedicated
          operator: In
          values:
          - teleport

dnsConfig

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

Type Default value
string ""

Kubernetes reference

Kubernetes pod DNS policy.

dnsPolicy: "Default"

nodeSelector

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

values.yaml example:

nodeSelector:
  role: node
  region: us-east

extraLabels.clusterRole

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  clusterRole:
    app.kubernetes.io/name: teleport-kube-agent

extraLabels.clusterRoleBinding

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  clusterRoleBinding:
    app.kubernetes.io/name: teleport-kube-agent

extraLabels.role

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  role:
    app.kubernetes.io/name: teleport-kube-agent

extraLabels.roleBinding

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  roleBinding:
    app.kubernetes.io/name: teleport-kube-agent

extraLabels.config

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  config:
    app.kubernetes.io/name: teleport-kube-agent

extraLabels.deployment

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  deployment:
    app.kubernetes.io/name: teleport-kube-agent

extraLabels.pod

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  pod:
    app.kubernetes.io/name: teleport-kube-agent

extraLabels.podDisruptionBudget

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  podDisruptionBudget:
    app.kubernetes.io/name: teleport-kube-agent

extraLabels.podSecurityPolicy

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  podSecurityPolicy:
    app.kubernetes.io/name: teleport-kube-agent

extraLabels.secret

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  secret:
    app.kubernetes.io/name: teleport-kube-agent

extraLabels.serviceAccount

Type Default value
object {}

Kubernetes reference

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

values.yaml example:

extraLabels:
  serviceAccount:
    app.kubernetes.io/name: teleport-kube-agent

annotations.config

Type Default value Can 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.

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

values.yaml example:

annotations:
  config:
    kubernetes.io/annotation: value

annotations.deployment

Type Default value Can be used in custom mode?
object {}

Kubernetes reference

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

values.yaml example:

annotations:
  deployment:
    kubernetes.io/annotation: value

annotations.pod

Type Default value Can be used in custom mode?
object {}

Kubernetes reference

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

values.yaml example:

annotations:
  pod:
    kubernetes.io/annotation: value

annotations.serviceAccount

Type Default value Can be used in custom mode?
object {}

Kubernetes reference

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

values.yaml example:

annotations:
  serviceAccount:
    kubernetes.io/annotation: value

extraVolumes

Type Default value Can 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.

values.yaml example:

extraVolumes:
- name: myvolume
  secret:
    secretName: mysecret

extraArgs

Type Default value
list []

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

values.yaml example:

extraArgs:
- "--debug"

extraEnv

Type Default value
list []

Kubernetes reference

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

values.yaml example:

extraEnv:
- name: HTTPS_PROXY
  value: "http://username:password@my.proxy.host:3128"

extraVolumeMounts

Type Default value Can 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.

values.yaml example:

extraVolumeMounts:
- name: myvolume
  mountPath: /path/to/mount/volume

imagePullPolicy

Type Default value Can be used in custom mode?
string IfNotPresent

Kubernetes reference

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

values.yaml example:

imagePullPolicy: Always

initContainers

Type Default value Can 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.

values.yaml example:

initContainers:
- name: teleport-init
  image: alpine
  args: ['echo test']

resources

Type Default value Can 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.

values.yaml example:

resources:
  requests:
    cpu: 1
    memory: 2Gi

initSecurityContext

Container security context to set for the initContainer. Defaults to:

initSecurityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - all
  readOnlyRootFilesystem: true
  runAsNonRoot: true
  runAsUser: 9807

To unset the security context, set it to null or ~.

securityContext

Container security context to set for the main Teleport container. Defaults to:

securityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - all
  readOnlyRootFilesystem: true
  runAsNonRoot: true
  runAsUser: 9807

To unset the security context, set it to null or ~.

tolerations

Type Default value Can be used in custom mode?
list []

Kubernetes reference

Kubernetes Tolerations to set for pod assignment.

values.yaml example:

tolerations:
- key: "dedicated"
  operator: "Equal"
  value: "teleport"
  effect: "NoSchedule"

probeTimeoutSeconds

Type Default value
integer 1

Kubernetes reference

Kubernetes timeouts for the liveness and readiness probes.

values.yaml example:

probeTimeoutSeconds: 5