Charm's metadata is messy


The metadata about a charm is scaterred accross different places:

  • metadata.yaml: Charm Metadata v2
  • charmcraft.yaml (this “defines” the OS that the charm runs, an important information about the charm)
  • a secret version file that defines the version of the charm code (not the underlying service/wrokload)
  • some fields that can only be filled in Title and Summary again (they are already in the metadata.yaml); and Project Homepage and Contact.
  • and another bit that a Canonical Engineer has to flip manually for a charm be searchable in CharmHub

This is frustrating and confusing.

Is it possible to have CharmHub pulling the metadata from the charm? This means: having Project Homepage and Contact in the metadata.yaml and the Title and Summary from the charm metadata.

The metadata.yaml has fields for tags and categories. This is again confusing: why we need both? where are they used? What are the categories that I can set in my charm so it can appear in CharmHub’s filters? Charmcraft could have a linter to ensure only the “valid” categories.

The information about the license used is not available anywhere (Juju should know about Charm licenses).


These are very valid points @Heitor. Consolidating metadata to a single place/file would simplify and make life alot easier for charmers.

@jameinel can also chime in here. A brief summary from me which hopefully explains things a bit… (I think the doc does need to catch up here; things are in a bit of flux at the moment).

With the charmhub display attributes like tags, categories etc - these are slated to be removed from metadata.yaml. They are a carry over from what was used on the old charm store. metadata.yaml is really supposed to model the requirements and behaviour of the charm; what endpoints does it provide, what storage does it need etc.

The above is orthogonal to the platform (architectures and os/version) on which the charm runs - this information is generated at build time using instructions from the charmcraft.yaml file. Previously charms did not support different binaries for different architectures. Now that this is a thing, the modelling of runtime platform has been separated out from metadata.yaml (which used to just specify os/version) and becomes part of the build process, similar to what is done for snaps.

So we have 3 different types of information, each has a different and independent purpose:

  • display info for the store like title, summary, tags etc (entered via charmhub)
  • charm behaviour / semantics (metadata.yaml)
  • charm build / runtime requirements (charmcraft.yaml)

The fact that there’s a little legacy still in metadata.yaml is being cleaned up (sorry about the confusion there).

I am not sure what you mean by “secret version file”? Before we transitioned to charmcraft, the charm build tool would create the version file to contain the VCS SHA/revision if the build was being done from a VCS checkout. Juju displays this info in status and it allows folks to understand exactly what version of a charm is running. I just check and it looks like this is still an open issue for charmcraft to catch up and implement that behaviour. The file can be created manually if needed in the meantime. It’s just a single line of text which Juju will render in YAML or JSON status.

Hopefully that help clarify things a bit until we can make progress on better documentation.

Thanks for the comments, @wallyworld.

This is frustrating and makes charming more difficult and error prone. Please don’t scatter metadata entries in different places and platforms.

Whenever I see a file named metadata.yaml I expect all metadata to be there, not only a subset of it. This includes: title, summary, license, categories, project homepage, contact, etc. Why can’t the store (charmhub, jaas, or others) be able to read this metadata from the metadata.yaml file? Why do we have to enter some metadata in CharmHub instead of the metadata.yaml file?

On the other hand, if this information is available in the charm, then every possible charm store or CLI application (e.g. juju, unzip, the controller, etc) can display this information. But if this metadata is not available in the charm, how do we use Juju in an enterprise environment with a firewalled internet connection?

Please move further discussion to the metadata reference document’s discourse post Charm Metadata Reference