
While you can register a Kubernetes cluster with Teleport by running the Teleport Kubernetes Service on that cluster, you can also run the Teleport Kubernetes Service on a Linux host outside the cluster. This is useful if you want to decouple your Teleport deployment from the Kubernetes clusters you want to manage access to.
In this setup, the Teleport Kubernetes Service uses a kubeconfig
file to
authenticate to the API server of your chosen Kubernetes cluster.
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 resource service (e.g., the Database Service or
Application Service) 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 >= 12.1.1.tctl versionTeleport v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
Please use the latest version of Teleport Enterprise documentation.
- A Kubernetes cluster you would like to access.
- A Linux host deployed on your own infrastructure to run the Teleport Kubernetes Service. This can run outside of your Kubernetes cluster.
- The
kubectl
command line tool installed on your workstation.
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 12.1.1
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 12.1.2
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
Step 1/4. Generate a kubeconfig file
The Teleport Kubernetes Service uses a kubeconfig
file to authenticate to your
Kubernetes cluster. In this section, we will generate a kubeconfig
file so we
can configure the Teleport Kubernetes Service to use it later in this guide.
Ensure your context is correct
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
:
e.g., my-context
CONTEXT_NAME=context-namekubectl config use-context ${CONTEXT_NAME?}
Run the script
On your workstation, download Teleport's get-kubeconfig.sh
script, which you
will use to generate the kubeconfig
file:
curl -OL \https://raw.githubusercontent.com/gravitational/teleport/v12.1.1/examples/k8s-auth/get-kubeconfig.sh
get-kubeconfig.sh
creates a service account for the Teleport Kubernetes
Service that can get Kubernetes pods as well as impersonate users, groups, and
other service accounts. The Teleport Kubernetes Service uses this service
account to manage access to resources in your Kubernetes cluster. The script
also ensures that there is a Kubernetes Secret
in your cluster to store
service account credentials.
get-kubeconfig.sh
also creates a namespace called teleport
for the
resources it deploys, though you can choose a different name by assigning the
TELEPORT_NAMESPACE
environment variable in the shell where you run the
script.
After creating resources, get-kubeconfig.sh
writes a new kubeconfig
file
called kubeconfig
in the directory where you run the script.
Run the get-kubeconfig.sh
script:
bash get-kubeconfig.sh
The script is successful if you see this message:
Done!
Move the kubeconfig
file to the host you are using to run the Teleport
Kubernetes Service. We will assume that the kubeconfig
file exists at
/var/lib/teleport/kubeconfig
.
You can connect multiple Kubernetes clusters to Teleport from one kubeconfig
file if it contains multiple entries. Use
merge-kubeconfigs.sh
to combine multiple kubeconfig
files generated by get-kubeconfig.sh
.
Step 2/4. Set up the Teleport Kubernetes Service
In this step, you will install the Teleport Kubernetes Service and configure it
to use the kubeconfig
file you generated to access a Kubernetes cluster.
Get a join token
Establish trust between your Teleport cluster and your new Kubernetes Service instance by creating a join token:
tctl nodes add --roles=kubeThe invite token: abcd123-insecure-do-not-use-this
This token will expire in 30 minutes.
Run this on the new node to join the cluster:
> teleport start \
--roles=kube \
--token=abcd123-insecure-do-not-use-this \
--ca-pin=sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 \
--auth-server=192.0.2.255:3025
Please note:
- This invitation token will expire in 30 minutes
- 192.0.2.255:3025 must be reachable from the new node
On the host where you are running the Teleport Kubernetes Service, create a
file called /tmp/token
that consists only of your token:
echo join-token | sudo tee /tmp/token
Install the Teleport Kubernetes Service
Run the following commands on the host where you will install the Teleport Kubernetes Service:
Use the appropriate commands for your environment to install your package.
Teleport Edition
Add the Teleport repository to your repository list:
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID'
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v12/teleport.repo")sudo yum install teleportTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Optional: Use DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport
In the example commands below, update $SYSTEM-ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
curl https://get.gravitational.com/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzshasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzcd teleportsudo ./install
In the example commands below, update $SYSTEM-ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
After Downloading the .deb
file for your system architecture, install it with
dpkg
. The example below assumes the root
user:
dpkg -i ~/Downloads/teleport-ent_12.1.1_$SYSTEM-ARCH.debSelecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_12.1.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 12.1.1 ...
Setting up teleport-ent 12.1.1 ...
After Downloading the .rpm
file for your system architecture, install it with rpm
:
rpm -i ~/Downloads/teleport-ent-12.1.1.$SYSTEM-ARCH.rpmwarning: teleport-ent-12.1.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY
curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzshasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzcd teleport-entsudo ./install
For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
Please use the latest version of Teleport Enterprise documentation.
Configure the Teleport Kubernetes Service
On the host where you will run the Teleport Kubernetes Service, create a file at
/etc/teleport.yaml
with the following content:
version: v3
teleport:
join_params:
token_name: "/tmp/token"
method: token
proxy_server: "teleport.example.com:3080"
auth_service:
enabled: off
proxy_service:
enabled: off
ssh_service:
enabled: off
kubernetes_service:
enabled: "yes"
kubeconfig_file: "/var/lib/teleport/kubeconfig"
labels:
"region": "us-east1"
Edit /etc/teleport.yaml
to replace teleport.example.com:3080
with the host
and port of your Teleport Proxy Service or Teleport Cloud tenant, e.g.,
mytenant.teleport.sh:443
.
When using kubeconfig_file
, Amazon 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
files, which are not allowed in Teleport.
Start the Teleport Kubernetes Service
On the host where you will run the Teleport Kubernetes Service, execute the following command, depending on whether you installed Teleport using a package manager or via a TAR archive:
sudo systemctl start teleport
sudo teleport install systemd --output=/etc/systemd/system/teleport.service;sudo systemctl enable teleport;sudo systemctl start teleport;
Step 3/4. Grant access to your Teleport user
Enable your Teleport user to access resources in your Kubernetes cluster so you can connect to the cluster later in this guide.
Kubernetes authentication
To authenticate to a Kubernetes cluster via Teleport, your Teleport roles must allow access as at least one Kubernetes user or group. Ensure that you have a Teleport role that grants access to the cluster you plan to interact with.
Run the following command to get the Kubernetes user for your current context:
kubectl config view \-o jsonpath="{.contexts[?(@.name==\"$(kubectl config current-context)\")].context.user}"
Create a file called kube-access.yaml
with the following content, replacing
USER
with the output of the command above.
kind: role
metadata:
name: kube-access
version: v6
spec:
allow:
kubernetes_labels:
'*': '*'
kubernetes_resources:
- kind: pod
namespace: "*"
name: "*"
kubernetes_groups:
- viewers
kubernetes_users:
- USER
deny: {}
Apply your changes:
tctl create -f kube-access.yaml
Assign the kube-access
role to your Teleport user by running the following
commands, depending on whether you authenticate as a local Teleport user or via
the github
, saml
, or oidc
authentication connectors:
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
Edit out.yaml
, adding kube-access
to the list of existing roles:
roles:
- access
- auditor
- editor
+ - kube-access
Apply your changes:
tctl create -f out.yaml
Retrieve your github
configuration resource:
tctl get github/github --with-secrets > github.yaml
Edit github.yaml
, adding kube-access
to the
teams_to_roles
section. The team you will map to this role will depend on how
you have designed your organization's RBAC, but it should be the smallest team
possible within your organization. This team must also include your user.
Here is an example:
teams_to_roles:
- organization: octocats
team: admins
roles:
- access
+ - kube-access
Apply your changes:
tctl create -f github.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your saml
configuration resource:
tctl get --with-secrets saml/mysaml > saml.yaml
Edit saml.yaml
, adding kube-access
to the
attributes_to_roles
section. The attribute you will map to this role will
depend on how you have designed your organization's RBAC, but it should be the
smallest group possible within your organization. This group must also include
your user.
Here is an example:
attributes_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - kube-access
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc --with-secrets > oidc.yaml
Edit oidc.yaml
, adding kube-access
to the
claims_to_roles
section. The claim you will map to this role will depend on
how you have designed your organization's RBAC, but it should be the smallest
group possible within your organization. This group must also include your
user.
Here is an example:
claims_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - kube-access
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Log out of your Teleport cluster and log in again to assume the new role.
Now that Teleport RBAC is configured, you can authenticate to your Kubernetes cluster via Teleport. To interact with your Kubernetes cluster, you will need to configure authorization within Kubernetes.
Kubernetes authorization
To configure authorization within your Kubernetes cluster, you need to create Kubernetes RoleBinding
s or
ClusterRoleBindings
that grant permissions to the subjects listed in kubernetes_users
and
kubernetes_groups
.
For example, you can grant some limited read-only permissions to the viewers
group used in the kube-access
role defined above:
Create a file called viewers-bind.yaml
with the following contents:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: viewers-crb
subjects:
- kind: Group
# Bind the group "viewers", corresponding to the kubernetes_groups we assigned our "kube-access" role above
name: viewers
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
# "view" is a default ClusterRole that grants read-only access to resources
# See: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles
name: view
apiGroup: rbac.authorization.k8s.io
Apply the ClusterRoleBinding
with kubectl
:
kubectl apply -f viewers-bind.yaml
Log out of Teleport and log in again.
Step 4/4. Access your Kubernetes cluster
After Teleport starts with the above config, you should be able to see all new clusters:
tsh kube lsKube Cluster Name Labels Selected
--------------------------------------- ------ --------
my-cluster region=us-east-1
To access your cluster, run the following command, replacing my-cluster
with
the name of the cluster you would like to access:
tsh kube login my-clusterLogged into kubernetes cluster "my-cluster". Try 'kubectl version' to test the connection.