JujuTool: The Complete Beginner’s GuideJujuTool is an emerging utility for managing, inspecting, and working with Juju models, charms, and deployments. This guide explains what JujuTool is, why it’s useful, how to install it, core commands and workflows, common tasks for beginners, troubleshooting tips, and where to go next.
What is JujuTool?
JujuTool is a command-line utility designed to simplify interacting with Juju environments. It provides helpers that make common operations—such as examining models, downloading bundles, inspecting charm metadata, and exporting deployment states—faster and more consistent. While Juju (the orchestration system) focuses on deploying and managing services, JujuTool complements it by easing local inspection, automation scripting, and diagnostics.
Why use JujuTool?
- Faster inspection: Quickly view model, unit, or relation details without composing complex juju queries.
- Automation-friendly: Commands can be scripted to integrate with CI/CD or management workflows.
- Consistency: Standardized outputs and shortcuts reduce human error.
- Debugging aid: Helpful for gathering data for support or diagnosing why a deployment isn’t behaving as expected.
Installing JujuTool
Installation steps vary by platform and distribution. Below are general patterns; consult the project’s official repo or package source for the most current instructions.
-
On macOS (Homebrew):
brew install jujutool
-
On Debian/Ubuntu (APT):
sudo apt update sudo apt install jujutool
-
From source (generic):
git clone https://example.org/jujutool.git cd jujutool make build sudo make install
If there’s a prebuilt binary for your OS, downloading and placing it in your PATH is a quick option. After installing, verify with:
jujutool --version
Getting started: connecting to Juju
JujuTool assumes you have Juju client credentials set up and can access controllers and models. Typical Juju setup steps:
- Install juju client:
snap install juju --classic
- Add or login to a controller:
juju bootstrap <cloud> <controller-name> juju add-model <model-name>
- Confirm juju status works:
juju status
With Juju reachable, JujuTool commands that query models and charms will function.
Core JujuTool commands and patterns
Note: command names below reflect common patterns—actual names may differ depending on the JujuTool release. Use jujutool help
for an index.
- jujutool models — list available models and basic metadata
- jujutool status
— compact model status snapshot - jujutool inspect-charm
— show charm metadata, actions, and config schema - jujutool fetch-bundle
— download and expand a bundle to local directory - jujutool export-model
–format yaml/json — export model definition for backup or review - jujutool relations
— list relations and endpoints with endpoints mapping - jujutool logs
— tail or fetch recent logs for a particular unit - jujutool gather-diagnostics
–output path — produce normalized diagnostics archive for support
Command examples:
jujutool inspect-charm cs:~openstack-charmers/haproxy-36 jujutool export-model mymodel --format yaml > mymodel-export.yaml jujutool gather-diagnostics mymodel --output diagnostics-mymodel.tar.gz
Typical beginner workflows
-
Inspect a charm before deploying:
- Use inspect-charm to view config options, resources, and required relations. This avoids surprises when deploying a new charm.
- Example: determine what configuration keys you must set for a database charm.
-
Download and review a bundle:
- fetch-bundle lets you download a bundle and open its YAML to understand service relations and constraints before deploying.
-
Export model state for backup or sharing:
- export-model provides a portable representation of services, placements, and config.
-
Gather and share diagnostics:
- When seeking help, gather-diagnostics creates a consistent archive containing logs, status outputs, and charm metadata.
-
Script repetitive tasks:
- Combine jujutool commands in shell scripts or CI pipelines to standardize deployments or auditing.
Examples: practical commands
-
View models and their controllers:
jujutool models --verbose
-
Show all relations in a human-friendly tree:
jujutool relations mymodel --tree
-
Download a charm resource (if supported):
jujutool fetch-resource cs:~foo/bar-10 resource-name --output ./resources
-
Tail logs for a unit and filter for errors:
jujutool logs unit/myapp/0 | grep -i error
Output formats and scripting
JujuTool can often emit JSON or YAML to facilitate scripting. Prefer machine-readable formats when writing automation:
-
JSON example:
jujutool export-model mymodel --format json | jq '.services'
-
YAML example:
jujutool inspect-charm cs:apache-78 --format yaml > apache-charm.yaml
This lets tools like jq, yq, or native language parsers handle the data.
Common pitfalls and troubleshooting
- Authentication issues: ensure your Juju credentials and controller access are valid. Run juju whoami and juju controllers to confirm.
- Version mismatches: Juju and JujuTool versions may introduce incompatible output/flags. Keep tools updated and check changelogs.
- Network/timeouts: commands that fetch resources or talk to controllers depend on network stability; use timeouts and retries in scripts.
- Insufficient privileges: some commands require controller or model-level permissions; run them as a user with the appropriate role.
If a command fails, rerun with a verbose or debug flag (for example, –debug) and capture output for support.
Extending JujuTool: plugins and integration
Many users extend JujuTool via scripts or plugins to add organization-specific checks, reporting, or integrations (Slack, GitHub Actions, Prometheus). Typical extension points:
- Hook scripts that call jujutool and process outputs
- CI jobs that use jujutool to validate charms or bundles before merge
- Custom reporters that ingest export-model output and produce inventory dashboards
Security and best practices
- Treat exported model files and diagnostics archives as sensitive if they contain configuration values or secret references. Store them securely.
- Rotate Juju credentials and follow your organization’s secret-management practices.
- Use least-privilege roles for operators interacting with Juju controllers and models.
Where to learn more
- Official Juju documentation and charm store for authoritative charm and bundle details.
- Project repository or homepage for JujuTool for the latest install instructions, issue tracker, and changelog.
- Community forums, mailing lists, and chat channels for examples and help from other operators.
Quick reference (cheat sheet)
- Inspect charm: jujutool inspect-charm
- Download bundle: jujutool fetch-bundle
- Export model: jujutool export-model
–format yaml|json - Gather diagnostics: jujutool gather-diagnostics
–output - List relations: jujutool relations
JujuTool helps bridge the gap between raw Juju commands and daily operational needs by offering concise, scriptable helpers for inspection, export, and diagnostics. For a beginner, focus on inspect-charm, fetch-bundle, and export-model—those will make deploying and understanding services much easier.