[Teleport Docker Compose] Run Teleport with Docker Compose

Run Teleport with Docker Compose

Teleport is a Certificate Authority and an Access Plane for your infrastructure. With Teleport you can:

  • Set up Single Sign-On and have one place to access your SSH servers, Kubernetes, Databases, Desktops, and Web Apps.

  • Use your favorite programming language to define access policies to your infrastructure.

  • Share and record interactive sessions across all environments.

This article will help you understand how Teleport works using Docker Compose. It will also show you how to use Teleport with OpenSSH, Ansible, and Teleport’s native client, tsh.

Prerequisites

  • Teleport v9.0.0 Open Source or Enterprise.

  • Docker v20.10.7 or later and docker-compose v1.25.0 or later.

1
2
3
4
5
6
$ docker-compose version
docker-compose version 1.25.0, build unknown

$ docker version
Client: Docker Engine - Community
Version: 20.10.7

Configuration

Teleport uses the YAML file format for configuration. A full configuration reference file is shown below, this provides comments and all available options for teleport.yaml By default, it is stored in /etc/teleport.yaml.

1
2
3
4
$ docker run --hostname localhost --rm \
--entrypoint=/bin/sh \
-v ${PWD}/runtime/teleport/etc/teleport:/etc/teleport \
quay.io/gravitational/teleport:9.0.1 -c "teleport configure > /etc/teleport/teleport.yaml"

It will generate teleport.yaml file in ./runtime/teleport/etc/teleport directory for container later.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# /etc/teleport.yaml

#
# A Sample Teleport configuration file.
# Creates a single proxy, auth and node server.
#
# Things to update:
# 1. license.pem: You only need a license from https://dashboard.goteleport.com
# if you are an Enterprise customer.
#
version: v2
teleport:
nodename: localhost
data_dir: /var/lib/teleport
log:
output: stderr
severity: INFO
format:
output: text
ca_pin: []
diag_addr: ""
auth_service:
enabled: "yes"

authentication:

# second_factor can be 'off', 'on', 'optional', 'otp', 'webauthn' or
# 'u2f'.
# - 'on' requires otp and either webauthn (preferred) or u2f.
# - 'optional' allows otp and either webauthn (preferred) or u2f.
# - 'otp', 'webauthn' and 'u2f' require their corresponding second
# factor type.
second_factor: off

listen_addr: 0.0.0.0:3025
proxy_listener_mode: multiplex
ssh_service:
enabled: "yes"
labels:
env: example
commands:
- name: hostname
command: [hostname]
period: 1m0s
proxy_service:
enabled: "yes"
https_keypairs: []
acme: {}

See Teleport Configuration Reference | Teleport Docs - https://goteleport.com/docs/setup/reference/config/ to learn more.

Run with Docker Compose

First, create docker-compose.yaml file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# docker-compose.yaml

# Compose file | Docker Documentation
# https://docs.docker.com/compose/compose-file/

version: "3"
services:
teleport:
# gravitational/teleport · Quay
# https://quay.io/repository/gravitational/teleport?tab=tags&tag=latest
image: quay.io/gravitational/teleport:9.0.1
ports:
- "3022:3022"
- "3023:3023"
- "3024:3024"
- "3025:3025"
- "3026:3026"
- "3027:3027"
- "3028:3028"
- "3036:3036"
- "3080:3080"
restart: always
volumes:
- ./runtime/teleport/etc/teleport:/etc/teleport
- ./runtime/teleport/var/lib/teleport:/var/lib/teleport

Then, run docker-compose up

1
$ docker-compose up

Usages

Explore CLI

Let’s jump into container with setup clients and explore Teleport:

From your local terminal

1
$ docker exec -ti teleport /bin/bash

We will run all future commands from the teleport container.


You can see Teleport’s nodes registered in the cluster using tsh ls command:

1
2
3
4
5
6
7
# From teleport container
$ tsh ls
Node Name Address Labels

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

localhost 127.0.0.1:3022 env=example,hostname=ce00cb46c587

Explore web UI

Create a Teleport user called cloudolife which is allowed to log in as either operating system user root or ubuntu.

1
2
# From term container
$ tctl users add cloudolife --roles=editor,access --logins=root,ubuntu

Teleport will output a URL that you must open to complete the user sign-up process:

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

