Teleport EKS Auto-Discovery
- Available for:
EKS Auto-Discovery can automatically discover any EKS cluster and enroll it in Teleport if its tags match the configured labels.
Teleport Kubernetes Auto-Discovery involves two components.
The first, the Discovery Service, is responsible for watching your cloud provider and checking if there are any new clusters or if there have been any modifications to previously discovered clusters. The second, the Kubernetes Service, monitors the clusters created by the Discovery Service. It proxies communications between users and the API servers of these clusters.
This guide presents the Discovery Service and Kubernetes Service running in the same process, however both can run independently and on different machines.
For example, you can run an instance of the Kubernetes Service in each Kubernetes cluster you want to register with Teleport, and an instance of the Discovery Service in any network you wish.
- An AWS account with permissions to create and attach IAM policies.
- An AWS account with
system:mastersRBAC access to EKS clusters.
- A host to run the Teleport Discovery and Kubernetes services.
- One or more EKS clusters running.
Due to the authorization method that AWS has chosen for EKS clusters, it is not
possible for the Teleport process to configure the necessary permissions to forward
requests to EKS clusters.
This limitation exists because the authorization method on EKS clusters requires that the IAM role -
used for authentication - exists in the
ConfigMap, IAM roles are mapped to Kubernetes RBAC users or groups that are then
used by Kubernetes RBAC to grant access permissions. If the mapping does not exist, it results in
unauthorized requests. Therefore, Teleport cannot edit the
without first having access to the cluster.
If Teleport is not running with the same IAM identity that creates all clusters, please ensure you configure the required permissions as described in Step 2.
The AWS EKS team is working on a feature request to introduce an external API to manage access to the cluster without manually editing the Configmap (aws/containers-roadmap#185).
Hopefully, once the feature is available, Teleport can leverage it to configure its access to the cluster.
For Teleport to discover EKS clusters, the instance running the Discovery Service requires an IAM policy that allows Teleport to list and describe EKS clusters:
When the Kubernetes Service uses an IAM role that is different from the one that
creates the clusters, you need to configure the mapping between the Teleport IAM
Role and the Kubernetes RBAC permissions by editing the
each of the discovered clusters.
To forward requests to the Kubernetes cluster, the Teleport Kubernetes Service
requires cluster-wide permissions to
Impersonate RBAC users and groups, to
SelfSubjectRulesReviews, and, finally,
read access to
If your Kubernetes cluster does not have an RBAC group with the required
permissions, you can create the
ClusterRoleBinding, and the
mapping by following the Creating RBAC group guide.
If your cluster already has an RBAC group that satisfies the required permissions,
you can reuse it and map it into the IAM Role used by the Teleport Kubernetes
Service. For simplicity, it is also possible to map the Teleport IAM role onto
a built-in Kubernetes RBAC group like
system:masters, but not recommended in
If you provision your EKS clusters using tools such as
Cloudformation, you can use them to automatically configure the
and create the
ClusterRoleBinding resources during cluster provisioning.
Teleport EKS Auto-Discovery requires a valid Teleport auth token for the Discovery and
Kubernetes services to join the cluster. Generate one by running the following
command against your Teleport Auth Service and save it in
/tmp/token on the
machine that will run Kubernetes Discovery:
tctl tokens add --type=discovery,kube
Discovery Service exposes a configuration parameter -
that allows you to group discovered resources into different sets. This parameter
is used to prevent Discovery Agents watching different sets of cloud resources
from colliding against each other and deleting resources created by another services.
When running multiple Discovery Services, you must ensure that each service is configured
with the same
discovery_group value if they are watching the same cloud resources
or a different value if they are watching different cloud resources.
It is possible to run a mix of configurations in the same Teleport cluster meaning that some Discovery Services can be configured to watch the same cloud resources while others watch different resources. As an example, a 4-agent high availability configuration analyzing data from two different cloud accounts would run with the following configuration.
- 2 Discovery Services configured with
discovery_group: "prod"polling data from Production account.
- 2 Discovery Services configured with
discovery_group: "staging"polling data from Staging account.
Enabling EKS Auto-Discovery requires that the
include at least one entry and that
It also requires configuring the
kubernetes_service.resources.tags to use the same
labels configured at
discovery_service.aws.tags or a subset of them to make
the Kubernetes Service listen to the dynamic resources created by the Discovery
- types: ["eks"]
"env": "prod" # Match EKS cluster tags where tag:env=prod
"env": "prod" # Match Kubernetes Cluster labels specified earlier
Grant the Kubernetes and Discovery Services access to credentials that it can use to authenticate to AWS. If you are running the Kubernetes and Discovery Services on an EC2 instance, you should use the EC2 Instance Metadata Service method. Otherwise, you must use environment variables:
Teleport's AWS client loads credentials from different sources in the following order:
- Environment Variables
- Shared credentials file
- Shared configuration file (Teleport always enables shared configuration)
- EC2 Instance Metadata (credentials only)
While you can provide AWS credentials via a shared credentials file or shared
configuration file, you will need to run the Kubernetes and Discovery Services with the
environment variable assigned to the name of your profile of choice.
If you have a specific use case that the instructions above do not account for, consult the documentation for the AWS SDK for Go for a detailed description of credential loading behavior.
Configure the Kubernetes and Discovery Services to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Kubernetes and Discovery Services.
You can check the status of the Kubernetes and Discovery Services with
systemctl status teleport
and view its logs with
journalctl -fu teleport.
Once the Kubernetes and Discovery Services start, EKS clusters matching the tags and regions specified in the AWS section will be added to the Teleport cluster automatically.
To check if the Discovery Service is working correctly, you can check if any Kubernetes
clusters have been discovered. To do this, you can use the
tctl get kube_cluster
command and inspect if the expected clusters have already been imported into Teleport.
If some clusters do not appear in the list, check if the filtering labels match the missing cluster tags or look into the service logs for permission errors.
tctl get kube_cluster command returns the discovered clusters, but the
tsh kube ls command does not include them, check that you have set the
kubernetes_service.resources section correctly.
If the section is correctly configured, but clusters still do not appear or return authentication errors, please check if permissions have been correctly configured in your target cluster or that you have the correct permissions to list Kubernetes clusters in Teleport.