Fork me on GitHub

Teleport

Get started with Teleport on DigitalOcean Kubernetes

Improve

This guide will show you how to get started with Teleport on DigitalOcean Kubernetes.

Teleport Cloud takes care of this setup for you so you can provide secure access to your infrastructure right away.

Get started with a free trial of Teleport Cloud.

Prerequisites

  • DigitalOcean account.
  • Your workstation configured with kubectl, Helm, doctl, and the Teleport tsh client.

Step 1/4. Create a DigitalOcean Kubernetes cluster

Create a new DigitalOcean Kubernetes Cluster

Create DigitalOcean Kubernetes cluster


While the Kubernetes cluster is being provisioned, follow the "Getting Started" guide as shown below:

Set up DigitalOcean Kubernetes client

Step 2/4. Install Teleport

Add the Teleport repository to Helm.

helm repo add teleport https://charts.releases.teleport.dev

Install Teleport in your Kubernetes cluster using the teleport-cluster Helm chart.

CLUSTERNAME=tele.example.com # replace with your preferred domain name
[email protected] # replace with your email
helm install teleport-cluster teleport/teleport-cluster --create-namespace --namespace=teleport-cluster \ --set clusterName=$CLUSTERNAME \ --set acme=true \ --set acmeEmail=$EMAIL_ADDR

NAME: teleport-cluster

LAST DEPLOYED: Tue Oct 26 17:01:21 2021

NAMESPACE: teleport-cluster

STATUS: deployed

REVISION: 1

TEST SUITE: None

Update DNS for clusterName

First, get the external IP (from the EXTERNAL-IP field) for the Kubernetes cluster.

kubectl --namespace=teleport-cluster get services

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

teleport-cluster LoadBalancer 10.245.163.12 192.168.200.200 443:31959/TCP,3023:30525/TCP,3026:30079/TCP,3024:32437/TCP 19m

Once you get the value for the external IP (it may take a few minutes for this field to be populated), update your DNS record such that the clusterName's A record points to this IP address. For example 192.168.200.200 is the external IP in the above case.

Configure DNS

Step 3/4. Create and set up Teleport user

Now we create a Teleport user by executing the tctl command with kubectl.

kubectl --namespace teleport-cluster exec deploy/teleport-cluster -- tctl users add tadmin --roles=access,editor --logins=ubuntu

User "tadmin" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:

https://tele.example.com:443/web/invite/<invite-token>

NOTE: Make sure tele.teleporters.dev:443 points at a Teleport proxy which users can access.

Copy the link shown after executing the above command and open the link in a web browser to complete the user registration process (the link is https://tele.teleporters.dev:443/web/invite/<invite-token> in the above case).

Setup user

After you complete the registration process by setting up a password and enrolling in two-factor authentication, you will be logged in to Teleport Web UI.

In this step, we created a user tadmin with roles access, edit. These are the default roles available in Teleport. However, to allow this user to access the Kubernetes cluster, we will need to assign tadmin a role authorized to access the Kubernetes cluster. So first, let's create a role named member with the Kubernetes privilege system:master.

Create a new Kubernetes Role named "member"

Create a file named member.yaml with the following spec:

kind: role
version: v4
metadata:
  name: member
spec:
  allow:
    kubernetes_groups: ["system:masters"]
Warning

system:masters is a Kubernetes built-in role that is similar to sudo permissions in Linux systems. It is used here for demonstration purposes and should be used in production only when necessary.

Next, create this role in Kubernetes with the command:

POD=$(kubectl --namespace=teleport-cluster get pod -l app=teleport-cluster -o jsonpath='{.items[0].metadata.name}')
kubectl --namespace=teleport-cluster exec -i ${POD?} -- tctl create -f < member.yaml

Assign the "member" role to user "tadmin"

Now we will assign Teleport user tadmin with this role. The example below shows a process using Teleport Web UI: First, lets select user edit menu:

Edit user

Second, update the tadmin user role to assign the member role:

Update role

We've updated the user tadmin to have the member role, which is allowed to access a Kubernetes cluster with privilege system:master.

Step 4/4. Access your Kubernetes cluster using Teleport

The following steps show how to access the Kubernetes cluster using tsh.

Log in to Teleport

First, authenticate to Teleport using tsh as the tadmin user we created in the third step.

Note

The following process will override your global kubectl configuration file. To write your kubectl configuration to a separate file instead of having your global kubectl configuration modified, run the following command:

export KUBECONFIG=${HOME?}/teleport-kubeconfig.yaml
tsh login --proxy=tele.teleporters.dev:443 --auth=local --user=tadmin

Enter password for Teleport user tadmin:

Enter your OTP token:

540255

> Profile URL: https://tele.example.com:443

Logged in as: tadmin

Cluster: tele.example.com

Roles: access, editor, member

Logins: ubuntu

Kubernetes: enabled

Valid until: 2021-10-27 06:37:15 +0000 UTC [valid for 12h0m0s]

Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty

Grant Kubernetes cluster access to your user

To use Teleport to interact with a Kubernetes cluster, your Teleport roles must allow access from your Kubernetes user and groups. 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[?(@.context.cluster==\"$(kubectl config current-context)\")].context.user}"

Create a file called kube-user.yaml with the following content, replacing USER with the output of the command above.

kind: role
metadata:
  name: kube-user
version: v5
spec:
  allow:
    kubernetes_labels:
      '*': '*'
    kubernetes_groups:
    - view
    kubernetes_users:
    - USER
  deny: {}

Retrieve your user:

TELEPORT_USER=myuser
tctl get user/${TELEPORT_USER?} > user.yaml

Add kube-user to your Teleport user's list of roles:

   roles:
   - access
   - auditor
+  - kube-user

Apply your changes:

tctl create -f kube-user.yaml
tctl create -f user.yaml

Log out of Teleport and log in again.

Select the Kubernetes cluster

tsh kube login tele.example.com

Logged into kubernetes cluster "tele.example.com". Try 'kubectl version' to test the connection.

Connect to the Kubernetes cluster

kubectl --namespace=teleport-cluster get pods

NAME READY STATUS RESTARTS AGE

teleport-cluster-6cc679b6f6-7xr5h 1/1 Running 0 14h

Voila! User tadmin was able to list the pods in their DigitalOcean Kubernetes cluster.

Teleport keeps an audit log of access to a Kubernetes cluster. In the screenshot below, the Teleport audit log shows that the user tadmin has logged into the cluster.

View audit log

Next steps