docs: grab workload version in k8s tutorial by tromai · Pull Request #2559 · canonical/operator

tromai · 2026-06-10T23:33:38Z

Closes #2282.

This PR modify the From zero to hero: Write your first Kubernetes charm tutorial:

Added a section in Chapter 1: creating a helper module for the charm to interact with the workload application. This is inspired by what we have in the machine charm tutorial. The helper module contains the function to get the version of the FastAPI web server.
Added another section in Chapter 1: exposing this version as the workload version to Juju (following this guide).
Added unit tests and integration tests to cover the above logic.
Propagate the changes to the other chapters.

The PR reviewer can focus on the Markdown docs. We can leave the code changes in examples/ at the end, when we have finalized the tutorial, as the changes in examples/ are plenty and mostly reflect the tutorial.

port the grab workfload version code to tutorial 2->5 and use auto fixture for patching get_version in unit tests and also change localhost -> 0.0.0.0 in the fastapi_demo.py modules in examples

tromai · 2026-06-15T06:28:39Z

While working on this task, I noticed that in Chapter 5, we introduced requests for the integration tests. However, we didn't mention adding this dependency using uv add or modifying pyproject.toml. Please let me know if this is a real gap in the doc, and I can fix it in this PR too.

…-in-k8s-tutorial

dwilding · 2026-06-15T07:42:56Z

While working on this task, I noticed that in Chapter 5, we introduced requests for the integration tests. However, we didn't mention adding this dependency using uv add or modifying pyproject.toml. Please let me know if this is a real gap in the doc, and I can fix it in this PR too.

Oops, you're quite right. Well spotted! In the tutorial we say "Then import pytest, pytest_jubilant, and requests" - but only the first two are predefined dependencies in the Charmcraft profile.

tromai · 2026-06-16T07:43:04Z

While working on this task, I noticed that in Chapter 5, we introduced requests for the integration tests. However, we didn't mention adding this dependency using uv add or modifying pyproject.toml. Please let me know if this is a real gap in the doc, and I can fix it in this PR too.

Oops, you're quite right. Well spotted! In the tutorial we say "Then import pytest, pytest_jubilant, and requests" - but only the first two are predefined dependencies in the Charmcraft profile.

Thanks for the confirmation David. I added the step to run uv add requests in the tutorial 80bbc83

dwilding

This is a serious chunk of work - thanks for working through it so thoroughly! It's looking great. I'm sending a first batch of comments and will hold off reviewing further until you've had a chance to think about them.

dwilding · 2026-06-17T03:14:38Z

 1. The same Juju controller injects Pebble -- a lightweight, API-driven process supervisor -- into each workload container and overrides the container entrypoint so that Pebble starts when the container is ready.
 1. When the Kubernetes API reports that a workload container is ready, the Juju controller informs the charm that the instance of Pebble in that container is ready. At that point, the charm knows that it can start communicating with Pebble.
 1. Typically, at this point the charm will make calls to Pebble so that Pebble can configure and start the workload and begin operations.
+1. Besides Pebble exec, the charm can communicate to the workload using HTTP requests. This is possible because they share the same pod (Kubernetes charms are deployed following sidecar pattern).  


I think it's good to make this feel more sequential, following on from "begin operations" in the previous item. Also I don't think we need to mention the sidecar pattern, as item 1 essentially explains it.

Suggested change

1. Besides Pebble exec, the charm can communicate to the workload using HTTP requests. This is possible because they share the same pod (Kubernetes charms are deployed following sidecar pattern).

1. During operations, the charm may need to directly communicate with the workload using HTTP requests. This is possible because the charm container and workload container share the same pod.

dwilding · 2026-06-17T03:18:22Z


+### Write a helper module
+
+Your charm will interact with our workload application `api_demo_server`. It’s a good idea to write a helper module that wraps `api_demo_server`. Charmcraft created `src/fastapi_demo.py` as a placeholder helper module.


Suggested change

Your charm will interact with our workload application `api_demo_server`. It’s a good idea to write a helper module that wraps `api_demo_server`. Charmcraft created `src/fastapi_demo.py` as a placeholder helper module.

Your charm will interact with our workload application `api_demo_server`. It's a good idea to write a helper module that wraps `api_demo_server`. Charmcraft created `src/fastapi_demo.py` as a placeholder helper module.

dwilding · 2026-06-17T03:24:33Z

+The helper module will be independent of the main logic of your charm. This will make it easier to test your charm. In this tutorial, the helper module only contains the logic to get the version of `api_demo_server`. The server has an endpoint at `/version` that returns a JSON payload containing the version number (see {ref}`study-your-application`).
+
+This is called the workload version. To make things easier for Juju admins, our charm should expose the workload version to Juju. It will be visible in `juju status`. For more information, see {ref}`how-to-set-the-workload-version`.


