architechture.md

Architecture Overview

This document describes the architecture of the Kubernetes Kind cluster setup and its components.

Cluster Architecture

Node Topology

The cluster consists of 6 nodes:

┌─────────────────────────────────────────────────────────┐
│                    Control Plane                        │
│                  (1 node)                               │
│              - API Server                                │
│              - etcd                                      │
│              - Controller Manager                        │
│              - Scheduler                                 │
└─────────────────────────────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
┌───────▼──────┐  ┌───────▼──────┐  ┌───────▼──────┐
│  Infra Node  │  │   App Node   │  │ Database     │
│  (1 node)    │  │  (1 node)    │  │ Nodes        │
│              │  │              │  │ (3 nodes)    │
│ - Monitoring │  │ - Application│  │ - PostgreSQL │
│ - Logging    │  │   Workloads  │  │   Clusters   │
└──────────────┘  └──────────────┘  └──────────────┘

Node Roles and Labels

Node Type	Count	Labels	Purpose
Control Plane	1	tier: master	Cluster management
Infrastructure	1	tier: infra, node-role.kubernetes.io/infra	Monitoring, logging
Application	1	tier: app, node-role.kubernetes.io/app	Application workloads
Database	3	tier: database, node-role.kubernetes.io/postgres	PostgreSQL clusters

Networking Architecture

Cilium CNI

┌─────────────────────────────────────────────────────────┐
│                    Cilium CNI                            │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ Native       │  │ Gateway API  │  │ LoadBalancer  │ │
│  │ Routing      │  │              │  │ (L2 Announce) │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ WireGuard    │  │ Hubble       │  │ XDP          │ │
│  │ Encryption   │  │ Observability │  │ Acceleration │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────┘

Key Features:

• Native Routing: Direct pod-to-pod communication without overlay
• kube-proxy Replacement: BPF-based service handling
• L2 Announcements: LoadBalancer IP assignment without BGP
• Gateway API: Advanced ingress/egress routing
• WireGuard Encryption: Transparent pod-to-pod encryption
• Hubble: Network observability and security

Network CIDRs

• Pod Subnet: 10.244.0.0/16
• Service Subnet: 10.96.0.0/12 (default)
• LoadBalancer Range: 192.168.250.0/24 (configurable)

Storage Architecture

Storage Classes

┌─────────────────────────────────────────────────────────┐
│              Storage Provisioning                       │
│                                                          │
│  ┌──────────────────┐      ┌──────────────────┐         │
│  │ Static PV        │      │ Dynamic PV      │         │
│  │ (NFS Manual)     │      │ (NFS CSI)       │         │
│  └──────────────────┘      └──────────────────┘         │
│           │                        │                    │
│           └──────────┬─────────────┘                    │
│                      │                                  │
│              ┌───────▼───────┐                         │
│              │  NFS Server   │                         │
│              │  (Host)       │                         │
│              └───────────────┘                         │
└─────────────────────────────────────────────────────────┘

NFS Shares

• /kind/_dynamic: Dynamic provisioning via CSI
• /kind/grafana: Grafana persistent storage
• /kind/prometheus: Prometheus persistent storage
• /kind/postgres: PostgreSQL cluster storage

Local Storage

Each node has local storage mounted at:

• /srv/kind/multinode-cni/local/infra-node-1
• /srv/kind/multinode-cni/local/app-node-1
• /srv/kind/multinode-cni/local/pg-node-{1,2,3}

Monitoring Architecture

┌─────────────────────────────────────────────────────────┐
│              Monitoring Stack                           │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ Prometheus   │  │  Grafana     │  │  Hubble      │ │
│  │              │  │              │  │              │ │
│  │ - Metrics    │  │ - Dashboards │  │ - Network    │ │
│  │ - Scraping   │  │ - Alerts     │  │   Flow       │ │
│  │ - Storage    │  │ - Viz        │  │   Security   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│         │                  │                  │         │
│         └──────────────────┼──────────────────┘         │
│                            │                            │
│                    ┌───────▼───────┐                    │
│                    │  Kubernetes   │                    │
│                    │  Resources    │                    │
│                    └───────────────┘                    │
└─────────────────────────────────────────────────────────┘

