Kubernetes多叢集管理與外部服務整合

# Prometheus Operator 自訂資源定義範例
# 這個組態定義了一個高可用的 Prometheus 叢集
# 包含副本數量、資源限制、持久化儲存以及服務監控選擇器
apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  # Prometheus 實例名稱
  # 這個名稱會用於生成相關的 StatefulSet 和 Service
  name: prometheus-production
  # 部署到 monitoring 命名空間
  # 集中管理所有監控相關資源
  namespace: monitoring
  labels:
    # 標籤用於識別這是生產環境的 Prometheus
    app: prometheus
    environment: production
spec:
  # 副本數量設為 2 以實現高可用
  # Prometheus 會自動處理資料複製
  replicas: 2
  # 服務帳戶用於 Prometheus 存取 Kubernetes API
  # 需要適當的 RBAC 權限來發現監控目標
  serviceAccountName: prometheus
  # 選擇要監控的 ServiceMonitor 資源
  # 使用標籤選擇器來篩選
  serviceMonitorSelector:
    matchLabels:
      # 只監控標記為 prometheus: enabled 的 ServiceMonitor
      prometheus: enabled
  # 選擇要監控的 PodMonitor 資源
  podMonitorSelector:
    matchLabels:
      prometheus: enabled
  # 資源請求與限制
  # 確保 Prometheus 有足夠的資源處理監控資料
  resources:
    requests:
      # 請求 2 個 CPU 核心
      cpu: "2"
      # 請求 4GB 記憶體
      memory: 4Gi
    limits:
      # 限制最多使用 4 個 CPU 核心
      cpu: "4"
      # 限制最多使用 8GB 記憶體
      memory: 8Gi
  # 持久化儲存組態
  # 確保 Prometheus 資料在 Pod 重啟後不會遺失
  storage:
    volumeClaimTemplate:
      spec:
        # 使用 SSD 儲存類別以獲得更好的 I/O 效能
        storageClassName: ssd-storage
        # 存取模式為單節點讀寫
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            # 請求 100GB 儲存空間
            storage: 100Gi
  # 資料保留期限
  # 保留 30 天的監控資料
  retention: 30d
  # 外部標籤會附加到所有指標
  # 用於在多叢集環境中識別資料來源
  externalLabels:
    cluster: production-cluster-01
    region: asia-east1

# Elasticsearch Operator 自訂資源定義範例
# 定義一個具有多種節點角色的 Elasticsearch 叢集
apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  # Elasticsearch 叢集名稱
  name: elasticsearch-production
  namespace: elastic-system
spec:
  # Elasticsearch 版本
  # Operator 會自動處理版本升級
  version: 8.11.0
  # 節點集合定義
  # 可以定義多個節點集合，每個有不同的角色和規格
  nodeSets:
    # 主節點集合
    # 負責叢集管理和元資料操作
    - name: master
      # 主節點數量
      # 建議使用奇數以避免腦裂問題
      count: 3
      config:
        # 節點角色設定
        # 主節點只負責叢集協調
        node.roles: ["master"]
        # 禁用機器學習功能以節省資源
        xpack.ml.enabled: false
      # Pod 模板用於自訂 Pod 規格
      podTemplate:
        spec:
          containers:
            - name: elasticsearch
              resources:
                requests:
                  # 主節點資源需求較低
                  cpu: "1"
                  memory: 2Gi
                limits:
                  cpu: "2"
                  memory: 4Gi
      # 持久化儲存組態
      volumeClaimTemplates:
        - metadata:
            name: elasticsearch-data
          spec:
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                # 主節點儲存需求較小
                storage: 10Gi
            storageClassName: ssd-storage
    # 資料節點集合
    # 負責資料儲存和搜尋操作
    - name: data
      # 資料節點數量
      count: 6
      config:
        # 資料節點角色
        node.roles: ["data", "ingest"]
        # 啟用資料分層儲存
        node.attr.data: hot
      podTemplate:
        spec:
          # 節點親和性設定
          # 確保資料節點分散到不同的可用區
          affinity:
            podAntiAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
                - labelSelector:
                    matchLabels:
                      elasticsearch.k8s.elastic.co/cluster-name: elasticsearch-production
                      elasticsearch.k8s.elastic.co/statefulset-name: elasticsearch-production-es-data
                  topologyKey: topology.kubernetes.io/zone
          containers:
            - name: elasticsearch
              resources:
                requests:
                  # 資料節點需要較多資源
                  cpu: "4"
                  memory: 16Gi
                limits:
                  cpu: "8"
                  memory: 32Gi
      volumeClaimTemplates:
        - metadata:
            name: elasticsearch-data
          spec:
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                # 資料節點需要大量儲存空間
                storage: 500Gi
            storageClassName: ssd-storage
  # HTTP 組態
  http:
    tls:
      # 啟用自簽憑證
      # Operator 會自動管理憑證生命週期
      selfSignedCertificate:
        disabled: false

