Charm SDK Documentation

The Charm SDK documentation presupposes familiarity with Juju.

The Charm SDK is a toolkit for building charms.

The SDK provides a Python library for developing and testing charms, ops, and a CLI tool for building, packaging and publishing charms, charmcraft.

A charm can be developed in a variety of ways. However, the SDK provides useful abstractions and CLI commands so you can develop and share your charm better and faster.

Whether you are a charm developer or a charm end user, with the Charm SDK you get a smoother experience.

For a collection of existing charms, see Charmhub. To deploy and manage an existing or new charm, see Juju docs.

In this documentation

Get started - a hands-on introduction to the Charm SDK for new users
How-to guides
Step-by-step guides covering key operations and common tasks
Concepts - discussion and clarification of key topics
Technical information - specifications, APIs, architecture

Project and community

The Juju SDK is an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback.


Level Path Navlink
1 SDK documentation
1 tutorials Tutorials
2 write-your-first-machine-charm Write your first machine charm
2 from-zero-to-hero-write-your-first-kubernetes-charm Write your first Kubernetes charm
3 study-your-application Study your application
3 set-up-your-development-environment Set up your development environment
3 create-a-minimal-kubernetes-charm Create a minimal Kubernetes charm
3 make-your-charm-configurable Make your charm configurable
3 expose-the-version-of-the-application-behind-your-charm Expose the version of the application behind your charm
3 integrate-your-charm-with-postgresql Integrate your charm with PostgreSQL
3 preserve-your-charms-data Preserve your charm’s data
3 expose-your-charms-operational-tasks-via-actions Expose your charm’s operational tasks via actions
3 observe-your-charm-with-cos-lite Observe your charm with COS Lite
3 write-unit-tests-for-your-charm Write unit tests for your charm
3 write-scenario-tests-for-your-charm Write scenario tests for your charm
3 write-integration-tests-for-your-charm Write integration tests for your charm
3 open-a-kubernetes-port-in-your-charm Open a Kubernetes port in your charm
3 publish-your-charm-on-charmhub Publish your charm on Charmhub
1 how-to How-to guides
2 dev-setup Set up your development environment
2 Implement core charm functionality
3 set-up-a-charm-project Set up a charm project
3 config Add a config option to a charm
3 actions Add an action to a charm
3 workloads Run workloads with a charm
3 logging Configure logging in a charm
3 interact-with-pebble Interact with Pebble
2 Test and debug a charm
3 pack-a-charm Pack a charm
3 deploy-a-charm Deploy a charm
3 write-a-unit-test-for-a-charm Write a unit test for a charm
3 write-a-functional-test-for-a-charm-with-scenario Write a functional test for a charm with Scenario
3 write-an-integration-test-for-a-charm Write an integration test for a charm
3 debug-a-charm Debug a charm
3 get-logs-from-a-kubernetes-charm Get logs from a Kubernetes charm
2 add-a-secret-to-a-charm Use secrets in a charm
2 resources Use charm resources
3 define-a-resource-for-your-charm Define a resource for your charm
3 associate-a-resource-to-your-charm Associate a resource to your charm
3 publishing-resources Publish a resource to Charmhub
3 attach-a-resource-to-a-charm-at-release-time Attach a resource to a charm at release time
3 access-a-resource-from-your-charm Access a resource from your charm
2 manage-libraries Use charm libraries
3 find-and-use-a-charm-library Find and use a charm library
3 create-and-publish-a-charm-library Create and publish a charm library
3 document-your-charm-library Document a charm library
2 implement-integrations-in-a-charm Implement integrations in a charm
2 Observe a charm
3 instrument-your-charm-with-tracing-telemetry Instrument your charm with tracing telemetry
2 publishing Publish a charm
3 create-a-track-for-your-charm Create a track for your charm
3 create-an-icon-for-your-charm Create an icon for a charm
3 add-docs-to-your-charmhub-page Add docs to a charm on Charmhub
3 charm-documentation Document a charm: The README file
2 manage-charmcraft Manage Charmcraft
3 install-charmcraft Install Charmcraft
3 charmcraft-config Configure Charmcraft
3 remote-env-auth Authenticate Charmcraft in remote environments
3 change-step-behavior-in-a-charm Change step behavior when creating a charm
2 Align an old charm with charmcraft and ops
3 turn-a-hooks-based-charm-into-an-ops-charm Turn a hooks-based charm into an ops charm
3 pack-a-reactive-based-charm-with-charmcraft Pack a reactive-based charm with Charmcraft
3 pack-a-hooks-based-charm-with-charmcraft Pack a hooks-based charm with Charmcraft
2 manage-bundles Manage bundles
3 create-a-charm-bundle Create a charm bundle
3 configure-a-charm-bundle Configure a charm bundle
3 compare-a-bundle-to-a-model Compare a bundle to a model
3 pack-a-charm-bundle Pack a charm bundle
3 deploy-a-charm-bundle Deploy a charm bundle
3 publish-a-charm-bundle-to-charmhub Publish a charm bundle to Charmhub
1 reference Reference
2 action Action
2 charm-bundles Bundle
3 kubernetes-vs-non-kubernetes-bundles Kubernetes vs. non-Kubernetes bundles
2 channel Channel
2 charmed-operators Charm(ed operator)
3 list-of-files-in-the-charm-project List of files in the charm project
3 the-juju-execution-flow-for-a-charm The Juju execution flow for a charm
3 charm-taxonomy Charm taxonomy
3 charm-maturity Charm maturity
3 styleguide Charm development best practices
2 charmcraft Charmcraft
3 charmcraft-cli-commands List of commands
3 charmcraft-deprecations Charmcraft deprecation notices
2 charmhub Charmhub
2 configuration Configuration
2 developer-tools Developer tools
3 charmcraft-analyzers-and-linters Charmcraft analyzers and linters
3 tools-for-debugging Tools for debugging
2 event Event
3 list-of-events List of events
3 custom-event Custom event
3 a-charms-life A charm’s life
2 hook Hook
2 hook-tool Hook tool
3 charm-environment-variables Charm environment variables
3 leadership-hook-tools Leadership hook tools
2 integration Integration
3 the-lifecycle-of-charm-integrations The lifecycle of charm integrations
2 library Library
3 library-index Popular charm library index
2 ops Ops
3 constructs Framework constructs
3 framework Framework
3 leadership Leader
3 ops-model Model
3 pebble Pebble
2 promotion Promotion
2 publication Publication
3 reasons-to-publish-your-charm-on-charmhub Reasons to publish your charm on Charmhub
2 about-resources Resource
2 revision Revision
2 scenario Scenario
3 scenario-context Context
3 scenario-event Event
3 scenario-state State
2 secret Secret
2 State
3 stored-state-uses-limitations StoredState: Uses, Limitations
2 status Status
2 storage Storage
2 testing Testing
3 integration-testing-cookbook Testing: Integration testing cookbook
2 yaml-anchors-and-aliases YAML anchors and aliases
1 explanation Explanation
2 history Charming history
2 charmed-operators-vs-kubernetes-operators Charmed operators vs. Kubernetes operators
2 deferring-events-details-and-dilemmas Deferring events: Details and dilemmas
2 talking-to-a-workload-control-flow-from-a-to-z Talking to a workload: control flow from A to Z
roadmap Roadmap
Level 4+ items (currently not supported)
configure-a-charm-bundle Configure a charm bundle
set-charm-channels-within-a-bundle Set charm channels within a bundle
set-charm-constraints-within-a-bundle Set charm constraints within a bundle
set-charm-options-within-a-bundle Set charm options within a bundle
integrate-a-local-charm-into-a-bundle Integrate a local charm into a bundle
add-an-overlay-bundle Configure with an overlay bundle
append-an-overlay-bundle-to-a-base-bundle Append an overlay bundle to a base
resolve-a-relative-path-inside-a-bundle Resolve a relative path inside a bundle
remove-an-application-from-a-bundle Remove an application from a bundle
replace-machines-in-a-bundle Replace machines in a bundle
modify-relations-inside-a-bundle Modify relations inside a bundle
add-machine-specifications-to-a-bundle Add machine specifications to a bundle
bind-endpoints-within-a-bundle Bind endpoints within a bundle
specify-application-expose-parameters-within-a-bundle Specify application expose parameters within a bundle
use-charm-resources-in-a-bundle Use charm resources in a bundle
recycle-machines-in-a-bundle Recycle machines in a bundle
add-a-placement-directive-to-a-bundle Add placement directives to a bundle
add-storage-directives-to-a-bundle Add storage directives to a bundle
set-up-subordinate-charms-inside-a-bundle Set up subordinate charms inside a bundle
events Lifecycle events
collect-metrics-event collect-metrics (deprecated)
config-changed-event config-changed
install-event install
leader-elected-event leader-elected
leader-settings-changed-event leader-settings-changed
post-series-upgrade-event post-series-upgrade
pre-series-upgrade-event pre-series-upgrade
remove-event remove
start-event start
stop-event stop
update-status-event update-status
upgrade-charm-event upgrade-charm
secret-events Secret events
event-secret-changed secret-changed
event-secret-expired secret-expired
event-secret-remove secret-remove
event-secret-rotate secret-rotate
relation-events Relation events
relation-name-relation-broken-event <relation name>-relation-broken
relation-name-relation-changed-event <relation name>-relation-changed
relation-name-relation-created-event <relation name>-relation-created
relation-name-relation-departed-event <relation name>-relation-departed
relation-name-relation-joined-event <relation name>-relation-joined
storage-events Storage events
storage-name-storage-attached-event <storage name>-storage-attached
storage-name-storage-detaching-event <storage name>-storage-detaching
Other events
action-name-action-event <action name>-action
container-name-pebble-ready-event <container name>-pebble-ready
Ops events
events-collect-app-status-and-collect-unit-status Events ‘collect-app-status’ and ‘collect-unit-status’
Charmcraft CLI commands
charmcraft-analyze analyze
charmcraft-clean clean
charmcraft-close close
charmcraft-create-lib create-lib
charmcraft-fetch-lib fetch-lib
charmcraft-init init
charmcraft-list-lib list-lib
charmcraft-login login
charmcraft-logout logout
charmcraft-names names
charmcraft-pack pack
charmcraft-publish-lib publish-lib
charmcraft-register register
charmcraft-register-bundle register-bundle
charmcraft-release release
charmcraft-resource-revisions resource-revisions
charmcraft-resources resources
charmcraft-revisions revisions
charmcraft-status status
charmcraft-upload-resource upload-resource
charmcraft-upload upload
charmcraft-version version
charmcraft-whoami whoami
Files in the charm project
license LICENSE
actions-yaml actions.yaml
charmcraft-yaml charmcraft.yaml
config-yaml config.yaml
dispatch ‘dispatch’
icon-svg icon.svg
lxd-profile-yaml lxd-profile.yaml
manifest-yaml manifest.yaml
metadata-yaml metadata.yaml
requirements-dev-txt requirements-dev.txt
requirements-txt requirements.txt
run-tests run_tests
src-charm-py src/
tests–init–py tests/
tests-test-charm-py tests/
version version
Charm maturity
charm-maturity-stage-1 Charm maturity stage 1
charm-maturity-stage-2 Charm maturity stage 2
naming Charm naming guidelines
Developer tools >> Tools for debugging
jhack jhack
jhack-tail jhack tail
jhack-show-relation jhack show-relation
ops-classes Ops classes
api-reference API reference
Unit testing
Integration testing
create-an-ubuntu-virtual-machine-with-multipass     Create an Ubuntu virtual machine with Multipass
hello-world Hello, world
setup Set-up
libraries Libraries