Database Architecture

CloudNativePG Cluster

┌─────────────────────────────────────────────────────────┐
│         PostgreSQL Cluster (CloudNativePG)              │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ Primary      │  │  Replica 1   │  │  Replica 2   │ │
│  │ (Read/Write) │  │  (Read Only) │  │  (Read Only) │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘ │
│         │                 │                 │          │
│         └─────────────────┼─────────────────┘          │
│                           │                            │
│                  ┌────────▼────────┐                   │
│                  │  NFS Storage    │                   │
│                  │  /kind/postgres │                   │
│                  └─────────────────┘                   │
└─────────────────────────────────────────────────────────┘

Features:

• High availability with automatic failover
• Streaming replication
• Backup and restore
• Point-in-time recovery

CI/CD Architecture

Tekton Pipeline

┌─────────────────────────────────────────────────────────┐
│              Tekton CI/CD                               │
│                                                          │
│  ┌──────────────┐                                       │
│  │ EventListener│                                       │
│  │ (Webhook)    │                                       │
│  └──────┬───────┘                                       │
│         │                                                │
│  ┌──────▼───────┐                                       │
│  │ Trigger      │                                       │
│  │ (Binding +   │                                       │
│  │  Template)   │                                       │
│  └──────┬───────┘                                       │
│         │                                                │
│  ┌──────▼───────┐                                       │
│  │ Pipeline     │                                       │
│  │              │                                       │
│  │  ┌────────┐  │                                       │
│  │  │ Task 1 │  │                                       │
│  │  └───┬────┘  │                                       │
│  │      │        │                                       │
│  │  ┌───▼────┐  │                                       │
│  │  │ Task 2 │  │                                       │
│  │  └────────┘  │                                       │
│  └──────────────┘                                       │
└─────────────────────────────────────────────────────────┘

Security Architecture

Network Security

• WireGuard Encryption: All pod-to-pod traffic encrypted
• Network Policies: Cilium-based policies (can be configured)
• Service Mesh: Cilium service mesh capabilities

Access Control

• RBAC: Kubernetes Role-Based Access Control
• Service Accounts: Per-namespace service accounts
• Secrets Management: Kubernetes secrets (consider external solutions for production)

Component Interaction Flow

Service Request Flow

Client Request
    │
    ▼
┌─────────────────┐
│  Gateway API    │  (Cilium Gateway)
└────────┬────────┘
         │
    ┌────▼────┐
    │ HTTPRoute│
    └────┬────┘
         │
    ┌────▼────┐
    │ Service │  (LoadBalancer/ClusterIP)
    └────┬────┘
         │
    ┌────▼────┐
    │  Pods   │
    └─────────┘

Data Flow (Monitoring)

Application Pods
    │
    ▼
┌─────────────┐
│  Metrics    │
└──────┬──────┘
       │
┌──────▼──────┐
│ Prometheus  │  (Scraping)
└──────┬──────┘
       │
┌──────▼──────┐
│  Grafana    │  (Querying)
└─────────────┘

Resource Allocation

Default Resource Limits

The cluster is designed for development/testing. Production deployments should:

• Increase node resources
• Configure resource requests/limits
• Enable resource quotas
• Set up autoscaling

Storage Considerations

• NFS shares are on the host filesystem
• Consider performance for production workloads
• Monitor disk usage
• Implement backup strategies

High Availability

Current Setup

• Control Plane: Single node (not HA)
• Database: 3-node cluster (HA)
• Workloads: Can be distributed across nodes

Production Recommendations

• Use multiple control plane nodes
• Implement pod disruption budgets
• Configure horizontal pod autoscaling
• Set up cluster autoscaling (if supported)