排解透明資料加密 (TDE) 問題

選取說明文件版本：

本頁說明如何排解 AlloyDB Omni 中的透明資料加密 (TDE) 問題。

擷取疑難排解記錄

如要排解 TDE 問題，可以根據部署類型收集記錄。

從下列三個來源收集診斷資訊：

  1. 叢集設定和事件：

    使用 describe 資料庫叢集指令，檢查高階錯誤或狀態訊息：

    kubectl describe dbcluster CLUSTER_NAME -n NAMESPACE

  2. Pod 記錄檔：

    取得資料庫 Pod 的記錄：

    kubectl logs POD_NAME -n NAMESPACE

  3. 內部資料庫記錄：

    檢查 Pod 內的 PostgreSQL 診斷記錄檔，篩選出與 TDE 相關的訊息：

    kubectl exec -it POD_NAME -c database -n NAMESPACE -- cat /obs/diagnostic/postgresql.log | grep "TDE"

記錄可能包含下列項目：

  • TDE: TdeContext initialization failed
  • TDE: Vault server unreachable
  • TDE: Certificate expired

錯誤情況

本節說明常見的 TDE 錯誤情境，並提供建議的修正方式。

JWT 錯誤

如果您在收集的記錄中看到 HashiCorp Vault 驗證或初始化失敗，通常與 JSON Web Token (JWT) 問題有關。

說明

您可能會看到下列錯誤：

錯誤 說明 原因
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 3, error message: JWT cannot be empty 找不到 JWT 或 JWT 為空白 缺少 JWT 權杖或權杖為空白。
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 3, error message: Invalid JWT format. Expected JWS compact serialization (three dot-separated segments: header, payload, and signature) with base64url encoded values. JWT 格式有誤 JWT 權杖不符合正確的 JWS 壓縮序列化格式。
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 3, error message: Vault request failed with HTTP code: 400, Vault errors: ["error validating token: invalid expiration time (exp) claim: token is expired"] 過期的 JWT JWT 權杖已過期。
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 3, error message: Vault request failed with HTTP code: 400, Vault errors: ["error validating token: error verifying token signature: failed to verify id token signature"] JWT 簽章無效 Vault 伺服器無法驗證 JWT 權杖的簽章。
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 9, error message: Failed to get Vault configuration parameter 'VAULT_JWT' 權限問題 AlloyDB Omni 沒有讀取 JWT 權杖檔案的權限，或未設定 VAULT_JWT 環境變數。

如要解決 JWT 問題，請按照下列步驟操作：

  1. 擷取有效的 JWT：

    執行下列指令，從 Pod 擷取 JWT 權杖：

    kubectl exec -it POD_NAME -c database -n NAMESPACE -- cat /var/run/secrets/vault/token

  2. 檢查 JWT 結構：確認權杖有效，且符合 JWT 精簡序列化格式。

  3. 驗證權杖狀態：確認權杖有效且尚未過期。

KMS 網址錯誤

如果資料庫無法初始化或啟動，可能是因為金鑰管理服務 (KMS) 金鑰加密金鑰 (KEK) 網址設定錯誤。

說明

您可能會看到下列錯誤：

