Confusion and conflict between upgrade docs and "upgrade insights" feature

[Kalli]

The docs for updating a cluster suggest to proceed with a kubernetes upgrade in the following order:

...
Step 3: Update cluster control plane
Step 4: Update cluster components
...
Step 4.4
Update the Amazon VPC CNI plugin for Kubernetes, CoreDNS, and kube-proxy add-ons.

But when you go to a cluster in the console page, the upgrade insights will warn you about any out of date add ons:

Upgrade insights identify possible issues that could impact Kubernetes cluster upgrades.

If you click to upgrade your cluster, to start the update control plane and nodes before updating the add ons (as per the eks-user-guide) you will get a warning about the upgrade insights. This prompted some confusion for me and my team.

• Perhaps the docs could be updated to reflect whether to upgrade the add-ons before the control plane and nodes (as per the upgrade insights) or after (as per the userguide).
• It isn't very clear whether the add ons should be updated to the default version for the current k8s version or if they need to be updated to the default for the k8s target version before upgrade insights will let you know upgrade without warning.

[fincd-aws]

Hi thanks for pointing this out. Inconsistent advice around upgrade is a serious problem.

Also a third place with differing advice: the best practices guide says to upgrade the cluster as step 5, then the add-ons as step 6: https://docs.aws.amazon.com/eks/latest/best-practices/cluster-upgrades.html

5. Upgrade the cluster control plane using the AWS console or cli.
6. Review add-on compatibility. Upgrade your Kubernetes add-ons and custom controllers, as required.

I think we ended up with different steps b/c of differing experiences from the different authors:

• You might need to upgrade both before and after, it depends on just how far behind a specific add-on was.
• Also the add-ons that are tied to a k8s version (kube-proxy) must be upgraded after, regardless of doing the upgrade to latest add-on version of the current k8s version or not.
• However you can skip most add-ons at most versions and upgrade the cluster first - this is shorter b/c you upgrade each add-on fewer times.

Upgrade insights is context-aware without a lot of extra "if this scenario" being visible - it it built in. We could point out the nuance here with a specific example, but that's going to be a lot to read (and write).

So for the docs, I could put add-ons both before and after the cluster. If an add-on has no more new versions the second time, then you can skip it.
What do you think?

[Kalli]

Thanks for the response.

So for the docs, I could put add-ons both before and after the cluster. If an add-on has no more new versions the second time, then you can skip it.

That seems reasonable to me. Maybe "Upgrade insights" could be mentioned in the docs as well? Doesn't have to go into details, but perhaps worth saying that its recommendations will be specific to users situation, while the docs will always be more general?