Kubernetes 叢集測試、偵錯與監控體系完整實戰指南

# 檢視指定 Pod 的日誌輸出
# 這是最基本的日誌查看方式
kubectl logs my-pod -n production

# 參數說明:
# my-pod: Pod 的名稱
# -n production: 指定命名空間為 production
#
# 輸出將顯示該 Pod 主容器的所有日誌內容

# 即時追蹤日誌輸出
# 適用於需要觀察應用程式即時行為的場景
kubectl logs -f my-pod -n production

# 參數說明:
# -f 或 --follow: 持續輸出新產生的日誌,類似 tail -f
# 使用 Ctrl+C 可以中斷追蹤

# 檢視包含多個容器的 Pod 中特定容器的日誌
# 當 Pod 包含 sidecar 容器時經常需要使用
kubectl logs my-pod -c app-container -n production

# 參數說明:
# -c app-container: 指定要檢視的容器名稱
# 如果不指定容器名稱且 Pod 包含多個容器,指令會失敗並提示選擇容器

# 檢視前一個容器實例的日誌
# 當容器崩潰重啟時,這個選項非常有用
kubectl logs my-pod --previous -n production

# 參數說明:
# --previous: 顯示前一個終止的容器實例的日誌
# 這對於診斷容器崩潰原因特別有幫助
# 如果容器從未重啟過,這個指令會失敗

# 限制日誌輸出的時間範圍
# 適用於日誌量很大時,只關注最近的輸出
kubectl logs my-pod --since=1h -n production

# 參數說明:
# --since=1h: 只顯示最近 1 小時內的日誌
# 可以使用的時間單位: s(秒)、m(分)、h(時)
# 這可以大幅減少需要處理的日誌量

# 限制日誌輸出的行數
# 快速查看最新的日誌內容
kubectl logs my-pod --tail=100 -n production

# 參數說明:
# --tail=100: 只顯示最後 100 行日誌
# 預設會顯示所有日誌,在日誌量大時可能需要等待較長時間

# 檢視所有具有特定標籤的 Pod 的日誌
# 適用於檢視一組相關 Pod 的日誌
kubectl logs -l app=myapp -n production

# 參數說明:
# -l app=myapp: 使用標籤選擇器選擇 Pod
# 這會顯示所有匹配標籤的 Pod 的日誌
# --prefix 選項可以在每行前加上 Pod 名稱以區分來源

# 在容器中執行單一指令
# 適用於快速檢查特定資訊
kubectl exec my-pod -n production -- ls -la /app

# 參數說明:
# --: 這個分隔符號很重要,它將 kubectl 的選項與要在容器內執行的指令分開
# ls -la /app: 列出 /app 目錄的詳細內容
# 指令的輸出會直接顯示在終端

# 開啟互動式 shell
# 這是最常用的除錯方式,讓你能夠在容器內自由操作
kubectl exec -it my-pod -n production -- /bin/bash

# 參數說明:
# -i 或 --stdin: 保持標準輸入開啟
# -t 或 --tty: 分配一個偽終端(TTY)
# 兩者結合使用才能獲得完整的互動式體驗
# /bin/bash: 要執行的 shell 程式
# 如果容器中沒有 bash,可以嘗試 /bin/sh

# 在多容器 Pod 中的特定容器內執行指令
kubectl exec my-pod -c sidecar -n production -- ps aux

# 參數說明:
# -c sidecar: 指定要執行指令的容器
# ps aux: 列出該容器內所有執行中的程序
# 這可以幫助理解容器內的程序結構

# 檢查網路連線
# 驗證容器能否連接到其他服務
kubectl exec my-pod -n production -- curl -v http://other-service:8080/health

# 參數說明:
# curl -v: 以詳細模式執行 HTTP 請求
# 這可以幫助診斷服務間的網路連接問題
# 注意: 容器內需要安裝 curl 工具

# 檢查環境變數
# 驗證容器的環境變數配置是否正確
kubectl exec my-pod -n production -- env

# 參數說明:
# env: 列出所有環境變數
# 這可以幫助確認 ConfigMap 或 Secret 是否正確注入

# 檢視容器內的檔案內容
# 適用於驗證配置檔案是否正確掛載
kubectl exec my-pod -n production -- cat /etc/config/app.conf

# 參數說明:
# cat: 顯示檔案內容
# 這可以確認配置檔案的內容是否符合預期

