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

Tutorials
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
Explanation
Concepts - discussion and clarification of key topics
Reference
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.

Navigation

Navigation
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
2 write-your-first-kubernetes-charm-for-a-flask-app Write your first Kubernetes charm for a Flask app
2 write-your-first-kubernetes-charm-for-a-django-app Write your first Kubernetes charm for a Django app
2 write-your-first-kubernetes-charm-for-a-fastapi-app Write your first Kubernetes charm for a FastAPI app
1 how-to How-to guides
2 build-a-12-factor-app-charm Build a 12-Factor app charm
2 build-and-own-a-charm-or-a-bundle Build and own a charm or a bundle
2 manage-bundles Manage bundles
2 Set things up
3 dev-setup Set up your development environment
3 set-up-a-charm-project Set up a charm project
3 manage-extensions Manage extensions
3 manage-charmcraft Manage Charmcraft
4 install-charmcraft Install Charmcraft
4 charmcraft-config Configure Charmcraft
4 remote-env-auth Authenticate Charmcraft in remote environments
4 change-step-behavior-in-a-charm Change step behavior when creating a charm
3 include-extra-files-in-a-charm Include extra files in a charm
2 Develop
3 logging Configure logging in a charm
3 resources Use charm resources
3 workloads Run workloads with a charm - machines
3 interact-with-pebble Run workloads with a charm - Kubernetes
3 set-the-charm-version Set the charm version
3 set-the-workload-version Set the workload version
3 actions Add an action to a charm
3 config Add a config option to a charm
3 use-storage-in-a-charm Use storage in a charm
3 add-a-secret-to-a-charm Use secrets in a charm
3 manage-libraries Use charm libraries
4 find-and-use-a-charm-library Find and use a charm library
4 create-and-publish-a-charm-library Create and publish a charm library
4 write-a-scenario-test-for-a-charm-library Write a scenario test for a charm library
4 document-your-charm-library Document a charm library
3 handle-leadership Handle leadership
3 implement-integrations-in-a-charm Add an integration to a charm
3 instrument-your-charm-with-tracing-telemetry Observe a charm
3 Manage interfaces
4 register-an-interface Register an interface
4 write-interface-tests Write interface tests
2 Test and debug
3 get-started-with-charm-testing Get started with charm testing
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 scenario test for a charm
3 write-integration-tests-for-a-charm Write integration tests for a charm
3 pack-a-charm Pack a charm
3 deploy-a-charm Deploy a charm
3 debug-a-charm Debug a charm
3 get-logs-from-a-kubernetes-charm Get logs from a Kubernetes charm
2 Document
3 add-docs-to-your-charmhub-page Add docs to a charm on Charmhub
3 charm-documentation Document a charm: The README file
2 Market
3 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
2 Miscellaneous
3 Align an old charm with charmcraft and ops
4 turn-a-hooks-based-charm-into-an-ops-charm Turn a hooks-based charm into an ops charm
4 pack-a-reactive-based-charm-with-charmcraft Pack a reactive-based charm with Charmcraft
4 pack-a-hooks-based-charm-with-charmcraft Pack a hooks-based charm with Charmcraft
1 reference Reference
2 bundle Bundle
3 bundle.yaml File <bundle>.yaml
2 charm Charm
3 list-of-files-in-the-charm-project List of files in the charm project
4 contributing-md File ‘CONTRIBUTING.md’
4 license File ‘LICENSE’
4 readme-md File ‘README.md’
4 actions-yaml File ‘actions.yaml’
4 charmcraft-yaml File ‘charmcraft.yaml’
4 config-yaml config.yaml
4 dispatch File ‘dispatch’
4 icon-svg File ‘icon.svg’
4 lxd-profile-yaml File ‘lxd-profile.yaml’
4 manifest-yaml File ‘manifest.yaml’
4 metadata-yaml File ‘metadata.yaml’
4 pyproject-toml File ‘pyproject.toml’
4 requirements-dev-txt File ‘requirements-dev.txt’
4 requirements-txt File ‘requirements.txt’
4 src-charm-py File ‘src/charm.py’
4 tests-unit-test-charm-py File ‘tests/unit/test_charm.py’
4 tests-integration-test-charm-py File ‘tests/integration/test_charm.py’
4 tox-ini File 'tox.ini
3 the-juju-execution-flow-for-a-charm The Juju execution flow for a charm
3 charm-taxonomy Charm taxonomy
4 12-factor-app-charm 12-Factor app charm
3 charm-maturity Charm maturity
4 charm-maturity-stage-1 Charm maturity stage 1
4 charm-maturity-stage-2 Charm maturity stage 2
3 naming Charm naming guidelines
3 styleguide Charm development best practices
2 charmcraft Charmcraft
3 charmcraft-cli-commands List of Charmcraft CLI commands
4 charmcraft-analyse charmcraft analyse
4 charmcraft-build charmcraft build
4 charmcraft-clean charmcraft clean
4 charmcraft-close charmcraft close
4 charmcraft-create-lib charmcraft create-lib
4 charmcraft-expand-extensions charmcraft expand-extensions
4 charmcraft-fetch-lib charmcraft fetch-lib
4 charmcraft-fetch-libs charmcraft fetch-libs
4 charmcraft-init charmcraft init
4 charmcraft-list-extensions charmcraft list-extensions
4 charmcraft-list-lib charmcraft list-lib
4 charmcraft-login charmcraft login
4 charmcraft-logout charmcraft logout
4 charmcraft-names charmcraft names
4 charmcraft-pack charmcraft pack
4 charmcraft-prime charmcraft prime
4 charmcraft-promote-bundle charmcraft promote-bundle
4 charmcraft-pull charmcraft pull
4 charmcraft-publish-lib charmcraft publish-lib
4 charmcraft-register charmcraft register
4 charmcraft-register-bundle charmcraft register-bundle
4 charmcraft-release charmcraft release
4 charmcraft-remote-build charmcraft remote-build
4 charmcraft-resources charmcraft resources
4 charmcraft-resource-revisions charmcraft resource-revisions
4 charmcraft-revisions charmcraft revisions
4 charmcraft-set-resource-architectures charmcraft set-resource-architectures
4 charmcraft-stage charmcraft stage
4 charmcraft-status charmcraft status
4 charmcraft-unregister charmcraft unregister
4 charmcraft-upload charmcraft upload
4 charmcraft-upload-resource charmcraft upload-resource
4 charmcraft-version charmcraft version
4 charmcraft-whoami charmcraft whoami
3 charmcraft-extension-flask-framework Charmcraft extension ‘flask-framework’
3 charmcraft-extension-django-framework Charmcraft extension ‘django-framework’
3 charmcraft-extension-fastapi-framework Charmcraft extension ‘fastapi-framework’
3 charmcraft-deprecations Charmcraft deprecation notices
3 charmcraft-analyzers-and-linters Charmcraft analyzers and linters
2 charmhub Charmhub
2 charm-relation-interfaces charm-relation-interfaces
2 event Event
3 list-of-events List of events
4 events Lifecycle events
4 secret-events Secret events
4 relation-events Relation events
4 storage-events Storage events
3 custom-event Custom event
3 charm-lifecycle Charm lifecycle
2 extension Extension
2 library Library
2 jhack jhack
3 jhack-tail jhack tail
3 jhack-show-relation jhack show-relation
3 library-index Popular charm library index
2 ops Ops
2 pebble Pebble
2 profile Profile
2 promotion Promotion
2 publication Publication
3 reasons-to-publish-your-charm-on-charmhub Reasons to publish your charm on Charmhub
2 pytest-operator pytest-operator
2 revision Revision
2 rockcraft Rockcraft
3 rockcraft-extension-flask-framework Rockcraft extension ‘flask-framework’
3 rockcraft-extension-django-framework Rockcraft extension ‘django-framework’
3 rockcraft-extension-fastapi-framework Rockcraft extension ‘fastapi-framework’
2 scenario Scenario
3 scenario-context Context
3 scenario-event Event
3 scenario-state State
2 status Status
2 storage Storage
2 stored-state-uses-limitations StoredState: Uses, Limitations
2 testing Testing
3 interface-tests Interface tests
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 how-and-when-to-defer-events How and When to Defer Events
2 holistic-vs-delta-charms Holistic vs delta charms
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)
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-custom-notice-event <container name>-pebble-custom-notice
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
Files in the charm project
Charm maturity
Developer tools >> Tools for debugging
Ops
ops-classes Ops classes
api-reference API reference
Publication
Testing
Unit testing
Integration testing
Other
create-an-ubuntu-virtual-machine-with-multipass     Create an Ubuntu virtual machine with Multipass
hello-world Hello, world
setup Set-up
INTEGRATE WITH EXISTING MATERIAL
libraries Libraries

