From Wikitech
Jump to navigation Jump to search

This page contains information on Toolforge lima-kilo, a project to help setting up a fake Toolforge local kubernetes environment in a given local machine (like a laptop), to help develop some of the Toolforge internal components.

The lima-kilo project is based on ansible.

Repository: https://gitlab.wikimedia.org/repos/cloud/toolforge/lima-kilo


Developing some Toolforge kubernetes components can be challenging because Toolforge is not just a bare k8s deployment. It is Toolforge's kubernetes. There are custom admission webhooks, custom namespaces, a particular security model, some host files are expected to be present, etc.

The lima-kilo fakes most of this service context in a local environment in a way that, thanks to ansible, is lightweight, robust, deterministic, idempotent and easy to use.

The industry uses mostly 2 solutions for local kubernetes deployments like this:

Some of these product work best for different laptop operating systems (Debian, Ubuntu, mac OSX, etc). And the already-in-place modularity of lima-kilo allows to support the combo of these options, for example:

  • debian-kind
  • debian-minikube
  • osx-kind
  • osx-minikube

Please note that not all of them might be supported/coded yet, and if you are the first to bring a new environment combo you might have to add support for it yourself. This should be rather easy though. Ask for help,

The project was mildly inspired by MediaWiki-Vagrant, and might in fact introduce vagrant support in the future.

Basic usage workflow

Usage should be rather simple:

  1. Git clone the repository
  2. make sure there is a playbook for your desired environment combo, check the playbooks/ directory. If not, ask for help with implementing a new one.
  3. run the playbook, like ansible-playbook -KD playbooks/kind-install.yaml
  4. enjoy!

You may want to set up some local configuration to modify the lima-kilo behavior. This can be done in the ~/.toolforge-lima-kilo/userconfig.yaml file, see the README file for some hints.

Code conventions

Some informal code conventions:

  • Everything lima-kilo does, it should be capable of undoing.
  • Therefore, there should be install and uninstall playbooks for each environment.
  • Playbooks should be idempotent (ie, if running them twice, the second time is basically a NOOP). This is a core principle of ansible, but worth mentioning.
  • If an action is too invasive in the local system, a config option should be introduced to prevent/relax the action. Like installing / uninstalling packages that might be managed by hand by the user.
  • When introducing changes, be mindful of previous lima-kilo deployments others developers may have in their system. This is important for example when renaming resources.
  • Try to write playbooks as much OS-agnostic as possible. So the same playbook can be used in both OSX and Debian.

See also