# 將 Pod 的連接埠轉發到本地
# 這是最直接的連接埠轉發方式
kubectl port-forward my-pod 8080:80 -n production

# 參數說明:
# 8080:80 表示將 Pod 的 80 連接埠映射到本地的 8080 連接埠
# 之後可以透過 http://localhost:8080 存取該 Pod 的服務
# 按 Ctrl+C 可以終止轉發
#
# 注意事項:
# 1. 連接埠轉發只在 kubectl 指令執行期間有效
# 2. 只有執行該指令的本地機器可以存取
# 3. 適用於開發與除錯,不建議在生產環境長期使用

# 將 Service 的連接埠轉發到本地
# 自動選擇一個健康的 Pod 進行轉發
kubectl port-forward service/my-service 8080:80 -n production

# 參數說明:
# service/my-service: 指定要轉發的 Service
# Kubernetes 會自動選擇該 Service 後端的一個 Pod
# 如果 Pod 失敗,轉發會中斷,需要重新執行指令

# 監聽所有網路介面
# 允許同一網路內的其他機器也能存取
kubectl port-forward --address 0.0.0.0 my-pod 8080:80 -n production

# 參數說明:
# --address 0.0.0.0: 監聽所有網路介面
# 預設只監聽 localhost (127.0.0.1)
# 使用此選項時需要注意安全性,確保網路環境是受信任的

# 轉發多個連接埠
# 當服務使用多個連接埠時很有用
kubectl port-forward my-pod 8080:80 8443:443 -n production

# 參數說明:
# 8080:80 和 8443:443: 同時轉發兩個連接埠
# 第一個數字是本地連接埠,第二個是 Pod 的連接埠
# 可以根據需要轉發任意數量的連接埠

# 為開發者命名空間設定資源配額
# 這個配置限制了命名空間可以使用的最大資源量
apiVersion: v1
kind: ResourceQuota
metadata:
  name: dev-quota
  namespace: dev-alice
  labels:
    environment: development
    managed-by: platform-team
spec:
  hard:
    # CPU 資源限制
    # requests.cpu: 命名空間內所有 Pod 的 CPU 請求總和上限
    # limits.cpu: 命名空間內所有 Pod 的 CPU 限制總和上限
    requests.cpu: "4"
    limits.cpu: "8"
    
    # 記憶體資源限制
    # requests.memory: 命名空間內所有 Pod 的記憶體請求總和上限
    # limits.memory: 命名空間內所有 Pod 的記憶體限制總和上限
    requests.memory: 8Gi
    limits.memory: 16Gi
    
    # 持久化儲存限制
    # 限制命名空間可以請求的持久化儲存總量
    requests.storage: 100Gi
    persistentvolumeclaims: "10"
    
    # 物件數量限制
    # 防止建立過多的資源物件
    pods: "20"
    services: "10"
    configmaps: "20"
    secrets: "20"
    
  # 可選:設定資源配額的作用域
  # 例如只限制特定優先順序類別的 Pod
  scopeSelector:
    matchExpressions:
      - operator: In
        scopeName: PriorityClass
        values: ["low-priority", "medium-priority"]
---
# 設定 LimitRange 以提供預設值並限制單一 Pod 的資源
# LimitRange 與 ResourceQuota 配合使用,提供更精細的控制
apiVersion: v1
kind: LimitRange
metadata:
  name: dev-limits
  namespace: dev-alice
spec:
  limits:
    # 對 Pod 的限制
    - type: Pod
      max:
        cpu: "4"
        memory: 8Gi
      min:
        cpu: "100m"
        memory: 128Mi
    
    # 對 Container 的限制
    - type: Container
      # 單一容器可以使用的最大資源
      max:
        cpu: "2"
        memory: 4Gi
      # 單一容器必須請求的最小資源
      min:
        cpu: "100m"
        memory: 128Mi
      # 如果容器沒有指定資源請求或限制,使用這些預設值
      default:
        cpu: "500m"
        memory: 512Mi
      defaultRequest:
        cpu: "200m"
        memory: 256Mi
    
    # 對持久化儲存卷的限制
    - type: PersistentVolumeClaim
      max:
        storage: 50Gi
      min:
        storage: 1Gi

# Python 應用程式暴露 Prometheus 指標的範例
# 這個範例展示如何在 Flask 應用程式中整合 Prometheus 指標收集

from flask import Flask, request
from prometheus_client import Counter, Histogram, Gauge, generate_latest, REGISTRY
import time