# Flux GitRepository 組態範例
# 定義 Flux 要監控的 Git 儲存庫
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  # GitRepository 資源名稱
  name: infrastructure-repo
  # 部署到 flux-system 命名空間
  namespace: flux-system
spec:
  # 同步間隔
  # Flux 每分鐘檢查一次 Git 儲存庫的變更
  interval: 1m
  # Git 儲存庫 URL
  url: https://github.com/myorg/infrastructure
  # 要追蹤的分支
  ref:
    branch: main
  # 存取憑證
  # 參考包含 SSH 金鑰或存取令牌的 Secret
  secretRef:
    name: git-credentials
  # 忽略特定路徑
  # 避免不必要的同步觸發
  ignore: |
    # 忽略文件目錄
    /docs/
    # 忽略測試檔案
    /**/*_test.yaml
---
# Flux Kustomization 組態範例
# 定義如何將 Git 儲存庫中的組態套用到叢集
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  # Kustomization 資源名稱
  name: infrastructure
  namespace: flux-system
spec:
  # 同步間隔
  interval: 10m
  # 來源參考
  # 指向前面定義的 GitRepository
  sourceRef:
    kind: GitRepository
    name: infrastructure-repo
  # Git 儲存庫中的路徑
  # Flux 會套用這個目錄下的所有 Kubernetes 資源
  path: ./clusters/production
  # 啟用修剪功能
  # 當資源從 Git 移除時，也會從叢集中刪除
  prune: true
  # 健康檢查超時
  timeout: 5m
  # 啟用等待功能
  # 確保資源完全就緒後才繼續
  wait: true
  # 變數替換
  # 支援環境特定的組態
  postBuild:
    substitute:
      CLUSTER_NAME: production-cluster-01
      ENVIRONMENT: production
    substituteFrom:
      - kind: ConfigMap
        name: cluster-config

# ArgoCD Application 組態範例
# 定義一個由 ArgoCD 管理的應用程式
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  # 應用程式名稱
  name: microservice-platform
  # ArgoCD 應用程式必須部署在 argocd 命名空間
  namespace: argocd
  # 終結器確保應用程式刪除時相關資源也被清理
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  # 專案參考
  # 用於存取控制和資源限制
  project: production
  # 來源組態
  # 定義應用程式的 Git 儲存庫位置
  source:
    # Git 儲存庫 URL
    repoURL: https://github.com/myorg/microservices
    # 目標修訂版本
    # 可以是分支名、標籤或提交 SHA
    targetRevision: HEAD
    # Git 儲存庫中的路徑
    path: apps/microservice-platform
    # Helm 組態
    # 如果應用程式使用 Helm Chart
    helm:
      # Helm values 檔案
      valueFiles:
        - values-production.yaml
      # 額外的 Helm 參數
      parameters:
        - name: image.tag
          value: "v2.3.1"
        - name: replicas
          value: "5"
  # 目標叢集組態
  destination:
    # 目標 Kubernetes API 伺服器
    # https://kubernetes.default.svc 表示 ArgoCD 所在的叢集
    server: https://kubernetes.default.svc
    # 目標命名空間
    namespace: microservices
  # 同步策略
  syncPolicy:
    # 自動同步組態
    automated:
      # 啟用自動修剪
      # 當資源從 Git 移除時也從叢集刪除
      prune: true
      # 啟用自我修復
      # 當叢集狀態與 Git 不符時自動修復
      selfHeal: true
      # 允許同步空白應用程式
      allowEmpty: false
    # 同步選項
    syncOptions:
      # 驗證資源
      - Validate=true
      # 建立命名空間
      - CreateNamespace=true
      # 伺服器端套用
      - ServerSideApply=true
    # 重試策略
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m
  # 忽略差異
  # 某些欄位可能被動態修改，忽略這些差異
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas

#!/bin/bash
# 多叢集管理腳本範例
# 這個腳本展示了如何自動化多叢集的常見管理任務

# 定義叢集組態陣列
# 每個項目包含叢集名稱和上下文名稱
declare -A CLUSTERS
CLUSTERS["production"]="aks-production-eastasia"
CLUSTERS["staging"]="aks-staging-eastasia"
CLUSTERS["development"]="minikube"

# 函式：列出所有叢集的節點狀態
# 這個函式遍歷所有叢集並顯示節點資訊
list_all_nodes() {
    echo "=========================================="
    echo "多叢集節點狀態報告"
    echo "=========================================="

    # 遍歷所有叢集
    for cluster_name in "${!CLUSTERS[@]}"; do
        context="${CLUSTERS[$cluster_name]}"
        echo ""
        echo "叢集: $cluster_name (上下文: $context)"
        echo "------------------------------------------"

        # 切換到目標叢集上下文
        # --context 參數允許在不改變當前上下文的情況下執行命令
        kubectl --context="$context" get nodes \
            -o custom-columns=\
'NAME:.metadata.name,'\
'STATUS:.status.conditions[?(@.type=="Ready")].status,'\
'VERSION:.status.nodeInfo.kubeletVersion,'\
'CPU:.status.capacity.cpu,'\
'MEMORY:.status.capacity.memory'

        # 檢查命令執行結果
        if [ $? -ne 0 ]; then
            echo "警告: 無法連線到叢集 $cluster_name"
        fi
    done
}

