🩺 juju-doctor 🩺

Run a configurable set of probes (assertions) against Juju deployment artifacts, which are the output of other tools like juju, sosreport, and kubectl. To enforce best practices, these probes are organized into a ruleset, which acts as a guide for correct deployment configurations.

Purpose & value

• Unlike with goss, probes written by juju-doctor are equally usable on a live deployment as well as a (partial) support archive.
• Unlike with LLMs, juju-doctor is intended as read-only operations, no KUBECONFIG needed.
• Unlike with LLMs, you don't need to come up with prompts and pay for them for every troubleshooting session; instead, you can start with relying on probes that were written by others beforehand, from insights gained from previous incidents.
• Unlike with charm code, juju-doctor probes can be created and updated much faster, ad hoc, and put immediately in use, without needing to release and refresh charm(s).
  • This means that juju-doctor probes can serve as a "staging ground" for production teams to communicate the kind of self-test checks that charming teams should consider incorporating into the operator code.

Usage

Here's some typical usage examples:

∮ juju-doctor check --help # displays the help

You can run juju-doctor against a solution archive:

∮ juju-doctor check \
    --probe file://tests/resources/probes/python/failing.py \
    --probe file://tests/resources/probes/python/passing.py \
    --status=status.yaml \
    --bundle=bundle.yaml

If you have a live deplyoment, you can also run juju-doctor against that:

∮ juju-doctor check \
    --probe file://tests/resources/probes/python/failing.py \
    --probe file://tests/resources/probes/python/passing.py \
    --model model-one \
    --model model-two

In either case, the output will look like so (configurable with --format and --verbose):

Results
├── 🔴 tests_resources_probes_python_failing.py
└── 🟢 tests_resources_probes_python_passing.py

Total: 🟢 3/6 🔴 3/6

The path to a probe can also be a URL:

# Run a remote probe against a live model
∮ juju-doctor check --model cos --probe github://canonical/grafana-k8s-operator//probes/some_probe.py

Writing Probes

Scriptlet

Scriptlet probes are written in Python, and run on standardized artifacts that can be provided either as static files, or gathered from a live model.

Currently, we support the following artifacts:

• status: juju status --format=yaml
• bundle: juju export-bundle
• show_unit: juju show-unit --format=yaml

To write a probe, you should start by choosing an artifact. Your code will only have access to one artifact type at a time, but the input information can span multiple models.

Then, write a function named after your artifact (e.g., status, bundle, etc.) that takes one Dict argument: the artifact of choice indexed by model name. The function should raise an exception if you want your probe to fail, explaining why it failed.

Let's look at an example.

from typing import Dict

def status(juju_statuses: Dict[str, Dict]): # {'cos': juju_status_dict, ...}
    ... # do things with the Juju statuses
    if not all_good:
        raise Exception("'coconut' charm shouldn't be there!")

def bundle(juju_bundles: Dict[str, Dict]):
    ... # do things with the Juju bundles
    if not passing:
      raise Exception("who deployed the 'coconut' charm?")

def _first_check(...):
    ...

def _second_check(...):
    ...

# You can split multiple checks in functions
def show_unit(juju_show_units):
    ...
    _first_check()
    _second_check()

Remember: juju-doctor will only run functions that exactly match a supported artifact name, and will always pass to them a dictionary of model name mapped to the proper artifact.

For some real-world examples, check out the examples directory and this Grafana charm probe.

Ruleset

Ruleset probes are written in YAML, specifying which probes should be coordinated for a deployment validation.

Currently, the following probe types are supported:

• scriptlet: A Python probe
• ruleset: A declarative deployment RuleSet
• builtin/*: A builtin plugin of a type defined in the supported plugins

Run juju-doctor schema to output the schema of a RuleSet YAML file and check out this RuleSet probe as an extensive example.

Builtins

See this doc for contributing a builtin and general information about the builtin plugin design.

Development

git clone https://github.com/canonical/juju-doctor.git
uv sync --extra=dev && source .venv/bin/activate
uv pip install -e .
juju-doctor check --help