Mapping table
Location Path
/docs/sdk/charm-types /docs/sdk/charm-types-by-destination-type
/docs/sdk/setting-up-charmcraft /docs/sdk/install-charmcraft
/docs/sdk/bundles /docs/sdk/publish-a-charm-bundle-to-charmhub
/docs/sdk/bundle-reference /docs/sdk/manage-bundles
/docs/sdk/charmcraft-libraries /docs/sdk/manage-libraries
/docs/sdk/event-hook /docs/sdk/event
/docs/sdk/setup /docs/sdk/tutorials
/docs/sdk/ /docs/sdk
/docs/sdk/charm-types-by-deployment-type /docs/sdk/charm-types
/docs/sdk/charm-types-by-development-type /docs/sdk/charm-types
/docs/sdk/charm-pre-publication-checklist /docs/sdk/charm-publication-checklist
/docs/sdk/initialise-your-charm /docs/sdk/set-up-a-charm-project
/docs/sdk/metadata-reference /docs/sdk/metadata-yaml
/docs/sdk/charm-anatomy /docs/sdk/list-of-files-in-the-charm-project
/docs/sdk/relations /docs/sdk/integration
/docs/sdk/the-lifecycle-of-charm-relations /docs/sdk/the-lifecycle-of-charm-integrations
/docs/sdk/assumes /docs/sdk/metadata-yaml
/docs/sdk/debugging /docs/sdk/debug-a-charm
/docs/sdk/build-and-deploy-minimal-kubernetes-charm /docs/sdk/from-zero-to-hero-write-your-first-kubernetes-charm
/docs/sdk/the-location-of-a-charm-library-inside-a-charm /docs/sdk/library
/docs/sdk/charm-libraries /docs/sdk/library
/docs/sdk/manage-charms /docs/sdk/how-to
/docs/sdk/build-your-charm /docs/sdk/pack-a-charm
/docs/sdk/deploy-your-charm /docs/sdk/deploy-a-charm
/docs/sdk/testing /docs/sdk/write-a-unit-test-for-a-charm
/docs/sdk/write-an-integration-test-for-a-charm /docs/sdk/write-an-integration-test-for-a-charm
/docs/sdk/pack-your-reactive-based-charm-with-charmcraft /docs/sdk/pack-a-reactive-based-charm-with-charmcraft
/docs/sdk/pack-your-hooks-based-charm-with-charmcraft /docs/sdk/pack-a-hooks-based-charm-with-charmcraft
/docs/sdk/understand-your-application /docs/sdk/study-your-application
/docs/sdk/charm-types /docs/sdk/charm-taxonomy
/docs/sdk/charm-publication-checklist /docs/sdk/charm-maturity-stage-1
/docs/sdk/charm-evaluation-checklist /docs/sdk/charm-maturity-stage-2
/docs/sdk/build-and-deploy-minimal-machine-charm /docs/sdk/write-your-first-machine-charm

There’s a few bugs in this document:

Under the “Kubernetes Charm” header
When a model is created on Kubernetes, a corresponding Kubernetes namespace is created.

This should read “When a model is created in juju, a corresponding…”

1 Like

Thanks, will fix now.

Although the navigation menu here correctly links “Github” to, when rendered it is linked to, which is a 404.

Hmm that’s annoying, I wonder if that’s changed recently :confused:

@toto do you know how to solve that? Trying to link to an external link the nav?

@jkfran Can you please take a look here?

I opened a bug on it a few days back, I believe it is being worked on -

We had a bug in the previous version of our documentation parser with external links. It should be fine now :slight_smile:

1 Like

Hi, here are sum suggestions/fixes/imporvements on the doc.

Hi Kos - top reviewing today!

Have made some adjustments here. I’ve left the charmed operators link pointing at the docs homepage as it has a brief definition and link off to other places with more context. Will review when I find a better end destination!

I made some additional clarifying edits about what a unit is compared to an application as a corollary to the “scale to n replicas” example.