維運 SOP：憑證與帳密更新

多系統年度維運 SOP，涵蓋 K8s/AKS TLS Secret、PostgreSQL VM、GitLab Server、K8s 叢集自簽憑證，以及 LDAP 帳密同步更新。

概述

本環境使用萬用字元憑證（*.wiwynn.com），年度更換時需同步更新散落在多個系統的憑證。若更新不同步，服務間 TLS 握手會失敗，LDAP 認證也可能因憑證變更而中斷。

憑證更新涉及的系統可分為三類：

1. Kubernetes 叢集內：TLS Secret（Ingress 用）與 K8s 叢集本身的自簽憑證（API Server 等）
2. VM 服務：Datamarket PostgreSQL（需設定 ssl_cert_file、ssl_key_file 與權限）
3. GitLab Server：Docker 容器內 Omnibus 管理的 Nginx SSL 憑證

除憑證外，LDAP 認證帳密（Assistant 帳號）若有異動，也需同步更新 PostgreSQL pg_hba.conf 與 GitLab gitlab.rb。

核心內容

K8s TLS Secret 的更新機制

K8s TLS Secret 以 kubectl create secret tls 建立，不支援原地更新。若 Secret 已存在，需先刪除再建立，或使用 --dry-run=client -o yaml | kubectl apply -f - 的方式強制更新。

AKS（Azure Kubernetes Service）的 QAS 環境前端有 Application Gateway，TLS 終止可能在 App Gateway 層處理，此時 K8s 內的 TLS Secret 更新可能由 Sam 負責操作，需提前確認分工。

PostgreSQL VM 的憑證設定

PostgreSQL 使用 TLS 加密連線時，憑證與私鑰的路徑設定在 postgresql.conf（ssl_cert_file、ssl_key_file）。私鑰的 ownership 必須屬於 postgres 使用者，且權限為 600，否則 PostgreSQL 啟動時會拒絕讀取而報錯。

網段調整或 LDAP Server IP 更換後，必須同步確認 PostgreSQL 是否仍能連線至 LDAP Server 進行認證（pg_hba.conf 中的 ldap 條目使用 IP 或 FQDN）。

GitLab Server 的憑證更新

GitLab Omnibus Docker 部署的憑證更換流程需特別注意：憑證放置後必須執行 gitlab-ctl reconfigure，而非只 restart。詳細排除步驟與陷阱說明詳見GitLab Omnibus (Docker) HTTPS 連線失敗排除 SOP。

K8s 叢集自簽憑證輪替

K8s 叢集（kubeadm 建立）的自簽憑證預設有效期為 1 年。到期後 API Server 無法連線，kubectl 所有指令都會失敗。定期執行 kubeadm certs check-expiration 可提前掌握到期時間。輪替後需更新 ~/.kube/config，或將新的 admin.conf 分發給所有管理員。

操作歷史紀錄清除

更新 LDAP 帳密時，bash 歷史紀錄可能殘留明文密碼。操作完成後需執行 history -c && rm ~/.bash_history && exec bash 清除歷史，避免安全洩露。

關鍵要點

• CRT 檔需先整合 Bundle（中繼 CA）再放置，避免 chain 不完整
• PostgreSQL KEY 的 ownership 必須是 postgres，否則服務無法啟動
• AKS QAS 環境需確認由誰負責更新（可能有 App Gateway 分層）
• LDAP 帳密更新後必須驗證連線（gitlab-rake gitlab:ldap:check[10]）
• 操作含帳密的設定檔後，清除 bash 歷史紀錄

實際應用

此 SOP 在以下情境執行：

• 年度 *.wiwynn.com 萬用字元憑證更換
• LDAP Assistant 帳號密碼異動
• K8s 叢集自簽憑證即將到期（提前 1 個月操作）

部署設定參考

以下為實際部署時使用的完整指令，供日後查詢與複製使用。

環境參數

