Machine ID v14 Upgrade Guide
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
Teleport 14.0 introduces a new version of the configuration format (v2) for
the Machine ID agent,
tbot. This guide explains the breaking changes present
between the v1 and v2 configuration format and how to migrate.
You do not need to take any action if:
- You do not use Machine ID.
- You configure
tbotusing only the CLI parameters.
tbot configuration contained a list of destinations. A
destination described what should be written, where it should be written, and
which credential attributes should be used.
destination had a large number of configuration fields, the
fields sometimes combined to produce unusable certificates.
To address this issue and simplify the configuration for Machine ID, Teleport 14
provides a new version of the configuration schema. The field previously known
destination is now an
output. Unlike a
a specific type. The concept of
destination remains, but now refers to where
artifacts should be read from and written to.
Here is an example of the v1 configuration:
destinations: - directory: path: /opt/machine-id roles: - editor app: grafana
Here is an example of the v2 configuration:
version: v2 outputs: - type: application roles: - editor destination: type: directory path: /opt/machine-id
See the configuration reference for details of the new configuration version and how to define outputs.
tbot will automatically attempt to migrate a v1 configuration to
v2 to continue operating without disruption. This migration is ephemeral and
is not written to disk.
We strongly recommend converting your configuration file from v1 to v2
tbot will emit a warning when it starts until you do so.
Determine the path of your current configuration file and the path you wish to write the migrated configuration file to. Then run:
tbot migrate -c /config.yaml -o /config.migrated.yaml
Inspect the migrated configuration file to ensure it meets your expectations,
and try running
tbot with it. If everything works as expected, replace your
original configuration file with the migrated one.
If migration fails, review the error logged by the migration command. In most
cases, the error will indicate where a problem was found or why your original
configuration can't be migrated. It might be that your original configuration
contains invalid or conflicting entries and that previous versions of
might not have validated for these.
If you are still unable to determine why your configuration will not migrate, seek guidance. If you have a support contract, submit a ticket. If you are using Teleport Community Edition, join our community Slack.