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.
