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

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

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: wendy-ha18
Once this PR has been reviewed and has the lgtm label, please assign ivanvc for approval. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

• OWNERS

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

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

[k8s-ci-robot]

@wendy-ha18: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-website-lint	ebd0627	link	true	/test pull-website-lint

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

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