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 thehistory
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 andtsh
client tool version >= 9.3.7.tctl versionTeleport v9.3.7 go1.17
tsh versionTeleport 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 andtsh
client tool version >= 9.3.7, which you can download by visiting the customer portal.tctl versionTeleport v9.3.7 go1.17
tsh versionTeleport 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 andtsh
client tool version >= 9.3.8. To download these tools, visit the Downloads page.tctl versionTeleport v9.3.8 go1.17
tsh versionTeleport 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 statusCluster 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 statusCluster 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"
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 lsor
sudo tctl get kube_service