排解透明資料加密問題

本頁面說明如何排解 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"

更改下列內容：

  • CLUSTER_NAME：DBCluster 資源的名稱。
  • NAMESPACE：部署 DBCluster 的 Kubernetes 命名空間。
  • POD_NAME：資料庫 Pod 的名稱。

記錄可能包含下列項目：

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

錯誤情況

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

JWT 錯誤 (HashiCorp Vault)

如果您在收集的記錄中看到 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

    將 POD_NAME 替換為資料庫 Pod 的名稱，並將 NAMESPACE 替換為部署叢集的命名空間。

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

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

CipherTrust 憑證錯誤 (Thales CipherTrust Manager)

如果在收集的記錄中看到 Thales CipherTrust Manager 驗證或初始化失敗，通常是因為缺少或使用者憑證無效 (username 和 password)。

說明

您可能會看到類似下方的錯誤訊息：

錯誤 說明 原因
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 3, error message: CipherTrust user cannot be empty 缺少使用者名稱 CIPHERTRUST_USER 環境變數或 Kubernetes Secret 中的 username 鍵空白。
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 3, error message: CipherTrust password cannot be empty 缺少密碼 CIPHERTRUST_PASSWORD 環境變數或 Kubernetes Secret 中的 password 鍵空白。
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 9, error message: Failed to get CipherTrust configuration parameter 'CIPHERTRUST_USER'
或
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 9, error message: Failed to get CipherTrust configuration parameter 'CIPHERTRUST_PASSWORD'		 未設定環境變數 缺少 CIPHERTRUST_USER 或 CIPHERTRUST_PASSWORD 環境變數。
TDE: Failed to register Key Store with URL: CIPHERTRUST_URL, error code: 16, error message: CipherTrust request failed with HTTP code: 401 憑證無效 username 或 password遭 Thales CipherTrust Manager 驗證端點 (/api/v1/auth/tokens) 拒絕。

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

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

  2. 從 TdeConfig 資源中擷取參照的 credentialsSecretRef 名稱：

    kubectl get tdeconfig TDE_CONFIG_NAME -n NAMESPACE -o jsonpath='{.spec.kmsProvider.ciphertrust.credentialsSecretRef.name}'

  3. 確認 Secret 存在於同一個命名空間，且包含非空白的 username 和 password 鍵：

    kubectl describe secret CREDENTIALS_SECRET_NAME -n NAMESPACE

更改下列內容：

  • <var>CLUSTER_NAME</var>：DBCluster資源的名稱。
  • <var>NAMESPACE</var>：部署 DBCluster 的 Kubernetes 命名空間。
  • <var>TDE_CONFIG_NAME</var>：TdeConfig自訂資源的名稱。
  • <var>CREDENTIALS_SECRET_NAME</var>：包含 CipherTrust Manager 憑證的 Kubernetes Secret 名稱。

KMS 網址錯誤

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

說明

您可能會看到類似下方的錯誤訊息：

錯誤 說明 原因
TDE: Failed to register Key Store with URL: KMS_URL, error code: 12, error message: Unsupported key store type 不支援的金鑰儲存庫類型 如果 KEK 網址通訊協定不是 vault 或 ciphertrust，就會發生這個錯誤。例如，使用 http:// 或 https://，而非 vault:// 或 ciphertrust://，或完全省略配置。
TDE: Failed to register Key Store with URL: KMS_URL, error code: 3, error message: Invalid Vault address format. Expected hostname or hostname:port
或
TDE: Failed to register Key Store with URL: KMS_URL, error code: 3, error message: Invalid CipherTrust address format. Expected hostname or hostname:port		 KMS 位址格式無效 如果網址的 KMS 位址部分格式有誤，就會發生這種情況。舉例來說，如果網址再次包含通訊協定配置，例如 vault://https://vault.example.com:8200/... 或 ciphertrust://https://ciphertrust.example.com:443/...。
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 金鑰路徑格式無效 KMS 網址的路徑部分格式錯誤時，就會發生這種情況。路徑開頭須為正斜線 /，結尾不得為正斜線。
TDE: Failed to register Key Store with URL: KMS_URL, error code: 13, error message: curl_easy_perform() failed: Could not resolve hostname 主機名稱解析失敗 KEK 網址中的 KMS 主機名稱無法解析時，就會發生這個錯誤。如果網址格式有誤或發生 DNS 設定問題，就可能發生這種情況。
  • 驗證 KEK 網址配置：確認網址開頭為 vault:// (適用於 HashiCorp Vault) 或 ciphertrust:// (適用於 Thales CipherTrust Manager)。請勿使用 https:// 做為前置字元。
    • 正確 (保管箱)：vault://vault.example.com:8200/v1/secret/data/key
    • 正確 (CipherTrust)：ciphertrust://ciphertrust.example.com:443/api/v1/vault/secrets/key
    • 不正確：https://vault.example.com:8200/v1/secret/data/key
  • 檢查位址格式：確認主機和通訊埠緊接在 vault:// 或 ciphertrust:// 前置字串之後，且指定正確。
  • 確認路徑格式：請確保路徑以 / 開頭，且結尾沒有正斜線 (例如，使用 HashiCorp Vault 的 /v1/secret/data/key 或 Thales CipherTrust Manager 的 /api/v1/vault/secrets/key，結尾沒有 /)。
  • 驗證主機解析度：確認網址中指定的 KMS 主機名稱正確無誤，且可從資料庫 Pod 內解析。

KEK 未採用 Base64 編碼

如果儲存在外部 KMS 的 KEK 未正確採用 base64 編碼，AlloyDB Omni 擷取時就無法解碼。這會導致裝置無法解除包裝本機資料加密金鑰 (DEK)，並造成開機失敗。

說明

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

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

KMS 中缺少 KEK 版本

當 AlloyDB Omni 嘗試使用特定歷史版本的 KEK 解除包裝本機 DEK 時，如果該版本已刪除、毀損或在外部 KMS 中遺失，就會發生 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 ...}
或
TDE: Failed to read KEK, error code: 5, error message: CipherTrust request failed with HTTP code: 404, CipherTrust error: "NCERRResourceNotFound: ..."		 金鑰版本遺失或已刪除 要求的 KEK 版本在 KMS 中遺失、刪除或永久刪除。
  • 在 KMS 中驗證 KEK 版本：確認要求的 KEK 版本存在於 KMS 中且有效 (未刪除或毀損)。
  • 還原遺失的 KEK 版本：如果要求的 KEK 版本已刪除但未銷毀，請在 KMS 中還原或取消刪除該版本。
  • 處理已刪除的金鑰：如果要求的金鑰版本已在 KMS 中永久刪除，則以該版本加密的資料或備份將永久無法復原。

TLS 或 SSL 憑證錯誤或遺失

如果憑證遺失、過期、不受信任或設定錯誤，AlloyDB Omni 就無法與外部 KMS (HashiCorp Vault 或 Thales CipherTrust Manager) 建立安全的 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		 KMS 伺服器憑證驗證失敗 無法使用提供的 CA 憑證驗證 KMS 伺服器的憑證。
TDE: Failed to register Key Store with URL: KMS_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. 確認 Secret 已正確掛接，且 postgres 使用者可讀取檔案：

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

更改下列內容：

  • CLUSTER_NAME：DBCluster 資源的名稱。
  • NAMESPACE：部署 DBCluster 的 Kubernetes 命名空間。
  • TDE_CONFIG_NAME：TdeConfig 自訂資源的名稱。
  • CERT_SECRET_NAME：包含 TLS 憑證的 Kubernetes Secret 名稱。
  • POD_NAME：資料庫 Pod 的名稱。