docs: cleanup and tidy up the 1.11 upgrade guide

[aanm]

This upgrade guide contained all other versions in it. To prevent users
from mistakenly reading an old upgrade guide, we should remove those
leftovers.

Signed-off-by: André Martins andre@cilium.io

[qmonnet]

RST change/cleanup looks good.

Are you sure we should delete the instructions for older versions?

• How will people find the documentation they need if they want to update from an older version? Should we at least point them to the older versions of the documentation?
• This list is also sometimes useful for developers, for tracking the evolution of configuration options for example. Now we'll have to go through the git history or to checkout an older branch to find it?

Would it make sense to keep this information but to “hide” it on another page that doesn't get as much exposure, and to link to it from the upgrade guide?

Note that the rest of the document (the Advanced section) also has a few references to older versions, see for example https://docs.cilium.io/en/latest/operations/upgrade/#migrating-from-kvstore-backed-identities-to-kubernetes-crd-backed-identities Beginning with cilium 1.6...

[aanm]

RST change/cleanup looks good.

Are you sure we should delete the instructions for older versions?

It's up for debate. I think it doesn't make sense to have all of that text for older versions since we only support upgrades from a minor version to the next minor version.

• How will people find the documentation they need if they want to update from an older version? Should we at least point them to the older versions of the documentation?

Each documentation is specific for a branch, they can find the upgrade from 1.9 to 1.10 in the v1.10 branch

• This list is also sometimes useful for developers, for tracking the evolution of configuration options for example. Now we'll have to go through the git history or to checkout an older branch to find it?

🤔 I never came across that myself. Can you give a specific example?

Would it make sense to keep this information but to “hide” it on another page that doesn't get as much exposure, and to link to it from the upgrade guide?

Note that the rest of the document (the Advanced section) also has a few references to older versions, see for example https://docs.cilium.io/en/latest/operations/upgrade/#migrating-from-kvstore-backed-identities-to-kubernetes-crd-backed-identities Beginning with cilium 1.6...

Correct, although it is available since Cilium 1.6, users can still opt-in to migrate from kvstore to crd in 1.10/1.11/1.12...

[qmonnet]

It's up for debate. I think it doesn't make sense to have all of that text for older versions since we only support upgrades from a minor version to the next minor version.

I understand and I'm not opposed to have them removed from that page, but at the same time I'm not sure it should disappear altogether from the repository.

• How will people find the documentation...

Each documentation is specific for a branch, they can find the upgrade from 1.9 to 1.10 in the v1.10 branch

I know that, but I'm not sure that all users know. This is why I suggested that we should at least replace the removed content with a paragraph pointing to those documentation branches (If you seek to upgrade from an older version, see [the older versions of this document](...)...)

• This list is also sometimes useful for developers, ...

thinking I never came across that myself. Can you give a specific example?

The example I had in mind was about troubleshooting a user issue, with an older version of Cilium involved, and we realised that the bug was due to a configuration mistake: The user was relying on the former version of an option which had since changed name. I read the upgrade guide to find this out.

If we remove the older guides from this branch I will still be able to read the former upgrade notes from the older branches of the online documentation, but it will be less convenient than reading them locally from the .rst file in my opinion. Then if we keep removing the legacy notes for each new release, in time, I will have to go through all the existing branches if I'm looking for a deprecation and I don't know in what version it was removed.

Note that the rest of the document...

Correct, although it is available since Cilium 1.6, users can still opt-in to migrate from kvstore to crd in 1.10/1.11/1.12...

👍

(Overall I'm not strongly opposed to removing the older notes, it does make the guide cleaner - I'm simply voicing concerns that I believe we should at least consider before proceeding.)

[joestringer]

This is a nice cleanup.

In the past I was maybe more inclined to keep these here for reasons similar to what Quentin raises above, but this doc is really big and we don't really intend for OSS users to upgrade directly across multiple minor releases so it should be enough to just link the older guides and encourage upgrading through each minor release.

As for figuring out that users have specified an unsupported configuration item, I wonder if it'd be better to just come up with a simple config validator tool that could highlight the problems. Ultimately if the user specifies foo in the helm charts and expects that cilium-agent gets configured with --foo, then the result should be fairly easy to cross-reference with either the logs at the agent startup or vs. cilium config --all to determine whether the setting is set correctly. From there, it should be easy to bisect whether the problem is in helm or in the agent.