Fork me on GitHub

Kubernetes Access from standalone Teleport

Standalone Teleport installation

Teleport can connect to external Kubernetes clusters without using the Teleport Helm chart or running a pod inside of the Kubernetes cluster. To do this, Teleport needs a kubeconfig file to authenticate against the Kubernetes API.


The examples below may include the use of the sudo keyword, token UUIDs, and users with admin privileges to make following each step easier when creating resources from scratch.


  1. We discourage using sudo in production environments unless it's needed.
  2. We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
  3. We encourage adherence to the Principle of Least Privilege (PoLP) and Zero Admin best practices. Don't give users the admin role when giving them the more restrictive access,editor roles will do instead.
  4. Saving tokens into a file rather than sharing tokens directly as strings.

Learn more about Teleport Role-Based Access Control best practices.

Generating kubeconfig

First, configure your local kubectl command to point at the Kubernetes cluster you want to register. You can use kubectl config get-contexts to verify that the correct cluster is selected, or kubectl config use-context ${CONTEXT_NAME?} to switch to cluster CONTEXT_NAME.

Next, use to create a kubeconfig for Teleport to use.

You can connect multiple Kubernetes clusters to Teleport from one kubeconfig if it contains multiple entries. Use to combine multiple kubeconfigs generated by

Adding kubeconfig to Teleport

In your Teleport Proxy or a new separate instance, add the following to teleport.yaml:

# ...
  # ...

  # optional: set a different public address for kubernetes access

  enabled: yes
  # replace this path with the actual path for your generated kubeconfig
  kubeconfig_file: "path/to/kubeconfig"
When using kubeconfig_file, EKS users may need to replace illegal characters in the context names. Supported characters are alphanumeric characters, ., _, and -. EKS typically includes : and @ in their kubeconfig which are not allowed in Teleport.

After Teleport starts with the above config, you should be able to see all new clusters using:

tsh kube ls


sudo tctl get kube_service
Have a suggestion or can’t find something?