mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-05 03:33:24 +08:00
rosstimothy
8b6f9fd007
Historically migrations have been ad-hoc functions added and removed
from `lib/auth/init.go`. They are introduced for a major version
and removed in time for the following major version. The migrations
are applied during every boot sequence for the Auth service until
the migration is removed. This causes tracking which versions
introduced migrations challenging and slows down Auth start up time.
Persisting the migrations status in the backend allows Auth to only
execute a migration once. This improves start up time and provides
observability into the clusters migration state by inspecting the
backend. Migration state is stored in the backend at key
`migrations/current`. It's not available from tctl yet but can be
added to `tctl get` in a subsequent change.
All new migrations must be added to a new file in
`lib/auth/migration`. The file should follow the naming convention
`<version>_<friendly_identifer>.go`. For example, the existing
migration that created database CAs from host CAs was moved to
`lib/auth/0001_db_ca.go` as it is the first migration. The migration
package is also the entry point into executing migrations.
`migration.Apply` executes any outstanding migrations and persists
the status. When adding a new migration it must also be registered
within `migration.Apply` by adding to the migrations slice.
The structure added is meant to make migrations more discoverable
and make the process of adding a new migration easier. With the
new structure there are a few rules that must be adhered to.
1) All migrations must have a version - as dictated by the
`backend.Migration` interface.
2) Migration version must be unique and not skip any versions.
3) Migrations must not be removed or have their version altered
after they have been released.