How to associate a resource to your charm

See also:

You have published your charm. This document shows you how you can now associate a resource name to your charm.

By default, a charm has no attached resources. You can verify this by running charmcraft resources:

jdoe@machine:~/blogsystem$ charmcraft resources my-super-charm
No resources associated to my-super-charm.

To attach a resource to a charm, open your charm’s metadata.yaml file and edit the resources block:

jdoe@machine:~/blogsystem$ cat metadata.yaml 
name: my-super-charm
summary: My super charm.
description: My super duper charm, used for testing.
series:
    - bionic
resources:
    someresource:
        type: file
        filename: superdb.bin
        description: the DB with needed info

You may include as many resources as we want.

When you’re done, rebuild and reupload your charm to Charmhub with the new metadata:

jdoe@machine:~/blogsystem$ charmcraft build
Created 'my-super-charm.charm'.
jdoe@machine:~/blogsystem$ charmcraft upload my-super-charm.charm
Revision 13 of 'my-super-charm' created

Finally, inspect the results:

jdoe@machine:~/blogsystem$ charmcraft resources my-super-charm
Name          Type    Revision    Optional
someresource  file    13          True

As you can see, the resource is associated to revision 13 of the charm. This association to a specific revision of a charm is important is important to keep in mind, as it will matter if you want to attach a resource to a charm at release time—the attachment will work only if the resource has been included in the chosen charm revision’s metadata.

The resource shown someresource is marked as Optional True however there is no information on how to set this to false. Is this possible ? If it is set to false will charmcraft throw an error when an attempt is made to publish a new charm revision without specifying mandatory resources ?

Hi @bthomas! The entry in the metadata reference for resources doesn’t mention being able to set or unset the “optional” property. @jameinel @roadmr : do you know if that “Optional” field is an artifact of the past, or a harbinger of things to come?

If you wanted to upload a version of the charm without the resource, you should be able to just omit the resource line from the metadata.yaml. Charmcraft will build the charm without complaining, and I don’t think that the store will check for resources that aren’t in the new revision’s metadata when processing the upload.

1 Like

Thanks @pengale. Just to provide a bit more context my question was motivated by the the use case – “I would like to prevent accidental release of my charm on charmhub without an essential resource (revision) being (explicitly) specified.”

So (Optional) on that list is about whether the field must be present in the metdata.yaml file for it to be valid. The general model for Juju (currently) is that resources always must be present. We very much wanted to avoid the situation where you “juju deploy foo” and it just breaks immediately because you didn’t provide a key piece.

I’d like to dig into this a little bit further. You should always have a resource (though it may be the previous version of the resource that you released, and the big question is what happens for the very first releases). I don’t know the publication workflow at this point, but you shouldn’t be able to charmcraft release without having all of your resources defined. (If you can, I would consider it a bug in the publication workflow.)

Now that experience means you have to “upload a 0 byte file for optional resources” which is not great, and we could look at changing this flow.

@jameinel Thank you for you explanation. I did make the mistake of recently releasing an edge version of the Prometheus k8s charm without specifying the promql-transform-amd64 resource. Hence I infer this is possible. I am not sure I understand what is meant by “field must be present in the metadata.yaml”. The resource is defined in the metadata.yaml so I fail to understand how else charmcraft would be aware of a resource that it needs to check the presence of in the metadata.yaml.