# 函式：同步組態到所有叢集
# 這個函式將指定的 Kubernetes 資源套用到所有叢集
sync_config_to_all() {
    local config_file="$1"

    # 檢查組態檔案是否存在
    if [ ! -f "$config_file" ]; then
        echo "錯誤: 組態檔案 $config_file 不存在"
        return 1
    fi

    echo "同步組態: $config_file"
    echo ""

    # 遍歷所有叢集
    for cluster_name in "${!CLUSTERS[@]}"; do
        context="${CLUSTERS[$cluster_name]}"
        echo "套用到叢集: $cluster_name"

        # 使用 kubectl apply 套用組態
        # --server-side 啟用伺服器端套用以獲得更好的合併行為
        kubectl --context="$context" apply \
            --server-side \
            --force-conflicts \
            -f "$config_file"

        # 檢查執行結果
        if [ $? -eq 0 ]; then
            echo "✓ 成功套用到 $cluster_name"
        else
            echo "✗ 套用到 $cluster_name 失敗"
        fi
        echo ""
    done
}

# 函式：檢查所有叢集的資源使用狀況
# 這個函式收集並顯示各叢集的資源使用指標
check_resource_usage() {
    echo "=========================================="
    echo "多叢集資源使用報告"
    echo "=========================================="

    # 遍歷所有叢集
    for cluster_name in "${!CLUSTERS[@]}"; do
        context="${CLUSTERS[$cluster_name]}"
        echo ""
        echo "叢集: $cluster_name"
        echo "------------------------------------------"

        # 取得節點資源使用狀況
        # 需要安裝 metrics-server
        kubectl --context="$context" top nodes 2>/dev/null

        # 如果 metrics-server 未安裝，顯示替代資訊
        if [ $? -ne 0 ]; then
            echo "提示: 請安裝 metrics-server 以取得資源指標"
            # 顯示節點容量作為替代
            kubectl --context="$context" get nodes \
                -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.capacity.cpu}{"\t"}{.status.capacity.memory}{"\n"}{end}'
        fi
    done
}

# 函式：備份所有叢集的關鍵資源
# 這個函式將各叢集的重要資源匯出為 YAML 檔案
backup_critical_resources() {
    local backup_dir="$1"
    local timestamp=$(date +%Y%m%d_%H%M%S)

    # 建立備份目錄
    mkdir -p "$backup_dir"

    echo "開始備份 - 時間戳記: $timestamp"
    echo ""

    # 定義要備份的資源類型
    local resource_types=(
        "configmaps"
        "secrets"
        "services"
        "deployments"
        "statefulsets"
        "ingresses"
    )

    # 遍歷所有叢集
    for cluster_name in "${!CLUSTERS[@]}"; do
        context="${CLUSTERS[$cluster_name]}"
        cluster_backup_dir="$backup_dir/$cluster_name/$timestamp"
        mkdir -p "$cluster_backup_dir"

        echo "備份叢集: $cluster_name"

        # 遍歷資源類型
        for resource_type in "${resource_types[@]}"; do
            echo "  備份 $resource_type..."

            # 匯出所有命名空間的資源
            kubectl --context="$context" get "$resource_type" \
                --all-namespaces \
                -o yaml > "$cluster_backup_dir/${resource_type}.yaml" 2>/dev/null
        done

        echo "  備份完成: $cluster_backup_dir"
        echo ""
    done
}

# 主程式進入點
# 根據命令列參數執行相應功能
case "$1" in
    "nodes")
        list_all_nodes
        ;;
    "sync")
        sync_config_to_all "$2"
        ;;
    "usage")
        check_resource_usage
        ;;
    "backup")
        backup_critical_resources "${2:-./backups}"
        ;;
    *)
        echo "使用方法: $0 {nodes|sync|usage|backup}"
        echo ""
        echo "命令說明:"
        echo "  nodes         列出所有叢集的節點狀態"
        echo "  sync <file>   同步組態到所有叢集"
        echo "  usage         檢查所有叢集的資源使用狀況"
        echo "  backup [dir]  備份所有叢集的關鍵資源"
        exit 1
        ;;
esac

# 多叢集管理器類別範例
# 這個 Python 類別展示了如何程式化管理多個 Kubernetes 叢集

import os
import yaml
import json
from typing import Dict, List, Optional, Any
from datetime import datetime
from kubernetes import client, config
from kubernetes.client.rest import ApiException
from concurrent.futures import ThreadPoolExecutor, as_completed

