
Teleport
Connect a Kubernetes Cluster to Teleport
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise

Getting Started With Teleport 12 | Kubernetes Edition
Length: 14:35
In this guide, we will show you how to register a Kubernetes cluster with Teleport by deploying the Teleport Kubernetes Service on the Kubernetes cluster you want to register.
In this setup, the Teleport Kubernetes Service pod detects that it is running on Kubernetes and registers the cluster automatically.
You can also run the Teleport Kubernetes Service on a Linux host in a separate network from your Kubernetes cluster. Learn how in Kubernetes Access from a Standalone Teleport Cluster.
Prerequisites
-
A Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
-
A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.0.0.See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
Please use the latest version of Teleport Enterprise documentation.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com
-
Kubernetes >= v1.17.0
-
Helm >= 3.4.2
Verify that Helm and Kubernetes are installed and up to date.
helm versionversion.BuildInfo{Version:"v3.4.2"}
kubectl versionClient Version: version.Info{Major:"1", Minor:"17+"}
Server Version: version.Info{Major:"1", Minor:"17+"}
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands on your administrative workstation using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.0.0
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
Deployment overview
In this guide, we deploy the Teleport Kubernetes Service, which connects a Kubernetes cluster to a Teleport cluster:
In your Teleport Cloud account, the name of your cluster will be your tenant
domain name, e.g., mytenant.teleport.sh
, rather than teleport.example.com
.
Step 1/3. Get a join token
In order to start the Teleport Kubernetes Service, we will need to request a join token from the Teleport Auth Service:
Create a join token for the Teleport Kubernetes Service to authenticate
TOKEN=$(tctl tokens add --type=kube,app,discovery --ttl=1h --format=text)echo $TOKEN
Step 2/3. Deploy teleport-kube-agent
The Teleport Kubernetes Service version should be the same as the Teleport Cluster version
or up to one major version back. You can set the version override with the override variable, ex: --set teleportVersionOverride=14.0.0
.
To allow Helm to install charts that are hosted in the Teleport Helm repository, use helm repo add
:
helm repo add teleport https://charts.releases.teleport.dev
To update the cache of charts from the remote repository, run helm repo update
:
helm repo update
Switch kubectl
to the Kubernetes cluster cookie
and run the following
commands, assigning PROXY_ADDR
to the address of your Auth Service or Proxy
Service.
PROXY_ADDR=teleport.example.com:443CLUSTER=cookieCreate the values.yaml file
cat > values.yaml << EOFauthToken: "${TOKEN}"proxyAddr: "${PROXY_ADDR}"roles: "kube,app,discovery"joinParams: method: "token" tokenName: "${TOKEN}"kubeClusterName: "${CLUSTER}"EOFInstall the helm chart with the values.yaml setting
helm install teleport-agent teleport/teleport-kube-agent \ -f values.yaml \ --create-namespace \ --namespace=teleport-agent \ --version 14.0.0
Switch kubectl
to the Kubernetes cluster cookie
and run the following
commands, assigning PROXY_ADDR
to the address of your Auth Service or Proxy
Service.
PROXY_ADDR=teleport.example.com:443CLUSTER=cookieCreate the values.yaml file
cat > values.yaml << EOFauthToken: "${TOKEN}"proxyAddr: "${PROXY_ADDR}"roles: "kube,app,discovery"joinParams: method: "token" tokenName: "${TOKEN}"kubeClusterName: "${CLUSTER}"enterprise: trueEOFInstall the helm chart with the values.yaml setting
helm install teleport-agent teleport/teleport-kube-agent \ -f values.yaml \ --create-namespace \ --namespace=teleport-agent \ --version 14.0.0
Please use the latest version of Teleport Enterprise documentation.
Make sure that the Teleport agent pod is running. You should see one Teleport agent pod pod with a single ready container:
kubectl -n teleport get podsNAME READY STATUS RESTARTS AGEteleport-agent-0 1/1 Running 0 32s
Step 3/3 Access your Kubernetes cluster
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: v7
spec:
allow:
kubernetes_labels:
'*': '*'
kubernetes_resources:
- kind: '*'
namespace: '*'
name: '*'
verbs: ['*']
kubernetes_groups:
- viewers
kubernetes_users:
# Replace USER with the Kubernetes user for your current context.
- USER
deny: {}
Apply your changes:
tctl create -f kube-access.yaml
Assign the kube-access
role to your Teleport user by running the appropriate
commands for your authentication provider:
-
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml -
Edit
out.yaml
, addingkube-access
to the list of existing roles:roles: - access - auditor - editor + - kube-access
-
Apply your changes:
tctl create -f out.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
github
authentication connector:tctl get github/github --with-secrets > github.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thegithub.yaml
file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource. -
Edit
github.yaml
, addingkube-access
to theteams_to_roles
section.The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.
Here is an example:
teams_to_roles: - organization: octocats team: admins roles: - access + - kube-access
-
Apply your changes:
tctl create -f github.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
saml
configuration resource:tctl get --with-secrets saml/mysaml > saml.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thesaml.yaml
file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource. -
Edit
saml.yaml
, addingkube-access
to theattributes_to_roles
section.The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
attributes_to_roles: - name: "groups" value: "my-group" roles: - access + - kube-access
-
Apply your changes:
tctl create -f saml.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
oidc
configuration resource:tctl get oidc/myoidc --with-secrets > oidc.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to theoidc.yaml
file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource. -
Edit
oidc.yaml
, addingkube-access
to theclaims_to_roles
section.The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
claims_to_roles: - name: "groups" value: "my-group" roles: - access + - kube-access
-
Apply your changes:
tctl create -f oidc.yaml -
Sign out of the Teleport cluster and sign 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.
View pods in your cluster
List connected clusters using tsh kube ls
and switch between
them using tsh kube login
:
tsh kube lsKube Cluster Name Selected
----------------- --------
cookie
kubeconfig now points to the cookie cluster
tsh kube login cookieLogged into kubernetes cluster "cookie". Try 'kubectl version' to test the connection.
kubectl command executed on `cookie` but is routed through the Teleport cluster.
kubectl get pods
Next Steps
- Take a look at a kube-agent helm chart reference for a full list of parameters.