docs: switch chapter 1 to Charmcraft charm#2259
Merged
dwilding merged 15 commits intocanonical:k8s-tutorial-uvfrom Jan 19, 2026
Merged
docs: switch chapter 1 to Charmcraft charm#2259dwilding merged 15 commits intocanonical:k8s-tutorial-uvfrom
dwilding merged 15 commits intocanonical:k8s-tutorial-uvfrom
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR modernizes the Chapter 1 Kubernetes charm example to use the current Charmcraft initialization template and tooling. The changes transition from a manual charm setup to one generated by charmcraft init --profile kubernetes, incorporating modern Python project management with uv and updated testing infrastructure.
Key changes:
- Replaces manual charm creation steps with
charmcraft initworkflow - Updates project structure to use
pyproject.tomlwith dependency groups instead ofrequirements.txt - Modernizes testing infrastructure with uv-based dependency management
- Updates copyright year from 2025 to 2026
Reviewed changes
Copilot reviewed 16 out of 17 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| examples/k8s-1-minimal/tox.ini | Updated to use uv-venv-lock-runner, dependency groups, reorganized test environments, and added format/lint configurations |
| examples/k8s-1-minimal/tests/unit/test_charm.py | Changed string quotes to double quotes, added testing documentation link |
| examples/k8s-1-minimal/tests/integration/test_charm.py | Updated string quotes, simplified docstrings, changed charm path handling to use resolve() |
| examples/k8s-1-minimal/tests/integration/conftest.py | Enhanced with better logging, CHARM_PATH environment variable support, and improved error handling |
| examples/k8s-1-minimal/src/charm.py | Changed all string literals to double quotes, simplified docstrings |
| examples/k8s-1-minimal/requirements.txt | Removed file (dependencies moved to pyproject.toml) |
| examples/k8s-1-minimal/pyproject.toml | Added comprehensive project configuration with dependency groups for lint, unit, and integration tests |
| examples/k8s-1-minimal/charmcraft.yaml | Modernized to use current Charmcraft format with base/platforms instead of bases, added uv plugin configuration |
| docs/tutorial/write-your-first-machine-charm.md | Updated tool installation instructions to mention uv separately from tox |
| docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/set-up-your-development-environment.md | Complete rewrite with detailed VM setup, Concierge installation, and project directory mounting instructions |
| docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/observe-your-charm-with-cos-lite.md | Updated VM name references from charm-dev to juju-sandbox-k8s, charm name from demo-api-charm to fastapi-demo, model name from welcome-k8s to testing |
| docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/make-your-charm-configurable.md | Updated charm and model name references to match new naming conventions |
| docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/integrate-your-charm-with-postgresql.md | Updated VM, charm, and model name references throughout |
| docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/expose-operational-tasks-via-actions.md | Updated charm and model name references in example commands |
| docs/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md | Major restructure to use charmcraft init workflow instead of manual file creation, updated all references to new naming conventions |
| .github/workflows/example-charm-integration-tests.yaml | Moved k8s-1-minimal from one test matrix to another |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
dwilding
force-pushed
the
k8s-tutorial-minimal-charm
branch
from
95628b9 to
66261ee
Compare
james-garner-canonical
approved these changes
Jan 14, 2026
Contributor
james-garner-canonical
left a comment
james-garner-canonical
left a comment
There was a problem hiding this comment.
This looks great. I've asked a few questions and made a few wording suggestions, though I know that improving the wording was not the focus of this PR. Feel free to reject or defer these suggestions as needed.
dwilding
added a commit
that referenced
this pull request
Jan 19, 2026
Our httpbin demo charm packs to a file called `httpbin-demo_amd64.charm`
not `httpbin-demo_ubuntu-22.04-amd64.charm` (depending on the
architecture). That's because the charm's `charmcraft.yaml` has
```yaml
base: ubuntu@24.04
platforms:
amd64:
arm64:
```
instead of
```yaml
bases:
- build-on:
- name: ubuntu
channel: "22.04"
run-on:
- name: ubuntu
channel: "22.04"
```
[Related
discussion](#2259 (comment))
dwilding
added a commit
that referenced
this pull request
Jan 29, 2026
…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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is an intermediate PR for switching the Kubernetes charm tutorial to use uv and the latest Charmcraft profiles. Target branch is
k8s-tutorial-uvThis PR switches "Create a minimal Kubernetes charm" to use a charm project generated by the latest version of Charmcraft. That lets us remove several of the manual steps.
Preview doc
I'm fully updating "Create a minimal Kubernetes charm" and the corresponding example charm. I'm also partially updating subsequent chapters, for consistency of naming, but I'm not updating the subsequent example charms yet. I'll fully update the subsequent chapters and example charms in follow-on PRs.
There's some noise in the PR due to:
demo-api-charmtofastapi-demoIn
examples/k8s-minimal-1, the charm code incharm.pyand the unit & integration tests are essentially the same as before. Other charm files match what comes from Charmcraft. (charmcraft.yamlcomes with a placeholder config option, which we'll replace in a later chapter of the tutorial, in a subsequent PR.)So I think the most important part to review is
create-a-minimal-kubernetes-charm.md.