Kubernetes 金鑰管理實戰：從 Keywhiz 系統架構到現代化解決方案

# 透過宣告式組態建立 Kubernetes Secret 資源
# 實務上不應將明文金鑰直接提交至版本控制系統
apiVersion: v1
kind: Secret
metadata:
  # Secret 的唯一識別名稱，用於後續引用
  name: database-credentials
  # 指定所屬的命名空間，實現邏輯隔離
  namespace: production
  # 使用標籤進行分類，便於批次操作與查詢篩選
  labels:
    app: payment-service
    environment: production
    managed-by: platform-team
  # 註解記錄額外的後設資料，協助稽核與追蹤管理
  annotations:
    # 記錄建立的時間戳記，便於追蹤金鑰年齡
    created-at: "2025-11-23T09:00:00Z"
    # 記錄建立者的身份識別，落實責任歸屬制度
    created-by: "platform-admin"
    # 記錄預定的輪替週期，便於自動化管理流程
    rotation-schedule: "90days"
    # 記錄用途說明，協助團隊成員理解金鑰用途
    description: "PostgreSQL 資料庫連線憑證用於支付服務"
# Secret 的類型，Opaque 表示一般用途的金鑰資料
type: Opaque
# 實際的金鑰資料內容，必須使用 Base64 編碼格式
# 注意：Base64 編碼不是加密，僅用於處理二進位資料
data:
  # 資料庫主機位址的 Base64 編碼值
  DB_HOST: cG9zdGdyZXNxbC5wcm9kdWN0aW9uLnN2Yy5jbHVzdGVyLmxvY2Fs
  # 資料庫連接埠的 Base64 編碼值
  DB_PORT: NTQzMg==
  # 資料庫名稱的 Base64 編碼值
  DB_NAME: cGF5bWVudF9kYg==
  # 資料庫使用者名稱的 Base64 編碼值
  DB_USER: cGF5bWVudF91c2Vy
  # 資料庫密碼的 Base64 編碼值，應使用強密碼產生器建立
  DB_PASSWORD: c3Ryb25nX3Bhc3N3b3JkX2hlcmU=

# 透過 Volume 掛載 Secret 的安全組態範例
apiVersion: v1
kind: Pod
metadata:
  name: secure-payment-service
  namespace: production
spec:
  # 指定服務帳戶，用於 RBAC 權限控制機制
  serviceAccountName: payment-service-sa
  
  containers:
    - name: payment-app
      image: payment-service:v1.2.3
      
      # 設定環境變數指向 Secret 檔案路徑
      # 應用程式從檔案讀取而非從環境變數直接取得
      env:
        # 告知應用程式資料庫密碼檔案的路徑位置
        - name: DB_PASSWORD_FILE
          value: /secrets/database/password
        # 告知應用程式 API 金鑰檔案的路徑位置
        - name: API_KEY_FILE
          value: /secrets/api/key
      
      # 將 Secret 資源掛載為 Volume 檔案系統
      volumeMounts:
        # 掛載資料庫憑證 Secret 資源
        - name: database-secrets
          # 指定掛載至容器內的目標路徑
          mountPath: /secrets/database
          # 設定為唯讀模式，防止容器程序修改內容
          readOnly: true
        
        # 掛載 API 金鑰 Secret 資源
        - name: api-secrets
          mountPath: /secrets/api
          readOnly: true
      
      # 設定容器的安全性上下文，強化安全防護
      securityContext:
        # 不允許提升權限，防止權限升級攻擊
        allowPrivilegeEscalation: false
        # 設定唯讀的根檔案系統，增強安全性
        readOnlyRootFilesystem: true
        # 強制以非 root 使用者身份執行容器程序
        runAsNonRoot: true
        runAsUser: 1000
        # 設定檔案系統群組，控制檔案存取權限
        fsGroup: 2000
  
  # 定義 Volume 資源的來源與組態設定
  volumes:
    # 定義資料庫憑證的 Volume 資源
    - name: database-secrets
      secret:
        # 指定來源 Secret 資源的名稱
        secretName: database-credentials
        # 設定檔案權限為 400 (僅擁有者可讀取)
        # 這比預設的 644 權限更加安全
        defaultMode: 0400
        # 只掛載需要的項目，避免暴露不必要的金鑰
        items:
          - key: DB_PASSWORD
            path: password
          - key: DB_USER
            path: username
    
    # 定義 API 金鑰的 Volume 資源
    - name: api-secrets
      secret:
        secretName: api-credentials
        defaultMode: 0400
        items:
          - key: API_KEY
            path: key

#!/bin/bash
# Kubernetes Secrets 自動化備份腳本
# 功能：匯出所有命名空間的 Secrets 至加密的備份檔案

# 設定備份目錄路徑與檔案命名格式
BACKUP_DIR="/var/backups/kubernetes/secrets"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/secrets_backup_${TIMESTAMP}.yaml"

# 建立備份目錄結構（若目錄不存在則自動建立）
mkdir -p "${BACKUP_DIR}"

