Charm Upgrade documentation #881

addyess · 2024-12-09T23:09:43Z

Overview

Ported upgrade docs from Charmed Kubernetes
Ported validation docs from Charmed Kubernetes

Details

providing docs for minor upgrades
providing docs for patch upgrades
providing docs for cluster validation

nhennigan

Let me know when you finish writing this and I will review again but for now here are some initial thoughts

docs/src/charm/howto/upgrade-minor.md

nhennigan · 2024-12-10T12:36:03Z

docs/src/charm/howto/upgrade-minor.md

+[juju-docs]:          https://juju.is/docs/juju/upgrade-models
+[release-notes]:      ../reference/releases.md
+[upgrade-notes]:      ../reference/upgrade-notes.md
+[upstream-notes]:     https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.31.md#deprecation


Linking to a specific changelog version will make this link out of date with each release. Maybe we should like to one level higher? Or would this be updated on each release?

it should be updated ever release. is there a variable for which release this is?

There is a {{version}} variable we have set up like {{product}} but I am not sure how it will integrate into a url

@nhennigan is there anything i can do to test it?

So I tried to use {{version}} in the url but it wasn't working. There does seem to be a work around but it will take a new configuration file and I think that is out of the scope of this PR. I will add it to the backlog to see if it can be automated in the future

@nhennigan would you like me to update the link to point to 1.32 changelog?

Yes I think its safe enough to update to 1.32 now

docs/src/charm/howto/upgrade-minor.md

docs/src/charm/howto/validate.md

eaudetcobello · 2024-12-10T14:29:01Z

docs/src/charm/howto/upgrade-minor.md

+It is recommended that you keep your Kubernetes deployment
+updated to the latest available stable version. You should
+also update the other applications which make up Kubernetes.


I would remove the second sentence and rephrase, or specify what other applications make up Kubernetes.

thanks @eaudetcobello i'm opened to rewording this. I guess i could list possible other charm integrations here ceph-csi, cinder-csi, openstack-integrator but there's like 60 charms and i'd rather not list them all.

Then you could say "the applications you've deployed in your Kubernetes cluster"?

eaudetcobello · 2024-12-10T15:23:19Z

docs/src/charm/howto/upgrade-minor.md

+It is also important to understand that Kubernetes will only 
+upgrade and if necessary migrate, components relating specifically
+to elements of Kubernetes installed and configured as part of Kubernetes.
+This may not include any customized configuration of Kubernetes,
+or user generated objects (e.g. storage classes) or deployments which
+rely on deprecated APIs.


I think this is confusing for a CK8s user. How does this relate to Canonical K8s specifically and the components we deploy like the built-in features?

maybe so. I'm forking the instructions here
https://ubuntu.com/kubernetes/docs/upgrading

Whats good for the goose i'd hoped would be good for the gander

other integrations like:

ceph-csi

cinder-csi

openstack-cloud-controller-manager

none of these get upgraded when you update the k8s and k8s-worker. This statement is here for that reason

Similarly -- if someone has "kubelet-extra-args" set on their application. And those args for kubelet are deprecated -- we aren't magically migrating them.

docs/src/charm/howto/upgrade-minor.md

eaudetcobello

Great work, thanks @addyess! The main thing I would improve here is the distinction between Kubernetes itself and Canonical Kubernetes. For example, the following paragraph:

It is also important to understand that Kubernetes will only 
upgrade and if necessary migrate, components relating specifically
to elements of Kubernetes installed and configured as part of Kubernetes.
This may not include any customized configuration of Kubernetes,
or user generated objects (e.g. storage classes) or deployments which
rely on deprecated APIs.

addyess · 2024-12-10T22:12:59Z

@nhennigan
ok, i'm likely not the first nor the last to wonder why there are two wordlists.

docs/canonicalk8s/styles/config/vocabularies/Canonical/accept.txt seems to be the superset.

Why are there two dictionaries?

nhennigan · 2024-12-11T09:50:22Z

.custom_wordlist was what we used for the automatic_doc_checks runner (complete list of checks for docs). It is basically duplicated in docs/canonicalk8s/styles/config/vocabularies/Canonical/accept.txt for the spellcheck runner. I will consolidate again into one when the automatic_doc_checks are working properly. I have plans in the coming weeks to fix the other checks that are failing like link checker, style etc. but I wanted a spellcheck on the repo in the mean time

docs/src/charm/howto/upgrade-minor.md

mateoflorido

Great work! Thanks for taking the lead on the documentation. I do have a few suggestions:

docs/src/charm/howto/upgrade-minor.md

