# mysticrenji/home-assistant-on-kubernetes architecture

> Architecture diagram of the GitHub repository mysticrenji/home-assistant-on-kubernetes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mysticrenji/home-assistant-on-kubernetes
- Repository: https://github.com/mysticrenji/home-assistant-on-kubernetes

## Overview

##### Project type and purpose
- This is an infrastructure‐as‐code repository that provisions and runs a home‐automation full-stack system on a single-node K3s (lightweight Kubernetes) cluster, hosted on an ARM64 Nvidia Jetson Nano.
- Purpose: Deploy Home Assistant, BLE (Bluez) and Zigbee device adapters, a Cloudflare tunnel, networking components (MetalLB, Ingress‐Nginx), certificate management, and auxiliary services (Ansible-Semaphore, Plex) in containers.

##### File structure
- Top‐level:
- .github/ – CI workflows (build, test, renovate)
- home-automation/ – k8s manifests for core Home-Assistant, BLE service Dockerfile, configuration yamls (Deployment, ConfigMap, PVC, Ingress)
- sub-components/ – reusable k8s sub-charts/manifests for cert-manager, MetalLB, ingress-nginx, cloudflare-daemon, ansible-semaphore, kube-plex
- tests/ – sanity tests (nginx.yaml)
- Patterns:
- Microservices: each adapter and service runs in its own pod
- Kubernetes primitives: Deployments, ConfigMaps, PVCs, Ingress, custom namespaces
- Container builds (Dockerfile + app.js) for the BLE adapter

##### README for additional insights
- K3s runs with containerd on Jetson Nano (ARM64)
- Bluetooth Low Energy sensor integration via a custom Bluez service (app.js)
- Zigbee coordinator likewise runs in its own pod
- Home Assistant pod uses the official container image
- Cloudflare Daemon pod exposes services securely to the public Internet
- MetalLB handles bare-metal LoadBalancer IP assignment
- cert-manager issues TLS certificates via Helm
- Tailscale VPN stitches multiple ARM64 worker nodes into the cluster

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Physical Host Layer
    subgraph "Physical Host: Jetson Nano" 
        direction TB
        USB1["USB BLE Dongle"]:::hardware
        USB2["USB Zigbee Dongle"]:::hardware
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        BLE_Sensor["BLE Sensor"]:::external
        Zigbee_Sensor["Zigbee Sensor"]:::external
        User["User (Web UI)"]:::external
        Internet["Internet"]:::external
        Tailscale["Tailscale VPN"]:::external
        CloudflareDNS["Cloudflare DNS"]:::external
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster" 
        direction TB

        subgraph "Control Plane & Agents"
            direction TB
            APIServer["K3s API Server"]:::control
            Agent["K3s Agent"]:::control
        end

        subgraph "Cluster Services"
            direction TB
            Ingress_NGINX["Ingress-NGINX Controller"]:::network
            MetalLB["MetalLB Speaker"]:::network
            CertManager["cert-manager"]:::security
            Cloudflare["Cloudflare Tunnel Daemon"]:::security
        end

        subgraph "Workload Pods"
            direction TB
            HA_Pod["home-assistant Pod"]:::compute
            BLE_Adapter["bluez-BLE Adapter Pod"]:::compute
            Zigbee_Pod["zigbee-coordinator Pod"]:::compute
            Semaphore["Ansible-Semaphore Pod"]:::compute
            Plex["kube-plex Pod"]:::compute
        end

        subgraph "Storage"
            direction TB
            PVCs["PersistentVolumeClaims"]:::storage
        end
    end

    %% Connections: Sensors to Adapters
    BLE_Sensor --> USB1
    USB1 --> BLE_Adapter
    Zigbee_Sensor --> USB2
    USB2 --> Zigbee_Pod

    %% Adapters to Home Assistant
    BLE_Adapter -->|"BLE Data"| HA_Pod
    Zigbee_Pod -->|"Zigbee Data"| HA_Pod

    %% Home Assistant UI Exposure
    HA_Pod -->|"HTTP(S)"| Ingress_NGINX
    Ingress_NGINX --> MetalLB
    MetalLB --> Cloudflare
    Cloudflare -->|"Tunnel"| Internet
    Cloudflare --> CloudflareDNS
    User --> CloudflareDNS
    User -->|"Access via DNS"| Internet

    %% Control Plane Communication
    APIServer <--> Agent
    Agent -->|"joins cluster over"| Tailscale
    APIServer -->|"provisions certs"| CertManager

    %% Auxiliary Services
    APIServer --> Semaphore
    APIServer --> Plex
    PVCs --> HA_Pod
    PVCs --> Semaphore
    PVCs --> Plex

    %% Tests
    Tests["Ingress Validation Tests"]:::test
    Ingress_NGINX --> Tests

    %% Click Events
    click HA_Pod "https://github.com/mysticrenji/home-assistant-on-kubernetes/blob/main/home-automation/deployment.yaml"
    click BLE_Adapter "https://github.com/mysticrenji/home-assistant-on-kubernetes/tree/main/home-automation/ble/Dockerfile"
    click Cloudflare "https://github.com/mysticrenji/home-assistant-on-kubernetes/blob/main/sub-components/cloudflare-daemon/deployment.yaml"
    click Ingress_NGINX "https://github.com/mysticrenji/home-assistant-on-kubernetes/blob/main/sub-components/ingress-nginx/values.yaml"
    click MetalLB "https://github.com/mysticrenji/home-assistant-on-kubernetes/blob/main/sub-components/metal-lb/config.yaml"
    click CertManager "https://github.com/mysticrenji/home-assistant-on-kubernetes/blob/main/sub-components/cert-manager/cluster-issuer.yaml"
    click Semaphore "https://github.com/mysticrenji/home-assistant-on-kubernetes/blob/main/sub-components/ansible-sempahore/semaphore-deployment.yaml"
    click Plex "https://github.com/mysticrenji/home-assistant-on-kubernetes/blob/main/sub-components/kube-plex/deployment.yaml"
    click Tests "https://github.com/mysticrenji/home-assistant-on-kubernetes/blob/main/tests/nginx.yaml"

    %% Styles
    classDef hardware fill:#FFD700,stroke:#333,stroke-width:1px
    classDef external fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef control fill:#FFA500,stroke:#333,stroke-width:1px
    classDef network fill:#98FB98,stroke:#333,stroke-width:1px
    classDef security fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef compute fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef storage fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef test fill:#FF69B4,stroke:#333,stroke-width:1px
```
