Symplegma

Symplegma (from greek σύμπλεγμα) is a simple set of Ansible playbooks to deploy Kubernetes with Kubeadm. It is heavily inspired by Kubespray and OpenStack Ansible.

Historical releases have Kubernetes conformance results. The refreshed stack has not yet been submitted for conformance certification.

The main goal is to be minimalist with sensible defaults.

Flannel is included. Install other cluster networking providers independently; legacy Calico/operator roles are no longer part of the supported requirements.

Deploys a Kubernetes cluster

• Deploys vanilla Kubernetes with Kubeadm.
• Targets current stable Flatcar Linux and Ubuntu 24.04 / 26.04, on amd64 and arm64 with cgroup v2.
• Requires Python 3.12 or newer on the Ansible controller.
• Windows workers are retired.
• Does not rely on Docker
• Uses CRI compatible runtime:
  • containerd (default)
  • cri-o
• Does not depend on cloud provider
• Does not depend on primary master
• Dynamic config
• Pins component versions for reproducible installations

Install and validate

mise install
just setup
just check

Mise pins uv, Node and just; uv selects Python from .python-version, resolves the Ansible/development/documentation groups in pyproject.toml, and reproduces them from uv.lock. No virtualenv activation is needed. Without mise, use uv sync --locked --all-groups and uv run --locked before each command.

The install script fetches the exact published roles in requirements.yml. It preserves existing role checkouts and refuses mismatched revisions; no local compatibility patches or virtualenv activation are needed.

The default stack is Kubernetes / kubeadm / kubelet / kubectl 1.37.0, containerd 2.3.5, runc 1.5.1, CNI plugins 1.9.1, and crictl 1.37.0. CRI-O 1.36.5 with crun 1.29.1 is also available, paired with Kubernetes 1.36.4 until CRI-O publishes its 1.37 series. Ansible is pinned to 14.3.1 and ansible-core 2.21.3. See the release inventory.

Existing clusters must follow Kubernetes' sequential minor upgrade policy. symplegma-upgrade.yml drains each node, upgrades control planes before worker kubelets, waits for readiness, then uncordons. A failed upgrade leaves the node cordoned. This is not a direct upgrade path from the former 1.24 defaults.

Documentation

Documentation is generated using mkdocs and the sources are located in the docs/ directory.

It is available online at particuleio.github.io/symplegma.

Roles

• symplegma-os_bootstrap: Configure the hosts OS to support Vanilla Kubernetes
• symplegma-kubernetes_hosts: Bootstrap Kubernetes on Linux hosts
• symplegma-kubeadm: Bootstrap the Kubernetes Cluster using kubeadm
• symplegma-containerd: Install the containerd CRI
• symplegma-crio: Install the cri-o CRI
• symplegma-cni: Boostrap the hosts to install the CNI
• symplegma-flannel: Bootstrap and install the Flannel CNI

Roadmap

• Support cilium as network plugin
• Support Kata container on QEMU and Firecracker
• Support bootstrapping GitOps

Contributing

Each role is hosted in a separate repository in particuleio. requirements.yml pins their published releases. scripts/install-roles.py installs and verifies those revisions; local clones remain editable under roles/. See maintenance and validation.

License