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 elevated privileges to make following each step easier.

We recommend you follow the best practices to avoid security incidents:

  1. Avoid using sudo in production environments unless it's necessary.
  2. Create new, non-root, users and use test instances for experimenting with Teleport.
  3. You can run many Teleport's services as a non root. For example, auth, proxy, application access, kubernetes access, and database access services can run as a non-root user. Only the SSH/node service requires root access. You will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443)
  4. Follow the "Principle of Least Privilege" (PoLP) and "Zero Admin" best practices. Don't give users permissive roles when giving them more restrictive access,editor roles will do instead.
  5. Save tokens into a file rather than sharing tokens directly as strings.

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?