項目	值
萬用字元憑證	STAR_wiwynn.com.crt / STAR_wiwynn.com.key
K8s TLS Secret 名稱	aks-ingress-tls
K8s Namespace	ingress-basic
GitLab Server IP	10.248.32.101
PostgreSQL 版本	14
PostgreSQL config 路徑	/etc/postgresql/14/main/postgresql.conf
PostgreSQL hba 路徑	/etc/postgresql/14/main/pg_hba.conf

1. K8s / AKS TLS Secret 更新

kubectl create secret -n ingress-basic tls aks-ingress-tls \
  --cert=STAR_wiwynn.com.crt \
  --key=STAR_wiwynn.com.key

注意：

• QAS AKS 環境可能需要 Sam 處理（前面有 App Gateway 擋著）
• CRT 檔案需先整合 Bundle.crt（串接中繼 CA）

2. Datamarket VM 憑證更新

# 2-1. 放置憑證（644 權限，預設 root:root）
# 放置至 /etc/ssl/certs/STAR_wiwynn.com.crt

# 2-2. 放置私鑰並調整權限與擁有者
chmod 600 STAR_wiwynn.com.key
chown postgres:postgres STAR_wiwynn.com.key
# 放置至 /etc/ssl/private/STAR_wiwynn.com.key

# 2-3. 確認設定檔路徑正確
vi /etc/postgresql/14/main/postgresql.conf

# 2-4. 重啟 PostgreSQL
systemctl restart postgresql

注意： 網段更新時須確認 LDAP Server 是否仍可正常進行驗證。

• 實際權限範例截圖

3. GitLab Server 憑證更新

SSH 登入 GitLab Server，進入 Docker 容器後放置憑證並 reconfigure：

ssh 10.248.32.101
# 容器內操作，詳見 GitLab Omnibus HTTPS 排除 SOP
gitlab-ctl reconfigure

參考：GitLab Omnibus (Docker) HTTPS 連線失敗排除 SOP

4. Assistant 帳密更新

4-1. Datamarket PRD / QAS

# 更新 LDAP 認證帳密
sudo vi /etc/postgresql/14/main/pg_hba.conf

# 重啟 PostgreSQL
systemctl start postgresql

# 清除操作歷史紀錄（含明文密碼）
history -c && rm ~/.bash_history && exec bash

4-2. GitLab Server

# 登入 GitLab Server
ssh 10.248.32.101

# 進入 Docker 容器，更新 LDAP 認證帳密
vi /etc/gitlab/gitlab.rb

# 重新套用設定
gitlab-ctl reconfigure

# 驗證 LDAP 連線
gitlab-rake gitlab:ldap:check[10]

5. K8s 叢集自簽憑證輪替

sudo -s

# 檢查憑證到期時間
kubeadm certs check-expiration

# 查看可用的 renew 選項
kubeadm certs renew --help

# 更新所有憑證
kubeadm certs renew all

# 更新 kubectl config
cp /etc/kubernetes/admin.conf ~/.kube/config

參考文件：https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-certs/#manual-certificate-renewal

6. 更新 K8s Base64 Config

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

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

# 將 config 進行 Base64 編碼（單行輸出）
cat master1-config | base64 -w0 > master1-config-base64

# 將新的 Base64 編碼設定檔更新到 Azure Keyvault

相關概念

• GitLab Omnibus (Docker) HTTPS 連線失敗排除 SOP — GitLab HTTPS 連線失敗的完整診斷與修復步驟
• Kubernetes RBAC 帳號管理 — K8s ServiceAccount 與 kubeconfig 管理
• OpenSSL 自簽憑證產生 — 自建 CA 根憑證與伺服器憑證的產生腳本
• GitLab LDAP 設定更新 — GitLab 更新 LDAP Bind 帳密的三步驟 SOP
• AAD / LDAP 查詢工具指南 — 用 ldapsearch 驗證 LDAP bind 帳號有效性
• 驗證 Base64 Kubeconfig 有效性 — 更新 Keyvault 中的 kubeconfig 後驗證有效性
• Azure Pipeline — Kubeconfig 隔離最佳實踐 — Pipeline 安全使用 kubeconfig 的完整方案

來源

• 原始素材：2026-04-12 工作維運注意事項：憑證與帳密更新