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
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 - machines
3 interact-with-pebble Run workloads with a charm - Kubernetes
3 logging Configure logging in a charm
2 Test and debug a charm
3 pack-a-charm Pack a charm
3 deploy-a-charm Deploy a charm
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 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 write-a-scenario-test-for-a-charm-library Write a scenario test for a charm library
3 document-your-charm-library Document a charm library
2 implement-integrations-in-a-charm Add an integration to a charm
3 register-an-interface Register an interface
3 write-interface-tests Write interface tests
2 Observe a charm
3 instrument-your-charm-with-tracing-telemetry Instrument a 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 include-extra-files-in-a-charm Include extra files in 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
1 reference Reference
2 action Action
2 bundle Bundle
3 bundle.yaml File <bundle>.yaml
2 channel Channel
2 charm Charm
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 Charmcraft CLI commands
3 charmcraft-deprecations Charmcraft deprecation notices
2 charmhub Charmhub
2 charm-relation-interfaces charm-relation-interfaces
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 charm-lifecycle Charm lifecycle
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 ops-pebble Pebble (Ops)
2 pebble Pebble
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 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 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 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
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-remote-build remote-build
charmcraft-resource-revisions resource-revisions
charmcraft-resources resources
charmcraft-revisions revisions
charmcraft-set-resource-architectures set-resource-architectures
charmcraft-status status
charmcraft-upload-resource upload-resource
charmcraft-upload upload
charmcraft-version version
charmcraft-whoami whoami
Files in the charm project
contributing-md File ‘CONTRIBUTING.md’
license File ‘LICENSE’
readme-md File ‘README.md’
actions-yaml File ‘actions.yaml’
charmcraft-yaml File ‘charmcraft.yaml’
config-yaml config.yaml
dispatch File ‘dispatch’
icon-svg File ‘icon.svg’
lxd-profile-yaml File ‘lxd-profile.yaml’
manifest-yaml File ‘manifest.yaml’
metadata-yaml File ‘metadata.yaml’
pyproject-toml File ‘pyproject.toml’
requirements-dev-txt File ‘requirements-dev.txt’
requirements-txt File ‘requirements.txt’
src-charm-py File ‘src/charm.py’
tests-unit-test-charm-py File ‘tests/unit/test_charm.py’
tests-integration-test-charm-py File ‘tests/integration/test_charm.py’
tox-ini File 'tox.ini
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
/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

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