# 建立 Flask 應用程式實例
app = Flask(__name__)

# 定義各種類型的 Prometheus 指標

# Counter: 計數器,只能增加的指標
# 適用於記錄累積的事件數量,如請求總數、錯誤總數等
http_requests_total = Counter(
    'http_requests_total',
    'HTTP 請求總數',
    ['method', 'endpoint', 'status_code']
)

# Histogram: 直方圖,記錄數值的分布情況
# 適用於記錄請求延遲、回應大小等
http_request_duration_seconds = Histogram(
    'http_request_duration_seconds',
    'HTTP 請求處理時間(秒)',
    ['method', 'endpoint']
)

# Gauge: 儀表,可增可減的指標
# 適用於記錄當前狀態,如當前連線數、佇列長度等
active_connections = Gauge(
    'active_connections',
    '當前活躍連線數'
)

# 中介軟體:自動記錄每個請求的指標
@app.before_request
def before_request():
    # 記錄請求開始時間
    request.start_time = time.time()
    # 增加活躍連線計數
    active_connections.inc()

@app.after_request
def after_request(response):
    # 計算請求處理時間
    request_duration = time.time() - request.start_time
    
    # 記錄請求計數
    # labels 用於區分不同類型的請求
    http_requests_total.labels(
        method=request.method,
        endpoint=request.endpoint or 'unknown',
        status_code=response.status_code
    ).inc()
    
    # 記錄請求處理時間
    http_request_duration_seconds.labels(
        method=request.method,
        endpoint=request.endpoint or 'unknown'
    ).observe(request_duration)
    
    # 減少活躍連線計數
    active_connections.dec()
    
    return response

# 業務邏輯端點
@app.route('/api/data')
def get_data():
    # 這裡是實際的業務邏輯
    # 所有的指標記錄都由中介軟體自動處理
    return {'data': 'example'}

# Prometheus 指標端點
# 這個端點會被 Prometheus 定期抓取
@app.route('/metrics')
def metrics():
    # generate_latest() 會生成所有已註冊指標的當前值
    # 格式為 Prometheus 可以解析的文字格式
    return generate_latest(REGISTRY)

# 啟動應用程式
if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)

# 指標輸出範例:
# # HELP http_requests_total HTTP 請求總數
# # TYPE http_requests_total counter
# http_requests_total{method="GET",endpoint="get_data",status_code="200"} 1523.0
# http_requests_total{method="POST",endpoint="create_item",status_code="201"} 342.0
# http_requests_total{method="GET",endpoint="get_data",status_code="500"} 12.0
#
# # HELP http_request_duration_seconds HTTP 請求處理時間(秒)
# # TYPE http_request_duration_seconds histogram
# http_request_duration_seconds_bucket{method="GET",endpoint="get_data",le="0.005"} 1234.0
# http_request_duration_seconds_bucket{method="GET",endpoint="get_data",le="0.01"} 1456.0
# http_request_duration_seconds_bucket{method="GET",endpoint="get_data",le="0.025"} 1489.0
# http_request_duration_seconds_sum{method="GET",endpoint="get_data"} 15.234
# http_request_duration_seconds_count{method="GET",endpoint="get_data"} 1523.0
#
# # HELP active_connections 當前活躍連線數
# # TYPE active_connections gauge
# active_connections 23.0

# 步驟 1: 建立專用的命名空間
# 將所有監控相關的資源隔離在獨立的命名空間中
kubectl create namespace monitoring

# 參數說明:
# monitoring: 命名空間名稱,可以根據需要自訂
# 建立獨立命名空間的好處:
# 1. 邏輯隔離,便於管理
# 2. 可以設定專用的資源配額
# 3. 可以設定專用的網路策略
# 4. 便於日誌與監控的過濾

# 步驟 2: 新增 Prometheus Community Helm Chart 倉庫
# Helm Chart 倉庫類似於套件管理器的軟體源
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

# 參數說明:
# prometheus-community: 倉庫的本地別名
# https://prometheus-community...: 倉庫的實際 URL
#
# 這個倉庫包含了 Prometheus 相關的各種 Chart:
# - kube-prometheus-stack: 完整的監控堆疊
# - prometheus: 獨立的 Prometheus Server
# - alertmanager: 獨立的 Alertmanager
# - pushgateway: Prometheus Pushgateway

# 步驟 3: 新增 Helm Stable Chart 倉庫
# 某些相依套件可能在這個倉庫中
helm repo add stable https://charts.helm.sh/stable

