Manage charms

Initialise a charm

Best practice

If you’re setting up a git repository: name it using the pattern <charm name>-operator. For the charm name, see Specify a name.

To initialise a charm project, create a directory for your charm, enter it, then run charmcraft init with the --profile flag followed by a suitable profile name (for machine charms: machine; for Kubernetes charms: kubernetes, simple, or flask-framework); that will create all the necessary files and even prepopulate them with useful content.

charmcraft init --profile <profile>
Example session
mkdir my-flask-app-k8s
cd my-flask-app-k8s/
charmcraft init --profile flask-framework
Charmed operator package file and directory tree initialisedNow edit the following package files to provide fundamental charm metadataand other information: charmcraft.yamlsrc/charm.pyREADME.md
ls -R
.:charmcraft.yaml  requirements.txt  src ./src:charm.py

The command also allows you to not specify any profile (in that case you get the simple profile – a Kubernetes profile with lots of scaffolding, suitable for beginners) and has flags that you can use to specify a different directory to operate in, a charm name different from the name of the root directory, etc.

See more: revisions, Profile, Files

See more: Manage extensions

Add charm project metadata, an icon, docs

Specify that the project is a charm

To specify that the project is a charm (as supposed to a bundle), set the type key to charm in your project file:

type: charm

See more: type

Specify a name

To specify a pack-and-deploy name for your charm, in your charm’s project file, specify the name key. E.g.,

name: traefik-k8s

See more: name

Specify a title

To specify a title for your charm’s page on Charmhub, in your charm’s project file, specify a value for the title key. E.g.,

title: |
  Traefik Ingress Operator for Kubernetes

See more: title

Add a summary

To add a summary line for your charm, in your charm’s project file, specify a value for the summary key. E.g.,

summary: |
  A Juju charm to run a Traefik-powered ingress controller on Kubernetes.

See more: summary

Add a description

To add a longer description for your charm, in your charm’s project file, specify a value for the description key. E.g.,

description: |
  A Juju-operated Traefik operator that routes requests from the outside of a
  Kubernetes cluster to Juju units and applications.

See more: description

Add contact information

To add maintainer contact information for a charm, in your charm’s project file, specify a value for the links.contact key. E.g.,

links:
  contact: Please send your answer to Old Pink, care of the Funny Farm, Chalfont

See more: links

Add docs

If you publish your charm on Charmhub, reference documentation about the charm’s resources, actions, configurations, relations, and libraries is generated and published automatically in respective tabs.

To add content to the Description tab, create a Discourse topic and include its URL in your charm’s project file under the links.documentation key:

links:
  documentation: https://discourse.charmhub.io/t/traefik-k8s-docs-index/10778

See more: links

The Description tab can contain additional documentation, such as tutorials or how-to guides.

Note

A charm’s documentation should focus on the charm itself. For workload-specific or Juju-related content, link to the appropriate upstream documentation.

A smaller charm can have single-page documentation for its description. A bigger charm, that needs multi-page documentation, can have either a brief description with a link to an external documentation set, or a full Diátaxis navigation tree in the Description tab.

Best practice

Smaller charm documentation examples:

Best practice

Bigger charm documentation examples:

Add terms of use

To add terms of use for your charm, in your charm’s project file, specify a value for the terms key. E.g.,

terms:
  - Butterscotch is regal
  - Cara is adorable

See more: terms

Add an icon

See more: Manage icons

Add runtime details to a charm

Require a specific Juju version

To require a specific Juju version for your charm, in your charm’s project file, specify the assumes key. E.g.,

assumes:
  - juju >= 3.5

See more: assumes

Require a Kubernetes cloud

To require a Kubernetes cloud for your charm, in your charm’s project file, specify the assumes key. E.g.,

assumes:
  - k8s-api

See more: assumes

Require a specific base and platforms

To require a specific base and platforms for your charm, in your charm’s project file, specify the base, and platforms keys. E.g.,

Note

In Charmcraft < 3.0 this was done via a single key: bases.

# The run time base, the base format is <os-name>@<os-release>,
# accepted bases are:
# - [email protected]
base: <base>
# The build time base, if not defined the base is also the build time
# base, in addition to valid bases, the build-base can be "devel"
# which would use the latest in development Ubuntu Series.
build-base: <base>

platforms:
  # The supported platforms, may omit build-for if platform-name
  # is a valid arch, valid architectures follow the Debian architecture names,
  # accepted architectures are:
  # - amd64
  # - arm64
  # - armhf
  # - ppc64el
  # - riscv64
  # - s390x
  <platform-name>:
    # The build time architecture
    build-on: <list-of-arch> | <arch>
    # The run time architecture
    build-for: <list-of-arch> | <arch>

See more: base, build-base

Specify container requirements

To specify container requirements, in your charm’s project file, specify the containers key.

See more: containers

Specify associated resources

To specify the resources associated with the charm, in your charm’s project file, specify the resources key.

Specify device requirements

To specify device requirements, in your charm’s project file, specify the devices key.

See more: devices

Manage storage

To specify storage requirements, in your charm’s project file, specify the storage key.

See more: storage

Specify extra binding requirements

To specify extra binding requirements, in your charm’s project file, specify the extra-bindings key.

See more: extra-bindings

Require subordinate deployment

To require subordinate deployment for your charm (i.e., for it to be deployed to the same machine as another charm, called its principal), in your charm’s project file, specify the subordinate key.

See more: subordinate

Manage actions

To declare an action in your charm, in your charm’s project file, specify the actions key.

See more: actions

See next: Ops | Manage actions

Manage the app configuration

To declare a configuration option for your charm, in your charm’s project file, specify the config key.