docs/src/charm/howto/upgrade-patch.md

louiseschmidtgen

Fantastic work Adam! I've got some word nits for you please apply these to both docs.

docs/src/charm/howto/upgrade-minor.md

louiseschmidtgen · 2024-12-16T11:55:26Z

docs/src/charm/howto/upgrade-minor.md

+and security patches for smooth operation of your cluster.
+
+New minor versions of Kubernetes are set to release three
+times per year. You can check the latest release version


Suggested change

times per year. You can check the latest release version

times per year. Check the latest release version

(Avoid using you)

louiseschmidtgen · 2024-12-16T11:57:25Z

docs/src/charm/howto/upgrade-minor.md

+whether to a patch or minor version.
+```
+
+You can see which version of each application is currently deployed by running:


Suggested change

You can see which version of each application is currently deployed by running:

Determine which version of each application is currently deployed by running:

louiseschmidtgen · 2024-12-16T11:58:35Z

docs/src/charm/howto/upgrade-minor.md

+unforeseen difficulties. It is highly recommended that you make
+a backup of any important data, including any running workloads.


Suggested change

unforeseen difficulties. It is highly recommended that you make

a backup of any important data, including any running workloads.

unforeseen difficulties. It is highly recommended to make

a backup of any important data, including any running workloads.

louiseschmidtgen · 2024-12-16T11:58:58Z

docs/src/charm/howto/upgrade-minor.md

+[docs on backups][backup-restore].
+
+
+You should also make sure:


Suggested change

You should also make sure:

Please verify that:

docs/src/charm/howto/upgrade-minor.md

docs/src/charm/howto/upgrade-patch.md

Co-authored-by: Mateo Florido <[email protected]>

nhennigan

I know there seems to be so many rounds of review on this but they are almost there! Once these are addressed and Louise's comments are closed I think we are good to merge 😺

docs/src/charm/howto/upgrade-patch.md

nhennigan · 2024-12-20T08:56:04Z

docs/src/charm/howto/upgrade-minor.md

+[juju-docs]:          https://juju.is/docs/juju/upgrade-models
+[release-notes]:      ../reference/releases.md
+[upgrade-notes]:      ../reference/upgrade-notes.md
+[upstream-notes]:     https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.31.md#deprecation


Yes I think its safe enough to update to 1.32 now

nhennigan · 2024-12-20T09:01:56Z

docs/src/charm/howto/upgrade-minor.md

+* Your cluster is running normally
+* Your Juju client and controller/models are running the same,
+  stable version of Juju (see the [Juju docs][juju-docs])
+* You read the [Upgrade notes][upgrade-notes] to see if any
+  caveats apply to the versions you are upgrading to/from
+* You read the [Upstream release notes][upstream-notes] for details
+  of Kubernetes deprecation notices and API changes that may impact
+  your workloads


The difference is small but I think "you should" lends itself more to tutorials. How-to guides are more direct so I would implement Louise's changes.

nhennigan · 2024-12-20T09:04:37Z

docs/src/charm/howto/upgrade-minor.md

+stable release in this channel and you should continue with the
+[Pre Upgrade Check](#the-pre-upgrade-check).
+
+Otherwise, continue with the [Upgrade Patch](upgrade-patch) instructions.


I am a bit confused to the logic here. Am I right in saying:
If there can-upgrade-to is null, we are on the latest stable release (up to date in our patches ) in our channel and we can go to to the next channel with the upgrade.
If the can-upgrade-to is not null, we want them to upgrade the patch first.

That's correct. I wonder how to make this more clear

nhennigan · 2024-12-20T09:23:16Z

docs/src/charm/howto/upgrade-minor.md

+[cluster-validation]:  ./validate
+[juju-docs]:           https://juju.is/docs/juju/upgrade-models
+[release-notes]:       ../reference/releases
+[upgrade-notes]:       ../reference/upgrade-notes


Same as before

nhennigan · 2024-12-20T09:28:16Z

docs/src/charm/howto/upgrade-minor.md

+```
+
+The `refresh` command instructs the juju controller to follow a new
+charm channel related to the Kubernetes release and use the new charm


This is quite a long sentence. Can we split into two? Suggestion:
The refresh command instructs the juju controller to follow a new
charm channel related to the Kubernetes release. It also instructs the juju controller to use the new charm revision of the application's channel to upgrade each unit.

addyess · 2024-12-20T21:48:18Z

@nhennigan i think i've incorporated your suggestions. Feel free to push any other suggestions to the branch or we can carry over this task

bschimke95 · 2025-01-09T08:22:56Z

