# vitobotta/hetzner-k3s architecture

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

- Interactive diagram: https://gitdiagram.com/vitobotta/hetzner-k3s
- Repository: https://github.com/vitobotta/hetzner-k3s

## Overview

##### Project Type and Purpose
- This project is a CLI tool for quickly setting up and managing production-ready Kubernetes clusters on Hetzner Cloud using k3s.
- The README emphasizes that it handles the deployment of infrastructure (instances, networks, load balancers, firewalls, etc.) as well as the installation of essential Kubernetes components (Hetzner Cloud Controller Manager, Hetzner CSI Driver, Cluster Autoscaler, and Rancher System Upgrade Controller).

##### File Structure to Pinpoint Main Components
- CLI Entry Point and Cluster Management:
- Files in the top-level src/ directory (e.g., src/hetzner-k3s.cr) suggest the main executable.
- The src/cluster directory (with create.cr, delete.cr, upgrade.cr) handles lifecycle management for clusters.
- Configuration Handling:
- The src/configuration folder, with multiple configuration modules (including settings, manifests, and networking), indicates robust support for specifying cluster parameters.
- Hetzner API Integration:
- The src/hetzner folder contains multiple directories and files managing interaction with Hetzner resources such as instances, firewalls, load balancers, networks, placement groups, and SSH keys.
- This module encapsulates the integration with the Hetzner Cloud API.
- Kubernetes Deployment and Resource Management:
- The src/kubernetes folder contains files for the installer, resource definitions (deployments, pods, containers, volumes), as well as software components like the cloud controller manager and CSI driver.
- Utility and Scripting Support:
- The src/util directory supports common tasks like prefixed I/O or running shell commands.
- Templates and scripts (cloud_init.yaml and install/upgrade scripts) help automate node initialization and upgrades.
- Testing and Container Infrastructure:
- The e2e-tests directory includes end-to-end testing scripts and configuration files.
- Dockerfiles, docker-compose files, and .devcontainer.json reveal support for containerized development or testing.

##### Key Components and Their Interactions
- User/CLI Interface:
- The tool is run from the command line, and user input triggers commands like create, delete, or upgrade.
- Cluster Lifecycle Manager:
- This component (represented via src/cluster) orchestrates infrastructure provisioning, modification, or teardown.
- Configuration Loader:
- Reads settings and customizations from various configuration files (src/configuration and its submodules) to drive cluster deployment.
- Hetzner Cloud Integration Layer:
- Interfaces with the Hetzner API for managing instances, networks, load balancers, firewalls, and other cloud resources.
- Each resource type (instance, firewall, network, ssh_key, etc.) is encapsulated in its specific module.
- Kubernetes Installer and Resource Manager:
- Manages the installation of k3s on provisioned nodes, deploys Kubernetes resources (via src/kubernetes/resources), and installs essential add-ons.
- Automation, Utility, and Scripting:
- Utility modules act as support for command execution and common routines.
- External Dependencies:
- The integration with external components like the Hetzner Cloud Controller Manager, CSI Driver, and Cluster Autoscaler should be noted.

##### Architectural Patterns and Design Principles
- Modular Design:
- The directory structure shows clear separation of concerns: cluster management, configuration, Hetzner API integration, Kubernetes resource handling, and utilities.
- Extensibility:
- A plugin-like approach is used in the configuration and Hetzner modules, allowing for easy extension and customization.
- Automation:
- Heavy automation of the provisioning and deployment process, driven by configuration files and scripts, is central in this design.

- Use clear labels for each block/component (e.g., “CLI/Entry Point”, “Cluster Manager”, “Hetzner API Integration”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Control Layer"
        CLI["CLI/Entry Point"]:::control
        ClusterManager["Cluster Lifecycle Manager"]:::control
        ConfigLoader["Configuration Loader"]:::control
    end

    subgraph "Infrastructure Provisioning Layer"
        HetznerAPI["Hetzner Cloud API Integration"]:::provisioning
        UtilityModules["Utility Modules"]:::provisioning
    end

    subgraph "Deployment Layer"
        KubernetesInstaller["Kubernetes Installer & Resource Manager"]:::deployment
        ExternalIntegrations["External Integrations"]:::external
    end

    subgraph "Testing/Development Layer"
        Testing["Testing and Container Support"]:::testing
    end

    CLI -->|"triggers"| ClusterManager
    ClusterManager -->|"readsConfiguration"| ConfigLoader
    ClusterManager -->|"provisionsInfra"| HetznerAPI
    HetznerAPI -->|"usesUtilities"| UtilityModules
    ClusterManager -->|"deploysK8s"| KubernetesInstaller
    KubernetesInstaller -->|"integratesExternal"| ExternalIntegrations
    ConfigLoader -->|"configuresDeployment"| KubernetesInstaller
    ConfigLoader -->|"configuresInfra"| HetznerAPI

    click CLI "https://github.com/vitobotta/hetzner-k3s/blob/main/src/hetzner-k3s.cr"
    click ClusterManager "https://github.com/vitobotta/hetzner-k3s/tree/main/src/cluster"
    click ConfigLoader "https://github.com/vitobotta/hetzner-k3s/tree/main/src/configuration"
    click HetznerAPI "https://github.com/vitobotta/hetzner-k3s/tree/main/src/hetzner"
    click KubernetesInstaller "https://github.com/vitobotta/hetzner-k3s/tree/main/src/kubernetes"
    click UtilityModules "https://github.com/vitobotta/hetzner-k3s/tree/main/src/util"
    click Testing "https://github.com/vitobotta/hetzner-k3s/tree/main/e2e-tests"

    classDef control fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef provisioning fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef deployment fill:#FFCCBC,stroke:#333,stroke-width:2px;
    classDef external fill:#FFF9C4,stroke:#333,stroke-width:2px;
    classDef testing fill:#E1BEE7,stroke:#333,stroke-width:2px;
```
