# dhermes/tailsk8s architecture

> Architecture diagram of the GitHub repository dhermes/tailsk8s, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhermes/tailsk8s
- Repository: https://github.com/dhermes/tailsk8s

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation
    subgraph "Developer Workstation"
        direction TB
        AdvertiseCLI["tailscale-advertise\n(Go CLI)"]:::dev
        AuthorizeCLI["tailscale-authorize\n(Go CLI)"]:::dev
        WithdrawCLI["tailscale-withdraw\n(Go CLI)"]:::dev
        subgraph "Provisioning Scripts"
            direction TB
            BootstrapSSH["bootstrap-ssh-bare-metal.sh"]:::dev
            PrimaryInit["k8s-primary-init.sh"]:::dev
            CPJoin["k8s-control-plane-join.sh"]:::dev
            WorkerJoin["k8s-worker-join.sh"]:::dev
            LBProxy["k8s-load-balancer-proxy.sh"]:::dev
        end
        Makefile["Makefile"]:::dev
        GoTools["dev.go"]:::dev
    end

    %% Tailscale Control Plane
    subgraph "Tailscale Control Plane" 
        direction TB
        TSAPI["Tailscale API\n(HTTPS/JSON)"]:::ts
        TailnetMgmt["Tailnet Management"]:::ts
    end

    %% Infrastructure & Kubernetes Cluster
    subgraph "Infrastructure & Kubernetes Cluster"
        direction TB
        subgraph "Control Plane Node" 
            direction TB
            APIServer["Kubernetes API Server"]:::k8s
            InitTemplate["kubeadm-init-config.yaml"]:::k8s
        end
        subgraph "Worker Node(s)" 
            direction TB
            WorkerNode["Worker Node\n(kubeadm join)"]:::k8s
            WorkerTemplate["kubeadm-worker-join-config.yaml"]:::k8s
        end
        subgraph "Load Balancer Node"
            LBNode["Load Balancer\n(proxy)"]:::infra
        end
        subgraph "Cloud VM Nodes"
            direction TB
            AWSVM["AWS VM Node"]:::infra
            GCPVM["GCP VM Node"]:::infra
        end
        Httpbin["httpbin.manifest.yaml"]:::k8s
    end

    %% Relationships
    AdvertiseCLI -->|"calls"| TSAPI
    AuthorizeCLI -->|"calls"| TSAPI
    WithdrawCLI -->|"calls"| TSAPI
    AdvertiseCLI -->|invokes| BootstrapSSH
    AuthorizeCLI -->|invokes| BootstrapSSH
    WithdrawCLI -->|invokes| BootstrapSSH

    BootstrapSSH -->|SSH| InitTemplate
    BootstrapSSH -->|SSH| WorkerTemplate
    BootstrapSSH -->|SSH| LBNode

    Makefile -->|builds| AdvertiseCLI
    Makefile -->|builds| AuthorizeCLI
    Makefile -->|builds| WithdrawCLI
    GoTools -->|helper tasks| Makefile

    TSAPI -->|"manages"| TailnetMgmt
    TailnetMgmt -->|peer config| APIServer
    TailnetMgmt -->|peer config| WorkerNode

    APIServer -->|"schedules"| WorkerNode
    WorkerNode -->|"runs"| Httpbin

    AdvertiseCLI -->|SSH| APIServer
    AdvertiseCLI -->|SSH| WorkerNode

    %% Overlay network
    APIServer <-->|"Tailscale CNI"| WorkerNode
    AWSVM <-->|"optional peer"| APIServer
    GCPVM <-->|"optional peer"| APIServer

    %% Developer to Kubernetes API
    AdvertiseCLI -->|"kubectl"| APIServer

    %% Click Events
    click AdvertiseCLI "https://github.com/dhermes/tailsk8s/blob/main/cmd/tailscale-advertise/main.go"
    click AuthorizeCLI "https://github.com/dhermes/tailsk8s/blob/main/cmd/tailscale-authorize/main.go"
    click WithdrawCLI "https://github.com/dhermes/tailsk8s/blob/main/cmd/tailscale-withdraw/main.go"
    click BootstrapSSH "https://github.com/dhermes/tailsk8s/blob/main/_bin/bootstrap-ssh-bare-metal.sh"
    click PrimaryInit "https://github.com/dhermes/tailsk8s/blob/main/_bin/k8s-primary-init.sh"
    click CPJoin "https://github.com/dhermes/tailsk8s/blob/main/_bin/k8s-control-plane-join.sh"
    click WorkerJoin "https://github.com/dhermes/tailsk8s/blob/main/_bin/k8s-worker-join.sh"
    click LBProxy "https://github.com/dhermes/tailsk8s/blob/main/_bin/k8s-load-balancer-proxy.sh"
    click Makefile "https://github.com/dhermes/tailsk8s/tree/main/Makefile"
    click GoTools "https://github.com/dhermes/tailsk8s/blob/main/go-tools/dev.go"
    click ConfigGo "https://github.com/dhermes/tailsk8s/blob/main/pkg/tailscale/cloud/config.go"
    click ApiTypes "https://github.com/dhermes/tailsk8s/blob/main/pkg/tailscale/cloud/apitypes.go"
    click Devices "https://github.com/dhermes/tailsk8s/blob/main/pkg/tailscale/cloud/devices.go"
    click Routes "https://github.com/dhermes/tailsk8s/blob/main/pkg/tailscale/cloud/routes.go"
    click Tailnets "https://github.com/dhermes/tailsk8s/blob/main/pkg/tailscale/cloud/tailnets.go"
    click Remix "https://github.com/dhermes/tailsk8s/tree/main/pkg/tailscale/cloud/remix"
    click LocalDoc "https://github.com/dhermes/tailsk8s/blob/main/pkg/tailscale/local/doc.go"
    click AdvertiseLogic "https://github.com/dhermes/tailsk8s/blob/main/pkg/tailscale/command/advertise/advertise.go"
    click AuthorizeLogic "https://github.com/dhermes/tailsk8s/blob/main/pkg/tailscale/command/authorize/authorize.go"
    click WithdrawLogic "https://github.com/dhermes/tailsk8s/blob/main/pkg/tailscale/command/withdraw/withdraw.go"
    click CLIContext "https://github.com/dhermes/tailsk8s/blob/main/pkg/cli/context.go"
    click CLIPrint "https://github.com/dhermes/tailsk8s/blob/main/pkg/cli/print.go"
    click InitTemplate "https://github.com/dhermes/tailsk8s/blob/main/_templates/kubeadm-init-config.yaml"
    click CPJoinTemplate "https://github.com/dhermes/tailsk8s/blob/main/_templates/kubeadm-control-plane-join-config.yaml"
    click WorkerTemplate "https://github.com/dhermes/tailsk8s/blob/main/_templates/kubeadm-worker-join-config.yaml"
    click Httpbin "https://github.com/dhermes/tailsk8s/blob/main/_templates/httpbin.manifest.yaml"

    %% Styles
    classDef dev fill:#bbdefb,stroke:#000,stroke-width:1px
    classDef ts fill:#d1c4e9,stroke:#000,stroke-width:1px
    classDef infra fill:#e0e0e0,stroke:#000,stroke-width:1px
    classDef k8s fill:#ffe0b2,stroke:#000,stroke-width:1px
```
