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 |