How dhermes/tailsk8s works
Project Type and Purpose
• This is a CLI-driven orchestration tool (tailsk8s) written in Go.
• It automates the provisioning and configuration of a bare-metal Kubernetes cluster using Tailscale as the CNI (overlay network).
• It also provides subcommands to “advertise”, “authorize”, and “withdraw” machines from a Tailscale tailnet.
• The repository includes:
• Bash scripts (_bin/) for bootstrapping SSH and Kubernetes via kubeadm
• YAML templates (_templates/) for control-plane and worker join configs
• Go code (cmd/, pkg/) implementing the CLI and Tailscale API integrations
• Tutorial Markdown steps for a guided lab
High-Level File Structure Analysis
• Top-level labs (01-15) are purely documentation for end-users.
• _bin/ contains helper scripts and vendored Tailscale binaries for provisioning and tearing down clusters.
• _templates/ holds kubeadm manifest YAMLs for init/join configurations and a sample HTTPBin manifest.
• cmd/ defines three Go binaries:
• tailscale-advertise
• tailscale-authorize
• tailscale-withdraw
• pkg/ is the core Go library:
• pkg/cli – shared CLI parsing and output
• pkg/tailscale/cloud – interfaces with Tailscale’s control-plane API
• pkg/tailscale/local – local host interactions (if any)
• pkg/tailscale/command/* – business logic for each subcommand
• go-tools/ contains development helpers, and Makefile orchestrates builds.
Relevant README Insights
• The project’s goal is “Bare Metal Kubernetes with Tailscale.”
• It leverages kubeadm for cluster bootstrap, plus Tailscale CNI for pod-to-pod networking.
• It provides an end-to-end lab sequence.
Main Components
a. Developer Workstation
• Runs the Go CLI (tailscale-advertise, tailscale-authorize, tailscale-withdraw).
• Invokes Bash scripts in _bin/, passing in YAML from _templates/.
• Relies on SSH keys (prepared via docs) to connect to target machines.
b. Tailscale Control Plane (SaaS)
• Exposes REST/GRPC API endpoints (pkg/tailscale/cloud).
• Manages tailnets, devices, routes.
c. Bare-Metal (or Cloud VM) Nodes
• Control-Plane Node(s): bootstrapped by kubeadm init (_templates/kubeadm-init-config.yaml).
• Worker Node(s): joined via kubeadm join (_templates/kubeadm-worker-join-config.yaml).
• Load Balancer Node: optional provision script _bin/k8s-load-balancer-proxy.sh.
d. Kubernetes Cluster
• Pods and services communicate over Tailscale CNI (configured in step 09).
• HTTPBin sample workload (from _templates/httpbin.manifest.yaml) as proof of concept.
e. External Cloud VMs (AWS/GCP)
• Instances brought into cluster via 13-add-vm-aws.md, 14-add-vm-gcp.md.
f. Local Tools
• Makefile – orchestrates static binary builds (go build).
• go-tools/dev.go – developer helper tasks.
Component Relationships & Data Flows
1. Developer Workstation → SSH → Bare-Metal Nodes
• Executes Bash bootstrap scripts (_bin/*).
• Installs Kubernetes packages, Tailscale binaries.
2. Developer Workstation → Tailscale API
• Calls tailscale-advertise to register node in tailnet.
• Calls tailscale-authorize to approve device.
3. Bare-Metal Nodes ↔ Tailscale Network
• After authorization, nodes peer into the tailnet.
• Use Tailscale CNI for Kubernetes pod traffic routing.
4. Bare-Metal Nodes → Kubernetes API Server
• kubeadm init sets up control plane.
• Workers join and register to control plane.
5. Developer Workstation → Kubernetes API
• Uses kubectl or scripts for smoke test (HTTPBin service).
Architectural Patterns & Design Principles
• Separation of concerns:
• CLI layer (cmd/), application logic (pkg/tailscale/command), API integration (pkg/tailscale/cloud), templates, and scripts are clearly delineated.
• Infrastructure as Code:
• YAML templates + idempotent scripts encapsulate cluster configuration.
• Micro-service style CLI commands:
• Three single-purpose subcommands (advertise, authorize, withdraw).
• Modular Go packages for reusable API and CLI context.
Final Advice
• Be exhaustive but clear: don’t omit any template or script that directly affects cluster bootstrapping.
• Dual-path orchestration: SSH provisioning vs. Tailscale API signaling.
• How CNI config (09-tailscale-cni.md) changes pod networking to go over the tailnet.