排查透明数据加密问题

选择文档版本：

本页面介绍了如何在 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 令牌 (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'
Or
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
Or
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://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 检索到的 Secret 进行解码时，但字符串不是有效的 Base64，就会发生此错误。
  • 检索 KEK 值：直接从 KMS（HashiCorp Vault 或 Thales CipherTrust Manager）检索并检查 KEK 值。
  • 更新 KMS 中的值：确保存储在 KMS 中的 KEK 采用 base64 编码。如果它以原始二进制文件或纯文本形式存储，请使用其 base64 编码的等效值更新 KMS 中的值。
    1. 将原始密钥转换为 Base64： 
      echo -n "RAW_KEY" | base64
       将 <var>RAW_KEY</var> 替换为未编码的密钥值。
    2. 将 KMS 中的 Secret 更新为生成的 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 ...}
Or
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
Or
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 形式提供证书，并将其装载到数据库 Pod 中的 /tde-tls。如需查找并检查证书 Secret，请执行以下操作：

  1. 直接从数据库集群中提取引用的 TdeConfig 名称：

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

  2. 直接从 TdeConfig 资源中提取 Secret 名称：

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

  3. 验证 Secret 是否存在并包含所需的密钥：

    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 的名称。