Fork me on GitHub

Getting Started - Kubernetes with SSO

Getting Started with Teleport for Kubernetes Access

Getting Started with Teleport for Kubernetes Access

Length: 23:14

Getting Started

Let's deploy Teleport in a Kubernetes with SSO and Audit logs:

  • Install Teleport in a Kubernetes cluster.
  • Set up Single Sign-On (SSO).
  • Capture and playback Kubernetes commands.


Verify that helm and kubernetes are installed and up to date.

$ helm version
# version.BuildInfo{Version:"v3.4.2"}

$ kubectl version
# Client Version: version.Info{Major:"1", Minor:"17+"}
# Server Version: version.Info{Major:"1", Minor:"17+"}

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.


  1. We discourage using sudo in production environments unless it's needed.
  2. We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
  3. 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.
  4. Saving tokens into a file rather than sharing tokens directly as strings.

Learn more about Teleport Role-Based Access Control best practices.

Step 1/3. Install Teleport

Let's start with a single-pod Teleport using persistent volume as a backend.

helm repo add teleport

Install a single node teleport cluster and provision a cert using ACME.

Set clusterName to unique hostname, for example

Set acmeEmail to receive correspondence from Letsencrypt certificate authority.

helm install teleport-cluster teleport/teleport-cluster --create-namespace --namespace=teleport-cluster \ --set clusterName=${CLUSTER_NAME?} --set acme=true --set acmeEmail=${EMAIL?}

Teleport's helm chart uses an external load balancer to create a public IP for Teleport.

Set kubectl context to the namespace to save some typing

kubectl config set-context --current --namespace=teleport-cluster

Service is up, load balancer is created

kubectl get services


teleport-cluster LoadBalancer 443:31204/TCP,3026:32690/TCP 89s

Save the pod IP or Hostname. If the IP is not available, check the pod and load balancer status.

MYIP=$(kubectl get services teleport-cluster -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo $MYIP

Set up two A DNS records - for UI and * for web apps using application access.


gcloud dns record-sets transaction start --zone="${MYZONE?}"
gcloud dns record-sets transaction add ${MYIP?} --name="${MYDNS?}" --ttl="30" --type="A" --zone="${MYZONE?}"
gcloud dns record-sets transaction add ${MYIP?} --name="*.${MYDNS?}" --ttl="30" --type="A" --zone="${MYZONE?}"
gcloud dns record-sets transaction describe --zone="${MYZONE?}"
gcloud dns record-sets transaction execute --zone="${MYZONE?}"

The first request to Teleport's API will take a bit longer because it gets a cert from Let's Encrypt. Teleport will respond with discovery info:



Step 2/3. Create a local admin

Local users are a reliable fallback for cases when the SSO provider is down. Let's create a local admin alice who has access to Kubernetes group system:masters.

Save this role as member.yaml:

kind: role
version: v4
  name: member
    kubernetes_groups: ["system:masters"]

Create the role and add a user:

To create a local user, we are going to run Teleport's admin tool tctl from the pod.

POD=$(kubectl get pod -l app=teleport-cluster -o jsonpath='{.items[0]}')

Create a role

kubectl exec -i ${POD?} -- tctl create -f < member.yaml

Generate an invite link for the user.

kubectl exec -ti ${POD?} -- tctl users add alice --roles=member

User "alice" has been created but requires a password. Share this URL with the user to

complete user setup, link is valid for 1h:

NOTE: Make sure points at a Teleport proxy which users can access.

Let's install tsh and tctl on Linux. For other install options, check out install guide

curl -L -O
tar -xzf teleport-v7.1.3-linux-amd64-bin.tar.gz
sudo mv teleport/tsh /usr/local/bin/tsh
sudo mv teleport/tctl /usr/local/bin/tctl

Try tsh login with a local user. Use a custom KUBECONFIG to prevent overwriting the default one in case there is a problem.

KUBECONFIG=${HOME?}/teleport.yaml tsh login --user=alice

Teleport updated KUBECONFIG with a short-lived 12-hour certificate.

List connected Kubernetes clusters

tsh kube ls

Kube Cluster Name Selected

----------------- --------

Login to Kubernetes by name

tsh kube login

Once working, remove the KUBECONFIG= override to switch to teleport

KUBECONFIG=${HOME?}/teleport.yaml kubectl get -n teleport-cluster pods


teleport-cluster-6c9b88fd8f-glmhf 1/1 Running 0 127m

Step 3/3. SSO for Kubernetes

We are going to setup Github connector for OSS and Okta for Enterprise version.

Save the file below as github.yaml and update the fields. You will need to set up Github OAuth 2.0 Connector app. Any member with the team admin in the organization octocats will be able to assume a builtin role admin.

kind: github
version: v3
  # connector name that will be used with `tsh --auth=github login`
  name: github
  # client ID of Github OAuth app
  client_id: client-id
  # client secret of Github OAuth app
  client_secret: client-secret
  # This name will be shown on UI login screen
  display: Github
  # Change to your domain name
  # Map github teams to teleport roles
    - organization: octocats # Github organization name
      team: admin            # Github team name within that organization
      # map github admin team to Teleport's "admin" role
      logins: ["access"]

To create a connector, we are going to run Teleport's admin tool tctl from the pod.

kubectl config set-context --current --namespace=teleport-cluster
POD=$(kubectl get po -l app=teleport-cluster -o jsonpath='{.items[0]}')

kubectl exec -i ${POD?} -- tctl create -f < github.yaml

authentication connector "github" has been created

Try tsh login with Github user. I am using a custom KUBECONFIG to prevent overwriting the default one in case there is a problem.

KUBECONFIG=${HOME?}/teleport.yaml tsh login --auth=github
Debugging SSO

If you are getting a login error, take a look at the audit log for details:

kubectl exec -ti "${POD?}" -- tail -n 100 /var/lib/teleport/log/events.log

{"error":"user \"alice\" does not belong to any teams configured in \"github\" connector","method":"github","attributes":{"octocats":["devs"]}}

Next steps

Have a suggestion or can’t find something?