Concierge

Concierge Development Environment Assistant

Expert guidance for provisioning and managing charm development and testing environments using concierge.

What is Concierge?

Concierge is an opinionated utility for automating the setup of charm development machines. It:

• Installs craft tools (charmcraft, snapcraft, rockcraft)
• Configures providers (LXD, MicroK8s, K8s, Google Cloud)
• Bootstraps Juju controllers
• Installs additional packages (snaps and debs)
• Provides environment restoration capabilities

Core Workflows

Quick Start with Presets

# Full development environment (recommended for most developers)
concierge prepare -p dev

# Machine charm development only
concierge prepare -p machine

# Kubernetes-focused development
concierge prepare -p k8s

# Lightweight K8s with MicroK8s
concierge prepare -p microk8s

# Build tools only (no Juju)
concierge prepare -p crafts

Presets comparison:

Legend:

• ✓ = Installed
• ✓† = Installed and bootstrapped with Juju controller
• ✓* = Installed but NOT bootstrapped (only for charmcraft build backend)
• — = Not included

For detailed preset information, see references/presets.md

Environment Status

# Check provisioning status
concierge status

# Possible states:
# - "provisioning" - Setup in progress
# - "succeeded" - Ready for development
# - "failed" - Setup encountered errors

Restoring Original State

# Reverse the prepare operation
concierge restore

⚠️ CRITICAL WARNING:

• restore does NOT account for packages/configuration that existed before prepare
• It literally reverses the prepare operation
• If you had LXD installed before running prepare, restore will remove it
• Use with caution on machines with existing configurations

Custom Configuration

Create a concierge.yaml file in your working directory:

juju:
  channel: "3.6/stable"
  agent_version: "3.6.0"
  bootstrap_constraints:
    cores: 4
    mem: 8G
  model_defaults:
    logging-config: "<root>=INFO"

providers:
  microk8s:
    enable: true
    bootstrap: true
    channel: "1.31-strict/stable"

  lxd:
    enable: true
    bootstrap: true
    channel: "5.21/stable"

  k8s:
    enable: false

  gcloud:
    enable: false

host:
  snaps:
    - name: astral-uv
      channel: "latest/edge"
      classic: true
    - name: jhack
      channel: "latest/stable"

  debs:
    - build-essential
    - python3-dev

Then run:

concierge prepare -c concierge.yaml

For complete YAML schema, see references/configuration.md

Overriding Configuration

# Override snap channels
concierge prepare -p dev --juju-channel=4.0/edge

# Install extra packages
concierge prepare -p dev \
  --extra-snaps=astral-uv/latest/edge,jhack \
  --extra-debs=build-essential,python3-tox

# Skip Juju installation/bootstrap
concierge prepare -p crafts --disable-juju

# Use Google Cloud credentials
concierge prepare -p k8s --google-credential-file=~/gcloud-creds.json

Channel override flags:

• --juju-channel
• --lxd-channel
• --k8s-channel
• --microk8s-channel
• --charmcraft-channel
• --snapcraft-channel
• --rockcraft-channel

Environment Variables

All flags have environment variable equivalents:

# Set via environment
export CONCIERGE_JUJU_CHANNEL="4.0/edge"
export CONCIERGE_EXTRA_SNAPS="astral-uv/latest/edge,jhack"
export CONCIERGE_EXTRA_DEBS="build-essential"

concierge prepare -p dev

Variable naming: Flag --juju-channel becomes CONCIERGE_JUJU_CHANNEL

Common Workflows

Setting Up a New Development Machine

# 1. Install concierge
sudo snap install --classic concierge

# 2. Prepare full dev environment
concierge prepare -p dev --extra-snaps=jhack

# 3. Verify installation
concierge status
juju controllers
lxc list

# 4. Start developing
cd my-charm-project
charmcraft pack
juju deploy ./my-charm.charm

Quick K8s Testing Environment

# Prepare K8s environment
concierge prepare -p k8s

# Verify controller
juju controllers
juju models

# Deploy a K8s charm
juju add-model test
juju deploy postgresql-k8s

Minimal Build-Only Setup

# Just install craft tools (no Juju)
concierge prepare -p crafts

# Build charms and rocks
cd my-charm
charmcraft pack

cd ../my-rock
rockcraft pack

CI/CD Environment Setup

# Automated setup for CI
concierge prepare -p dev \
  --juju-channel=3.6/stable \
  --extra-snaps=astral-uv/latest/edge \
  --extra-debs=python3-tox,make

# Check it worked
concierge status
if [ $? -eq 0 ]; then
  echo "Environment ready"
fi

Cleaning Up After Testing

# Remove everything concierge installed
concierge restore

# Verify cleanup
concierge status

Best Practices

Choosing a Preset

1. Use dev for general charm development - Includes everything most developers need
2. Use machine for traditional charms - No K8s overhead
3. Use k8s or microk8s for K8s-only work - Lighter than dev
4. Use crafts for build servers - Minimal installation for building only

Configuration Management

