Charmcraft

Charmcraft Development Assistant

Expert guidance for developing, building, testing, and publishing Juju charms using charmcraft.

Core Workflows

Project Initialization

# Initialize new charm with profile
charmcraft init --profile=kubernetes       # K8s charm (default)
charmcraft init --profile=machine          # Machine charm
charmcraft init --profile=django-framework # Django app
charmcraft init --profile=fastapi-framework # FastAPI app
charmcraft init --profile=flask-framework  # Flask app

# With custom name and author
charmcraft init --name=my-charm --author="Your Name"

# List/expand extensions
charmcraft list-extensions
charmcraft expand-extensions

If the directory is not empty (for example, there's a plan, CLAUDE.md, or a .git folder), you need to add --force.

After init:

1. Customize charmcraft.yaml (metadata, bases, relations, config)
2. Edit README.md (becomes Charmhub documentation)
3. Implement src/charm.py (using Ops framework)
4. Update tests in tests/unit/ and tests/integration/

For detailed charmcraft.yaml configuration, see references/charmcraft-yaml-reference.md

Building and Packaging

# Build charm
charmcraft pack                    # Main command
charmcraft pack -o ./build/        # Custom output directory
charmcraft pack --bases-index=0    # Specific base (if multiple defined)

# Analyse charm (always run before uploading!)
charmcraft analyse ./my-charm_ubuntu-22.04-amd64.charm
charmcraft analyse --format=json ./my-charm.charm

# Clean build artifacts
charmcraft clean

# Remote build (for multi-architecture)
charmcraft remote-build

Build lifecycle: pack handles everything automatically. Only use individual steps (pull, build, stage, prime) for debugging.

Always run charmcraft analyse before uploading to catch:

• Missing/malformed metadata
• File permission issues
• Deprecated patterns

Testing

# Run tests
charmcraft test                    # Integration tests
charmcraft test --shell            # Debug environment
charmcraft test --debug            # Shell on failure

# Local quality checks
tox -e format                      # Format with ruff
tox -e lint                        # Lint with ruff + pyright
tox -e unit                        # Unit tests (ops.testing)
tox -e integration                 # Integration tests

Publishing to Charmhub

# Account setup
charmcraft login
charmcraft whoami
charmcraft register my-charm       # Register name first

# Upload and release
charmcraft upload ./my-charm.charm --release=edge
charmcraft status my-charm         # Check status
charmcraft revisions my-charm      # List revisions

# Release specific revision
charmcraft release my-charm --revision=5 --channel=stable

# Promote between channels
charmcraft promote my-charm --from=beta --to=stable

# Close channel
charmcraft close my-charm edge

Channel structure: [track/]risk[/branch]

• Risks: edge → beta → candidate → stable
• Examples: stable, edge, 2.0/candidate, beta/hotfix-123

Always: Upload to edge first, test thoroughly, then promote through channels.

Resources

# Manage resources (images, binaries)
charmcraft resources my-charm
charmcraft upload-resource my-charm my-resource --filepath=./file.tar.gz
charmcraft resource-revisions my-charm my-resource

# Release with specific resources
charmcraft release my-charm --revision=5 --channel=stable --resource=my-resource:3

Library Management

Always look for a version of the library on charmlibs first, and use those in preference to ones from Charmhub via charmcraft.

# Using libraries (define in charmcraft.yaml first)
charmcraft fetch-libs              # Fetch defined libraries
charmcraft list-lib postgresql     # List available libs

# Publishing libraries
charmcraft create-lib my-charm my_library
charmcraft publish-lib charms.my_charm.v0.my_library

In charmcraft.yaml:

charm-libs:
  - lib: postgresql.postgres_client
    version: "0"           # Major version (auto-updates minor)
  - lib: mysql.client
    version: "0.57"        # Pinned version

Library versioning:

• v0, v1 = breaking changes (API changes)
• Patch auto-increments for non-breaking changes
• Libraries go in lib/charms/{charm_name}/v{X}/{lib_name}.py

Essential Files

charmcraft.yaml

Core configuration defining:

• Charm metadata (name, title, summary, description)
• Base OS (bases)
• Build config (parts)
• Relations (provides, requires, peers - always use optional: true for requires!)
• Config options (config)
• Actions (actions)
• Resources (resources)
• Containers (K8s charms)

See references/charmcraft-yaml-reference.md for complete specification.

src/charm.py

Main charm implementation:

• Config/action dataclasses
• Charm class (extends CharmBase)
• Event observation and handlers
• Uses Ops framework: https://documentation.ubuntu.com/ops/

Best Practices

Development Workflow

1. Write integration tests first - define expected behavior
2. Implement incrementally - get basic functionality working
3. Run quality checks - tox -e lint and tox -e format frequently
4. Analyse before upload - charmcraft analyse on every build
5. Test locally - charmcraft pack then juju deploy ./my-charm.charm

Documentation

Keep updated:

• README.md - Main docs (appears on Charmhub)
• CONTRIBUTING.md - Development workflow
• CHANGELOG.md - User-facing changes
• SECURITY.md - Security reporting
• TUTORIAL.md - Basic usage guide

Version Control

Commit: charmcraft.yaml, all source, uv.lock, pyproject.toml, tests, docs

Ignore: *.charm, __pycache__/, .tox/, venv/, .claude/settings.local.json

Common Patterns

Pack for specific base: charmcraft pack --bases-index=0

Database Integration Example

# In charmcraft.yaml
requires:
  database:
    interface: postgresql_client
    optional: true  # ALWAYS include the `optional` field, rather than relying on the default. Use `optional: false` if the charm works without the relation

charm-libs:
  - lib: data_platform_libs.data_interfaces
    version: "0"

# In src/charm.py
from charms.data_platform_libs.v0.data_interfaces import DatabaseRequires


class MyCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        self.database = DatabaseRequires(self, "database", "myapp")
        self.framework.observe(self.database.on.database_created, self._on_database_created)

Troubleshooting

Build fails:

• Check charmcraft.yaml syntax
• Verify required files exist (src/charm.py, uv.lock)
• Run charmcraft -v pack for verbose output

Upload fails:

• Login: charmcraft login
• Register name: charmcraft register my-charm
• Analyse first: charmcraft analyse ./my-charm.charm

Library errors:

• Fetch: charmcraft fetch-libs
• Check library definitions in charmcraft.yaml

Runtime issues:

• Check Juju logs: juju debug-log
• Verify resources uploaded: charmcraft resources my-charm
• Test base compatibility

For comprehensive troubleshooting, see references/troubleshooting.md

Quick Reference

# Setup
charmcraft init --profile=kubernetes
charmcraft login

# Development cycle
charmcraft pack
charmcraft analyse ./my-charm.charm
tox -e lint
tox -e unit

# Publishing
charmcraft upload ./my-charm.charm --release=edge
charmcraft status my-charm
charmcraft promote my-charm --from=edge --to=beta

# Libraries
charmcraft fetch-libs
charmcraft publish-lib charms.my_charm.v0.my_library

# Testing with Juju
juju deploy ./my-charm.charm
juju status
juju debug-log

Resources

• Charmcraft docs: https://documentation.ubuntu.com/charmcraft/stable/
• Juju docs: https://documentation.ubuntu.com/juju/latest/
• Ops framework: https://documentation.ubuntu.com/ops/latest/
• Charmhub: https://charmhub.io/

Additional References

When you need detailed information:

• Complete charmcraft.yaml reference: See references/charmcraft-yaml-reference.md
• Troubleshooting guide: See references/troubleshooting.md
• Quick project setup: Use scripts/quick-start.sh helper

Key reminders:

• Always run charmcraft analyse before uploading
• Test on edge before promoting to stable
• Use optional: true for all requires relations
• Keep uv.lock in version control
• Follow conventional commits for changelogs