docs: update docs, deps, and tests for charms with libs by dwilding · Pull Request #2281 · canonical/operator

dwilding · 2026-01-20T11:41:14Z

This is an intermediate PR for switching the Kubernetes charm tutorial to use uv and the latest Charmcraft profiles. Target branch is k8s-tutorial-uv

This PR:

Updates Integrate your charm with PostgreSQL (preview) to explain that Charmcraft might show a warning when fetching libs - thanks @xdqi for raising this! I'm also improving the guidance about setting PYTHONPATH.
In Observe your charm with COS Lite (preview):
- Adds a section "Add dependencies from libraries" about including cosl as a dependency.
- Removes an incorrect note about Charmcraft copying the contents of lib. As explained in the PostgreSQL chapter, what actually happens is that the dispatch script sets PYTHONPATH. The note also mentioned how to import a lib, which isn't necessary because the chapter covers that later.
- Removes the binary package workaround that was needed when we used the Charm plugin.
- Mentions the same Charmcraft warning as in the PostgreSQL chapter.
Adds cosl as a dependency of the relevant charm code.
Updates our "Example Charm Integration Tests" workflow so that it correctly handles uv-based charms that use Charmhub-hosted libs.

The workflow doesn't run on PRs, so I temporarily enabled it here and checked that it succeeded: https://github.com/canonical/operator/actions/runs/21170536298/

dwilding · 2026-01-20T12:02:33Z

-# Workaround for a build error.
-parts:
-  charm:
-    charm-binary-python-packages:
-      - cosl


I've already removed this from the relevant charm code in the k8s-tutorial-uv branch.

dwilding · 2026-01-20T23:54:29Z