錯誤 說明 原因
TDE: Failed to register Key Store with URL: KMS_URL, error code: 12, error message: Unsupported key store type 不支援的金鑰儲存類型 如果 KEK 網址通訊協定不是 vault，就會發生這個問題。例如，使用 http:// 或 https://，而非 vault://，或完全省略配置。
TDE: Failed to register Key Store with URL: KMS_URL, error code: 3, error message: Invalid Vault address format. Expected hostname or hostname:port Vault 地址格式無效 網址的保管箱位址部分格式不正確時，就會發生這種情況。舉例來說，如果再次加入通訊協定架構，例如 vault://https://vault.example.com:8200/...。
TDE: Failed to read KEK, error code: 3, error message: Invalid key path format. Must start with '/', not end with '/', and contain only valid characters 金鑰路徑格式無效 保管箱網址的路徑部分格式不正確時，就會發生這種情況。路徑開頭須為正斜線 /，結尾不得為斜線。
TDE: Failed to register Key Store with URL: KMS_URL, error code: 13, error message: curl_easy_perform() failed: Could not resolve hostname 無法解析主機名稱 如果無法解析 KEK 網址中的 Vault 主機名稱，就會發生這個錯誤。如果網址格式不正確 (例如 vault://https:) 或 DNS 設定有問題，就可能發生這種情況。
  • 驗證 KEK 網址配置：確認網址開頭為 vault://。請勿使用 https:// 做為前置字元。
    • 正確：vault://vault.example.com:8200/v1/secret/data/key
    • 錯誤：https://vault.example.com:8200/v1/secret/data/key
  • 檢查地址格式：確認主機和通訊埠緊接在 vault:// 前置字元後方，且指定正確。
  • 確認路徑格式：請確認路徑開頭為 /，且結尾沒有斜線 (例如使用 /v1/secret/data/key，而非 /v1/secret/data/key/)。
  • 驗證主機解析度：確認網址中指定的主機名稱正確無誤，且可從資料庫 Pod 內解析。

KEK 未採用 Base64 編碼

如果儲存在 HashiCorp Vault 的 KEK 未正確採用 Base64 編碼，AlloyDB Omni 擷取時就無法解碼。這會導致系統無法解開本機資料加密金鑰 (DEK)，進而造成啟動失敗。

說明

您可能會在資料庫診斷記錄中看到下列錯誤 (postgresql.log)：

錯誤 說明 原因
TDE: Failed to read KEK, error code: 13, error message: Error decoding base64 key string 解碼 Base64 金鑰字串時發生錯誤 當金鑰管理員嘗試使用 Base64 解碼從 Vault 擷取的密鑰時，如果字串不是有效的 Base64，就會發生這個錯誤。
  • 擷取 KEK 值：直接從 HashiCorp Vault 擷取並檢查 KEK 值。
  • 更新 Vault 中的值：請確認 Vault 中儲存的 KEK 已採用 Base64 編碼。如果儲存為原始二進位或純文字，請使用 Base64 編碼的對等值更新 Vault 中的值。
    1. 將原始金鑰轉換為 Base64： 
      echo -n "RAW_KEY" | base64
    2. 將 HashiCorp Vault 中的 Secret 更新為產生的 Base64 編碼字串。

保管箱中缺少 KEK 版本

如果 AlloyDB Omni 嘗試使用特定歷來版本的 KEK 解開本機 DEK，但該版本已刪除、銷毀或在 HashiCorp Vault 中遺失，就會發生「Vault 中缺少 KEK 版本」錯誤。這種情況最常發生在備份還原作業或待命副本初始化期間。

說明

您可能會在資料庫診斷記錄中看到下列錯誤 (postgresql.log)：

錯誤 說明 原因
TDE: Failed to read KEK, error code: 5, error message: Vault request failed with HTTP code: 404, Response body: {... "destroyed":true, "version":4 ...} 已刪除金鑰版本 系統會永久刪除保管箱中要求的 KEK 版本。
  • 在 Vault 中驗證 KEK 版本：確認要求的 KEK 版本存在於 HashiCorp Vault 中，且處於啟用狀態 (未刪除或毀損)。
  • 還原遺失的 KEK 版本：如果要求的 KEK 版本已刪除但未銷毀，請在 Vault 中還原或取消刪除。
  • 處理已刪除的金鑰：如果要求的金鑰版本已在保管箱中永久刪除，則使用該版本加密的資料或備份將永久無法復原。

TLS 或 SSL 憑證無效或遺失

如果憑證遺失、過期、不受信任或設定錯誤，AlloyDB Omni 無法與 HashiCorp Vault 建立安全的 TLS 連線，就會發生 TLS 或 SSL 憑證錯誤或遺失。

說明

您可能會在資料庫診斷記錄中看到下列錯誤 (postgresql.log)：

錯誤 說明 原因
TDE: Failed to read KEK, error code: 13, error message: curl_easy_perform() failed: SSL peer certificate or SSH remote key was not OK
或
TDE: Failed to read KEK, error code: 13, error message: curl_easy_perform() failed: Peer certificate cannot be authenticated with given CA certificates		 Vault 伺服器憑證驗證失敗 無法使用提供的 CA 憑證驗證 Vault 伺服器的憑證。
TDE: Failed to register Key Store with URL: VAULT_URL, error code: 13, error message: curl_easy_perform() failed: Problem with the local SSL certificate 本機 SSL 憑證問題 如果需要用戶端憑證，但憑證有問題，就會發生這個錯誤。

如要解決 TLS 驗證問題，請確認已提供正確的憑證，並由 postgres 使用者掛接及讀取。

Kubernetes 預期憑證會以 Secret 的形式提供，並掛接至 /tde-tls 的資料庫 Pod。如要找出並檢查憑證密鑰，請按照下列步驟操作：

  1. 直接從資料庫叢集擷取參照的 TdeConfig 名稱：

    kubectl get dbcluster CLUSTER_NAME -n NAMESPACE -o jsonpath='{.spec.primarySpec.features.transparentDataEncryption.tdeConfigRef.name}'

  2. 直接從 TdeConfig 資源擷取密鑰名稱：

    kubectl get tdeconfig TDE_CONFIG_NAME -n NAMESPACE -o jsonpath='{.spec.tls.certSecret.name}'

  3. 確認密鑰是否存在，且包含必要金鑰：

    kubectl describe secret CERT_SECRET_NAME -n NAMESPACE

  4. 確認密鑰已正確掛接，且 postgres 使用者可讀取檔案：

    kubectl exec -it POD_NAME -c database -n NAMESPACE -- ls -la /tde-tls