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.
- Learn about the Roadmap & Releases
- Read our Code of Conduct
- Join our Matrix chat
- Join the Discourse forum to talk about Juju, charms, docs, or to meet the community
- Report a bug on GitHub (for code) or GitHub (for docs)
- Contribute to the documentation on Discourse
- Contribute to the code on Github
- Visit the Juju careers page
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 |
| 2 | write-your-first-kubernetes-charm-for-a-go-app | Write your first Kubernetes charm for a Go 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-extension-go-framework | Charmcraft extension âgo-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 |
| 3 | library-index | Popular charm library index |
| 2 | jhack | jhack |
| 3 | jhack-tail | jhack tail |
| 3 | jhack-show-relation | jhack show-relation |
| 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 |