I'm OK to drop the reference link because people typically follow in sequence and there's not much be gained by jumping back at this point.

A couple of other suggestions: It's best to use the term "Juju users" instead of admins (although we still say "admins" in a bunch of places for historical reasons). I recommend changing juju status because we haven't introduced this command yet.

Suggested change

The helper module will be independent of the main logic of your charm. This will make it easier to test your charm. In this tutorial, the helper module only contains the logic to get the version of `api_demo_server`. The server has an endpoint at `/version` that returns a JSON payload containing the version number (see {ref}`study-your-application`).

This is called the workload version. To make things easier for Juju admins, our charm should expose the workload version to Juju. It will be visible in `juju status`. For more information, see {ref}`how-to-set-the-workload-version`.

The helper module will be independent of the main logic of your charm. This will make it easier to test your charm. In this tutorial, the helper module only contains the logic to get the version of `api_demo_server`. The server has an endpoint at `/version` that returns a JSON payload containing the version number. This is called the workload version.

To make things easier for Juju users, your charm should expose the workload version to Juju. It will be visible in Juju's status output. For more information, see {ref}`how-to-set-the-workload-version`.

dwilding · 2026-06-17T03:26:50Z

+
+This is called the workload version. To make things easier for Juju admins, our charm should expose the workload version to Juju. It will be visible in `juju status`. For more information, see {ref}`how-to-set-the-workload-version`.
+
+We first define a function to get the workload version. Replace the content of `src/fastapi_demo.py` with:


I think the first sentence can be dropped because we've already said what what we're going to do (and the code is short and clear enough)

Suggested change

We first define a function to get the workload version. Replace the content of `src/fastapi_demo.py` with:

Replace the content of `src/fastapi_demo.py` with:

dwilding · 2026-06-17T03:28:44Z

+
+
+def get_version(port: int) -> str:
+    """Get the version of fastapi_demo installed.


How about this instead?

Suggested change

"""Get the version of fastapi_demo installed.

