Installing Charmcraft

How to install

Linux

The recommended way to install charmcraft is from the stable channel with

sudo snap install charmcraft --classic

There are multiple channels other than stable. See the full list with
snap info charmcraft.

We recommend either latest/stable or latest/candidate for everyday charming. With the snap you will always be up to date as Charmhub services and APIs evolve. Charmcraft supports Kubernetes operator development.

On Linux, Charmcraft currently depends on LXD to build the charms in a container matching the target base(s). Charmcraft will offer to install LXD if required, but here are steps to set it up manually:

$ sudo snap install lxd
$ sudo adduser $USER lxd
$ newgrp lxd
$ lxd init --auto

MacOS

Charmcraft does not yet support Mac OS.

Windows

Charmcraft does not yet support Windows.

Developer Mode (Unsupported)

Use pip to install Charmcraft for development purposes. Using a virtualenv is strongly recommended. For example:

git clone https://github.com/canonical/charmcraft.git
cd charmcraft
python3 -m venv venv
source venv/bin/activate
pip install -e .[dev]

Then run Charmcraft with CHARMCRAFT_DEVELOPER=y to enable developer-mode. For example:

CHARMCRAFT_DEVELOPER=y charmcraft pack

Alternatively:

CHARMCRAFT_DEVELOPER=y python3 -m charmcraft pack

NOTE: this is not supported for production use and may cause unexpected behaviors.

Using Charmcraft

Charmcraft enables collaboration between charmed operator developers, and
publication on Charmhub, home of the Charmed Operator
Collection.

Use charmcraft to:

  • Init a new charmed operator file structure
  • Build your operator into a charmed operator for distribution
  • Register your charmed operator name on Charmhub
  • Upload your charmed operators to Charmhub
  • Release your charmed operators into channels

You can use charmcraft with operators written in any language but we
recommend the Python Operator Framework on
Github
which is also on
PyPI
for ease of development and
collaboration.

Charmcraft and the Charmed Operator Framework extend the operator pattern
beyond Kubernetes with universal
operators
that drive Linux and
Windows apps. The universal operator pattern is very exciting for
multi-cloud application management.

Initialize a charm operator package file structure

Use charmcraft init to create a new template charm operator file tree:

$ mkdir my-new-charm; cd my-new-charm
$ charmcraft init
Charm operator package file and directory tree initialized.
TODO:

      README.md: Describe your charm in a few paragraphs of Markdown
      README.md: Provide high-level usage, such as required config or relations
   actions.yaml: change this example to suit your needs.
    config.yaml: change this example to suit your needs.
  metadata.yaml: fill out the charm's description
  metadata.yaml: fill out the charm's summary
  metadata.yaml: replace with containers for your workload (delete for non-k8s)
  metadata.yaml: each container defined above must specify an oci-image resource
   src/charm.py: change this example to suit your needs.
   src/charm.py: change this example to suit your needs.
   src/charm.py: change this example to suit your needs.

You will now have all the essential files for a charmed operator, including
the actual src/charm.py skeleton and various items of metadata. Charmcraft
assumes you want to work in Python so it will add requirements.txt with
the Python operator framework ops, and other conventional development
support files.

Build your charm

With a correct metadata.yaml and with ops in requirements.txt you can
build a charmed operator with:

$ charmcraft build
Created 'test-charm.charm'.

charmcraft build will fetch additional files into the tree from PyPI based
on requirements.txt and will compile modules using a virtualenv.

The charmed operator is just a zipfile with metadata and the operator code
itself:

$ unzip -l test-charm.charm
Archive:  test-charm.charm
  Length      Date    Time    Name
---------  ---------- -----   ----
      221  2020-11-15 08:10   metadata.yaml
[...]
    25304  2020-11-15 08:14   venv/yaml/__pycache__/scanner.cpython-38.pyc
---------                     -------
   812617                     84 files

Now, if you have a Kubernetes cluster with the Juju OLM accessible you can issue
juju deploy ./my-new-charm.charm --resource httpbin-image=kennethreitz/httpbin.
You do not need to publish your operator on Charmhub, you can pass the charmed
operator file around directly to users, or for CI/CD purposes.


Last updated 5 days ago.