Guide: Migrate from Teleport Open Source to Enterprise

[yjperez]

Migrate to Teleport Self-Hosted

Prerequisites

• An existing Teleport Open Source (OSS) Cluster.
• A downloaded Teleport Enterprise license file.
• The tsh and tctl client tools. This guide assumes that you are using tctl to manage dynamic resources, but it is also possible to use Teleport Terraform provider and Kubernetes operator, in addition to custom scripts that use the Teleport API to manage the Teleport Auth Service backend.

Back-up Resources

Back-up your users and roles

tctl get roles > roles.yaml
tctl get users > users.yaml

Prepare for Upgrade

1. Add the license file to all Auth Servers

• Recommend placing your license file in the Teleport data directory.
• By default the data directory is located /var/lib/teleport

2. Update the Teleport configuration file

• The default location is /etc/teleport.yaml
• The file must be updated to include the license file location

auth_service:
  license_file: /var/lib/teleport/license.pem

3. Rename the Open Source binary of Teleport

To install the new binary the OSS binary should be renamed or removed to prevent conflicts. If renamed, it can serve as a back-up.

Find the teleport binary:

which teleport

Rename the old binary:

mv /usr/local/bin/teleport /usr/local/bin/teleport-oss
mv /usr/local/bin/tctl /usr/local/bin/tctl-oss
mv /usr/local/bin/tsh /usr/local/bin/tsh-oss

Download and install the Teleport Enterprise binary

It is recommended you install the same major version of Teleport you have installed.

To check your version of Teleport and set variables for download:

tctl version 

Set Environment Variables

TELEPORT_EDITION="enterprise"
TELEPORT_VERSION="16.4.12"
TELEPORT_DOMAIN="teleport.example.com"

Download and install the Teleport Enterprise binary

curl https://cdn.teleport.dev/install-v${TELEPORT_VERSION}.sh | bash -s ${TELEPORT_VERSION?} ${TELEPORT_EDITION?}

Restart Teleport service and check the status

systemctl restart teleport && systemctl status teleport

Verify you are running the Enterprise version

curl https://${TELEPORT_DOMAIN}/web/config.js | sed -n 's/.*"edition":"\([^"]*\)".*/edition: \1/p'

Validate User Access and Performance

Verify access to the Teleport Cluster

Your roles, and local users should have been carried over from OSS to the ENT version of Teleport. You should be able to log right in.

If you are unable to login to your cluster or your users/roles did not migrate, you are able to import manually from previous backups.

Access the auth servers and apply the backup files.

tctl apply roles.yaml
tctl apply users.yaml

Verify resources are connected

After a couple minutes all your resources should automatically reconnect to your cluster. Confirm you are able to connect to them.

Migrate to Teleport Cloud

Follow the cloud migration guide