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 the Mattermost chat to talk about Juju, charms, docs, or to meet the community
- Join the Discourse forum to talk about Juju, charms, docs, or to meet the community
- Report a bug on Github
- 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 |
| 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 | ||
| contributing-md | CONTRIBUTING.md | |
| license | LICENSE | |
| readme-md | README.md | |
| 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/charm.py | |
| testsâinitâpy | tests/init.py | |
| tests-test-charm-py | tests/test_charm.py | |
| 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 | ||
| 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 |
