In Juju, a bundle is a collection of charms which have been carefully combined and configured in order to automate a multi-charm solution.
For example, a bundle may include the wordpress charm, the mysql charm, and the relation between them.
The operations are transparent to Juju and so the deployment can continue to be managed by Juju as if everything was performed manually (what you see in juju status is applications, relations, etc.; that is, not the bundle entity, but its contents).
Bundles can be of two kinds, regular and overlay.
An overlay bundle is a local bundle you pass to juju deploy <charm/bundle> via --overlay <overlay bundle name>.yaml if you want to customise an upstream charm / bundle (usually the latter, also known as a base bundle) for your own needs without modifying the existing charm / bundle directly. For example, you may wish to add extra applications, set custom machine constraints or modify the number of units being deployed. They are especially useful for keeping configuration local, while being able to make use of public bundles. It is also necessary in cases where certain bundle properties (e.g. offers, exposed endpoints) are deployment specific and can only be provided by the bundle’s user.
A regular bundle is any bundle that is not an overlay.
Whether regular or overlay, a bundle is fundamentally just a YAML file that contains all the applications, configurations, relations, etc., that you want your deployment to have.
i learned today about include-file:// and include-base64://but i didn’t exactly know under what circumstances i can use them in the bundle.yaml.
Are they only allowed as a values of config key or can they be anywhere? Where’s the reference manual for how these magic-key values are supposed to be used?
this blog did give me some hints to some of my questions
I don’t know about a reference manual but these two methods can be used to include application configuration options (‘config’) or to contain binary data for a specific application configuration option (charm-specific) like ‘cert’. There is a simple example on the Charm bundles page.
@tmihoc I know that bundles are being deprecated, but I think it could be useful to add a section (I could even do this) to this doc about overlays with some simple examples. I browsed some Canonical repos and noticed that ~90% of the overlay YAML files just make use of the applications and relations keys. I would follow a similar format to the Juju config-yaml doc.
What are your thoughts? I am also happy to leave it as is.
Hi @crucible , and thanks for raising this! We do already have something similar to File config.yaml, namely, File <bundle>.yaml, but it’s in the SDK docs; I’ve added a “See more” link to it at the bottom of the doc. (That file, at the very top, also has a link to examples from test files. The schema part itself could use a lot of work but, since bundles are being phased out, improving that content isn’t a priority.)
As a general note: Our current documentation architecture, which is split into Juju and Charm SDK, makes it hard sometimes to document concepts relevant to both. So far we’ve handled this by documenting shared concepts under Juju (they usually come from the Juju API anyway) and having the charm SDK docs presuppose Juju docs and linking to Juju docs via “See first” links. However, the approach is clunky (what happened here is an example of that) and potentially misleading: It suggests that the relation between what a charm+Juju user needs to know and what a charm author needs to know is subset-superset, whereas in reality it’s partial overlap. I’m thinking of combining the Juju and the Charm SDK docs and having the how-to guides continue to reflect the charm author vs. user split but the reference combined, with all the shared entries being directly linked to from both, wherever relevant. Happy to chat further.
