docs/pages/migrate-plans.mdx
This guide explains how to migrate from Teleport Community Edition, Teleport Enterprise (Self-Hosted) and Teleport Enterprise (Cloud) to another Teleport plan.
We recommend that you try out a Teleport demo cluster with Teleport Community Edition, migrate to Teleport Enterprise (Cloud) to roll out Teleport across your organization, and deploy a self-hosted Teleport Enterprise cluster if you have security and compliance requirements that Teleport Enterprise (Cloud) cannot address.
While in a cloud-hosted Teleport Enterprise plan, Teleport manages the Auth Service and Proxy Service for you, but you need to migrate dynamic resources and Teleport services yourself. In a self-hosted Teleport Enterprise plan, as well as Teleport Community edition, you must manage all Teleport components.
To migrate between Teleport plans:
Teleport Community Edition contains a small subset of Teleport features to enable users to try out Teleport. This guide assumes that you are not migrating from Teleport Enterprise to Teleport Community Edition.
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.Determine the teleport.sh subdomain you would like to use for your new
Teleport Enterprise account.
If you are migrating to Teleport Enterprise (Cloud) and the license dashboard for your self-hosted Teleport Enterprise cluster is already using your desired subdomain, you can contact Teleport Support to free up the domain for reuse.
Reach out to your Account Management team to set up your new Teleport Enterprise account.
If you are migrating to a self-hosted Teleport Enterprise account, plan and execute the deployment with the help of your Account Management team. To assist with this, read the documentation on Self-Hosting Teleport.
Ensure you are running Teleport Enterprise agents with versions that are
the same major or just one major version lower than the new Teleport
Enterprise account version. To check the versions of your Teleport
Enterprise agents, you can use the tctl command
to list the inventory of connected agents and their version:
# check for older versions
$ tctl inventory ls --older-than=<version>
# check for newer versions
$ tctl inventory ls --newer-than=<version>
We recommend that Teleport Enterprise (Self-Hosted) customers set up automatic updates to maintain a healthy set of Agents, and require this in Teleport Enterprise (Cloud). See how to Set up Automatic Agent Updates to incorporate this into your migration.
Validate connectivity to both the new Teleport Enterprise cluster and your
original Teleport Enterprise cluster. You should be able to connect to both
Teleport clusters and execute tctl commands using your current credentials.
Log in to the original Teleport cluster, replacing <Var name="enterprise.example.com" /> with the cluster domain name:
# Use the --auth flag instead of --user to log in with Single Sign-On.
$ tsh login --proxy=<Var name="enterprise.example.com" /> --user=<Var name="myuser" />
$ tctl status
Log in to the new Teleport Enterprise cluster, replacing <Var name="example.teleport.sh" /> with the domain name of your new cluster:
# Use the --auth flag instead of --user to log in with Single Sign-On.
$ tsh login --proxy=<Var name="example.teleport.sh" /> --user=<Var name="myuser" />
$ tctl status
Subscribe to the Teleport Enterprise status website to stay current on any issues impacting the performance of your new cluster.
<Admonition type="danger"
If you are migrating to a Teleport Enterprise (Cloud) cluster, ensure that the recovery codes displayed when you first set up your Teleport Enterprise (Cloud) account are saved securely, so as not to lose access. For your security, Teleport Support cannot assist with resetting passwords or recovering lost credentials.
</Admonition>After ensuring that both your original and new Teleport clusters are up and running, you can migrate dynamic Teleport resources from one cluster to the next.
Dynamic Teleport resources such as roles and local users are stored on the Teleport Auth Service backend. Since your original Teleport cluster uses a separate Auth Service backend from your new cluster, you must retrieve the resources on the first backend, then re-apply them against the second backend.
Review the dynamic resources list to see if any other resources need to be migrated. Some common dynamic resources includes:
windows_desktopappsdbslogin_ruleTo achieve this:
Log in to your original Teleport cluster and export a collection of the
above-mentioned dynamic resource configuration using the tctl
administrative tool. An example is shown below:
# Use the --auth flag instead of --user to log in with Single Sign-On.
$ tsh login --proxy=teleport.example.com [email protected]
$ tctl get roles > roles.yaml
$ tctl get users > users.yaml
Once you have the resource configuration file from the above, proceed to log in to your new Teleport Enterprise account with an admin user and create the resources from the exported files:
# Use the --auth flag instead of --user to log in with Single Sign-On.
$ tsh login --proxy=example.teleport.sh [email protected]
$ tctl create -f roles.yaml
$ tctl create -f users.yaml
We recommend managing dynamic resources with the Teleport Terraform provider or Kubernetes operator. In this case, you can configure these tools to manage dynamic resources on your new Teleport cluster.
</Admonition>For your SSO auth connector, most SSO integrations only work for a single configured endpoint. It is recommended to create a separate SSO connector in your Identity Provider specifically for the new Teleport Enterprise endpoint, and configure a new Auth Connector in the new Teleport Enterprise tenant.
To migrate services such as Teleport Agents, Machine & Workload Identity Bots, and plugins, start by cataloging the various services you're managing with Teleport. The following resources should be considered for migration:
Before migrating services, make sure you are logged in to your new Teleport Enterprise account.
You can migrate Teleport services all at once or gradually, depending on your business requirements. If running Teleport at scale, you'll generally want to use a configuration management tool to automate and streamline the process of carrying out the actions involved in migrating agent configurations.
To migrate Teleport Agents:
For each Agent and Machine & Workload Identity Bot, obtain a valid join token. We recommend using a delegated join method.
If using ephemeral tokens, ensure you specify the appropriate token type to
match the Teleport services. Token types can include node, app, kube,
db, windowsdesktop and others depending on the service you wish to join
to your Teleport Cluster.
In the following example, a new token is created with the TTL of fifteen minutes:
$ tctl tokens add --type node,app,db --ttl 15m
In this command, we assigned the token the node, app and db type,
indicating that it will allow an agent to join which is running the Teleport
ssh_service, db_service and app_service.
Copy the token so you can use it later in this guide.
Stop Teleport services on each Agent (if applicable).
If you are using Teleport repositories to install on Linux
update the repository channel to stable/cloud for Teleport
Enterprise (Cloud). For self-hosted Teleport Enterprise you can use the major version
stable/v(=teleport.major_version=) or if you are using automatic
upgrades the stable/rolling channel has all released versions.
If you are using Teleport Community Edition, uninstall Teleport
and install the enterprise edition of the teleport binary. You can confirm if the binary
is correct by running teleport version. The output will contain the words
Teleport Enterprise. The enterprise edition of the teleport
binary should be used when connecting to Teleport Enterprise (Cloud) or
Teleport Enterprise (Self-Hosted).
Update the proxy_server or auth_servers field in each Agent configuration
file to point to the address of your new Teleport Enterprise cluster. By
default, on Linux servers, the configuration is located in the
/etc/teleport.yaml directory:
version: v3
teleport:
proxy_server: example.teleport.sh:443
If your Agent configuration does not include a teleport.proxy_server
field, and instead has a teleport.auth_server or teleport.auth_servers
field, we recommend migrating your configuration to version: v3 and using
teleport.proxy_server.
With the teleport.proxy_server field, the Agent attempts to connect to the
Teleport cluster using a single mode, rather than multiple modes, which takes
less time and involves less functionality to troubleshoot.
Update the auth_token or join_params.token_name field with the newly
generated token.
teleport:
join_params:
method: token
token_name: new-token-goes-here
On Linux servers, delete the local Agent cache and restart the Teleport process
on each Agent to force the Agent to rejoin the new Teleport Enterprise cluster.
By default, the data is located in the /var/lib/teleport directory:
rm -rf /var/lib/teleport
If you are using the teleport-kube-agent Helm chart, wipe out existing
state and recycle the Kubernetes pod to rejoin the Kubernetes Agent(s) to the
new cluster. This will cause the Agents to re-register with the new Teleport
Enterprise cluster and obtain new certificates signed by the new cluster's
certificate authority.
# get the release name
helm -n <namespace> ls
# delete the state secret
kubectl -n <namespace> delete secret <release-name>-0-state
The settings for the new Teleport Kubernetes Agent should have the
enterprise value set to true.
In general, you can migrate a Machine & Workload Identity Bot using the following steps:
tbot configuration file, edit the proxy_server configuration field
to point to the new Teleport cluster address and port 443.tbot.To learn how to restart and configure a Bot for your infrastructure, read the Machine & Workload Identity deployment guide.
In general, you can migrate Teleport plugins using the following steps:
If you are using Machine & Workload Identity to produce credentials for the plugin, reconfigure the Bot to connect to the new Teleport cluster and restart the Bot.
Otherwise, connect to the new Teleport cluster with tctl and produce an
identity file manually, then make it available to the plugin.
Reconfigure the plugin by editing the teleport.address field of the plugin
configuration file to point to the address of the new Teleport cluster, with
port 443.
Restart the plugin.
For specific plugins running in your infrastructure, read the full documentation on:
Once you have migrated dynamic resources and reconfigured services to connect to your new Teleport cluster, ensure that the setup is complete.
Validate that all expected resources are present in the Teleport cluster and
verify their status and connectivity to ensure they are properly registered
and available for connections. You can either check via the Web UI, or use
tctl to get a list of all resources and verify their registration and
status.
For example, to list all nodes registered with the Teleport Cluster, you can run the command below:
$ tctl nodes ls
Similarly, to list all other registered resources, you can run the commands below:
List all registered Kubernetes clusters:
$ tctl kube ls
List all registered databases:
$ tctl db ls
List all registered applications:
$ tctl apps ls
List all registered Windows desktops:
$ tctl desktop ls
Ensure that end users have the expected SSO access to your infrastructure.
Establish break-glass access procedures to ensure access to infrastructure in case your new Teleport Enterprise cluster becomes unavailable.
For example, you can run OpenSSH with a limited key following our best practices on How to SSH properly.
We recommend configuring systemd to start OpenSSH for 5 minutes at boot, then shut it down. The master keys should be stored in a secure vault. To break the glass, obtain the master key, reboot the server, and connect using an OpenSSH client within 5 minutes.
For more information on using cloud-hosted Teleport Enterprise, refer to our documentation on signing up for a cloud-hosted Teleport Enterprise account.
Read the documentation on Self-Hosting Teleport Enterprise.