# rhastie/nmos-kubernetes architecture

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

- Interactive diagram: https://gitdiagram.com/rhastie/nmos-kubernetes
- Repository: https://github.com/rhastie/nmos-kubernetes

## Overview

##### Project Type & Purpose
- This is an “infrastructure-as-code” Kubernetes deployment project.
- It sets up a local kind cluster with MetalLB, CoreDNS extended by a custom DNS‐SD plugin, the Gateway API (via Istio), and two NMOS C++ services (registry & node) exposed for service discovery and testing.

##### File Structure Analysis
- Top level assets are all YAML or text files—no code directories.
- You see:
- kind.yaml, node.yaml, registry.yaml – kind cluster config and Kubernetes resource manifests for the NMOS services
- coredns-config.yaml – CoreDNS plugin configuration to forward DNS queries to the custom plugin
- dns-values-*.yml, values.yaml – Helm values for installing k8s_gateway and MetalLB
- svc-test.yaml – likely a Service manifest for testing connectivity
- README shows a sequential Helm/Kubectl deployment of:
- MetalLB (L2 load-balancer)
- Gateway API CRDs
- k8s_gateway (custom Gateway API controller / DNS plugin)
- CoreDNS plugin update
- Istio control plane & ingress gateway
- NMOS registry & node deployments

##### Key Insights from README
- Uses kind (Kubernetes in Docker) as the test cluster environment.
- MetalLB provides external LoadBalancer IPs in the kind cluster.
- Gateway API (HTTPRoute, TCPRoute) is enabled via upstream CRDs and Istio’s Gateway controller.
- A CoreDNS plugin is loaded to handle DNS-SD (_nmos-register._tcp) queries and forward them to the k8s_gateway service.
- The NMOS C++ registry runs on HTTP port 8010 (NodePort) and a WebSocket query port 8011.
- NMOS Node service is similarly deployed.

##### Main Components
a. Kubernetes Cluster (kind)
- Control Plane (API Server, Scheduler, etcd)
- Worker Node(s)
b. MetalLB (L2 LoadBalancer)
- Provides external IPs to Services of type LoadBalancer
c. CoreDNS + DNS-SD Plugin
- CoreDNS deployment (built-in Kubernetes DNS)
- Custom plugin endpoint (local pod)
d. k8s_gateway Controller
- Installed via Helm (listens for Gateway API CRDs: Gateway, HTTPRoute, TCPRoute)
e. Istio Service Mesh
- istio-base, istiod (control plane)
- istio-ingress (Envoy gateway)
f. NMOS Services
- nmos-cpp-registry Deployment + NodePort Service (port 8010/8011)
- nmos-cpp-node Deployment + (Service)
g. External Clients & mDNS Service Discovery
- dns-sd clients issuing _nmos-register._tcp queries
- curl/HTTP client hitting NodePort

##### Relationships & Data Flows
- DNS-SD client → CoreDNS (UDP 53) → plugin intercepts _nmos-register._tcp → forwards to k8s_gateway
- k8s_gateway (Gateway API controller) evaluates HTTPRoute/TCPRoute CRs → configures Istio ingress → routes to registry/node Services
- Kubernetes Services (LoadBalancer via MetalLB or NodePort) send traffic to Pods
- curl/HTTP client or WebSocket clients connect through NodePort to registry

##### Architectural Patterns & Principles
- Control Plane vs Data Plane separation (Kubernetes API vs actual packet forwarding)
- Declarative infrastructure (Helm + YAML + Kustomize)
- Plugin architecture (CoreDNS plugin for DNS-SD)
- Service mesh + Gateway API for protocol‐agnostic routing
- Microservices: registry & node as separate deployable units

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: External Clients
    subgraph "Layer 1: External Clients"
        DS["DNS-SD Client"]:::external
        CURL["curl/HTTP & WS Client"]:::external
    end

    %% Layer 2: DNS Layer
    subgraph "Layer 2: DNS Layer"
        CD["CoreDNS + DNS-SD Plugin"]:::dns
    end

    %% Layer 3: Gateway Layer
    subgraph "Layer 3: Gateway Layer"
        KG["k8s_gateway Controller"]:::routing
        IL["Istio IngressGateway"]:::routing
    end

    %% Layer 4: Application Layer
    subgraph "Layer 4: Application Layer"
        MB["MetalLB LoadBalancer"]:::app
        subgraph "NMOS Services"
            REG["nmos-cpp-registry Pods"]:::app
            RSVC["Registry Service\n(NodePort 8010/8011)"]:::app
            NODE["nmos-cpp-node Pods"]:::app
            NSVC["Node Service"]:::app
        end
    end

    %% Layer 5: Cluster Infrastructure
    subgraph "Layer 5: Cluster Infrastructure"
        KP["K8s API Server & Control Plane"]:::infra
        KN["kind Worker Nodes"]:::infra
    end

    %% Connections
    DS -->|"UDP 53 mDNS PTR"| CD
    CD -->|"forwards _nmos-register._tcp"| KG
    KG -->|"configures Gateway & Route"| IL
    CURL -->|"HTTP/WS 8010/8011"| RSVC
    IL -->|"routes traffic"| RSVC
    IL -->|"routes traffic"| NSVC
    MB -->|"LoadBalancer IPs"| RSVC
    MB -->|"LoadBalancer IPs"| NSVC
    RSVC -->|"pods"| REG
    NSVC -->|"pods"| NODE
    KP -->|"schedules pods"| REG
    KP -->|"schedules pods"| NODE
    KP -->|"schedules pods"| CD
    KP -->|"schedules pods"| KG
    KP -->|"schedules pods"| IL
    KN -->|"runs pods"| REG
    KN -->|"runs pods"| NODE
    KN -->|"runs pods"| CD
    KN -->|"runs pods"| KG
    KN -->|"runs pods"| IL

    %% Click Events
    click KP "https://github.com/rhastie/nmos-kubernetes/blob/main/kind.yaml"
    click REG "https://github.com/rhastie/nmos-kubernetes/blob/main/registry.yaml"
    click RSVC "https://github.com/rhastie/nmos-kubernetes/blob/main/registry.yaml"
    click NODE "https://github.com/rhastie/nmos-kubernetes/blob/main/node.yaml"
    click NSVC "https://github.com/rhastie/nmos-kubernetes/blob/main/node.yaml"
    click CD "https://github.com/rhastie/nmos-kubernetes/blob/main/coredns-config.yaml"
    click KG "https://github.com/rhastie/nmos-kubernetes/blob/main/dns-values-http.yml"
    click KG "https://github.com/rhastie/nmos-kubernetes/blob/main/dns-values-tcp.yml"
    click MB "https://github.com/rhastie/nmos-kubernetes/blob/main/values.yaml"
    click CURL "https://github.com/rhastie/nmos-kubernetes/blob/main/svc-test.yaml"
    click DS "https://github.com/rhastie/nmos-kubernetes/blob/main/NMOS DNS Settings.txt"

    %% Styles
    classDef external fill:#d3bfff,stroke:#8b5cf6,stroke-width:2px
    classDef dns fill:#bfdbfe,stroke:#3b82f6,stroke-width:2px
    classDef routing fill:#bbf7d0,stroke:#22c55e,stroke-width:2px
    classDef app fill:#fed7aa,stroke:#fb923c,stroke-width:2px
    classDef infra fill:#e5e7eb,stroke:#6b7280,stroke-width:2px
```
