Manage charms¶

See first: Juju | Charm, Juju | Manage charms

Initialise a charm¶

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), in your charmcraft.yaml file set the type key to charm:

type: charm

Specify a name¶

To specify a pack-and-deploy name for your charm, in your charm’s charmcraft.yaml 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 charmcraft.yaml 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 charmcraft.yaml 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 charmcraft.yaml 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 charmcraft.yaml 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 a link to source code¶

To add a link to the source code for a charm, in your charm’s charmcraft.yaml file specify an item under the links.source key. E.g.,

links:
  source:
  - https://github.com/canonical/traefik-k8s-operator

See more: links

Add a link to the bug tracker¶

To add a link to the bug tracker for a charm, in your charm’s charmcraft.yaml file specify an item under the links.issues key. E.g.,

links:
  issues:
    - https://github.com/canonical/traefik-k8s-operator/issues

See more: links

Add a link to the website¶

If your charm has a website outside of Charmhub, to add a link to this website, in your charm’s charmcraft.yaml file specify an item under the links.website key. E.g.,

links:
  website:
  - https://charmed-kubeflow.io/

See more: links

Add docs and a link to the docs¶

If you publish your charm on Charmhub, reference documentation about the charm’s resources, actions, configurations, relations, and libraries is extracted automatically. However, you should also aim to add further docs, e.g., a tutorial, how-to guides, etc. To provide a link to these docs, in your charm’s charmcraft.yaml file specify a value for the links.documentation key. Note that at present this must be a Discourse page. E.g.,

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

See more: links

Add terms of use¶

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

terms:
  - Butterscotch is regal
  - Cara is adorable

See more: terms

Add an icon¶

See 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 charmcraft.yaml 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 charmcraft.yaml 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 charmcraft.yaml 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 charmcraft.yaml file specify the containers key.

See more: containers

Specify associated resources¶

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

See Manage resources.

Specify device requirements¶

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

See more: devices

Specify storage requirements¶

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

See more: storage

Specify extra binding requirements¶

To specify extra binding requirements, in your charm’s charmcraft.yaml 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 charmcraft.yaml file specify the subordinate key.

See more: subordinate

Manage actions¶

See first: Juju | Action, Juju | Manage actions

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

See more: actions

See next: How to manage actions

Manage configurations¶

See first: Juju | Application configuration, Juju | Manage applications > Configure

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

See more: config

See next: Manage configurations

Manage relations (integrations)¶

See first: Juju | Relation, Juju | Manage relations

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

See more: peers, provides, and requires

See more: How to manage relations

Specify necessary libs¶

Manage secrets¶

See first: Juju | User secret

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

See more: config

See next: How to 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

See next: Juju | Manage charms

Publish a charm on Charmhub¶

Log in to Charmhub:
```
   charmcraft login

..
```
See more: Manage the current Charmhub user
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.
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.
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-super-charm someresource
--filepath=/tmp/superdb.bin
```
Revision 1 created of resource 'someresource' for charm 'my-super-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.
Release the charm: To release a charm, release your revision of choice to the target release channel. E.g.,
```
charmcraft release my-awesome-charm --revision=1 --channel=beta
```
Revision 1 of charm 'my-awesome-charm' released to beta ..

See more: Manage charm revisions

Note

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

See next: Juju | Deploy a Charmub charm, Juju | Update a Charmhub 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: