Teleport

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.

Tip

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.

Generally:

We discourage using sudo in production environments unless it's needed.
We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
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.
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 get-kubeconfig.sh 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 merge-kubeconfigs.sh to combine multiple kubeconfigs generated by get-kubeconfig.sh.

Adding kubeconfig to Teleport

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

# ...
proxy_service:
  # ...
  public_addr: proxy.example.com:3080

  kube_listen_addr: 0.0.0.0:3026
  # optional: set a different public address for kubernetes access
  kube_public_addr: kube.example.com:3027

kubernetes_service:
  enabled: yes
  listen_addr: 0.0.0.0:3027
  # replace this path with the actual path for your generated kubeconfig
  kubeconfig_file: "path/to/kubeconfig"

Warning

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?

IMPROVE THE DOCS