class MultiClusterManager:
    """
    多叢集管理器

    這個類別提供了統一的介面來管理多個 Kubernetes 叢集
    支援叢集健康檢查、資源同步以及組態管理等功能
    """

    def __init__(self, kubeconfig_path: Optional[str] = None):
        """
        初始化多叢集管理器

        參數:
            kubeconfig_path: kubeconfig 檔案路徑
                           如果未指定，使用預設路徑 ~/.kube/config
        """
        # 設定 kubeconfig 路徑
        self.kubeconfig_path = kubeconfig_path or os.path.expanduser(
            "~/.kube/config"
        )
        # 儲存各叢集的 API 客戶端
        self.cluster_clients: Dict[str, client.CoreV1Api] = {}
        # 儲存各叢集的 Apps API 客戶端
        self.apps_clients: Dict[str, client.AppsV1Api] = {}
        # 載入叢集組態
        self._load_clusters()

    def _load_clusters(self) -> None:
        """
        從 kubeconfig 載入所有叢集組態

        這個方法讀取 kubeconfig 檔案並為每個上下文建立 API 客戶端
        """
        # 載入 kubeconfig 檔案
        # 讀取檔案內容以取得所有上下文
        with open(self.kubeconfig_path, 'r') as f:
            kubeconfig = yaml.safe_load(f)

        # 遍歷所有上下文
        for context in kubeconfig.get('contexts', []):
            context_name = context['name']

            try:
                # 為特定上下文載入組態
                # new_client_from_config 返回一個 API 客戶端
                api_client = config.new_client_from_config(
                    config_file=self.kubeconfig_path,
                    context=context_name
                )

                # 建立 CoreV1Api 客戶端
                # 用於存取 Pod、Service、ConfigMap 等核心資源
                self.cluster_clients[context_name] = client.CoreV1Api(
                    api_client
                )

                # 建立 AppsV1Api 客戶端
                # 用於存取 Deployment、StatefulSet 等應用資源
                self.apps_clients[context_name] = client.AppsV1Api(
                    api_client
                )

                print(f"已載入叢集: {context_name}")

            except Exception as e:
                print(f"載入叢集 {context_name} 失敗: {str(e)}")

    def get_cluster_health(self, cluster_name: str) -> Dict[str, Any]:
        """
        取得指定叢集的健康狀態

        參數:
            cluster_name: 叢集名稱（上下文名稱）

        返回:
            包含叢集健康資訊的字典
        """
        # 檢查叢集是否存在
        if cluster_name not in self.cluster_clients:
            return {
                "cluster": cluster_name,
                "status": "unknown",
                "error": "叢集未找到"
            }

        api = self.cluster_clients[cluster_name]
        health_info = {
            "cluster": cluster_name,
            "timestamp": datetime.utcnow().isoformat(),
            "nodes": [],
            "status": "healthy"
        }

        try:
            # 取得所有節點
            nodes = api.list_node()

            # 檢查每個節點的狀態
            for node in nodes.items:
                node_status = {
                    "name": node.metadata.name,
                    "ready": False,
                    "conditions": []
                }

                # 檢查節點條件
                for condition in node.status.conditions:
                    node_status["conditions"].append({
                        "type": condition.type,
                        "status": condition.status
                    })

                    # 檢查 Ready 條件
                    if condition.type == "Ready":
                        node_status["ready"] = condition.status == "True"

                # 取得節點容量
                node_status["capacity"] = {
                    "cpu": node.status.capacity.get("cpu"),
                    "memory": node.status.capacity.get("memory"),
                    "pods": node.status.capacity.get("pods")
                }

                health_info["nodes"].append(node_status)

                # 如果有節點未就緒，更新整體狀態
                if not node_status["ready"]:
                    health_info["status"] = "degraded"

            # 計算節點統計
            health_info["node_count"] = len(health_info["nodes"])
            health_info["ready_nodes"] = sum(
                1 for n in health_info["nodes"] if n["ready"]
            )

        except ApiException as e:
            health_info["status"] = "error"
            health_info["error"] = str(e)

        return health_info

    def get_all_clusters_health(self) -> List[Dict[str, Any]]:
        """
        取得所有叢集的健康狀態

        使用多執行緒並行檢查以提高效率

        返回:
            包含所有叢集健康資訊的列表
        """
        results = []

        # 使用 ThreadPoolExecutor 並行執行
        with ThreadPoolExecutor(max_workers=10) as executor:
            # 提交所有任務
            future_to_cluster = {
                executor.submit(
                    self.get_cluster_health, cluster_name
                ): cluster_name
                for cluster_name in self.cluster_clients.keys()
            }

            # 收集結果
            for future in as_completed(future_to_cluster):
                cluster_name = future_to_cluster[future]
                try:
                    result = future.result()
                    results.append(result)
                except Exception as e:
                    results.append({
                        "cluster": cluster_name,
                        "status": "error",
                        "error": str(e)
                    })

        return results

    def sync_configmap(
        self,
        source_cluster: str,
        source_namespace: str,
        configmap_name: str,
        target_clusters: List[str],
        target_namespace: Optional[str] = None
    ) -> Dict[str, str]:
        """
        將 ConfigMap 從來源叢集同步到目標叢集

        參數:
            source_cluster: 來源叢集名稱
            source_namespace: 來源命名空間
            configmap_name: ConfigMap 名稱
            target_clusters: 目標叢集列表
            target_namespace: 目標命名空間，如果未指定則使用來源命名空間

        返回:
            包含每個目標叢集同步結果的字典
        """
        results = {}

        # 使用來源命名空間作為預設目標命名空間
        if target_namespace is None:
            target_namespace = source_namespace

        # 從來源叢集讀取 ConfigMap
        try:
            source_api = self.cluster_clients[source_cluster]
            configmap = source_api.read_namespaced_config_map(
                name=configmap_name,
                namespace=source_namespace
            )

            # 清理元資料以便在其他叢集中建立
            # 移除叢集特定的欄位
            configmap.metadata.resource_version = None
            configmap.metadata.uid = None
            configmap.metadata.creation_timestamp = None
            configmap.metadata.namespace = target_namespace

        except ApiException as e:
            return {
                "error": f"無法從來源叢集讀取 ConfigMap: {str(e)}"
            }

        # 同步到每個目標叢集
        for target_cluster in target_clusters:
            if target_cluster not in self.cluster_clients:
                results[target_cluster] = "叢集未找到"
                continue

            target_api = self.cluster_clients[target_cluster]

            try:
                # 嘗試更新現有的 ConfigMap
                target_api.replace_namespaced_config_map(
                    name=configmap_name,
                    namespace=target_namespace,
                    body=configmap
                )
                results[target_cluster] = "已更新"

            except ApiException as e:
                if e.status == 404:
                    # ConfigMap 不存在，建立新的
                    try:
                        target_api.create_namespaced_config_map(
                            namespace=target_namespace,
                            body=configmap
                        )
                        results[target_cluster] = "已建立"
                    except ApiException as create_error:
                        results[target_cluster] = f"建立失敗: {str(create_error)}"
                else:
                    results[target_cluster] = f"更新失敗: {str(e)}"

        return results

    def get_cross_cluster_service_status(
        self,
        service_name: str,
        namespace: str
    ) -> Dict[str, Any]:
        """
        取得跨叢集的服務狀態

        檢查指定服務在所有叢集中的部署狀態

        參數:
            service_name: 服務名稱
            namespace: 命名空間

        返回:
            包含所有叢集中服務狀態的字典
        """
        status = {
            "service_name": service_name,
            "namespace": namespace,
            "clusters": {}
        }

        for cluster_name, api in self.cluster_clients.items():
            cluster_status = {
                "service_exists": False,
                "deployment_exists": False,
                "ready_replicas": 0,
                "desired_replicas": 0
            }

            # 檢查 Service 是否存在
            try:
                service = api.read_namespaced_service(
                    name=service_name,
                    namespace=namespace
                )
                cluster_status["service_exists"] = True
                cluster_status["service_type"] = service.spec.type
                cluster_status["cluster_ip"] = service.spec.cluster_ip

            except ApiException:
                pass

            # 檢查 Deployment 是否存在
            try:
                apps_api = self.apps_clients[cluster_name]
                deployment = apps_api.read_namespaced_deployment(
                    name=service_name,
                    namespace=namespace
                )
                cluster_status["deployment_exists"] = True
                cluster_status["desired_replicas"] = deployment.spec.replicas or 0
                cluster_status["ready_replicas"] = (
                    deployment.status.ready_replicas or 0
                )
                cluster_status["available_replicas"] = (
                    deployment.status.available_replicas or 0
                )

            except ApiException:
                pass

            status["clusters"][cluster_name] = cluster_status

        return status

    def generate_health_report(self) -> str:
        """
        產生多叢集健康報告

        返回:
            格式化的健康報告字串
        """
        # 取得所有叢集健康狀態
        health_data = self.get_all_clusters_health()

        # 建立報告
        report_lines = [
            "=" * 60,
            "多叢集健康報告",
            f"產生時間: {datetime.utcnow().isoformat()}",
            "=" * 60,
            ""
        ]

        # 統計總覽
        total_clusters = len(health_data)
        healthy_clusters = sum(
            1 for h in health_data if h.get("status") == "healthy"
        )
        degraded_clusters = sum(
            1 for h in health_data if h.get("status") == "degraded"
        )
        error_clusters = total_clusters - healthy_clusters - degraded_clusters

        report_lines.extend([
            "總覽:",
            f"  總叢集數: {total_clusters}",
            f"  健康叢集: {healthy_clusters}",
            f"  降級叢集: {degraded_clusters}",
            f"  錯誤叢集: {error_clusters}",
            ""
        ])

        # 各叢集詳細資訊
        report_lines.append("叢集詳細資訊:")
        report_lines.append("-" * 60)

        for cluster_health in health_data:
            cluster_name = cluster_health.get("cluster", "未知")
            status = cluster_health.get("status", "未知")

            report_lines.append(f"\n叢集: {cluster_name}")
            report_lines.append(f"  狀態: {status}")

            if "error" in cluster_health:
                report_lines.append(f"  錯誤: {cluster_health['error']}")

            if "nodes" in cluster_health:
                node_count = cluster_health.get("node_count", 0)
                ready_nodes = cluster_health.get("ready_nodes", 0)
                report_lines.append(f"  節點: {ready_nodes}/{node_count} 就緒")

                # 列出未就緒的節點
                for node in cluster_health["nodes"]:
                    if not node.get("ready"):
                        report_lines.append(
                            f"    - {node['name']}: 未就緒"
                        )

        report_lines.append("\n" + "=" * 60)

        return "\n".join(report_lines)

