Migrating from Self-Hosted to Teleport Enterprise Cloud

[pschisa]

Overview

Migrating from a self-hosted Teleport deployment to the Teleport Cloud is a simple process that can be accomplished all at once or in a gradual manner. The steps to migrate from your self-hosted cluster to a Teleport Cloud cluster can be sumarrized as follows:

1. Create and access your Teleport Cloud cluster
2. Migrate over the necessary Teleport configurations to your new Teleport Cloud cluster (SSO, users, roles)
3. Migrate your Teleport agents to the new Teleport Cloud cluster
4. Verify end user access, performance, and break glass procedures on Teleport Cloud

Create your Teleport Cloud Cluster

Follow our documentation to sign up for a new cloud account.

Be sure to save the recovery codes! For your security, Teleport support cannot help reset passwords or recover lost account credentials.

Subscribe to the https://status.teleport.sh/ to stay up to date on any issues impacting Teleport Cloud performance.

Recreate Teleport Configurations

You will want to recreate the following team resources from your current Teleport cluster:

• Roles
• Local Users
• SSO Auth Connector
• Trusted Clusters*

If not using our Terraform Provider already to manage your infrastructure as a code, roles and local users can be migrated easily using the tctl administrative tool. You can use tctl get to download configurations from your self-hosted cluster and tctl create to rebuild those configurations. Here is an example of getting the roles:

Self-hosted: 
tctl get roles > roles.yaml
Teleport Cloud:
 tsh login
tctl create -f roles.yaml

The SSO connector cannot be moved as easily since most SSO integrations will only work for a single endpoint as configured. If not migrating all at once, it is recommended to build a separate SSO connector in your Identity Provider for the Teleport Cloud cluster and configure a new auth connector.

Trusted Clusters are no longer supported in Teleport Cloud.

Migrate the Teleport agents

The following resources should be considered at this point for the migration if used:

• Teleport agents (SSH, Kubernetes, Database, Applications, Desktops)
• Machine ID bots
• Access Request Plugins

The following is the general procedure for migrating a Teleport agent:

1. Create a valid join token in the Teleport Cloud cluster for your agent(s) using the tctl tokens add command
2. Stop the Teleport service (if applicable)
3. Change the proxy_server or auth_servers setting in the agent configuration (default /etc/teleport.yaml) to point your Teleport Cloud proxy:

proxy_server:
- example.teleport.sh:443

4. Update the auth_token setting in your agent configuration to be the valid auth token on the Teleport Cloud Cluster
5. Delete the local agent cache to force the agent through the new cluster join process. By default, this data is located in the /var/lib/teleport/ directory
6. Start the Teleport service or recycle the pod

The migration of all Teleport agents can happen in one push or gradually depending on what suits your business needs. If going for a gradual migration, the use of our Trusted Cluster feature will enable end users to not have to log in to separate Teleport clusters during the migration. While it is technically possible to run two Teleport processes on a single agent to connect to both clusters simultaneously, we do not recommend this option due to added administrative complexity.

Verify end user access, performance, and break glass procedures

Once the initial resource migration is complete, confirm your end users have the expected access. Ensure that their workflow has taken no serious latency or performance degradation as a result of the change.

It is also important at this point to be ready with break glass access should Teleport Cloud ever become unavailable. It is recommended to have a secure alternative means of accessing infrastructure accessible to admins in the case of an outage.