Juju SDK Documentation

The Charmed Operator Software Development Kit (SDK) is a toolkit for packaging applications—in a special format called Charmed Operators (‘charms’)—for the cloud. It is a component of the Charmed Operator Framework Juju and it consists of the command line tool Charmcraft (charmcraft) and the Python charmed operator framework Ops (ops).

The SDK provides commands and templates to package both Kubernetes and non-Kubernetes applications in one standard format with the extension “.charm”. These can be subsequently deployed using Juju’s Charmed Operator Lifecycle Manager (OLM).

As such, the SDK makes it quick and easy to make applications of any type ready for the cloud.

For DevOps, Juju’s SDK simplifies workflow; for CIOs, it helps reimagine solutions, as it lowers the barrier for including new applications.

For a collection of existing charms, see Charmhub. To deploy and manage an existing or new charm, see the Charmed Operator Lifecycle Manager (OLM).

In this documentation

Get started - a hands-on introduction to the Juju SDK for new users
How-to guides
Step-by-step guides covering key operations and common tasks
Concepts - discussion and clarification of key topics
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.


Level Path Navlink
1 Juju SDK documentation
1 tutorials Tutorials
2 build-and-deploy-minimal-machine-charm Get started with the Juju SDK - machines
2 from-zero-to-hero-write-your-first-kubernetes-charm Get started with the Juju SDK - Kubernetes
3 understand-your-application Understand 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
1 how-to How-to guides
2 manage-charmcraft Manage Charmcraft
3 install-charmcraft Install Charmcraft
3 charmcraft-config Configure Charmcraft
3 remote-env-auth Authenticate Charmcraft in remote environments
2 manage-charms Manage charms
3 set-up-a-charm-project Set up a charm project
3 change-step-behavior-in-a-charm Change step behavior when creating a charm
3 build-your-charm Pack a charm
3 pack-your-reactive-based-charm-with-charmcraft Pack a reactive-based charm with Charmcraft
3 pack-your-hooks-based-charm-with-charmcraft Pack a hooks-based charm with Charmcraft
3 workloads Run workloads with your charm
3 logging Configure logging in your charm
3 config Handle charm configuration
3 add-a-secret-to-a-charm Add a secret to a charm
3 debug-a-charm Debug a charm
3 testing Test a charm
3 write-an-integration-test-for-a-charm Write an integration test for a charm
3 deploy-your-charm Deploy your charm
3 charm-documentation Document your charm: The README file
3 publishing Publish your charm to Charmhub
3 add-docs-to-your-charmhub-page Add docs to your charm page on Charmhub
3 create-an-icon-for-your-charm Create an icon for your charm
3 turn-a-hooks-based-charm-into-an-ops-charm Turn a hooks-based charm into an ops charm
3 interact-with-pebble Interact with Pebble
3 actions Handle actions
2 resources Manage 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 Manage 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 your charm library
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 charm-bundles Bundle
3 kubernetes-vs-non-kubernetes-bundles Kubernetes vs. non-Kubernetes bundles
2 channel Channel
2 charmed-operators Charm(ed operator)
3 charm-types Charm types
3 list-of-files-in-the-charm-project List of files in the charm project
2 charmcraft Charmcraft
3 charmcraft-cli-commands List of commands
3 charmcraft-deprecations Charmcraft deprecation notices
2 charmhub Charmhub
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 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 publication Publication
3 reasons-to-publish-your-charm-on-charmhub Reasons to publish your charm on Charmhub
3 charm-publication-checklist Charm publication checklist
3 charm-evaluation-checklist Charm evaluation checklist
2 about-resources Resource
2 State
3 stored-state-uses-limitations StoredState: Uses, Limitations
2 Status
2 storage Storage
2 integration-testing-cookbook Testing: Integration testing cookbook
2 yaml-anchors-and-aliases YAML anchors and aliases
1 explanation Explanation
2 deferring-events-details-and-dilemmas Deferring events: Details and dilemmas
2 history Charming history
2 styleguide Charm development best practices
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
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
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
icon-svg icon.svg
manifest-yaml manifest.yaml
version version
Developer tools >> Tools for debugging
jhack jhack
jhack-tail jhack tail
jhack-show-relation jhack show-relation
ops-classes Ops classes
api-reference API reference
naming Charm naming guidelines
Unit testing
Integration testing
create-an-ubuntu-virtual-machine-with-multipass     Create an Ubuntu virtual machine with Multipass
dev-setup Development setup
hello-world Hello, world
setup Set-up
libraries Libraries


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

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.

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.