# 使用範例
if __name__ == "__main__":
    # 建立多叢集管理器實例
    manager = MultiClusterManager()

    # 產生並輸出健康報告
    report = manager.generate_health_report()
    print(report)

    # 取得特定服務的跨叢集狀態
    service_status = manager.get_cross_cluster_service_status(
        service_name="api-gateway",
        namespace="production"
    )
    print("\n跨叢集服務狀態:")
    print(json.dumps(service_status, indent=2, ensure_ascii=False))

# 無選擇器服務範例
# 用於將外部資料庫整合到 Kubernetes 服務發現中
# 這種方法適用於外部服務具有穩定 IP 位址的情況
apiVersion: v1
kind: Service
metadata:
  # 服務名稱
  # Pod 可以使用這個名稱存取外部資料庫
  name: external-database
  namespace: production
  labels:
    app: database
    type: external
spec:
  # 注意：沒有定義 selector
  # 這表示 Kubernetes 不會自動管理端點
  ports:
    # MySQL 連接埠
    - name: mysql
      protocol: TCP
      port: 3306
      targetPort: 3306
    # 監控連接埠
    - name: metrics
      protocol: TCP
      port: 9104
      targetPort: 9104
---
# 端點資源
# 手動定義服務的後端 IP 位址
apiVersion: v1
kind: Endpoints
metadata:
  # 名稱必須與服務名稱完全相同
  # 這是 Kubernetes 關聯服務和端點的方式
  name: external-database
  namespace: production
