Installing to a local machine
Installing Charmed Kubernetes on a single machine is possible for the purposes of testing and development.
However, be aware that the full deployment of Charmed Kubernetes has system requirements which may exceed a standard laptop or desktop machine. It is only recommended for a machine with 32GB RAM and 250GB of SSD storage.
Note: If you don't meet these requirements or want a lightweight way to develop on pure Kubernetes, we recommend microk8s
In order to run locally, you will need a local cloud. This can be achieved by using lightweight containers managed by LXD. LXD version 3.0 or better is required.
1. Set up LXD
If LXD has not previously been installed
LXD 3.0 or above should be installed from a snap and configured for Charmed Kubernetes
sudo snap install lxd
Run the LXD init script
The init script itself may vary depending on the version of LXD. The important configuration options for the installer are:
- Networking: Do NOT enable ipv6 networking on the bridge interface
- Storage Pool: Use the 'dir' storage type
You can now move on to the next step
If LXD is already installed
If you installed LXD from a snap, you can skip this step (but if necessary, you may need to alter the default profile). If your system
had LXD pre-installed, or you have installed it from the archive (i.e. with
apt install), you will need to migrate to the snap version.
If you aren't sure whether LXD is installed, you can check installed snaps with:
snap list | grep lxd
and installed deb packages with:
dpkg -s lxd | grep Status
If you do have the deb version of LXD installed, you should migrate to the snap version after it has been installed. The snap includes a script to do this for you:
sudo snap install lxd sudo /snap/bin/lxd.migrate
This will move all container specific data to the snap version and clean up the unused Debian packages, which may take a few minutes.
If LXD was installed, but never used, there will be no data in the default profile, so you should now initialise LXD:
sudo lxd init
Currently, Charmed Kubernetes only supports
dir as a storage option and
does not support ipv6, which should be set to
none from the init script.
Additional profiles will be added automatically to LXD to support the
requirements of Charmed Kubernetes.
2. Install Juju
Juju should be installed from a snap:
sudo snap install juju --classic
Juju comes preconfigured to work with LXD. A cloud created by using LXD
containers on the local machine is known as
localhost to Juju. To begin, you
need to create a Juju controller for this cloud:
juju bootstrap localhost
Juju creates a default model, but it is useful to create a new model for each project:
juju add-model k8s
3. Deploy Charmed Kubernetes
All that remains is to deploy Charmed Kubernetes. A simple install can be achieved with one command:
juju deploy charmed-kubernetes
This will install the latest stable version of Charmed Kubernetes with the default components and configuration. If you wish to customise this install (which may be helpful if you are close to the system requirements), please see the main install page.
In order to avoid potential IP masquerading issues with kube-proxy on LXD, we also recommend configuring kube-proxy to use its userspace proxy mode:
juju config kubernetes-master proxy-extra-args="proxy-mode=userspace" juju config kubernetes-worker proxy-extra-args="proxy-mode=userspace"
Now you have a cluster up and running, check out the Operations guide for how to use it!
I get an error message when running lxc or lxd init
The most common cause of this message:
Error: Get http://unix.socket/1.0: dial unix /var/snap/lxd/common/lxd/unix.socket: connect: permission denied
...is that either you have not run
lxd init, or you are logged in as a user
who is not part of the
lxd group (the user installing the snap is
To add the current user to the relevant group:
sudo usermod -a -G lxd $USER
You may need to start a new shell (or logout and login) for this to take effect:
Services fail to start with errors related to missing files in the /proc filesystem
systemctl status snap.kube-proxy.daemon may report the following:
Error: open /proc/sys/net/netfilter/nf_conntrack_max: no such file or directory
This is most commonly caused when lxd-profile.yaml is not applied.
Verify the profile in use by the
lxc profile list lxc profile show juju-[model]-kubernetes-worker-[revision]
Identify any missing fields from the above
lxd-profile.yaml file and add them
as needed with:
lxc profile edit juju-[model]-kubernetes-worker-[revision]
You may need to remove and re-add the affected unit for the changes to take effect:
juju remove-unit kubernetes-worker/[n] juju add-unit kubernetes-worker