`https://localhost:3080/web/invite/your-token-here


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


Port 443 on the Teleport container is published to the local host, so you can access the invitation page at https://localhost/web/invite/your-token-here.


INSECURE CERTIFICATE ERROR

If you encounter an “Insecure Certificate Error” (or equivalent warning) that prevents the Teleport Web UI from opening, you can perform one of the following actions depending on your browser:

  • In Safari’s “This Connection Is Not Private” page, click “Show Details,” then click “visit this website.”

  • In Firefox, click “Advanced” from the warning page, then click “Accept the Risk and Continue.”

  • In Chrome’s warning page, type thisisunsafe to ignore certificate validation for the Teleport Web UI.


Explore tsh CLI

Use tsh ssh to login and run tctl within Telepor.

1
2
3
4
5
6
7
8
9
10
11
$ tsh --proxy=localhost login --user=cloudolife --insecure
Enter password for Teleport user cloudolife:
WARNING: You are using insecure connection to SSH proxy https://localhost:3080
> Profile URL: https://localhost:3080
Logged in as: cloudolife
Cluster: localhost
Roles: access, editor
Logins: root, ubuntu, centos, pi, cloudolife
Kubernetes: enabled
Valid until: 2022-03-30 18:56:48 +0800 CST [valid for 12h0m0s]
Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty

Remember to ignore x509: certificate signed by unknown authority error with --insecure option.


List nodes within Teleport.

1
2
3
4
$ tsh ls
Node Name Address Labels
--------- -------------- ---------------------------------
localhost 127.0.0.1:3022 env=example,hostname=ce00cb46c587

Run tsh ssh to login localhost host within Teleport.

1
2
3
4
5
6
$ tsh ssh [email protected]

[email protected]:~# tctl nodes ls
Nodename UUID Address Labels
--------- ------------------------------------ -------------- ---------------------------------
localhost ef38168a-8310-496a-b48f-2a7187e9202b 127.0.0.1:3022 env=example,hostname=ce00cb46c587

See Using TSH | Teleport Docs - https://goteleport.com/docs/server-access/guides/tsh/, Teleport CLI Reference | Teleport Docs - https://goteleport.com/docs/setup/reference/cli/#tsh to learn more.

Create another Teleport user called col which is allowed to log in as either operating system user root or ubuntu.

1
2
# From [email protected] within Teleport
[email protected]:~# tctl users add col --roles=editor,access --logins=root,ubuntu

Add node into Teleport

It will generate an invite token to add node.

1
$ tctl nodes add

Run teleport start to register a host into Teleport as a node.

1
2
3
4
5
6
# On your host
$ sudo teleport start
--roles=node \
--token=6da632bb82d55f46908eb4dac4ba7a77 \
--ca-pin=sha256:2a06aa0297c232cbaddcf05889d04bf183323c18679df02c8e43f658fcbf1e6e \
--auth-server=localhost:3080 --insecure

See Server Access Getting Started Guide | Teleport Docs - https://goteleport.com/docs/server-access/getting-started/ to learn more.

Check nodes.

1
2
3
4
5
$ tctl nodes ls
Nodename UUID Address Labels
------------------------------- ------------------------------------ -------------- ---------------------------------
<Your Host>.local 26e1ac50-eea1-4dd0-9313-cdde9f7f6f1f
localhost 3b8c2e9c-91e0-4b27-9664-3a0369963984 127.0.0.1:3022 env=example,hostname=ce00cb46c587

Run tsh ssh to login your host through Teleport

1
$ tsh ssh <Your User Name>@<Your Host>.local

See Teleport CLI Reference | Teleport Docs - https://goteleport.com/docs/setup/reference/cli/#tctl to learn more.

Stop Teleport

You can stop the Teleport using:

1
$ docker-compose down

FAQs

ERROR: Get “https://localhost:3080/webapi/ping”: x509: certificate signed by unknown authority

1
2
$ tsh --proxy=localhost login --user=blogbin
ERROR: Get "https://localhost:3080/webapi/ping": x509: certificate signed by unknown authority

Remember to ignore x509: certificate signed by unknown authority error with --insecure option.

1
$ tsh --proxy=localhost login --user=cloudolife --insecure

References

[1] Getting started with Teleport using Docker Compose | Teleport Docs - https://goteleport.com/docs/getting-started/docker-compose/

[2] Teleport Configuration Reference | Teleport Docs - https://goteleport.com/docs/setup/reference/config/

[3] Using TSH | Teleport Docs - https://goteleport.com/docs/server-access/guides/tsh/

[4] Teleport CLI Reference | Teleport Docs - https://goteleport.com/docs/setup/reference/cli/#tsh

[5] Teleport CLI Reference | Teleport Docs - https://goteleport.com/docs/setup/reference/cli/#tctl

[6] Server Access Getting Started Guide | Teleport Docs - https://goteleport.com/docs/server-access/getting-started/

[7] Teleport: Easiest, most secure way to access infrastructure | Teleport - https://goteleport.com/

[8] Overview of Docker Compose | Docker Documentation - https://docs.docker.com/compose/

[9] Home - Docker - https://www.docker.com/