Machine ID v14 Upgrade Guide

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 tbot using only the CLI parameters.

Summary of breaking changes

Previously, the 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.

Because each 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 as a destination is now an output. Unlike a destination, an output has 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.

Migrating configuration files

On start, 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 permanently. 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.

Migration failure

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 tbot 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.