AI-Guided Setup#

The fastest way to get a cluster running is to let Claude Code walk you through it interactively. The /bootstrap-cluster skill asks you a series of questions, configures all the files, generates secrets, runs the Ansible playbooks, and writes a credentials file — all in one conversation.

Prerequisites#

  • Claude Code installed (claude.ai/claude-code)

  • A devcontainer session open in this repository (see below)

  • Your target hardware ready (Turing Pi boards or Linux servers with Ubuntu 24.04)

If you haven’t forked and cloned the repository yet, do that first:

Fork and clone the repository#

  1. Fork the repository on GitHub: visit gilesknap/tpi-k3s-ansible and click Fork.

  2. Clone your fork:

git clone https://github.com/<your-username>/tpi-k3s-ansible.git
cd tpi-k3s-ansible

Note

You need your own fork because ArgoCD tracks your repository for GitOps. Changes you push to your fork are automatically deployed to your cluster.

The repo contains SealedSecret files encrypted for the original cluster — these won’t work on yours and can be safely ignored until you create your own during Set Up DNS, TLS & Cloudflare Tunnel setup.

Then open the devcontainer:

Open the devcontainer#

Open the repository in VS Code:

code .

When prompted, select “Reopen in Container” (or use Ctrl+Shift+P → Dev Containers: Reopen in Container).

The devcontainer provides Ansible (and its Python dependencies) out of the box. Cluster tools (kubectl, helm, kubeseal) are installed later by the tools role when you run the playbook. No additional installation is needed on your workstation.

Run the skill#

Open a Claude Code session inside the devcontainer and type:

/bootstrap-cluster

Claude will guide you through:

  1. Hardware inventory — Turing Pi slots and node types, or generic server hostnames

  2. Cluster personalisation — domain name, email, GitHub fork URL

  3. Optional features — NFS storage, OAuth, Cloudflare tunnel, Open Brain

  4. File configuration — edits hosts.yml, group_vars/all.yml, and kubernetes-services/values.yaml based on your answers

  5. SSH key setup — checks for an existing key or walks you through generating one

  6. Playbook execution — runs the Ansible playbook to flash nodes (Turing Pi) or configure servers, install K3s, and deploy ArgoCD

  7. Secret generation — creates the shared admin password, and optionally seals Open Brain (Supabase) credentials

  8. Credentials file — writes everything to /tmp/cluster-credentials.txt for safekeeping

The entire process takes 15–30 minutes depending on the number of nodes and network speed.

What happens next#

After the skill completes, your cluster is running with all core services managed by ArgoCD. The skill will print next steps, but here is a summary:

Prefer a manual setup?#

If you prefer to follow written steps rather than an interactive guide, use the hardware-specific tutorials instead: