Skip to content

feat: add a private multi-charm model for ops.testing - #2913

Draft
tonyandrewmeyer wants to merge 9 commits into
canonical:mainfrom
tonyandrewmeyer:saddle/split-03a-model
Draft

tonyandrewmeyer wants to merge 9 commits into
canonical:mainfrom
tonyandrewmeyer:saddle/split-03a-model

Conversation

@tonyandrewmeyer

@tonyandrewmeyer tonyandrewmeyer commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Adds a private model of a Juju deployment, so that several charms can be tested together: Juju holds applications and their units, each unit has its own State, and settle() runs the events that Juju would run for the operations so far. Nothing is exported yet. This is the first of three PRs for the model, with peer relations next and then config(), to_context() and the dispatch-order hooks.

  • deploy() takes a CharmSpec (the charm class and its metadata, shaped like charmcraft.yaml) or a charm class with its metadata beside its source, as Context does. Deploying a charm from a path will come with running applications in a worker process.
  • Each unit runs Juju's startup sequence (install, leader-elected on unit 0 and leader-settings-changed on the others, config-changed, start, then pebble-ready for each container).
  • Each unit has its own queue, and the units take turns, one event each, in deploy order, with the turn carrying on into the next settle(). Keeping each unit's own order separate from the order across units means the order across units can be varied later without changing what any one unit sees.
  • Secret IDs are seeded from the unit's own dispatch count, and the model name and UUID default to fixed values, so a test gives the same State on every run. (Two Jujus in one test share a name and UUID, so their secret IDs can match.)
  • The model is on a Kubernetes cloud named localhost unless the test gives a CloudSpec, so a trusted charm can read its cloud spec. On Kubernetes with Juju before 3.6.10 the unit gets no cloud spec, as with Juju.
  • state_template is for what the model can't know (such as Exec mocks, storage, and stored state), and a template that sets a field the model owns is rejected.

The classes that will be exported (Juju, App, Unit, Dispatch, CharmSpec) already have full docstrings, which is most of the source. I think they're the easiest way to check the behaviour is what's intended. For the rest, I'd read Juju.deploy(), then _add_unit(), settle() and _dispatch(), and then the tests.

Add `Juju`, `App`, `Unit`, `Dispatch` and `CharmSpec` in a private
module, with `deploy()`, `add_unit()` and `settle()`, for charms that
run in the test process. Nothing is exported yet.

`deploy()` takes a `CharmSpec` or a charm class with its metadata beside
its source, checks `config` against the charm's options, and raises
`JujuError` for an unknown option or a value of the wrong type. Each
unit runs Juju's startup sequence: `install`, `leader-elected` on unit 0
and `leader-settings-changed` on the others, `config-changed`, `start`,
then `pebble-ready` for each container.

`settle()` dispatches until nothing is pending. Each unit has its own
queue, and the units take turns, one event each, in deploy order, so
that the order across units can be varied later without changing any
unit's own order. Secret IDs are seeded by the unit's own dispatch
count, so they're the same on every run and stay the same if the order
across units changes.

The model name and UUID default to fixed values, so anything derived
from them is the same on every run. The model is on a Kubernetes cloud
named `localhost` unless the test gives a cloud spec, so a trusted charm
can read it, except on Kubernetes with Juju before 3.6.10, which doesn't
give charms one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tonyandrewmeyer and others added 7 commits November 18, 2026 15:16
Tests for a machine model keeping its cloud spec on Juju before 3.6.10,
the Juju version reaching the charm, a missing application name, a
template container the metadata doesn't declare, two secrets from one
unit getting different IDs, and `close()` dropping the applications.

Binding a `pebble-ready` event to its container can't fail, because a
charm can't remove its own containers, so it's an assert rather than a
skip.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The constants are private, so autodoc never renders them and `#:`
comments with Sphinx roles only make them harder to read.

The default model UUID now spells something in hex rather than looking
random, so it's easy to recognise as the default in a failing test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each unit gets the instances of each store its metadata asks for (the
minimum of multiple.range, or one), or the count passed with storage=,
checked as Juju checks --storage. Instances are numbered from one
model-wide sequence, as Juju does. storage-attached runs before install
in a machine model and after start in a Kubernetes model, matching the
uniter's storage resolver. storages is now a Juju-owned State field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Juju deploys a charm that declares containers to a machine model, but
only the Kubernetes agent watches containers, so there is no Pebble to
connect to and no pebble-ready. Default the containers to
can_connect=False and queue pebble-ready only in a Kubernetes model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Juju runs <container>-pebble-ready once the unit agent has seen the
container's Pebble come up, and a charm can't rely on reaching Pebble
before that. The model gave a container whatever can_connect the
template set (or true on Kubernetes) from install on, so a charm that
called Pebble unguarded in install passed, and one that waited for the
container could wait for ever.

Every container now starts unconnectable and becomes connectable when
its pebble-ready is dispatched, for units deployed with the application
and units added later. A state_template container may no longer set
can_connect, since Juju decides it.
@tonyandrewmeyer

Copy link
Copy Markdown
Collaborator Author

This is bigger than I wanted to make any of the PRs for this feature (it's roughly 50/50 code and tests). I split out the parts that seemed easiest to logically do separately, but it left ~800 lines of code. Let me know if this is too large and I can try to figure out how to do more splits.

Juju 4 removed leader settings, and with them leader-settings-changed, so
a unit that isn't the leader no longer gets one at startup when the charm
is deployed with a juju_version of 4 or later. The leader still gets
leader-elected, and the rest of the startup order is unchanged. The
default version is 3.6, so nothing changes unless a test asks for Juju 4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M2H4WjJ1cbsAx2YAXVD4sR

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant