# Kubernetes & Airflow HA 基礎架構設計說明

# 目錄
#### 1. 設計背景與目標
- 為何 Kubernetes 需要 HA
- 為何 Airflow 需要 HA
- 兩者在資料平台中的角色
- 設計目標

#### 2. 整體架構總覽
- 架構設計概念
- 核心元件與責任分層

#### 3. 平台入口HA設計
- Keepalived + HAProxy
- VIP 設計原則

#### 4. Kubernetes Control Plane HA設計
- API Server HA
- K8s Etcd 的角色與邊界

#### 5. Airflow on Kubernetes HA設計
- Airflow 元件角色
- 使用K8s的功能達到HA設計

#### 6. Metadata Database HA設計
- PostgreSQL + Patroni
- Patroni Etcd（DCS）

#### 7. 故障情境與自動切換流程
- Kubernetes Control Plane Failover
- 平台入口（VIP）Failover
- Metadata Database Failover
- Airflow 服務連續性

#### 8. 總結

---

## 1. 設計背景與目標
資料平台與自動化流程中，Kubernetes 與 Apache Airflow 分別扮演 「容器平台」與「工作流程中樞」的關鍵角色。
任一元件不可用，都可能導致整體平台服務中斷。

本文件之設計目標如下：
- **Kubernetes 平台高可用**  
  確保 Control Plane 具備容錯能力，避免單一 Master 失效導致平台不可控。
- **Airflow 服務高可用**  
  透過 Kubernetes 的調度與自我修復能力，確保工作流程服務不中斷。
- **狀態與資料層高可用**  
  針對 Airflow Metadata Database，設計具備自動 Failover 能力的資料庫架構。
- **消除單一故障點（SPOF）**  
  從流量入口、平台控制層到狀態儲存層，避免任何單點失效。
---
## 2. 整體架構總覽
本架構以 On-Premise 或 Private Cloud 環境下 **Kubernetes 與 Apache Airflow 的 HA** 為設計核心，
透過多層次的 HA 機制，確保平台在任一元件或節點失效時，仍可持續提供服務。

整體HA架構可分為四個層級：

- **平台入口層（Platform Ingress HA）**  
  使用 Keepalived + HAProxy 提供虛擬 IP（VIP）與流量入口HA。

- **容器平台層（Kubernetes HA）**  
  Kubernetes Control Plane 採用多 Master 架構，確保叢集控制能力不中斷。

- **工作流程層（Airflow on Kubernetes）**  
  Airflow 元件以 Pod 形式運行，透過 Kubernetes 調度與自我修復能力達成服務高可用。

- **狀態與資料層（Stateful Services HA）**  
  Metadata Database 採用 PostgreSQL + Patroni，並使用獨立 Etcd 作為分散式共識（DCS）。

```
┌─────────────────────────────────────────────────┐
│ Layer 1: 平台入口層 (Ingress HA)                  │
│   VIP + Keepalived + HAProxy                    │
│   → 消除流量入口單點故障                           │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ Layer 2: 容器平台層 (Kubernetes HA)               │
│   Multi-Master + K8s Etcd                       │
│   → 消除集群控制平面單點故障                        │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ Layer 3: 工作流程層 (Airflow on K8s)              │
│   Scheduler + API Server + Worker Pods         │
│   → 透過 K8s 實現服務自動恢復                       │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ Layer 4: 狀態與資料層 (Stateful Services HA)      │
│   PostgreSQL + Patroni + Patroni Etcd          │
│   → 資料庫自動 Failover                           │
└─────────────────────────────────────────────────┘
```

### **整體架構**
```mermaid
graph TB
    %% ===== 外部使用者 =====
    User[用戶 / 運維人員]

    %% ===== Layer 1: Ingress HA =====
    subgraph L1["Layer 1: 平台入口層"]
        VIP[VIP: 10.10.0.83]
        subgraph HAProxy_Cluster["HAProxy + Keepalived"]
            F01[doris-f01Keepalived + HAProxy]
            F02[doris-f02Keepalived + HAProxy]
            F03[doris-f03Keepalived + HAProxy]
        end
    end

    %% ===== Layer 2: K8s HA =====
    subgraph L2["Layer 2: 容器平台層"]
        subgraph K8s_Masters["Kubernetes Control Plane"]
            M1[Master 1API + Controller + Scheduler]
            M2[Master 2API + Controller + Scheduler]
            M3[Master 3API + Controller + Scheduler]
        end
        subgraph K8s_Etcd["K8s Etcd Cluster"]
            KE1[etcd:2379]
            KE2[etcd:2379]
            KE3[etcd:2379]
        end
    end

    %% ===== Layer 3: Airflow =====
    subgraph L3["Layer 3: 工作流程層"]
        subgraph Airflow["Airflow on Kubernetes"]
            AF_Web[Webserver Pod]
            AF_Sch[Scheduler Pod]
            AF_Wrk[Worker Pods]
        end
    end

    %% ===== Layer 4: Database HA =====
    subgraph L4["Layer 4: 狀態與資料層"]
        subgraph PG_Cluster["PostgreSQL + Patroni"]
            PG1[Primarydoris-f01]
            PG2[Replicadoris-f02]
            PG3[Replicadoris-f03]
        end
        subgraph Patroni_Etcd["Patroni Etcd (DCS)"]
            PE1[etcd:12379]
            PE2[etcd:12379]
            PE3[etcd:12379]
        end
    end

    %% ===== 連接關係 =====
    User --> VIP
    VIP --> F01 & F02 & F03
    F01 & F02 & F03 --> M1 & M2 & M3
    M1 & M2 & M3 --> KE1 & KE2 & KE3
    M1 & M2 & M3 --> Airflow
    Airflow --> PG_Cluster
    PG_Cluster -.-> Patroni_Etcd

    %% ===== 樣式 =====
    classDef layer1 fill:#e1f5ff,stroke:#01579b
    classDef layer2 fill:#f3e5f5,stroke:#4a148c
    classDef layer3 fill:#e8f5e9,stroke:#1b5e20
    classDef layer4 fill:#fff3e0,stroke:#e65100
    
    class L1 layer1
    class L2 layer2
    class L3 layer3
    class L4 layer4
```

---
## 3. 平台入口HA設計

**Keepalived + HAProxy**

設計原則
- VIP 為唯一入口
- 任一節點失效時，自動切換入口主機 
- 流量入口 HA 與後端服務角色解耦


**VRRP 選舉概念**
```mermaid
graph TD
    Client --> VIP
    VIP -->|Priority 100| doris-f01
    VIP -.->|Priority 90| doris-f02
    VIP -.->|Priority 80| doris-f03
```
- Keepalived 透過 VRRP 協定競選 Master
- 僅 Master 節點綁定 VIP
- Backup 節點持續監聽並待命

**流量轉發流程**
```mermaid
graph TD
    Client --> VIP
    VIP --> Keepalived
    Keepalived --> HAProxy
    HAProxy --> Backend
```
- HAProxy 在所有節點上運行
- 只有持有 VIP 的節點實際接收流量
- VIP 切換 ≠ 服務重啟

---
## 4. Kubernetes Control Plane HA

設計說明
- Kubernetes Control Plane 為整體平台基礎
- 使用 Kubernetes 內建 Etcd
- 與 Patroni Etcd 完全隔離

### **Kubernetes Control Plane HA架構**
```mermaid
graph TD
    %% ===== Client =====
    User[User / Operator]

    %% ===== K8s API VIP =====
    API_VIP(VIP: K8s API)
    User --> API_VIP

    %% ===== Kubernetes Control Plane HA =====
    subgraph CP["Kubernetes Control Plane HA"]
        direction TB

        %% --- API Servers ---
        subgraph APIS["API Servers"]
            API1[kube-apiserver]
            API2[kube-apiserver]
            API3[kube-apiserver]
        end

        %% --- Controllers & Scheduler ---
        subgraph CTRL["Controller & Scheduler"]
            CM1[kube-controller-manager]
            SCH1[kube-scheduler]
            CM2[kube-controller-manager]
            SCH2[kube-scheduler]
            CM3[kube-controller-manager]
            SCH3[kube-scheduler]
        end

        %% --- etcd State Backend ---
        subgraph ETCD["etcd Cluster (State Backend)"]
            KE1[etcd]
            KE2[etcd]
            KE3[etcd]
        end
    end

    %% ===== Connections =====
    API_VIP --> API1
    API_VIP --> API2
    API_VIP --> API3

    API1 --> KE1
    API2 --> KE2
    API3 --> KE3

    CM1 --> API1
    SCH1 --> API1

    CM2 --> API2
    SCH2 --> API2

    CM3 --> API3
    SCH3 --> API3
```

邊界原則
- Kubernetes Etcd：
  - 僅供 K8s 使用
  - Port：2379 / 2380
- Patroni Etcd：
  - 僅供 PostgreSQL HA 使用
  - Port：12379 / 12380
- 嚴禁共用 Etcd
---
## 5. Airflow on Kubernetes HA設計

| 元件 | 角色 | 運行方式 | HA 機制 |
|-----|------|---------|---------|
| **Webserver** | 提供 Web UI 與 REST API | Deployment (2 replicas) | K8s 自動重建 |
| **Scheduler** | 解析 DAG、產生 Task Instance | Deployment (2 replicas) | Leader Election |
| **Triggerer** | 處理 Deferrable Operator | Deployment (1-2 replicas) | K8s 自動重建 |
| **Worker** | 執行 Task | KubernetesExecutor: 動態 Pod<br>CeleryExecutor: StatefulSet | 短生命週期 |
---
## 6. Metadata Database HA設計

PostgreSQL + Patroni + Etcd

設計重點
- Metadata DB 為 Airflow 核心依賴
- 使用 Patroni 管理 PostgreSQL 角色
- Etcd 作為 DCS（Distributed Configuration Store）

### **Airflow Metadata Database HA架構**

```mermaid
graph TD
    User[User / Client]

    %% ===== 流量入口 =====
    VIP(VIP 10.10.0.83)
    User --> VIP

    subgraph ENTRY["Ingress HA (Keepalived + HAProxy)"]
        subgraph F01["doris-f01"]
            K1[Keepalived]
            H1[HAProxy]
        end
        subgraph F02["doris-f02"]
            K2[Keepalived]
            H2[HAProxy]
        end
        subgraph F03["doris-f03"]
            K3[Keepalived]
            H3[HAProxy]
        end
    end

    VIP --> K1 --> H1

    %% ===== Kubernetes =====
    subgraph K8S["Kubernetes Cluster"]
        API[K8s API Server]
        subgraph AIRFLOW["Airflow Components"]
            AF_API[Airflow API Server]
            AF_SCH[Airflow Scheduler]
            AF_WK[Airflow Workers Pods]
        end
    end

    H1 --> AF_API
    AF_SCH --> AF_WK

    %% ===== DB =====
    subgraph DB["PostgreSQL HA (Patroni)"]
        PG1[Primary]
        PG2[Replica]
        PG3[Replica]
    end

    %% ===== DCS =====
    subgraph DCS["Patroni Etcd (DCS)"]
        E1[Etcd f01]
        E2[Etcd f02]
        E3[Etcd f03]
    end

    AF_API --> DB
    AF_SCH --> DB

    PG1 --> PG2
    PG1 --> PG3

    PG1 -.-> DCS
    PG2 -.-> DCS
    PG3 -.-> DCS
```

---
## 7. 故障情境與自動切換流程

- Kubernetes Control Plane Failover
  - kube-apiserver 為無狀態服務，可由多個實例同時提供服務
  - 當單一 Master 節點失效時，其餘 Master 持續提供 API 能力
  - Controller Manager 與 Scheduler 透過 Leader Election 機制自動切換

- 平台入口（VIP）Failover
```mermaid
sequenceDiagram
    participant Client
    participant F01 as doris-f01
    participant F02 as doris-f02

    Client->>F01: 存取 VIP
    Note over F01: Keepalived 停止
    F02->>F02: 接手 VIP
    Client->>F02: 流量自動切換
```

- Metadata Database Failover
  - Patroni 偵測 Primary 不可用
  - Etcd 重新選舉 Leader
  - Replica 升級為新 Primary
  - Airflow 自動重新連線
- Airflow 服務連續性
  - Airflow Scheduler 與 API Server 為無狀態服務，可由 Kubernetes 自動重建
  - Worker Pod 為短生命週期任務執行單元，單一 Pod 失效不影響整體流程
  - Metadata Database 透過 Patroni 提供自動 Failover
  - 各層 HA 機制相互獨立，避免連鎖性故障
---

## 8. 總結

本架構透過多層HA設計，確保 Apache Airflow 及 Kubernetes 的運作：
- 可自動容錯
- 可長期穩定運行