驗證 Base64 Kubeconfig 有效性

在不覆蓋 ~/.kube/config 的前提下，驗證一串 Base64 kubeconfig 是否能成功連線叢集。

概述

當 kubeconfig 以 Base64 形式儲存在 Azure Key Vault、環境變數或 CI/CD Secret 中時，在實際部署前驗證其有效性是重要的防錯步驟。直接覆蓋 ~/.kube/config 風險高（可能中斷現有 kubectl 操作），正確的做法是解碼到 /tmp 臨時路徑，用 KUBECONFIG 環境變數指定路徑來測試，測試完畢後立即刪除。

常見的失效原因：AKS kubeconfig 內的 token 通常 1 小時後過期、ServiceAccount token 可能被撤銷、Certificate-based 憑證到期、叢集 Endpoint 的 DNS 或網路可達性問題。

核心內容

四步驟驗證 SOP

步驟一：解碼並暫存

echo "<your-base64-string>" | base64 -d > /tmp/test-kubeconfig.yaml

步驟二：測試連線

KUBECONFIG=/tmp/test-kubeconfig.yaml kubectl cluster-info

步驟三：驗證資源存取與身分

# 列出節點（較完整的連線驗證）
KUBECONFIG=/tmp/test-kubeconfig.yaml kubectl get nodes

# 僅驗證身分認證
KUBECONFIG=/tmp/test-kubeconfig.yaml kubectl auth whoami

步驟四：清除暫存檔

rm /tmp/test-kubeconfig.yaml

不產生暫存檔的一行版

適合驗證短暫性 token（避免暫存檔殘留）：

echo "<your-base64-string>" | base64 -d | KUBECONFIG=/dev/stdin kubectl cluster-info

常見錯誤判讀

錯誤訊息	原因
Unable to connect to the server	網路不通，或 API Server 已下線
Unauthorized	Token / Certificate 已過期或被撤銷
certificate signed by unknown authority	CA Certificate 不符
no such host	DNS 解析失敗，Cluster Endpoint 有問題

憑證到期日檢查

Certificate-based kubeconfig 可用以下指令確認到期日：

echo "<your-base64-string>" | base64 -d \
  | grep -A1 "client-certificate-data" \
  | tail -1 | base64 -d \
  | openssl x509 -noout -dates

關鍵要點

• 永遠用 /tmp 臨時路徑，不要覆蓋 ~/.kube/config
• AKS kubeconfig 內的 token 通常只有 1 小時有效期，過期須重新 az aks get-credentials
• kubectl auth whoami 只驗證身分，kubectl get nodes 才能同時確認叢集連通性與 RBAC 權限
• /dev/stdin 技巧可省略暫存檔，但不適用所有環境（macOS 行為與 Linux 不同）

實際應用

• CI/CD 部署前的煙霧測試：在 decode kubeconfig 後立即執行 kubectl cluster-info，確認可連線後再繼續部署
• 更新 Azure Key Vault 後驗證：確認新版 kubeconfig 有效後，再通知各 pipeline 改用新版本
• 交付 restricted kubeconfig 給外部廠商前：驗證可以連線叢集、且權限範圍符合預期（kubectl auth can-i）

部署設定參考

AKS Token 過期時重新取得

az aks get-credentials --resource-group <rg> --name <cluster-name>

ServiceAccount Token 到期確認

kubectl describe secret <secret-name> -n <namespace>

更新 Azure Keyvault 中的 Base64 Kubeconfig

# 切換到指定設定檔
kubectl config use-context CONTEXT_NAME

# 輸出扁平化設定檔
kubectl config view --minify --flatten > exported_context.yaml

# 編碼成單行 Base64
cat exported_context.yaml | base64 -w0 > exported_context-base64.txt

# 更新到 Azure Keyvault（用 az cli 或 Portal 手動更新）
az keyvault secret set --vault-name <vault-name> --name <secret-name> --file exported_context-base64.txt

相關概念

• Kubernetes RBAC 帳號管理 — 產生 restricted kubeconfig 的方法
• Azure Pipeline — Kubeconfig 隔離最佳實踐 — CI/CD 中安全使用 kubeconfig 的完整方案
• 維運 SOP：憑證與帳密更新 — 更新 K8s Base64 Config 的完整 SOP
• Linux 剪貼簿工具 — 複製 Base64 kubeconfig 到剪貼簿的方法

來源

• 原始素材：2026-04-22 驗證 Base64 Kubeconfig 有效性