1. Check config into version control - Share team configurations via concierge.yaml
2. Use environment variables in CI - Easier than managing config files
3. Document custom setups - Add comments to concierge.yaml
4. Test configurations locally first - Before deploying to CI

Safety

1. ⚠️ Never run restore on production machines - It removes configurations blindly
2. Use virtual machines for testing - Try configurations safely
3. Check status before and after - concierge status shows what happened
4. Review preset contents - Know what will be installed before running

Development Workflow

1. Prepare once per machine - Don't re-run prepare unnecessarily
2. Update tools via snap - Use snap refresh for updates, not restore+prepare
3. Use jhack for iteration - Once environment is ready, jhack speeds up development
4. Keep environments consistent - Use same preset across team

Troubleshooting

Prepare Fails

# Run with verbose logging
concierge prepare -p dev -v

# Run with trace logging for detailed output
concierge prepare -p dev --trace

# Check status
concierge status

Common issues:

• Insufficient permissions - Run with sudo
• Network connectivity - Check internet access
• Conflicting installations - Remove existing snaps first
• Disk space - Ensure adequate free space (10GB+ recommended)

Controller Bootstrap Fails

If Juju controller bootstrap fails:

# Check Juju logs
juju debug-log -m controller

# Manually bootstrap if needed
juju bootstrap lxd
juju bootstrap microk8s

# Check provider status
lxc list            # For LXD
microk8s status     # For MicroK8s

Restore Issues

# Check what will be restored
concierge status

# Run restore with logging
concierge restore -v

If restore fails:

• Check sudo/root access
• Review logs for specific errors
• Manually remove remaining configurations

Snap Installation Failures

# Check snap connectivity
snap version
snap list

# Manually install problematic snaps
sudo snap install juju --channel=3.6/stable --classic

# Then retry prepare
concierge prepare -p dev

Command Reference

# Prepare environment
concierge prepare [flags]
concierge prepare -p <preset>
concierge prepare -c <config-file>

# Check status
concierge status

# Restore/cleanup
concierge restore

# Shell completion
concierge completion bash
concierge completion zsh
concierge completion fish

# Help
concierge --help
concierge prepare --help
concierge --version

# Logging
concierge prepare -p dev -v        # Verbose
concierge prepare -p dev --trace   # Trace (very detailed)

Integration with Development Tools

With Charmcraft

# Prepare environment
concierge prepare -p dev

# Develop charm
cd my-charm
charmcraft init --profile=kubernetes
charmcraft pack
charmcraft test

# Deploy
juju deploy ./my-charm.charm

With Jhack

# Install jhack during prepare
concierge prepare -p dev --extra-snaps=jhack

# Or add to concierge.yaml
# host:
#   snaps:
#     - name: jhack
#       channel: latest/stable

# Use jhack for development
jhack sync src/ myapp/0
jhack tail myapp/0

With Tox and UV

# Install build tools
concierge prepare -p dev \
  --extra-snaps=astral-uv/latest/edge \
  --extra-debs=python3-tox

# Use in charm development
cd my-charm
tox -e lint
tox -e unit
uv sync

With CI/CD

# GitHub Actions example
- name: Prepare environment
  run: |
    sudo snap install --classic concierge
    concierge prepare -p dev --extra-snaps=astral-uv/latest/edge

- name: Verify setup
  run: concierge status

- name: Run tests
  run: |
    charmcraft pack
    charmcraft test

Configuration Priority

Concierge uses this priority order (highest to lowest):

1. Command-line flags - --juju-channel=4.0/edge
2. Environment variables - CONCIERGE_JUJU_CHANNEL=4.0/edge
3. Configuration file - concierge.yaml
4. Preset defaults - Built-in preset values
5. Fallback - If no config found, defaults to dev preset

Quick Reference

# Common operations
concierge prepare -p dev                   # Full dev environment
concierge prepare -p machine               # Machine charm dev
concierge prepare -p k8s                   # K8s charm dev
concierge status                           # Check status
concierge restore                          # Remove everything

# With customisation
concierge prepare -p dev --extra-snaps=jhack
concierge prepare -p dev --juju-channel=4.0/edge
concierge prepare -c my-config.yaml
concierge prepare -p dev -v                # Verbose output

# Environment variables
export CONCIERGE_JUJU_CHANNEL="3.6/stable"
export CONCIERGE_EXTRA_SNAPS="jhack"
concierge prepare -p dev

Resources

• Concierge GitHub: https://github.com/canonical/concierge
• Juju docs: https://documentation.ubuntu.com/juju/latest/
• Charmcraft docs: https://documentation.ubuntu.com/charmcraft/
• LXD docs: https://documentation.ubuntu.com/lxd/
• MicroK8s docs: https://microk8s.io/docs

Additional References

When you need detailed information:

• Complete preset comparison: See references/presets.md
• Configuration YAML schema: See references/configuration.md

Key reminders:

• Choose the right preset for your use case
• restore does NOT preserve pre-existing configurations
• Use concierge status to verify setup
• Add --extra-snaps=jhack for rapid development
• Run with -v or --trace when troubleshooting