Publishing Resources

A charm’s resources can be inspected using the charmcraft tool. The following examples will work on the assumption of the following resource definition:

# ...
resources:
  someresource:
    type: file
    filename: superdb.bin
    description: the DB with needed info
# ...

Once the resource has been defined, you can build the charm as normal, then upload it to Charmhub:

# Build the charm
$ charmcraft pack
Created 'my-super-charm.charm'.

# Upload the charm to Charmhub
$ charmcraft upload my-super-charm.charm
Revision 13 of 'my-super-charm' created

# Query Charmhub about the charm's resources
$ charmcraft resources my-super-charm
Name          Type    Revision    Optional
someresource  file    13          True

Now we’ve confirmed that the resource is associated with the charm, we can upload the resource to Charmhub.

Uploading file resources

# Upload the resource
$ charmcraft upload-resource my-super-charm someresource --filepath=/tmp/superdb.bin
Revision 1 created of resource 'someresource' for charm 'my-super-charm'

# Update the resource to a new revision
$ charmcraft upload-resource my-super-charm someresource --filepath=/tmp/superdb.bin
Revision 2 created of resource 'someresource' for charm 'my-super-charm'

# Verify the revisions of the charm resource
$ charmcraft resource-revisions my-super-charm someresource
Revision    Created at    Size
2           2021-03-05  192.3K
1           2021-03-05  204.9K

Uploading oci-image resources

Uploading oci-image resources is similar to uploading file resources, but with a few different parameters to the command.

For example, if an oci-image is defined in metadata.yaml like so:

# ...

resources:
  redis-image:
    type: oci-image
    description: OCI image for Redis
# ...

It can be uploaded like so:

# charmcraft upload-resource --image <image digest> <charm name> <resource name>

$ charmcraft upload-resource my-super-charm redis-image --image=sha256:64aa8983ec5cea7bc143af18829836914fa405184d56dcbdfd9df672ade85249
Revision 1 created of resource 'redis-image' for charm 'my-super-charm'

The option --image must indicate an OCI image’s digest, being it in the short or long form (e.g.: 70aa8983ec5c or sha256:64aa8983ec5cea7bc143af18829836914fa405184d56dcbdfd9df672ade85249).

Charmcraft will first check if that specific image is available in Canonical’s Registry, and just use it if that’s the case. If not, it will try to get it from the developer’s local OCI repository (needs dockerd to be installed and running), push it to the Canonical’s Registry, and then use it.

When using the “short form” of the digest, the image needs to be present locally so its proper ID (the “long form”) can be retrieved.

The following is an example of charmcraft using an image already present in Canonical’s Registry:

$ charmcraft upload-resource my-super-charm redis-image --image=sha256:c8f0dbc0d5a5e3aef7281a4d3941e97f204390b2cba9de6c117341361cbe84e4

Using the OCI image from Canonical's registry

Revision 7 created of resource 'redis-image' for charm 'my-super-charm'

The following is the case of charmcraft needing to push the image first:

$ charmcraft upload-resource my-super-charm redis-image --image=sha256:70aa8983ec5cea7bc143af188b4bdc424fa405184d56dcbdfd9df672ade85249

Remote image not found, uploading from local registry

Image uploaded, new remote digest: sha256:29b027d656acae6e50693a2ec063d40c7de59a2f7b4c0d62c765d2f1cbde616c

Revision 5 created of resource 'redis-image' for charm 'my-super-charm'

One detail to take into consideration: when charmcraft pushes the local image to Canonical’s registry, the remote manifest ends up slightly different to the local one. This is deterministic, so future operations will continue to use the same manifest, but it does take some work each time to compute the target manifest.

Attach a resource to a release

Any uploaded revision of your charm’s resources can be associated with the charm at release time. This way, you can decide which revision of the resource will work with each revision of your charm.

$ charmcraft release my-super-charm --revision=13 --channel=stable --resource=someresource:2
Revision 13 of charm 'my-super-charm' released to stable (attaching resources: 'someresource' r2)

We can inspect the charm, and any associated resources at any time with charmcraft status:

$ charmcraft status my-super-charm
$ charmcraft status my-super-charm
Track       Channel    Version    Revision    Resources
latest      stable     7.4a       13          someresource (r1)
            candidate  ↑          ↑           ↑
            beta       7.4a       10
            edge       7.4a       14          someresource (r3)

Last updated 3 months ago.