subsets:
  - addresses:
      # 主要資料庫伺服器
      - ip: 10.0.1.100
        # 可選：設定節點名稱用於拓撲感知路由
        nodeName: db-primary
      # 備用資料庫伺服器
      - ip: 10.0.1.101
        nodeName: db-secondary
    ports:
      - name: mysql
        port: 3306
        protocol: TCP
      - name: metrics
        port: 9104
        protocol: TCP
---
# ExternalName 服務範例
# 用於外部服務具有穩定 DNS 名稱但沒有固定 IP 的情況
# 例如雲端供應商的受管服務
apiVersion: v1
kind: Service
metadata:
  # 服務名稱
  name: external-cache
  namespace: production
  labels:
    app: cache
    type: external
spec:
  # ExternalName 類型會建立 CNAME 記錄
  type: ExternalName
  # 外部服務的 DNS 名稱
  # 對 external-cache 的查詢會被解析為此名稱
  externalName: redis-cluster.cache.svc.external
  # 連接埠定義是可選的，主要用於文件目的
  ports:
    - name: redis
      port: 6379
      protocol: TCP

// 外部服務端點控制器範例
// 這個 Go 程式碼展示了如何實作自訂控制器
// 用於動態更新外部服務的端點

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
	"time"

	corev1 "k8s.io/api/core/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/client-go/kubernetes"
	"k8s.io/client-go/rest"
)

// ExternalServiceEndpoint 代表外部服務的端點資訊
// 這個結構對應外部服務 API 返回的資料格式
type ExternalServiceEndpoint struct {
	// IP 位址
	Address string `json:"address"`
	// 連接埠
	Port    int32  `json:"port"`
	// 健康狀態
	Healthy bool   `json:"healthy"`
	// 區域
	Zone    string `json:"zone"`
}

// EndpointController 管理外部服務端點的控制器
type EndpointController struct {
	// Kubernetes 客戶端
	clientset *kubernetes.Clientset
	// 外部服務 API 端點
	externalAPIURL string
	// 服務名稱
	serviceName string
	// 命名空間
	namespace string
	// 同步間隔
	syncInterval time.Duration
}

// NewEndpointController 建立新的端點控制器實例
// 參數:
//   - externalAPIURL: 外部服務 API 的 URL
//   - serviceName: 要管理的 Kubernetes 服務名稱
//   - namespace: 服務所在的命名空間
//   - syncInterval: 同步間隔
func NewEndpointController(
	externalAPIURL string,
	serviceName string,
	namespace string,
	syncInterval time.Duration,
) (*EndpointController, error) {
	// 使用叢集內組態
	// 這假設控制器運行在 Kubernetes 叢集內
	config, err := rest.InClusterConfig()
	if err != nil {
		return nil, fmt.Errorf("無法取得叢集組態: %w", err)
	}

	// 建立 Kubernetes 客戶端
	clientset, err := kubernetes.NewForConfig(config)
	if err != nil {
		return nil, fmt.Errorf("無法建立 Kubernetes 客戶端: %w", err)
	}

	return &EndpointController{
		clientset:      clientset,
		externalAPIURL: externalAPIURL,
		serviceName:    serviceName,
		namespace:      namespace,
		syncInterval:   syncInterval,
	}, nil
}