Redirects

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
/docs/sdk/run-tests /docs/sdk/list-of-files-in-the-charm-project
/docs/sdk/tests–init–py /docs/sdk/list-of-files-in-the-charm-project
/docs/sdk/tests-test-charm-py /docs/sdk/tests-unit-test-charm-py
/docs/sdk/version /docs/sdk/list-of-files-in-the-charm-project
/docs/sdk/write-an-integration-test-for-a-charm /docs/sdk/write-integration-tests-for-a-charm
/docs/sdk/integration-testing-cookbook /docs/sdk/write-integration-tests-for-a-charm
/docs/sdk/a-charms-life /docs/sdk/charm-lifecycle
/docs/sdk/charmed-operators /docs/sdk/charm
/docs/sdk/deferring-events-details-and-dilemmas /docs/sdk/how-and-when-to-defer-events
/docs/sdk/create-a-charm-bundle /docs/sdk/manage-bundles
/docs/sdk/configure-a-charm-bundle /docs/sdk/manage-bundles
/docs/sdk/compare-a-bundle-to-a-model /docs/sdk/manage-bundles
/docs/sdk/pack-a-charm-bundle /docs/sdk/manage-bundles
/docs/sdk/deploy-a-charm-bundle /docs/sdk/manage-bundles
/docs/sdk/publish-a-charm-bundle-to-charmhub /docs/sdk/manage-bundles
/docs/sdk/configure-a-charm-bundle /docs/sdk/manage-bundles
/docs/sdk/set-charm-channels-within-a-bundle /docs/sdk/manage-bundles
/docs/sdk/set-charm-constraints-within-a-bundle /docs/sdk/manage-bundles
/docs/sdk/set-charm-options-within-a-bundle /docs/sdk/manage-bundles
/docs/sdk/integrate-a-local-charm-into-a-bundle /docs/sdk/manage-bundles
/docs/sdk/add-an-overlay-bundle /docs/sdk/manage-bundles
/docs/sdk/append-an-overlay-bundle-to-a-base-bundle /docs/sdk/manage-bundles
/docs/sdk/resolve-a-relative-path-inside-a-bundle /docs/sdk/manage-bundles
/docs/sdk/remove-an-application-from-a-bundle /docs/sdk/manage-bundles
/docs/sdk/replace-machines-in-a-bundle /docs/sdk/manage-bundles
/docs/sdk/modify-relations-inside-a-bundle /docs/sdk/manage-bundles
/docs/sdk/add-machine-specifications-to-a-bundle /docs/sdk/manage-bundles
/docs/sdk/bind-endpoints-within-a-bundle /docs/sdk/manage-bundles
/docs/sdk/specify-application-expose-parameters-within-a-bundle /docs/sdk/manage-bundles
/docs/sdk/use-charm-resources-in-a-bundle /docs/sdk/manage-bundles
/docs/sdk/recycle-machines-in-a-bundle /docs/sdk/manage-bundles
/docs/sdk/add-a-placement-directive-to-a-bundle /docs/sdk/manage-bundles
/docs/sdk/add-storage-directives-to-a-bundle /docs/sdk/manage-bundles
/docs/sdk/set-up-subordinate-charms-inside-a-bundle /docs/sdk/manage-bundles
/docs/sdk/charm-bundles /docs/sdk/bundle
/docs/sdk/kubernetes-vs-non-kubernetes-bundles /docs/sdk/bundle.yaml
/docs/sdk/charmcraft-analyze /docs/sdk/charmcraft-analyse
/docs/sdk/action https://juju.is/docs/juju/action
/docs/sdk/channel https://juju.is/docs/juju/channel
/docs/sdk/configuration https://juju.is/docs/juju/configuration
/docs/sdk/hook https://juju.is/docs/juju/hook
/docs/sdk/hook-tool https://juju.is/docs/juju/hook-tool
/docs/sdk/charm-environment-variables https://juju.is/docs/juju/charm-environment-variables
/docs/sdk/leadership-hook-tools https://juju.is/docs/juju/hook-tool
/docs/sdk/integration https://juju.is/docs/juju/relation
/docs/sdk/the-lifecycle-of-charm-integrations https://juju.is/docs/juju/relation
/docs/sdk/about-resources https://juju.is/docs/juju/charm-resource
/docs/sdk/secret https://juju.is/docs/juju/secret
/docs/sdk/define-a-resource-for-your-charm /docs/sdk/resources
/docs/sdk/associate-a-resource-to-your-charm /docs/sdk/resources
/docs/sdk/publishing-resources /docs/sdk/resources
/docs/sdk/attach-a-resource-to-a-charm-at-release-time /docs/sdk/resources
/docs/sdk/access-a-resource-from-your-charm /docs/sdk/resources
/docs/sdk/write-your-first-kubernetes-charm-using-the-paas-app-charmer /docs/sdk/write-your-first-kubernetes-charm-for-a-flask-app
/docs/sdk/constructs /docs/sdk/ops
/docs/sdk/framework /docs/sdk/ops
/docs/sdk/leadership /docs/sdk/ops
/docs/sdk/ops-model /docs/sdk/ops
/docs/sdk/ops-pebble /docs/sdk/ops
/docs/sdk/developer-tools /docs/sdk/jhack
/docs/sdk/tools-for-debugging /docs/sdk/jhack
/docs/sdk/paas-app-charmer /docs/sdk/12-factor-app-charm
/docs/sdk/paas-charm /docs/sdk/12-factor-app-charm
/docs/sdk/build-a-paas-charm /docs/sdk/build-a-12-factor-app-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 https://github.com/canonical/operator, when rendered it is linked to https://juju.is/canonical/operator, 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 - https://github.com/canonical-web-and-design/juju.is/issues/258

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.

  • for the “operator pattern” we may want to link to
    https://kubernetes.io/docs/concepts/extend-kubernetes/operator/

  • “Charmed Operators” points to Juju | Welcome to the Juju documentation! is this correct?

  • “Consider the deployment of a large web application of n units.” if you are new to Juju and you start with the overview of Juju | The Charmed Operator Framework you do not know what a unit is the context of juju. Maybe we could link to a page saying what a unit is.

  • “Subordinate charms are written in the same way as other charms, with the addition of an extra flag in the charm’s metadata.” Maybe we could provide a link on how subordinate charms are written. Which is this extra flag?
    The link to metadata seems off maybe we should point to Charm Metadata v2

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.

2 Likes