You can develop a charm however you want, and in any language; however, the current standard is to use Charmcraft and to develop in Python using Ops. To test it, you’ll need a cloud – we recommend MicroK8s / LXD (for Kubernetes / machine charms) which you can set up on your local workstation – and Juju. Finally, you can develop directly on your machine but it is always a good idea to work in an isolated development environment; for that, we recommend a Multipass VM.
See more: Charmcraft (
charmcraft), Ops (ops), Juju | MicroK8su, Juju | LXD, Multipass
There are two ways to get all this set up: you can do it all step by step manually or you can take advantage of the Multipass charm-dev blueprint.
We demonstrate both below, starting with the automatic method which is designed to streamline the whole process for you.
Advanced charm development may require integrating with larger deployments. In those cases, a local MicroK8s or LXD provider may not be sufficient, and you may want to work with a bigger cloud. For that see the full list of Juju-supported clouds.
Set up your development environment automatically
- Create a directory for your charm
- Set up an Ubuntu
charm-dev-vmVM with Multipass - Choose your cloud and workload model
- Mount your charm directory to the Multipass VM
- Clean up
Create a directory for your charm
On your workstation, create a directory for your charm. E.g., on Linux, open a shell and run:
mkdir ~/my-charm
Set up an Ubuntu charm-dev-vm VM with Multipass
Multipass is a tool that will help you quickly spin up an Ubuntu VM.
Read more: Multipass
sudo snap install multipass
- Use Multipass to launch an Ubuntu VM called ‘charm-dev-vm’ using the
charm-devblueprint:
multipass launch --cpus 4 --memory 8G --disk 50G --name charm-dev-vm charm-dev
This step may take a few minutes to complete (e.g., 10 mins).
This is because the command downloads, installs, (updates,) and configures a number of packages, and the speed will be affected by network bandwidth (not just your own, but also that of the package sources).
However, once it’s done, you’ll have everything you’ll need – all in a nice isolated environment that you can clean up easily.
- Open a shell into the VM:
multipass shell charm-dev-vm
- (Optional:) Verify that the VM has indeed come pre-equipped with you’ll need:
Verify that you have Charmcraft:
charmcraft # should show a quick summary
Verify that you have a version of Python that meets the requirements from Ops:
python3 --version # should show Python >= 3.8
Take stock of any other pre-installed Python packages:
pip list # should show, e.g., requests, tox, toml, virtualenv
Verify that you have Juju, MicroK8s (for k8s charms) / LXD (for machine charms), a MicroK8s / LXD cloud (microk8s / localhost), a controller on that cloud (microk8s / lxd), and a workload model on that controller (welcome-k8s / welcome-lxd) :
Expand to see the instructions for MicroK8s
kubectl version
juju status --model microk8s:controller
juju status --model microk8s:welcome-k8s
Expand to see the instructions for LXD
lxc version
juju status --model lxd:controller
juju status --model lxd:welcome-lxd
Choose your cloud and workload model
Expand to see the instructions for MicroK8s
juju switch microk8s:welcome-k8s
Expand to see the instructions for LXD
juju switch lxd:welcome-lxd
Mount your charm directory to the Multipass VM
Use the multipass mount command. E.g., on Linux, open another shell and run:
multipass mount ~/my-charm charm-dev-vm:~/my-charm
You should now see a copy of your local charm directory on your VM as well. In your Multipass VM shell, run ls to verify:
ubuntu@charm-dev-vm:~$ ls
my-charm snap
With this setup you’ll be able to use all the tools preinstalled on the VM to initialise, pack, deploy, etc., your charm while also being able to edit the charm files in your own favourite local editor.
-
Going forward:
- Use your host machine (on Linux,
cd ~/my-charm) to create and edit your charm files. This will allow you to use your favorite local editor. - Use the Multipass VM shell (on Linux,
ubuntu@charm-dev-vm:~$ cd ~/my-charm) to run Charmcraft and Juju commands.
- Use your host machine (on Linux,
-
At any point:
- To exit the shell, press
mod key + Cor typeexit. - To stop the VM after exiting the VM shell, run
multipass stop charm-dev-vm. - To restart the VM and re-open a shell into it, type
multipass shell charm-dev-vm.
- To exit the shell, press
Clean up
Delete the Multipass VM:
multipass delete --purge charm-dev
Uninstall Multipass: Linux | macOS | Windows.
Set up your development environment manually
- Create a directory for your charm
- (Optional) Set up an Ubuntu VM with Multipass
- Set up Charmcraft
- Set up all the tools you’ll need for development in Python with Ops
- Set up your cloud
- Set up Juju
- (Optional) Set up Docker to publish your charm on Charmhub
- (Optional) Mount your charm directory to the Multipass VM
- (Optional) Clean up
Create a directory for your charm
On your workstation, create a directory for your charm. E.g., on Linux, open a shell and run:
mkdir ~/my-charm
(Optional) Set up an Ubuntu VM with Multipass
Multipass is a tool that will help you quickly spin up an Ubuntu VM.
Read more: Multipass
The goal of this section is to help you get a Linux machine that supports installation from snap, so that you can install Charmcraft.
If you already have that, we still recommend this step as a way for you to experiment in an isolated development environment.
If you however wish to continue directly on your existing Linux machine, just skip this step.
However, please keep in mind that the instructions in this tutorial have only been tested for the scenario with Multipass.
sudo snap install multipass
- Use Multipass to launch an Ubuntu VM called ‘charm-dev-vm’:
multipass launch --cpus 4 --memory 8G --disk 50G --name charm-dev-vm
- Open a shell into the VM:
multipass shell charm-dev-vm
Set up Charmcraft
E.g., on your Multipass VM:
# Charmcraft relies on LXD. Your Multipass VM already has LXD, but you must configure it:
lxd init --auto
# Install Charmcraft:
sudo snap install charmcraft --classic
See more: Install Charmcraft
Set up all the tools you’ll need for development in Python with Ops
Ops requires Python 3.8+. Check that you have that. E.g., on your Multipass VM:
python3 --version
Development with Ops usually requires some other Python tools as well. Make sure to get them ready. For example, install Tox – on your Multipass VM, as below:
# tox depends on Python and pip
sudo apt update; sudo apt install python3 python3-pip
# Use pip to get tox:
python3 -m pip install --user tox
Set up your cloud
Depending on whether you want to develop a Kubernetes / machine charm, you will have to set up the MicroK8s / LXD localhost cloud. For example, on Linux:
Expand to set up your MicroK8s cloud
# Install MicroK8s package:
sudo snap install microk8s --channel 1.28-strict
# Add your user to the `microk8s` group for unprivileged access:
sudo adduser $USER snap_microk8s
# Give your user permissions to read the ~/.kube directory:
sudo chown -f -R $USER ~/.kube
# Wait for MicroK8s to finish initialising:
sudo microk8s status --wait-ready
# Enable the 'storage' and 'dns' addons:
# (required for the Juju controller)
sudo microk8s enable hostpath-storage dns
# Alias kubectl so it interacts with MicroK8s by default:
sudo snap alias microk8s.kubectl kubectl
# Ensure your new group membership is apparent in the current terminal:
# (Not required once you have logged out and back in again)
newgrp snap_microk8s
Expand to set up your LXD cloud
# lxd init --auto # should already be there from the Charmcraft setup step
lxc network set lxdbr0 ipv6.address none
Set up Juju
On your Ubuntu VM, install Juju, connect it to your MicroK8s cloud, and create a model:
# Install Juju:
sudo snap install juju --channel 3.1/stable
# >>> juju (3.1/stable) 3.1.2 from Canonical✓ installed
# Since the juju package is strictly confined, you also need to manually create a path:
mkdir -p ~/.local/share
# For MicroK8s, if you are working with an existing snap installation, and it is not strictly confined:
# (https://microk8s.io/docs/strict-confinement), you must also:
#
# # Share the MicroK8s config with Juju:
# sudo sh -c "mkdir -p /var/snap/juju/current/microk8s/credentials"
# sudo sh -c "microk8s config | tee /var/snap/juju/current/microk8s/credentials/client.config"
#
# # Give the current user permission to this file:
# sudo chown -f -R $USER:$USER /var/snap/juju/current/microk8s/credentials/client.config
# Register your MicroK8s / LXD cloud with Juju:
# Not necessary --juju recognises a local MicroK8s / LXD cloud automatically, as you can see by running 'juju clouds'.
juju clouds
# >>> Cloud Regions Default Type Credentials Source Description
# >>> localhost 1 localhost lxd 0 built-in LXD Container Hypervisor
# >>> microk8s 1 localhost k8s 1 built-in A Kubernetes Cluster
# (If for any reason this doesn't happen, you can register it manually using 'juju add-k8s microk8s'.)
# Replace <cloud> with 'microk8s' or 'localhost'
# to bootstrap a Juju controller into your MicroK8s / LXD cloud.
# We'll name our controller "dev-controller".
juju bootstrap <cloud> dev-controller
# Create a workspace, or 'model', on this controller.
# We'll call ours "dev-model".
# Reminder: In Kubernetes this corresponds to a namespace "dev-model".
juju add-model dev-model
# Check status:
juju status
# >>> Model Controller Cloud/Region Version SLA Timestamp
# >>> dev-model tutorial-controller microk8s/localhost 3.0.2 unsupported 16:05:03+01:00
# >>> Model "admin/dev-model" is empty.
# There's your charm model!
(Optional) Set up Docker to publish your charm on Charmhub
E.g., on your Multipass VM:
sudo addgroup --system docker
sudo adduser $USER docker
newgrp docker
sudo snap install docker
(Optional) Mount your charm directory to the Multipass VM
If earlier you decided to use Multipass, mount your local charm directory to the charm VM. E.g., on Linux:
multipass mount ~/my-charm charm-dev:~/my-charm
This will allow you to use all the tools from the VM to initialise, pack, deploy, etc., your charm while also being able to edit the charm files in your own favourite local editor.
(Optional) Clean up
If earlier you decided to use Multipass, delete the Multipass VM:
multipass delete --purge charm-dev-vm
Uninstall Multipass: Linux | macOS | Windows.
Contributors: @jnsgruk , @kos.tsakalozos , @rbarry , @facundo , @saviq , @sed-i , @tmihoc , @gbeuzeboc , @acsgn , @gzanchi , @jose-mingorance
