canonical Skill: setup-charm-tests
Goal
Install only the prerequisites needed for charm integration testing:
- Cloud substrates (LXD and/or Kubernetes) - only what you need
- Logging tools (always installed for all scenarios)
The test suite automatically bootstraps controllers when you use --current-state "no_bundle" or --current-state "no_controller".
Quick Start
Machine Charm Testing (LXD only)
/setup-charm-tests --platform machine
- ✅ Install and configure LXD
- ✅ Install logging tools
- ✅ Skip Kubernetes setup
- ⏳ Test suite will bootstrap LXD controller when needed
Kubernetes Charm Testing (K8s only)
/setup-charm-tests --platform kubernetes
- ✅ Install and configure Canonical k8s
- ✅ Install logging tools
- ✅ Skip LXD setup
- ⏳ Test suite will bootstrap K8s controller when needed
Cross-Model Relation Testing (LXD + K8s)
/setup-charm-tests --platform mixed
- ✅ Install and configure LXD
- ✅ Install and configure Canonical k8s
- ✅ Install logging tools
- ⏳ Test suite will bootstrap both controllers when needed
Default (Everything)
/setup-charm-tests
- ✅ Installs all substrates and tools (same as
--platform mixed)
What Gets Installed
Logging & Debugging Tools (Always Installed)
Always install these regardless of platform, since log collection needs both tools:
juju-crashdump (snap)
- Collects logs from machine/LXD controllers
- Captures unit logs, charm output, and Juju internals
juju-k8s-crashdump (git+pip)
- Collects logs from Kubernetes controllers
- Captures pod logs, statefulset events, and K8s-specific state
- Required for reproducing issue #693 (mixed-cloud CMR logging)
kubectl (snap)
- Inspect Kubernetes pods and events
- Used by juju-k8s-crashdump
Cloud Substrates (Optional based on --platform)
LXD (when --platform machine or --platform mixed)
- Juju cloud name:
localhost - Platform: machine (LXD containers)
- Use for: Traditional machine charms
Canonical Kubernetes (when --platform kubernetes or --platform mixed)
- Juju cloud name:
local-k8s - Platform: Kubernetes (pod-based)
- Use for: Kubernetes-native charms
- Kubeconfig:
/home/ubuntu/k8s.yaml
Step-by-Step Setup
Option 1: Machine Charms Only (LXD)
# 1. Install logging tools
sudo snap install juju-crashdump --classic
sudo snap install kubectl --classic
pipx install "git+https://github.com/canonical/juju-k8s-crashdump.git@22ef04caaeeb94ad6ed49f8392b6bada65184569#egg=juju-k8s-crashdump"
# 2. Setup LXD only
$PROJECT_ROOT/development-sandbox/bin/setup-lxd.sh
# That's it! Test suite will bootstrap controller when you run tests with --current-state
Option 2: Kubernetes Charms Only
# 1. Install logging tools
sudo snap install juju-crashdump --classic
sudo snap install kubectl --classic
pipx install "git+https://github.com/canonical/juju-k8s-crashdump.git@22ef04caaeeb94ad6ed49f8392b6bada65184569#egg=juju-k8s-crashdump"
# 2. Setup K8s only
$PROJECT_ROOT/development-sandbox/bin/setup-k8s.sh
# That's it! Test suite will bootstrap controller when you run tests with --current-state
Option 3: Mixed-Cloud CMR Tests (LXD + K8s)
# 1. Install logging tools
sudo snap install juju-crashdump --classic
sudo snap install kubectl --classic
pipx install "git+https://github.com/canonical/juju-k8s-crashdump.git@22ef04caaeeb94ad6ed49f8392b6bada65184569#egg=juju-k8s-crashdump"
# 2. Setup both substrates
$PROJECT_ROOT/development-sandbox/bin/setup-lxd.sh
$PROJECT_ROOT/development-sandbox/bin/setup-k8s.sh
# That's it! Test suite will bootstrap both controllers when you run tests with --current-state
Installing Logging Tools Details
All three tools should be installed regardless of which clouds you're using, since you might need both for log collection in mixed-cloud scenarios.
# juju-crashdump: For machine/LXD controllers
sudo snap install juju-crashdump --classic
# kubectl: For Kubernetes inspection and juju-k8s-crashdump support
sudo snap install kubectl --classic
# juju-k8s-crashdump: For Kubernetes controllers
# Using specific commit hash from charm-testing.yaml workflow
pipx install "git+https://github.com/canonical/juju-k8s-crashdump.git@22ef04caaeeb94ad6ed49f8392b6bada65184569#egg=juju-k8s-crashdump"
Note: If installation fails, see Troubleshooting section below.
Running Tests After Setup
Once setup is complete, run tests with the test suite. The suite handles controller bootstrap based on --current-state:
# The test suite will bootstrap LXD controller automatically
./scripts/run-tests.sh \
--target-cloud "localhost" \
--target-charm "postgresql" \
--target-endpoint "database" \
--target-application "target" \
--current-state "no_bundle" \
--mermaid-output "./bundle.mmd" \
...
# The test suite will bootstrap both controllers for CMR
./scripts/run-tests.sh \
--target-cloud "localhost" \
--target-charm "glauth-utils" \
--neighbor-cloud "local-k8s" \
--neighbor-charm "glauth-k8s" \
--current-state "no_bundle" \
...
See the run-charm-tests skill for full test execution documentation.
Verification
Check Logging Tools
juju-crashdump --version
juju-k8s-crashdump --help # Should show help without errors
kubectl version --client
Check Cloud Setup (after running tests)
Once you run tests, controllers will be created and you can verify:
# Check what clouds are registered
juju clouds
# List controllers (will be auto-created by test suite)
juju controllers
Troubleshooting
Problem: "LXD is already installed"
This is fine! The setup scripts are idempotent:
$PROJECT_ROOT/development-sandbox/bin/setup-lxd.sh
# Output: LXD substrate ready (or already configured)
Problem: "Cannot install juju-k8s-crashdump"
The tool is in a private repository. If you encounter issues:
# Try with git+https instead of git+ssh
git clone https://github.com/canonical/juju-k8s-crashdump.git
cd juju-k8s-crashdump
pip install .
# Or use the commit hash from charm-testing.yaml
pip install "git+https://github.com/canonical/juju-k8s-crashdump@22ef04caaeeb94ad6ed49f8392b6bada65184569"
Problem: "kubeconfig not found"
If /home/ubuntu/k8s.yaml doesn't exist:
# Re-run K8s setup
$PROJECT_ROOT/development-sandbox/bin/setup-k8s.sh
# Verify location
ls -la /home/ubuntu/k8s.yaml
Problem: "juju-crashdump: command not found"
If snap installation failed:
# Try reinstalling
sudo snap remove juju-crashdump
sudo snap install juju-crashdump --classic
juju-crashdump --version
Problem: "Controller bootstrap timeout"
LXD and K8s bootstrap can take 5-10 minutes on first run. If timeout occurs:
# Check controller status
juju controllers
# Wait and retry
juju bootstrap localhost lxd-ctrl
# Or check logs
juju debug-log -c lxd-ctrl --limit 50
Next Steps
After setup completes, you can run charm integration tests:
# Test a single charm on LXD
./scripts/run-tests.sh \
--target-cloud "localhost" \
--target-charm "postgresql" \
--target-endpoint "database" \
--target-application "target" \
--mermaid-output "./bundle.mmd" \
--current-state "no_bundle" \
--prefix "test-1"
# Test mixed-cloud CMR (LXD + K8s)
./scripts/run-tests.sh \
--target-cloud "localhost" \
--target-charm "glauth-utils" \
--target-endpoint "glauth-auxiliary" \
--target-application "target" \
\
--neighbor-cloud "local-k8s" \
--neighbor-charm "glauth-k8s" \
--neighbor-endpoint "glauth-auxiliary" \
--neighbor-application "neighbor" \
\
--current-state "no_bundle" \
--mermaid-output "./bundle.mmd" \
--prefix "test-cmr-1"
See the run-charm-tests skill for full documentation.
Key References
- charm-testing.yaml: Official workflow that shows the canonical setup process
- setup-lxd.sh:
$PROJECT_ROOT/development-sandbox/bin/setup-lxd.sh - setup-k8s.sh:
$PROJECT_ROOT/development-sandbox/bin/setup-k8s.sh - Issue #693: Mixed-cloud CMR logging (requires juju-k8s-crashdump)
Environment Details
- Project: charm-integration-testing
- Python: 3.12+
- Juju: 3/stable (3.6.25+)
- LXD: 5.21+
- Kubernetes: 1.32+ (Canonical k8s)
- System: Linux (Ubuntu 22.04+)
Skill Version: 1.0
Last Updated: July 3, 2026