Set up your development environment

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 | MicroK8s, 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.

• Set up your development environment automatically
• Set up your development environment manually

Set up your development environment automatically

1. Create a directory for your charm
2. Set up an Ubuntu charm-dev-vm VM with Multipass
3. Choose your cloud and workload model
4. Mount your charm directory to the Multipass VM
5. 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

1. Install Multipass:

sudo snap install multipass

2. Use Multipass to launch an Ubuntu VM called ‘charm-dev-vm’ using the charm-dev blueprint:

multipass launch --cpus 4 --memory 8G --disk 50G --name charm-dev-vm charm-dev 

3. Open a shell into the VM:

multipass shell charm-dev-vm

4. (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) :

kubectl version
juju status --model microk8s:controller
juju status --model microk8s:welcome-k8s

lxc version
juju status --model lxd:controller
juju status --model lxd:welcome-lxd

Choose your cloud and workload model

juju switch microk8s:welcome-k8s

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 --type native ~/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.

Clean up

Delete the Multipass VM:

multipass delete --purge charm-dev

Uninstall Multipass: Linux | macOS | Windows.

Set up your development environment manually

1. Create a directory for your charm
2. (Optional) Set up an Ubuntu VM with Multipass
3. Set up Charmcraft
4. Set up all the tools you’ll need for development in Python with Ops
5. Set up your cloud
6. Set up Juju
7. (Optional) Set up Docker to publish your charm on Charmhub
8. (Optional) Mount your charm directory to the Multipass VM
9. (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

1. Install Multipass: Linux | macOS | Windows. On Linux (assumes you have snapd):

sudo snap install multipass

2. Use Multipass to launch an Ubuntu VM called ‘charm-dev-vm’:

multipass launch --cpus 4 --memory 8G --disk 50G --name charm-dev-vm

3. 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:

# 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

# 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: @acsgn , @facundo , @gbeuzeboc, @gzanchi, @jnsgruk , @jose-mingorance, @kos.tsakalozos , @mathmarchand, @rbarry , @saviq , @sed-i , @tmihoc