Implement storage versioning

[serathius]

Implementing a backward compatibility for etcd data directory is a prerequisite to implement downgrades (https://github.com/etcd-io/etcd/issues/11716)

Proposal https://docs.google.com/document/d/1yD0GDkxqWBPAax6jLZ97clwAz2Gp0Gux6xaTrtJ6wHE/edit?usp=sharing

Milestone 1

Storage version is available for snapshots.

• [x] Etcd saves storage version during first raft snapshot #13070
• [x] During bootstrap etcd should panic when encountering higher version https://github.com/etcd-io/etcd/pull/13200
• [x] Add etcdutl migrate --force as an escape hatch https://github.com/etcd-io/etcd/pull/13220

Milestone 2

Etcd code is version aware making downgrade implementation possible

• [ ] Implement version gating for all features
• [x] Implement version annotations for golang structs and proto https://github.com/etcd-io/etcd/pull/13216
• [x] Create a DB file schema
  • Abstract modification of DB fields
  • https://github.com/etcd-io/etcd/pull/13155
  • https://github.com/etcd-io/etcd/pull/13160
  • https://github.com/etcd-io/etcd/pull/13161
  • https://github.com/etcd-io/etcd/pull/13162
  • https://github.com/etcd-io/etcd/pull/13163
  • https://github.com/etcd-io/etcd/pull/13164
  • https://github.com/etcd-io/etcd/pull/13165
• [x] Add static analysis to validate annotations https://github.com/etcd-io/etcd/pull/13490
• [x] Implement simple downgrade upgrade tests that verify storage versioning (https://github.com/etcd-io/etcd/pull/13405)

Milestone 3

Downgrades can be implemented based on storage versioning

• [x] Etcd should validate storage version during bootstrap
• [x] Etcdutl migrate can upgrade and downgrade data dir files
  • [ ] Fix ClusterVersionSet blocking downgrades to v3.5

Followups

• [ ] Fix setting clusterversion after downgrade&upgrade timeout
• [ ] Automate snapshotting on downgrade

[lilic]

Thanks for the detailed document and this issue! 🎉 Looks good overall to me.

What is the diff between this in milestone 1:

Add etcdutl migrate --force as an escape hatch

and this task in milestone 2?

Implement etcdutl migrate

Also, could we have some issues open for contributions? For example if someone new or existing contributors want to contribute one or two of these tasks maybe?

[serathius]

What is the diff between this in milestone 1:

Add etcdutl migrate --force as an escape hatch

and this task in milestone 2?

Implement etcdutl migrate

First milestone introduces storage version that should be used to prevent using outdated tools/etcd to load storage data. For example etcd v3.6 should not be able to start from data left by v3.7 without doing explicit downgrade of this data.

This is technically a breaking change as currently you could technically load etcd v3.4 data by etcd v3.0 and vice versa. Official we only support only one by one upgrade (v3.0 -> v3.1 -> v3.2 -> v3.3 -> v3.4) and no downgrades (use backup), but there is no mechanism that would prevent user from shutting themselves in a foot.

Milestone 1 introduces mechanism to explicitly prevent this, so we need to introduce an escape hatch for users that still want to do an downgrade, but they should do it explicitly by running migrate --force.

Difference between Milestone 1 and 3 etcdutl migrate is that the first one just implements the escape hatch, and the second whole schema upgrades and downgrades.

[serathius]

Also, could we have some issues open for contributions? For example if someone new or existing contributors want to contribute one or two of these tasks maybe?

As implementing versioning of storage touches basically whole server codebase I was worried about potential code conflicts before we update the codebase structure. To minimize future conflicts I have started from large scale refactors to restructure code to accommodate versioning, but got bottle-necked on reviews.

Currently I have local going couple of PR in future as my published PRs are waiting for review from a week. I don't think adding new contributors will help the effort or be a good experience as they would have the same problem.

I'm happy to start creating issues when the ground work will be done.

[serathius]

@YoyinZyc @hexfusion @wenjiaswe @ptabor Could you do a review the design and give an approval on the design, so we have a community consensus and can move forward with implementing the breaking changes.