# 注意:
# stable 倉庫已經被棄用,但某些舊的 Chart 可能仍有相依性
# 新的專案應該避免依賴 stable 倉庫

# 步驟 4: 更新本地的 Chart 倉庫索引
# 確保能夠獲取最新版本的 Chart
helm repo update

# 參數說明:
# 這個指令會從所有已新增的倉庫下載最新的 Chart 清單
# 類似於 apt-get update 或 yum update

# 步驟 5: 安裝 kube-prometheus-stack Chart
# 這會部署完整的監控堆疊
helm install prometheus prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace

# 參數詳細說明:
# install: Helm 子命令,用於安裝 Chart
# prometheus: Release 名稱,這個名稱會作為所有資源的前綴
# prometheus-community/kube-prometheus-stack: Chart 的完整名稱
# --namespace monitoring: 指定安裝到 monitoring 命名空間
# --create-namespace: 如果命名空間不存在則自動建立
#
# 這個 Chart 會建立以下資源:
# - Prometheus Operator: 管理 Prometheus 實例的 Operator
# - Prometheus Server: 指標收集與儲存
# - Alertmanager: 警示管理
# - Grafana: 視覺化儀表板
# - kube-state-metrics: Kubernetes 物件狀態指標
# - Node Exporter: 節點層級的系統指標
# - 預設的 ServiceMonitor: 自動發現與抓取目標
# - 預設的 PrometheusRule: 常見的警示規則

# 可選:使用自訂的 values.yaml 檔案
# 如果需要自訂配置,可以準備一個 values.yaml 檔案
helm install prometheus prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --values custom-values.yaml

# custom-values.yaml 範例:
# prometheus:
#   prometheusSpec:
#     retention: 30d  # 指標保留時間
#     storageSpec:
#       volumeClaimTemplate:
#         spec:
#           storageClassName: fast-ssd
#           resources:
#             requests:
#               storage: 100Gi
# grafana:
#   adminPassword: "secure-password"
#   persistence:
#     enabled: true
#     size: 10Gi

# 步驟 6: 驗證部署狀態
# 檢查所有 Pod 是否正常執行
kubectl get pods -n monitoring

# 預期輸出範例:
# NAME                                                     READY   STATUS    RESTARTS   AGE
# alertmanager-prometheus-kube-prometheus-alertmanager-0   2/2     Running   0          2m
# prometheus-grafana-6f7cf9b968-xtnzj                      3/3     Running   0          2m
# prometheus-kube-prometheus-operator-7bdb94567b-q8k9z     1/1     Running   0          2m
# prometheus-kube-state-metrics-6bdd65d76-s5r5j            1/1     Running   0          2m
# prometheus-prometheus-kube-prometheus-prometheus-0       2/2     Running   0          2m
# prometheus-prometheus-node-exporter-dgrlf                1/1     Running   0          2m
#
# 狀態說明:
# READY 2/2 或 3/3: 表示 Pod 內的所有容器都已就緒
# STATUS Running: Pod 正在正常執行
# RESTARTS 0: Pod 沒有重啟過,表示穩定
#
# 如果某個 Pod 的狀態不是 Running,可以使用以下指令診斷:
# kubectl describe pod <pod-name> -n monitoring
# kubectl logs <pod-name> -n monitoring

# 步驟 7: 檢視所有相關的資源
kubectl get all -n monitoring

# 這會列出命名空間內的所有資源:
# - Pods
# - Services
# - Deployments
# - StatefulSets
# - DaemonSets
# - ReplicaSets

# 步驟 8: 存取 Grafana 儀表板
# 使用連接埠轉發將 Grafana 服務暴露到本地
kubectl port-forward -n monitoring \
  svc/prometheus-grafana 3000:80

# 參數說明:
# svc/prometheus-grafana: 要轉發的 Service
# 3000:80: 本地連接埠 3000 對應 Service 的連接埠 80
#
# 執行後,可以在瀏覽器中開啟 http://localhost:3000
# 預設登入憑證:
# 使用者名稱: admin
# 密碼: prom-operator (除非在 values.yaml 中自訂)
#
# 建議在生產環境中:
# 1. 修改預設密碼
# 2. 配置 Ingress 而不是使用 port-forward
# 3. 啟用 HTTPS
# 4. 整合 OAuth 或 LDAP 認證

