Teleport

Kubernetes Access from a Standalone Teleport Cluster

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.

When running Teleport in production, we recommend that you follow the practices below to avoid security incidents. These practices may differ from the examples used in this guide, which are intended for demo environments:

Avoid using sudo in production environments unless it's necessary.
Create new, non-root, users and use test instances for experimenting with Teleport.
Run Teleport's services as a non-root user unless required. Only the SSH Service requires root access. Note that you will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443).
Follow the "Principle of Least Privilege" (PoLP). Don't give users permissive roles when giving them more restrictive roles will do instead. For example, assign users the built-in access,editor roles.
When joining a Teleport agent to a cluster, save the invitation token to a file. Otherwise, the token will be visible when examining the teleport command that started the agent, e.g., via the history command on a compromised system.

Prerequisites

A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
The tctl admin tool and tsh client tool version >= 9.3.7.
```
tctl version
Teleport v9.3.7 go1.17
tsh version
Teleport v9.3.7 go1.17
```
See Installation for details.

A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The tctl admin tool and tsh client tool version >= 9.3.7, which you can download by visiting the customer portal.
```
tctl version
Teleport v9.3.7 go1.17
tsh version
Teleport v9.3.7 go1.17
```

A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.
The tctl admin tool and tsh client tool version >= 9.3.8. To download these tools, visit the Downloads page.
```
tctl version
Teleport v9.3.8 go1.17
tsh version
Teleport v9.3.8 go1.17
```

A Kubernetes cluster you would like to access.
A host deployed on your own infrastructure to run the Teleport Kubernetes Service. This can run outside of your Kubernetes cluster.

See Installing Teleport for details on installing the teleport binary.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  9.3.7
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  9.3.8
CA pin   sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Step 1/2. Generate a kubeconfig

First, configure your local kubectl command to point at the Kubernetes cluster you want to register. You can use the following command to verify that the correct cluster is selected:

kubectl config get-contexts

Use this command to switch to the cluster assigned to CONTEXT_NAME:

kubectl config use-context ${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.

Step 2/2. Add your kubeconfig to Teleport

In your Teleport Proxy, add the following to teleport.yaml, replacing example.com with the domain name of your Teleport cluster:

# ...
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:3026

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"

On the host you will use to run the Teleport Kubernetes Service, add the following to teleport.yaml.

# ...
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
or
sudo tctl get kube_service

Have a suggestion or can’t find something?

IMPROVE THE DOCS