[Ready for review] etcd-website: Update migration process guidance with etcdctl v3.4

[wendy-ha18]

This PR uses to update the document for migrate etcd v2 to etcd v3 at this issue: #798

Website review link: https://deploy-preview-1044--etcd.netlify.app/docs/v3.4/how-to-migrate/

• Add prerequisites.
• Define all variables and flags used in the examples in a bulleted list.
• Describe process of migration.
• Add note to guide user that etcdctl migrate command was removed in etcd v3.5.0 (pull/12971). They must use etcdctl v3.4 or earlier to perform the migration (CHANGELOG-3.5). Reference this issue: Missing command: migrate etcd#14058.
• Included a link explaining the difference between etcd storage format and etcd version.
  • Clarified that the doc guides users on migrating etcd v2store to v3store. All mentions of “v2” and “v3” have been updated to “v2store” and “v3store” for consistency.
  • Added a couple of sentences at the top explaining how v2store relates to etcd v2.X.
  • Added a reference to the official guide for migrating API v2 → API v3 to avoid confusion: https://etcd.io/docs/v3.4/op-guide/v2-migration/.
• Removed the GIF.

[wendy-ha18]

Hi @nate-double-u @jberkus @ronaldngounou, this PR is ready to review. I'm a bit hesitate to backport to v3.7 cause I want to get feedbacks for it first. Please help me revise the migration process here. Thanks everyone!

[nate-double-u]

I think there are a couple paths here:

1. if we don't want to support migration from v2 to v3.5 and above, then we should remove migration from v3.5, v3.6, and v3.7.
2. if we do want to keep supporting migration then it looks like the path is to go from v2 to v3.4, then do a stepwise upgrade from there (v3.4 to v3.5, v3.5 to v3.6 and so on). I don't think think this is a great user experience, and would rather go with option 1.

[wendy-ha18]

Q: Should we keep the Visual guide GIF here? this's quite hard to maintain and I'm not sure about the accuracy of it now as it was created 3 years ago.

[wendy-ha18]

Warning: My cluster is already running etcd v3 only with etcd v3.6 so I'm still trying to figure out how to test this process. Are there any suggestion for it?

[ivanvc]

Q: Should we keep the Visual guide GIF here? this's quite hard to maintain and I'm not sure about the accuracy of it now as it was created 3 years ago.

I spoke about the GIFs in the tutorial pages with James before. I agree that the problem is that they can get outdated, and there's no easy way to update/reproduce them. An alternative could be to use a tool like VHS, write a script for each GIF, and use our official Docker images to reproduce the same GIFs later on.

[jberkus]

One more cleanup item: please fix the header for the how-to-migrate page so it shows up in 3.4's TOC.

[jberkus]

Two more things per Ivan's comments.

• Most mentions of "v2" should actually say "v2store". A lot of mentions of v3 should also say v3store.
• There should be a couple sentences at the top that explain how v2store relates to etcd v2.X

Also: mention that there's also a change of API, and link to this document: https://etcd.io/docs/v3.4/op-guide/v2-migration/

[jberkus]

We should discuss v2 vs v2store before merging this. Also whether it's "v2 store" or "v2store". Once we discuss that, we can merge.

[wendy-ha18]

This PR has fixed:

• Included a link explaining the difference between etcd storage format and etcd version.
  • Clarified that the doc guides users on migrating etcd v2store to v3store. All mentions of “v2” and “v3” have been updated to “v2store” and “v3store” for consistency.
  • Added a couple of sentences at the top explaining how v2store relates to etcd v2.X.
  • Added a reference to the official guide for migrating API v2 → API v3 to avoid confusion: https://etcd.io/docs/v3.4/op-guide/v2-migration/.
• Removed the GIF.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jberkus, wendy-ha18

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [jberkus]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[jberkus]

@wendy-ha18 this looks good but it's still marked as a draft. Are you ready to merge it?

[wendy-ha18]

Hi @jberkus and everyone, this PR is ready for final review now.

I included all of these changes:
Website review link: https://deploy-preview-1044--etcd.netlify.app/docs/v3.4/how-to-migrate/

• Add prerequisites.
• Define all variables and flags used in the examples in a bulleted list.
• Describe process of migration.
• Add note to guide user that etcdctl migrate command was removed in etcd v3.5.0 (pull/12971). They must use etcdctl v3.4 or earlier to perform the migration (CHANGELOG-3.5). Reference this issue: Missing command: migrate etcd#14058.
• Included a link explaining the difference between etcd storage format and etcd version.
  • Clarified that the doc guides users on migrating etcd v2store to v3store. All mentions of “v2” and “v3” have been updated to “v2store” and “v3store” for consistency.
  • Added a couple of sentences at the top explaining how v2store relates to etcd v2.X.
  • Added a reference to the official guide for migrating API v2 → API v3 to avoid confusion: https://etcd.io/docs/v3.4/op-guide/v2-migration/.
• Removed the GIF.

[jberkus]

Can you fix the linter failure?

[wendy-ha18]

Hi @jberkus I have fixed the lint issue and the PR is ready now 😄