# 匯出所有命名空間的 Secrets 資源至 YAML 格式
# --all-namespaces: 包含所有命名空間的資源內容
# -o yaml: 以 YAML 格式輸出，便於版本控制與還原操作
echo "開始執行 Kubernetes Secrets 備份程序..."
kubectl get secrets --all-namespaces -o yaml > "${BACKUP_FILE}"

# 檢查備份檔案是否成功建立
if [ -f "${BACKUP_FILE}" ]; then
    echo "備份檔案建立成功：${BACKUP_FILE}"
    
    # 使用 GPG 工具對備份檔案進行加密處理
    # 保護備份內容避免未經授權的存取讀取
    # --encrypt: 執行加密操作指令
    # --recipient: 指定接收者的 GPG 金鑰識別碼
    # --output: 指定加密後的輸出檔案路徑
    echo "正在執行備份檔案加密處理..."
    gpg --encrypt --recipient backup-key@company.com \
        --output "${BACKUP_FILE}.gpg" "${BACKUP_FILE}"
    
    # 刪除未加密的備份檔案，避免敏感資訊洩露風險
    rm -f "${BACKUP_FILE}"
    
    # 設定加密備份檔案的權限為僅擁有者可讀取
    chmod 400 "${BACKUP_FILE}.gpg"
    
    echo "備份完成並已完成加密處理：${BACKUP_FILE}.gpg"
    
    # 將加密的備份檔案上傳至遠端雲端儲存服務
    # 建議使用企業級的備份解決方案如 AWS S3、Azure Blob Storage
    echo "正在上傳備份檔案至遠端儲存服務..."
    aws s3 cp "${BACKUP_FILE}.gpg" \
        s3://company-k8s-backups/secrets/ \
        --storage-class GLACIER
    
    # 清理超過 30 天的本地備份檔案，節省本地儲存空間
    find "${BACKUP_DIR}" -name "*.gpg" -mtime +30 -delete
    
else
    echo "錯誤：備份檔案建立失敗，請檢查系統狀態"
    exit 1
fi

# 定義自動化金鑰輪替的 CronJob 資源組態
apiVersion: batch/v1
kind: CronJob
metadata:
  name: secret-rotation-cronjob
  namespace: platform-automation
  labels:
    component: secret-management
    managed-by: platform-team
spec:
  # 設定執行排程：每月 1 日凌晨 2 點執行輪替作業
  # 格式為 Cron 表達式：分 時 日 月 週
  # 選擇凌晨時段執行可減少對業務運作的影響
  schedule: "0 2 1 * *"
  
  # 並行策略設定為 Forbid，避免同時執行多個輪替作業
  # 若前一次執行尚未完成，新的執行會被自動跳過
  concurrencyPolicy: Forbid
  
  # 保留最近 3 次成功與失敗的 Job 執行歷史記錄
  # 便於追蹤執行結果與問題診斷除錯
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 3
  
  jobTemplate:
    spec:
      # 設定 Job 的完成時間限制為 1 小時
      # 超過此時間未完成則視為執行失敗
      activeDeadlineSeconds: 3600
      
      # 失敗重試次數設定為 2 次
      # 避免因暫時性錯誤而直接放棄輪替作業
      backoffLimit: 2
      
      template:
        metadata:
          labels:
            app: secret-rotation
            job-type: automation
        spec:
          # 使用專用的服務帳戶，僅授予必要的最小權限
          serviceAccountName: secret-rotator-sa
          
          containers:
            - name: secret-rotator
              # 使用自訂的輪替工具映像檔
              # 此映像應包含密碼產生、API 互動等邏輯
              image: secret-rotator:v2.1.0
              
              # 設定環境變數來控制輪替行為與參數
              env:
                # 指定要輪替的 Secret 名稱模式
                # 支援萬用字元匹配多個 Secret 資源
                - name: SECRET_PATTERN
                  value: "*-credentials"
                
                # 指定要處理的命名空間清單
                # 以逗號分隔支援多個命名空間
                - name: TARGET_NAMESPACES
                  value: "production,staging"
                
                # 設定新密碼的長度要求標準
                - name: PASSWORD_LENGTH
                  value: "32"
                
                # 設定密碼複雜度等級
                # high 表示包含大小寫字母數字與特殊符號
                - name: PASSWORD_COMPLEXITY
                  value: "high"
                
                # 指定輪替週期，超過此天數的金鑰將被輪替
                - name: ROTATION_AGE_DAYS
                  value: "90"
                
                # 外部金鑰管理系統的連線位址資訊
                # 用於同步更新外部系統的認證資訊
                - name: VAULT_ADDR
                  value: "https://vault.company.com"
                
                # Vault 認證 Token，從 Secret 資源中讀取
                - name: VAULT_TOKEN
                  valueFrom:
                    secretKeyRef:
                      name: vault-auth-token
                      key: token
              
              # 資源限制，避免輪替 Job 消耗過多系統資源
              resources:
                requests:
                  memory: "256Mi"
                  cpu: "200m"
                limits:
                  memory: "512Mi"
                  cpu: "500m"
              
              # 安全性上下文設定，強化容器安全防護
              securityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                runAsNonRoot: true
                runAsUser: 1000
          
          # 重啟策略設定為 OnFailure
          # 失敗時會自動重試，成功後不會重新啟動
          restartPolicy: OnFailure