seems all comments are resolved and @nhennigan approved - merging this.

nhennigan reviewed Dec 10, 2024

View reviewed changes

eaudetcobello reviewed Dec 10, 2024

View reviewed changes

docs/src/charm/howto/upgrade-minor.md Outdated Show resolved Hide resolved

eaudetcobello reviewed Dec 10, 2024

View reviewed changes

addyess force-pushed the KU-2262/charm-upgrades branch from 7e03866 to 2605c98 Compare December 10, 2024 22:11

addyess marked this pull request as ready for review December 11, 2024 17:06

addyess requested a review from a team as a code owner December 11, 2024 17:06

addyess force-pushed the KU-2262/charm-upgrades branch from 3e39e26 to 71693fd Compare December 11, 2024 17:22

addyess changed the title ~~Beginning of the upgrade documentation~~ Charm Upgrade documentation Dec 11, 2024

addyess commented Dec 11, 2024

View reviewed changes

docs/src/charm/howto/upgrade-minor.md Outdated Show resolved Hide resolved

addyess commented Dec 11, 2024

View reviewed changes

docs/src/charm/howto/upgrade-minor.md Outdated Show resolved Hide resolved

mateoflorido requested changes Dec 11, 2024

View reviewed changes

louiseschmidtgen reviewed Dec 16, 2024

View reviewed changes

addyess force-pushed the KU-2262/charm-upgrades branch 2 times, most recently from c0d5efa to 4b9927a Compare December 16, 2024 19:54

addyess and others added 7 commits December 17, 2024 16:51

Beginning of the upgrade documentation

701f453

Address Review comments

d1ce212

teach vale some spellings

c986970

Incorporate output directly from juju

59fff2c

Apply suggestions from code review

f9de36d

Co-authored-by: Mateo Florido <[email protected]>

Apply more review comments

5f5ff00

Integrate review comment

735cfe9

addyess force-pushed the KU-2262/charm-upgrades branch from 4b9927a to 735cfe9 Compare December 17, 2024 22:53

nhennigan reviewed Dec 20, 2024

View reviewed changes

mateoflorido approved these changes Dec 20, 2024

View reviewed changes

More review comments

9f7086e

nhennigan approved these changes Jan 7, 2025

View reviewed changes

bschimke95 merged commit bb10a1c into main Jan 9, 2025
6 checks passed

bschimke95 deleted the KU-2262/charm-upgrades branch January 9, 2025 08:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Charm Upgrade documentation #881

Charm Upgrade documentation #881

addyess commented Dec 9, 2024

nhennigan left a comment

nhennigan Dec 10, 2024

addyess Dec 10, 2024

nhennigan Dec 16, 2024

addyess Dec 16, 2024

nhennigan Dec 19, 2024

addyess Dec 19, 2024

nhennigan Dec 20, 2024

eaudetcobello Dec 10, 2024

addyess Dec 10, 2024

eaudetcobello Dec 11, 2024

eaudetcobello Dec 10, 2024

addyess Dec 10, 2024

addyess Dec 16, 2024

addyess Dec 16, 2024

eaudetcobello left a comment

addyess commented Dec 10, 2024

nhennigan commented Dec 11, 2024

mateoflorido left a comment

louiseschmidtgen left a comment

louiseschmidtgen Dec 16, 2024

louiseschmidtgen Dec 16, 2024

louiseschmidtgen Dec 16, 2024

louiseschmidtgen Dec 16, 2024

nhennigan left a comment

nhennigan Dec 20, 2024

nhennigan Dec 20, 2024

nhennigan Dec 20, 2024

addyess Dec 20, 2024

nhennigan Dec 20, 2024

nhennigan Dec 20, 2024

addyess commented Dec 20, 2024

bschimke95 commented Jan 9, 2025

	times per year. You can check the latest release version
	times per year. Check the latest release version

	You can see which version of each application is currently deployed by running:
	Determine which version of each application is currently deployed by running:

		unforeseen difficulties. It is highly recommended that you make
		a backup of any important data, including any running workloads.

		[docs on backups][backup-restore].


		You should also make sure:

Charm Upgrade documentation #881

Charm Upgrade documentation #881

Conversation

addyess commented Dec 9, 2024

Overview

Details

nhennigan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eaudetcobello left a comment

Choose a reason for hiding this comment

addyess commented Dec 10, 2024

nhennigan commented Dec 11, 2024

mateoflorido left a comment

Choose a reason for hiding this comment

louiseschmidtgen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nhennigan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

addyess commented Dec 20, 2024

bschimke95 commented Jan 9, 2025