See more: config

See next: Ops | Manage configuration

Manage relations

See first: Juju | Relation, Juju | Manage relations

To declare a relation endpoint in your charm, in your charm’s project file, specify the peers, provides, or requires key.

See more: peers, provides, and requires

See more: Ops | Manage relations

Specify necessary libs

See more: Manage libraries

Manage secrets

To make your charm capable of accepting a user secret, in your charm’s project file, specify the config key with the type subkey set to secret.

See more: config

See next: Ops | Manage secrets

Specify necessary parts

See more: Manage parts

Pack a charm

To pack a charm directory, in the charm’s root directory, run the command below:

charmcraft pack

This will fetch any dependencies (from PyPI, based on requirements.txt), compile any modules, check that all the key files are in place, and produce a compressed archive with the extension .charm. As you can verify, this archive is just a zip file with metadata and the operator code itself.

Example session for a charm called microsample-vm

Pack the charm:

charmcraft pack
Created 'microsample-vm_ubuntu-22.04-amd64.charm'.Charms packed:  microsample-vm_ubuntu-22.04-amd64.charm

Optionally, verify that this has created a .charm file in your charm’s root directory:

ls
CONTRIBUTING.md  charmcraft.yaml                          requirements.txt  tox.iniLICENSE          microsample-vm_ubuntu-22.04-amd64.charm  srcREADME.md        pyproject.toml                           tests

Optionally, verify that the .charm file is simply a zip file that contains everything you’ve packed plus any dependencies:

unzip -l microsample-vm_ubuntu-22.04-amd64.charm | { head; tail;}
Archive:  microsample-vm_ubuntu-22.04-amd64.charm  Length      Date    Time    Name---------  ---------- -----   ----      815  2023-12-05 12:12   README.md    11337  2023-12-05 12:12   LICENSE      250  2023-12-05 12:31   manifest.yaml      102  2023-12-05 12:31   dispatch      106  2023-12-01 14:59   config.yaml      717  2023-12-05 12:31   metadata.yaml      921  2023-12-05 12:26   src/charm.py      817  2023-12-01 14:44   venv/setuptools/command/__pycache__/upload.cpython-310.pyc    65175  2023-12-01 14:44   venv/setuptools/command/__pycache__/easy_install.cpython-310.pyc     4540  2023-12-01 14:44   venv/setuptools/command/__pycache__/py36compat.cpython-310.pyc     1593  2023-12-01 14:44   venv/setuptools/command/__pycache__/bdist_rpm.cpython-310.pyc     6959  2023-12-01 14:44   venv/setuptools/command/__pycache__/sdist.cpython-310.pyc     2511  2023-12-01 14:44   venv/setuptools/command/__pycache__/rotate.cpython-310.pyc     2407  2023-12-01 14:44   venv/setuptools/extern/__init__.py     2939  2023-12-01 14:44   venv/setuptools/extern/__pycache__/__init__.cpython-310.pyc---------                     -------20274163                     1538 files

The command has a number of flags that allow you to specify a different charm directory to pack, whether to force pack if there are linting errors, etc.

See more: pack

Caution

If you’ve declared any resources : This will not pack the resources. This means that, when you upload your charm to Charmhub (if you do), you will have to upload the resources separately. See more: Manage resources.

Important

When the charm is packed, a series of analyses and lintings will happen, you may receive warnings and even errors to help improve the quality of the charm. See more: Charmcraft analyzers and linters

Publish a charm on Charmhub

  1. Log in to Charmhub:

    charmcraft login

  1. Register your charm’s name (the one you specified in charmcraft.yaml > name):

    charmcraft register my-awesome-charm

    See more: Manage names

    Note

    This automatically creates 4 channels, all with track latest but with different risk levels, namely, edge, beta, candidate, stable, respectively.

    See more: Manage channels.

  2. Upload the charm to Charmhub: Use the charmcraft upload command followed by the your charm’s filepath. E.g., if you are in the charm’s root directory,

    charmcraft upload my-awesome-charm.charm
    Revision 1 of my-awesome-charm created

    See more: upload

    Note

    Each time you upload a charm to Charmhub, that creates a revision (unless you upload the exact same file again). See more: Manage charm revisions.

  3. If your charm has associated resources: These are not packed with the rest of the charm project, so you must upload them explicitly to Charmhub as well. For example:

    charmcraft upload-resource my-awesome-charm someresource
--filepath=/tmp/superdb.bin
    Revision 1 created of resource 'someresource' for charm 'my-awesome-charm'

    See more: Manage resources

    Note

    Each time you upload a resource to Charmhub, that creates a revision (unless you upload the exact same file again). See more: Manage resource revisions.

  4. Release the charm: To release a charm, release your revision of choice to the target release channel. For a charm that has a resource, also specify the resource and its revision. E.g.,

    charmcraft release my-awesome-charm --revision=1 --channel=beta
--resource someresource:1
    Revision 1 of charm 'my-awesome-charm' released to beta (attaching resources: 'someresource' r1)

See more: Manage charm revisions

Note

This automatically opens the channel. See more: Manage channels.

See next: Juju | Deploy a charm, Juju | Update a charm

Tip

To update the charm on Charmhub, repeat the upload and release steps.

Important

Releasing a charm on Charmhub gives it a public URL. However, the charm will not appear in the Charmhub search results until it has passed formal review. To request formal review, reach out to the community to announce your charm and ask for a review by an experienced community member. See more: Discourse | review requests.

Also, the point of publishing and having a charm publicly listed on Charmhub is so others can reuse it and potentially contribute to it as well. To publicise your charm: