How to create and publish a bundle

Bundles are collections of charms that link applications together. They enable administrators to deploy large, complex systems from one file, where all of the configuration and relations are pre-defined. Where a charm represents a single application or service, a bundle represents an entire Juju model. More information about deploying and operating bundles can be found in the bundle reference docs. This section will focus on the creation and publishing of bundles.

A bundle is fundamentally just a YAML file that contains details of the charms, relationships and configuration to deploy. However, it is recommended that bundle developers also distribute some files alongside the bundle YAML file, such as a README, LICENSE and other associated information that may be useful to an administrator deploying the bundle.

These docs will not cover the full scope of what is possible with a bundle, but there is a spec for a bundle YAML file available in the reference docs.

You can create a bundle from a deployed Juju model easily by running juju export-bundle --filename bundle.yaml.


Register your bundle’s name

Much like when publishing a charm, before you can publish a bundle, you must register a name for it. This is done using the charmcraft register-bundle command:

$ charmcraft register-bundle super-bundle
You are now the publisher of bundle 'super-bundle' in Charmhub.

Note that if you’re not already authenticated with Charmhub, you may need to login first with charmcraft login.

Pack your bundle

We refer to the preparation of a bundle for upload to Charmhub as “packing”. In this simple example, we pack just a README file, and the bundle’s YAML file. Before we can issue the charmcraft pack command though, we must first create a charmcraft.yaml file. We can keep this simple for now, and just specify a type (there is more info on this file in the essentials section):

# Note the following command will clobber any existing charmcraft.yaml!
$ echo "type: bundle" > charmcraft.yaml

We’re now ready to pack our bundle, before continuing confirm that all the pieces are in place:

$ ls -l
total 12
-rw-rw-r-- 1 jdoe jdoe   13 mar  2 11:08 charmcraft.yaml
-rw-rw-r-- 1 jdoe jdoe 3221 feb 24 09:42
-rw------- 1 jdoe jdoe  247 feb 24 09:42 bundle.yaml
$ cat charmcraft.yaml
type: bundle

And now we can pack the bundle:

$ charmcraft pack
Created ''.

Publish your bundle

As with charms, the publishing process contains two steps: upload and release. To upload a packed bundle, use the charmcraft upload command:

$ charmcraft upload
Revision 1 of 'super-bundle' created

Each time you upload a new packed bundle, Charmhub will automatically provide different revisions. Charmhub will reject the upload if you try to upload a blob that has already been uploaded. You can verify which revisions are in Charmhub for a given bundle like so:

$ charmcraft revisions super-bundle
Revision    Version    Created at    Status
4           4          2021-04-28    released
3           3          2021-04-27    approved
2           2          2021-04-27    approved
1           1          2021-04-27    approved

Uploading a bundle to Charmhub does not automatically make it available to the public, to do this, the bundle must be released into a channel:

$ charmcraft release super-bundle --revision=1 --channel=beta
Revision 1 of charm 'super-bundle' released to beta

As with revisions, you can inspect the status of releases and channels using charmcraft:

$ charmcraft status super-bundle
Track    Channel    Version    Revision
latest   stable     -          -
         candidate  -          -
         beta       1          1
         edge       ↑          ↑

Last updated 8 days ago.