// Run 啟動控制器的主迴圈
// 這個方法會持續運行，直到 context 被取消
func (c *EndpointController) Run(ctx context.Context) error {
	fmt.Printf("啟動端點控制器，服務: %s/%s\n", c.namespace, c.serviceName)

	// 建立定時器
	ticker := time.NewTicker(c.syncInterval)
	defer ticker.Stop()

	// 立即執行一次同步
	if err := c.syncEndpoints(ctx); err != nil {
		fmt.Printf("初始同步失敗: %v\n", err)
	}

	// 主迴圈
	for {
		select {
		case <-ctx.Done():
			// context 被取消，退出迴圈
			fmt.Println("控制器收到停止信號")
			return ctx.Err()
		case <-ticker.C:
			// 定時同步
			if err := c.syncEndpoints(ctx); err != nil {
				fmt.Printf("同步端點失敗: %v\n", err)
			}
		}
	}
}

// syncEndpoints 從外部 API 取得端點並更新 Kubernetes
func (c *EndpointController) syncEndpoints(ctx context.Context) error {
	// 從外部 API 取得端點列表
	endpoints, err := c.fetchExternalEndpoints(ctx)
	if err != nil {
		return fmt.Errorf("取得外部端點失敗: %w", err)
	}

	// 篩選健康的端點
	var healthyAddresses []corev1.EndpointAddress
	var ports []corev1.EndpointPort

	for _, ep := range endpoints {
		if ep.Healthy {
			healthyAddresses = append(healthyAddresses, corev1.EndpointAddress{
				IP: ep.Address,
			})
		}
	}

	// 如果有健康的端點，使用第一個端點的連接埠
	if len(endpoints) > 0 {
		ports = []corev1.EndpointPort{
			{
				Name:     "default",
				Port:     endpoints[0].Port,
				Protocol: corev1.ProtocolTCP,
			},
		}
	}

	// 建立 Endpoints 資源
	k8sEndpoints := &corev1.Endpoints{
		ObjectMeta: metav1.ObjectMeta{
			Name:      c.serviceName,
			Namespace: c.namespace,
			Labels: map[string]string{
				"managed-by": "external-endpoint-controller",
			},
		},
		Subsets: []corev1.EndpointSubset{
			{
				Addresses: healthyAddresses,
				Ports:     ports,
			},
		},
	}

	// 更新 Kubernetes 中的端點
	// 首先嘗試更新，如果不存在則建立
	_, err = c.clientset.CoreV1().Endpoints(c.namespace).Update(
		ctx,
		k8sEndpoints,
		metav1.UpdateOptions{},
	)

	if err != nil {
		// 如果端點不存在，嘗試建立
		_, err = c.clientset.CoreV1().Endpoints(c.namespace).Create(
			ctx,
			k8sEndpoints,
			metav1.CreateOptions{},
		)
		if err != nil {
			return fmt.Errorf("建立端點失敗: %w", err)
		}
		fmt.Printf("已建立端點，健康端點數: %d\n", len(healthyAddresses))
	} else {
		fmt.Printf("已更新端點，健康端點數: %d\n", len(healthyAddresses))
	}

	return nil
}

// fetchExternalEndpoints 從外部 API 取得端點資訊
func (c *EndpointController) fetchExternalEndpoints(
	ctx context.Context,
) ([]ExternalServiceEndpoint, error) {
	// 建立 HTTP 請求
	req, err := http.NewRequestWithContext(ctx, "GET", c.externalAPIURL, nil)
	if err != nil {
		return nil, err
	}

	// 發送請求
	client := &http.Client{Timeout: 10 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	// 檢查回應狀態
	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("API 返回非 200 狀態碼: %d", resp.StatusCode)
	}

	// 讀取回應內容
	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return nil, err
	}

	// 解析 JSON
	var endpoints []ExternalServiceEndpoint
	if err := json.Unmarshal(body, &endpoints); err != nil {
		return nil, err
	}

	return endpoints, nil
}

func main() {
	// 建立控制器
	controller, err := NewEndpointController(
		"http://service-registry.internal/api/endpoints",
		"external-service",
		"production",
		30*time.Second,
	)
	if err != nil {
		panic(err)
	}

	// 執行控制器
	ctx := context.Background()
	if err := controller.Run(ctx); err != nil {
		panic(err)
	}
}