-If you're experiencing issues with your IDE or just trying to run the `charm.py` file on your own, make sure to set/update `PYTHONPATH` to include `lib` directory as well.
+If you're experiencing issues with your IDE, make sure to set/update `PYTHONPATH` to include the `lib` directory as well.

 ```bash
-# from the charm project directory (~/fastapi-demo), set
+# in your project directory (~/k8s-tutorial), set
 export PYTHONPATH=lib
 # or update
 export PYTHONPATH=lib:$PYTHONPATH


I don't think it's fruitful for people to spend time trying to run charm.py. Also, focusing on IDEs lets us clarify that PYTHONPATH should be set in ~/k8s-tutorial, which is outside the VM.

…rial-lib-charms

james-garner-canonical

These changes look good to me!

dimaqq

Nice, especially running the tests in the same pipeline.

tonyandrewmeyer

Looks good, thanks!

I didn't run through the tutorial - I assume that'll be done by at least one person at the end when the merge through to main is ready.

tonyandrewmeyer · 2026-01-22T22:47:38Z

-Your charm directory should now include the structure below:
+You might see a warning that Charmcraft cannot get a keyring. You can ignore the warning.
+
+After Charmcraft has downloaded the libraries, you project's `lib` directory contains:


Suggested change

After Charmcraft has downloaded the libraries, you project's `lib` directory contains:

After Charmcraft has downloaded the library, your project's `lib` directory contains:

Oops, thanks. Corrected "you" --> "your" but kept "libraries" as charmcraft fetch-libs is downloading several libraries in this chapter

…rofile (#2285) This PR makes significant changes to our [Kubernetes charm tutorial](https://documentation.ubuntu.com/ops/latest/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/). ### Main changes - Use similar environment setup instructions as our machine charm tutorial. The instructions explain how to use Concierge to prepare a Multipass VM with Canonical Kubernetes and charm dev tools. I'm recommending that the reader mounts a local directory into their VM so that they can use their IDE to edit charm code. **[Preview chapter](https://canonical-ubuntu-documentation-library--2285.com.readthedocs.build/ops/2285/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/set-up-your-development-environment/)** I also made a small clarification to the setup instructions of the machine charm tutorial. - Start the charm from the latest Charmcraft `kubernetes` profile. This removes the need for the reader to create several files, including `charmcraft.yaml`, `pyproject.toml`, and `tox.ini`. The charm expects uv for managing dependencies and uses Charmcraft's uv plugin. **[Preview chapter](https://canonical-ubuntu-documentation-library--2285.com.readthedocs.build/ops/2285/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm/)** - Manually find transitive dependencies of Charmhub-hosted libs. This makes the last chapter slightly more complicated, but is unavoidable because the observability libs haven't been migrated to `charmlibs` packages and Charmcraft's uv plugin doesn't extract `PYDEPS` from libs. **[Preview section](https://canonical-ubuntu-documentation-library--2285.com.readthedocs.build/ops/2285/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/observe-your-charm-with-cos-lite/#add-dependencies-from-libraries)** These changes were reviewed in my intermediate PRs #2258, #2259, and #2281. ### Unrelated changes - Mention that Charmcraft might show a warning when fetching libs. - I fixed a bug in the [demo server](https://github.com/canonical/api_demo_server) workload. Version 1.0.1 of the image returns version string `1.0.0` from the API. I'm switching the tutorial to use version 1.0.2 of the image, which correctly returns version string `1.0.2`. ### Adjustments after testing After the main changes had been reviewed, I tested the tutorial from end to end and made some small adjustments/fixes: f33ac24, 2851e1f, 71b9838, f8b22a8. Further adjustments during PR review: 7d36dce Final adjustments to add a note about issues accessing services inside the VM: 837df1b

dwilding added 4 commits January 20, 2026 19:38

undocument the workaround for binary packages

4e45596

add cosl dep to k8s-5-observe

71abac3

update CI for integration tests

0c1338e

temporarily enable CI for integration tests

7e4a26e

dwilding commented Jan 20, 2026

View reviewed changes

adjust instructions for setting PYTHONPATH

fb374b0

dwilding commented Jan 20, 2026

View reviewed changes

dwilding added 9 commits January 21, 2026 08:03

mention that Charmcraft might show a warning

80ee571

adjust wording around lib dir

64d4f5d

make data_interfaces a singular lib

2c6e160

revert temporary change to CI

1771c49

remove note about Charmcraft copying the lib dir

ea35ae2

mention Charmcraft warning and adjust wording

565c5d9

in pyproject.toml, match ordering of 'uv add'

a2951be

add section about adding PYDEPS

23d541c

Merge remote-tracking branch 'upstream/k8s-tutorial-uv' into k8s-tuto…

48e490a

…rial-lib-charms

dwilding marked this pull request as ready for review January 21, 2026 02:17

dwilding requested review from james-garner-canonical and tonyandrewmeyer January 21, 2026 02:17

dwilding mentioned this pull request Jan 21, 2026

Update K8s tutorial to start with charmcraft init #1749

Closed

james-garner-canonical approved these changes Jan 22, 2026

View reviewed changes

dimaqq approved these changes Jan 22, 2026

View reviewed changes

tonyandrewmeyer approved these changes Jan 22, 2026

View reviewed changes

fix typo

6f785b8

dwilding merged commit 7cfb5af into canonical:k8s-tutorial-uv Jan 22, 2026
56 checks passed

dwilding deleted the k8s-tutorial-lib-charms branch January 22, 2026 23:42

dwilding mentioned this pull request Jan 23, 2026

docs: refresh K8s tutorial to use Concierge and uv-based Charmcraft profile #2285

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update docs, deps, and tests for charms with libs#2281

docs: update docs, deps, and tests for charms with libs#2281
dwilding merged 15 commits intocanonical:k8s-tutorial-uvfrom
dwilding:k8s-tutorial-lib-charms

dwilding commented Jan 20, 2026 •

edited

Loading

Uh oh!

dwilding Jan 20, 2026

Uh oh!

dwilding Jan 20, 2026 •

edited

Loading

Uh oh!

james-garner-canonical left a comment

Uh oh!

dimaqq left a comment

Uh oh!

tonyandrewmeyer left a comment

Uh oh!

tonyandrewmeyer Jan 22, 2026

Uh oh!

dwilding Jan 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	After Charmcraft has downloaded the libraries, you project's `lib` directory contains:
	After Charmcraft has downloaded the library, your project's `lib` directory contains:

Conversation

dwilding commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dwilding Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

dwilding Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

dimaqq left a comment

Choose a reason for hiding this comment

Uh oh!

tonyandrewmeyer left a comment

Choose a reason for hiding this comment

Uh oh!

tonyandrewmeyer Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

dwilding Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dwilding commented Jan 20, 2026 •

edited

Loading

dwilding Jan 20, 2026 •

edited

Loading