MicroK8s’ addons, extra services which can be added to your bare-bones cluster, are a great favourite with users. Do you want to apply the CoreDNS manifest, reconfigure kubelet and restart the nodes on a cluster? Just run microk8s enable dns… Do you want to install a hostpath storage provisioner and fire up Portainer? microk8s enable portainer does exactly that. There are no particular restrictions to what an addon can do - if you can do it in Kubernetes, you can write an addon to do it too.
From the v1.24 release, the addons framework is now open to the public! We have made sure software vendors and enthusiasts can create and use thier own addon repositories and edit in-place any available addons within a running cluster.
In this page you will find out :
- How addons are used
- How they can be tuned to match your needs
- How to create addons and use them in your own repo
- How to promote your work through the community addons repository
How to use MicroK8s addons
With the microk8s status command you can see the list of the available addons:
To enable an addon, you need to call microk8s enable followed by the name of the addon, eg microk8s enable dns. Similarly, microk8s disable will disable the named addon and uninstall it.
In the example output above you may notice that the description of each addon starts with “core”. This indicates the repository the addon is available from. Core addons are the ones maintained and supported by the MicroK8s team. In addition to the core addons we ship MicroK8s with a set of community maintained addons. To display those you just need to run the command microk8s enable community
As we will see, adding, removing and updating repositories is done through the microk8s addons repo command. The microk8s enable community is a shortcut to get the community contributions visible without knowing the exact URL of the respective repo.
Adapting addons to meet your needs
Addon repositories are git projects which are cloned under /var/snap/microk8s/common/addons . For example, the core repository is found in the /var/snap/microk8s/common/addons/core directory inside which there is a folder called addons with all its addons.
Notice the enable and disable executable files found on each addon? These are the hook scripts each addon implements and the microk8s enable and microk8s disable commands expect to be able to find and call.
Maybe an addon does 95% of what you want, but not exactly what you need. There is nothing stopping you from editing the respective enable hook to match your needs. Although there are no restrictions on the language these hooks are written in, often they come as bash or Python scripts.
Try this yourself. Edit /var/snap/microk8s/common/addons/core/addons/dns/coredns.yaml and change the image: coredns/coredns:1.10.0 to image: coredns/coredns:1.10.1 Save the enable file and call microk8s enable dns. Yes, it is that simple!
Setup your own repository
The most exciting feature of the v1.24 release is the option to add 3rd-party repositories to a MicroK8s cluster.
To bootstrap the repository authoring process the MicroK8s team provides a template repository with two example addons (in python and bash) to fork. That repository can be found at https://github.com/canonical/microk8s-addons-repo-template. The README.md and HACKING.md pages will guide you through this task.
Here, we will briefly touch on the main steps you need to take:
Fork the template repository. If you are logged into Github just click on the “Use this template” button and fill out the “new repository” form.
The addons.yaml at the top level of each repo holds the list of the addons. Replace this list with the list of addons you will be shipping. Each entry has the following fields:
- name: the name of the addon
- description: printed in the microk8s status output
- version: a string with the version of your addon
- check_status: what would the microk8s status run to figure out if the addon is enabled or not. This can be a deployment within Kubernetes or a file acting as a lock file on the host.
- supported_architectures: for now MicroK8s ships for AMD64, ARM64 and S390x.
Create a directory under addons named after the addon you would be implementing.
In that directory, add two executable files named enable and disable. These executables can be written in any language and are called by the microk8s enable/disable commands.
At this point, you are able to add your repository into MicroK8s with something similar to:
microk8s addons repo add fantastic https://github.com/myorg/myrepo
fantastic is the ID you give to your repository. From this point on this ID is used to reference the repo when updating and removing it, eg:
microk8s addons repo update fantastic
microk8s addons repo remove fantastic
Knowing that addons are git projects allows for a number of workflows while developing:
Using the --reference flag you can add a repository and point to a branch/tag:
You can also add a git project as a repository that is local on your host:
Use microk8s addons repo update to fetch the latest changes pushed on the repository you are working on. Alternatively you can clone a git repository directly under /var/snap/microk8s/common/addons/ and MicroK8s will pick it up as a repository.
Promote your work in the MicroK8s community repo
MicroK8s ships with both the core and community addons. In order not to clutter the user output the community addons are not visible by default. You need to microk8s enable community or to add the community repository as any other repository:
microk8s addons repo add community https://github.com/canonical/microk8s-addons.git
In order to promote your work you can fork the community repository, add your addon, and place a PR against the upstream repo. Some things you should be aware of:
-
New addons are added only on new releases. This means that the set of addons of a release (eg v1.24) will not change during patch releases. Newly merged addons are available in the next release.
-
Each addon is expected to have a maintainer. The addons are not “donated” to the MicroK8s team.
-
Each addon is expected to have a test making sure it deploys correctly. Tests are Python based at this point and are found under the tests directory. Before each patch release we make sure all tests are passing.
What Next?
- Take a look at the community addon repository for ideas.
- Read the HACKING.md docs for detailed instructions on making your own add-on!