Fork me on GitHub


Kubernetes Auto-Discovery (Preview)


Kubernetes Auto-Discovery allows Kubernetes clusters hosted on cloud providers to be discovered and enrolled automatically.

While discovering a new Kubernetes cluster, Teleport does not install any component on the cluster. Instead, it requires direct access to the cluster's API and minimal access permissions.

Supported clouds

  • AWS: Kubernetes Auto-Discovery for AWS EKS clusters.
  • Azure: Kubernetes Auto-Discovery for Azure AKS clusters.
  • Google Cloud: Kubernetes Auto-Discovery for Google Kubernetes Engine clusters.

How Kubernetes Auto-Discovery works

Kubernetes Auto-Discovery consists of two steps:

Polling cloud APIs

The Teleport Discovery Service is responsible for scanning the configured cloud providers and identifying if any Kubernetes clusters match a set of filtering labels. When the process identifies a new Kubernetes cluster, it creates a dynamic resource within Teleport. This resource includes information imported from the cloud provider such as:

  • Name: Cluster name
  • Labels
    • Cluster tags.
    • Cluster location.
    • Identification of which cloud account the cluster belongs to — AWS Account ID / Azure Subscription ID.

You can import the cluster under a different name into Teleport's registry. To achieve this, you must attach the following tag to the resources — EKS and AKS — in your cloud provider:

  • key:
  • value: desired name

The Discovery Service will check if the cluster includes the tag and use its value as the resource name in Teleport.

You should use this feature whenever there are clusters in different regions/cloud providers with the same name to prevent them from colliding in Teleport.

In addition to detecting new Kubernetes clusters, the Discovery Service also removes — from Teleport's registry — the Kubernetes clusters that have been deleted or whose tags no longer meet the filtering labels.

The following snippet describes the different configuration options for the Discovery Service and their default values.

# This section configures the Discovery Service
    enabled: "yes"
       # AWS resource types. Valid options are:
       # eks - discovers and registers AWS EKS clusters
       # ec2 - discovers and registers AWS EC2 Machines
     - types: ["eks"]
       # AWS regions to search for resources from
       regions: ["us-east-1", "us-west-1"]
       # AWS resource tags to match when registering resources
       # Optional section: Defaults to "*":"*"
         "env": "prod"
    # Matchers for discovering Azure-hosted resources.
      # Azure resource types. Valid options are:
      # 'aks' - discovers and registers Azure AKS Kubernetes Clusters.
    - types: ["aks"]
      # Azure regions to search for resources from. Valid options are:
      # '*' - discovers resources in all regions (default).
      # Any valid Azure region name. List all valid regions using the Azure "az" cli: `az account list-locations -o table`
      regions: ["*"]
      # Azure subscription IDs to search resources from. Valid options are:
      # '*' - discovers resources in all subscriptions (default).
      # Any subscription_id: `az account subscription list -o table`
      subscriptions: ["*"]
      # Azure resource groups to search resources from. Valid options are:
      # '*' - discovers resources in all resource groups within configured subscription(s) (default).
      # Any resource_groups: `az group list -o table`
      resource_groups: ["*"]
      # Azure resource tag filters used to match resources.
      # Optional section: Defaults to "*":"*"
        "env": "prod"

Forwarding requests to the Kubernetes Cluster

The Teleport Kubernetes Service is responsible for monitoring the dynamic resources created or updated by the Discovery Service and forwarding requests to the Kubernetes clusters they represent. To work correctly, it requires direct access to the target Kubernetes clusters and permissions to forward requests.

To turn on dynamic resource monitoring in the Kubernetes Service, you must configure the kubernetes_service.resources section as shown in the following snippet:

## This section configures the Kubernetes Service
    enabled: "yes"
    # Matchers for dynamic Kubernetes cluster resources created with the "tctl create" command or by Kubernetes auto-discovery.
    - labels:
        "*": "*" # can be configured to limit the clusters to watched by this service.

Both services — Discovery and Kubernetes — can be configured in the same Teleport process or separate processes.