# 內部負載平衡器服務範例
# 用於將 Kubernetes 服務匯出到虛擬網路
# 這個範例展示了不同雲端供應商的組態方式
apiVersion: v1
kind: Service
metadata:
  name: internal-api-gateway
  namespace: production
  annotations:
    # Azure 內部負載平衡器
    # 這個註解告訴 Azure 建立內部 LB 而非公開 LB
    service.beta.kubernetes.io/azure-load-balancer-internal: "true"
    # 指定內部 LB 的子網路
    service.beta.kubernetes.io/azure-load-balancer-internal-subnet: "internal-subnet"

    # AWS 內部負載平衡器（如果使用 AWS）
    # service.beta.kubernetes.io/aws-load-balancer-internal: "true"
    # service.beta.kubernetes.io/aws-load-balancer-scheme: "internal"

    # GCP 內部負載平衡器（如果使用 GCP）
    # cloud.google.com/load-balancer-type: "Internal"
    # networking.gke.io/internal-load-balancer-subnet: "internal-subnet"
spec:
  # LoadBalancer 類型會請求雲端供應商分配負載平衡器
  type: LoadBalancer
  # 選擇器定義要路由到的 Pod
  selector:
    app: api-gateway
    environment: production
  ports:
    # HTTPS 連接埠
    - name: https
      protocol: TCP
      port: 443
      targetPort: 8443
    # gRPC 連接埠
    - name: grpc
      protocol: TCP
      port: 9090
      targetPort: 9090
  # 會話親和性
  # ClientIP 確保同一客戶端的請求路由到同一 Pod
  sessionAffinity: ClientIP
  sessionAffinityConfig:
    clientIP:
      timeoutSeconds: 3600
---
# NodePort 服務範例
# 用於本地部署環境，沒有雲端負載平衡器
apiVersion: v1
kind: Service
metadata:
  name: external-web-service
  namespace: production
spec:
  # NodePort 類型在每個節點上開放連接埠
  type: NodePort
  selector:
    app: web-service
  ports:
    - name: http
      protocol: TCP
      # 服務連接埠
      port: 80
      # Pod 連接埠
      targetPort: 8080
      # 節點連接埠
      # 如果不指定，Kubernetes 會自動分配 30000-32767 範圍內的連接埠
      nodePort: 30080
    - name: https
      protocol: TCP
      port: 443
      targetPort: 8443
      nodePort: 30443
  # 外部流量政策
  # Local 確保流量只路由到本地節點上的 Pod
  # 這可以保留客戶端 IP 並減少網路跳躍
  externalTrafficPolicy: Local

# CoreDNS 跨叢集組態範例
# 這個組態展示了如何設定 CoreDNS 實現跨叢集 DNS 解析
apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns
  namespace: kube-system
data:
  Corefile: |
    # 預設叢集域名
    cluster.local:53 {
        errors
        health {
           lameduck 5s
        }
        ready
        # kubernetes 外掛處理叢集內服務發現
        kubernetes cluster.local in-addr.arpa ip6.arpa {
           pods insecure
           fallthrough in-addr.arpa ip6.arpa
           ttl 30
        }
        prometheus :9153
        # 轉發到上游 DNS
        forward . /etc/resolv.conf {
           max_concurrent 1000
        }
        cache 30
        loop
        reload
        loadbalance
    }

    # 全域服務域名
    # 用於跨叢集服務發現
    global.svc:53 {
        errors
        cache 30
        # 使用 etcd 作為後端儲存
        # 所有叢集將服務記錄寫入這個共享的 etcd
        etcd {
           stubzones
           path /skydns
           # etcd 端點
           endpoint http://etcd-cluster.etcd-system:2379
        }
    }

    # 其他叢集的服務域名
    # 轉發到對應叢集的 DNS 伺服器
    cluster-east.svc:53 {
        errors
        cache 30
        forward . 10.0.2.10:53
    }

    cluster-west.svc:53 {
        errors
        cache 30
        forward . 10.0.3.10:53
    }

    # 根域名
    .:53 {
        errors
        health
        ready
        # 預設轉發
        forward . /etc/resolv.conf
        cache 30
        reload
        loadbalance
    }
---
# External-DNS 組態範例
# 自動將 Kubernetes 服務同步到外部 DNS
apiVersion: apps/v1
kind: Deployment
metadata:
  name: external-dns
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: external-dns
  template:
    metadata:
      labels:
        app: external-dns
    spec:
      serviceAccountName: external-dns
      containers:
        - name: external-dns
          # External-DNS 映像檔
          image: registry.k8s.io/external-dns/external-dns:v0.14.0
          args:
            # DNS 供應商
            - --source=service
            - --source=ingress
            # DNS 供應商設定（以 AWS Route53 為例）
            - --provider=aws
            # 只管理這個域名下的記錄
            - --domain-filter=k8s.example.com
            # 記錄擁有者 ID，用於識別由這個 external-dns 管理的記錄
            - --txt-owner-id=production-cluster
            # 同步策略
            # sync 會建立、更新和刪除記錄
            # upsert-only 只建立和更新，不刪除
            - --policy=sync
            # 記錄 TTL
            - --registry=txt
            - --txt-prefix=external-dns-
            # 日誌級別
            - --log-level=info
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 100m
              memory: 128Mi