# 步驟 9: 存取 Prometheus UI
# 使用連接埠轉發存取 Prometheus 的 Web UI
kubectl port-forward -n monitoring \
  svc/prometheus-kube-prometheus-prometheus 9090:9090

# 存取 http://localhost:9090 可以:
# 1. 執行 PromQL 查詢
# 2. 檢視所有的抓取目標
# 3. 檢視警示規則的狀態
# 4. 瀏覽所有可用的指標

# 步驟 10: 檢視 Prometheus 的配置
# Prometheus 的配置儲存在 Secret 中
kubectl get secret -n monitoring \
  prometheus-prometheus-kube-prometheus-prometheus \
  -o jsonpath='{.data.prometheus\.yaml\.gz}' | \
  base64 -d | gunzip

# 這會顯示 Prometheus 的完整配置,包括:
# - 抓取配置(scrape_configs)
# - 警示規則檔案(rule_files)
# - 警示管理器端點(alerting)
# - 遠端寫入配置(remote_write,如果有)

# 步驟 1: 確保應用程式暴露了 Prometheus 指標端點
# 應用程式應該在某個路徑(通常是 /metrics)提供指標
# 這個端點需要回傳 Prometheus 文字格式的指標

# 步驟 2: 建立 Service 來暴露應用程式的指標端點
apiVersion: v1
kind: Service
metadata:
  name: my-app-metrics
  namespace: default
  labels:
    app: my-app
    # 這個標籤很重要,ServiceMonitor 會使用它來選擇 Service
    monitoring: "true"
spec:
  selector:
    app: my-app
  ports:
    - name: metrics
      # 連接埠名稱對於 ServiceMonitor 很重要
      # ServiceMonitor 會透過名稱來識別指標端點
      port: 8080
      targetPort: 8080
      protocol: TCP
  type: ClusterIP
---
# 步驟 3: 建立 ServiceMonitor 資源
# ServiceMonitor 告訴 Prometheus Operator 應該監控哪些 Service
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-app-monitor
  namespace: default
  labels:
    # 這個標籤必須與 Prometheus 的 serviceMonitorSelector 匹配
    # kube-prometheus-stack 預設的 selector 是 release: prometheus
    release: prometheus
spec:
  # 選擇要監控的 Service
  # 這個 selector 會匹配具有 app=my-app 與 monitoring=true 標籤的 Service
  selector:
    matchLabels:
      app: my-app
      monitoring: "true"
  
  # 可選:限制在特定的命名空間中查找 Service
  # 如果不設定,會在 ServiceMonitor 所在的命名空間中查找
  namespaceSelector:
    matchNames:
      - default
      - production
  
  # 定義如何抓取指標
  endpoints:
    - port: metrics
      # 連接埠名稱,必須與 Service 中定義的名稱匹配
      
      interval: 30s
      # 抓取間隔,預設是 30 秒
      # 更短的間隔提供更高的時間解析度,但會增加 Prometheus 的負載
      
      path: /metrics
      # 指標端點的路徑,預設是 /metrics
      
      scheme: http
      # 使用的協定,可以是 http 或 https
      
      # 可選:如果使用 HTTPS,可以配置 TLS
      # tlsConfig:
      #   insecureSkipVerify: true
      #   ca:
      #     secret:
      #       name: my-app-ca-cert
      #       key: ca.crt
      
      # 可選:添加額外的標籤到抓取的指標
      # 這些標籤可以用於在 PromQL 查詢中進行過濾
      relabelings:
        - sourceLabels: [__meta_kubernetes_namespace]
          targetLabel: kubernetes_namespace
        - sourceLabels: [__meta_kubernetes_service_name]
          targetLabel: kubernetes_service_name
      
      # 可選:指標重新標籤
      # 可以用來過濾或修改指標
      # metricRelabelings:
      #   - sourceLabels: [__name__]
      #     regex: 'go_.*'
      #     action: drop  # 丟棄所有以 go_ 開頭的指標
---
# 步驟 4: 驗證 ServiceMonitor 是否被 Prometheus 發現
# 可以透過 Prometheus UI 檢查
# 1. 開啟 http://localhost:9090/targets
# 2. 應該能看到 my-app-monitor 相關的目標
# 3. 檢查目標的狀態是否為 UP

# 步驟 5: 驗證指標是否被成功抓取
# 在 Prometheus UI 中執行查詢
# 例如:my_app_requests_total
# 應該能看到來自應用程式的指標