Secure Access for Kubernetes

The Basics

Teleport offers an identity-based access proxy for multiple Kubernetes clusters. Following are the important points on how Kubernetes access works:

• Users receive short-lived kubeconfig files (and certificates) using Single Sign-On (SSO) and switch between Kubernetes clusters without logging in twice.
• Admins use roles to implement policies, such as the best practice that developers must not access production.
• Admins can host the Teleport Auth Service and Teleport Proxy Service within a Kubernetes Cluster.
• kubectl events and sessions can be recorded for security and compliance purposes.

Architecture

This section assumes that you are already familiar with basic Teleport architecture and understand the concept of a Teleport Cluster

Let's consider a simple environment on a private network with a single Kubernetes cluster. To enable access to this cluster from a public network via Teleport:

• The Kubernetes integration must be enabled in the Teleport Proxy Service configuration file.
• The Teleport Proxy Service should be given Kubernetes API access with permissions to use the user impersonation. The easiest way to do this is to deploy the Teleport Proxy Service into a Kubernetes cluster and give its service account the right permissions.

The location of the Teleport Auth Service does not matter as long as the Teleport Proxy Service can connect to it. If SSH connectivity is required, any SSH node can be accessed via Teleport regardless of whether it is a part of Kubernetes or not, as long as:

• The Teleport Proxy Service can connect to a node.
• A node can connect to the Teleport Auth Service.

The diagram below illustrates the typical Teleport deployment into a Kubernetes cluster.

In the example above:

1. Teleport Proxy and Teleport Auth services are both deployed into the Kubernetes cluster as pods.
2. Connections over the internal Kubernetes cluster network are marked as "A" and connections from outside the Kubernetes network are marked as "B".
3. Teleport Proxy Service is exposed to the outside world via a Kubernetes service of the Load Balancer type. It has a fully qualified domain name with proper HTTP/TLS encryption, in this example it is https://proxy.example.com
4. Teleport Auth Service is exposed to the internal network (but external to Kubernetes), i.e. a VPC on AWS or VLAN in a traditional data center, the same network on which non-Kubernetes SSH nodes are running.

The Teleport Auth Service maintains a list of Teleport roles. Each Teleport role is mapped to a set of Kubernetes groups and they, in turn, are mapped to an identity provider such as Okta or Active Directory. This is how synchronization of permissions works across SSH and Kubernetes.

User Experience

On the client, users must authenticate using the tsh command-line utility, which opens the web browser if SSO authentication is configured. Upon successful authentication, tsh automatically updates ~/.kube/config file for all Kubernetes tools:

# login:
$ tsh login --proxy=proxy.example.com

# access Kubernetes cluster API:
$ kubectl get pods

# or SSH into a node:
$ ssh node

The access will be automatically revoked when the Teleport-issued certificate's time to live (TTL) expires. Users may also explicitly log out if using someone else's untrusted computer:

$ tsh logout

Using Multiple Clusters

If Teleport is configured with multiple Kubernetes clusters, users may choose which one to connect to by executing tsh login <cluster-name>. If a user already has a valid certificate, this command does not trigger the SSO login prompt. It only updates ~/.kube/config with the selected cluster.

# print the list of trusted clusters:
$ tsh clusters
staging
production

# select the staging cluster, this command updates ./kube/config:
$ tsh login staging

# talk to Kubernetes API:
$ kubectl get pods

How do multiple Kubernetes clusters work?

As you can see, each Kubernetes cluster becomes a Teleport cluster if Teleport is deployed inside of one. Teleport has the ability to connect multiple clusters together. For example, you have multiple Kubernetes clusters set up similarly to the diagram above, you can configure Teleport to proxy users between multiple clusters.

This capability is called "Trusted Clusters" or "Remote Clusters" and you can read more about it in the SSH and Kubernetes on the Edge page.