How to configure Charmcraft

See also:

You have installed Charmcraft. This document shows you how you can configure it.

Since Charmcraft v0.8.0 , this configuration file is mandatory for packing bundles, though optional for the rest of the commands. In a future release it will become mandatory for all project-handling commands, though remain optional for some store-related commands.

Contents:

Find the configuration file

The charmcraft tool configuration is specified in a charmcraft.yaml file located in the project’s root directory.

By default, Charmcraft will try to find that file in the current directory, but in case of needing to run charmcraft outside the project’s directory, it can be specified using the global option --project-dir.

Get acquainted with its contents

The following are the fields available in the configuration file. Everything is optional unless stated otherwise.

# (Required) The type of entity for which the present config exists
type: charm | bundle

# (Optional) Used for configuring charmcraft's interaction with store servers
charmhub:

    # (Optional) Base URL for the Charmhub API - default used if not set. 
    # Used mostly in the context of "private" charm stores.
    api-url: <api url>

    # (Optional) Base URL to push binaries to Charmhub - default used if not set.
    # Used mostly in the context of "private" charm stores.
    storage-url: <storage url>

# (Optional) List of files/directories to include in the built file. 
parts:

    # (Optional) Specify parts for a charm if `type`is set to `charm`.
    charm:

        # (Optional, new in charmcraft 1.2) The charm entry point, relative to the project
        # directory. If not defined, `src/charm.py` will be used.
        charm-entrypoint: /path/to/entrypoint

        # (Optional, new in charmcraft 1.2) Requirement files. If not defined, `requirements.txt`
        # will be used if it's present in the project directory.
        charm-requirements:
            - requirements-1.txt
            - requirements-2.txt

        # (Optional, new in charmcraft 1.4) A list of python packages to install
        # before installing requirements. These packages will be installed from
        # sources and built locally at packing time.
        charm-python-packages:
            - package1
            - package2

        # (Optional, new in charmcraft 1.4) A list of python packages to install
        # before installing requirements. Binary packages are allowed, but they
        # may also be installed from sources if a package is only available in
        # source form.
        charm-binary-python-packages:
            - package3
            - package4

        # (Optional) List of files to include. Note that `bundle.yaml`, the entry point
        # file and hooks are included automatically when packing a charm. Additionaly,
        # `config.yaml`, `metrics.yaml`, `actions.yaml`, `lxd-profile.yaml`, `templates`,
        # `version`, `lib` and `mod` will be included if they exist in the project directory.
        prime:
            - /path/to/file1
            - /path/to/file2

    # (Optional) Specify parts for a bundle if `type` is set to `bundle`.
    bundle:

        # (Optional) List of files to include. Note that `metadata.yaml` is included
        # automatically when packing a bundle.
        prime:
            - /path/to/file1
            - /path/to/file2

# A list of base configurations specifying environments charms 
# must be built on, and run on.
#
# There are two forms of base definition, both are indicated below.
bases:
    
    # (Optional) Short form base definition. Implies that the specified base is 
    # to be used for both `build-on` and `run-on`.
    - name: <name>
      channel: <channel>
      # (Optional) List of architecture strings, defaults to machine architecture
      architectures:
          - <arch>

    # (Optional) Expanded, long-form definition
    - build-on:
          - name: <name>
            channel: <channel>
            # (Optional) List of architecture strings, defaults to machine architecture
            architectures:
                - <arch>

      # (Optional) Defaults to what's specified in 'build-on'
      run-on:
          - name: <name>
            channel: <channel>
            # (Optional) List of architecture strings, defaults to machine architecture
            architectures:
                - <arch>

# (Optional, new in charmcraft 1.2) Control the analysis behaviour when explicitly running the 
# `analyze` command or implicitly running `pack`
analysis:
    # (Optional) Any attribute/lint analysis listed here (by name) will be ignored 
    ignore:
        attributes: [<check>,...]
        linters: [<check>,...]

Consult some examples

The following illustrate some implementations of the above spec:

type: bundle
charmhub:
  # these fields are set to the default value to illustrate field usage
  # likely not required in most cases
  api-url: https://api.charmhub.io
  storage-url: https://storage.snapcraftcontent.com
parts:
  bundle:
    prime: ["README.md"]

A different example, with a more comprehensive base definition:

type: charm
bases:
    - build-on:
        - name: ubuntu
          channel: "20.04"
          architectures: ["amd64"]
      run-on:
        - name: ubuntu
          channel: "21.04"
          architectures: 
              - amd64
              - aarch64
              - arm64

Start configuring!

Start modifying the examples above to suit your own needs.

1 Like

@facundo without quotation marks I am getting

Bad charmcraft.yaml content:
- string type expected in field 'bases[0].channel'

not sure if it should be a feature (convert to string) or should add quotation marks here

20.04 is a float. While we could convert this one to string automatically (and get "20.04", we do NOT want to get into the situation of converting 20.10 to "20.1".

So please use quotation marks around it. Thanks!

Thanks. Added.

@facundo The dash ("-") should be removed. With the current yaml I get the following error:

ERROR    Bad charmcraft.yaml content:
- field 'run-on' required in 'bases[0]' configuration
- field 'build-on' required in 'bases[1]' configuration
1 Like

Thanks! Fixed.

I understand there’s also a build-packages option to parts/charm. Could that be added here, it’s been asked about a few times by different people on Mattermost ?

1 Like

Unless I misread this, it is not specified under what path, the files listed under prime are included in the charm container. Also in the case of a bundle what path are prime files mapped into and for which charm ?

The files are included in the same path that are in the project (the root of the charm file would be root dir of the project itself).

If it’s a bundle, there are no “charms”. A bundle specifies a collection of charms but those charms are not inside the produced zip file.

Is it possible to have per-base configuration of the charms-python-packages property? See this github discussion for reference, where setuptools needs to be on v58 or lower for support on Bionic charms. It would be nice if charmcraft.yaml could have this specified for each Ubuntu base as needed.

Could this be added, and can anyone confirm if stage-packages should work as a way of installing packages in the charm at run time (or if there’s another way to do that - I’ve tried it without success)?

Is it necessary to specify the bases for a bundle? What happens if the bases in the bundle differ from the charm’s bases? Will the run-on from the charms be overwritten by the values on the bundle file?

No. bases is not needed, and in fact forbidden as a key, when packing a bundle.

Ah, got it! Do you know how to specify that a bundle can run on different OSes? We have charms that run on Ubuntu and Centos, but I can only specify one series in the bundle file, so when I upload to charmhub it shows only one OS in there. The bundle I am working on is: charmhub.io/slurm