"""Get the version of fastapi_demo that is running.

dwilding · 2026-06-17T05:07:53Z

+            "Failed to get version from the server: %s. Please double check your port config",
+            version_e,
+        )
+        self.unit.status = ops.BlockedStatus(str(version_e))


I think it's best to use a hardcoded status string here. Blocked status implies that the Juju user should be able to unblock the charm by themself, and ideally the message should give some indication of how.

As I write this, now I'm wondering whether blocked is really right. I'd like to hear other opinions - but here's what I'm thinking:

If getting the version fails because we can't connect, it might be that the workload container is temporarily unavailable. The charm should go into Maintenance status with an appropriate message. The user needs to wait.

If we got the version, but we couldn't decode it, there's nothing the user can do. We shouldn't catch the error; we should let the charm go into Error state. (The user needs to bug the charm developer about it.)

I discussed this a bit with Nhan, and a couple of things:

Agreed it's better to use a hard-coded message, more like the log message, for example: "Failed to get version from server: check port config"

I don't think Maintenance status would be good here. That means we the charm is doing some maintenance and we know it's going to come right in a minute. But here it might never come right until they fix the port. So I'd recommend keeping BlockedStatus

Agreed re decoding being a hard error -- I think we should just omit the JSONDecodeError and let that one bubble up

dwilding · 2026-06-17T05:09:51Z


 When the config is loaded as part of creating the Pebble layer, if the config is invalid (in our case, if the port is set to 22), then a `ValueError` will be raised. The `_replan_workload` method handles that by logging the error and setting the status of the unit to blocked, letting the Juju user know that they need to take action.

+We also add error handling for getting the workload version. If the charm fails to obtain a valid version number, we set the unit status to blocked. This lets the Juju user know that either the charm code or the workload application behaved unexpectedly.


This will need updating if the error handling strategy changes (which I think it should)

dwilding · 2026-06-17T05:11:43Z


 ```python
-def test_config_changed():
+def test_config_changed(mock_version):


[Continuing discussion from another comment]

I agree that we need mock_version here. Because _on_config_changed calls _replan_workload, which gets the workload version.

I think it would be worth adding a brief sentence or two immediately after the code block, to explain why mock_version is needed in this instance. Then don't mention it again for the rest of the tutorial.

dwilding · 2026-06-17T05:18:40Z

 And define a method that does the various checks, adding appropriate statuses. The library will take care of selecting the 'most significant' status for you.

 ```python
 def _on_collect_status(self, event: ops.CollectStatusEvent) -> None:


Arguably we should get the workload version at the end of this method, as a way of confirming that the workload has started correctly. I'd class that as icing on the cake, not a must-have for this PR.

dwilding · 2026-06-17T05:22:22Z


 ```python
-def test_get_db_info_action():
+def test_get_db_info_action(mock_version):


This test shouldn't need mock_version, because _on_get_db_info_action doesn't end up getting the workload version. But if we change _on_collect_status so that it gets the workload version, then we will need mock_version here.

james-garner-canonical

This is looking good. I agree with David's suggestions.

tromai · 2026-06-18T01:54:34Z

Thanks everyone for the reviews. I really appreciate it !

I will address the feedback

tromai added 3 commits June 10, 2026 15:45

update k8s-1-minimal with setting workload version

cc1a517

update tutorial for creating a minimal kubernetes charm

9381cf9

update docs creating minimal k8s charm

2234b14

tromai self-assigned this Jun 10, 2026

tromai commented Jun 10, 2026

View reviewed changes

Comment thread ...ial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md Outdated

fix typo

c448138

tromai requested a review from james-garner-canonical June 11, 2026 01:42

merge setting workload version step to write your charm section

6f5e0e2

tromai commented Jun 11, 2026

View reviewed changes

Comment thread ...ial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md Outdated

tromai added 3 commits June 11, 2026 17:02

rewrite the explanation about HTTP requests between workload and charm

601f883

WIP:

1bf544f

port the grab workfload version code to tutorial 2->5 and use auto fixture for patching get_version in unit tests and also change localhost -> 0.0.0.0 in the fastapi_demo.py modules in examples

fix format of k8s-2-configurable

f41826e

benhoyt reviewed Jun 12, 2026

View reviewed changes

address feedback from Ben

e522d58

tromai commented Jun 15, 2026

View reviewed changes

Comment thread ...ial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md

tromai commented Jun 15, 2026

View reviewed changes

Comment thread ...ial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md Outdated

tromai commented Jun 15, 2026

View reviewed changes

Comment thread ...ial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md

tromai added the rainy day Small items done in ~10% of each week's time label Jun 15, 2026

tromai added 2 commits June 15, 2026 16:44

remove hardcode version string

035a521

Merge remote-tracking branch 'origin/main' into grab-workload-version…

5ac4068

…-in-k8s-tutorial

tromai marked this pull request as ready for review June 15, 2026 06:49

add instruction to add requests as a dependency in chapter 5

80bbc83

dwilding reviewed Jun 17, 2026

View reviewed changes

james-garner-canonical reviewed Jun 18, 2026

View reviewed changes

Merge branch 'main' into grab-workload-version-in-k8s-tutorial

050a5d9

	1. Besides Pebble exec, the charm can communicate to the workload using HTTP requests. This is possible because they share the same pod (Kubernetes charms are deployed following sidecar pattern).
	1. During operations, the charm may need to directly communicate with the workload using HTTP requests. This is possible because the charm container and workload container share the same pod.


		### Write a helper module

		Your charm will interact with our workload application `api_demo_server`. It’s a good idea to write a helper module that wraps `api_demo_server`. Charmcraft created `src/fastapi_demo.py` as a placeholder helper module.

		The helper module will be independent of the main logic of your charm. This will make it easier to test your charm. In this tutorial, the helper module only contains the logic to get the version of `api_demo_server`. The server has an endpoint at `/version` that returns a JSON payload containing the version number (see {ref}`study-your-application`).

		This is called the workload version. To make things easier for Juju admins, our charm should expose the workload version to Juju. It will be visible in `juju status`. For more information, see {ref}`how-to-set-the-workload-version`.


		This is called the workload version. To make things easier for Juju admins, our charm should expose the workload version to Juju. It will be visible in `juju status`. For more information, see {ref}`how-to-set-the-workload-version`.

		We first define a function to get the workload version. Replace the content of `src/fastapi_demo.py` with:

	We first define a function to get the workload version. Replace the content of `src/fastapi_demo.py` with:
	Replace the content of `src/fastapi_demo.py` with:



		def get_version(port: int) -> str:
		"""Get the version of fastapi_demo installed.

	"""Get the version of fastapi_demo installed.
	"""Get the version of fastapi_demo that is running.


		When the config is loaded as part of creating the Pebble layer, if the config is invalid (in our case, if the port is set to 22), then a `ValueError` will be raised. The `_replan_workload` method handles that by logging the error and setting the status of the unit to blocked, letting the Juju user know that they need to take action.

		We also add error handling for getting the workload version. If the charm fails to obtain a valid version number, we set the unit status to blocked. This lets the Juju user know that either the charm code or the workload application behaved unexpectedly.

Conversation

tromai commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tromai commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dwilding commented Jun 15, 2026

Uh oh!

tromai commented Jun 16, 2026

Uh oh!

dwilding left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

james-garner-canonical left a comment

Choose a reason for hiding this comment

Uh oh!

tromai commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tromai commented Jun 10, 2026 •

edited

Loading

tromai commented Jun 15, 2026 •

edited

Loading

tromai commented Jun 18, 2026 •

edited

Loading