taloscluster

taloscluster provisions and manages Talos Linux Kubernetes clusters on OpenStack or Proxmox. Describe the cluster in cluster.yaml, keep credentials in secrets.yaml, and run taloscluster converge to create, scale, or upgrade it.

Resources are discovered by name and ownership tags, without a separate infrastructure state file. Optional plugins register the cluster with Rancher or ArgoCD.

Documentation · Quickstart · Command reference

Install

Install uv and make talosctl and kubectl available on PATH, then:

uv tool install git+https://github.com/ncsa/taloscluster

For optional Rancher and ArgoCD plugins, install the all extra:

uv tool install "taloscluster[all] @ git+https://github.com/ncsa/taloscluster"

See Installation for updating, running without installing, and development setup.

Get started

Prepare your provider credentials and node access using the Quickstart, then:

taloscluster init --openstack -C mycluster mycluster  # or --proxmox
cd mycluster
vi cluster.yaml secrets.yaml
taloscluster plan
taloscluster converge
taloscluster status

Edit the generated templates for your environment before converging. Back up talossecrets.yaml after the first converge; it holds the cluster’s cryptographic identity.

Documentation

• Usage: scaling, upgrades, access changes, and teardown.
• Commands: subcommands, options, examples, and exit status.
• Configuration: every cluster and secrets setting.
• Proxmox setup: permissions, networking, and managed SDN.
• OpenStack setup: application credentials, services and quotas, networking, and access.
• Plugins: Rancher, ArgoCD, and writing a plugin.
• Troubleshooting: common problems and diagnostic steps.

Development

Install the working tree in editable mode:

uv sync --extra dev --extra all --editable

Or install it as an editable tool with all plugins:

uv tool install --editable ".[all]"
uv sync --extra dev

The uv run commands below use the project environment, which the tool install leaves without development dependencies, so run uv sync --extra dev first. Then run the tests and local docs:

uv run pytest
uv run mkdocs serve

See development installation for running the working tree with plugins, CHANGELOG.md for release history, and todo.md for outstanding work.