Teleport

teleport-kube-agent Chart Reference

OpenSource
Enterprise
Cloud

The teleport-kube-agent Helm chart is used to configure a Teleport instance that runs in a remote Kubernetes cluster and joins back to a Teleport cluster to provide access to services running there.

You can browse the source on GitHub.

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

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.

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

roles: kube,app,db

--set roles=kube\,app\,db

Note

When specifying multiple roles using --set syntax, you must escape the commas using a backslash (\).

This is a quirk of Helm's CLI parser.

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

`authToken`

Type	Default value	Required?
`string`	`nil`	Yes

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

This value must be provided for the chart to work. The token that you use must also be valid for every Teleport service that you are trying to add with the teleport-kube-agent chart. Here are a few examples:

Services	Service Name	`tctl tokens add` example	`teleport.yaml` static token example
Kubernetes	`kube`	`tctl tokens add --type=kube`	`"kube:<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>"`

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>

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

kubeClusterName: my-gke-cluster

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

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

YAML formatting

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

--set "apps[0].name=grafana" \--set "apps[0].uri=http://localhost:3000" \--set "apps[0].purpose=monitoring" \--set "apps[1].name=grafana" \--set "apps[1].uri=http://jenkins:8080" \--set "apps[1].purpose=ci"

Note

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

Supported values

You can see a list of all the supported values which can be used in a Teleport application access configuration here.

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

Database auto-discovery

This section configures database auto-discovery, which is only currently supported on AWS. You can configure databases for other platforms using the databases section below this.

IAM roles

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

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

awsDatabases:
  - types: ["rds"]
    regions: ["us-east-1", "us-west-2"]
    tags:
      "environment": "production"
  - types: ["rds"]
    regions: ["us-east-1"]
    tags:
      "environment": "dev"
  - types: ["rds"]
    regions: ["eu-west-1"]
    tags:
      "*": "*"

YAML formatting

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

--set "awsDatabases[0].types[0]=rds" \
--set "awsDatabases[0].regions[0]=us-east-1" \
--set "awsDatabases[0].regions[1]=us-west-2" \
--set "awsDatabases[0].tags[0].environment=production" \
--set "awsDatabases[1].types[0]=rds" \
--set "awsDatabases[1].regions[0]=us-east-1" \
--set "awsDatabases[1].tags[0].environment=dev" \
--set "awsDatabases[2].types[0]=rds" \
--set "awsDatabases[2].regions[0]=eu-west-1" \
--set "awsDatabases[2].tags[0].*=*"

Note

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

`databases`

Type	Default value	Required?
`list`	`[]`	When the `db` chart role is used at least one of `databases`, `awsDatabases`, `dbResources` 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 like to use a linter to validate your YAML list and ensure that it is correctly formatted.

--set "databases[0].name=aurora" \--set "databases[0].uri=postgres-aurora-instance-1.xxx.us-east-1.rds.amazonaws.com:5432" \--set "databases[0].protocol=postgres" \--set "databases[0].aws.region=us-east-1" \--set "databases[0].static_labels.env=staging" \--set "databases[1].name=mysql" \--set "databases[1].uri=mysql-instance-1.xxx.us-east-1.rds.amazonaws.com:3306" \--set "databases[1].protocol=mysql" \--set "databases[1].aws.region=us-east-1" \--set "databases[1].static_labels.env=staging"

Note

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

Supported values

You can see a list of all the supported values which can be used in a Teleport database service configuration here.

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

`dbResources`

Type	Default value	Required?
`list`	`[]`	When the `db` chart role is used at least one of `databases`, `awsDatabases`, `dbResources` is required.

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

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


--set "dbResources[0].labels.env=prod" \
--set "dbResources[0].labels.engine=postgres" \
--set "dbResources[1].labels.env=test" \
--set "dbResources[0].labels.engine=mysql"

Note

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

Example

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

`teleportVersionOverride`

Type	Default value
`string`	`nil`

Normally the version of Teleport being used will match the version of the chart being installed. If you install chart version 7.0.0, you'll be using Teleport 7.0.0.

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

See this link for information on Community Docker image versions.

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`

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.

caPin: ["sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1"]

--set caPin[0]="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.

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.

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

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`

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.

existingDataVolume: my-volume

--set existingDataVolume=my-volume

`podSecurityPolicy`

`podSecurityPolicy.enabled`

Type	Default value
`bool`	`true`

By default, Teleport charts also install a podSecurityPolicy.

To disable this, you can set enabled to false.

teleport-kube-agent Chart Reference

roles

authToken

proxyAddr

kubeClusterName

apps

appResources

awsDatabases

databases

dbResources

teleportVersionOverride

caPin

insecureSkipProxyTLSVerify

tls

existingCASecretName

existingDataVolume

podSecurityPolicy

podSecurityPolicy.enabled

labels

storage

storage.enabled

storage.storageClassName

storage.requests

image

imagePullSecrets

highAvailability

highAvailability.replicaCount

highAvailability.requireAntiAffinity

highAvailability.podDisruptionBudget

highAvailability.podDisruptionBudget.enabled

highAvailability.podDisruptionBudget.minAvailable

clusterRoleName

clusterRoleBindingName

priorityClassName

serviceAccountName

secretName

log

log.level

log.output

log.format

log.extraFields

affinity

nodeSelector

extraLabels.clusterRole

extraLabels.clusterRoleBinding

extraLabels.config

extraLabels.deployment

extraLabels.pod

extraLabels.podDisruptionBudget

extraLabels.podSecurityPolicy

extraLabels.secret

extraLabels.serviceAccount

annotations.config

annotations.deployment

annotations.pod

annotations.serviceAccount

extraVolumes

extraArgs

extraEnv

extraVolumeMounts

imagePullPolicy

initContainers

resources

tolerations

probeTimeoutSeconds

`roles`

`authToken`

`proxyAddr`

`kubeClusterName`

`apps`

`appResources`

`awsDatabases`

`databases`

`dbResources`

`teleportVersionOverride`

`caPin`

`insecureSkipProxyTLSVerify`

`tls`

`existingCASecretName`

`existingDataVolume`

`podSecurityPolicy`

`podSecurityPolicy.enabled`

`labels`

`storage`

`storage.enabled`

`storage.storageClassName`

`storage.requests`

`image`

`imagePullSecrets`

`highAvailability`

`highAvailability.replicaCount`

`highAvailability.requireAntiAffinity`

`highAvailability.podDisruptionBudget`

`highAvailability.podDisruptionBudget.enabled`

`highAvailability.podDisruptionBudget.minAvailable`

`clusterRoleName`

`clusterRoleBindingName`

`priorityClassName`

`serviceAccountName`

`secretName`

`log`

`log.level`

`log.output`

`log.format`

`log.extraFields`

`affinity`

`nodeSelector`

`extraLabels.clusterRole`

`extraLabels.clusterRoleBinding`

`extraLabels.config`

`extraLabels.deployment`

`extraLabels.pod`

`extraLabels.podDisruptionBudget`

`extraLabels.podSecurityPolicy`

`extraLabels.secret`

`extraLabels.serviceAccount`

`annotations.config`

`annotations.deployment`

`annotations.pod`

`annotations.serviceAccount`

`extraVolumes`

`extraArgs`

`extraEnv`

`extraVolumeMounts`

`imagePullPolicy`

`initContainers`

`resources`

`tolerations`

`probeTimeoutSeconds`