#1358 Link to 'Settings for etcd tuning' no longer valid, plus other fixes to links to etcd.io/docs

martyav commented 3 months ago

Fixes #1358

Reminders

See the README for more details on how to work with the Rancher docs.
Verify if changes pertain to other versions of Rancher. If they do, finalize the edits on one version of the page, then apply the edits to the other versions.
If the pull request is dependent on an upcoming release, remember to add a "MERGE ON RELEASE" label and set the proper milestone.

Description

From the issue:

The link points to https://coreos.com/etcd/docs/latest/tuning.html, but with coreos.com no longer existing, this now redirects to etcd.io. Checking archive.org, it looks like this link was invalidated sometime in 2019, as the first instance I can find that has a valid page is back in 2018.

I checked the site the link now redirects to, and found that an updated version of the original Tuning page is now located at https://etcd.io/docs/v3.5/tuning/. I updated the link across the docset, including Chinese language versions.

Since performing the update three other things came up:

Each link to etcd.io/docs needs to include a version number. There's no default/latest version of the site available without a version number, and at any rate it would be inaccurate if the user needs information on an etcd version that is incompatible with their version of Kubernetes.
We had numerous existing links to etcd.io/docs that needed to have their version numbers modified, as K8s v1.22 and later use etcd v3.5, and many of our links pointed to pages for earlier etcd versions.
The etcd.io/docs site used to include trailing zeros in the version number portion of the URL. At some point, the URLs dropped the zeros. In v3.4 and earlier the site would redirect the link correctly if a zero was included, but in v3.5 the outdated links simply throw a 404.

This PR now addresses both the inaccurate versioning and etcd.io/docs URLs containing trailing zeros across the docset.

Comments

martyav commented 2 months ago

@btat I did a diff of https://etcd.io/docs/v3.3/tuning/ vs https://etcd.io/docs/v3.4/tuning/ and the pages are identical except for the addition of the heading, "When to update the heartbeat interval and election timeout settings", to v3.4. Since in some cases I had to choose between the v3.3 and v3.4 link, I opted for including the earlier version as they're functionally the same. I pushed changes for the English docs. I'll update the international pages and any other pages that include the bad links in a bit

martyav commented 2 months ago

@btat I did a crude search on /docs for "https://etcd.io/docs/v3.4" and found ~28~ multiple instances. Presumably versioned docs will have about as many each. Should we put the updated links for all instances of outdated etcd.io links in this PR or separate them out for ease of review?

btat commented 2 months ago

@btat I did a crude search on /docs for "https://etcd.io/docs/v3.4" and found 28 instances. Presumably versioned docs will have about as many each. Should we put the updated links for all instances of outdated etcd.io links in this PR or separate them out for ease of review?

Given that these should just be version number changes, I think it's fine to include it in this PR since this PR has the context for why it's being done. As for ease of review, if you group things by commit it shouldn't affect readability too much since the actual content change is minimal.

martyav commented 2 months ago

For 2.5 you opted to use the earlier etcd version. For 2.6 the more recent version (3.5) is used, but early 2.6 versions (e.g. 2.6.0 use 3.4. Is there a content difference between 3.4 and 3.5 to prompt the early vs recent version choice?

I didn't realize that the earliest versions of Rancher v2.6 used etcd v3.4. The pages on v3.4 and v3.5 differ more substantially, so we should advise users to use one page for early and one page for later versions. I'll look up the cut off point.

Edit: Looks like Kubernetes v1.22 makes the switch to etcd v3.5 (https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md#etcd-moves-to-version-350). This overlaps with v2.6's range of supported Kubernetes versions so the advice should link users to one page or the other based on their K8s versions.

martyav commented 2 months ago

Just pushed another URL fix, because at about 3.4 the etcd.io site changed how version numbers are written in the URL, from including a trailing zero to not including a trailing zero, and the site would inconsistently redirect links that still contained the zero.

rancher / rancher-docs